docs: complete and verify the split documents — 24 undocumented routes, merged route sections, ADRs #264

New issue

Closed

opened 2026-10-13 16:41:11 +02:00 by dominik.polakovics · 0 comments

dominik.polakovics commented

2026-10-13 16:41:11 +02:00

Owner

Summary

Make the documents #263 created true and complete: write the 24 route sections the API reference stubs, fix the stale claims the move carried over, condense the narrative to the depth each document's audience needs, and extract the design decisions into docs/adr/. #263 moved the content without rewording it; this issue is the content pass.

Current behavior

After #263 lands, docs/ holds the README's former content verbatim, with these known defects carried over:

docs/api.md has stub headings for 24 routes that were never documented: /api/element/body, /api/element/duplicate, /api/element/refs, /api/media/bundle, /api/media/delete, /api/media/folder/create, /api/media/folder/delete, /api/media/folder/delete-plan, /api/media/folder/move, /api/media/folder/rename, /api/media/info, /api/media/library, /api/media/move, /api/media/refs, /api/media/rename, /api/media/thumb, /api/media/tree, /api/media/upload, /api/page/create-root, /api/page/discard, /api/page/move, /api/page/refs, /api/page/reorder, /api/publish/status.
The documented routes were written one feature at a time, each in the voice of its commit: the same route (GET /api/page, POST /api/page/save, GET /api/tree) is described in several places with different key lists (base shape in one paragraph, translation keys in "Translations on the wire", enabled in another, children digest in another). No section gives a route's full current response.
docs/harness.md inherited "The ten commands" (eleven lines, version missing) and prose written before later flags existed.
docs/architecture.md still carries rationale paragraphs that are decisions, not architecture: "Rich text, never raw HTML", "Media gate", "Publish is a background job", "Branch mode", "Branch-bundle page management", "Publish anyway", the host-navigation "Safety" reasoning, the bundle "requires" model replacing the standard flag (78e181e), the engine-written aliases being dropped (e4d8138).
docs/adr/ is empty apart from its format README.
Sections may contradict the code: the README was never synced (no docs: commit since July); the update-docs skill's "verify against the current code, not the diff" rule has never been applied to it.

Desired behavior

docs/api.md: every route has exactly one section, in a consistent shape — method and path, purpose in one sentence, request body (or query) with every key and its type, response with every key, the error codes it answers with (from the coded-error catalog), and language/translation behaviour where it applies. The scattered partial descriptions of a route are merged into its one section; cross-cutting behaviour (coded error bodies, Accept-Language, lang addressing, translation on page answers) is stated once in a preamble and linked. Every key named is verified against the handler and the Go types it marshals, not against the old prose.
docs/harness.md: every command's section matches usage() and the flag parsing in cmd/harness; exit codes and --json shapes verified against the code; "ten commands" is gone.
docs/host-navigation.md: unchanged in substance (it is a versioned contract); only broken cross-links and clearly editorial fixes.
docs/features.md: verified against internal/feature (or wherever bundles, receipts and requires resolution live) and the shipped bundles under scaffold/; condensed where the move left feature-by-feature repetition.
docs/architecture.md: a reader-ordered narrative (content model → sidecars → server → editor shell → git/publish → multilingual) at roughly a third of the moved length. Each decision paragraph becomes one sentence plus a link to its ADR.
docs/adr/: one record per decision listed above (and any other the agent finds that has a stated "why"), each with context, decision, consequences and the originating commit or issue. ADRs are records: write them from the rationale the README already stated, dated to the commit that made the decision, not reinvented.
scaffold/site/AGENTS.md: if any moved sidecar fact proves wrong against the engine during verification, fix it there (its drift test must stay green).
docs/.docs-sync updated to the new HEAD.

Decisions

Verify against code, not the diff or the old prose — the old README was append-only and never synced; carrying its claims forward unverified would just relocate the drift. This is the update-docs skill's standing rule, applied for the first time.
One section per route, merged — the per-feature scatter is why nobody could read a route's full shape; the route drift test from #263 guarantees the heading set, this issue guarantees the content.
ADRs are records, dated to their commit — the update-docs skill forbids editing records to match new code; a record written now about a 2026-10-04 decision says so in its date and references the commit.
Architecture is for orientation, not completeness — a third of the length is a target, not a limit; the completeness lives in docs/api.md and docs/harness.md, which the drift tests cover.
Host-navigation substance is frozen — it is a contract with deckle-hosted; a substantive change is its own issue with a version bump.

Key interfaces

