iterative-works/iw-cli

Watch

Fork 0

llms.txt links every module page as docs/<Module>.md, but the pages live in docs/api/ #543

New issue

Open

opened 2026-09-11 18:18:16 +00:00 by mph · 4 comments

mph commented

2026-09-11 18:18:16 +00:00

Owner

llms.txt links every module page as docs/<Module>.md, but the pages live in docs/api/<Module>.md. So the links in the index an agent reads first lead nowhere.

Evidence

Counted on main at ba6cc9f9:

Links of the form ](docs/…) in llms.txt: 43
Links that resolve as written: 0
Links that resolve once docs/ becomes docs/api/: 43
Links that resolve neither way: 0

For example, - [GitWorktree](docs/GitWorktree.md) points to a missing file; the page is docs/api/GitWorktree.md.

Relation to #440

#440 covers modules that have no page at all. This issue is about the links to pages that do exist. #440 also says "a link to a docs/<Module>.md that does not exist is worse than no line" — with the paths as they are now, that already describes almost every line in the index.

Fix

Rewrite the links to docs/api/<Module>.md, or move the pages to where the links point. Pick one location and use it everywhere.
Have the build-iw-cli-skills check (see #440) confirm that every llms.txt link resolves, so the paths cannot drift apart again.

Type: bug
Found while: adding the ZvecGrepIndexSetup and WorktreeSearchIndex entries on branch wip/zg-index-setup

`llms.txt` links every module page as `docs/<Module>.md`, but the pages live in `docs/api/<Module>.md`. So the links in the index an agent reads first lead nowhere. ## Evidence Counted on `main` at `ba6cc9f9`: - Links of the form `](docs/…)` in `llms.txt`: **43** - Links that resolve as written: **0** - Links that resolve once `docs/` becomes `docs/api/`: **43** - Links that resolve neither way: **0** For example, `- [GitWorktree](docs/GitWorktree.md)` points to a missing file; the page is `docs/api/GitWorktree.md`. ## Relation to #440 #440 covers modules that have no page at all. This issue is about the links to pages that *do* exist. #440 also says "a link to a `docs/<Module>.md` that does not exist is worse than no line" — with the paths as they are now, that already describes almost every line in the index. ## Fix - Rewrite the links to `docs/api/<Module>.md`, or move the pages to where the links point. Pick one location and use it everywhere. - Have the `build-iw-cli-skills` check (see #440) confirm that every `llms.txt` link resolves, so the paths cannot drift apart again. --- **Type:** bug **Found while:** adding the `ZvecGrepIndexSetup` and `WorktreeSearchIndex` entries on branch `wip/zg-index-setup`

claude added the

agent-ready

label

2026-09-15 01:37:33 +00:00

claude commented

2026-09-15 01:37:33 +00:00

Member

Intake: agent-ready
Workflow: diagnostic
Reason: all gates passed
Analysis: project-management/issues/IW-543/analysis.md on branch IW-543

Intake: agent-ready Workflow: diagnostic Reason: all gates passed Analysis: project-management/issues/IW-543/analysis.md on branch IW-543

claude removed the

agent-ready

label

2026-09-25 21:51:41 +00:00

claude commented

2026-10-15 21:54:30 +00:00

Member

Intake: agent-ready
Workflow: diagnostic
Reason: all gates passed
Analysis: project-management/issues/IW-543/analysis.md on branch IW-543

Intake: agent-ready Workflow: diagnostic Reason: all gates passed Analysis: project-management/issues/IW-543/analysis.md on branch IW-543

claude added the

agent-ready

label

2026-10-15 21:54:30 +00:00

claude commented

2026-10-15 22:01:50 +00:00

Member

[warn]  Using directives detected in multiple files:
- /home/mph/.local/share/iw/plugins/kanon/lib/deps.scala:1:1-7:41
It is recommended to keep them centralized in the /home/mph/Devel/iw/iw-cli-IW-543/core/project.scala file.

[error] /home/mph/.local/share/iw/plugins/kanon/lib/batch/ForgeCatchUp.scala:143:7
[error] Found:    Either[iw.core.model.TrackerError, Option[batch.ForgeState]]
[error] Required: Either[String, Option[batch.ForgeState]]
Compilation failed

Implement: needs-human Reason: batch-implement exit 1 — the kanon plugin does not compile against the iw-cli core of this branch: ForgeCatchUp.scala:143 expects Either[String, _] from fetchPullRequestForBranch, and core now returns Either[TrackerError, _] (#778). No phase ran, and batch-implement.log was not written. The lines below are the output of the command. ``` [warn] Using directives detected in multiple files: - /home/mph/.local/share/iw/plugins/kanon/lib/deps.scala:1:1-7:41 It is recommended to keep them centralized in the /home/mph/Devel/iw/iw-cli-IW-543/core/project.scala file. [error] /home/mph/.local/share/iw/plugins/kanon/lib/batch/ForgeCatchUp.scala:143:7 [error] Found: Either[iw.core.model.TrackerError, Option[batch.ForgeState]] [error] Required: Either[String, Option[batch.ForgeState]] Compilation failed ```

claude added

needs-human

and removed

agent-ready

labels

2026-10-15 22:01:50 +00:00

claude commented

2026-10-16 17:10:35 +00:00

Member

Release: the implement loop failed this issue for a reason outside it. The kanon plugin did not compile against iw-cli main, because the tracker port now returns TrackerError (iw-cli #778). The plugin fix is dev-docs #484, and iw-cli 0.22.1 carries the core change. The issue goes back to the implement loop.

claude added

agent-ready

and removed

needs-human

labels

2026-10-16 17:10:35 +00:00