@naswerks/engineering-loop 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "naswerks",
       "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The engineering loop: a knowledge loop (docs-*) and an execution loop (spec-*) for repositories driven by hosted agent sessions, plus init to make a repository ready for both.",
   "author": { "name": "naswerks" },
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,30 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-24
+
+### Added
+
+- **The menu declares its shape.** `docs/_meta/doc-index.md` carries `<!-- naswerks-loop: menu=all -->` (it
+  lists every living doc: the repository has no other index; the default, and what a menu with no such line
+  means) or `<!-- naswerks-loop: menu=curated; index={path} -->` (the repository already indexes every doc in
+  `{path}`; the menu lists the docs its seats read). `docs-workflow.md` § The repository-owned sections
+  explains both, and the loop's standard for a doc on a curated menu: a header at a decided status and a
+  `## Key Files` section. `init` writes `menu=curated` when its scan finds an index the repository already
+  keeps; `docs-process` registers a new doc where the shape says; `docs-status` and `docs-audit-full` flag a
+  menu that has drifted; `init doctor` reads the shape, FAILs a doc the menu names that does not exist,
+  flags a living doc an all-menu misses, and holds every doc a curated menu names to the standard.
+  `pins/menu.test.mjs` holds both shapes.
+
+### Changed
+
+- The map's Doc metadata row no longer asks whether the menu is kept by hand; the menu's shape line says
+  what the menu is.
+- `docs-workflow.md` § The repository-owned sections no longer says which words this repository writes for
+  the loop's states; that is § Doc metadata's to say, so a repository that pastes the section verbatim no
+  longer inherits a line that is untrue for it.
+- README: taking a new release is `claude plugin update`; the pins and the release path read as they are.
+
 ## [0.4.0] - 2026-09-23
 
 ### Changed

package/README.md

@@ -20,7 +20,8 @@ claude plugin install naswerks@engineering-loop
 
 The marketplace is this repository, and the plugin is sourced from it: no registry sits between you and a
 release. Plugins load at session start, so start a new session (or run `/reload-plugins`) after installing.
-To pick up a new release later: `claude plugin marketplace update engineering-loop`, then the install line again.
+To pick up a new release later: `claude plugin marketplace update engineering-loop`, then
+`claude plugin update naswerks@engineering-loop` (an install over an existing install does nothing).
 
 Skills are namespaced by the plugin: `/naswerks:docs-write`, `/naswerks:spec-pipeline`, `/naswerks:init`.
 
