docs: split the command table into an index and a reference

[eschizoid]

Closes part of #365 (P6).

The Commands table was doing two jobs at once. Someone scanning "what can this thing do" needs one line per command; someone debugging "why didn't my session group with the others" needs the anchor-matching rules. Both were living in the same cell — the worst at 1110 characters, which ended by pointing at Metrics.anchor_filter for the exact rules it had just spent a paragraph restating.

A table is a lookup structure. When the answer needs a paragraph, the reader is not looking anything up any more.

What changed

README.md keeps the index — 32 rows, one line each, worst cell 75 characters against 1110 before. docs/commands.md takes the detail, grouped as the README groups it.

What review caught

Two agents reviewed this: one checking every claim against the running binary, one attacking the guard claim below. Both found real defects, which are fixed in 15aec1b. The ones worth naming:

• plan said "14d outlook". The window is the last 14 days — Plan.roc computes anchor - 13, the payload field is recent_activities_14d. The text I was moving verbatim had it right and my one-line summary inverted it.
• top listed four of seven metrics, skipping over intensity to reach distance — so it read as the complete set rather than a truncation, and three metrics became undiscoverable from the index.
• ## Coaching log was an empty heading at the end of the file. Every coaching command sat under "Reading your training", so relabel was filed as a reading command and the section the README pointed at contained nothing.
• The claim "stride --help is the authoritative list ... generated from the parser, so it cannot drift" was false. The human help is a hand-maintained string literal in app.roc, and it had already drifted: it omitted config unset, which the parser accepts and the JSON help lists. So the README documented a command its own stated oracle did not mention. The claim is now scoped to the machine form, which genuinely is generated, and the literal has the missing line.

The guard claim, corrected

I originally wrote that this file is "guarded by construction" because every command is written stride <cmd>. That is not defensible as written. An adversarial pass found the honest scope:

Every command name written as a backticked `stride <cmd>` is resolved against the binary's own table, so the 31 headings cannot name a command or subcommand that does not exist. Within that shape the gate is strong — headings, prose, tables, links, emphasis, both fence dialects, any indentation, and every slot of a compound heading.

Outside it, the gate does not check: arguments (stride tte with the required <watts> omitted passes), any third token, any flag, bracketed argument syntax at all, or a capitalised name — stride Frobnicate passes silently, with no output and no counter movement. Its corpus floors are also global rather than per-file, so docs/commands.md can lose every one of its references, or be deleted outright, and the gate stays green.

So this file's coverage is a convention the gate rewards, not an invariant it enforces. Two narrower fixes did land: the alias claims are now written (alias stride pz) so they are checked, and breaking one is confirmed to fail the gate by name.

Worth a follow-up issue, not this PR: the unparsed-line counter can be satisfied by an unrelated wording change elsewhere in the same commit, which lets an unbackticked bogus command through — and help_text has no gate asserting it mentions every Command.specs name, which is what let config unset go missing in the first place.

Verification

BUILD rc=0, SUITE rc=0 (1111 == 1111), four gates rc=0. Coverage verified both directions: all 38 commands in commands.json appear in the index, and nothing named is invented.

One note for whoever edits the table next: column widths are computed on character width, not byte width. macOS awk counts length() in bytes, so an em dash silently shifts a row by two — the same trap command-claims.sh documents in its own header.

[Copilot]

🟡 Changes recommended

The new docs/commands.md has a misplaced/duplicate “Coaching log” section header, and the README index row for config omits the documented utc_offset_minutes fallback.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR restructures command documentation by turning the README “Commands” table into a concise index and moving full per-command semantics into a dedicated reference doc, improving scanability while keeping detailed behavior documented.

Changes:

• Replaces the README command table’s long descriptions with short, one-line index entries and adds a pointer to the full reference.
• Adds docs/commands.md as a per-command reference document containing the detailed descriptions previously embedded in the README.

File summaries

