Remove docs MCP from the default overlay

.cursor/cloud-install.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # Cloud Agent snapshot bootstrap (idempotent).
 # Torch stays out of requirements.txt so local `make check` stays pyyaml-only.
+# No docs MCP server is installed or allowlisted.
 set -euo pipefail
 export PATH="${HOME}/.local/bin:${PATH}"
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
@@ -9,15 +10,12 @@ cd "$ROOT"
 python3 -m pip install --user -r requirements.txt
 python3 -m pip install --user --index-url https://download.pytorch.org/whl/cpu torch
 python3 -m pip install --user diffusers
-bash "$ROOT/.cursor/install-docs-mcp.sh"
-python3 "$ROOT/tools/docs_mcp_server.py" --selftest
+python3 "$ROOT/tools/docs_mcp_server.py" --query "set_timesteps" >/dev/null
 python3 - <<'PY'
 import torch
 import diffusers
 
 print("torch", torch.__version__, "cuda", torch.cuda.is_available())
 print("diffusers", diffusers.__version__)
 PY
-test -x "${HOME}/.local/bin/diffusers-docs-mcp"
-echo "shim: ${HOME}/.local/bin/diffusers-docs-mcp"
 echo "cloud-install: ok"

.cursor/commands/scaffold.md

@@ -5,15 +5,25 @@ Usage: `/scaffold <component> <Name>`
 - `$1` = component. Today the registry ships `scheduler`. Adding `model` or `pipeline` is a data change (see `templates/README.md`), not a new command.
 - `$2` = PascalCase name **without** the type suffix. Example: `EulerLite` → class `EulerLiteScheduler`, file `scheduling_euler_lite.py`. If those files already exist, pick a new unused `$2`.
 
-Done is what `conventions/rules.yaml` checks **and**, on a real library checkout, what the library's own CI checks. Copy the templates. Do not start from a blank file, from library scheduler source, or from a docs search.
+Done is what `conventions/rules.yaml` checks **and**, on a real library checkout, what the library's own CI checks. Copy the templates. Do not start from a blank file or from library scheduler source.
 
-## 0. Ground in the registry
+## 0. Ground in the registry (and the library guide)
 
 Read `conventions/rules.yaml`. Blocking ids for this contribution: SCHED001,
 SCHED002, SCHED003, REPRO001, DEVICE001, DEPR001, MUT001, TEST001, TEST002.
 
-The templates already satisfy them. Stay inside `.cursorignore`. Do not read or
-copy `examples/candidate_scheduler/` (known-bad fixture).
+On a library checkout, also read root `AGENTS.md` and `.ai/` (do not overwrite
+them) plus the reference source those files name. Optional keyword search:
+
+```bash
+python3 tools/docs_mcp_server.py --query "set_timesteps"
+```
+
+That CLI is a fallback, not a deliverable. Default `.cursor/mcp.json` has no
+servers.
+
+The templates already satisfy the registry. Stay inside `.cursorignore`. Do not
+read or copy `examples/candidate_scheduler/` (known-bad fixture).
 
 ## 1. Name the files
 

.cursor/commands/search-docs.md

@@ -1,13 +1,10 @@
-# /search-docs — grounded diffusers docs (MCP fallback)
+# /search-docs — optional keyword search of bundled / checkout docs
 
 Usage: `/search-docs <query>`
 
