python-docs-mcp-server 0.2.0__tar.gz → 0.3.0__tar.gz

python_docs_mcp_server-0.3.0/.coderabbit.yaml

@@ -0,0 +1,24 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-US"
+
+reviews:
+  profile: "chill"
+  request_changes_workflow: false
+  high_level_summary: true
+  review_status: true
+  path_filters:
+    - "src/**"
+    - "tests/**"
+  path_instructions:
+    - path: "src/**"
+      instructions: |
+        Focus review on correctness, MCP tool behavior, runtime compatibility,
+        cache/index compatibility, packaging impact, and security boundaries.
+        Avoid comments about planning docs, release docs, or repository process
+        unless the changed source code makes those docs materially inaccurate.
+    - path: "tests/**"
+      instructions: |
+        Focus review on meaningful assertions, regression coverage, fixture
+        correctness, deterministic behavior, and avoiding network- or
+        environment-dependent tests unless the test is explicitly marked as an
+        integration smoke test.

python_docs_mcp_server-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,49 @@
+# CODEOWNERS — requests maintainer visibility on forbidden-territory paths.
+#
+# Source of truth: AGENT-EXECUTION-PIPELINE.md §2 (Forbidden Territory),
+# required by §10 (Pre-flight Checklist).
+#
+# For these rules to be ENFORCED, branch protection on `main` must enable
+# "Require review from Code Owners". CODEOWNERS alone only requests review;
+# branch protection only blocks merge when review rules are enabled.
+#
+# Autonomous agents may NOT modify these paths without explicit Vision approval
+# (pipeline §2). Any agent PR touching them must add the `supervisor-review`
+# label and stop short of self-merging (pipeline §7).
+
+# --- Project identity, dependencies, classifiers (only `version` is agent-editable) ---
+/pyproject.toml                                   @ayhammouda
+
+# --- Permanent commitments and trust posture ---
+/LICENSE                                          @ayhammouda
+/SECURITY.md                                      @ayhammouda
+
+# --- Load-bearing brand assets ---
+/README.md                                        @ayhammouda
+/.planning/POSITIONING.md                         @ayhammouda
+
+# --- Release history (adding entries is fine; rewriting history is not) ---
+/CHANGELOG.md                                     @ayhammouda
+
+# --- CI/CD and supply chain (release path especially) ---
+# The single /.github/ rule covers workflows and release.yml. Last-matching-
+# pattern wins in CODEOWNERS — adding narrower entries with the same owner
+# below would be no-ops and would silently *override* this rule if a different
+# owner is ever added here, so we keep ownership of /.github/ uniform.
+/.github/                                         @ayhammouda
+
+# --- Index schema and migrations (rebuilds existing user indexes) ---
+# NOTE: the retrieved-docs *cache* table lives in
+# src/mcp_server_python_docs/services/persistent_cache.py and is NOT covered
+# here — it is best-effort, fingerprint-scoped, and agent-editable per
+# decision 5.7. Only the canonical *index* schema is forbidden territory.
+**/storage/schema.sql                             @ayhammouda
+**/migrations/                                    @ayhammouda
+
+# --- Archival roadmap history ---
+/.planning/ROADMAP.md                             @ayhammouda
+
+# --- Governing policy + strategy documents ---
+/AGENT-EXECUTION-PIPELINE.md                      @ayhammouda
+/OPENCLAW-FORGE-PROTOCOL.md                       @ayhammouda
+/STRATEGIC-ROADMAP-2026-05-29.md                  @ayhammouda

python_docs_mcp_server-0.3.0/.github/ISSUE_TEMPLATE/autonomous-agent.yml

