Support two install paths — make the theme-first (direct download) route first-class

[Schmandarine]

brmbh should support two ways in, and both should be first-class:

1. Skill-first — user installs the global brmbh skill, asks their agent for a theme, the skill runs brmbh create. (The skills-first install flow is undocumented — nothing tells users how to install the brmbh skill cli#7)
2. Theme-first — user downloads/clones this theme directly. An agent working inside it should then get the CLI without the user having to know it exists.

Path 2 is the one that needs design work.

What's already true: the theme does not need the Node CLI

Checked every in-theme skill. None of the AGENTS/*.md skills invoke the brmbh Node CLI. They call:

• tools/*.sh directly — deploy.sh, db-pull.sh, db-push.sh, sync-plugins.sh, uploads-*.sh, version-check.sh, sync-tokens.mjs
• wp brmbh … — a WP-CLI subcommand registered by this theme's inc/cli.php (see Two different programs are both called brmbh (wp brmbh vs the Node CLI) #7 — the name collision is its own problem)
• npm run build / npm run watch

So a direct clone already works end to end. The Node CLI adds convenience wrappers (brmbh dev, brmbh doctor, brmbh add block, brmbh deploy) over the same scripts, plus the --json envelopes that make those operations agent-legible. Valuable, but not load-bearing.

That reframes the requirement: it is not "the theme is broken without the CLI", it is "an agent gets a better, more deterministic interface when the CLI is there."

Recommendation: declare the CLI as a devDependency, don't have agents install it

The obvious implementation — "agent checks for brmbh, runs npm install -g @brmbh/cli if missing" — has real problems. An agent installing software globally on someone's machine without asking is invasive, needs a permission prompt it will often mishandle, and produces a floating version with no relationship to the theme it is operating on.

Better: add @brmbh/cli to this theme's devDependencies.

"devDependencies": {
  "@brmbh/cli": "^0.1.0",
  …
}

Consequences, all good:

• npm install is already step one of theme setup (and brmbh create runs it automatically). The CLI simply exists afterwards — npx brmbh doctor just works.
• Nothing is installed globally. Nothing is installed without the user's npm install.
• The CLI version is pinned per project. Two client sites can sit on different CLI versions without conflict, and a scaffold becomes reproducible — which directly feeds No way to pull improved agent skills into an already-scaffolded site cli#3.
• The "is it present?" check mostly disappears. If node_modules exists, so does the CLI.

No dependency cycle: the CLI fetches this theme over git, this theme depends on the CLI over npm. Different mechanisms, npm sees no loop.

Still needed: a preflight in the agent contract

AGENTS.md should open with a short precondition block so an agent entering a fresh clone knows what to do:

## Before anything else
1. `node_modules/` missing → run `npm install` (this also installs the brmbh CLI)
2. Then `npx brmbh doctor --json` and branch on `class`
3. `wp-cli` missing → say so; deploy/db/scf skills will not work

doctor already reports exactly these checks, so this is wiring, not new logic.

Tasks

• Add @brmbh/cli to devDependencies (after brmbh/cli is published — blocked on that)
• Add the preflight block to AGENTS.md
• Decide whether in-theme skills should prefer npx brmbh <cmd> over calling tools/*.sh directly, or keep calling the scripts and treat the CLI as optional sugar. Worth deciding explicitly — right now it is neither, by accident.
• README: document both entry paths, so the direct-download route is visibly supported rather than merely possible

Note

This resolves the open question in #3: a direct git clone is a supported path, so the generated .claude/ .cursor/ .windsurf/ wrappers must stay committed, and need a CI guard to stop them drifting from AGENTS/.

Related: #3, #7, brmbh/cli#3, brmbh/cli#7

[Schmandarine]

Confirmed and superseded in part by #8, which settles the mechanism:

• The theme-first path stays supported — git clone still yields a working theme.
• The CLI arrives as a devDependency, installed by the npm install that setup already requires. No global install, no agent installing software unprompted, version pinned per project.
• Accepted trade-off, now explicit: after ARCHITECTURE: absorb the CLI into this repo as a published devDependency #8 a bare clone with no npm install will not have deploy/db tooling, since those scripts move into the package. This must be stated in the README, not discovered.

The preflight block for AGENTS.md proposed here is still wanted and carries into #8.