@@ -48,6 +49,11 @@ sections lists what each must answer. One grep lists the four:
 rg -n '^#+ .*\(repository-owned\)' docs/_meta/
 ```
 
+If the repository already keeps an index of every doc, declare the loop's menu curated — put
+`<!-- naswerks-loop: menu=curated; index=docs/INDEX.md -->` (your index's path) in `docs/_meta/doc-index.md`
+— and the menu lists only the docs your seats read, each held to the loop's standard; every other doc stays
+in your own index. A repository with no index of its own keeps the default, a menu of every living doc.
+
 Every skill names the section it needs and never states the format itself, so the pack stays generic and
 your conventions live in your repository. **Taking a newer pack:** `/naswerks:init refresh` writes only
 those four sections and the version stamp into your copies — a dry run first, then `--write` on your word —
@@ -70,7 +76,7 @@ and never touches the rest of the text.
 | `spec-retro` | spec | the coordinator's close-out audit |
 | `spec-witness` | spec | a read-only verifier |
 | `spec-ignite` | spec | the ignition copilot for a hosted run |
-| `init` | — | make a repository ready for both loops |
+| `init` | — | make a repository ready for both loops; `init doctor` checks one, `init refresh` takes a newer pack's repository-owned sections |
 
 `references/` carries the two method documents a repository copies into `docs/_meta/` and then
 rewrites where they say (repository-owned);
@@ -84,19 +90,26 @@ or the child may resolve `docs/` paths against the parent session's workspace.
 
 ## Does it work
 
-`npm test` runs the pins: one version across the package, the plugin manifest and the marketplace
-entry; every skill directory carries a `SKILL.md` named for its folder; no byte-order marks; the
-method documents carry the version stamp; the vocabulary censuses. `node bin/verify-staged.mjs
---self-test` drives the receipt against a throwaway repository and reports each case.
+`npm test` runs the pins: one version across the package, the plugin manifest, the marketplace entry and
+both method documents' stamps; every skill directory carries a `SKILL.md` named for its folder; no
+byte-order marks; the vocabulary and content censuses; no skill states a format a repository owns, and
+every skill that needs one carries the same find-format line; exactly four repository-owned sections, found
+by the one grep; the loop's own preferences stay stated in the method documents; the menu's two shapes; `init refresh` leaves
+every line outside those sections byte for byte. `node bin/verify-staged.mjs --self-test` drives the
+receipt against a throwaway repository and reports each case.
 
 ## Releasing
 
-The version lives in `package.json` and `.claude-plugin/plugin.json` (they must agree). A `v*` tag
-runs the pins and publishes to npm through trusted publishing; the GitHub release notes are the
-CHANGELOG section for that version. The marketplace serves the plugin from this repository at whatever
-`main` holds, so a CLI install never waits on npm; npm is the runner lane, and a refused publish leaves
-runners one version behind until the trusted publisher on npmjs.com matches this repository and
-`release.yml` (the workflow prints that remedy when it happens).
+The version lives in `package.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
+(they must agree), in both method documents' stamps, and in a CHANGELOG section. The marketplace serves
+the plugin from this repository at whatever `main` holds, so a CLI install never waits on npm; npm is the
+runner lane.
+
+To release: push the release commit to `main`, publish it to npm from the repository root (`npm login`,
+then `npm publish --access public`), then push its `v*` tag. The tag's workflow runs the pins, finds the
+version already on the registry and skips its own publish, and creates the GitHub release from the
+CHANGELOG section. With a trusted publisher linked on npmjs.com for this repository and `release.yml`,
+pushing the tag alone publishes; the workflow prints that remedy when a publish is refused.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The engineering loop as a Claude Code plugin: a knowledge loop (docs-*), an execution loop (spec-*), and init for a fresh repository. The package root is the plugin root.",
   "license": "MIT",
   "type": "module",

package/references/docs-workflow.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.4.0 -->
+<!-- naswerks-loop: version=0.5.0 -->
 # Docs Workflow
 
 > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.
@@ -84,12 +84,12 @@ that replaces the section rewrites alongside it):
 | Section | What the skills read from it | Also echoed in |
 |---------|------------------------------|----------------|
 | **The archive convention** (this file) | the archive home for each kind of effort (hand-cranked, spec pipeline, follow-on round) and for audit reports · the shape inside it · what a working doc's `## Archive` line says, and whether an umbrella carries an `Archive:` line · the links a move repairs · what is frozen once filed | The Loop (the diagram and its prose) · Folders (`research/`, `working/`, `archive/`) · "Living docs vs session docs" · the skills table (`docs-process`) · Conventions (incident receipts, archived docs) · `engineering-loop.md` "The loop at a glance" |
-| **Doc metadata** (this file) | the header — its form and its place · the sweep: one command, one line per doc · the word for each loop state (below) · where the verified date lives, and the rule that moves it · whether `## Lineage` stays · the gates a doc passes, and the folders they exempt · whether `doc-index.md` is kept by hand or generated | the skills table (`docs-status`) · Conventions (the machine layer; dates in the header) · `engineering-loop.md`'s own header line and its `## Lineage` |
+| **Doc metadata** (this file) | the header — its form and its place · the sweep: one command, one line per doc · the word for each loop state (below) · where the verified date lives, and the rule that moves it · whether `## Lineage` stays · the gates a doc passes, and the folders they exempt | the skills table (`docs-status`) · Conventions (the machine layer; dates in the header) · `engineering-loop.md`'s own header line and its `## Lineage` |
 | **Templates** (this file) | each template's header lines, at the state its writer names | — |
 | **This repository's rails** (`engineering-loop.md`) | the policy document, and how a seat reaches it · the gates a commit passes · the suite before a PR · the base branch, the PR target, the branch names and how a PR is opened · the staging rule · the repository's own skills a seat meets | the POLICY row of "Where a rule lives" · the Hard rules, which the rails add to and never subtract from |
 
 **The loop's states.** The skills speak in four states, and § Doc metadata says which word this repository
-writes for each. Here the words are the states themselves.
+writes for each.
 
 | State | Written by | Means |
 |-------|------------|-------|