@@ -0,0 +1,108 @@
+name: Autonomous Agent Task
+description: A task spec scoped for unattended execution by an autonomous coding agent (Claude Code or similar).
+title: "[vX.Y.Z] <scope> — <verb> <thing>"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template enforces the issue structure required by
+        `AGENT-EXECUTION-PIPELINE.md` §3 (in the repo root). An issue missing
+        any required section is **not** agent-ready and will not pass the §10
+        pre-flight checklist. Do not apply the `agent-ready` label from this
+        template; a maintainer applies it only after reading the completed
+        issue end-to-end. Read the pipeline doc and
+        `STRATEGIC-ROADMAP-2026-05-29.md` before filling this out.
+  - type: textarea
+    id: context
+    attributes:
+      label: Context (self-containment)
+      description: Link to the per-issue context file, this pipeline doc, the roadmap, any relevant ADR or `.planning/phases/0X-*` directory, and prior related issues.
+      value: |
+        - Per-issue context file: `.planning/agent-context/<issue-slug>.md` (read this first)
+        - Pipeline: `AGENT-EXECUTION-PIPELINE.md`
+        - Roadmap: `STRATEGIC-ROADMAP-2026-05-29.md` §<section>
+        - Related issues:
+    validations:
+      required: true
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal (one sentence)
+      description: The single outcome that counts as success.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria (testable checkbox list)
+      description: Each criterion must be testable, atomic, achievable without touching forbidden territory, and verifiable in <5 minutes (pipeline §4). Prefer exact commands and expected output.
+      value: |
+        - [ ] `<exact command>` <expected result>
+        - [ ] `<exact command>` <expected result>
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope boundaries
+      description: Explicit In scope / Out of scope. Out-of-scope work is a stop-and-comment trigger, never silent expansion.
+      value: |
+        **In scope:**
+        -
+
+        **Out of scope:**
+        -
+    validations:
+      required: true
+  - type: textarea
+    id: forbidden
+    attributes:
+      label: Forbidden-territory reminders
+      description: Repeat the AGENT-EXECUTION-PIPELINE.md §2 items relevant to THIS issue. If the task appears to require touching any of them, stop and comment.
+    validations:
+      required: true
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation commands (pipeline §5 gate)
+      description: The exact canonical gate, in order, plus any change-type-specific gates. Must pass before any PR is opened.
+      value: |
+        ```bash
+        uv run ruff check src/ tests/
+        uv run pyright src/
+        uv run pytest --tb=short -q
+        uv run python-docs-mcp-server doctor
+        ```
+    validations:
+      required: true
+  - type: textarea
+    id: pr-and-recovery
+    attributes:
+      label: PR requirements & recovery
+      description: What the PR description must include (pipeline §6) and where to go if blocked (pipeline §8).
+      value: |
+        - PR title matches this issue title verbatim; body uses
+          `.github/PULL_REQUEST_TEMPLATE/agent.md`.
+        - Branch: `agent/<issue-number>-<kebab-summary>`.
+        - If blocked: stop, write `WORKING-NOTES.md` on the branch, comment on
+          this issue per pipeline §8. **No PR and no silent scope expansion.**
+    validations:
+      required: true
+  - type: input
+    id: effort
+    attributes:
+      label: Effort estimate (hours)
+      description: Rough hours. Agent must bail and escalate if work exceeds 2× this estimate (pipeline §8).
+    validations:
+      required: true
+  - type: checkboxes
+    id: acknowledgements
+    attributes:
+      label: Agent acknowledgements
+      options:
+        - label: I will work on a branch, never on `main`, and will not self-merge.
+          required: true
+        - label: I will stop and comment rather than silently expand scope or touch forbidden territory.
+          required: true
+        - label: I will add `supervisor-review` if any pipeline §7 trigger fires.
+          required: true

python_docs_mcp_server-0.3.0/.github/PULL_REQUEST_TEMPLATE/agent.md

