Theme should declare its own scaffold contract so the CLI can personalize it

[Schmandarine]

When brmbh/cli scaffolds a site from this theme, nothing renames it. The client's theme still calls itself "brmbh Agentic WP Suite" in WP Admin, and the text domain brmbh-agentic-wp-suite stays hardcoded throughout.

The CLI-side fix is tracked at brmbh/cli#1. This issue covers what this repo should provide so the CLI does not have to hardcode knowledge about the theme's internals.

The numbers

brmbh-agentic-wp-suite appears 65 times across 25 files here. They split three ways:

Theme code — must be rewritten on scaffold (20 files):
404.php, footer.php, functions.php, header.php, index.php, page.php, single.php, style.css, package.json, assets/src/scss/style.scss, inc/block-patterns.php, inc/bootstrap-nav-walker.php, inc/cli.php, inc/dependencies.php, inc/footer-menus.php, inc/gutenberg.php, inc/scaffold.php, inc/template-functions.php, my-acf-blocks/loader.php, my-acf-blocks/example-hero/block.json, template-parts/branding/site-logo.php

Skill docs — a judgement call:
AGENTS/create-block.md and skills/wordpress/SKILL.md reference the text domain as the value agents should use when generating new blocks. If they are not rewritten, every block an agent generates after scaffolding reintroduces the starter's text domain. They probably must be rewritten too. (skills/wordpress/SKILL.md is being deleted from this repo per #1, so it stops mattering here.)

Leave alone:
README.md (this repo's own docs — the scaffold should delete it, not rewrite it), tools/env/production.env.example and tools/env/staging.env.example (the string is a deploy path/dir hint — check what it means before touching), package-lock.json (regenerated by npm install anyway).

A blind repo-wide find/replace is therefore wrong.

Proposal: this repo declares its own scaffold contract

Add a brmbh.template.json at the theme root that the CLI reads after copying files:

{
  "textDomain": "brmbh-agentic-wp-suite",
  "rewrite": ["**/*.php", "style.css", "package.json", "assets/src/scss/style.scss", "AGENTS/*.md"],
  "leave":   ["tools/env/*.example", "package-lock.json"],
  "delete":  ["README.md", "CLAUDE.md", "brmbh.template.json"]
}

Why here and not in the CLI: the text domain, the file layout, and which files are the starter's own meta are all facts about this theme. If the CLI hardcodes them, then renaming the text domain, adding a directory, or adding a doc file silently breaks scaffolding for every already-published CLI version — and the CLI cannot be patched retroactively. Declaring it here means the theme can evolve without a CLI release.

Tasks

• Agree the manifest shape with create: scaffolded theme keeps the starter's identity (name, text domain, package name) cli#1 (it is a contract between the repos — either both use it or neither)
• Add brmbh.template.json
• Confirm what brmbh-agentic-wp-suite means inside tools/env/*.example before deciding rewrite vs leave
• Decide whether AGENTS/create-block.md should carry a placeholder token rather than a literal text domain

Acceptance

The CLI can personalize a scaffold using only this manifest, with no theme-specific strings hardcoded on its side.

Related: brmbh/cli#1, brmbh/cli#6

[Schmandarine]

Still valid and now more important — #8 makes the personalization step responsible for stripping packages/ out of scaffolds as well, so the manifest gains a delete list with real work to do.

Simplification from #8: the manifest and the code that reads it now live in the same repo, so this stops being a cross-repo contract that has to be versioned in lockstep. It is just an internal file the packaged create reads.

[Schmandarine]

Simplified by the rename (1588056). The text domain is now brmbh — 5 characters instead of 21, and it already matches what AGENTS/create-block.md tells agents to write into new blocks.

The scaffold contract still needs to declare it (the personalization step rewrites it per project), but the manifest gets simpler: one short token, and the skill docs no longer need special-casing since they already say brmbh.

Current occurrence count to rewrite on scaffold: grep -rc brmbh across theme code — recount when implementing, the 65-across-25-files figure in the body predates this rename.

[Schmandarine]

Done in @brmbh/cli@1.1.0. Closes this and brmbh/cli#1.

The manifest lives in the theme as brmbh.template.json, as proposed — the CLI reads it rather than hardcoding theme internals, so the theme can change its own identity without a CLI release. It also drives the strip list (replacing the hardcoded one) and deletes itself from the scaffold.

Rewritten — project identity:

• style.css Theme Name / Text Domain / Description; Theme URI dropped
• package.json name, description, private: true; repository + homepage dropped
• the i18n text domain across PHP, block.json, and the SCSS banner
• @package docblocks

Preserved — framework plumbing: the wp brmbh WP-CLI namespace, BRMBH_* constants, brmbh_* function prefix, and the @brmbh/cli dependency. Renaming those buys nothing: only one theme is active at a time, so there is nothing to collide with.

The trap worth recording. add_command( 'brmbh', … ) is textually identical to load_theme_textdomain( 'brmbh', … ). A blunt find/replace — which is what the original issue implied — would have silently renamed the WP-CLI namespace and broken wp brmbh scaffold in every scaffolded project. The patterns are deliberately narrow: the trailing argument of an i18n call, load_theme_textdomain's first argument, block.json's textdomain key, and @package tags.

Verified on a scaffold named acme-site:

✓ Personalized as "Acme Site" (text domain acme-site, 49 refs in 21 files)
  Theme Name: Acme Site · Text Domain: acme-site
  add_command( 'brmbh', 'BRMBH_CLI' )   intact
  @brmbh/cli: ^1.0.0                intact
  grep for stale text domains       none
  php -l on every file              clean
  npm install + npm run build       green, 160KB css
  30 wrappers generated

The count is 49, not the 65 in the original issue — the 2026-07-29 rename to brmbh shrank the identifier first.