internal/server handlers and the request/response structs they decode and marshal — the source of truth for every key in docs/api.md.
The coded-error catalog (servermessages.json / the code + args error body introduced in 1322a0c) — the error-code vocabulary each route section cites.
cmd/harness usage(), per-command flag sets, --json output structs.
internal/feature (or equivalent) manifest, receipt and requires types.
docs/agents/docs-map.md and the drift tests from #263 — keep green throughout.

Acceptance criteria

No stub remains in docs/api.md; each of the 24 listed routes has a full section.
Every route has exactly one section; no route's keys are described in more than one place except the shared preamble.
For a sample of at least ten routes chosen across page, element, media, publish and translation, the PR description shows the handler's marshalled type beside the documented keys and they match.
docs/harness.md lists every command the dispatcher accepts with its real flags; no "ten commands" wording.
docs/architecture.md is at most half the line count it had after #263 and contains no wire shapes.
docs/adr/ holds a record for each decision named in Current behavior, each dated and citing its commit.
Every claim corrected is listed in the PR description as "was: / now: / verified in: ".
docs/.docs-sync updated; go test ./... green including the #263 drift tests, scaffold/skills_test.go and internal/element/agentsdoc_test.go.

How to verify

go test ./... green.
For each sampled route: read the handler, list the marshalled struct's JSON tags, diff against the doc section.
harness --help-style usage output (run the binary) matches docs/harness.md's command table.
grep -rn 'ten commands' docs README.md is empty.
Cross-link test from #263 green after the restructuring.

Assumptions to check

That every error body a handler writes uses a code present in the catalog; an uncatalogued code is a bug to report, not to document.
That the moved host-navigation text matches what deckle-hosted actually sends — read the snapshot's host-navigation producer before touching even editorial wording.
That the originating commits listed above are the ones that made each decision; confirm with git log -S before dating an ADR.

Out of scope

