docs: lean AGENTS.md to rules, fix the install sentence, and retire comments naming deleted workflows and paths

[Vivswan]

Before / After

Where	Before	After
README.md, Library	npm install @vivswan/github-settings-as-code "installs the released version"; npm latest is the 0.0.0 placeholder	Ask for the next tag until the first stable release, as docs/start/cli.md already says
docs/reference/library.md, Install and Versioning	The bare install comment says "the released version"; the latest row says it names a next pre-release until the first release	Both say latest is the 0.0.0 placeholder until the first stable release and ask for @next until then
AGENTS.md	Seven bullets restate mechanics CONTRIBUTING.md or the code carries	Each bullet keeps its rule; the intro points at CONTRIBUTING.md for the mechanics
test/e2e/runner.ts, runner.test.ts	The parity pin is a unit test "because the e2e job skipped on a package.json-only diff" (that selector is gone)	The pin is a unit test because it is the binding assertion, failing by name; builtBundle() checks the same pin only as a fast local signal that aborts the whole e2e run
test/e2e/generators.ts	sections: "a smoke or PR-diff subset"	"the --sections flag; the default is every registered section"
src/sections/webhooks/events.ts	Header names test/sections/webhooks-events.test.ts	Names test/sections/webhooks/events.test.ts, where the test lives
.github/scripts/release-pipeline.ts, .github/workflows/update-release.yml	The stable-publish verdict's comments say latest names a pre-release until the first release	They say latest names the first publish (the 0.0.0 placeholder, or a pre-release) until a release takes it over; the verdict itself already handles both
.github/workflows/auto-fix.yml	Two comments name a dependabot-bun-lockfile.yml workflow that exists nowhere	The header row says a bun.lock the Bun updater left stale fails the frozen install, a close/reopen re-runs it against the same lockfile, and only a push with a real token brings a fresh one; the push-step comment keeps the Dependabot-rebase case

How

Prose and comments only; no behavior changes.
AGENTS.md is the single source (CLAUDE.md, .github/copilot-instructions.md, .github/agents.md are symlinks) and is edited below the END marker only.
CONTRIBUTING.md is untouched: every dropped clause already lives there, or in the code, once.

Dropped AGENTS.md clauses and where each lives

Dropped clause	Carried by
The list of generated artifacts (settings schema, upstream-gaps index, action.yml and docs regions)	CONTRIBUTING.md line 9
bun run build:check fails on drift	CONTRIBUTING.md line 10
lib/index.js is the action bundle and lib/pkg/ the npm library	CONTRIBUTING.md line 11
main stays source-only	CONTRIBUTING.md line 11
The packaged commits off main carry the built bundle and library	CONTRIBUTING.md line 55
bun run test:e2e runs the corpus	CONTRIBUTING.md line 38
A shim that stays carries a COMPAT(vN) marker naming the major that deletes it	CONTRIBUTING.md line 16
Tests mirror the section under test/sections//	CONTRIBUTING.md line 25
e2e scenarios mirror the section under test/sections//scenarios/	CONTRIBUTING.md line 39
The release job runs downstream of the all-green gate	CONTRIBUTING.md line 53
The git topology lives in .github/scripts/release-pipeline.ts	CONTRIBUTING.md line 56
The compiler flags a forgotten registration step	the types in src/sections/registry.ts
An undeclared key keeps GitHub's current value; _remove: true drops a keyed entry	docs/operate/layering.md, which the bullet still names as the owner

The generated-output sentence in CONTRIBUTING.md line 9 was checked against the table in .github/scripts/generated.ts: both name the settings schema, the upstream-gaps index, and the action.yml and docs regions. Nothing to align.

Proof

• bun run typecheck: pass
• bun run lint: pass
• bun run lint:yaml: pass
• bun x actionlint .github/workflows/auto-fix.yml: pass
• bun x typos over the changed files: pass
• bun test test/docs test/architecture test/e2e/runner.test.ts: 497 pass, 0 fail; bun test test/docs test/scripts/release-pipeline.test.ts after the library and release-comment edits: 482 pass, 0 fail
• bun run build:check: 12 generated files match their generators (README.md carries generated regions; the edit is outside them)
• Gates: codex rubber-duck review, 3 rounds (the third after the rebase added the auto-fix.yml half), converged with no findings

Line accounting

File	+	-
.github/scripts/release-pipeline.ts	3	3
.github/workflows/auto-fix.yml	4	5
.github/workflows/update-release.yml	1	1
AGENTS.md	9	9
docs/reference/library.md	3	3
README.md	1	1
src/sections/webhooks/events.ts	1	1
test/e2e/generators.ts	1	1
test/e2e/runner.test.ts	2	2
test/e2e/runner.ts	2	2
Total	27	28

Reviewer note

• Deferred: none. The auto-fix.yml half joined this commit after chore(docs): render the inputs table with action-docs and run the generators by their package.json scripts #405 landed; the branch was rebased onto main once for it.
• The "Errors are values" bullet is left as is; chore(lint): move the never-throw rule to a Biome GritQL plugin #404 rewrites it.
• What each kept AGENTS.md bullet is a rule about:
  • Generated artifacts: never hand-edit them; the table in generated.ts is the one list.
  • lib/index.js and lib/pkg/: never commit them on main.
  • e2e scenarios: a new section or endpoint ships with them.
  • No backward-compatibility shims: break behind a major with a loud error; a one-shot migration only when many files move.
  • The section directory: the unit of work; the prose is docs/sections/.docs.yml.
  • The layered fold: null is a value, not CSS unset; layering.md owns the rules.
  • The release job: out of all-green's needs, so a release only happens from a green main.
  • Consumable refs: packaged commits off main, forward-only, no tag on main.

