The Five-Layer Model

bgng apply resolves configuration through five layers, from broadest to most specific:

1. Packaged harness defaults — config, built-in skills, and built-in MCP definitions shipped with the package
2. Local library — package-backed skills and user MCP definitions under ~/.agents/library
3. User defaults — machine-wide active state under ~/.agents/bgng/config.json
4. Project overlay — current-project overrides under <project>/.agents/bgng/config.json
5. Downstream state — Claude, Codex, Cursor, and generated MCP config files

Each layer narrows or overrides the one above it. The result is the effective harness for a given project and machine.

What It Changes On Disk

bgng can read and write local agent configuration under:

• ~/.agents
• ~/.claude
• ~/.codex
• ~/.cursor
• <project>/.agents/bgng/config.json

The normal apply path is conservative:

• bgng apply --dry-run previews changes
• Apply creates or replaces managed symlinks and generated MCP config
• Stale downstream skill symlinks are reported, not deleted
• bgng doctor reports issues without fixing them

Running Apply

Preview before writing:

bgng apply --dry-run

Apply everything:

bgng apply

Run only one side when needed:

bgng apply --mcp-only
bgng apply --skills-only

Limit apply to one target:

bgng apply --target=claude
bgng mcp apply --target=cursor

Usage Modes

Packaged harness

Use the published package when you want the default config and CLI behavior:

npm install -g beginning-harness
bgng apply --dry-run

Editable harness source

Use a checkout when you want to own the source of truth:

export AGENTS_REPO_ROOT=/path/to/beginning-harness
bgng status

In checkout mode, edit:

• config.json for target and optional-server toggles
• mcp-servers.json for MCP server definitions
• skills/ for built-in skill content