@@ -0,0 +1,42 @@
+<!--
+Autonomous-agent PR template. Enforces AGENT-EXECUTION-PIPELINE.md §6.
+PR title MUST match the issue title verbatim. Never self-merge.
+-->
+
+Closes #<issue-number>
+
+## Acceptance criteria
+<!-- Copy every criterion from the issue. Check the box only when satisfied,
+     and add one line of evidence (command + observed result) per item. -->
+- [ ] <criterion 1> — <evidence>
+- [ ] <criterion 2> — <evidence>
+
+## Validation gate output
+<!-- Paste the tail of each gate command. All must be green before opening this PR. -->
+```text
+$ uv run ruff check src/ tests/
+$ uv run pyright src/
+$ uv run pytest --tb=short -q
+$ uv run python-docs-mcp-server doctor
+```
+<!-- Plus any change-type-specific gates from pipeline §5 (stdio smoke,
+     validate-corpus, uv lock --check) that applied to this change. -->
+
+## CodeRabbit review
+<!-- After CodeRabbit comments, summarize findings as:
+     - Blocking: <items or None>
+     - Follow-up: <items or None>
+     - False positive: <items or None>
+     If CodeRabbit has not run yet, write "Pending." Do not mark findings green
+     by silence. -->
+Pending.
+
+## Why this approach
+<!-- One paragraph max. If the issue fully prescribed the approach, say so.
+     If you cite a design choice NOT in the issue, that is a §7 trigger. -->
+
+## Why this triggered supervisor review
+<!-- List any pipeline §7 triggers and explain each. If none, write "None."
+     If any fired: this PR is opened for supervisor review only; do not merge it yourself,
+     and ensure the `supervisor-review` label is applied. -->
+None.

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.3.0}/.github/RELEASE.md