File	Description
README.md	Converts the Commands section into a short index and links to the full command reference.
docs/commands.md	Introduces a detailed, per-command reference document (new file).

Review details

Suppressed comments (1)

docs/commands.md:147

• After moving the “Coaching log” header above the coaching commands, the trailing “## Coaching log / The adaptation loop.” block at the end becomes duplicate and should be removed to avoid an empty section footer.

## Coaching log

The adaptation loop.

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The new reference doc has structural inconsistencies (misplaced/dangling “Coaching log” heading) and omits at least one callable command form (stride config), which undermines the stated goal of a complete per-command reference.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

docs/commands.md:122

• docs/commands.md places the "Coaching log" heading at the very end of the file, after all the coaching commands, so the coaching section currently has no heading where it starts and ends with a dangling header.

### `stride week add <date> <type> <detail> <rationale> [target]`

docs/commands.md:148

• The file ends with a second "## Coaching log" header (and "The adaptation loop.") after the last command description, which reads like leftover text and makes the section structure confusing.

## Coaching log

The adaptation loop.

README.md:256

• progress's synopsis currently shows [asc\|desc] in inline code, which renders with a backslash in the README table. Use a pipe-free spelling so the rendered synopsis stays clean.

| `progress [date] [asc\|desc]`             | trend on a repeated workout, sport-aware lens             |

• Files reviewed: 2/2 changed files
• Comments generated: 5
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

A few newly added documentation claims/signatures are objectively inaccurate or inconsistent with the code (notably “generated from the parser” phrasing and the skip signature), and should be corrected before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

docs/commands.md:61

• There’s a duplicated “Each answers a different question.” line: it appears once before the section header and again immediately after it. Dropping the pre-header copy keeps the structure clean and avoids accidental drift if one copy is edited later.

This issue also appears on line 158 of the same file.

docs/commands.md:160

• The header for skip doesn’t mention the supported none sentinel, but the CLI accepts [activity_id|none] (and the section text below relies on it). Updating the signature here avoids readers thinking none is an undocumented extra.

### `stride skip <id> <reason> [activity_id]`

Marks a planned session skipped, with the reason — optionally linking the activity done instead (rendered `→ id` in `week`). Adherence history stays honest either way; a bare re-skip keeps an existing link; pass a new id to change it or `none` to release it. A done session refuses skip — re-complete to fix a mis-link.

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Several new documentation statements are inaccurate or duplicated (notably the “generated from the parser” claim and repeated sentences), and should be corrected before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

README.md:219

• The README says STRIDE_FORMAT=json stride --help is “generated from the parser”, but the JSON help payload is emitted from Command.specs (and Command.specs is explicitly documented as hand-written + cross-checked, not generated). This wording overstates the guarantee and is inaccurate (see src/app.roc:205-207 and src/Command.roc:288-289).

Full detail for every command — grouping rules, matching semantics, output
shapes — lives in **[docs/commands.md](docs/commands.md)**.
`STRIDE_FORMAT=json stride --help` is generated from the parser and is the
authoritative list; this table is the index.

docs/commands.md:7

• This claim is not accurate: STRIDE_FORMAT=json stride --help is not “generated from the parser”. The JSON help payload is emitted from Command.specs, and Command.specs is documented as hand-written + cross-checked rather than generated (src/app.roc:205-207, src/Command.roc:288-289). Consider rewording to match what is actually enforced.

`STRIDE_FORMAT=json stride --help` is generated from the parser, so its list of
commands and arguments cannot drift. This file explains what they *mean*.

docs/commands.md:176

• The document ends with a duplicate “The adaptation loop.” footer even though the Coaching log section already introduces itself with the same sentence. Dropping this trailing line avoids accidental copy/paste leftovers.

The adaptation loop.

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The changes are documentation-focused and the only issues found are minor duplicated lines in the new reference doc with straightforward fixes.

Review details

Suppressed comments (1)

docs/commands.md:61

• The line "Each answers a different question." is duplicated immediately before and after the "Reading your training" section header; keeping only one avoids accidental drift and reads cleaner.

