initial

.github/instructions/docs.instructions.md

@@ -0,0 +1,118 @@
+---
+name: Documentation lookups via context7 MCP
+description: How and when to use the context7 MCP server for library documentation
+applyTo: "**/*.py,**/*.md,**/*.toml,**/*.yaml,**/*.yml"
+---
+
+# Documentation lookups — use context7
+
+When you are uncertain about a library's API, **call the `context7` MCP server before writing code**. Do not rely on training-data memory. Pydantic, FastMCP, Typer, httpx, and pytest all evolve quickly; what was true two releases ago is often wrong now.
+
+## When to use context7
+
+Use it **before** writing code involving any of these:
+
+* **FastMCP / MCP Python SDK** — `@mcp.tool()` signatures, `ToolAnnotations`, `mcp.run(transport=...)`, resource and prompt decorators, server lifecycle, streamable-HTTP setup.
+* **Pydantic v2** — `BaseModel`, `Field`, `ConfigDict`, `model_validator`, `field_validator`, `model_dump` / `model_dump_json`, discriminated unions, `Annotated[...]` with validators.
+* **Typer** — `Typer()` apps, `typer.Option`, `typer.Argument`, sub-apps via `add_typer`, callbacks, exit codes, testing with `CliRunner`.
+* **httpx** — `AsyncClient`, timeouts, transports, retries, `Response` API.
+* **respx** — mocking httpx, `respx.mock`, `route.mock`, match patterns.
+* **msgpack** — packing/unpacking, type extensions, raw vs string mode.
+* **base64** — `urlsafe_b64encode`, padding handling.
+* **pytest** / **pytest-asyncio** — fixtures, parametrize, async tests, markers, `tmp_path`, `monkeypatch`.
+* **BeautifulSoup** / **lxml** — selectors, parser flavors, element traversal.
+* **typer.testing.CliRunner** — invoking apps, asserting on stdout/stderr/exit codes.
+
+Use it **also** when:
+
+* A test fails with an error like `AttributeError: 'BaseModel' object has no attribute 'dict'` (Pydantic v1 vs v2 confusion).
+* You see a `DeprecationWarning` from a third-party library and aren't sure of the modern replacement.
+* You're about to copy a code pattern from memory that feels "old".
+
+## When NOT to use it
+
+* Pure Python stdlib (`json`, `pathlib`, `dataclasses`, `typing`) — these are stable and well-known.
+* Project-internal modules — read the source.
+* Generic programming questions ("what's a list comprehension") — use your own knowledge.
+* FINN / Eiendom.no API behavior — these are not in context7. Use fixtures from prior runs in `tests/fixtures/` and the endpoint notes in `PRD.md` §9.
+
+## How to use it
+
+Two-step pattern:
+
+### 1. Resolve the library ID
+
+```
+context7:resolve-library-id(query="fastmcp")
+context7:resolve-library-id(query="pydantic")
+context7:resolve-library-id(query="typer")
+```
+
+Returns the canonical library ID (e.g. `pydantic/pydantic`, `fastapi/typer`). Pick the most-starred / official-looking match.
+
+### 2. Query the docs
+
+```
+context7:query-docs(
+    context7CompatibleLibraryID="pydantic/pydantic",
+    topic="field validators v2 mode after",
+    tokens=3000,
+)
+```
+
+* **Keep the topic focused.** "Pydantic v2 field validators with mode=after on Optional[str]" beats "Pydantic validation".
+* **Cap tokens** to roughly what you need (1500–4000 is usually plenty). The default is fine for most calls.
+* **Use library-specific terminology** in the topic — "discriminator field" for Pydantic, "tool annotations" for FastMCP, "sub-apps" for Typer.
+
+### Worked examples
+
+**Q: How do I declare a FastMCP tool with read-only annotations?**
+
+```
+context7:resolve-library-id(query="modelcontextprotocol python sdk")
+context7:query-docs(context7CompatibleLibraryID="<resolved id>",
+                    topic="FastMCP @mcp.tool ToolAnnotations readOnlyHint")
+```
+
+**Q: How do I write a Pydantic v2 model_validator that runs after field validation?**
+
+```
+context7:resolve-library-id(query="pydantic")
+context7:query-docs(context7CompatibleLibraryID="pydantic/pydantic",
+                    topic="model_validator mode='after' v2")
+```
+
+**Q: How do I mock an async httpx POST with respx?**
+
+```
+context7:resolve-library-id(query="respx")
+context7:query-docs(context7CompatibleLibraryID="<resolved id>",
+                    topic="respx mock async httpx POST json body")
+```
+
+**Q: How do I add a Typer sub-app for `cache` commands?**
+
+```
+context7:resolve-library-id(query="typer")
+context7:query-docs(context7CompatibleLibraryID="<resolved id>",
+                    topic="Typer add_typer sub-application command groups")
+```
+
+## After the lookup
+
+* Cite or summarize what you found in a code comment **only when** the snippet documents a non-obvious API choice — otherwise the code is enough.
+* If context7 returns nothing useful, fall back to:
+  1. The library's official docs site.
+  2. The library's repo `README` / `examples/`.
+  3. The smallest possible spike (a 5-line script in the venv) to verify behavior.
+
+## Anti-patterns
+
+* **Don't** invent a method signature from memory and hope. If you're not 100% sure of an API, look it up.
+* **Don't** copy patterns from old Stack Overflow answers without verifying — Pydantic, FastMCP, and Typer all had breaking changes recently.
+* **Don't** silence a warning instead of fixing the deprecation. Look up the modern API.
+* **Don't** query context7 for FINN or Eiendom.no — those endpoints aren't in any public docs index. Use `tests/fixtures/` and `PRD.md` §9.
+
+## Network configuration note
+
+`context7` is configured as a connected MCP server in this environment. If a call fails with a connection error, surface it clearly — don't fall back to guessing.