@@ -51,6 +51,7 @@ Replace `X.Y.Z` below with the version you are releasing (e.g. `0.1.7`). Complet
   ```
   Must report `✅ server.json is valid`. If validation fails, shorten `server.json` `description` on `main` before tagging (the `pyproject.toml` description is unbounded by this constraint and can stay longer).
 - [ ] Integration tests from `.github/INTEGRATION-TEST.md` are complete and signed off
+- [ ] Refresh README `## Tools`, `glama.json`, and registry/version badges to match the current tool surface.
 - [ ] `Doctor` subcommand passes:
   ```bash
   uv run python-docs-mcp-server doctor

python_docs_mcp_server-0.3.0/.planning/agent-context/adr-001-source-adapters.md

@@ -0,0 +1,49 @@
+# Agent Context — ADR-001 (Source Adapters)
+
+> One-read working context for issue `[v0.3.0] docs — write ADR-001 (Source Adapters)`.
+> A **writing** task. Every claim must match the code — verify before you assert.
+
+## 1. Roadmap excerpts (the principles you are recording)
+
+- **Principle 2.1:** Canonical source only. CPython at a pinned tag for stdlib
+  docs; PyPI metadata API for package URLs. No scraped mirrors. No third-party indexers.
+- **Principle 2.2:** Offline-first *runtime*. No network access at query time.
+- **Principle 2.7:** Layered design with stable contracts; the **source
+  connector** is layer 1 of 8 and is what makes the pattern cloneable.
+
+## 2. The two source adapters that exist today (describe these)
+
+1. **CPython documentation source** (`src/mcp_server_python_docs/ingestion/`):
+   - `cpython_versions.py` — pinned build targets (`CPYTHON_DOCS_BUILD_CONFIG`:
+     per-version `tag` + `sphinx_pin`). Five versions: 3.10–3.14.
+   - `__main__.py` `build-index` path — `git clone --depth 1 --branch <tag>` of
+     `python/cpython`, builds docs with `sphinx-build -b json` in a dedicated venv.
+   - `sphinx_json.py` — parses the Sphinx JSON output into the index; also loads
+     `synonyms.yaml`. `inventory.py` — parses `objects.inv` for exact symbol resolution.
+2. **PyPI metadata source** (`src/mcp_server_python_docs/services/package_docs.py`):
+   - Backs `lookup_package_docs`. A **controlled** PyPI metadata lookup
+     (`GET /pypi/<project>/json`) that returns only project/docs/homepage/source
+     URLs — not a generic web fetch, not scraped docs.
+
+## 3. The one documented exception to "offline-first"
+
+- `lookup_package_docs` performs a network call to PyPI's metadata API. This is
+  **not** a docs-*query*-time call against the canonical stdlib index — it is a
+  controlled, narrowly-scoped metadata lookup. The ADR must state this exception
+  explicitly so the offline-first invariant (2.2) stays honest. (See README's
+  "Why not Context7" section and `SECURITY.md` scope for the existing framing.)
+
+## 4. Known pitfalls
+
+- **Verify, don't assume.** Open each cited file and confirm the behavior before
+  writing it into the ADR. An ADR that misstates current behavior is worse than none.
+- Don't document adapters that don't exist (Rust/Go) beyond a single "future
+  adopters clone this contract" sentence — that's the cloneability point, not a claim.
+- No code, schema, or workflow changes — writing only.
+- Keep it factual; "reference architecture" is not claimed externally (5.6).
+
+## 5. Decision log
+
+- File path:
+- Claims you verified against code (file:line):
+- Anything ambiguous about the layer contract that you flagged for the maintainer:

python_docs_mcp_server-0.3.0/.planning/agent-context/adr-006-serialization.md

@@ -0,0 +1,55 @@
+# Agent Context — ADR-006 (Serialization)
+
+> One-read working context for issue `[v0.3.0] docs — write ADR-006 (Serialization)`.
+> This is a **writing** task. You are recording locked decisions, not making new ones.
+
+## 1. Roadmap excerpts (the decisions you are recording — verbatim)
+
+- **Principle 2.5:** Wire format is explicit and pluggable on structured tools
+  only. Compact JSON default; TOON opt-in *if and only if* the empirical study
+  supports it. `get_docs` stays markdown. *Token economy is empirical, not architectural.*
+- **Principle 2.7:** Layered design with stable contracts — eight layers, the
+  **serializer** being one of them.
+- **Decision 5.3:** Storage stays SQLite + markdown. **TOON-as-storage killed.**
+- **Decision 5.4:** Empirical Claude-tokenizer study **gates** the `format="toon"` decision.
+- **Decision 5.5:** `format` parameter on `search_docs`, `list_versions`,
+  `compare_versions` **only**. JSON default; TOON opt-in. `get_docs` stays markdown.
+- **Decision 5.8:** The study measures **client-side rewrap**, not just raw
+  payload tokens; reports tokens AND latency per tool family.
+
+## 2. Code touch-points (for accuracy — describe, do NOT change)
+
+- Tool results are Pydantic models in `src/mcp_server_python_docs/models.py`
+  (e.g. `GetDocsResult`); tools live in `server.py` and return those models,
+  which FastMCP serializes. The "serializer layer" is the conceptual seam where
+  a structured result becomes a wire string — that's what the `format` parameter
+  will eventually parameterize. You are documenting that seam, not building it.
+- `get_docs` returns markdown content (`GetDocsResult.content`) — this is why it
+  is carved out of the `format` parameter (markdown is already the canonical body).
+
+## 3. Pattern to follow
+
+- There is no `docs/architecture/` ADR yet — you are establishing the house
+  style. Use the exact skeleton embedded in the issue. Keep it tight (1–2 pages).
+- Number/name the file `docs/architecture/ADR-006-serialization.md` to match the
+  roadmap's ADR numbering (ADR-001 and ADR-006 are the first two written).
+
+## 4. Known pitfalls
+
+- **Do not invent.** If you find yourself making a serialization choice that is
+  not in §2 above, that's a pipeline §7 trigger ("cites a design choice not in
+  the issue") — stop and comment.
+- **Do not implement `format`.** That is v0.3.x and is gated by the study.
+- Don't claim a TOON token win — the study hasn't run. The ADR records that TOON
+  is *opt-in and gated*, with the bar being "win holds after client rewrap" (5.8).
+- "Reference architecture" is **not** claimed externally (decision 5.6) — keep
+  the ADR factual, not promotional.
+
+## 5. Decision log
+
+- Final file path: `docs/architecture/ADR-006-serialization.md`
+- Any wording you were unsure mapped to a locked decision (and how you resolved it):
+  none; the ADR records only roadmap principles 2.5 and 2.7 plus decisions
+  5.3, 5.4, 5.5, and 5.8.
+- Open follow-ups: link the ADR to the v0.3.0 TOKEN-STUDY.md once that study
+  exists.

python_docs_mcp_server-0.3.0/.planning/agent-context/cpython-source-sha-pin.md

@@ -0,0 +1,78 @@
+# Agent Context — CPython source SHA pin
+
+> One-read working context for issue `[v0.3.0] ingestion — pin CPython source by commit SHA`.
+> PARTIAL issue: you do the pin + verification; Vision handles the SECURITY.md prose.
+
+## 1. Roadmap excerpt
+
+> **Build-time supply-chain hardening** (roadmap §4, v0.3.0): Pin CPython source
+> by SHA, not by tag. Document the threat model in SECURITY.md (the `build-index`
+> CPython clone is the largest non-runtime attack surface). Verify Sphinx-build
+> environment isolation.
+>
+> **Decision 5.10 (locked):** Build-time supply chain (the `build-index` CPython
+> clone) is an explicit risk area; threat model documented in SECURITY.md;
+> CPython source pinned by SHA.
+
+## 2. Code touch-points
+
+- `src/mcp_server_python_docs/ingestion/cpython_versions.py`
+  - `CPythonDocsBuildConfig(TypedDict)` — add `sha: str`.
+  - `CPYTHON_DOCS_BUILD_CONFIG` — five entries, currently `{"tag": ..., "sphinx_pin": ...}`:
+    `3.10→v3.10.20`, `3.11→v3.11.15`, `3.12→v3.12.13`, `3.13→v3.13.13`, `3.14→v3.14.4`.
+    Add the resolved SHA to each. Resolve with:
+    `git ls-remote https://github.com/python/cpython.git refs/tags/<tag>`
+    (use the dereferenced commit — the `<tag>^{}` line — not the annotated-tag object).
+- `src/mcp_server_python_docs/__main__.py:210–226` — the clone:
+  `git clone --depth 1 --branch config["tag"] https://github.com/python/cpython.git <clone_dir>`.
+  After it, add: `rev = git -C <clone_dir> rev-parse HEAD`; if `rev != config["sha"]`,
+  log a clear error and **abort this version's build** (raise / skip-with-failure —
+  match the existing error-handling style in this function; do not silently continue).
+- `tests/test_ingestion.py:53` — existing assertion
+  `config["tag"].startswith(f"v{version}.")`. Add a sibling assertion that
+  `config["sha"]` matches `^[0-9a-f]{40}$`.
+
+## 3. Patterns to follow
+
+- `tests/test_ingestion.py` iterates `CPYTHON_DOCS_BUILD_CONFIG.items()` for the
+  tag assertion — extend that same loop for the SHA assertion. No new fixtures.
+- The clone block already uses `subprocess.run([...], check=True, capture_output=True, text=True)`
+  — reuse that idiom for the `rev-parse` call.
+
+## 4. Known pitfalls
+
+- **`--branch <tag>` cannot take a raw SHA** on a shallow clone against GitHub by
+  default. Keep the tag-based shallow fetch; make the **SHA a post-clone
+  verification gate**, not the fetch ref. That is the integrity win: a moved/re-tagged
+  tag now fails the build instead of silently changing canonical content.
+- Use the **dereferenced commit SHA** (peeled tag), not the annotated tag object's
+  own SHA — `rev-parse HEAD` after checkout gives the commit; match that.
+- **Do not edit `SECURITY.md`** (forbidden). Draft the threat-model paragraph in
+  the PR body + decision log below for Vision to apply.
+- A full `build-index` clones over the network and takes minutes — do not gate the
+  PR on it. The unit tests cover the config + verification logic offline.
+- Don't bump any tag to a newer CPython point release; pin the SHA of the
+  **current** tag only.
+
+## 5. Decision log
+
+- Resolved SHAs (tag → 40-hex commit), one line each:
+  - 3.10 / v3.10.20 → 842e987df856a5d4db37933c62a3456930a19092
+  - 3.11 / v3.11.15 → 2340a037f7450e70fccfe411e6531afb4d57a312
+  - 3.12 / v3.12.13 → 3bb231a6a5dc02b95658877318bf61501a7209e9
+  - 3.13 / v3.13.13 → 01104ce1beb3135c2e0c01ec835b994c1f55a1c0
+  - 3.14 / v3.14.4 → 23116f998f6789d8c2fbe5ed5b8146854c8c2a4f
+- Where/how the verification aborts on mismatch: after the shallow
+  tag-based clone in `build-index`, `git -C <clone_dir> rev-parse HEAD` is
+  compared to the authoritative config SHA. A mismatch logs the version, tag,
+  actual SHA, and expected SHA, then raises `SystemExit(1)` before Sphinx setup
+  or content ingestion can proceed.
+- **Draft SECURITY.md threat-model paragraph (for Vision to apply):**
+  > The largest build-time supply-chain input is the `build-index` clone of the
+  > upstream CPython repository, which provides the source tree used to generate
+  > canonical documentation content. Each supported CPython docs release is pinned
+  > to the exact commit SHA that its human-readable release tag currently resolves
+  > to; the tag is retained for operator readability, but the SHA is the
+  > authoritative integrity anchor. If a tag is reissued, moved, or otherwise
+  > resolves to different source content, the build fails before Sphinx setup or
+  > content ingestion rather than silently publishing changed documentation.

