coilysiren/website

Watch

Write the docs manifests for agent-compose and mcp-beaver: 62 pages need a title, a shelf, and a blurb #137

New issue

Closed

opened 2026-08-27 08:24:29 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-27 08:24:29 +00:00

Collaborator

Developer Advocate lane. Handoff from coilysiren/website#135, and the long pole on mounting either project's docs.

Why this is writing rather than extraction

umbra's manifest was cheap because umbra has a docs/index.md, and every blurb in src/data/umbra-docs.js was lifted from it verbatim. That is deliberate, and docs/project-docs-mount.md states it: the shelf never invents a second description of a page.

Verified against origin/main on 2026-08-27: neither repo has a docs/index.md. There is nothing to lift, so each page needs a line written for it.

agent-compose: 40 docs, 5 excluded as planning artifacts, so 35 pages.
mcp-beaver: 22 docs, none excluded, so 22 pages.

Both exclusion lists are verified and already recorded in src/data/docs-mounts.json under planned.

What each page needs

Title - the reader-facing name rather than the filename. umbra's specgen.md is titled "The no-code driver".
Shelf - one of the five reader-task groups umbra uses: getting started, guides, reference, concepts, contributing. Decided on coilysiren/inbox#438, and reader-task rather than architecture.
Blurb - one line in Kai's register. umbra's read like "Install it, then watch a refusal." and "Author policy and locks, never Go."

Shelf assignment and reading order are structure rather than prose, so they can come from whoever holds the file. The blurb is the part that needs the voice.

Also needed, and smaller

A front-door headline per project, the way /projects/umbra/docs/ has one. docs/project-docs-mount.md already calls that Developer Advocate work rather than layout.

Where it lands

src/data/<project>-docs.js, mirroring src/data/umbra-docs.js: shelves in reading order, each with its pages. One file per project, hand-written and reviewed. It is the only place section structure can live, because documentation-layout permits no subdirectories under docs/.

Sequencing

The render layer is umbra-shaped and tracked separately as coilysiren/website#136. The two are independent: manifests can be written before the code takes them, and neither project mounts until both exist.

Worth knowing before writing

These are reference docs for a config framework and an MCP generator. The audience coilysiren/website#133 names for the site is a hiring manager rather than a practitioner, and reference docs mostly serve people who already arrived. A blurb that reads as a promise to a buyer will fight the page it labels. umbra's blurbs are worth reading first as the register that worked.

**Developer Advocate lane. Handoff from coilysiren/website#135, and the long pole on mounting either project's docs.** ## Why this is writing rather than extraction umbra's manifest was cheap because umbra has a `docs/index.md`, and every blurb in `src/data/umbra-docs.js` was lifted from it verbatim. That is deliberate, and `docs/project-docs-mount.md` states it: the shelf never invents a second description of a page. Verified against `origin/main` on 2026-08-27: **neither repo has a `docs/index.md`.** There is nothing to lift, so each page needs a line written for it. * agent-compose: 40 docs, 5 excluded as planning artifacts, so 35 pages. * mcp-beaver: 22 docs, none excluded, so 22 pages. Both exclusion lists are verified and already recorded in `src/data/docs-mounts.json` under `planned`. ## What each page needs * **Title** - the reader-facing name rather than the filename. umbra's `specgen.md` is titled "The no-code driver". * **Shelf** - one of the five reader-task groups umbra uses: getting started, guides, reference, concepts, contributing. Decided on coilysiren/inbox#438, and reader-task rather than architecture. * **Blurb** - one line in Kai's register. umbra's read like "Install it, then watch a refusal." and "Author policy and locks, never Go." Shelf assignment and reading order are structure rather than prose, so they can come from whoever holds the file. The blurb is the part that needs the voice. ## Also needed, and smaller A front-door headline per project, the way `/projects/umbra/docs/` has one. `docs/project-docs-mount.md` already calls that Developer Advocate work rather than layout. ## Where it lands `src/data/<project>-docs.js`, mirroring `src/data/umbra-docs.js`: shelves in reading order, each with its pages. One file per project, hand-written and reviewed. It is the only place section structure can live, because `documentation-layout` permits no subdirectories under `docs/`. ## Sequencing The render layer is umbra-shaped and tracked separately as coilysiren/website#136. The two are independent: manifests can be written before the code takes them, and neither project mounts until both exist. ## Worth knowing before writing These are reference docs for a config framework and an MCP generator. The audience coilysiren/website#133 names for the site is a hiring manager rather than a practitioner, and reference docs mostly serve people who already arrived. A blurb that reads as a promise to a buyer will fight the page it labels. umbra's blurbs are worth reading first as the register that worked.