-Cloud Agents **do not load** project `.cursor/mcp.json`, and Cloud stdio
-**does not expand** `${workspaceFolder}` (that is why the tool goes missing).
-If `search_docs` is not in your tool list, this command is the connection.
-The Cloud dropdown paste is `python3 -u .cursor/mcp-diffusers-docs.py`.
-
-Run this exactly (do not invent an answer from memory):
+Prefer `conventions/rules.yaml` and, on the library, root `AGENTS.md` + `.ai/`
+plus the reference source those files name. Default `.cursor/mcp.json` has no
+servers.
 
 ```bash
 python3 tools/docs_mcp_server.py --query $1
@@ -22,6 +19,3 @@ python3 tools/docs_mcp_server.py --query "scheduler set_timesteps step Scheduler
 Then cite the provenance line (`bundled snapshot` vs a real checkout) and the
 matching section. If the snippets miss the contract, also read
 `conventions/rules.yaml` — the **gate** is authoritative.
-
-If the `diffusers-docs` / `search_docs` MCP tool **is** available, call that
-instead of the CLI; it is the same server.

.cursor/environment.json

@@ -1,13 +1,6 @@
 {
   "install": "bash .cursor/cloud-install.sh",
-  "start": "bash .cursor/install-docs-mcp.sh",
   "repositoryDependencies": [
     "github.com/alex-16moro/diffusers"
-  ],
-  "mcpServerAllowlist": [
-    {
-      "name": "diffusers-docs",
-      "command": "diffusers-docs-mcp"
-    }
   ]
 }

.cursor/mcp.json

@@ -1,12 +1 @@
-{
-  "mcpServers": {
-    "diffusers-docs": {
-      "type": "stdio",
-      "command": "python3",
-      "args": ["-u", ".cursor/mcp-diffusers-docs.py"],
-      "env": {
-        "PYTHONUNBUFFERED": "1"
-      }
-    }
-  }
-}
+{"mcpServers":{}}

.cursor/rules/00-conventions.mdc

@@ -14,8 +14,9 @@ code that violates a **block** rule will fail the build.
 The first contribution is what `conventions/rules.yaml` checks. Copy the
 templates (`/scaffold`) and stop at 0 blocking findings from
 `tools/convention_check.py` on the new files. Do not add files the
-registry does not scan. Docs search (`search_docs` / `/search-docs`) is
-optional and is not a deliverable.
+registry does not scan. Ground in this registry and, on the library,
+`.ai/` plus reference source. Optional:
+`python3 tools/docs_mcp_server.py --query "..."` — not a deliverable.
 
 Do not pull in code or context from outside this repo's approved
 boundaries (see `.cursorignore`).

.cursor/skills/search-docs/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: search-docs
-description: Ground answers in this repo's diffusers docs (same corpus as the search_docs MCP tool). Use before scaffolding or answering how the library does X, especially when the search_docs MCP tool is missing.
+description: Optional keyword search of this repo's diffusers docs via docs_mcp_server.py --query. Prefer the registry, .ai/, and reference source. Use before scaffolding or answering how the library does X.
 ---
 
 # Search bundled diffusers docs
 
-Cloud Agents often do not load project `.cursor/mcp.json`, so `search_docs` may
-be absent until the Cloud MCP dropdown is `diffusers-docs-mcp` (or
-`python3 -u .cursor/mcp-diffusers-docs.py`). This skill is the same grounding
-path.
+Default `.cursor/mcp.json` has no servers. Ground first in
+`conventions/rules.yaml` and, on the library, `AGENTS.md` + `.ai/` plus
+reference source. This skill is an optional CLI fallback.
 
 Run (do not invent the contract from memory):
 
@@ -24,6 +23,3 @@ python3 tools/docs_mcp_server.py --query "scheduler set_timesteps step Scheduler
 
 Cite the provenance line (`bundled snapshot` vs a real checkout). If snippets
 miss the contract, read `conventions/rules.yaml` — the **gate** is authoritative.
-
-If the MCP tool `search_docs` **is** in your tool list, call that instead; it is
-the same server (`python3 -u .cursor/mcp-diffusers-docs.py` / dashboard stdio).

.github/workflows/convention-gate.yml

@@ -19,8 +19,8 @@ jobs:
         run: python tools/build_projections.py && git diff --exit-code
       - name: Scheduler contract re-verify
         run: python tools/verify_scheduler_contract.py
-      - name: MCP doc-server self-test
-        run: python tools/docs_mcp_server.py --selftest
+      - name: Docs CLI --query fallback
+        run: python tools/docs_mcp_server.py --query "set_timesteps"
       - name: Contract tests
         run: python -m unittest discover -s tests -t .
       - name: Machine-readable report

AGENTS.md

@@ -7,8 +7,9 @@ This repo uses convention-as-code. The authoritative rules live in
 `conventions/rules.yaml` and are enforced by `tools/convention_check.py`.
 Before opening a PR, run `make check` and fix every blocking finding.
 The first contribution is the registry + templates, not a docs page or
-a copied library scheduler. Optional docs search: `search_docs` MCP,
-`/search-docs`, or `python3 tools/docs_mcp_server.py --query "..."`.
+a copied library scheduler. Grounding is the registry and (on the
+library) `.ai/` plus reference source. Optional docs CLI:
+`python3 tools/docs_mcp_server.py --query "..."`.
 
 ## Conventions
 

Makefile

@@ -12,8 +12,8 @@ help:
 	@echo "  make check      Run the convention gate on the whole repo (sets exit code)"
 	@echo "  make check-json Same, machine-readable (CI / dashboards)"
 	@echo "  make test       Run the contract tests (zero third-party installs needed)"
-	@echo "  make mcp        Self-test the diffusers-docs MCP server (Cursor handshake)"
-	@echo "  make demo       Catch the bad scheduler, pass the good one, MCP, tests"
+	@echo "  make mcp        Optional docs CLI: docs_mcp_server.py --query set_timesteps"
+	@echo "  make demo       Catch the bad scheduler, pass the good one, docs CLI, tests"
 	@echo "  make demo-contribute  First-contribution journey (KEEP=1 leaves files)"
 	@echo "  make demo-contribute-clean  Remove the EulerLite contribution files"
 	@echo "  make demo-maintain  Prove req #4: add a rule, rebuild, watch it propagate"
@@ -28,22 +28,25 @@ doctor:
 	@command -v $(PYTHON) >/dev/null || (echo "Need python3 on PATH"; exit 1)
 	@$(PYTHON) -c "import yaml" 2>/dev/null || (echo "Need PyYAML: pip install -r requirements.txt"; exit 1)
 	@test -f .cursor/hooks.json && test -f .cursor/mcp.json && test -f .cursor/commands/scaffold.md && test -f .cursorignore \
-		&& test -f .cursor/mcp-diffusers-docs.py && test -f .cursor/mcp-diffusers-docs.sh \
+		&& test ! -e .cursor/mcp-diffusers-docs.py && test ! -e .cursor/mcp-diffusers-docs.sh \
+		&& test ! -e .cursor/install-docs-mcp.sh && test ! -e overlay/mcp.optional.json \
 		&& test -f .cursor/commands/search-docs.md && test -f .cursor/skills/search-docs/SKILL.md \
-		|| (echo "Missing Cursor wiring (hooks, mcp launcher, scaffold, search-docs, .cursorignore)"; exit 1)
-	@! grep -q workspaceFolder .cursor/mcp.json || (echo "mcp.json must not use workspaceFolder vars (Cloud stdio does not expand them)"; exit 1)
-	@test -f tools/attach_library.py && test -f overlay/OVERLAY.md \
-		&& test -f overlay/mcp.json && test -f overlay/mcp.optional.json \
+		|| (echo "Missing Cursor wiring or leftover docs-MCP launchers still present"; exit 1)
+	@$(PYTHON) -c "import json, pathlib; c=json.loads(pathlib.Path('.cursor/mcp.json').read_text()); assert c.get('mcpServers')=={}, c" \
+		|| (echo ".cursor/mcp.json must be {\"mcpServers\":{}}"; exit 1)
+	@test -f tools/attach_library.py && test -f overlay/OVERLAY.md && test -f overlay/mcp.json \
 		|| (echo "Missing overlay attach tooling"; exit 1)
-	@$(PYTHON) -c "import json, pathlib; c=json.loads(pathlib.Path('overlay/mcp.json').read_text()); s=c['mcpServers']; assert 'diffusers-docs' in s and 'huggingface' not in s, c; assert s['diffusers-docs']['args']==['-u','.cursor/mcp-diffusers-docs.py'], s" \
-		|| (echo "overlay/mcp.json must be stdio diffusers-docs only (no Hub HTTP)"; exit 1)
-	@$(PYTHON) -c "import json, pathlib; s=json.loads(pathlib.Path('overlay/mcp.optional.json').read_text())['mcpServers']; assert 'diffusers-docs' in s and 'huggingface' in s, s" \
-		|| (echo "overlay/mcp.optional.json must list opt-in servers"; exit 1)
-	@$(PYTHON) tools/docs_mcp_server.py --selftest >/dev/null
+	@$(PYTHON) -c "import json, pathlib; c=json.loads(pathlib.Path('overlay/mcp.json').read_text()); assert c.get('mcpServers')=={}, c" \
+		|| (echo "overlay/mcp.json must be {\"mcpServers\":{}}"; exit 1)
+	@$(PYTHON) -c "import json, pathlib; e=json.loads(pathlib.Path('.cursor/environment.json').read_text()); assert 'mcpServerAllowlist' not in e and 'start' not in e, e" \
+		|| (echo "kit environment.json must not allowlist or start a docs MCP"; exit 1)
+	@$(PYTHON) -c "import json, pathlib; e=json.loads(pathlib.Path('overlay/environment.json').read_text()); assert 'mcpServerAllowlist' not in e and 'start' not in e, e" \
+		|| (echo "overlay environment.json must not allowlist or start a docs MCP"; exit 1)
+	@$(PYTHON) tools/docs_mcp_server.py --query "set_timesteps" >/dev/null
 	@test -f tools/grokbot_sim.py && test -f tools/verify_scheduler_contract.py \
 		&& test -f agents/grokbot-profiles.md && test -f .cursor/agents/grokbot-qa.md \
 		|| (echo "Missing GrokBot / contract-verify tooling"; exit 1)
-	@echo "doctor OK: $(PYTHON) + PyYAML + Cursor files + MCP self-test + overlay"
+	@echo "doctor OK: $(PYTHON) + PyYAML + empty mcpServers + docs CLI --query + overlay"
 
 attach:
 	$(PYTHON) tools/attach_library.py --target $(or $(TARGET),../diffusers)
@@ -77,18 +80,18 @@ test:
 	$(PYTHON) -m unittest discover -s tests -t . -v
 
 mcp:
-	$(PYTHON) tools/docs_mcp_server.py --selftest
+	$(PYTHON) tools/docs_mcp_server.py --query "set_timesteps"
 
 # The live-demo sequence: gate catches the from-memory scheduler (nonzero exit,
-# shown), then passes the scaffolded one, then the MCP grounds an answer, then
+# shown), then passes the scaffolded one, then the optional docs CLI, then
 # the contract tests are green.
 demo:
 	@echo "\n========== 1. A new engineer's first-cut scheduler =========="
 	-$(PYTHON) tools/convention_check.py examples/candidate_scheduler
 	@echo "\n========== 2. The scaffolded, convention-correct version =========="
 	$(PYTHON) tools/convention_check.py examples/scaffolded_scheduler
-	@echo "\n========== 3. Grounded doc-search via the MCP server =========="
-	$(PYTHON) tools/docs_mcp_server.py --selftest
+	@echo "\n========== 3. Optional docs CLI fallback (--query) =========="
+	$(PYTHON) tools/docs_mcp_server.py --query "set_timesteps"
 	@echo "\n========== 4. Contract tests (zero install) =========="
 	$(PYTHON) -m unittest discover -s tests -t . -v
 	@echo "\n========== 5. GrokBot QA simulation (read-side, does not gate) =========="