python_docs_mcp_server-0.3.0/.planning/agent-context/pyyaml-safe-loader-audit.md

@@ -0,0 +1,52 @@
+# Agent Context — PyYAML safe-loader audit
+
+> One-read working context for issue `[v0.3.0] security — audit and document PyYAML safe-loader discipline`.
+
+## 1. Roadmap excerpt
+
+> **PyYAML safe-loader audit** (roadmap §4, v0.3.0): `synonyms.yaml` is loaded at
+> startup; confirm only `yaml.safe_load` is used; document the trust boundary.
+>
+> **Decision 5.11 (locked):** PyYAML safe-loader-only discipline; `synonyms.yaml`
+> is the only YAML input and is packaged with the wheel.
+
+## 2. Code touch-points (already audited for you — verify, then lock in)
+
+- `src/mcp_server_python_docs/server.py:54–57` — loads `data/synonyms.yaml` via
+  `importlib.resources` and `yaml.safe_load(path.read_text())`. ✅ safe.
+- `src/mcp_server_python_docs/ingestion/sphinx_json.py:595–603` — loads the same
+  file via `importlib.resources` + `yaml.safe_load`, then type-checks it is a
+  mapping. ✅ safe.
+- `src/mcp_server_python_docs/data/synonyms.yaml` — the only YAML data input;
+  packaged with the wheel.
+- No other `yaml.load(` / `yaml.unsafe_load(` / custom-`Loader=` call sites were
+  found in `src/`. Your job is to **prove** this with a regression test, not just
+  assert it.
+
+## 3. Patterns to follow
+
+- `tests/test_synonyms.py` already exists — add the discipline test there.
+- A clean way to assert the discipline: walk `src/` `.py` files and fail if any
+  line matches `yaml.load(` or `yaml.unsafe_load(` or `Loader=` (excluding
+  `SafeLoader`). Keep it simple and fast; no new deps.
+- `tests/test_packaging.py` already verifies `synonyms.yaml` ships in the wheel —
+  reference it; you don't need to duplicate that.
+
+## 4. Known pitfalls
+
+- **Do not edit `SECURITY.md`** (forbidden). Capture the trust-boundary write-up
+  in a new `docs/architecture/YAML-TRUST-BOUNDARY.md` and recommend SECURITY.md
+  wording for Vision.
+- The two `safe_load` sites both also exist as `.pyc` in `__pycache__`; grep
+  source dirs only (`src/`, `tests/`), not `__pycache__`.
+- If the codebase is already clean (expected), the deliverable is the **lock-in**
+  (regression test + doc note), not a code fix. Say so plainly in the PR.
+- A literal `yaml.load(` string inside your *test* (as a pattern to search for)
+  is fine and expected — the test asserts it does not appear in non-test `src/`.
+
+## 5. Decision log
+
+- Audit result (clean / findings):
+- Regression test name + what it scans:
+- Trust-boundary doc location:
+- Recommended SECURITY.md wording (for Vision):

