docs/ has no index or table of contents for its 92 files; the sole link that could serve as one (AGENTS.md's docs/README.md) is dead

coilyco-ops commented

2026-07-01 23:11:03 +00:00

Member

Why

Persona: the-agent-itself, angle docs-ia. docs/ contains 92 markdown files. Grepped the tree for anything that could serve as a landing page - index.md, toc.md, docs/README.md - none exist (docs/README.md 404s; this is #429's finding, but that issue frames it as one broken link, not the underlying gap). A reader who opens the docs/ directory on the Forgejo web UI (or via the contents API) sees a flat, alphabetically-sorted list of 92 filenames with no descriptions, no grouping beyond whatever a reader infers from filename prefixes (agent-*, container-*, ward-kdl*), and no page that says "start here."

Every persona in this sweep that has gone deep on docs-ia so far has effectively built their own path by starting from README/FEATURES.md/AGENTS.md and following outbound links - none of them discovered a path by browsing docs/ itself, because there is nothing there to browse toward. Fixing #429's dead link narrowly (pointing it at an existing page like FEATURES.md) would satisfy that issue without ever producing an actual index for the 92 files.

Deliverable

A real docs/README.md (or docs/index.md) that groups the 92 files by subsystem (agent/harness docs, container docs, ward-kdl/config docs, ops docs, release/CI docs) with one-line descriptions, serving as the landing page AGENTS.md already assumes exists. Link it from README, AGENTS.md, and FEATURES.md.

Done condition

Opening docs/ (web UI or a fresh clone) leads to one page that orients a reader across the full doc set, not a bare alphabetical file listing.

Severity: major-friction · persona: the-agent-itself · angle: docs-ia
Filed by Claude Code during a cold-read release pressure test (run 24). Related: #429 (the specific dead link this issue is the underlying fix for).

## Why Persona: `the-agent-itself`, angle `docs-ia`. `docs/` contains 92 markdown files. Grepped the tree for anything that could serve as a landing page - `index.md`, `toc.md`, `docs/README.md` - none exist (`docs/README.md` 404s; this is #429's finding, but that issue frames it as one broken link, not the underlying gap). A reader who opens the `docs/` directory on the Forgejo web UI (or via the contents API) sees a flat, alphabetically-sorted list of 92 filenames with no descriptions, no grouping beyond whatever a reader infers from filename prefixes (`agent-*`, `container-*`, `ward-kdl*`), and no page that says "start here." Every persona in this sweep that has gone deep on docs-ia so far has effectively built their own path by starting from README/FEATURES.md/AGENTS.md and following outbound links - none of them discovered a path by browsing docs/ itself, because there is nothing there to browse toward. Fixing #429's dead link narrowly (pointing it at an existing page like FEATURES.md) would satisfy that issue without ever producing an actual index for the 92 files. ## Deliverable A real `docs/README.md` (or `docs/index.md`) that groups the 92 files by subsystem (agent/harness docs, container docs, ward-kdl/config docs, ops docs, release/CI docs) with one-line descriptions, serving as the landing page AGENTS.md already assumes exists. Link it from README, AGENTS.md, and FEATURES.md. ## Done condition Opening docs/ (web UI or a fresh clone) leads to one page that orients a reader across the full doc set, not a bare alphabetical file listing. --- **Severity: major-friction** · persona: the-agent-itself · angle: docs-ia Filed by Claude Code during a cold-read release pressure test (run 24). Related: #429 (the specific dead link this issue is the underlying fix for).

coilyco-ops added the

pressure-test

label

2026-07-01 23:11:03 +00:00

coilyco-ops referenced this issue

2026-07-01 23:11:21 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:20 +00:00

coilyco-ops added the

headless

P1

labels

2026-07-01 23:30:19 +00:00

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 02:31:20 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-488 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:31:17Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-488` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:31:17Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 02:43:08 +00:00

docs(index): add docs/ landing page grouping all docs by subsystem

coilysiren closed this issue

2026-07-02 02:43:08 +00:00

coilysiren commented

2026-07-02 02:43:54 +00:00

Owner

WARD-OUTCOME: done - added docs/README.md, a real index grouping all docs by subsystem, linked from the README/AGENTS/FEATURES trifecta.

The core work was straightforward and satisfying: the docs already carried clean H1s and lead paragraphs, so building an honest grouped index with one-line descriptions was mostly reading and organizing. I listed every flat docs/*.md and folded the 24 generated ward-kdl/ guardfile refs behind a pointer to ward-kdl-surface.md rather than dumping them, then wrote a check that diffed the linked set against the real tree to prove nothing was orphaned.

Two things fought back, both about the caps rather than the content. First, an index of the whole doc set can't fit the 80-line/4000-char documentation-layout cap by construction, so it needed the same "grows with the surface" exclude the generated docs already carry - dead-cross-links still validates every entry, which is the guard that actually matters. Second, and more annoying: the pinned v0.65.0 hook enforces a flat 4000-char cap on the trifecta files, and AGENTS.md/FEATURES.md were sitting just under it - my one See-also link tipped both over. I paid it back with small concision trims rather than adding new excludes, since those two files fit fine minus a few redundant words.

The run also collided with live traffic: main moved three times while I worked, and one of those landings retired ward ci watch, which deleted docs/ci-watch.md out from under my fresh index link. Git merged clean (no textual conflict) but the dead link was a content-level break only pre-commit caught - a good reminder that a clean merge isn't a clean tree. Re-integrated, dropped the entry, pushed.

Confident in the result: full suite green on the merged tree, every link resolves, main is at my HEAD. One honest rough edge worth a follow-up (ward#427 already tracks the root cause): the trifecta files are chronically pressed against the stale flat cap, so the next See-also addition to AGENTS.md or FEATURES.md will hit the same wall until the hook pin advances to the release with the per-file opt-up.

WARD-OUTCOME: done - added docs/README.md, a real index grouping all docs by subsystem, linked from the README/AGENTS/FEATURES trifecta. The core work was straightforward and satisfying: the docs already carried clean H1s and lead paragraphs, so building an honest grouped index with one-line descriptions was mostly reading and organizing. I listed every flat docs/*.md and folded the 24 generated ward-kdl/ guardfile refs behind a pointer to ward-kdl-surface.md rather than dumping them, then wrote a check that diffed the linked set against the real tree to prove nothing was orphaned. Two things fought back, both about the caps rather than the content. First, an index of the whole doc set can't fit the 80-line/4000-char documentation-layout cap by construction, so it needed the same "grows with the surface" exclude the generated docs already carry - dead-cross-links still validates every entry, which is the guard that actually matters. Second, and more annoying: the pinned v0.65.0 hook enforces a flat 4000-char cap on the trifecta files, and AGENTS.md/FEATURES.md were sitting just under it - my one See-also link tipped both over. I paid it back with small concision trims rather than adding new excludes, since those two files fit fine minus a few redundant words. The run also collided with live traffic: main moved three times while I worked, and one of those landings retired `ward ci watch`, which deleted docs/ci-watch.md out from under my fresh index link. Git merged clean (no textual conflict) but the dead link was a content-level break only pre-commit caught - a good reminder that a clean merge isn't a clean tree. Re-integrated, dropped the entry, pushed. Confident in the result: full suite green on the merged tree, every link resolves, main is at my HEAD. One honest rough edge worth a follow-up (ward#427 already tracks the root cause): the trifecta files are chronically pressed against the stale flat cap, so the next See-also addition to AGENTS.md or FEATURES.md will hit the same wall until the hook pin advances to the release with the per-file opt-up.

coilysiren referenced this issue

2026-07-02 02:45:45 +00:00

advance the aos documentation-layout pin so the per-file caps bind (post-#427), narrow the README exclude #500

coilysiren referenced this issue

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

docs/ has no index or table of contents for its 92 files; the sole link that could serve as one (AGENTS.md's docs/README.md) is dead #488

Why

Deliverable

Done condition