Development record
Install instructions need a getting-started page once more than one harness is supported, and the version floor needs a home in it. Raised at the itd-108 grill (2026-08-11) while ruling that no migration is owed to existing users, because there are none yet.
Install instructions need a getting-started page once more than one harness is supported, and the version floor needs a home in it. Raised at the itd-108 grill (2026-08-11) while ruling that no migration is owed to existing users, because there are none yet.
Two things have nowhere to live today. First, the archive plugin source itd-108 adopts requires a minimum harness version (v2.1.224 for the harness abcd ships hooks for); below it an install fails, and on older builds the whole marketplace fails to load. A README line is the minimum, but a floor stated only in a README ages badly and is invisible at the moment it bites. Second, abcd is host-agnostic by design and the install story is currently written for exactly one harness, so the moment a second is supported the instructions become a matrix — per-harness add command, per-harness version floor, per-harness plugin-root behaviour — and a single README section cannot carry it without becoming the change-narration docs-lint forbids.
Shape, not adopted: a Diataxis tutorial (getting started) distinct from the how-to and reference pages already under docs/, holding the install path end to end for each supported harness, with the version floor stated where the user meets it rather than in a footnote. Note the constraint that makes this awkward: user-facing prose is held host-agnostic by the harness/* docs-lint rules, and naming a harness is confined to attribution surfaces, so a per-harness install matrix needs either the docs-lint allow escape or a decision that install instructions are a sanctioned place to name a host. That decision is the real content of this issue and should be settled before the page is written, not after.
Remedy grounds (2026-09-29)
- Diataxis places the first end-to-end path in a tutorial and keeps how-to guides for 'the already-competent user' (https://diataxis.fr/how-to-guides/, consulted 2026-09-29); the AGENTS.md steward's own page carries per-tool configuration lines only for the tools that need one (https://agents.md/, consulted 2026-09-29), precedent for a single named-tool table rather than tool names spread through the prose.
- Rejected: a README section, which the record already shows ageing into the change narration docs-lint forbids.
Frontmatter
| id | iss-216 |
|---|---|
| type | issue |
| lifecycle | open |
| severity | minor |
.abcd/work/issues/open/iss-216-install-instructions-need-a-getting.md
open on GitHub ↗ · commit history ↗
mentions4
- dcn-26082000000000022026-08-20 — bughunt round 2 (branch bughunt-b/round-2): captured the round-2 records (iss-346..iss-357, with the two colliding ids re-minted as iss-358/iss-359), fixed
- iss-2608271711530571docs/README.md advertises tutorials/ as a populated Diataxis home while the directory holds only a 6-line README and zero content pages. Until the iss-216 getting-started page lands (the real close), the table row overstates the tree: mark the tutorials row as not yet populated and name iss-216 so a reader is not routed to an empty home.
- iss-2608271711539855the docs-lint harness rules miss bare host-name tokens in paths and env vars: docs/how-to/install.md names the host harness twice in hand-written prose — a .claude-plugin/ directory link and the $CLAUDE_PLUGIN_DATA cache variable — with no docs-lint finding and no sanctioned allow escape. Fix the detector first: widen the harness/claude-code pattern in .abcd/docs-lint.json so a product-name token inside a path or env var is caught, and watch it fire on both install.md sites before deciding the prose remedy. Whether install pages get a per-line allow marker is already an open decision on iss-216 — do not pre-empt it here.
- itd-108The plugin installs from the curated release artifact, not the repo, and every cut release reaches users automatically