python_docs_mcp_server-0.3.0/.planning/agent-context/readme-glama-six-tool-refresh.md

@@ -0,0 +1,54 @@
+# Agent Context — README / glama 6-tool refresh
+
+> One-read working context for issue `[v0.3.0] docs — refresh public surfaces to the 6-tool surface`.
+
+## 1. Roadmap excerpt
+
+> **README + PyPI + glama.json refresh** (roadmap §4, v0.3.0): Reflect the 6-tool
+> surface including `compare_versions`. **Decision 5.9:** adopt as a release-cycle
+> discipline going forward — every release updates the public-facing tool table.
+> Roadmap §3 notes the surface "still lists 5 in some surfaces."
+
+## 2. Code / file touch-points
+
+- **Tool order of truth:** `src/mcp_server_python_docs/server.py`, the `@mcp.tool`
+  declarations in this order: `search_docs` (≈297), `get_docs` (≈318),
+  `lookup_package_docs` (≈341), `list_versions` (≈358), `detect_python_version`
+  (≈372), `compare_versions` (≈394).
+- `README.md`:
+  - `## Tools` section at **line ~178**: already a six-row table in the correct
+    order. Verify, don't churn it.
+  - **Stale badge near the top:** `MCP%20Registry-v0.1.4`. Current published
+    registry/PyPI version is **0.2.1**. This is the concrete fix and the only
+    allowed edit above the first install code block.
+  - Hero section = everything **above the first install code block** (~line 125)
+    — FORBIDDEN except the stale registry/version badge above.
+- `glama.json`: `description` field (prose, no tool list today).
+- `.github/RELEASE.md`: add one checklist line for decision 5.9.
+
+## 3. Patterns to follow
+
+- `tests/test_packaging.py` asserts packaging consistency — run it; if you add a
+  surface, see whether a cheap assertion belongs there (optional, not required).
+- Badge lines in `README.md` are markdown image links; match the existing style
+  when updating the version.
+
+## 4. Known pitfalls
+
+- **False positive — do NOT "fix":** `.github/INTEGRATION-TEST.md:139` says
+  "all five versions". That is the **five Python versions (3.10–3.14)**, not five
+  tools. Leave it alone.
+- **PyPI short description is forbidden.** It comes from `pyproject.toml`
+  `[project].description`. If it's stale, comment — do not edit `pyproject.toml`.
+  (The README *body* you edit *is* the PyPI long description on the next release,
+  which is fine; only the hero is off-limits.)
+- `README.md`, `.github/RELEASE.md`, and `glama.json` are all CODEOWNERS-owned.
+  Your PR will request maintainer review by design — note it, don't fight it.
+- Don't bump `server.json` / package versions here; that's release-managed.
+
+## 5. Decision log
+
+- Badge: pinned to `0.2.1` vs made version-agnostic — which and why:
+- Surfaces audited and their state (README Tools / glama / server.json):
+- RELEASE.md checklist line added:
+- Anything left for the maintainer (e.g. stale pyproject short description):