Moving content between documents (done in #263); only edits within the documents #263 established, plus the ADRs.
Changing any server, CLI or host-navigation behaviour found to differ from the old prose — document the code as it is and file an issue for behaviour that looks wrong.
The scaffolded site skills and the theme README.
A docs-site generator.

Blocked by

#263

## Summary Make the documents #263 created *true and complete*: write the 24 route sections the API reference stubs, fix the stale claims the move carried over, condense the narrative to the depth each document's audience needs, and extract the design decisions into `docs/adr/`. #263 moved the content without rewording it; this issue is the content pass. ## Current behavior After #263 lands, `docs/` holds the README's former content verbatim, with these known defects carried over: - `docs/api.md` has stub headings for 24 routes that were never documented: `/api/element/body`, `/api/element/duplicate`, `/api/element/refs`, `/api/media/bundle`, `/api/media/delete`, `/api/media/folder/create`, `/api/media/folder/delete`, `/api/media/folder/delete-plan`, `/api/media/folder/move`, `/api/media/folder/rename`, `/api/media/info`, `/api/media/library`, `/api/media/move`, `/api/media/refs`, `/api/media/rename`, `/api/media/thumb`, `/api/media/tree`, `/api/media/upload`, `/api/page/create-root`, `/api/page/discard`, `/api/page/move`, `/api/page/refs`, `/api/page/reorder`, `/api/publish/status`. - The documented routes were written one feature at a time, each in the voice of its commit: the same route (`GET /api/page`, `POST /api/page/save`, `GET /api/tree`) is described in several places with different key lists (base shape in one paragraph, translation keys in "Translations on the wire", `enabled` in another, children digest in another). No section gives a route's full current response. - `docs/harness.md` inherited "The ten commands" (eleven lines, `version` missing) and prose written before later flags existed. - `docs/architecture.md` still carries rationale paragraphs that are decisions, not architecture: "Rich text, never raw HTML", "Media gate", "Publish is a background job", "Branch mode", "Branch-bundle page management", "Publish anyway", the host-navigation "Safety" reasoning, the bundle "requires" model replacing the standard flag (`78e181e`), the engine-written aliases being dropped (`e4d8138`). - `docs/adr/` is empty apart from its format README. - Sections may contradict the code: the README was never synced (no `docs:` commit since July); the `update-docs` skill's "verify against the current code, not the diff" rule has never been applied to it. ## Desired behavior - **`docs/api.md`**: every route has exactly one section, in a consistent shape — method and path, purpose in one sentence, request body (or query) with every key and its type, response with every key, the error codes it answers with (from the coded-error catalog), and language/translation behaviour where it applies. The scattered partial descriptions of a route are merged into its one section; cross-cutting behaviour (coded error bodies, `Accept-Language`, `lang` addressing, `translation` on page answers) is stated once in a preamble and linked. Every key named is verified against the handler and the Go types it marshals, not against the old prose. - **`docs/harness.md`**: every command's section matches `usage()` and the flag parsing in `cmd/harness`; exit codes and `--json` shapes verified against the code; "ten commands" is gone. - **`docs/host-navigation.md`**: unchanged in substance (it is a versioned contract); only broken cross-links and clearly editorial fixes. - **`docs/features.md`**: verified against `internal/feature` (or wherever bundles, receipts and `requires` resolution live) and the shipped bundles under `scaffold/`; condensed where the move left feature-by-feature repetition. - **`docs/architecture.md`**: a reader-ordered narrative (content model → sidecars → server → editor shell → git/publish → multilingual) at roughly a third of the moved length. Each decision paragraph becomes one sentence plus a link to its ADR. - **`docs/adr/`**: one record per decision listed above (and any other the agent finds that has a stated "why"), each with context, decision, consequences and the originating commit or issue. ADRs are records: write them from the rationale the README already stated, dated to the commit that made the decision, not reinvented. - **`scaffold/site/AGENTS.md`**: if any moved sidecar fact proves wrong against the engine during verification, fix it there (its drift test must stay green). - `docs/.docs-sync` updated to the new HEAD. ## Decisions - **Verify against code, not the diff or the old prose** — the old README was append-only and never synced; carrying its claims forward unverified would just relocate the drift. This is the `update-docs` skill's standing rule, applied for the first time. - **One section per route, merged** — the per-feature scatter is why nobody could read a route's full shape; the route drift test from #263 guarantees the heading set, this issue guarantees the content. - **ADRs are records, dated to their commit** — the `update-docs` skill forbids editing records to match new code; a record written now about a 2026-10-04 decision says so in its date and references the commit. - **Architecture is for orientation, not completeness** — a third of the length is a target, not a limit; the completeness lives in `docs/api.md` and `docs/harness.md`, which the drift tests cover. - **Host-navigation substance is frozen** — it is a contract with `deckle-hosted`; a substantive change is its own issue with a version bump. ## Key interfaces - `internal/server` handlers and the request/response structs they decode and marshal — the source of truth for every key in `docs/api.md`. - The coded-error catalog (`servermessages.json` / the `code` + `args` error body introduced in `1322a0c`) — the error-code vocabulary each route section cites. - `cmd/harness` `usage()`, per-command flag sets, `--json` output structs. - `internal/feature` (or equivalent) manifest, receipt and `requires` types. - `docs/agents/docs-map.md` and the drift tests from #263 — keep green throughout. ## Acceptance criteria - [ ] No stub remains in `docs/api.md`; each of the 24 listed routes has a full section. - [ ] Every route has exactly one section; no route's keys are described in more than one place except the shared preamble. - [ ] For a sample of at least ten routes chosen across page, element, media, publish and translation, the PR description shows the handler's marshalled type beside the documented keys and they match. - [ ] `docs/harness.md` lists every command the dispatcher accepts with its real flags; no "ten commands" wording. - [ ] `docs/architecture.md` is at most half the line count it had after #263 and contains no wire shapes. - [ ] `docs/adr/` holds a record for each decision named in Current behavior, each dated and citing its commit. - [ ] Every claim corrected is listed in the PR description as "was: / now: / verified in: <file or type>". - [ ] `docs/.docs-sync` updated; `go test ./...` green including the #263 drift tests, `scaffold/skills_test.go` and `internal/element/agentsdoc_test.go`. ## How to verify - `go test ./...` green. - For each sampled route: read the handler, list the marshalled struct's JSON tags, diff against the doc section. - `harness --help`-style usage output (run the binary) matches `docs/harness.md`'s command table. - `grep -rn 'ten commands' docs README.md` is empty. - Cross-link test from #263 green after the restructuring. ## Assumptions to check - That every error body a handler writes uses a code present in the catalog; an uncatalogued code is a bug to report, not to document. - That the moved host-navigation text matches what `deckle-hosted` actually sends — read the snapshot's host-navigation producer before touching even editorial wording. - That the originating commits listed above are the ones that made each decision; confirm with `git log -S` before dating an ADR. ## Out of scope - Moving content between documents (done in #263); only edits within the documents #263 established, plus the ADRs. - Changing any server, CLI or host-navigation behaviour found to differ from the old prose — document the code as it is and file an issue for behaviour that looks wrong. - The scaffolded site skills and the theme README. - A docs-site generator. ## Blocked by - #263

dominik.polakovics added the

enhancement

ready-for-agent

labels

2026-10-13 16:41:11 +02:00

dominik.polakovics referenced this issue

2026-10-13 16:41:18 +02:00

docs: split the root README into owned documents under docs/ and guard it with drift tests #263

dominik.polakovics referenced this issue

2026-10-13 17:02:13 +02:00

docs: split the root README into owned documents under docs/ and guard it with drift tests #266

dominik.polakovics referenced this issue from a commit