coilyco-ops added the

autonomy

headless

priority

labels

2026-08-27 08:24:30 +00:00

coilyco-ops referenced this issue from a commit

2026-08-27 08:59:33 +00:00

docs(mounts): write the agent-compose and mcp-beaver docs manifests

coilyco-ops closed this issue

2026-08-27 08:59:33 +00:00

coilyco-ops commented

2026-08-27 09:01:20 +00:00

Author

Collaborator

Written and pushed in 007ae11.

src/data/docs-manifest-agent-compose.js - 35 pages, all five shelves.
src/data/docs-manifest-mcp-beaver.js - 22 pages, four shelves. No contributing page exists upstream, so there is no Contributing shelf.

Both slug sets were diffed against docs/ on each repo's origin/main, agent-compose minus the five exclusions already recorded under planned. They match exactly, so docs-mount.test.ts's manifest-versus-vendored check will pass the moment either entry moves into mounts.

What was written

Every title, every blurb, and a front-door headline, description, and lede per project. Nothing was lifted, because neither repo has a docs/index.md to lift from. Each line was written against the page it labels after reading it.

Shelf assignment is the reader-task set from coilysiren/inbox#438. Two calls worth naming, since both are judgment rather than mechanics:

Neither repo has a getting-started.md. agent-compose's Getting started is features then architecture, because architecture is where the nine words are defined and nothing downstream reads without them. mcp-beaver's is DESIGN.md then FEATURES.md, since DESIGN carries the thesis sentence and the scope boundary.
mcp-beaver's chart, image, and CI pages went to Guides rather than a shelf of their own. Shipping it is a thing you do, and the five groups have no sixth.

Headlines: "Compose the context, then diff it." and "Write the guardfile. Everything else derives." Both are the post-decision version of the case-study hook rather than a restatement of it, matching umbra's "Name every command, then prove it."

What this does not do

Neither project mounts. Both stay under planned, so the loader never imports either file and nothing renders. just test:quick is green, which here means the manifests are inert and correct rather than exercised.

Mounting is the remaining step and is behavior rather than copy: vendor the docs with just sync-project-docs, write the stamp, move the entry from planned into mounts, and let the 62 new routes into the sitemap. coilysiren/website#136 built the render half that makes it a config-only change. Whoever takes it should also expect the dead-cross-links exclusion in pyproject.toml to need both new mount paths, the way umbra's is listed.

Found while reading

ward-kdl appears in three of umbra's already-mounted docs pages and in two Go comments, against wrap ward everywhere else in that repo. The mount is verbatim by contract so this repo cannot fix it. Filed upstream as coilyco-flight-deck/umbra#332, and a just sync-project-docs pulls the fix through once it lands.

