docs(ai): consolidate canonical ai/* sources (#64)

[ashleyshaw]

Adds canonical ai/agents.md, ai/Claude.md, ai/Gemini.md, and ai/RUNNERS.md; rewires README/AGENTS/CLAUDE/custom-instructions to point at ai/* authority docs. Closes #64.

Summary by CodeRabbit

• Documentation
  • Updated metadata versions and timestamps across reference documents
  • Added new canonical AI agent governance and runner documentation files
  • Established consolidated index for AI agent sources and implementation references
  • Expanded AI & Automation documentation links in project README and related guides
  • Updated custom instructions with references to canonical agent and runner inventories

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

Warning

Review limit reached

@ashleyshaw, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 54 minutes and 1 second. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: dd54edac-fa97-486f-99cd-2b01af9470c0

📥 Commits

Reviewing files that changed from the base of the PR and between 3dbc9e4 and bf0bdfe.

📒 Files selected for processing (1)

• CLAUDE.md

📝 Walkthrough

Walkthrough

This PR consolidates fragmented AI documentation into authoritative canonical sources under the ai/ directory and updates repository-wide references to those sources. Four new documentation files are created (ai/agents.md, ai/Claude.md, ai/Gemini.md, ai/RUNNERS.md), and six existing files are updated with version bumps and cross-references to the new canonical sources.

Changes

AI Documentation Consolidation

Layer / File(s)	Summary
Canonical agents source map and governance policy ai/agents.md, AGENTS.md	ai/agents.md is authored as the foundational index for AI agent governance, defining frontmatter metadata, source-of-truth policy, and links to related docs. AGENTS.md is updated to version 1.4 and enhanced with references to the new canonical agent and runner inventory files.
Model-specific canonical entry points ai/Claude.md, ai/Gemini.md, CLAUDE.md	ai/Claude.md and ai/Gemini.md are authored as model-specific canonical references with governance guidance and core reference sections. CLAUDE.md is updated to version 1.1 with new cross-references to the ai/ directory canonical documents.
Runner and telemetry inventory ai/RUNNERS.md	ai/RUNNERS.md is authored to document JavaScript runner patterns, Bash runner inventory, telemetry hook locations, and the migration direction toward Node CLI scripts.
Repository-wide documentation navigation updates README.md, .github/custom-instructions.md	README.md is updated from version 2.1 to 2.2 with new "AI & Automation" links to the canonical ai/ documentation files. .github/custom-instructions.md "Start Here" section is updated with links to the agents and runners canonical sources.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is minimal but accurately identifies the four new canonical files added (ai/agents.md, ai/Claude.md, ai/Gemini.md, ai/RUNNERS.md) and references the linked issue. However, it lacks required sections from the template: Changelog, Risk Assessment, and How to Test.	Add Changelog (Added section with the four new files), Risk Assessment (Low risk for documentation-only changes), and How to Test (documentation review steps). The template requires these sections for release automation and risk tracking.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(ai): consolidate canonical ai/* sources (#64)' clearly and specifically describes the main change: consolidating AI documentation into canonical ai/* sources.
Linked Issues check	✅ Passed	The PR meets the core coding requirements from issue #64: four new canonical ai/* files are added (ai/agents.md, ai/Claude.md, ai/Gemini.md, ai/RUNNERS.md), and internal references in README, AGENTS.md, CLAUDE.md, and custom-instructions.md are updated to point to these authoritative sources.
Out of Scope Changes check	✅ Passed	All changes align with issue #64 objectives: new canonical ai/* files, metadata updates, and reference wiring. No unrelated changes detected beyond the scope of consolidating AI documentation sources.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/64-ai-docs-canonical

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔍 Reviewer Summary for PR #461

CI Status: ✅ success
Files changed: 8

Recommendations

• Ready to proceed pending human review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fddff01178

ℹ️ 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".

[chatgpt-codex-connector]

Bump frontmatter for edited docs

For body edits like this added paragraph, scripts/validation/validate-frontmatter-freshness.js requires the affected Markdown frontmatter to change; running npm run validate:frontmatter:changed -- --base 457671513f9064159c70bbde3edb716d7e5c6602^ --head 457671513f9064159c70bbde3edb716d7e5c6602 reports failures for AGENTS.md, CLAUDE.md, and README.md because their versions were not bumped, and CLAUDE.md also keeps last_updated: "2026-05-20". Please update the edited documents' frontmatter with these content changes so the freshness gate passes.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Use a valid stability value

This new documentation file sets stability: "active", but .schemas/frontmatter.schema.json only allows stable, experimental, or incubating for stability; validating this frontmatter with the repository schema marks ai/RUNNERS.md invalid. Use one of the allowed values or extend the schema before adding this canonical doc.

Useful? React with 👍 / 👎.

[github-actions]

🔍 Reviewer Summary for PR #461

CI Status: ✅ success
Files changed: 8

Recommendations

• Ready to proceed pending human review