ARCHITECTURE: absorb the CLI into this repo as a published devDependency

[Schmandarine]

Decided 2026-07-29 (supersedes brmbh/cli#8). The CLI is not retired — its relationship to the theme inverts, and it moves into this repo.

The problem being solved

Everything the CLI does today is copied or frozen at scaffold time, so improvements never reach existing sites. Retiring the CLI into theme-side tools/*.sh does not fix this — copied scripts freeze exactly like copied skills do. The fix is to make the tooling a dependency the theme consumes, rather than files it contains.

Old: CLI (npm) → clones theme (git) → theme is standalone forever after. CLI is upstream and then irrelevant.
New: theme (git, copied/forked) → depends on @brmbh/cli (npm) → stays connected, updatable via npm update.

The rule

Theme = what you own and edit. Package = what you consume and update.

Test for any file: would a client project ever edit this? If no, it belongs in the package.

Stays in the theme	Moves into the package
my-acf-blocks/, template-parts/, inc/	tools/deploy.sh, db-*.sh, uploads-*.sh, sync-plugins.sh, version-check.sh
style.css, theme.json, functions.php, SCSS	tools/sync-tokens.mjs, tools/sass-with-theme-flags.sh
tools/env/*.env — per-project, gitignored	AGENTS/*.md — the 10 in-project skill docs
Client blocks and content	doctor, init/create, block + CPT generators
	wrapper generation for .claude/ .cursor/ .windsurf/

The deploy scripts already read only exported shell vars (see the 2026-07-13 env-loading fix), so they move cleanly while the env files they consume stay per-project.

Target layout — one repo, two artifacts

brmbh/wordpress/
├── skills.sh.json          ← npx skills add brmbh/wordpress keeps working
├── skills/wordpress/       ← pre-scaffold skill (the marketing entry point)
├── packages/cli/           ← published to npm as @brmbh/cli
│   ├── AGENTS/             ← the 10 in-project skills live HERE now
│   └── tools/              ← deploy, db, doctor, generators
└── (theme at root)         ← style.css, functions.php, my-acf-blocks/, inc/ …

git clone of this repo still yields a working theme. packages/ is stripped from scaffolds by the personalization step (#4).

Why this makes skills updatable

If AGENTS/*.md ships inside the npm package instead of being copied into each site, npm update @brmbh/cli updates the skills. The .claude/ .cursor/ .windsurf/ wrappers become generated artifacts pointing at node_modules/@brmbh/cli/AGENTS/<name>.md — gitignored, regenerated on install.

Three tracked problems dissolve: brmbh/cli#3 (no refresh path), #3 here (committed wrappers already drifted), and the whole "which copy is canonical" question in #2 / brmbh/cli#5 / brmbh/cli#6.

Projects that need a tweaked skill get a local AGENTS/ override that wins over the package copy — so one customized skill does not cost you updates to the other nine.

The flow end to end

1. npx skills add brmbh/wordpress — marketing entry, unchanged
2. User: "make a new brmbh theme"
3. Skill runs npx @brmbh/cli create my-site — no global install; npx fetches latest on demand
4. create copies the theme, renames it (65 strings — Theme should declare its own scaffold contract so the CLI can personalize it #4 / create: scaffolded theme keeps the starter's identity (name, text domain, package name) cli#1), writes "@brmbh/cli": "^1.0.0" into the new theme's devDependencies, runs npm install, generates wrappers, builds, activates
5. Forever after: npx brmbh <cmd> hits the pinned local copy; npm update @brmbh/cli pulls new tooling and new skills

The package is used twice — transiently via npx to scaffold, then permanently as a devDependency.

Free bug fix

npx @brmbh/cli currently fails with "could not determine executable to run" because the package declares two bins (brmbh, create-brmbh). Drop the create-brmbh bin — with a single bin npx runs it regardless of name, so npx @brmbh/cli create my-site works. This also retires the npx create-brmbh 404 by deletion instead of by publishing a second package, closing Alignment Plan item 1.

Decided sub-questions

• Wrapper generation: postinstall plus an explicit npx brmbh skills sync fallback (postinstall can be skipped with --ignore-scripts). The pre-scaffold skill calls the explicit command after scaffolding.
• Zero-npm-install clone: no longer fully functional — deploy and db sync will require npm install first. Accepted: npm install is already required for the CSS build. Must be stated in the README rather than discovered.

Migration order

• Create packages/cli/, move the CLI source in from brmbh/cli (preserve history if practical)
• Move AGENTS/*.md and the generic tools/* into the package; leave tools/env/ behind
• Point wrapper generation at node_modules/@brmbh/cli/AGENTS/; gitignore the wrapper dirs
• Implement the local-AGENTS/-override precedence rule
• Drop the create-brmbh bin; verify npx @brmbh/cli create live
• Add the scaffold personalization step (Theme should declare its own scaffold contract so the CLI can personalize it #4 / create: scaffolded theme keeps the starter's identity (name, text domain, package name) cli#1) — it must also strip packages/
• Publish @brmbh/cli@1.0.0 from the new location
• Archive brmbh/cli; publish a deprecation notice on the old npm entry pointing here
• Update both READMEs only once the structure exists — documenting it early just creates new stale data

Blocks / supersedes

Supersedes brmbh/cli#8. Dissolves brmbh/cli#3, brmbh/cli#5, brmbh/cli#6, #2, #3. Relocates brmbh/cli#1, brmbh/cli#2, brmbh/cli#7 into this repo. #4, #5, #6, #7 stay valid and unaffected.

Vault: Automatic-Brain/Projects/brmbh-agentic-wp-suite/dashboard.md

[Schmandarine]

Blocker found: archiving brmbh/cli would strand the marketing site, which lives at brmbh/cli/site/ (9 tracked files, live at https://brombach.de/wordpress-suite/) plus an unmerged redesign in worktree-cli-scrollytell.

Tracked at #9 — extract to a standalone brmbh/site repo first. Added as a prerequisite to the "Archive brmbh/cli" step in the migration checklist above.

Net result for the org: two repos, not one — brmbh/wordpress (product) and brmbh/site (marketing). That is consistent with this issue: the consolidation here targets the code/skills seam that has produced real bugs, and a static marketing site shares no such seam.

[Schmandarine]

Migration landed and verified end to end. Merged as de665e4 (PR #10), plus 1.0.1 for a bug the test caught.

Published

@brmbh/cli@1.0.1 — 10 AGENTS/ skills, 11 tools, single brmbh bin.

The bug only a real install could find

--skip-install scaffolds looked perfect. The first install against the registry failed:

sh: node_modules/@brmbh/cli/tools/sass-with-theme-flags.sh: No such file or directory

node_modules/@brmbh/cli was a dangling symlink to ../../packages/cli. Stripping packages/ and the workspaces key was not enough — the starter's package-lock.json also records @brmbh/cli as a workspace link, and npm honoured the lockfile over the manifest. The registry version was never fetched. npm ls reported invalid, the build failed, no skills wired.

Fix: create now drops package-lock.json too (npm regenerates it). Shipped in 1.0.1.

Verified in ~/Local Sites/brmbh-cli

Clean-room run — cloned from GitHub, installed from npm, nothing local involved:

✓ Stripped starter scaffolding (packages, skills, skills.sh.json, package-lock.json, package.json#workspaces)
✓ Dependencies installed      → @brmbh/cli@1.0.1, real directory
                                 resolved: registry.npmjs.org/@brmbh/cli/-/cli-1.0.1.tgz
✓ Assets built                → 160KB style.css
✓ Agent skills wired          → 10 skills → 30 wrappers
                                 pointing at node_modules/@brmbh/cli/AGENTS/
doctor: all ok except scf (needs the WP install)
postinstall regenerates wrappers on every install → `npm update` refreshes skills

The original goal is met: skills and tools are now updatable via npm update.

Noted while testing, not fixed here

doctor --cwd <wp-root> picks the first brmbh theme it finds under wp-content/themes, not the intended one — it reported on an unrelated theme until run from inside the target. Pre-existing findThemeDir behaviour, worth its own issue.

Remaining before brmbh/cli can be archived

• Landing page is stranded in brmbh/cli — extract to brmbh/site before archiving #9 — extract the landing page
• Theme should declare its own scaffold contract so the CLI can personalize it #4 / create: scaffolded theme keeps the starter's identity (name, text domain, package name) cli#1 — scaffold personalization (a new theme still calls itself brmbh)
• deprecate the old npm entry