Split the documentation site out of the library repository

The pages, the tools that render them and the tests that check them move here from
CTRLRun/ctrlrun, with their history. That repository keeps the library, its specifications,
its README assets and everything `pip install ctrlrun` ships; this one keeps everything a
reader sees at ctrlrun.dev and nothing that is published to PyPI.

This repository is the Mintlify site root, so what was `docs/docs/` is `docs/` and the loose
pages moved up one level. Every URL and every docs.json entry is unchanged. `.mintignore` is
rewritten: the root used to be one directory with a few neighbours and is the whole repository
now, so the tooling, the tests and the form API are each named. A file that is not a page and
is not on that list would be a page nobody meant to publish.

**The guarantee that a page describes the shipped library needed both trees, so it did not
survive the split on its own.** `tools/docs_audit/_core.py` resolves a library checkout from
$CTRLRUN_SOURCE or ../ctrlrun and raises when there is none: a check that cannot find the
code is a red run, never a green one that verified nothing. CI here checks the library out;
the library's CI runs these same checks from here against the commit it is proposing, so one
implementation covers both directions.

Five of the library's test files were split rather than moved, each along a line that was
already there. What came here is the half that reads a page: the cookbook page checks, the
claims and adapter tables, T180's scan over the release documents, the verify page, and a new
comparison between this repository's images and the library's brand assets.

Four of those tests had begun skipping rather than failing once the pages moved -- each
guarded its read with a `pytest.skip("no repository checkout")` written for an sdist, where
the pages are pruned. Here the pages are never pruned, so a missing one is a failure.

One thing this commit cannot do: the Mintlify content directory is still `/docs` inside the
library's repository. It has to be repointed at this repository's root, once, in the Mintlify
dashboard, or the site keeps building from a directory with no pages left in it.

Author: arpanghoshal

.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # The pages describe a library that lives in another repository, so a change *there* can
+  # make a page here wrong without anything here changing. `CTRLRun/ctrlrun`'s own CI sends
+  # this event on a push to its main branch, and the run below checks these pages against
+  # that commit. Without it the split would have turned a red check into a slow drift.
+  repository_dispatch:
+    types: [library-changed]
+  # And a weekly floor, so a dispatch that never arrives -- a token expiring, a workflow
+  # edited -- surfaces as a red run rather than as silence.
+  schedule:
+    - cron: "17 6 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: ctrlrun-docs
+
+      # The library these pages document. The checks read it -- a page that says the CLI
+      # prints X is only true if the CLI prints X -- and `tools/docs_audit/_core.py` raises
+      # when it is absent rather than skipping, so a checkout that failed to happen is a red
+      # run and not a green one that verified nothing.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: CTRLRun/ctrlrun
+          ref: ${{ github.event.client_payload.sha || 'main' }}
+          path: ctrlrun
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          # The library itself, because the reference pages are rendered from its docstrings
+          # and its `--help`, and the checks import it to compare.
+          pip install -e "./ctrlrun[dev,gateway,otel,identity]"
+          pip install ruff mypy pytest griffe pyyaml
+
+      # One script, called here and by a developer before pushing, so "it passed locally" and
+      # "it passed in CI" cannot come to mean different things.
+      - name: check
+        working-directory: ctrlrun-docs
+        env:
+          CTRLRUN_SOURCE: ${{ github.workspace }}/ctrlrun
+        run: ./scripts/check.sh
+
+      # The four drift checks, named individually because `STYLE.md` says the CI job runs them
+      # and `test_ci_runs_the_three_checks_and_the_drift_check` reads this file to prove it.
+      # A guard CI does not run is prose.
+      - name: The documentation audit
+        working-directory: ctrlrun-docs
+        env:
+          CTRLRUN_SOURCE: ${{ github.workspace }}/ctrlrun
+        run: |
+          python tools/docs_audit/snippets.py
+          python tools/docs_audit/lint.py
+          python tools/docs_audit/links.py
+          python tools/docs_audit/render_capabilities.py --check

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.DS_Store
+
+# A local clone of the library this site documents, if you put it here rather than beside
+# this repository. `tools/docs_audit/_core.py` finds it either way.
+/ctrlrun/
+node_modules/

.mintignore

@@ -0,0 +1,32 @@
+# What is in this repository and is **not** a page of the site.
+#
+# The site root used to be `docs/` inside CTRLRun/ctrlrun, so this file only had to exclude a
+# handful of neighbours. The root is the whole repository now, which brings the tooling, the
+# tests and the form API into view -- so each of them is named here. A file that is not a page
+# and is not on this list is a page nobody meant to publish.
+
+# The maintainers' documents.
+README.md
+IA.md
+STYLE.md
+SEO.md
+BUILD-PROMPTS-*.md
+
+# The capability source and the rendered fragments pages embed. A render is a fragment, not a
+# page: `docs.mdx` and `docs/production/index.mdx` include them.
+capabilities.yaml
+generated/
+
+# Source assets and the browser verification scripts. `images/` is the published set.
+assets/
+
+# The checks, their tooling, and this repository's own configuration.
+tests/
+tools/
+scripts/
+.github/
+pyproject.toml
+LICENSE
+
+# The Vercel Function behind the review form. It is deployed by Vercel, not by Mintlify.
+website-form/

docs/IA.md IA.mddocs/IA.md renamed to IA.md

@@ -2,7 +2,7 @@
 
 The target shape of the docs site, one line per page: what it is for and the query it should
 answer. Later sessions write the pages; this file is what they write against, and
-`docs/capabilities.yaml` names pages by the paths below.
+`capabilities.yaml` names pages by the paths below.
 
 **The fixed copy**, quoted here so every page quotes the same words:
 
@@ -15,12 +15,12 @@ answer. Later sessions write the pages; this file is what they write against, an
 | Promise | A consequential action happens at most once, exactly as approved, and leaves a receipt — and when the outcome is unknown, CTRLRun says so instead of guessing. | Hero subline, README paragraph 2 |
 | Hook (posts) | Agents can retry. The real world can't. | Social, talk titles; not the README header |
 
-The rules every page is held to are in `docs/STYLE.md`. The tools that hold them are in
+The rules every page is held to are in `STYLE.md`. The tools that hold them are in
 `tools/docs_audit/`.
 
 ## Conventions
 
-- Paths are root-relative on the site: `docs/concepts/effect-keys` is `docs/docs/concepts/effect-keys.mdx`.
+- Paths are root-relative on the site: `docs/concepts/effect-keys` is `docs/concepts/effect-keys.mdx`.
 - **Purpose** is the page's first-paragraph answer, compressed. **Query** is the search a
   stranger types, and the first sentence of the page is written to answer it.
 - The existing Markdown documents that stay where they are — the specifications,
@@ -169,7 +169,7 @@ row landed with `docs/SPEC-mcp-operator.md`, which is when it stopped being plan
 
 Each Concepts page opens with one definitional sentence an assistant can quote standalone,
 has one diagram or code block, names the guarantee it supports and what it does not do, and
-ends with Next links. Every claim on a Concepts page has a `docs/docs/CLAIMS.md` row.
+ends with Next links. Every claim on a Concepts page has a `docs/CLAIMS.md` row.
 
 | Path | Purpose | Query |
 |---|---|---|
@@ -276,7 +276,7 @@ signature · what is not covered. Query: *ctrlrun faq* and each question verbati
 
 | Path | Purpose | Query |
 |---|---|---|
-| `security/threat-model` | What CTRLRun defends against, what it does not, and the fail-closed rules that follow; renders `docs/docs/THREAT_MODEL.md`. | *ctrlrun threat model* |
+| `security/threat-model` | What CTRLRun defends against, what it does not, and the fail-closed rules that follow; renders `docs/THREAT_MODEL.md`. | *ctrlrun threat model* |
 | `docs/security/verify-guarantees` | The guarantee catalogue G1–G11, what each exercises, what N/A means, what verify cannot see. | *ctrlrun verify guarantees* |
 | `docs/security/receipt-chain` | Each receipt carries the hash of the one before; what the chain detects, what it does not prove, and the two statements that erase the end of the log. Alteration, not authorship. | *tamper evident audit log AI agent* |
 | `security/how-this-is-built` | Spec-first, every MUST mutation-tested with the real numbers, independent review sessions, CLAIMS.md, N/A is not a pass, AI coding agents used throughout with the constraints that make that safe, and what has not been done: no external audit yet. Session 1b. | *is ctrlrun trustworthy* · *how ctrlrun is tested* |
@@ -286,7 +286,7 @@ signature · what is not covered. Query: *ctrlrun faq* and each question verbati
 
 | Path | Purpose | Query |
 |---|---|---|
-| `architecture/overview` | The boundary CTRLRun owns, the canonical flow (normalize · decide · approve · reserve · execute · record), the module map; renders `docs/docs/ARCHITECTURE.md`. | *ctrlrun architecture* |
+| `architecture/overview` | The boundary CTRLRun owns, the canonical flow (normalize · decide · approve · reserve · execute · record), the module map; renders `docs/ARCHITECTURE.md`. | *ctrlrun architecture* |
 | `docs/architecture/specifications` | The six specifications, unchanged, with one line each on what the version asked; plus the OWASP and ACS readings. | *ctrlrun spec* |
 
 ## Changelog
@@ -406,7 +406,7 @@ Two sources with opposite emphases, and the tree above follows both:
 - Mintlify's own position, for the assistants that do read them: `llms.txt`, `llms-full.txt`
   and an MCP server are generated for every site. — <https://www.mintlify.com/docs/ai/llmstxt>
 
-What this means concretely for these pages, and what `docs/STYLE.md` enforces: **answer-first
+What this means concretely for these pages, and what `STYLE.md` enforces: **answer-first
 first paragraphs** and one **definitional sentence** per Concepts page, written for a human;
 **consistent entity naming** (CTRLRun, effect key, action hash, AMBIGUOUS); **comparison
 tables** on every Compare page; **FAQ structured data** on the FAQ page; quotable, plain
@@ -415,6 +415,6 @@ it does not mean: keyword density, chunked pages, or a second writing style for
 
 ## Next
 
-- `docs/STYLE.md` — the rules every page follows.
-- `docs/capabilities.yaml` — the single source the capability tables are rendered from.
+- `STYLE.md` — the rules every page follows.
+- `capabilities.yaml` — the single source the capability tables are rendered from.
 - `tools/docs_audit/` — the three checks and the generator.