@@ -100,8 +100,21 @@ writes for each. Here the words are the states themselves.
 
 *Stale* is a date, not a state: `docs-status` computes it from the verified date, and no seat writes it.
 
-**Silence.** A section that says nothing about an item leaves the loop's default: the menu is kept by hand
-(`docs-process` adds a row for a new feature doc), no gate runs on a commit, the base branch is the remote's
+**The menu.** `doc-index.md` is the menu the seats read, and the whole file is the repository's: `init` writes
+it once and never again. A line near its top says which of two shapes it has, and one grep reads it:
+`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`.
+
+| Shape line | The menu lists | A new living doc goes |
+|------------|----------------|-----------------------|
+| `<!-- naswerks-loop: menu=all -->` | every living doc — the repository has no other index | onto the menu |
+| `<!-- naswerks-loop: menu=curated; index={path} -->` | the docs this repository's seats read; `{path}` indexes every doc | into `{path}`, the way that index is kept, and onto the menu only when it meets the loop's standard and a seat should read it |
+
+**The loop's standard for a doc on a curated menu:** it exists, it carries the header § Doc metadata
+prescribes at a decided status (not the word for `draft`), and it has a `## Key Files` section. `init doctor`
+checks exactly that, for every doc a curated menu names.
+
+**Silence.** A section that says nothing about an item leaves the loop's default: a menu with no shape line
+lists every living doc (`menu=all`), no gate runs on a commit, the base branch is the remote's
 default (`git symbolic-ref refs/remotes/origin/HEAD`), and a seat with no PR route asks the human once and
 suggests recording the answer in the rails. Any other unanswered item is a question for the human, never a
 guess.
@@ -131,6 +144,9 @@ Keep what the skills need to find, change the words to yours:
   `spec-pipeline` then records the resolved path in the umbrella's blockquote as an `Archive:` line.
 - **Your rails.** Fill each item of `engineering-loop.md` § This repository's rails from what the
   repository already wrote down — a policy document, hooks, CI, a pull-request template.
+- **Your menu.** A repository that already indexes its docs declares its menu curated and names that index:
+  the menu then lists only the docs its seats read, each meeting the loop's standard, and every other doc
+  stays in the repository's own index, kept the way it already is.
 
 **The version stamp** on line 1 names the pack version whose repository-owned sections this copy carries.
 The loop text around them is this repository's copy from whenever it was taken: `init doctor` never grades

package/references/engineering-loop.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.4.0 -->
+<!-- naswerks-loop: version=0.5.0 -->
 # The Engineering Loop — flow, seats, skills, and the ceremony
 
 > The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`

package/skills/docs-audit-full/SKILL.md

@@ -18,7 +18,10 @@ what to audit next.
    oldest-first.
 
 2. **Feature completeness** — quick `docs/features/` folder pass (per `docs-audit-feature`'s
-   folder mode): any features in code with no doc, or docs whose feature is gone.
+   folder mode): any features in code with no doc, or docs whose feature is gone. Then the menu against its
+   shape line (`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`; none means `menu=all`): on
+   `menu=all`, living docs it does not name; on `menu=curated`, docs it names that fall short of the loop's
+   standard (`docs/_meta/docs-workflow.md` § The repository-owned sections).
 
 3. **Convention spot-check** — sample 2-3 source files per major convention against the
    `docs/patterns/` docs; note drift.

package/skills/docs-process/SKILL.md

@@ -92,9 +92,13 @@ branch, which is the truth for that PR, and you say so at close.
      speculation. A sizable design idea goes to `docs-backlog` (research/) instead. `docs-status`
      surfaces these so they aren't lost.
 
-3. **New feature?** If the work added a feature, ensure it has a doc in `docs/features/` (one doc per
-   feature) and add it to the menu in `docs/_meta/doc-index.md` — unless `docs-workflow.md` § Doc metadata
-   (repository-owned) says a repository tool generates the menu, in which case leave it alone.
+3. **A new living doc?** If the work added a feature, ensure it has a doc in `docs/features/` (one doc per
+   feature). Then register every living doc this run created where the menu's shape line says
+   (`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`; `docs/_meta/docs-workflow.md` § The
+   repository-owned sections explains the two shapes). **`menu=all`, or no shape line:** add its row to the
+   menu in `docs/_meta/doc-index.md`. **`menu=curated; index={path}`:** add it to `{path}` the way that
+   index is kept — a generated index is never edited by hand — and add a menu row only when the doc meets
+   the loop's standard and a seat should read it; say which you did in the summary.
 
 4. **Closing grep** — if the session doc notes deletions or renames, grep all living
    docs (`guides/ patterns/ infrastructure/ features/ _meta/`) for stale references and fix them. Do

package/skills/docs-status/SKILL.md

@@ -36,6 +36,10 @@ just counts.
      broken breadcrumb).
    - **low-lineage feature** — where the section keeps `## Lineage`: a feature doc with no Lineage rows =
      ungrounded; worth wiring its lineage.
