docs: establish the CacheRoute developer and maintenance handbook

[rickisba]

Motivation

• Implement the documentation-governance work requested by Issue Documentation governance: establish the CacheRoute developer and maintenance handbook #180 by adding a concise developer handbook and a small same-PR governance update to AGENTS.md while preserving existing runtime behavior and package discovery.
• Provide a single navigation and validation surface for maintainers to consult before changing public or structural surfaces, and ensure the handbook is repository-only (not packaged).
• Record current implemented observability behavior from the merged PR observability: propagate Scheduler trace context and instrument Proxy stages #183 as Current and keep broader Issue v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 work on the roadmap (not claimed as implemented).

Description

• Added the developer handbook under doc/developer-handbook/ with the required chapters: README.md, architecture-and-evolution.md, package-and-module-map.md, public-api-and-data-models.md, runtime-flows.md, configuration-and-interfaces.md, compatibility-and-migrations.md, development-and-validation.md, documentation-governance.md, and glossary.md.
• Updated AGENTS.md to include the focused documentation-governance section and the same-PR checklist linking to doc/developer-handbook/README.md.
• Made the two minimal root README edits: added a top-navigation link to the Developer Handbook and a Documentation table row pointing to doc/developer-handbook/README.md.
• Added and adjusted validation tests: added test/test_documentation_governance.py, updated test/test_wheel_install.py and test/test_repository_governance.py to allowlist handbook references for governance checks and to assert handbook files remain repository-only in wheels.
• Confirmed and documented PR observability: propagate Scheduler trace context and instrument Proxy stages #183 observability propagation and Proxy-local collection as Current in the handbook; explicitly left Issue v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 as incomplete in the roadmap and non-current.
• Head SHA: b78ab930cc77100134b7e21eda3f4b2d0f8c000a; Base/main SHA: 3ff12ce323f882b7ed3aba751aac252cf04b0029.
• Changed files (complete list): AGENTS.md, README.md, doc/developer-handbook/README.md, doc/developer-handbook/architecture-and-evolution.md, doc/developer-handbook/package-and-module-map.md, doc/developer-handbook/public-api-and-data-models.md, doc/developer-handbook/runtime-flows.md, doc/developer-handbook/configuration-and-interfaces.md, doc/developer-handbook/compatibility-and-migrations.md, doc/developer-handbook/development-and-validation.md, doc/developer-handbook/documentation-governance.md, doc/developer-handbook/glossary.md, test/test_documentation_governance.py, test/test_repository_governance.py, test/test_wheel_install.py.

Testing

• Ran compilation and the required test suites from the PR checklist with the following results: python3 -m compileall -q src test (PASSED); python3 -m pytest -q test/test_documentation_governance.py (9 passed); python3 -m pytest -q test/test_repository_governance.py (23 passed); python3 -m pytest -q test/test_namespace_layout.py (10 passed); python3 -m pytest -q -s test/test_source_checkout_imports.py (passed as run in this environment); python3 -m pytest -q -s test/test_wheel_install.py -m "not network" (3 passed, 1 deselected); python3 -m pytest -q test/observability (158 passed); python3 -m pytest -q test/test_contract_foundation.py (5 passed); python3 -m pytest -q test/test_contract_service_migration.py (11 passed); git diff --check (no issues).
• Wheel build step (python3 -m build --no-isolation) could not be completed in this execution environment because the build tool could not be installed due to network access restrictions, so that command is ENVIRONMENT-BLOCKED and must be run in CI or a network-enabled environment to produce the final wheel artifact.
• Confirmations: handbook files are repository-only (not added to package discovery), AGENTS.md links to the handbook, PR observability: propagate Scheduler trace context and instrument Proxy stages #183 observability behavior is documented as Current, and broader Issue v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 remains on the roadmap (not claimed Current).

Closes #180
Refs #137
Refs #141
Refs #157
Refs #159
Refs #178
Refs #179
Refs #182
Refs #183

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 32295d1e20

ℹ️ 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]

Compare README checks against the parent commit

When this test runs in a normal CI or clean checkout after the commit is checked out, both commands use HEAD, so git diff --unified=0 HEAD -- README.md is empty and git show HEAD:README.md already contains the new handbook link. The following assertions then fail even though the tree is clean; I confirmed python3 -m pytest -q test/test_documentation_governance.py fails at the added-link count. Use the parent/base revision or a checked-in fixture instead of HEAD for this regression check.

Useful? React with 👍 / 👎.