Written and pushed in 007ae11. * `src/data/docs-manifest-agent-compose.js` - 35 pages, all five shelves. * `src/data/docs-manifest-mcp-beaver.js` - 22 pages, four shelves. No contributing page exists upstream, so there is no Contributing shelf. Both slug sets were diffed against `docs/` on each repo's `origin/main`, agent-compose minus the five exclusions already recorded under `planned`. They match exactly, so `docs-mount.test.ts`'s manifest-versus-vendored check will pass the moment either entry moves into `mounts`. ## What was written Every title, every blurb, and a front-door headline, description, and lede per project. Nothing was lifted, because neither repo has a `docs/index.md` to lift from. Each line was written against the page it labels after reading it. Shelf assignment is the reader-task set from coilysiren/inbox#438. Two calls worth naming, since both are judgment rather than mechanics: * Neither repo has a `getting-started.md`. agent-compose's Getting started is `features` then `architecture`, because architecture is where the nine words are defined and nothing downstream reads without them. mcp-beaver's is `DESIGN.md` then `FEATURES.md`, since DESIGN carries the thesis sentence and the scope boundary. * mcp-beaver's chart, image, and CI pages went to Guides rather than a shelf of their own. Shipping it is a thing you do, and the five groups have no sixth. Headlines: "Compose the context, then diff it." and "Write the guardfile. Everything else derives." Both are the post-decision version of the case-study hook rather than a restatement of it, matching umbra's "Name every command, then prove it." ## What this does not do Neither project mounts. Both stay under `planned`, so the loader never imports either file and nothing renders. `just test:quick` is green, which here means the manifests are inert and correct rather than exercised. Mounting is the remaining step and is behavior rather than copy: vendor the docs with `just sync-project-docs`, write the stamp, move the entry from `planned` into `mounts`, and let the 62 new routes into the sitemap. coilysiren/website#136 built the render half that makes it a config-only change. Whoever takes it should also expect the `dead-cross-links` exclusion in `pyproject.toml` to need both new mount paths, the way umbra's is listed. ## Found while reading `ward-kdl` appears in three of umbra's already-mounted docs pages and in two Go comments, against `wrap ward` everywhere else in that repo. The mount is verbatim by contract so this repo cannot fix it. Filed upstream as coilyco-flight-deck/umbra#332, and a `just sync-project-docs` pulls the fix through once it lands.

coilyco-ops commented

2026-08-27 09:14:48 +00:00

Author

Collaborator

Correction to the comment above, and to this issue's title. The count is 57 pages, not 62.

35 plus 22 is 57. The 62 in the title counts agent-compose's full 40 docs rather than the 35 that survive its exclusion list, which this issue's own body states correctly. I carried the title's number into my comment without doing the arithmetic.

What was actually written is unchanged and was verified by diff rather than by counting: 35 manifest entries for agent-compose, 22 for mcp-beaver, both matching docs/ on origin/main exactly. Only the prose totals were wrong.

Where it matters: mounting adds 59 new routes, not 62. 57 doc pages plus one front door per project. That is the number in front of the publish decision, so it is worth having right.

Two other corrections from coilyco-flight-deck/umbra#332's resolution and from Delphi's work on the mount, neither of them mine to claim:

The dead-cross-links exclusion needs no pyproject.toml edit. Delphi generalized it to src/projects/docs/**, so both new mounts are already inside the glob. My note above said otherwise and was inference rather than something I opened the file to check.
umbra#332 is closed and landed. ward-kdl was ward's proving-ground binary, retired, and ward is the live name. My write-up scoped it to five sites by excluding test files, and left out roughly a hundred more in fixtures across cli/execverb, http/guardfile, and http/specgen, some of them asserted on. Those stay deliberately, as arbitrary consumer names in test data. The fix reaches the site on the next daily sync.

Correction to the comment above, and to this issue's title. **The count is 57 pages, not 62.** 35 plus 22 is 57. The 62 in the title counts agent-compose's full 40 docs rather than the 35 that survive its exclusion list, which this issue's own body states correctly. I carried the title's number into my comment without doing the arithmetic. What was actually written is unchanged and was verified by diff rather than by counting: 35 manifest entries for agent-compose, 22 for mcp-beaver, both matching `docs/` on origin/main exactly. Only the prose totals were wrong. Where it matters: mounting adds **59 new routes**, not 62. 57 doc pages plus one front door per project. That is the number in front of the publish decision, so it is worth having right. Two other corrections from coilyco-flight-deck/umbra#332's resolution and from Delphi's work on the mount, neither of them mine to claim: * The `dead-cross-links` exclusion needs no `pyproject.toml` edit. Delphi generalized it to `src/projects/docs/**`, so both new mounts are already inside the glob. My note above said otherwise and was inference rather than something I opened the file to check. * umbra#332 is closed and landed. `ward-kdl` was ward's proving-ground binary, retired, and `ward` is the live name. My write-up scoped it to five sites by excluding test files, and left out roughly a hundred more in fixtures across `cli/execverb`, `http/guardfile`, and `http/specgen`, some of them asserted on. Those stay deliberately, as arbitrary consumer names in test data. The fix reaches the site on the next daily sync.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilysiren/website#137

No description provided.

Rows
Columns