+   - **menu drift** — read the menu's shape line (`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`;
+     none means `menu=all`). On `menu=all`: a living doc the menu does not name. On `menu=curated`: a doc the
+     menu names that falls short of the loop's standard (`docs/_meta/docs-workflow.md` § The
+     repository-owned sections — a header at a decided status and a `## Key Files` section).
 
 5. **Open issues.** Grep living docs for an `## Open Issues` section; list which docs/features carry
    unresolved, code-verified problems (and how many) so known risks surface at orientation instead of

package/skills/init/SKILL.md

@@ -38,7 +38,8 @@ docs/
   _meta/docs-workflow.md          a copy of the pack's references/docs-workflow.md (stamped); its sections marked
                                   (repository-owned) are the repository's to rewrite to its own conventions
   _meta/engineering-loop.md       a copy of references/engineering-loop.md (stamped), under the same rule
-  _meta/doc-index.md              the menu, written LAST — every doc that exists + three repo slots:
+  _meta/doc-index.md              the menu, written LAST — its shape line (menu=all: every doc that exists;
+                                  menu=curated: the docs init drafted, when the repository indexes its own) + three repo slots:
                                   ## Role reading lists · ## Apps and their build commands · ## The evidence tools
   research/ working/ archive/ guides/ patterns/ infrastructure/ features/     each with a README.md
   patterns/code-organization.md  patterns/backend-patterns.md
@@ -104,7 +105,9 @@ what it says` — and cite from it. A draft written mid-scan is a draft written
    analyzer configs (`.stylecop`, `.globalconfig`, `Directory.Build.props` rules such as
    `TreatWarningsAsErrors`, `Nullable`, banned-API lists) · `tsconfig*.json` strictness ·
    `BannedSymbols.txt`, `FLAKY-TESTS.md` · CODEOWNERS · `.husky/`, `.githooks/` · PR templates · the
-   existing `docs/` tree · `.claude/settings.json`.
+   existing `docs/` tree · `.claude/settings.json` · an index the repository already keeps of every doc (a
+   `docs/INDEX.md` or `docs/index.md` that lists them, a `docs/SUMMARY.md`, a `mkdocs.yml` nav, a
+   docusaurus or vitepress sidebar).
 
 ## The write order — create-if-missing at every step
 
@@ -134,8 +137,12 @@ not. `init` never overwrites, never reorders, never deletes.
    Evidence per concern: a `generated/` folder or codegen config; a state library; a UI library; a tokens
    file or token layer; a saga / workflow / state-machine mechanism; a realtime library on either side; a
    queue, worker or scheduler.
-5. `docs/_meta/doc-index.md` from its template, LAST, listing every doc that now exists under the four
-   living folders (drafted or repo-owned), the three repo slots filled from the scan.
+5. `docs/_meta/doc-index.md` from its template, LAST, with its shape line (`docs/_meta/docs-workflow.md`
+   § The repository-owned sections, the menu). **`menu=all`** when the repository keeps no other index: the
+   menu lists every doc that now exists under the four living folders (drafted or repo-owned). **`menu=curated;
+   index={path}`** when pass 4 found an index the repository already keeps of every doc: the menu lists only
+   the docs `init` drafted, and the report says the owner adds each further doc that meets the loop's
+   standard. Either way, the three repo slots are filled from the scan.
 6. The Start-here stanza (`templates/claude-md-stanza.md`) appended to `CLAUDE.md` (created if absent)
    and to `AGENTS.md` (only if present); skipped when the opening marker
    `<!-- naswerks-loop:start-here -->` is already there.
@@ -187,9 +194,11 @@ FAIL, so a CI job or a control plane can call it.
 | each repository-owned heading, in its file | — | unmarked (an earlier spelling) or missing — `init refresh` marks or adds it | present |
 | each item of § This repository's rails (repository-owned) | — | missing, or still its absent-line | recorded |
 | `_meta/doc-index.md` and its three slot sections | missing | a slot carries only the absent-line | filled |
+| the menu's shape line | an unknown shape | a curated menu names no index, or an index that does not exist | `menu=all` (also a menu with no shape line), or `menu=curated` with its index |
+| every living doc a `menu=all` menu should list | — | a doc under the four living folders the menu does not name | named |
+| every doc a menu names | the path does not exist (a row saying `not detected` is exempt) | on a curated menu: no status in either header form, the word `draft`, or no `## Key Files` | meets the loop's standard |
 | the four floor docs | missing | the word `draft` (read from either header form), or an `<!-- init: -->` left in | a decided status |
 | the seven standard docs | absent AND no doc-index row saying `not detected` | the word `draft` when present; absent with its row | present and decided, or absent with its row |
