Store And Migration | beginning-harness

Store Layout

Cards-era bgng stores local user-managed inventory under:

~/.agents/bgng/
|-- store.json
|-- machine.json
|-- cards/
|-- sources/
|-- skills/
|-- mcp-servers/
|-- generated/
|-- cache/
`-- global-write-record.json

Path	Purpose
`store.json`	Store metadata and schema version
`machine.json`	Machine-scope overlay used outside configured projects
`cards/`	Immutable published Harness Card versions
`sources/`	Editable card source directories
`skills/`	Package-backed skill bundles
`mcp-servers/`	User MCP server definitions, one JSON file per server
`generated/`	Machine-scope generated files such as Cursor MCP payloads
`global-write-record.json`	Machine-scope materialization ownership record

Inspect Store State

bgng store status
bgng store status --json

Store status reports whether the cards-era store exists, its schema version, inventory counts, and whether a pre-cards layout is still present.

Migration

Pre-cards versions used several paths:

Legacy path	Cards-era path
`~/.agents/bgng/config.json`	`~/.agents/bgng/machine.json`
`~/.agents/library/mcp-servers.json`	`~/.agents/bgng/mcp-servers/<id>.json`
`~/.agents/packages/skills/`	`~/.agents/bgng/skills/`

Run migration explicitly:

bgng store migrate

For structured output:

bgng store migrate --json

For unattended migration:

bgng store migrate --yes

Migration stages the new layout, validates it, archives the old layout, then activates ~/.agents/bgng. Ordinary commands do not silently migrate state; they warn when a pre-cards layout is detected.

Legacy Orphan Cleanup

After migration, old global downstream skill symlinks may still point into the legacy or archived store. Clean up bgng-owned legacy orphans explicitly:

bgng store migrate --cleanup-legacy-orphans
bgng store migrate --cleanup-legacy-orphans --yes

Cleanup removes only symlinks whose targets are recognized as bgng-owned legacy paths. User-owned replacements and unrelated paths are preserved.

Project Write Records

Configured projects use their own write record:

<project>/.agents/bgng/write-record.json

Machine-scope writes use:

~/.agents/bgng/global-write-record.json

Write records let bgng remove old bgng-owned materialized paths while preserving user-owned edits and replacements.