Skip to main content

Workspace State

bgng keeps all owned local state in one workspace directory. The default is ~/.bgng; set BGNG_HOME to move it.

export BGNG_HOME=/Volumes/work/bgng
bgng init

Directory layout​

~/.bgng/
  config.json
  queue.md
  transcripts/<YYYY-MM-DD>/<slug>/
    transcript.md
    transcript.txt
    meta.json
  notes/
  .qmd/index.sqlite
  ide/
    profiles.json
    sessions.json
    secrets.json
    runtime.json

Main config​

config.json is BgngConfig version 2. It stores the SupaData key, transcript defaults, collection configuration, and optional S3 adapter settings.

{
  "version": 2,
  "apiKey": "...",
  "transcriptLang": "en",
  "transcriptMode": "auto",
  "collections": {
    "transcripts": {
      "path": "/Users/you/.bgng/transcripts",
      "pattern": "**/*.md",
      "includeByDefault": true
    },
    "notes": {
      "path": "/Users/you/.bgng/notes",
      "pattern": "**/*.md",
      "includeByDefault": true
    }
  }
}

Older v1 config is migrated on read into the v2 collection model.

Environment precedence​

Environment variables override file-backed config at command execution time. They are never written back to config.json.

Key examples:

  • BGNG_HOME changes the workspace root.
  • BGNG_SUPADATA_API_KEY and SUPADATA_API_KEY override the SupaData key.
  • BGDB_S3_ADAPTER_URL and BGDB_S3_ADAPTER_ADMIN_TOKEN override S3 adapter config.
  • BGNG_IDE_VSIX_PATH, BGNG_IDE_VSCODE_EXTENSIONS_DIR, and BGNG_IDE_VSCODE_APP override IDE install/open paths.

Queue state​

queue.md is intentionally Markdown so it can be hand-edited. Only ## Pending and ## Processed sections are preserved on rewrite.

bgng url batch-process rewrites the queue after each completed URL using an atomic temp-file plus rename pattern, which keeps batch processing crash-safe.

IDE state and secrets​

The IDE control plane writes four JSON files under ~/.bgng/ide/. secrets.json contains direct bearer tokens and gateway refresh secrets in plain JSON. It is not encrypted and is not stored in the OS keychain.