docs: establish repository knowledge system

[dannysteenman]

Summary

• Rework AGENTS.md into a concise table of contents and add docs/README.md as the canonical knowledge map.
• Consolidate stale review and Turborepo pages into current guides and references for development, release, commands, generated files, tests, configuration, findings, and rule IDs.
• Add a mechanically enforced documentation graph with 14 CLI contract tests and a dedicated CI job.
• Record the unresolved stable-public-ID versus contiguous-per-service-ID contract without changing rule IDs or runtime behavior.

Diagram

flowchart LR
  A["AGENTS.md"] --> B["docs/README.md"]
  C["README.md"] --> B
  B --> D["Guides"]
  B --> E["Reference"]
  B --> F["Package AGENTS.md files"]
  G["CI docs checker"] --> A
  G --> B
  G --> D
  G --> E

Loading

Scope

• cloudburn (cli)
• @cloudburn/sdk
• @cloudburn/rules
• docs/community files

Release Notes

• Added a .changeset/*.md file for published package changes
• No published package changes in this PR

Verification

• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm build
• pnpm verify
• pnpm docs:test (14 tests)
• pnpm docs:check
• git diff --check

Boundary Checks

• No engine/parser/provider logic added to @cloudburn/rules
• CLI delegates scan logic to SDK
• README/CONTRIBUTING/docs updated when behavior changed

Related Issues

No directly related open issue was found.

[axonstone]

roborev: Combined Review (9827a67)

Verdict: Fail — the unresolved rule-ID contract risks silently changing user configuration semantics.

High

• Rule-ID compatibility is internally contradictory — docs/reference/rule-ids.md treats IDs as public configuration/result references while requiring renumbering to preserve gap-free sequences. The release guide prohibits major changesets and provides no migration or alias mechanism. Removing or reordering a rule could therefore make an existing enabled-rules entry silently select a different policy.
  • Recommended fix: Use immutable IDs with permitted gaps or tombstones and update the metadata test. Otherwise, define versioning, aliases, deprecation, migration diagnostics, and a release process for breaking renumbering.

---

Reviewers: 3 done | Synthesis: codex, 12s | Total: 5m35s

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9827a67bc8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".