python_docs_mcp_server-0.3.0/.planning/agent-context/zstd-cache-codec.md

@@ -0,0 +1,71 @@
+# Agent Context — zstd cache codec
+
+> One-read working context for issue `[v0.3.0] cache — add zstd codec layer`.
+> Everything you need is here; do not go fishing in `.planning/` archive material.
+
+## 1. Roadmap excerpt (the goal — do not re-derive)
+
+> **Workstream J — app-level zstd cache compression** (roadmap §4, v0.3.0):
+> Targets the retrieved-docs cache *value column only*. Trained dict on a
+> representative `get_docs` corpus. Codec column for forward-compat. Expected
+> ratio strong because zstd's dictionary mode is especially effective on small
+> correlated records — exactly the cache-entry shape.
+>
+> **Decision 5.7 (locked):** App-level zstd on retrieved-docs cache, *no gate*.
+> Versioned codec column for forward-compat.
+
+## 2. Code touch-points (file paths + symbols)
+
+- `src/mcp_server_python_docs/services/persistent_cache.py`
+  - `retrieved_docs_cache` table — created inline with `CREATE TABLE IF NOT EXISTS` at **line ~47**. Columns today: `index_fingerprint, version, slug, anchor, max_chars, start_index, result_json TEXT, created_at`. PK is the first six columns.
+  - `put(...)` — **line ~118**, `INSERT OR REPLACE ... result_json` = `result.model_dump_json()`.
+  - `get(...)` — **line ~80**, `SELECT result_json ...` then `GetDocsResult.model_validate_json(row[0])`.
+  - This is **best-effort**: every read/write is wrapped in try/except and the cache disables cleanly (`self._conn = None`) on error. Preserve that posture.
+- **New module:** `src/mcp_server_python_docs/cache/codec.py` (create the `cache/` package with `__init__.py`). Public API the pipeline §4 example expects:
+  - `list_supported() -> list[str]` → `['none', 'zstd', 'zstd-dict-v1']`
+  - `encode(text: str, codec: str, *, dictionary=None) -> bytes`, `decode(blob: bytes, codec: str, *, dictionary=None) -> str`.
+- **Tests:** new dir `tests/cache/` with `__init__.py` and `test_codec.py`.
+
+## 3. Existing test patterns to follow
+
+- `tests/test_persistent_docs_cache.py` shows the established cache-test idiom:
+  the `_cache(tmp_path, marker)` helper builds an index fingerprint file +
+  `PersistentDocsCache`, and `populated_db` (a fixture from `tests/conftest.py`)
+  provides a live SQLite index. Reuse this shape for the no-regression test.
+- The "survives restart" test (`test_cache_survives_restart_and_miss_falls_back`)
+  is the exact pattern for your "value reads back identically after restart" criterion:
+  build a `PersistentDocsCache`, write, construct a *second* instance on the same
+  files, assert `hits == 1` and equality.
+- Tests are plain `pytest` functions, `from __future__ import annotations`, type-annotated args. Match that.
+
+## 4. Known pitfalls
+
+- **The cache table is NOT `storage/schema.sql`.** `schema.sql` is the canonical
+  *index* schema and is forbidden territory. The cache table is owned by
+  `persistent_cache.py` and is yours to evolve per 5.7. Do not confuse them.
+- **Existing on-disk caches lack the new column.** `CREATE TABLE IF NOT EXISTS`
+  will *not* add a column to an existing table. Detect the column
+  (`PRAGMA table_info(retrieved_docs_cache)`) and `ALTER TABLE ... ADD COLUMN
+  compression TEXT NOT NULL DEFAULT 'none'` when missing, inside the same
+  try/except that already tolerates a broken cache.
+- **Value column type.** `result_json` is `TEXT`. Compressed output is `bytes`.
+  Either store the blob in a new `BLOB` column and keep `result_json` for the
+  `'none'` path, or store all payloads as `BLOB` and record the codec. Simplest
+  forward-compatible design: keep `result_json` semantics for `'none'`, add a
+  `result_blob BLOB` for compressed codecs, and let `compression` select which
+  column to read. Document whichever you choose in the decision log below.
+- **`zstandard` must already be importable** (maintainer pre-req). If
+  `import zstandard` fails, STOP and comment — do not edit `pyproject.toml`/`uv.lock`.
+- **`zstd-dict-v1` has no production dictionary in this issue.** Make the codec
+  *work* only when an explicit dictionary object is supplied by tests. The
+  cache's default production codec is `'zstd'`. Shipping a trained dictionary
+  artifact is a separate, Vision-gated follow-up.
+- Decode must dispatch off the stored `compression` value, never off the current
+  default — otherwise old `'none'` rows break the day the default flips.
+
+## 5. Decision log (fill this in as you work)
+
+- Chosen value-storage layout (`result_blob` vs reuse `result_json`):
+- How `zstd-dict-v1` round-trips in tests (dict training approach):
+- Default production codec wired into `put()`:
+- Anything you deferred or escalated: