feat: add AGENTS.md and docs site pages

[blackandredbot]

Closes #71

What does this change?

This PR adds two major pieces:

1. AGENTS.md (the "README for AI agents")

Creates AGENTS.md at the repo root following the AGENTS.md open format. It consolidates and restructures content from docs/LLM_HANDOVER.md, CONTRIBUTING.md, pyproject.toml, and README.md into 12 agent-optimized sections: project overview, architecture & dataflow, key file map, dev environment setup, build & test commands, code style, platform caveats, prohibited actions, PR workflow & GitHub templates, documentation accuracy, AI directives, and further reading.

docs/LLM_HANDOVER.md is not modified — it continues to serve the docs site. A property-based test enforces this.

2. Docs site pages (Zensical/MkDocs Material)

Adds the full documentation site structure under docs/:

• index.md, installation.md, usage.md, hardware-requirements.md, device-and-backend-selection.md
• architecture.md, contributing.md
• _snippets/ for reusable admonitions (model download, optional weights, Apple Silicon note, uv install)
• zensical.toml site configuration
• Mirrors the upstream README's docs link callout in docs/index.md
• Adds GVM/VideoMaMa "star their repo" callout in docs/usage.md (matching the recent README update)

3. Tests

• tests/test_agents_md.py — 18 unit tests + 5 Hypothesis property-based tests validating AGENTS.md content, structure, and LLM_HANDOVER.md preservation
• tests/test_docs_structure.py — docs site structure validation tests

---

Caution

Before merging: Enable GitHub Pages

This PR includes a docs.yml workflow that deploys the docs site to GitHub Pages via Zensical on pushes to main that touch docs/** or zensical.toml. For the deployment to work, GitHub Pages must be enabled on the repo first:

1. Go to Settings → Pages
2. Under Build and deployment → Source, select GitHub Actions
3. Save

Without this, the docs.yml workflow will run but the deployment step will fail with a permissions error. The rest of the PR (AGENTS.md, tests, docs content) is safe to merge regardless — only the automated deployment needs Pages enabled.

GitHub docs: Configuring a publishing source for your GitHub Pages site

How was it tested?

• uv run pytest tests/test_agents_md.py -v — all 23 tests pass (18 unit + 5 PBT)
• uv run pytest tests/test_docs_structure.py -v — docs structure tests pass
• Verified docs/LLM_HANDOVER.md is byte-identical to main (Property 4 enforces this)
• Verified all 11 required technical terms are present in AGENTS.md (Property 1)
• Verified all 6 key file paths appear in the file map (Property 2)
• Verified PR template elements are documented (Property 3)
• Verified all 5 documentation file references are present (Property 5)

Checklist

• uv run pytest passes
• uv run ruff check passes
• uv run ruff format --check passes

[blackandredbot]

Once GitHub Pages with Actions as the source is set up, this is what the experience will look like: https://blackandredbot.github.io/CorridorKey

I noticed strange formatting on the index.md — so will make that fix real quick and make another commit b

[shezmic]

Two specific concerns before this lands.

---

ISSUE — CONTRIBUTING.md, Apple Silicon section — uv.lock drift warning deleted without being moved to docs

The PR removes this block:

uv.lock drift: Running uv run pytest on macOS regenerates uv.lock with macOS-specific dependency markers. Do not commit this file. Before staging your changes, always run:

git restore uv.lock

This warning doesn't appear anywhere in the new docs/ pages — not in docs/contributing.md, not in any snippet. It was added to CONTRIBUTING.md specifically because it had already caused CI failures for Mac contributors. Silently removing it recreates that trap for every future contributor on macOS.

Fix: Move the warning into docs/contributing.md (or the Apple Silicon snippet) before deleting it from CONTRIBUTING.md. Issue #71's goal is to expand docs coverage, not reduce the total information available.

---

ISSUE — AGENTS.md, Prohibited Actions — missing the project's critical no-go zones

The section currently prohibits:

1. Pure gamma 2.2 curves
2. Modifying gvm_core/ or VideoMaMaInferenceModule/

The three files that are fully off-limits for any modification aren't listed:

• CorridorKeyModule/core/model_transformer.py — any change breaks checkpoint weight loading; there is no training infrastructure in this repo to validate changes
• CorridorKeyModule/core/color_utils.py — subtle colour math bugs produce silently incorrect compositing output that is very hard to catch in automated tests
• CorridorKeyModule/inference_engine.py — resizing, normalisation, and tensor handling are calibrated exactly to the model's training distribution

Also missing:

• img_size = 2048 in inference_engine.py and backend.py — the model was trained exclusively at this resolution; any change silently produces wrong results
• sRGB/Linear conversion order in clip_manager.py — wrong order produces crushed shadows, dark fringes, and broken composites (the piecewise sRGB curve is not interchangeable with gamma 2.2)

AGENTS.md is explicitly positioned as the primary AI-agent entry point for the codebase. Prohibited Actions is its highest-value section. An AI reading only AGENTS.md currently has no guardrail against touching any of the above. These should be the first things in that section, not an afterthought.

Fix: Expand Prohibited Actions to include all five of the above with a one-line rationale for each — the same format already used for the gamma 2.2 prohibition.

[blackandredbot]

Both addressed in dacad12.

AGENTS.md — Prohibited Actions: Expanded from 2 items to 7. The new entries (now items 1–5) cover:

1. model_transformer.py — no training infra to validate architectural changes
2. color_utils.py — subtle colour math bugs produce silently wrong composites
3. inference_engine.py — resize/normalisation calibrated to training distribution
4. img_size = 2048 — model trained exclusively at this resolution
5. sRGB/linear conversion order in clip_manager.py / color_utils.py — wrong order → crushed shadows, dark fringes

The gamma 2.2 and gvm_core/VideoMaMa prohibitions remain as items 6–7.

docs/contributing.md — uv.lock drift: Good catch on the deleted warning, but the underlying issue was fixed in #133 (extras-based backends made the lockfile platform-stable). Restoring the old "do not commit uv.lock" text would now be unnecessary. Instead, added a "Lockfile Stability" note under Apple Silicon explaining that the drift was resolved and how, so contributors have the context without the stale workaround.

That said — if you're seeing something about the lockfile situation that #133 didn't fully address, I'd want to know. Is there a deeper risk here you think we should be covering?

[nikopueringer]

I’m extremely hesitant to implement docs and guides that are AI generated. If an LLM generated these from analyzing the code, then there’s really no reason to use these docs as opposed to letting LLMs continue to analyze the code.

In addition, LLMs make abundant mistakes when planning image compositing, and I would bet that there are numerous issues introduced in these docs that can only be fixed by having a human expert with domain knowledge review them.

That said, I am very appreciative of the effort to improve the project. I am going to close this PR for now.