Each answers a different question.

## Reading your training

Each answers a different question.

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

There are a few concrete documentation/UX inconsistencies (duplicate sentences, a mismatched skip signature, and an inaccurate config get|set help line) that should be corrected before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

src/app.roc:82

• The help text shows config get|set <key> [value], but the parser requires a value for config set (and config get does not accept one). This can mislead users and contradicts the usage strings produced elsewhere.

        \\    config                      list the config that is set (secrets redacted)
        \\    config get|set <key> [value]   read or write one key (hr zone bounds, timezone)
        \\    config unset <key>          remove a key outright
        \\                                — FTP is derived, never set

docs/commands.md:61

• The sentence “Each answers a different question.” appears twice in a row here (once before and once after the section header), which reads like an accidental duplication.

Each answers a different question.

## Reading your training

Each answers a different question.

docs/commands.md:175

• The file ends with a second standalone “The adaptation loop.” sentence (already stated at the start of the Coaching log section), which looks like an accidental duplicate footer.

The adaptation loop.

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The changes are documentation-focused and the only findings are minor redundancy nits in the new reference file.

Review details

Suppressed comments (2)

docs/commands.md:61

• This sentence is duplicated immediately before and after the section header, which reads like an accidental copy/paste and adds noise to the reference page. Consider keeping it only once under the "Reading your training" heading.

Each answers a different question.

## Reading your training

Each answers a different question.

docs/commands.md:175

• This closing sentence repeats the section intro at line 140 ("The adaptation loop.") and doesn’t add new information at the end of the document. Removing it will keep the reference tighter.

The adaptation loop.

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

A few newly added/edited documentation/help lines overstate guarantees or have minor command-form mismatches that should be corrected for accuracy and consistency.

Review details

Suppressed comments (6)

Previously missed (1) — in code that hasn't changed since the last review.

README.md:251

• The README notes that STRIDE_FORMAT=json stride --help is the authoritative list and earlier text explains the command-claims gate only validates backticked stride <cmd> forms. Writing the alias as pz here leaves it unverified by that gate; using stride pz keeps the alias claim checkable.

This issue also appears on line 254 of the same file.

src/app.roc:82

• The help text implies config set's value is optional ([value]), but the parser requires a value for config set and supports config unset as a separate form (see Command.parse / usage string). This can mislead users and tools that rely on the human help output.

        \\    config                      list the config that is set (secrets redacted)
        \\    config get|set <key> [value]   read or write one key (hr zone bounds, timezone)
        \\    config unset <key>          remove a key outright
        \\                                — FTP is derived, never set

README.md:219

• This claims the JSON help is “generated from the parser”, but the implementation emits commands.json from Command.specs (an explicit command table). Suggest rephrasing to avoid implying it is mechanically derived from Command.parse / impossible to drift.

`STRIDE_FORMAT=json stride --help` is generated from the parser and is the
authoritative list; this table is the index.

README.md:255

• Same as the pz alias above: writing these aliases without the stride prefix leaves them outside the command-claims check for backticked stride <cmd> forms.

| `power-curve [days] [sport]` (alias `pc`) | power-duration curve + Critical Power                       |
| `pace-curve [days] [sport]` (alias `cs`)  | speed-duration curve + Critical Speed; name a sport         |

docs/commands.md:156

• The heading omits the documented/implemented none literal for releasing an existing activity link; Command.parse/usage uses [activity_id|none] and the paragraph below already mentions none. The command form in the heading should match.

### `stride skip <id> <reason> [activity_id]`

docs/commands.md:7

• This claims STRIDE_FORMAT=json stride --help is “generated from the parser” and “cannot drift”, but the binary builds the help payload from Command.specs (a maintained command table). Rephrase to avoid overstating the guarantee.

`STRIDE_FORMAT=json stride --help` is generated from the parser, so its list of
commands and arguments cannot drift. This file explains what they *mean*.

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite