docs: add llms.txt, robots.txt, JSON-LD schema markup

- Add docs/llms.txt for AI crawler discovery with per-plugin doc links
- Add docs/robots.txt explicitly allowing GPTBot, ClaudeBot, PerplexityBot and other AI crawlers
- Add docs/overrides/base.html with JSON-LD Organization + WebSite + SoftwareApplication structured data on index page
- Fix mkdocs.yml site_url/repo_url/repo_name from .local placeholder to Borda/AI-Rig; add copyright, social links, git-revision-date-localized + social plugins
- Convert plugin docs (codemap/develop/foundry/oss/research) from bare symlinks to files with metadata frontmatter + snippets include
- Add FAQ section to docs/index.md (7 questions covering validate-first, calibration bias, blast-radius, plugin independence)
- Add separate mdformat pre-commit hook for docs/ with mkdocs-specific extensions
- Add mkdocs-git-revision-date-localized-plugin to docs/requirements.txt

---
Co-authored-by: Claude Code <noreply@anthropic.com>

Author: Borda

.pre-commit-config.yaml

@@ -87,7 +87,7 @@ repos:
     hooks:
       - id: mdformat
         name: 📝 mdformat (general)
-        exclude: ^plugins/(?!.*README\.md$)
+        exclude: ^(plugins/(?!.*README\.md$)|docs/)
         args: ["--number", "--wrap=no"]
         additional_dependencies:
           - mdformat-gfm
@@ -97,6 +97,17 @@ repos:
           - mdformat-beautysh
           - mdformat-admon
           - mdformat-web
+      - id: mdformat
+        name: 📝 mdformat (docs)
+        files: ^docs/
+        args: ["--number", "--wrap=no"]
+        additional_dependencies:
+          - mdformat-mkdocs
+          - mdformat-ruff
+          - mdformat-frontmatter
+          - mdformat-config
+          - mdformat-beautysh
+          - mdformat-web
 
   - repo: https://github.com/lycheeverse/lychee.git
     rev: lychee-v0.23.0

docs/README.md docs/NOTES.mddocs/README.md renamed to docs/NOTES.md

@@ -0,0 +1,5 @@
+---
+description: 'Claude Code codemap plugin: Python structural indexer providing import graphs, blast-radius scores, and function call graphs for instant codebase-aware agent context.'
+---
+
+--8<-- "plugins/codemap/README.md"

docs/codemap.md

@@ -0,0 +1,5 @@
+---
+description: 'Claude Code develop plugin: six validate-first workflows — plan, feature, fix, refactor, debug, review — with mandatory test gates for Python/ML projects.'
+---
+
+--8<-- "plugins/develop/README.md"

docs/codemap.md

@@ -0,0 +1,5 @@
+---
+description: 'Claude Code foundry plugin: 8 specialist agents, calibration benchmarks, config audit, and a self-improvement loop for professional AI-assisted Python/ML development.'
+---
+
+--8<-- "plugins/foundry/README.md"

docs/develop.md

@@ -1,3 +1,7 @@
+---
+description: Five Claude Code plugins — foundry, oss, develop, research, codemap — that enforce specialist agents, validate-first workflows, and calibrated quality gates for Python/ML OSS projects.
+---
+
 # 🤖 Borda's AI-Rig
 
 > Five plugins that turn Claude Code into a disciplined development partner
@@ -163,6 +167,38 @@ The plugins are designed to be composed. Here are three workflows that span the
 
 ______________________________________________________________________
 
+## Frequently Asked Questions
+
+??? question "What is Borda's AI-Rig?"
+
+    Borda's AI-Rig is a suite of five Claude Code plugins — foundry, oss, develop, research, and codemap — that enforce specialist routing, validate-first discipline, and calibrated quality gates across the full Python/ML OSS development lifecycle. Each plugin targets a distinct part of the practitioner loop and is designed to compose with the others.
+
+??? question "How is this different from just prompting Claude?"
+
+    Without AI-Rig, one generalist model handles architecture, implementation, documentation, linting, testing, and performance with no boundary enforcement. Corrections made in one session evaporate. AI-Rig closes the feedback loop: each part of the loop has a dedicated skill backed by a calibrated specialist agent that enforces discipline at every gate and feeds corrections back into its own instructions automatically via `/foundry:distill`.
+
+??? question "What does 'validate-first' mean?"
+
+    Validate-first means you must prove you understand the problem before writing production code. `/develop:feature` requires a failing demo test before implementation. `/develop:fix` requires a failing regression test that reproduces the bug before applying any fix. If you cannot write the test, the problem is underspecified.
+
+??? question "What is calibration bias?"
+
+    Calibration bias measures the gap between an agent's stated confidence and its actual recall on synthetic test problems. A bias of +0.15 means the agent says it is 90% confident but is only right 75% of the time. `/foundry:calibrate` benchmarks this for every agent and surfaces agents that are systematically overconfident or underconfident.
+
+??? question "What is a blast-radius score?"
+
+    Blast-radius score (from the codemap plugin) measures how many modules would be affected if a given module changed. `scan-query rdeps mypackage.auth` returns every module that imports `auth`. High blast-radius modules are the riskiest to refactor — codemap surfaces these before you touch anything.
+
+??? question "Does this work without all five plugins?"
+
+    Yes. Each plugin installs independently. foundry is strongly recommended as a base since it provides the specialist agents the other plugins dispatch to. Without foundry, the other plugins fall back to a generic agent with a role-description prompt.
+
+??? question "How do I know if my agent configuration has drifted?"
+
+    Run `/foundry:audit` — it runs 29 checks across hooks, settings, agent routing, and rule files. Zero critical findings means the configuration is healthy. Run it weekly or after any Claude Code update.
+
+______________________________________________________________________
+
 ## 🤝 Contributing
 
 The agent and skill source lives in `plugins/` — one directory per plugin, each with its own `skills/`, `agents/`, and `rules/` subdirectories. If you find a gap in agent behavior, the right fix is usually a targeted edit to the agent's instruction file, not a new skill. If you find a workflow that should be a skill, open an issue describing the before/after and the command you wish existed.

docs/develop.md

@@ -0,0 +1,18 @@
+# Borda's AI-Rig
+
+> Five Claude Code plugins for Python/ML OSS development:
+> specialist agents, calibrated workflows, validate-first discipline.
+
+## Documentation
+
+- [Overview](https://borda.github.io/AI-Rig/): Plugin suite — install, quick-start, how plugins compose
+- [foundry](https://borda.github.io/AI-Rig/foundry/): Base infrastructure — 8 specialist agents, calibration, audit, self-improvement
+- [oss](https://borda.github.io/AI-Rig/oss/): OSS maintainer workflows — parallel PR review, resolve feedback, SemVer releases
+- [develop](https://borda.github.io/AI-Rig/develop/): Validate-first development — feature, fix, refactor, debug with mandatory test gates
+- [research](https://borda.github.io/AI-Rig/research/): Structured ML experiments — SOTA search, design review, automated improvement loop
+- [codemap](https://borda.github.io/AI-Rig/codemap/): Python structural indexer — import graph, blast-radius, function call graph
+
+## Optional
+
+- [GitHub Repository](https://github.com/Borda/AI-Rig): Source code and plugin files
+- [Sitemap](https://borda.github.io/AI-Rig/sitemap.xml): All pages