BEGIN_COMMIT_OVERRIDE
docs: lean AGENTS.md to rules, fix the install sentence, and retire comments naming deleted workflows and paths

• AGENTS.md keeps each rule as one sentence and drops the mechanism CONTRIBUTING.md or the code already carries.
• Dropped there: generated output and its drift check, the built lib paths, the e2e command, the COMPAT marker, the test mirror, the registry's checks, and the release topology.
• The intro sentence now points at CONTRIBUTING.md for the mechanics.
• README.md and docs/reference/library.md no longer say a bare npm install installs the released version; until the first stable release, latest is the 0.0.0 placeholder, so both ask for the next tag as the command line guide does.
• The stable-publish verdict's comment in release-pipeline.ts and update-release.yml's say the same: latest names the first publish (placeholder or pre-release) until a release takes it over.
• The bundle-parity comments in test/e2e/runner.ts and runner.test.ts no longer name an e2e job that skipped on a package.json-only diff; they say why the pin stays a unit test.
• The GenScenarioOptions.sections doc names the --sections flag instead of a smoke or PR-diff subset.
• The webhooks events header names test/sections/webhooks/events.test.ts, where the test lives now.
• Two auto-fix.yml comments no longer name a dependabot-bun-lockfile.yml workflow that does not exist; the stale-lockfile row says a close/reopen re-runs against the same lockfile and only a push with a real token brings a fresh one.
  END_COMMIT_OVERRIDE

[github-actions]

File size check

0 over a hard cap (fails), 32 warning(s).

File	Size	Tier	Cap
.github/scripts/gen-inputs-table.ts:54	11 comment lines	warn	10
.github/scripts/generated.ts:28	200 chars	warn	150
.github/scripts/release-pipeline.ts:6	156 chars	warn	150
.github/scripts/release-pipeline.ts:453	151 chars	warn	150
.github/scripts/release-pipeline.ts:1247	153 chars	warn	150
.github/scripts/release-pipeline.ts:1	34 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:449	14 comment lines	warn	10
.github/workflows/post-green.yml:29	153 chars	warn	150
.github/workflows/update-release-pr.yml:109	14 comment lines	warn	10
docs/upgrading/v2-to-v3.md	1276 lines	warn	1040
src/engine/layers.ts:217	157 chars	warn	150
src/flows/settings-write.ts:142	159 chars	warn	150
src/flows/settings-write.ts:30	11 comment lines	warn	10
src/flows/snapshot.ts:189	13 comment lines	warn	10
src/github/secret-scan.ts:42	11 comment lines	warn	10
src/schema.ts:186	153 chars	warn	150
src/schema.ts:197	176 chars	warn	150
src/sections/contract/errors.ts:14	14 comment lines	warn	10
src/sections/contract/module.ts:963	185 chars	warn	150
src/sections/contract/module.ts:627	12 comment lines	warn	10
src/sections/contract/module.ts:897	12 comment lines	warn	10
src/sections/secret_scanning_custom_patterns/compilable-form.ts:382	161 chars	warn	150
src/sections/shared/roles.ts:43	13 comment lines	warn	10
src/types.ts:16	156 chars	warn	150
test/docs/guides.test.ts:451	155 chars	warn	150
test/e2e/generators.ts	2633 lines	warn	2560
test/e2e/generators.ts:1703	166 chars	warn	150
test/e2e/generators.ts:1857	161 chars	warn	150
test/e2e/generators.ts:1666	12 comment lines	warn	10
test/engine/execute.test.ts:617	152 chars	warn	150
test/flows/merge-parity.test.ts:63	164 chars	warn	150
test/scripts/auto-fix-allowlist.test.ts:12	12 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

[Copilot]

Copilot review overview

🟢 Approval recommended

The prose changes accurately match the current code and repository documentation.

Review effort: Balanced
Findings: None

What changed in this PR

This documentation-only PR removes stale guidance and centralizes implementation details in CONTRIBUTING.md.

Changes:

• Streamlines AGENTS.md to durable rules.
• Corrects pre-release npm installation guidance.
• Updates comments describing tests, generators, and file locations.

File	Description
AGENTS.md	Removes duplicated implementation details.
README.md	Uses the next npm tag before stable release.
src/​sections/​webhooks/​events.ts	Corrects the test path.
test/​e2e/​generators.ts	Clarifies section generation behavior.
test/​e2e/​runner.test.ts	Updates bundle parity rationale.
test/​e2e/​runner.ts	Updates bundle parity documentation.

---

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

[Copilot]

Copilot review overview

🟢 Approval recommended

The prose-only updates accurately match the referenced code, paths, and current workflow behavior.

Review effort: Balanced
Findings: None

[Copilot]

Copilot review overview

🟡 Changes recommended

The revised npm bootstrap documentation conflicts with comments and tests in the release pipeline.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Update release pipeline comments and tests for 0.0.0 bootstrap state · New

[Copilot]

Copilot review overview

🟢 Approval recommended

The prose-only changes consistently reflect the current repository structure and behavior.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Update release pipeline comments and tests for 0.0.0 bootstrap state

[Copilot]

Copilot review overview

🟢 Approval recommended

The prose-only updates are consistent with the referenced code, paths, and repository documentation.

Review effort: Balanced
Findings: None