docs(dev): Record three gp-sphinx defects

Browsing the built site surfaced three defects that belong to the docs
toolchain rather than to this server. Two are pre-alpha-old and live on the
published site; none is worked around here, because a downstream patch would
hide a defect in code this project does not own.

sphinx-gp-llms emits a Markdown-twin link for every page while writing twins
only for source documents, so genindex, py-modindex and search each link to a
file that never exists -- the only three broken links among 228.

sphinx-inline-tabs' tabs.js never reaches _static although its stylesheet
does, so 103 pages log a 404. Switching survives on CSS alone; cross-group
sync does not, which is visible on the installation page. The cause is not
isolated and the entry says so rather than guessing.

sphinx-autodoc-fastmcp strips FastMCP's prompt-argument note by matching the
FastMCP 3 wording, which FastMCP 4 changed, so the note now renders seven
times on the prompts page.

Author: tony

CHANGES

@@ -83,6 +83,13 @@ depends on the client, since measured agent CLIs do not send
 `completion/complete`. The retired claims are pinned as forbidden text, so the
 page cannot drift back to underclaiming a shipped feature.
 
+**Defects owned by a dependency are written down**
+
+{ref}`upstream-issues` gains three: Markdown-twin links emitted for generated
+pages that have no twin, `tabs.js` never reaching `_static` while its
+stylesheet does, and FastMCP 4's reworded prompt-argument note surviving into
+the rendered prompts page. None is worked around here.
+
 **The toolset migration notes reach the migration page**
 
 The 0.1.0a21 notes mapping the retired tiers onto `inspect`, `manage`,

docs/dev/upstream-issues.md

@@ -45,3 +45,89 @@ rather than being deliberate.
 **Workaround.** None applied here. Narrowing it downstream would mean catching
 and re-raising in every handler, which trades a wrong error code for a worse
 one — the middleware exists precisely so handlers do not do that.
+
+## sphinx-gp-llms: Markdown-twin links are emitted for pages that have no twin
+
+**Status.** Drafted, not filed.
+
+**Summary.** Two places disagree about which pages get a Markdown twin.
+`sphinx_gp_llms/__init__.py` sets `context["llms_md_url"] = pagename + ".md"`
+on `html-page-context`, which fires for every page. `_md_twins.py` writes the
+twins by iterating `app.env.found_docs`, which holds only real source
+documents. Sphinx's generated pages are not source documents, so they receive
+the link without the file.
+
+**Why it matters.** Every site using the extension ships exactly three broken
+links — `genindex`, `py-modindex` and `search`. Sphinx does not warn, because
+these are raw template links rather than resolved references, so a `-W` build
+stays green and no gate catches them.
+
+**Observed on this server.** Of 228 unique internal links across 129 built
+pages, these three are the only broken ones. The per-page link works
+everywhere else: `/index.md` resolves.
+
+**Suggested fix.** Set `llms_md_url` only when a twin was actually written —
+gate it on `pagename in app.env.found_docs`, or on the same exclusion logic
+`_md_twins` already applies.
+
+**Workaround.** None applied here.
+
+## sphinx-inline-tabs: `tabs.js` is never copied, though `tabs.css` is
+
+**Status.** Drafted, not filed. Cause not isolated.
+
+**Summary.** `sphinx_inline_tabs` ships `tabs.css` and `tabs.js` side by side
+in one package static directory and registers both from `setup()`. Only the
+stylesheet reaches `_static`. The built `tabs.css` is byte-identical to the
+package's copy, so the static directory is being copied and the script alone
+is dropped.
+
+**Why it matters.** Every page that loads the script — 103 of 129 here —
+logs a 404. The published site has the same defect.
+
+**Observed on this server.** Tab *switching* still works, because the
+extension drives it through radio inputs and `:checked` rather than script.
+What breaks is cross-group synchronisation, which is the script's job: on the
+installation page, choosing `pip` in the first `uv`/`pip` group leaves the
+second group on `uv`, so two blocks describing one workflow disagree.
+
+**Suggested fix.** Unknown. `sphinx-vite-builder` hooks before
+`copy_static_files` rather than filtering it, nothing in the toolchain
+touches `js_files` or `script_files`, and the theme's only reference to
+inline-tabs concerns bundled CSS. Isolating this needs someone with context
+on the asset pipeline.
+
+**Workaround.** None applied here. Vendoring the script into this project's
+own `_static` would hide a defect that is live in production and is not this
+project's to own.
+
+## sphinx-autodoc-fastmcp: FastMCP 4's prompt-argument note is no longer stripped
+
+**Status.** Drafted, not filed.
+
+**Summary.** FastMCP appends a schema hint to a prompt argument's
+description, and the collector strips it by matching the FastMCP 3 wording as
+a literal prefix. FastMCP 4 reworded it, so the note now survives into the
+rendered page. Both wordings need matching rather than one replacing the
+other, because one released collector serves projects on either major.
+
+**Why it matters.** The note renders as documentation. It lands inside the
+prompt's argument table, appended to the authored description, so a reader
+sees machine text presented as prose.
+
+**Observed on this server.** Seven occurrences of the FastMCP 4 wording on
+the built prompts page and none of the FastMCP 3 wording. The docs build
+stays green and emits no warning, so no gate here catches it. A row reads:
+"The shell command to run. Provide a value matching the following JSON
+schema: ... Encode non-string values as JSON."
+
+**Suggested fix.** Match both wordings. FastMCP 3 emits "Provide as a JSON
+string matching the following schema:"; FastMCP 4 emits "Provide a value
+matching the following JSON schema:".
+
+**Also.** The JSON inside that note renders with typographic quotes, because
+MyST's `replacements` extension reaches it. Stripping the note removes the
+symptom here, but any authored argument description containing literal JSON
+would be rewritten the same way.
+
+**Workaround.** None applied here.