@bongos/core 1.19.465 → 1.19.466

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.465",
-  "core_contract": "1.19.465",
-  "source_commit": "82872e3e08c740d3499036c81775be82f4ab5538",
+  "core_version": "1.19.466",
+  "core_contract": "1.19.466",
+  "source_commit": "5b915c14235b08df52728e3d94dc196d548791a3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-02T01:57:06.137Z",
+  "built_at": "2026-09-02T02:25:23.295Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 406,
+    "docs_redacted": 407,
     "agent_docs_stubbed": 24,
     "functional_verbatim": 1822,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2252,
-  "tree_sha256": "ac3006fbcebed3829d82962a2c54bd4245e7f1b736f92b13c46ab9d56b58180b",
+  "file_count": 2253,
+  "tree_sha256": "4bb527a26dc80efbf88ff9d1a853737b1a657a8f300f8fbf01e76b4146834f58",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1624,10 +1624,15 @@
       "mode": "0000644",
       "sha256": "736f27c4a9e86d3169954a2555209e75dfc93f84b4581417188c71a02954e731"
     },
+    {
+      "path": "docs/adr/0224-module-skills-reach-the-core-checkout-as-untracked-self-ignored-copies.md",
+      "mode": "0000644",
+      "sha256": "717bdc174891ccf5bc8756b25f53eca016d4d6dfaeebec8d12bb2a6bfef56976"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "414345ac797782a5049cdae5b468149be343535055a261f257eec6979701c51b"
+      "sha256": "ec731cb900dc5b30287a370325042a4ead509759aba5688c32d91f293047c491"
     },
     {
       "path": "docs/api-reference.md",
@@ -2117,7 +2122,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "5bf0804834ecb65b42a29cf2936f93021fb15762735a75129ab52294b0731246"
+      "sha256": "5e800493043ac5941fa8ed5f9efc66359a0622f79968fd7158a61651556c1cf3"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6387,7 +6392,7 @@
     {
       "path": "modules/ui-design/skills/README.md",
       "mode": "0000644",
-      "sha256": "084b2a7757d7b6422683ac371f6448c563d2613c4c0061f077d27a335d1df2f0"
+      "sha256": "ddc9a2b8788d3e41f1d3ae285d56c75ecb6e7a9d4aa003a0db55f4d38ff24d4a"
     },
     {
       "path": "modules/ui-design/skills/brandkit/SKILL.md",
@@ -6617,12 +6622,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6db036356b674e4ea0fd8ef3a2d300b830ce95aa66ff9b19993188a41ca0bb66"
+      "sha256": "098654f260139d3b7b4d45ef87d7a15c3ca8a0ebb04ce36ba538e212c3dce351"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fcd520ba5ac29e9f0db6fad4629c7316aed291ed6428b030af7543d5c6144883"
+      "sha256": "9670afc099badbbc922edd16e4cb6a1a99d370267cc15b2232af678b6c65f7b0"
     },
     {
       "path": "public-docs/index.html",
@@ -6857,7 +6862,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "4cfe40c72c326ac80a467c56ad24fea60e1b2f1a8a1399c21208eb333b9980fa"
+      "sha256": "450c1a12c5e8c125db6794d74bb2c25251804d8613d83fa50a463e4007a46ddd"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -7107,7 +7112,7 @@
     {
       "path": "scripts/gds/gen-file-map.js",
       "mode": "0000644",
-      "sha256": "feee792d7111daae2100b253ef6f1ce94077772618f613ebdb991234b5b3ea46"
+      "sha256": "620188a2edcd4aec580193b3d97f0c4e19871db4d31af27cb0b7e0571457a73a"
     },
     {
       "path": "scripts/gds/gen-freshness.js",
@@ -8272,7 +8277,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "641bc335f6f62f9d3a6a1fbfe9f83147c3e652b0816ad008616c3f93f3d16f13"
+      "sha256": "400ed351948806a44d6558bbc10d35158237d80c3101415acebb6d075747c3ae"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -8787,7 +8792,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "37b2632142b2b2855a3c2b4b5dff6ab84536ee7b4a73fc24078851b6fc289f91"
+      "sha256": "6599b89948d3289d869f94fd87072f26a37d10a1e67727faf6c05b5052a035c8"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -9177,7 +9182,7 @@
     {
       "path": "tests/file_map.mjs",
       "mode": "0000644",
-      "sha256": "387eb4455a5e79f930fccae875278841094a52900a1158617345db8b58147d1a"
+      "sha256": "b44f040f21d1dbb978add1a96e392a0f3c1b5a46302c10616b2304505ca66097"
     },
     {
       "path": "tests/filing_abuse_matrix.mjs",

package/docs/adr/0224-module-skills-reach-the-core-checkout-as-untracked-self-ignored-copies.md

@@ -0,0 +1,30 @@
+# ADR 0224 — Module-owned skills reach the core checkout as untracked, self-ignored copies with a manifest: the self-copy guard stays, the dev path is a flag, and the file map skips what the module documents
+
+- **Status:** Accepted (2026-09-02)
+- **Task:** [task 1003330](https://cloudbongos.com/builders#/task/1003330) (goal 1000083 — the ui-design module as a platform capability; from idea 1000864, filed by task 1003321)
+- **Context:** [ADR 0198](<redacted>.md) landed module-owned skills for INSTANCES (`claude-materialize.js` step 1b, on `bongos init` / `upgrade`); [ADR 0220](<redacted>.md) and its successors noted each time that "the core checkout itself still does not see module-owned skills".
+
+## Context
+
+`materializeClaude`'s self-copy guard is a deliberate no-op when the instance dir is the core root: a core copying itself onto itself would be a no-op at best and corrupting at worst. Claude Code discovers only `.claude/skills/` at the project root. So a builder working in the core checkout, where all nine `ui-design` skills were written, cannot invoke a single one of them; the only copies on this machine were the upstream ones under the builder's home directory, by the same names, which is the collision ADR 0220 called "by design". Two constraints shaped the fix: nothing under `.claude/skills/` may be committed twice (the module's `skills/<name>/` is the source and the file-map generator lists every dir there and demands a note for each), and `bongos init` from a checkout that carries the copies must still land them through the module path.
+
+## Decision
+
+1. **The dev path is a flag on the library, not a change to the guard.** `node scripts/gds/claude-materialize.js --module-skills-only [--dry-run] [--clean]` calls `materializeModuleSkillsIntoCore`, which walks the same roster and passes the same `vendoredSkillGate` and `SKILL_NAME_RE` as step 1b, copies every ENABLED module's skill tree **verbatim** into `.claude/skills/<name>/` (no `bongosify`: the checkout runs `node scripts/gds/…`), leaves a name the core's own tracked skills carry to the core, and excludes a disabled module's. The self-copy guard in `materializeClaude` is untouched; init and upgrade are unchanged.
+2. **Untracked, self-ignored, manifest-named.** The run writes `.claude/skills/.module-skills.json` (each materialised name with its module, source dir, vendored flag and file count, sorted) and `.claude/skills/.gitignore` (ignoring itself, the manifest and every materialised dir), so `git status` shows nothing new and nothing can be committed by accident. Every run first removes what the last manifest named, then lands the current set, so a skill a module stopped declaring does not linger and a second run is byte-identical; `--clean` stops after the removal.
+3. **The file map skips what the module documents.** `gen-file-map.js` reads the manifest beside `.claude/skills/` and excludes those names from its listing and from its notes contract (a module skill is documented by its module's README, not by `docs/file-map.notes.json`), and `tests/file_map.mjs` filters its own exhaustiveness walk the same way through the exported `materializedNames`. `--check` stays green with the copies present and without them.
+4. **Init from a checkout that carries the copies still lands them through the module path.** `materializeClaude` reads the same manifest: step 1 skips the materialised names and the two dotfiles, and step 1b's "also exists under the core" note ignores a materialised copy, so an instance receives the module skills transformed (`bongos …`) as before and never the checkout's dotfiles.
+5. **The pins** (`tests/claude_materialize.mjs`): an enabled module's skills land verbatim with the manifest and the `.gitignore` lines, a disabled module's are excluded, a core-owned name is kept; a second run is byte-identical, a dropped declaration is removed, `--clean` removes exactly what was made and nothing of the core's; an instance materialised from such a core gets the skill through step 1b, transformed, and never the dotfiles; the bare CLI refuses with usage; `gen-file-map`'s `materializedNames` reads the manifest.
+
+## Consequences
+
+- **A builder in the core checkout sees all nine `ui-design` skills** after one command; the roster ADRs' standing consequence is closed. The command is not run automatically: a checkout is a workbench, and a builder who wants the module's skills in front of them runs it (or `--clean` to take them away).
+- **The upstream copies under the home directory are now shadowed by the project-level ones**, which is the collision ADR 0220 described, now resolved in the module's favour on this machine too.
+- **`docs/file-map.md` does not list materialised skills.** It never should have: they are the module's, and the module's README is their roster.
+
+## Rejected
+
+- **Dropping the self-copy guard** so `materializeClaude` writes into the core: it would `bongosify` the checkout's own core skills onto themselves and copy hooks and settings onto their sources.
+- **Committing the module skills under `.claude/skills/` as well:** two sources of truth for every skill, and the file-map notes contract doubled.
+- **A symlink or junction per skill:** Windows junctions into a tracked tree are the trap `worktree.js` exists to avoid, and a symlink is a tracked file the moment it lands in the index.
+- **Adding every materialised name to `docs/file-map.notes.json`:** a note for a dir that is not in the repository is a ghost by the file map's own definition.

package/docs/adr/README.md

@@ -310,5 +310,6 @@ This keeps the decision history honest and traceable.
 | 0221 | [**The impeccable method is one skill with sub-command playbooks: one preamble, one playbook per request, the three homes are the instance's own files, and the origin's mechanisms are dropped rather than disabled** ([task 1003326](https://cloudbongos.com/builders#/task/1003326) · goal 1000083). `pbakaus/impeccable` scanned `dangerous` (ADR 0198: hooks written into five harness configs, a child agent with permissions bypassed, an instruction override, a live-server credential in page source, an unverified remote bundle, default-on telemetry), so its method is rebuilt from the spec. ADR 0220 fixed where a rebuild lives; it had not said how a family of sub-commands lands, what the origin's three persisted homes become, or what to do with the six spec areas whose substance is the condemned mechanism. Decisions: **D1** one skill at `skills/impeccable/`: `SKILL.md` (invocation, the menu from live signals, session setup, the three homes, the routing table, the craft floor, the bounded finish, what is not here) plus `reference/<sub-command>.md`, eighteen playbooks, exactly one loaded per request (the spec's own entry rule); the preamble pinned once in `SKILL.md` and governing every playbook; the materialiser's tree copy ships `reference/` unchanged. **D2** the three homes are the instance's files (product truth = `docs/project-context.template.md` + the pack's identity; the visual system = the root `DESIGN.md` and a look's; the brief = the task's body + a fixed brief block in the ship notes); the skill creates none, `shape` proposes diffs, `document` drafts on the claim's branch with the refresh / overwrite / merge choice. **D3** dropped, not disabled, each with a destination: hooks → none (the ship gate is the sweep, the pre-flight is the kit); the bypass agent → an ordinary read-only subagent via the Agent tool; telemetry, the remote bundle, the credential → none; the live loop → the playwright plugin driving the kit's stub, variants as states, accept = commit, discard = checkout, nothing injected; the detector → task 1003329; the asset producer → the hero-plates rule and task 1003328; native → declines to `/design`; `init`/`doctor`/`pin`/installer → the materialiser is the install. **D4** the finish is the kit in bounded rounds (build, one batched inspection, one batch of fixes, at most one confirming round, stop, one budget) and the reviewer answers with one of `clean` / `recapture` / `defects` / `contradicted` after an evidence check and its own mock inventory. **D5** the craft floor is mechanics loaded late and never recited, translated for a world that may be hairlines by rule. **D6** the pins: sixteen routed playbooks, no orphan, no preamble copy in a playbook, and nothing in the tree directing a bypass, a hook write, a settings edit, telemetry, a remote download, a credential or an override. Rejected: eighteen skills; one inline file; a hooks-lite opt-in; an elevated reviewer; a `doctor`; the native playbooks.](<redacted>.md) | ui-design / skills |
 | 0222 | [**The image family under the hero-only rule: plates and hero objects, never screens; the mark is drawn; the board is a contact sheet; the pair and the sidecar are the output contract** ([task 1003328](https://cloudbongos.com/builders#/task/1003328) · goal 1000083). The four image skills of `Leonxlnx/taste-skill` (scanned `dangerous`, ADR 0198) are built around pictures of interfaces: one reference image per section, one app screen per flow step in a phone mockup, an identity board with the brand name rendered in, and a build loop whose truth is the generated image; the panel flagged the eagerness mandate, the image-count rule and the must-invoke-any-tool directive by name, and the owner's rule (2026-08-26/27) forbids the category. Decisions: **D1** the subject is the composition's plate slots and the count is the slot count; variety survives as anchors (field, beside-bleeding, masthead, orb, backdrop; text-left image-right refused), the palette lock is the pack, cross-frame consistency is one family (material, light, lens, ground). **D2** a screen is the surface itself: the mobile skill makes portrait plates for 390 / 320, the flow is the states file rendered by the kit, the bible is `DESIGN.md`, no phone mockup, native declines to `/design`. **D3** the source of truth for UI is the owner's references and the world; `image-to-code` reads them (analysis, extraction spec, faithful translation, drift as the failure mode, the clarity checklist) and the only image it may cause is the hero plate. **D4** the mark is drawn as inline SVG, the colour system is the pack, the type specimen is the faces on a real page, the applications are the kit's renders, the image direction is a hero-object family, the nine-panel board is a contact sheet of real parts. **D5** the output contract is DESIGN.md's pair and sidecar (JPEG dark plate, WebP alpha cutout, `<file>.<ext>.json` beside each, `--plate-*` tokens on `body`) through the instance's art pipeline key, the spend logged, a white ground through the remover, alpha verified with ffmpeg, never a crop. **D6** the worked example is the grove specimen's hero object, not the front door. **D7** the pins: the four declared, each naming the sidecar, "text-free" and the art key; no eagerness / count / per-section / must-invoke directive. Rejected: per-section images for reference only; phone mockups around real shots; a generated logo as a start; the plate on the front door; a shared base skill with wrappers.](<redacted>.md) | ui-design / skills / imagery |
 | 0223 | [**The anti-pattern detector is two tiers inside the kit: mechanical floors fail, craft tells warn, a false positive is waived in the file with its reason, and nothing new is installed** ([task 1003329](https://cloudbongos.com/builders#/task/1003329) · goal 1000083). The [detector] group of impeccable's rebuild spec (about sixty rules, a CLI plus a browser bundle wired to hooks, per-project ignores, in-file waivers, "a clean scan is a floor and never proof") lands as RULES in the kit that already exists, per the task body: no second tool, no bundle, no hook. Decisions: **D1** `kit/tells.js` carries the static rules and `check-mock.js` runs them after the platform rules and taste bans; `lib.js`'s `factsInPage` collects the computed-value twins as `tells` and `render.js` prints them as `~ tell:` lines per render, recorded in `report.json`, never counted as problems. Two tiers: floors FAIL (a bounce easing; a card nested in a card) and tells WARN (the icon-heading-text grid, hero metrics, section numbering, a kicker above the h1, a side stripe, a hard offset shadow, a coloured halo, decorative blur, a default typeface, a wide measure, a long headline, the same entrance everywhere, a geometric mask on a plate, glyphs as icons, a rainbow gradient, the browser surfaces nobody themed, proportional numerals, tiny type; rendered: measure, tiny text, numerals in cells, headline lines, an overshooting curve). **D2** the world decides which tells are floors: a kicker above the h1 is a FAIL where the instance's `DESIGN.md` bans the eyebrow (a new `eyebrow` taste key), a WARN elsewhere. **D3** a false positive is waived in the file with its reason (`kit-ignore: <rule prefix> (reason)` → a WAIVE row), `--raw` runs with none, `--no-tells` runs the platform rules only, `--json` prints rows with `fails` / `warns` counts; no per-project ignore config. **D4** not ported: the purple-to-blue tell (a literal colour already fails; hue is unresolvable under the fifteen), an injected overlay, the screenshot sampler (`contrast.js --url` is that pass), a cascade resolver (the browser is the resolver), native code, every hook. **D5** the pins: a clean fixture passes every rule, every rule class trips at its tier with the case count equal to the rule count, the promotion, the waiver / raw / json paths through the real CLI, `craftTells` as warnings; the hub mock and the three specimens still pass, `/projects` and the grove specimen still render ALL CLEAN. Rejected: a second CLI; every tell as a floor (the kit as the taste and the instance as the exception); a project-wide ignore config; an edit-time hook.](0223-the-detector-is-two-tiers-in-the-kit.md) | ui-design / kit |
+| 0224 | [**Module-owned skills reach the core checkout as untracked, self-ignored copies with a manifest: the self-copy guard stays, the dev path is a flag, and the file map skips what the module documents** ([task 1003330](https://cloudbongos.com/builders#/task/1003330) · goal 1000083). `materializeClaude`'s self-copy guard is right (a core copying itself is a no-op at best), but Claude Code discovers only `.claude/skills/` at the project root, so a builder IN the core checkout could not invoke any of the nine ui-design skills written there. Decisions: **D1** `node scripts/gds/claude-materialize.js --module-skills-only [--dry-run] [--clean]` calls `materializeModuleSkillsIntoCore`: the same roster, gate and slug rule as step 1b, verbatim copies (no bongosify: the checkout runs `node scripts/gds/…`), a core-owned name kept, a disabled module's excluded; the guard untouched. **D2** untracked and self-ignored: a generated `.claude/skills/.module-skills.json` manifest and a `.gitignore` that ignores itself, the manifest and every materialised dir; each run removes what the last manifest named then lands the current set (byte-identical on repeat; a dropped declaration disappears); `--clean` stops after the removal. **D3** `gen-file-map.js` and `tests/file_map.mjs` skip materialised names by the manifest (a module skill is documented by its module's README, not by the notes sidecar). **D4** init from a checkout that carries the copies still lands them through step 1b, transformed, and never the dotfiles. **D5** pinned end to end in `tests/claude_materialize.mjs`. Rejected: dropping the guard; committing the copies; symlinks or junctions; notes for dirs not in the repository.](<redacted>.md) | materialiser / skills |
 
 > ⚠️ **Numbering collisions are now machine-enforced, not narrated.** Twenty numbers are shared by two ADRs each — assigned in parallel sessions before anything checked. The files keep their filenames (renumbering would break every existing citation, and a number once assigned is never reused), and this table disambiguates each pair as `NNNN-a` / `NNNN-b`. The authoritative list is `LEGACY_DUPLICATE_ADRS` in [`scripts/gds/adr-namespace.js`](../../scripts/gds/adr-namespace.js), frozen by exact filename: a **new** collision — or a third file joining a legacy number, or a rename of either half — hard-fails the `unit` CI gate, as does an index row that points at no file or an ADR with no row. The list may only shrink. This paragraph used to narrate the collisions one by one and had fallen eight behind reality; see [ADR 0195](<redacted>.md) for why the check exists and why the pairs are grandfathered rather than renumbered.

package/docs/module-api-changelog.md

@@ -1367,5 +1367,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.463 with no explicit bump. run 33578746178. (task 1002620)
   1.19.465 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.464 with no explicit bump. run 33581328823. (task 1002620)
+  1.19.466 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.465 with no explicit bump. run 33583122775. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/ui-design/skills/README.md

@@ -43,6 +43,8 @@ A rebuild spec becomes a **first-party skill** at `<name>/` — no `vendor/` seg
 
 What every rebuild does with the upstream's opinions, in the same words: the palette is the pack and a variant is a look from [`../styles/`](../styles/README.md); the design system is the instance's `DESIGN.md`; images are hero plates and hero objects by token and never a step; every motion rule lives inside the Kill Switch (springs, magnetic hover, pointer-tracked borders are named *not available*); the upstream's bans are defaults an instance's `DESIGN.md` overrides; the kit's renders are the pre-flight. The image family (task 1003328, [ADR 0222](../../../docs/adr/<redacted>.md)) carries the one rewrite the upstream never had: images are for text-free hero plates and hero objects only, so a screen is the surface itself, the mark is drawn, the board is a contact sheet, and what ships is the pair (a black-ground JPEG for dark, an alpha WebP cutout for light) with a provenance sidecar beside every file, through the instance's art pipeline key. Still specs, not skills: the detector (task 1003329), the four looks (1003327).
 
+**In the core checkout itself**, where these skills are written, Claude Code reads only `.claude/skills/` at the repo root and the materialiser's self-copy guard leaves it empty of module skills. `node scripts/gds/claude-materialize.js --module-skills-only` lands every enabled module's skills there as untracked, self-ignored copies (a generated `.claude/skills/.module-skills.json` manifest and a `.gitignore` beside them; `--clean` removes them; the file map skips them by the manifest) so a builder can invoke them here too ([task 1003330](https://cloudbongos.com/builders#/task/1003330), [ADR 0224](../../../docs/adr/<redacted>.md)). Edit the module's `skills/<name>/`, never the copy, and re-run to refresh.
+
 **The playwright plugin** (`claude-plugins-official`, an MCP plugin) is the LIVE browser-driving loop, where the kit is the headless one. It is a prerequisite, documented — `claude plugin install playwright@claude-plugins-official` — never vendored.
 
 ## How to land one (when a scan says it may)

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.465",
+  "version": "1.19.466",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.465",
+      "version": "1.19.466",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.465",
+  "version": "1.19.466",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/claude-materialize.js

@@ -25,6 +25,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
 const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
 const { renderInstanceClaudeMd } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
@@ -340,7 +341,11 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   const roster = moduleSkillRoster({ coreRoot, instanceDir });
   const skipSkills = new Set();
   for (const m of roster) if (!m.enabled) for (const s of m.skills) skipSkills.add(s);
-  const skillSkip = (rel) => skipSkills.has(String(rel).split(/[\\/]/)[0]);
+  // A core checkout that materialised module skills into its own .claude/skills/ (task 1003330)
+  // carries them as untracked copies plus two dotfiles; step 1 must not ship those as core
+  // skills — step 1b lands them from the module, transformed, like everywhere else.
+  const materialisedInCore = readModuleSkillsManifest(path.join(coreRoot, '.claude', 'skills')).skills;
+  const skillSkip = (rel) => { const top = String(rel).split(/[\\/]/)[0]; return skipSkills.has(top) || top === MODULE_SKILLS_MANIFEST || top === '.gitignore' || Object.prototype.hasOwnProperty.call(materialisedInCore, top); };
 
   // 1. skills — ship in the core package; copy, rewrite invocations→bongos, rebrand
   //    identity, and exclude any skill owned by a disabled module.
@@ -369,7 +374,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   }
   for (const s of sources) {
     if (!s.enabled) { if (!summary.excludedSkills.includes(s.name)) summary.excludedSkills.push(s.name); continue; }
-    if (fs.existsSync(path.join(skillsSrc, s.name))) {
+    if (fs.existsSync(path.join(skillsSrc, s.name)) && !Object.prototype.hasOwnProperty.call(materialisedInCore, s.name)) {
       summary.notes.push(`module skill "${s.name}" (${s.module}) also exists under the core's .claude/skills/ — the core copy was materialized, the module copy ignored.`);
       continue;
     }
@@ -452,4 +457,82 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   return summary;
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+// ---- the dev checkout: module-owned skills materialised INTO the core (task 1003330, ADR 0224) ----
+// materializeClaude's self-copy guard is right for init/upgrade (instance == core is a no-op),
+// but Claude Code discovers only .claude/skills/ at the project root, so a builder working IN
+// the core checkout never sees modules/<key>/skills/. This lands every ENABLED module's skills
+// there as UNTRACKED, self-ignored dirs: verbatim copies (no bongosify — the checkout runs
+// `node scripts/gds/…`), a generated .claude/skills/.module-skills.json manifest naming what
+// was materialised and from where, and a generated .claude/skills/.gitignore covering the
+// manifest, itself and every materialised dir, so `git status` shows nothing new and nothing
+// can be committed by accident. The same vendoredSkillGate + SKILL_NAME_RE apply; a name the
+// core's own tracked .claude/skills/ carries is left to the core. Idempotent: every run first
+// removes what the last manifest named (so a skill a module stopped declaring does not
+// linger), then lands the current set; `clean` stops after the removal.
+const MODULE_SKILLS_MANIFEST = '.module-skills.json';
+function readModuleSkillsManifest(skillsDir) {
+  const m = readJsonSafe(path.join(skillsDir, MODULE_SKILLS_MANIFEST));
+  return m && m.skills && typeof m.skills === 'object' ? m : { skills: {} };
+}
+function materializeModuleSkillsIntoCore({ coreRoot, dryRun = false, clean = false, log = () => {} }) {
+  const skillsDir = path.join(coreRoot, '.claude', 'skills');
+  const summary = { materialized: [], removed: [], refused: [], excluded: [], keptCore: [], files: 0, notes: [] };
+  const previous = readModuleSkillsManifest(skillsDir);
+  // A dir git tracks is the core's, whatever an older manifest said (a core skill can take
+  // over a name a module once owned); it is never removed or overwritten here.
+  const tracked = (name) => { try { return spawnSync('git', ['-C', coreRoot, 'ls-files', '--error-unmatch', '--', `.claude/skills/${name}`], { encoding: 'utf8' }).status === 0; } catch { return false; } };
+  for (const name of Object.keys(previous.skills)) {
+    const dir = path.join(skillsDir, name);
+    if (!SKILL_NAME_RE.test(name) || !fs.existsSync(dir)) continue;
+    if (tracked(name)) { summary.keptCore.push(name); summary.notes.push(`"${name}" is tracked by git now — the last manifest's copy was not removed; the core's dir is kept.`); continue; }
+    if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
+    summary.removed.push(name);
+  }
+  if (clean) {
+    for (const f of [MODULE_SKILLS_MANIFEST, '.gitignore']) { const p = path.join(skillsDir, f); if (fs.existsSync(p) && !dryRun) fs.rmSync(p); }
+    log(`  ${dryRun ? '[dry-run] would remove' : '✓ removed'} ${summary.removed.length} materialised module skill dir(s), the manifest and .claude/skills/.gitignore`);
+    return summary;
+  }
+  const roster = moduleSkillRoster({ coreRoot, instanceDir: coreRoot });
+  const sources = moduleSkillSources({ roster });
+  for (const r of sources.refused) { summary.refused.push(`${r.name} (${r.module}): ${r.reason}`); log(`  ✗ refused module skill "${r.name}" (${r.module}): ${r.reason}`); }
+  const manifest = { _doc: 'GENERATED by `node scripts/gds/claude-materialize.js --module-skills-only` (task 1003330, ADR 0224): the module-owned skills materialised into this core checkout as UNTRACKED copies so Claude Code sees them here. Every dir named below is ignored by the sibling .gitignore and removed by --clean; edit the module\'s skills/<name>/ source, never these copies, and re-run to refresh.', skills: {} };
+  for (const s of sources) {
+    if (!s.enabled) { summary.excluded.push(s.name); continue; }
+    const dest = path.join(skillsDir, s.name);
+    if (fs.existsSync(dest) && (!Object.prototype.hasOwnProperty.call(previous.skills, s.name) || tracked(s.name))) {
+      summary.keptCore.push(s.name);
+      summary.notes.push(`"${s.name}" (${s.module}) already exists under .claude/skills/ and is not a materialised copy — the core's own dir is kept.`);
+      continue;
+    }
+    const r = copyTreeTransformed(s.dir, dest, { dryRun, overwrite: true, transform: (t) => t });
+    summary.files += r.files;
+    summary.materialized.push(s.name);
+    manifest.skills[s.name] = { module: s.module, source: path.relative(coreRoot, s.dir).split(path.sep).join('/'), vendored: s.vendored, files: r.files };
+  }
+  const names = Object.keys(manifest.skills).sort();
+  manifest.skills = Object.fromEntries(names.map((n) => [n, manifest.skills[n]]));
+  const ignore = ['# GENERATED by scripts/gds/claude-materialize.js --module-skills-only (task 1003330): the module-owned skills', '# materialised into this checkout are untracked copies; this file and the manifest ignore themselves. Never commit these.', '/.gitignore', `/${MODULE_SKILLS_MANIFEST}`, ...names.map((n) => `/${n}/`)].join('\n') + '\n';
+  if (!dryRun) {
+    fs.mkdirSync(skillsDir, { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, MODULE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
+    fs.writeFileSync(path.join(skillsDir, '.gitignore'), ignore);
+  }
+  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.materialized.length} module-owned skill(s) (${summary.files} file(s)) → .claude/skills/ as untracked copies: ${names.join(', ') || 'none'}`);
+  return summary;
+}
+
+// The CLI entry is the dev-checkout path only; init/upgrade call materializeClaude directly.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  if (!argv.includes('--module-skills-only') || argv.includes('--help')) {
+    process.stderr.write('usage: node scripts/gds/claude-materialize.js --module-skills-only [--dry-run] [--clean]\n  Lands every enabled module\'s skills (modules/<key>/skills/<name>/) into THIS checkout\'s .claude/skills/ as untracked,\n  self-ignored copies so Claude Code sees them here (task 1003330). --clean removes them. The library behind bongos init / upgrade otherwise.\n');
+    process.exit(argv.includes('--help') ? 0 : 2);
+  }
+  const s = materializeModuleSkillsIntoCore({ coreRoot: path.resolve(__dirname, '..', '..'), dryRun: argv.includes('--dry-run'), clean: argv.includes('--clean'), log: (l) => process.stdout.write(l + '\n') });
+  for (const n of s.notes) process.stdout.write(`  • ${n}\n`);
+  process.stdout.write(`module skills → .claude/skills/: ${s.materialized.length} materialised (${s.files} file(s)), ${s.removed.length} refreshed or removed, ${s.excluded.length} excluded (module off), ${s.keptCore.length} kept as the core's own, ${s.refused.length} refused\n`);
+  process.exit(s.refused.length ? 1 : 0);
+}
+
+module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/gen-file-map.js

@@ -63,12 +63,21 @@ function loadNotes() {
   try { return JSON.parse(fs.readFileSync(NOTES_PATH, 'utf8')); } catch { return {}; }
 }
 
-// Immediate subdirectories of an absolute dir, sorted by name (deterministic).
+// Module-owned skills materialised INTO this checkout (scripts/gds/claude-materialize.js
+// --module-skills-only, task 1003330) are untracked copies the module documents itself; they
+// are not repo skills needing a note here. One reader of the manifest exists — the
+// materialiser's — so this asks it rather than parsing the file a second way.
+const { readModuleSkillsManifest } = require('./claude-materialize.js');
+function materializedNames(absDir) { return new Set(Object.keys(readModuleSkillsManifest(absDir).skills)); }
+
+// Immediate subdirectories of an absolute dir, sorted by name (deterministic); materialised
+// module copies excluded.
 function listSubdirs(absDir) {
   let ents = [];
   try { ents = fs.readdirSync(absDir, { withFileTypes: true }); } catch { return []; }
+  const materialised = materializedNames(absDir);
   return ents
-    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !isConflictCopy(e.name))
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !isConflictCopy(e.name) && !materialised.has(e.name))
     .map((e) => e.name)
     .sort((a, b) => a.localeCompare(b));
 }
@@ -186,6 +195,7 @@ function main() {
 if (require.main === module) main();
 
 module.exports = {
+  materializedNames,
   SECTIONS,
   begin,
   end,

package/src/module-api.js

@@ -33,7 +33,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.465'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.466'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/claude_materialize.mjs

@@ -403,5 +403,86 @@ t('materializeClaude: NEVER clobbers an existing CLAUDE.md (init / adopt / upgra
   rmSync(dir, { recursive: true, force: true });
 });
 
+// ---- the dev checkout: module skills materialised INTO the core (task 1003330, ADR 0224) ----
+function fakeCore() {
+  const core = mkdtempSync(join(tmpdir(), 'cm-core-'));
+  const mod = (key, dflt, skills) => { mkdirSync(join(core, 'modules', key, 'skills'), { recursive: true }); writeFileSync(join(core, 'modules', key, 'module.json'), JSON.stringify({ key, default: dflt, contributes: { skills } })); };
+  const skill = (key, name, body = 'run `node scripts/gds/ship.js 1`') => { mkdirSync(join(core, 'modules', key, 'skills', name, 'reference'), { recursive: true }); writeFileSync(join(core, 'modules', key, 'skills', name, 'SKILL.md'), `---\nname: ${name}\n---\n${body}\n`); writeFileSync(join(core, 'modules', key, 'skills', name, 'reference', 'x.md'), 'a playbook\n'); };
+  mod('m1', true, ['alpha', 'shared']); skill('m1', 'alpha'); skill('m1', 'shared');
+  mod('m2', false, ['beta']); skill('m2', 'beta');
+  mkdirSync(join(core, '.claude', 'skills', 'shared'), { recursive: true }); writeFileSync(join(core, '.claude', 'skills', 'shared', 'SKILL.md'), 'the core\'s own shared\n');
+  mkdirSync(join(core, '.claude', 'skills', 'core-one'), { recursive: true }); writeFileSync(join(core, '.claude', 'skills', 'core-one', 'SKILL.md'), 'core one\n');
+  return core;
+}
+
+t('--module-skills-only: an enabled module\'s skills land in the core\'s own .claude/skills/ verbatim, with a manifest and a self-ignoring .gitignore; a disabled module\'s are excluded; a core-owned name is kept', () => {
+  const core = fakeCore();
+  const res = m.materializeModuleSkillsIntoCore({ coreRoot: core });
+  assert.deepEqual(res.materialized, ['alpha']); assert.deepEqual(res.excluded, ['beta']); assert.deepEqual(res.keptCore, ['shared']);
+  assert.equal(readFileSync(join(core, '.claude', 'skills', 'alpha', 'SKILL.md'), 'utf8'), '---\nname: alpha\n---\nrun `node scripts/gds/ship.js 1`\n', 'verbatim: no bongosify in the checkout');
+  assert.ok(existsSync(join(core, '.claude', 'skills', 'alpha', 'reference', 'x.md')), 'the tree is copied');
+  assert.equal(readFileSync(join(core, '.claude', 'skills', 'shared', 'SKILL.md'), 'utf8'), 'the core\'s own shared\n', 'the core copy is untouched');
+  const manifest = JSON.parse(readFileSync(join(core, '.claude', 'skills', m.MODULE_SKILLS_MANIFEST), 'utf8'));
+  assert.deepEqual(Object.keys(manifest.skills), ['alpha']); assert.equal(manifest.skills.alpha.module, 'm1'); assert.equal(manifest.skills.alpha.source, 'modules/m1/skills/alpha');
+  const ignore = readFileSync(join(core, '.claude', 'skills', '.gitignore'), 'utf8');
+  for (const line of ['/.gitignore', '/.module-skills.json', '/alpha/']) assert.ok(ignore.split('\n').includes(line), `.gitignore carries ${line}`);
+  assert.ok(!ignore.includes('/shared/') && !ignore.includes('/core-one/'), 'only materialised dirs are ignored');
+  rmSync(core, { recursive: true, force: true });
+});
+
+t('--module-skills-only: a second run is idempotent (byte-identical manifest + .gitignore), a skill the module stopped declaring is removed, and --clean removes everything it made', () => {
+  const core = fakeCore();
+  m.materializeModuleSkillsIntoCore({ coreRoot: core });
+  const before = [m.MODULE_SKILLS_MANIFEST, '.gitignore'].map((f) => readFileSync(join(core, '.claude', 'skills', f), 'utf8'));
+  const again = m.materializeModuleSkillsIntoCore({ coreRoot: core });
+  assert.deepEqual(again.removed, ['alpha']); assert.deepEqual(again.materialized, ['alpha']);
+  assert.deepEqual([m.MODULE_SKILLS_MANIFEST, '.gitignore'].map((f) => readFileSync(join(core, '.claude', 'skills', f), 'utf8')), before, 'byte-identical on the second run');
+  writeFileSync(join(core, 'modules', 'm1', 'module.json'), JSON.stringify({ key: 'm1', default: true, contributes: { skills: ['shared'] } }));
+  const dropped = m.materializeModuleSkillsIntoCore({ coreRoot: core });
+  assert.ok(!existsSync(join(core, '.claude', 'skills', 'alpha')), 'a skill no longer declared is removed, not left to linger');
+  assert.deepEqual(dropped.materialized, []);
+  writeFileSync(join(core, 'modules', 'm1', 'module.json'), JSON.stringify({ key: 'm1', default: true, contributes: { skills: ['alpha', 'shared'] } }));
+  m.materializeModuleSkillsIntoCore({ coreRoot: core });
+  const cleaned = m.materializeModuleSkillsIntoCore({ coreRoot: core, clean: true });
+  assert.deepEqual(cleaned.removed, ['alpha']);
+  for (const p of ['alpha', m.MODULE_SKILLS_MANIFEST, '.gitignore']) assert.ok(!existsSync(join(core, '.claude', 'skills', p)), `--clean removed ${p}`);
+  assert.ok(existsSync(join(core, '.claude', 'skills', 'core-one', 'SKILL.md')), 'the core\'s own skills survive --clean');
+  rmSync(core, { recursive: true, force: true });
+});
+
+t('--module-skills-only: an instance materialised FROM a core that carries materialised copies gets them through the module path (transformed), never as core skills, and never the two dotfiles', () => {
+  const core = fakeCore();
+  m.materializeModuleSkillsIntoCore({ coreRoot: core });
+  const inst = mkdtempSync(join(tmpdir(), 'cm-inst-'));
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.ok(!res.notes.some((n) => /"alpha".*also exists under the core/.test(n)), 'the materialised copy is not mistaken for a core skill');
+  assert.ok(res.moduleSkills >= 2, 'alpha landed through step 1b');
+  assert.match(readFileSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md'), 'utf8'), /bongos ship 1/, 'transformed on the way into the instance');
+  for (const f of [m.MODULE_SKILLS_MANIFEST, '.gitignore']) assert.ok(!existsSync(join(inst, '.claude', 'skills', f)), `${f} is not shipped to an instance`);
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'core-one', 'SKILL.md')) && existsSync(join(inst, '.claude', 'skills', 'shared', 'SKILL.md')), 'the core skills still land');
+  rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true });
+});
+
+t('--module-skills-only: the CLI entry refuses without the flag (usage, exit 2) and gen-file-map skips materialised names by the manifest', () => {
+  const { spawnSync } = require('node:child_process');
+  const bare = spawnSync(process.execPath, [join(ROOT, 'scripts', 'gds', 'claude-materialize.js')], { encoding: 'utf8' });
+  assert.equal(bare.status, 2); assert.match(bare.stderr, /--module-skills-only/);
+  // end to end through the real entry point, on the real checkout, writing nothing: --dry-run
+  // reports what it would land, --clean --dry-run what it would remove, both exit 0
+  const cli = join(ROOT, 'scripts', 'gds', 'claude-materialize.js');
+  const dry = spawnSync(process.execPath, [cli, '--module-skills-only', '--dry-run'], { encoding: 'utf8' });
+  assert.equal(dry.status, 0, dry.stderr); assert.match(dry.stdout, /\[dry-run\] would materialize \d+ module-owned skill/); assert.match(dry.stdout, /module skills → \.claude\/skills\//);
+  const dryClean = spawnSync(process.execPath, [cli, '--module-skills-only', '--clean', '--dry-run'], { encoding: 'utf8' });
+  assert.equal(dryClean.status, 0, dryClean.stderr); assert.match(dryClean.stdout, /\[dry-run\] would remove \d+ materialised module skill dir/);
+  assert.ok(!existsSync(join(ROOT, '.claude', 'skills', m.MODULE_SKILLS_MANIFEST)) || readFileSync(join(ROOT, '.claude', 'skills', m.MODULE_SKILLS_MANIFEST), 'utf8').length > 0, 'a dry run never wrote or emptied the real manifest');
+  const gen = require('../scripts/gds/gen-file-map.js');
+  const dir = mkdtempSync(join(tmpdir(), 'cm-fm-'));
+  for (const n of ['real', 'copy']) { mkdirSync(join(dir, n)); writeFileSync(join(dir, n, 'SKILL.md'), 'x'); }
+  writeFileSync(join(dir, m.MODULE_SKILLS_MANIFEST), JSON.stringify({ skills: { copy: { module: 'm1' } } }));
+  assert.deepEqual([...gen.materializedNames(dir)], ['copy']);
+  assert.deepEqual([...gen.materializedNames(join(dir, 'real'))], [], 'no manifest, nothing skipped');
+  rmSync(dir, { recursive: true, force: true });
+});
+
 console.log(`\nclaude_materialize: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/file_map.mjs

@@ -37,8 +37,11 @@ test('EVERY skill + scheduled-task dir on disk is listed AND has a note — no s
     // core checkout carries neither (task 1002470). Check the sections that exist.
     if (!existsSync(path.join(ROOT, section.dir))) continue;
     checked += 1;
+    // A module skill materialised into this checkout (task 1003330) is an untracked copy the
+    // module documents; the generator skips it by the manifest beside it, and so does this.
+    const materialised = gen.materializedNames(path.join(ROOT, section.dir));
     const onDisk = readdirSync(path.join(ROOT, section.dir), { withFileTypes: true })
-      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !materialised.has(e.name))
       .map((e) => e.name)
       .sort();
     const listed = section.entries.map((e) => e.name).sort();