coilyco-flight-deck/ward

Fork 0

AGENTS.md links to a nonexistent docs/README.md #429

New issue

Closed

opened 2026-07-01 21:32:50 +00:00 by coilyco-ops · 4 comments

coilyco-ops commented

2026-07-01 21:32:50 +00:00

Member

Why

A cold reader following the agent-facing entry points gets sent to [docs/README.md](README.md) from AGENTS.md, but there is no docs/README.md in the public tree. That makes the "see also" path dead the moment an agent tries to use it as a starting point.

Deliverable

Replace the broken reference with a real doc or remove it from the public agent instructions and point to an existing entry point instead.

Done condition

Every link in the agent instructions resolves on the public tree, and a newcomer can follow the listed "See also" path without hitting a 404 or missing file.

Severity: major-friction · persona: agent-legibility · angle: docs-ia
Filed by Codex during a cold-read release pressure test (run 3).

## Why A cold reader following the agent-facing entry points gets sent to `[docs/README.md](README.md)` from `AGENTS.md`, but there is no `docs/README.md` in the public tree. That makes the "see also" path dead the moment an agent tries to use it as a starting point. ## Deliverable Replace the broken reference with a real doc or remove it from the public agent instructions and point to an existing entry point instead. ## Done condition Every link in the agent instructions resolves on the public tree, and a newcomer can follow the listed "See also" path without hitting a 404 or missing file. --- **Severity: major-friction** · persona: agent-legibility · angle: docs-ia Filed by Codex during a cold-read release pressure test (run 3).

coilyco-ops added the

pressure-test

label

2026-07-01 21:32:50 +00:00

coilysiren commented

2026-07-01 21:33:53 +00:00

Owner

simple dead links linter would solve this

coilyco-ops referenced this issue

2026-07-01 21:47:35 +00:00

polish batch, run 2: yaml-config #439

coilyco-ops commented

2026-07-01 21:51:35 +00:00

Author

Member

+1 — independently hit via agent-legibility/docs-ia, run 8.

coilyco-ops referenced this issue

2026-07-01 21:51:59 +00:00

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

coilyco-ops commented

2026-07-01 22:22:44 +00:00

Author

Member

+1 — independently hit via forgejo-selfhoster/agent-legibility, this run. AGENTS.md points at docs/README.md but the repo has no such page, so the onboarding trail has a dead link.

coilyco-ops referenced this issue

2026-07-01 22:24:36 +00:00

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

coilyco-ops referenced this issue

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

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

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:44 +00:00

coilyco-ops added the

headless

labels

2026-07-01 23:30:34 +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

coilysiren commented

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

Owner

Verification close from the ward#492 burndown director: ward#488 landed docs/README.md on main (b7271cb + 0804349, the by-subsystem docs index), and AGENTS.md line 67 now links it as a live target. dead-cross-links runs clean on the landed tree, so the dead link this issue reported no longer exists. Closing via the issue API rather than an empty commit, same pattern as #462. Recorded by Claude Code (Fable) during the ward#492 burndown session.

Verification close from the ward#492 burndown director: ward#488 landed docs/README.md on main (`b7271cb` + `0804349`, the by-subsystem docs index), and AGENTS.md line 67 now links it as a live target. dead-cross-links runs clean on the landed tree, so the dead link this issue reported no longer exists. Closing via the issue API rather than an empty commit, same pattern as #462. Recorded by Claude Code (Fable) during the ward#492 burndown session.

coilysiren closed this issue

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