docs: correct and condense the moved docs, write the missing API route sections, extract ADRs

dominik.polakovics commented

2026-10-13 16:42:45 +02:00

Owner

Follow-up to #263 (referred to there as #ISSUE2).

#263 split the root README into owned documents under docs/ as a pure move: content changed location, not wording. This issue does the rewriting that was deliberately left out:

Write the missing route sections in docs/api.md. Every route registered by the server has a heading there (the route drift test enforces it), but the routes that were never documented before carry only a stub pointing at this issue. Each gets its request and response shape, written from the handler as it is now.
Reshape the moved API material per route. Wire-shape prose that was moved verbatim and spans several routes (forms, translations on the wire, publish) is split so each route's heading carries its own request/response shape.
Correct and condense the moved prose in docs/architecture.md, docs/harness.md, docs/features.md and docs/api.md: fix wrong or stale statements, drop repetition that the owning document already carries (see docs/agents/docs-map.md).
Extract ADRs from the "why" paragraphs (e.g. rich text never raw HTML, publish as a background job, branch mode, media gate) into docs/adr/ in the format docs/adr/README.md states, leaving a link where the rationale was.

Out of scope: the host-navigation contract (docs/host-navigation.md) is versioned; rewording it is a contract change.

Follow-up to #263 (referred to there as #ISSUE2). #263 split the root README into owned documents under `docs/` as a **pure move**: content changed location, not wording. This issue does the rewriting that was deliberately left out: - **Write the missing route sections in `docs/api.md`.** Every route registered by the server has a heading there (the route drift test enforces it), but the routes that were never documented before carry only a stub pointing at this issue. Each gets its request and response shape, written from the handler as it is now. - **Reshape the moved API material per route.** Wire-shape prose that was moved verbatim and spans several routes (forms, translations on the wire, publish) is split so each route's heading carries its own request/response shape. - **Correct and condense the moved prose** in `docs/architecture.md`, `docs/harness.md`, `docs/features.md` and `docs/api.md`: fix wrong or stale statements, drop repetition that the owning document already carries (see `docs/agents/docs-map.md`). - **Extract ADRs** from the "why" paragraphs (e.g. rich text never raw HTML, publish as a background job, branch mode, media gate) into `docs/adr/` in the format `docs/adr/README.md` states, leaving a link where the rationale was. Out of scope: the host-navigation contract (`docs/host-navigation.md`) is versioned; rewording it is a contract change.

dominik.polakovics added the

needs-triage

enhancement

labels

2026-10-13 16:42:45 +02:00

dominik.polakovics referenced this issue from a commit

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

docs: split the root README into owned documents under docs/ and guard it

dominik.polakovics referenced this issue

2026-10-13 16:55:15 +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 pull request that will close it,

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

2026-10-13 19:40:49 +02:00

docs: point the route stubs at #264 and read sections through mddoc

dominik.polakovics commented

2026-10-13 19:40:55 +02:00

Author

Owner

Closing as a duplicate of #264, the maintainer's follow-up that #263 names in its acceptance criteria. PR #266's route stubs and its drift test now point at #264; nothing references this issue any more.

dominik.polakovics closed this issue

2026-10-13 19:40:55 +02:00

dominik.polakovics referenced this issue

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

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

dominik.polakovics referenced this issue

2026-10-13 19:45:59 +02:00

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

Rows
Columns

docs: correct and condense the moved docs, write the missing API route sections, extract ADRs #265