docs(coding-agents): generate the companion skill from the README (#3735) (#3753)
The skill and the README documented the same configuration in two hand- maintained files, and they drifted in both directions. The skill never named `bankIdTemplate`, `dynamicBankId`, `optInOnly`, `optInPaths`, `retainTags`, `retainMetadata`, `resolveWorktrees`, `maxParallelRetains` or any daemon setting, and it stated outright that the package reads "no environment variables" — there are 35 (core/config.ts ENV_KEYS). That is the half #3735 reported. The README had lost the other half: `autoReflect` and `surveyRefreshCommits` were documented only in the skill, and neither file mentioned that `HINDSIGHT_CONFIG` relocates the config file, that the layering chain ends at `banks.<resolvedBankId>`, or that `optInPaths` takes a comma-separated env value like its sibling `retainTags`. The README is now the single source. scripts/build-skill.mjs copies the regions it marks with `skill:begin` / `skill:end` into skill/SKILL.md, normalising heading levels per region; only the agent-facing half — which tools to call, crediting memory, correcting a stale memory — stays separate, in skill-src/preamble.md. The docs page was already generated from the README; its generator now strips the markers, which MDX cannot parse. The skill's operative debugging knowledge (sync-status readiness, resetting a bank, the survey-baseline/gitlog marker documents, the session_start/deepen_started triage rule) moved into the README, so it reaches users and the docs site too. src/docs-freshness.test.ts fails when the skill is stale, when a field of `RawConfig` is readable from a config file but named nowhere in the README — the check that makes this class of drift impossible to reintroduce — and when a documented claim about the env layer stops holding (every key really is `HINDSIGHT_<FIELD_IN_CAPS>`; the four map-valued settings really are file-only). It also unit-tests the marker parser. prepublishOnly regenerates the skill so a publish cannot ship a stale copy.
N
Nicolò Boschi committed
1b74e3efa8a28ec564c5b04b617596f07f09d8c0
Parent: 8667598
Committed by GitHub <noreply@github.com>
on 8/24/2026, 9:06:28 AM