-| every path a § Role reading lists row names | the row's path does not exist | — | resolves |
 | `CLAUDE.md` / `AGENTS.md` stanza · `.claude/settings.json` pin | — | missing | present |
 | `verify-staged` | — | not on PATH (the row carries the fallback) | resolvable |
 | every `docs/research/*/00-ignition-brief.md` | the five problems the control plane's parser emits (no `## The kick`; the kick has no blockquote; no `## The sequence`; the sequence holds no table; a row names no kind from `coordinator build fixit review retro witness docs-process`), or a spec a row names is missing from disk | — | clean |

package/skills/init/scripts/doctor.mjs

@@ -118,13 +118,46 @@ function docRow(relPath, required) {
   if (/<!-- init:/.test(text)) row('DEGRADE', `docs/${relPath}`, 'an <!-- init: --> instruction was left in the file');
 }
 
-// ── 4b. every path a Role reading lists row names resolves ─────────────────────────────────────
-if (roleRows !== null) {
-  for (const line of roleRows.split('\n').filter((l) => l.trim().startsWith('|') && !/^\|\s*-/.test(l.trim()) && !/^\|\s*Doc\s*\|/i.test(l.trim()))) {
-    for (const m of line.matchAll(/`((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)`|\]\((?:\.\.\/)?((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)\)/g)) {
-      const p = m[1] || m[2];
-      if (/not detected/i.test(line)) continue;
-      row(existsSync(join(repo, 'docs', p)) ? 'ok' : 'FAIL', `doc-index row: docs/${p}`, existsSync(join(repo, 'docs', p)) ? '' : 'the row names a path that does not exist');
+// ── 4b. the menu: its shape, and every doc it names ────────────────────────────────────────────
+// doc-index.md declares one of two shapes (docs-workflow.md § The repository-owned sections): menu=all lists
+// every living doc; menu=curated lists the docs the seats read and names the index that lists every doc. A
+// menu with no shape line is menu=all. Every doc a menu names must exist (a row saying `not detected` is
+// exempt); a curated menu's docs must also meet the loop's standard: a status in either header form, not
+// draft, and a `## Key Files` section.
+{
+  const menu = read(join(repo, 'docs', '_meta', 'doc-index.md'));
+  if (menu !== null) {
+    const line = /<!-- naswerks-loop: menu=([A-Za-z-]+)(?:;\s*index=(\S+?))?\s*-->/.exec(menu);
+    const shape = line ? line[1] : 'all';
+    if (!['all', 'curated'].includes(shape)) row('FAIL', 'menu shape', `menu=${shape} is not a shape the loop knows (all | curated)`);
+    else if (shape === 'curated') {
+      const index = line[2];
+      if (!index) row('DEGRADE', 'menu shape', 'menu=curated names no index of every doc, so docs-process cannot say where a new doc is registered');
+      else if (!existsSync(join(repo, index))) row('DEGRADE', 'menu shape', `menu=curated; its index ${index} does not exist`);
+      else row('ok', 'menu shape', `menu=curated; index=${index}`);
+    } else row('ok', 'menu shape', line ? 'menu=all' : 'menu=all (no shape line: the default)');
+
+    const named = new Set();
+    for (const l of menu.split('\n')) {
+      if (/not detected/i.test(l)) continue;
+      for (const m of l.matchAll(/(?:\]\(|`)(?:\.\.\/)?((?:guides|patterns|infrastructure|features)\/[A-Za-z0-9_./-]+\.md)/g)) named.add(m[1]);
+    }
+    const missing = [...named].filter((p) => !existsSync(join(repo, 'docs', p))).sort();
+    for (const p of missing) row('FAIL', `menu: docs/${p}`, 'the menu names a doc that does not exist');
+    if (shape === 'curated') {
+      for (const p of [...named].filter((q) => !missing.includes(q)).sort()) {
+        const text = read(join(repo, 'docs', p));
+        const short = [];
+        const st = statusOf(text);
+        if (st === null) short.push('no status in either header form');
+        else if (st.value === 'draft') short.push('status draft');
+        if (!/^## Key Files\b/m.test(text)) short.push('no ## Key Files');
+        row(short.length ? 'DEGRADE' : 'ok', `menu: docs/${p}`, short.length ? `below the loop's standard: ${short.join(', ')}` : "meets the loop's standard");
+      }
+    } else if (shape === 'all') {
+      const unnamed = livingDocs().filter((p) => !named.has(p) && !menu.includes(p));
+      for (const p of unnamed) row('DEGRADE', `menu: docs/${p}`, 'a living doc the menu does not name (menu=all) — add its row, or declare the menu curated');
+      if (!unnamed.length && !missing.length) row('ok', 'menu entries', `names every living doc (${named.size}), each present`);
     }
   }
 }
@@ -249,6 +282,24 @@ function frontmatterOf(text) {
   }
   return out;
 }
+// The living docs a menu=all menu lists: every .md directly under the four living folders, and each
+// feature folder's own docs one level down (a filed effort's notes sit deeper and are history, not living).
+function livingDocs() {
+  const out = [];
+  for (const f of ['guides', 'patterns', 'infrastructure', 'features']) {
+    const dir = join(repo, 'docs', f);
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && e.name !== 'README.md') out.push(`${f}/${e.name}`);
+      else if (f === 'features' && e.isDirectory()) {
+        for (const g of readdirSync(join(dir, e.name), { withFileTypes: true })) {
+          if (g.isFile() && g.name.endsWith('.md') && g.name !== 'README.md') out.push(`features/${e.name}/${g.name}`);
+        }
+      }
+    }
+  }
+  return out.sort();
+}
 function firstBodyLine(text) {
   let body = text;
   if (text.startsWith('---\n')) { const end = text.indexOf('\n---', 4); if (end >= 0) body = text.slice(end + 4).replace(/^\n+/, ''); }

package/skills/spec-seat/SKILL.md

@@ -53,7 +53,7 @@ Do this immediately, whatever your assignment turns out to be. It needs no role
 
 | Doc | What it gives you |
 |---|---|
-| `docs/_meta/doc-index.md` | the menu — which living doc answers which question |
+| `docs/_meta/doc-index.md` | the menu — which living doc answers which question: every living doc, or on a curated menu the ones meant for seats (its shape line says which) |
 | `docs/_meta/docs-workflow.md` | the folders, the templates, the two loops — and, in its sections marked (repository-owned), this repository's doc header and where an effort is filed |
 | `docs/_meta/engineering-loop.md` | the seats, the ceremony, **the comms protocol you follow** — and this repository's rails (repository-owned) |
 

package/templates/docs/_meta/doc-index.md

@@ -2,6 +2,12 @@
 
 > The menu. Read this at session start, pick the 2-3 docs that match your task, read those for context.
 > This is the curated short list — the compiled layer you read *before* diving into source.
+<!-- naswerks-loop: menu=all -->
+<!-- init: the shape line above stays in the output. It says menu=all unless the scan found an index the
+     repository already keeps of every doc (a docs/INDEX.md or docs/index.md that lists them, a
+     docs/SUMMARY.md, a mkdocs.yml nav, a docusaurus or vitepress sidebar); then it says
+     menu=curated; index={that path}, and the tables below list only the docs init drafted plus the Meta
+     rows. The owner adds each further doc that meets the loop's standard. -->
 
 ---