mounting docs

.github/instructions/authoring.instructions.md

@@ -0,0 +1,17 @@
+---
+name: Authoring Content
+description: "Use when editing Markdown under docs/. Routes authors to the canonical docs ownership, layout, and symlink guidance."
+applyTo: 'docs/**/*.md'
+---
+
+For edits under `docs/`, use the [Authoring Guide](../../docs/authoring.md) as the entry point for content placement and contracts.
+
+For source-tree ownership, symlink, packaging, or runtime questions, follow [Source Tree Ownership](../../docs/authoring.md). Treat that section as authoritative instead of restating its guidance here.
+
+
+Primary references:
+- [Skill contract](../../docs/contracts/skill_contract.md)
+- [Prompt contract](../../docs/contracts/prompt.md)
+- [Frontmatter contract](../../docs/contracts/frontmatter.md)
+- [URI contract](../../docs/contracts/uris.md)
+- [Zensical documentation authoring skill](../../docs/skills/zensical-docs/SKILL.md)

.github/instructions/pytesting.instructions.md

@@ -0,0 +1,18 @@
+---
+name: Pytest Scaffolding Guidance
+description: Route tests edits to the Personal MCP pytesting resource.
+applyTo: 'tests/**'
+---
+
+When editing files under `tests/`, use `resource://skills/pytesting/document` as the primary guidance source for test scaffolding and pytest authoring decisions.
+
+Execution pattern:
+
+1. Load `resource://skills/pytesting/document` first.
+2. Apply only the portions relevant to the file being edited.
+3. Keep tests focused, deterministic, and aligned with repository conventions.
+4. Include source-document links for any feature-level recommendation.
+
+If task intent is ambiguous, ask one clarifying question before editing.
+
+Be sure to also refer to the [testing page](../../docs/testing.md) page for design detail

.github/instructions/vscode-configuration.instructions.md

@@ -0,0 +1,19 @@
+---
+name: VS Code Configuration
+description: Route .vscode edits to the Personal MCP VS Code configuration skill resource.
+applyTo: '.vscode/**'
+---
+
+When editing files under `.vscode/`, use `resource://skills/vscode-configuration/document` as the primary guidance source.
+
+Execution pattern:
+
+1. Load `resource://skills/vscode-configuration/document` first.
+2. Select only the matching reference page for the current file type:
+   - `launch.json` -> debug launch configurations.
+   - `tasks.json` -> tasks.json project tasks.
+   - `mcp.json` -> mcp.json MCP server configuration.
+3. Prefer the smallest safe config change and keep settings explicit.
+4. Include source-document links for any feature-level recommendation.
+
+If task intent is ambiguous, ask one clarifying question before editing.

.github/instructions/zensical-docs.instructions.md

@@ -7,3 +7,7 @@ applyTo: '**/*.md'
 When editing Markdown files in this repository, use the Zensical docs resource `resource://skills/zensical-docs/document` for relevant documentation authoring guidance.
 
 Prefer Zensical-native documentation conventions when they cover the need cleanly, while preserving expected MkDocs compatibility unless the Zensical guidance intentionally diverges.
+
+Always check to make sure the entries in `/home/john/Documents/prompts/zensical.toml` are up to date with any changes.
+
+Also ensure that top-level pages specify icons in their front matter

.github/prompts/plan-fastMcpServerGreenfield.prompt.md

@@ -8,7 +8,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
 3. Phase 1: Define URI contract with explicit break-and-replace policy. Recommend resource://catalog/skills_index, resource://catalog/skills/{skill_id}, resource://skills/{skill_id}/document, resource://skills/{skill_id}/references/{ref_id}, and resource://docs/{path*}. Evolving URIs and reference ids requires direct replacement, with no aliases or compatibility shims. Depends on steps 1-2. Deliverable: update the current docs/ directory with the finalized URI contract and break-and-replace policy from this step.
 4. Phase 2: Build a docs registry loader that reads packaged docs via importlib.resources.files(...) Traversable APIs, parses SKILL.md frontmatter, validates schema, and creates an in-memory registry keyed by skill_id. Fail fast for duplicate ids, missing files, broken reference mappings, or invalid depends_on. Depends on steps 2-3.
 5. Phase 2: Register FastMCP resources from the registry using RFC6570 templates (including wildcard paths where appropriate), read-only/idempotent annotations, explicit mime types, and on_duplicate_resources="error" for startup safety. Depends on step 4.
-6. Phase 2: Add discovery surfaces as resources first, then tool fallback. Keep catalog discovery in resources, then add ResourcesAsTools for tool-only clients. Add thin discovery tools only for parity and optional BM25/regex tool search when catalog/tool volume grows enough to affect token efficiency. Depends on step 5.
+6. Phase 2: Add discovery surfaces as resources first, then tool fallback. Keep catalog discovery in resources, then add ResourcesAsTools for tool-only clients. Add thin discovery tools only for parity and optional BM25/regex tool search when catalog/tool volume grows enough to affect token efficiency. Define canonical fallback tool names (`list_resources`, `read_resource`, `search_patterns`, `get_pattern_by_id`, `get_skill_document_by_id`), research host-specific naming behavior for GitHub Copilot, Cursor, Claude Desktop, and generic MCP clients, and require client-side name mapping or intentionally documented aliases when providers expose namespaced wrappers. Depends on step 5.
 7. Phase 3: Implement packaging so docs/ is copied into package resource space at build time (wheel + sdist) while docs/ remains canonical in source control. Use importlib.resources at runtime only; avoid direct filesystem assumptions. Depends on steps 4-6.
 8. Phase 3: Remove materialization coupling between skill source modules and docs. The website build reads docs/ directly, while MCP reads packaged docs resources from the installed package. This preserves one authored source with two distribution surfaces. Depends on step 7.
 9. Phase 4: Add validation and CI gates: frontmatter schema checks, URI uniqueness checks, reference integrity checks, docs build check, package content check, and stdio smoke checks that read representative skill/document resources from an installed wheel. Depends on steps 5-8.
@@ -31,7 +31,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
 2. Run uv run pytest -q with tests that validate frontmatter parsing, URI generation, reference mapping, and catalog responses.
 3. Run a packaging integrity check using importlib.resources.files(...) to confirm packaged docs resources exist and are readable from an installed wheel.
 4. Run a stdio MCP smoke test that lists resources and reads at least one skill document and one reference document.
-5. Run fallback-client smoke tests verifying list_resources/read_resource tools work and return expected metadata for both static and templated resources.
+5. Run fallback-client smoke tests verifying list_resources/read_resource tools work and return expected metadata for both static and templated resources, and that GitHub Copilot, Cursor, Claude Desktop, and protocol-level SDK tests use canonical tool names or documented mapped aliases.
 
 **Decisions**
 - Anthropic compatibility: strict skill directory pattern with SKILL.md and references subtree.

.github/prompts/plan-step1.prompt.md

@@ -61,7 +61,7 @@ Example valid ids:
 
 - `fastapi-uv-docker`
 - `zensical-docs`
-- `pytest-scaffolding`
+- `pytesting`
 
 Example invalid ids:
 

.github/prompts/plan-step6.prompt.md

@@ -23,6 +23,41 @@ Normative conclusions from those sources:
 3. Resources and tools must resolve to the same canonical authored markdown.
 4. Fallback behavior should keep context bounded and deterministic.
 
+### FastMCP Source Baseline (Authoritative References)
+
+Step 6 fallback behavior and compatibility-layer expectations align with:
+
+1. [FastMCP server concepts](https://gofastmcp.com/servers/server)
+2. [FastMCP resources and resource templates](https://gofastmcp.com/servers/resources)
+3. [FastMCP resources-as-tools transform](https://gofastmcp.com/servers/transforms/resources-as-tools)
+4. [MCP specification: resources](https://modelcontextprotocol.io/specification/latest/server/resources)
+
+Applied conclusions for this step:
+
+1. Resource contracts remain canonical and should be surfaced directly when clients support resource attachment.
+2. Tool-first compatibility layers should wrap canonical resource reads rather than creating alternate authored-content stores.
+3. URI-template-backed resource identity remains stable across direct-resource and tool-compatibility access paths.
+
+### Client Tool-Naming Research Baseline
+
+Authoritative and client-specific references to verify during implementation:
+
+1. [MCP specification: tools](https://modelcontextprotocol.io/specification/latest/server/tools)
+2. [MCP client concepts](https://modelcontextprotocol.io/docs/learn/client-concepts)
+3. [FastMCP tools](https://gofastmcp.com/servers/tools)
+4. [FastMCP resources-as-tools transform](https://gofastmcp.com/servers/transforms/resources-as-tools)
+5. [VS Code MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+6. [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
+7. [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol)
+8. [Claude Desktop local MCP server setup](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
+
+Baseline naming conclusions:
+
+1. MCP protocol tool identity is the server-advertised `name` returned by `tools/list` and used in `tools/call`.
+2. FastMCP tool identity should be treated as the canonical server contract unless a tool is intentionally registered with an explicit alternate name.
+3. Clients and host integrations may display, namespace, or internally route tool names with provider-specific prefixes, but those wrappers are not canonical server tool names.
+4. Compatibility should be validated by observed `tools/list` and successful `tools/call` behavior in each target client rather than by assuming one global host naming convention.
+
 ### Discovery Priority Contract (Normative)
 
 Preferred sequence for skill discovery and loading:
@@ -58,6 +93,19 @@ The fallback tool surface includes:
 4. `get_pattern_by_id`
 5. `get_skill_document_by_id`
 
+Canonical naming rule:
+
+1. The server-level tool contract uses the exact registered FastMCP tool names above.
+2. Clients that expose provider-prefixed names (for example, namespaced wrappers) must map those names to the canonical server tool name before invocation.
+3. `catalog_get_skill_document_by_id` is not a canonical server tool name for this contract unless an explicit alias is intentionally registered.
+
+Compatibility alias policy:
+
+1. Prefer canonical server tool names over aliases.
+2. Add server-side aliases only when a major client cannot reliably map its wrapper name back to the canonical name.
+3. Any alias must be read-only, delegate to the same payload builder as the canonical tool, and be documented as compatibility-only.
+4. If aliases are added, canonical and alias tools must return byte-for-byte equivalent payloads for the same input.
+
 Fallback order:
 
 1. call `list_resources` to inspect canonical static/template resource surfaces
@@ -70,6 +118,40 @@ Tool behavior requirements:
 2. deterministic ordering and bounded pagination
 3. explicit not-found responses (`found: false` style) where applicable
 4. payloads remain schema-aligned with catalog resources
+5. tool invocation examples and Copilot guidance must use canonical server tool names to avoid unknown-tool errors
+
+### Major Client Compatibility Plan
+
+Target clients and expected validation:
+
+1. GitHub Copilot in VS Code
+	- primary path: attach MCP resources when `MCP Resources...` is available
+	- fallback path: call `list_resources`, `read_resource`, then canonical thin tools only when needed
+	- validation: confirm Copilot-visible tool inventory includes or can invoke `list_resources`, `read_resource`, `search_patterns`, `get_pattern_by_id`, and `get_skill_document_by_id`
+	- compatibility risk: host-generated wrapper names may differ from canonical FastMCP names; document any observed wrapper-to-canonical mapping
+2. Cursor
+	- primary path: use the client MCP server configuration and resource/tool surfaces supported by the active Cursor version
+	- fallback path: prefer resource-backed tools first, then canonical thin tools
+	- validation: capture Cursor `tools/list` equivalent behavior and verify the canonical tool names or required host mappings
+	- compatibility risk: Cursor may present MCP tools through its own UI labels or internal routing names
+3. Claude Desktop
+	- primary path: configure the local MCP server and inspect advertised tools/resources in Claude Desktop
+	- fallback path: invoke canonical server tool names exactly as returned by `tools/list`
+	- validation: run a local smoke prompt that reads `resource://catalog/skills_index` and loads one skill document through `read_resource` or `get_skill_document_by_id`
+	- compatibility risk: local server configuration and transport setup may fail before tool-name compatibility is tested
+4. Generic MCP clients and SDK-based tests
+	- primary path: protocol-level `resources/list`, `resources/read`, `tools/list`, and `tools/call`
+	- fallback path: none beyond the canonical tool contract
+	- validation: automated smoke tests assert exact tool names returned by `tools/list` and successful calls for canonical names
+	- compatibility risk: SDK/client libraries may expose helper names that differ from raw protocol names
+
+Implementation checklist:
+
+1. Capture each target client's advertised tool names before adding aliases.
+2. Prefer fixing documentation or client-side mapping when the server already advertises canonical names correctly.
+3. Add a server-side alias only for a confirmed major-client incompatibility.
+4. Add regression tests for canonical names, resource-backed tools, and any intentionally supported aliases.
+5. Keep public examples centered on `list_resources`/`read_resource` and canonical thin tool names.
 
 ### Resources-As-Tools Compatibility Layer
 

.gitignore

@@ -2,3 +2,5 @@
 __pycache__
 .cache*
 site/
+
+*.log*

.vscode/tasks.json

@@ -0,0 +1,85 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Ruff: Check",
+      "type": "shell",
+      "command": "uv",
+      "args": [
+        "run",
+        "ruff",
+        "check",
+        "."
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Ty: Check",
+      "type": "shell",
+      "command": "uv",
+      "args": [
+        "run",
+        "ty",
+        "check"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Docs: Build",
+      "type": "shell",
+      "command": "uv",
+      "args": [
+        "run",
+        "zensical",
+        "build"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Server: Run (uvicorn)",
+      "type": "shell",
+      "command": "uv",
+      "args": [
+        "run",
+        "uvicorn",
+        "personal_mcp.main:app",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        "8000",
+        "--reload"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Docker: Compose Up (Build)",
+      "type": "shell",
+      "command": "docker",
+      "args": [
+        "compose",
+        "up",
+        "--build",
+        "-d"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    }
+  ]
+}

Dockerfile

@@ -1,43 +1,54 @@
-# syntax=docker/dockerfile:1
-
-FROM python:3.12-slim AS builder
-
-COPY --from=ghcr.io/astral-sh/uv:0.8.4 /uv /uvx /bin/
+FROM python:3.14-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     UV_COMPILE_BYTECODE=1 \
-    UV_LINK_MODE=copy
+    UV_LINK_MODE=copy \
+    UV_LOCKED=1
 
 WORKDIR /app
 
-COPY pyproject.toml uv.lock ./
-COPY src ./src
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=zensical.toml,target=zensical.toml \
+    --mount=type=bind,source=docs/,target=docs/ \
+    uvx zensical build
 
-RUN uv sync --frozen --no-dev
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --no-install-project
 
-COPY docs ./docs
-COPY zensical.toml ./
+# COPY --chown=appuser:appuser . /app
 
-RUN uv run zensical build
+# RUN --mount=type=cache,target=/root/.cache/uv \
+#     uv sync --no-editable
 
-FROM python:3.12-slim AS runtime
+FROM python:3.14-slim AS runtime
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     PATH="/app/.venv/bin:$PATH" \
-    PERSONAL_MCP_HOST=0.0.0.0 \
-    PERSONAL_MCP_PORT=8765
+    PERSONAL_MCP_SITE_DIR=/app/site
 
 WORKDIR /app
 
-RUN groupadd --system --gid 1001 appuser \
-    && useradd --system --uid 1001 --gid appuser --create-home --home-dir /home/appuser appuser
-
-COPY --from=builder --chown=appuser:appuser /app /app
-
 EXPOSE 8765
 
+RUN groupadd --system --gid 1001 appuser && \
+    useradd --system --uid 1001 --gid appuser appuser
+
+COPY --from=ghcr.io/astral-sh/uv:latest --chown=appuser:appuser /uv /uvx /bin/
+COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv
+COPY --from=builder --chown=appuser:appuser /app/site /app/site
+COPY --chown=appuser:appuser ./docs /app/docs
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    --mount=type=bind,source=src/,target=src/ \
+    uv sync --no-editable
+
 USER appuser
 
-CMD ["uvicorn", "personal_mcp.main:app", "--host", "0.0.0.0", "--port", "8765"]
+CMD ["uvicorn", "personal_mcp.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "8765"]

docker-compose.yaml

@@ -3,6 +3,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+    restart: unless-stopped
     ports:
       - "8765:8765"
-    restart: unless-stopped
+    volumes:
+      - ./docs:/app/src/personal_mcp/docs

docs/architecture.md

@@ -16,6 +16,8 @@ The system is complete in three layers:
 2. Catalog resources provide normalized discovery.
 3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.
 
+Prompt documents under `docs/prompts/` are also indexed and exposed as first-class catalog and prompt surfaces.
+
 This architecture is anchored by three contracts:
 
 1. Docs-first authored content contract under `docs/` with strict per-skill ownership.
@@ -24,9 +26,9 @@ This architecture is anchored by three contracts:
 
 Detailed contract pages:
 
-1. [Content Contract](./content.md)
-2. [Frontmatter Contract](./frontmatter.md)
-3. [URI Contract](./uris.md)
+1. [Content Contract](./contracts/index.md#content-contract)
+2. [Frontmatter Contract](./contracts/frontmatter.md)
+3. [URI Contract](./contracts/uris.md)
 
 This architecture keeps authored content human-friendly while preserving machine-stable contracts.
 
@@ -55,6 +57,17 @@ Each skill publishes resource families:
 
 The document resource returns canonical Markdown, while clients can perform any downstream section extraction they need.
 
+### Prompt Modules
+
+Prompt guidance can be authored in `docs/prompts/` using either canonical prompt directories (`docs/prompts/<prompt-id>/PROMPT.md`) or legacy markdown files during migration.
+
+Prompt modules publish two additive surfaces:
+
+1. prompt resources for catalog and document retrieval
+2. MCP prompt objects for prompt-list/get-prompt style client workflows
+
+This keeps authored markdown as source-of-truth while allowing clients to discover and invoke prompts directly.
+
 ### Catalog Module
 
 The catalog is the canonical discovery layer and publishes normalized records for all modules. It may also expose a minimal set of read-only discovery tools that resolve back to the same canonical markdown content when a client chat surface does not expose MCP resource attachment.
@@ -62,27 +75,35 @@ The catalog is the canonical discovery layer and publishes normalized records fo
 Typical catalog resources:
 
 1. resource://catalog/skills_index
-2. resource://catalog/skills/{skill_id}
+2. resource://catalog/skills_index{?q,tag,capability,cursor,limit}
+3. resource://catalog/skills/{skill_id}
+4. resource://catalog/prompts_index
+5. resource://catalog/prompts_index{?q,tag,cursor,limit}
+6. resource://catalog/prompts/{prompt_id}
 
 Only canonical catalog resources are part of the runtime contract in this phase.
 
 ### Registry Loader
 
-The runtime composition includes a startup registry loader that reads packaged docs resources using `importlib.resources.files(...)` and `Traversable` APIs.
+Importing the package does not read or parse documentation. The MCP server and FastAPI application factories request the registry when constructing a runnable server, using packaged resources through `importlib.resources.files(...)` and `Traversable` APIs.
 
 Loader responsibilities:
 
 1. Parse SKILL.md frontmatter for each skill.
 2. Validate schema and cross-field constraints before any resource registration.
 3. Build an in-memory registry keyed by `skill_id`.
-4. Fail fast for duplicate ids, missing markdown files, broken reference mappings, and invalid `depends_on` values.
+4. Fail fast for duplicate ids, missing markdown files, and broken reference mappings.
 
-Registry load failure is a startup error, not a partial runtime warning.
+The immutable registry is cached for the process lifetime. Each Uvicorn worker constructs and retains its own registry because worker processes do not share Python objects. Registry load failure is a server-factory startup error, not a package-import error or partial runtime warning.
 
 ### Content Sources
 
 Content is authored in markdown under `docs/` and managed as long-form reference material. Skill documents and companion references now live under `docs/skills/`, while project-authored pages remain alongside them in the docs tree. Resource handlers expose the same authored documents through stable resource URIs.
 
+The repository root `docs/` directory is the only authored source. The `src/personal_mcp/docs` path is a relative symlink to that directory for source-checkout and editable-install workflows; it is not a second content tree and packaging does not depend on traversing it.
+
+For wheel builds, [Hatchling forced inclusion](https://hatch.pypa.io/latest/config/build/#forced-inclusion) maps the root `docs/` tree to `personal_mcp/docs/`. The wheel therefore contains regular resource files at that destination rather than a symlink. Runtime registry loading uses [`importlib.resources.files`](https://docs.python.org/3/library/importlib.resources.html#importlib.resources.files) and `Traversable` operations from the `personal_mcp` package anchor, so it does not depend on the repository layout or current working directory.
+
 ### Static Docs Surface
 
 Static docs are built directly from two markdown source streams:
@@ -92,6 +113,8 @@ Static docs are built directly from two markdown source streams:
 
 The merged docs tree is built by Zensical into static files and served by the FastAPI app.
 
+Generated `site/` files are deployment assets for the human-facing static site. They are separate from the authored Markdown resources packaged under `personal_mcp/docs/`.
+
 ## Data Flow
 
 ```mermaid
@@ -110,7 +133,7 @@ flowchart TD
 
 Each skill declares frontmatter in `docs/skills/<skill-id>/SKILL.md`.
 
-For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./frontmatter.md).
+For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./contracts/frontmatter.md).
 
 Anthropic-facing required fields:
 
@@ -123,8 +146,7 @@ Repository indexing metadata is declared in `x-personal-mcp`:
 2. version
 3. tags
 4. capabilities
-5. depends_on
-6. references map (ref id to relative path and optional metadata)
+5. optional references map (for nested entries, overrides, and aliases)
 
 No `metadata.yaml` sidecar is part of the end-state contract.
 
@@ -132,18 +154,25 @@ No `metadata.yaml` sidecar is part of the end-state contract.
 
 Canonical resource URIs are:
 
-For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./uris.md).
+For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./contracts/uris.md).
 
 1. resource://skills/<skill_id>/document
 2. resource://skills/<skill_id>/references/<ref_id>
 3. resource://catalog/skills_index
-4. resource://catalog/skills/{skill_id}
-5. resource://docs/{path*}
+4. resource://catalog/skills_index{?q,tag,capability,cursor,limit}
+5. resource://catalog/skills/{skill_id}
+6. resource://docs/{path*}
+7. resource://catalog/prompts_index
+8. resource://catalog/prompts_index{?q,tag,cursor,limit}
+9. resource://catalog/prompts/{prompt_id}
+10. resource://prompts/{prompt_id}/document
 
 Validation rules:
 
 1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract.
-2. `ref_id` is lowercase kebab-case and must be declared in the skill references manifest.
+2. `ref_id` is lowercase kebab-case and must resolve from either:
+    - top-level auto-discovery of `references/*.md` filename stems, or
+    - an explicit `x-personal-mcp.references` entry.
 3. `path*` resolves only to normalized markdown paths under `docs/`.
 
 ### Resource Registration Contract
@@ -198,7 +227,7 @@ Markdown remains easy to review, while contracts remain stable for clients.
 
 ### Client Independence
 
-Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt orchestration. However, MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.
+Clients can use Ask, Edit, or Agent modes without requiring prompt-first orchestration. Prompt objects are available as an additive MCP surface, while resource retrieval remains the canonical source path. MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.
 
 ## Authoring and Publishing Lifecycle
 
@@ -229,8 +258,9 @@ Allowed exception:
 
 Existing markdown reference sets are valid examples of authored source material for this architecture:
 
-1. docs/skills/pytest-scaffolding/references/pytest-docs.md
-2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
-3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
+1. docs/skills/pytesting/references/pytest-docs.md
+2. docs/skills/python-logging/references/python-logging-docs.md
+3. docs/skills/python-logging/references/json-file-logging.md
+4. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
 
 These inputs are treated as content sources, while resource URIs and catalog payloads remain the machine-facing contracts.

docs/authoring.md

@@ -0,0 +1,262 @@
+---
+icon: lucide/pencil
+---
+
+# Authoring Guide
+
+This page defines the practical authoring workflow for this repository so Markdown remains the single source of truth for both published docs and MCP resources.
+
+Primary references:
+- [Skill contract](./contracts/skill_contract.md)
+- [Prompt contract](./contracts/prompt.md)
+- [Frontmatter contract](./contracts/frontmatter.md)
+- [URI contract](./contracts/uris.md)
+- [Zensical documentation authoring skill](./skills/zensical-docs/SKILL.md)
+
+## What You Author
+
+This repository has two primary authored content types:
+
+1. Skills under `docs/skills/<skill-id>/`.
+2. Prompts under `docs/prompts/<prompt-id>/`.
+
+Each module keeps one canonical document plus optional references:
+
+```text
+docs/
+	skills/<skill-id>/
+		SKILL.md
+		references/
+			*.md
+
+	prompts/<prompt-id>/
+		PROMPT.md
+		references/
+			*.md
+```
+
+## Source Tree Ownership
+
+Edit content only under the repository root `docs/` directory. The `src/personal_mcp/docs` path is a relative symlink provided so package-oriented tooling and editable installs see the same files; do not replace it with copied content or author files through a second tree.
+
+[Hatchling forced inclusion](https://hatch.pypa.io/latest/config/build/#forced-inclusion) projects root `docs/` into `personal_mcp/docs/` when building the wheel. Installed code reads that destination through [`importlib.resources`](https://docs.python.org/3/library/importlib.resources.html), while Zensical continues to build the human-facing site directly from root `docs/`.
+
+Package import does not load these resources. A runnable MCP or FastAPI server loads and validates them when its factory runs, then caches the immutable registry for that process. Restart initialized development or worker processes after changing authored Markdown.
+
+## Authoring Principles
+
+1. Keep Markdown as the canonical source and avoid duplicating content into alternate metadata files.
+2. Prefer resource-first discovery paths (`resource://catalog/...` then `resource://skills/...` or `resource://prompts/...`).
+3. Keep pages focused and composable: overview in the primary doc, details in `references/`.
+4. Use descriptive inline links for external sources instead of bare URLs.
+5. Use stable ids and slugs; renames are breaking changes and should be intentional.
+
+## Skill Authoring Workflow
+
+When creating or updating a skill:
+
+1. Confirm slug format is lowercase kebab-case.
+2. Keep directory name, `name`, and `x-personal-mcp.id` aligned.
+3. Ensure capabilities include `resource://skills/<skill-id>/document`.
+4. Place supporting material under `references/`.
+5. Use explicit frontmatter reference entries only when you need overrides or nested mappings.
+
+Recommended sequence:
+
+1. Draft `SKILL.md` intent and routing sections.
+2. Add or refine `references/*.md`.
+3. Verify links and example commands.
+4. Run docs build and tests.
+
+For exact metadata rules, see [Frontmatter contract](./contracts/frontmatter.md) and [Skill contract](./contracts/skill_contract.md).
+
+## Prompt Authoring Workflow
+
+When creating or updating a prompt module:
+
+1. Keep one canonical `PROMPT.md`.
+2. Keep `name`, `x-personal-mcp.id`, and directory slug aligned.
+3. Include `resource://prompts/<prompt-id>/document` in capabilities.
+4. Define prompt arguments in `x-personal-mcp.arguments` when inputs are required.
+5. Keep long rationale and source notes in `references/` to preserve prompt clarity.
+
+For exact structure, see [Prompt contract](./contracts/prompt.md).
+
+## Prompt Argument Mechanics
+
+When defining prompt inputs, keep argument metadata aligned with the prompt contract and runtime behavior.
+
+1. Define arguments under `x-personal-mcp.arguments` as a map keyed by argument name.
+2. Argument names must match Python identifier format: `^[A-Za-z_][A-Za-z0-9_]*$`.
+3. Each argument entry supports only:
+	 - `title` (optional)
+	 - `description` (optional)
+	 - `required` (optional, defaults to `false`)
+4. Unknown argument fields are rejected by strict frontmatter validation.
+5. Prompt argument metadata appears in `resource://catalog/prompts/{prompt_id}`, and MCP prompt objects expose the same arguments for prompt-list/get-prompt workflows.
+6. Enum-like constraints are not a native argument field; encode allowed values in `description`.
+
+### Frontmatter Safety Rules
+
+Use these rules to avoid YAML parse failures in prompt and skill frontmatter:
+
+1. Quote any scalar value that contains `:` (for example, `description: "Enum: skill | prompt | shim"`).
+2. Prefer quoted scalars for values with reserved YAML characters such as `#`, `{}`, `[]`, or leading `*`.
+3. If a description needs multiple lines, use a block scalar (`|`) instead of packing punctuation-heavy text into one line.
+4. Keep frontmatter keys simple and contract-bound; do not add undeclared argument fields.
+
+### Validation Timing
+
+Run validation immediately after frontmatter edits, not only at the end of a task:
+
+1. First pass after metadata changes: `uv run zensical build`
+2. Prompt/skill load verification: `uv run pytest -q`
+3. Final full pass before completion: run the full checklist in [Validation Checklist](#validation-checklist)
+
+Example:
+
+```yaml
+x-personal-mcp:
+	arguments:
+		artifact_type:
+			title: Artifact type
+			description: Allowed values are skill, prompt, or shim.
+			required: true
+		scope_glob:
+			title: Scope glob
+			description: Optional applyTo glob for shim outputs.
+			required: false
+```
+
+References:
+
+1. [Frontmatter contract](./contracts/frontmatter.md)
+2. [URI contract](./contracts/uris.md)
+3. [Resource-First Pattern Module Architecture](./architecture.md)
+4. [Prompt objects concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts)
+
+## Writing Quality Rules
+
+Apply these defaults to all docs pages:
+
+1. Prefer short sections with strong headings over long unbroken prose.
+2. Keep claims source-linked, especially for MCP, FastMCP, pytest, FastAPI, SQLAlchemy, and Zensical behavior.
+3. Prefer relative links for internal docs paths.
+4. Use code blocks for commands and configuration snippets.
+5. Keep examples minimal and actionable.
+
+Source examples:
+- [Model Context Protocol docs](https://modelcontextprotocol.io/docs/getting-started/intro)
+- [FastMCP docs](https://gofastmcp.com/getting-started/welcome)
+- [Zensical docs](https://zensical.org/docs/)
+
+## Authoring for GitHub Copilot
+
+For resource selection or tool-based matching to work well, each skill should have:
+
+1. precise `description`
+2. focused `tags`
+3. explicit `capabilities`
+4. stable `id` and slug naming
+
+Weak metadata reduces Copilot match quality and increases wrong context injection.
+
+### Copilot Instruction Authoring Pattern
+
+If you want Copilot to use `personal-mcp` skill content more reliably, instruction files should describe three things clearly:
+
+1. when MCP-backed skill guidance is relevant
+2. which retrieval path Copilot should prefer first
+3. how much skill context it should load before answering
+
+Instructions strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. Keep wording explicit about preferred path and fallback path.
+
+Repository policy:
+
+1. start from catalog discovery
+2. prefer MCP resources when the current chat surface exposes resource attachment
+3. fall back to catalog tools when resource attachment is unavailable
+4. keep loaded skill context bounded
+
+Suggested instruction text:
+
+```md
+When a task may match a documented implementation pattern from `personal-mcp`:
+
+1. Start with catalog-first discovery.
+2. Prefer MCP resources when the chat surface exposes resource attachment.
+3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
+4. Load only the most relevant skill document, or at most 2 skill documents.
+5. Reconcile loaded skill guidance with the actual repository code before making changes.
+
+Preferred resource order:
+
+1. `resource://catalog/skills_index`
+2. `resource://catalog/skills/{skill_id}`
+3. `resource://skills/<skill-id>/document`
+4. `resource://skills/<skill-id>/references/<ref-id>` when needed
+
+Preferred tool fallback order:
+
+1. `list_resources`
+2. `read_resource`
+3. `search_patterns`
+4. `get_pattern_by_id`
+5. `get_skill_document_by_id`
+
+Compatibility aliases for clients that use `catalog_*` naming are also available:
+
+1. `catalog_search_patterns`
+2. `catalog_get_pattern_by_id`
+3. `catalog_get_skill_document_by_id`
+4. `catalog_search_prompts`
+5. `catalog_get_prompt_by_id`
+
+Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.
+
+If confidence is low after discovery, ask one clarifying question before loading more context.
+```
+
+This is guidance, not a guarantee. It defines a reliable policy while preserving the resource-first architecture.
+
+Thin shim path binding guidance for MCP consumers is covered in [Skill Usage Mechanics](./usage.md).
+
+## Zensical Details
+
+When adding or restructuring pages:
+
+1. Update navigation in `zensical.toml`.
+2. Ensure top-level pages include frontmatter with an icon.
+3. Keep naming and labels concise so navigation remains scannable.
+
+Top-level page pattern:
+
+```yaml
+---
+icon: lucide/pencil
+---
+```
+
+## Validation Checklist
+
+Run these checks before considering authoring changes complete:
+
+```bash
+uv run zensical build
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+Address any errors or warnings that result.
+
+If a change only affects docs content, `uv run zensical build` is still required.
+
+## Quick Authoring Checklist
+
+1. Correct location (`skills/` or `prompts/`).
+2. Frontmatter id and slug alignment.
+3. Capability URI present.
+4. Links valid and descriptive.
+5. Navigation updated when needed.
+6. Validation commands passed.

docs/content.md

@@ -1,88 +0,0 @@
----
-icon: lucide/file-text
----
-
-# Content Contract
-
-This page defines the authored content contract for the docs-first MCP architecture.
-
-## Canonical Source Of Truth
-
-1. All authored Markdown lives under `docs/`.
-2. MCP resources and static docs are two distribution surfaces of the same authored files.
-3. No parallel authored markdown is allowed in `src/` or other package-only paths.
-
-## Canonical Skill Shape
-
-Each skill is one directory under `docs/skills/`:
-
-```text
-docs/
-  skills/
-    <skill-id>/
-      SKILL.md
-      references/
-        ... (one or more markdown files, optional nested folders)
-```
-
-Rules:
-
-1. `SKILL.md` is required for every skill.
-2. `references/` is the only place for skill-specific supporting docs.
-3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
-4. Skill directories are independent ownership boundaries; no cross-skill file writes.
-
-## File Placement And Ownership Boundaries
-
-1. Top-level project docs stay in `docs/*.md`.
-2. Skill docs stay in `docs/skills/<skill-id>/...`.
-3. A skill may link to other skills, but must not store content inside another skill's directory.
-4. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
-
-## Metadata Location Constraint
-
-1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
-2. No `metadata.yaml` sidecar exists in the end state.
-3. Reference lookup metadata, including reference id to relative path mappings, is declared from `SKILL.md` frontmatter rather than inferred as a hidden global convention.
-
-## Skill Id Contract
-
-`skill-id` is the public identifier and should satisfy all rules below:
-
-1. Format: lowercase kebab-case only.
-2. Character set: `a-z`, `0-9`, and `-`.
-3. Must start with a letter.
-4. No underscores, spaces, dots, or uppercase characters.
-5. Directory name should equal `skill-id` in each committed revision.
-6. Frontmatter `id` should equal directory name in each committed revision.
-7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
-
-Valid examples:
-
-1. `fastapi-uv-docker`
-2. `zensical-docs`
-3. `pytest-scaffolding`
-
-Invalid examples:
-
-1. `fastapi_uv_docker`
-2. `Zensical-Docs`
-3. `docs.zensical`
-
-## Invariants
-
-This contract guarantees:
-
-1. One authored source tree in `docs/` for both website and MCP.
-2. One skill directory maps to one skill identity per revision.
-3. Namespace and slug drift is minimized by keeping directory and frontmatter ids aligned per revision.
-4. Per-skill reference structure can evolve without changing cross-skill architecture.
-5. Packaging for stdio is deterministic because authored content is path-stable.
-
-## Non-Goals
-
-This contract does not define:
-
-1. URI versioning policy details.
-2. The full frontmatter schema.
-3. Migration instructions from the current architecture.

docs/contracts/frontmatter.md

@@ -0,0 +1,234 @@
+---
+icon: lucide/braces
+---
+
+# Frontmatter Contract
+
+This page defines the `SKILL.md` frontmatter and FastMCP metadata contract.
+
+Prompt modules use the same contract style in `docs/prompts/<prompt-id>/PROMPT.md` with prompt-specific capability and MCP-aligned prompt argument metadata.
+
+## Validated Frontmatter Surface
+
+The registry runtime validates a strict, standard-only frontmatter surface:
+
+1. Top-level fields accepted for skills: `name`, `description`, `x-personal-mcp`.
+2. Top-level fields accepted for prompts: `name`, `description`, `x-personal-mcp`.
+3. Unknown top-level fields are rejected during registry load.
+
+Skill and prompt identifier rules:
+
+1. `name` is required, 1-64 chars, lowercase kebab-case, and must not contain `anthropic` or `claude`.
+2. `description` is required, 1-1024 chars.
+3. `x-personal-mcp.id` must exactly match `name`.
+4. Directory slug must exactly match `name`.
+
+Capability invariants:
+
+1. Skill capabilities must include `resource://skills/<skill-id>/document`.
+2. Prompt capabilities must include `resource://prompts/<prompt-id>/document`.
+
+Repository contract decisions:
+
+1. Treat `name` and `description` as required in all `SKILL.md` files.
+2. Keep only validated standard fields at top level.
+3. Keep MCP indexing metadata in a namespaced extension block.
+4. Reject unsupported optional top-level fields until explicit model support is added.
+
+Reference specs:
+
+1. MCP prompts data types: [Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts)
+2. MCP schema reference for `Prompt` and `PromptArgument`: [Schema](https://modelcontextprotocol.io/specification/latest/schema)
+
+## Canonical Frontmatter Schema
+
+Use this two-layer pattern:
+
+1. Anthropic layer: top-level fields intended for Anthropic and Agent Skills behavior.
+2. Repository layer: one namespaced block, `x-personal-mcp`, for MCP catalog and routing metadata.
+
+Canonical shape:
+
+```yaml
+---
+name: <skill-id>
+description: <what this skill does and when to use it>
+
+# Repository-specific metadata
+x-personal-mcp:
+  id: <skill-id>
+  version: <semver>
+  tags:
+    - <tag>
+  capabilities:
+    - resource://skills/<skill-id>/document
+    # Optional: overrides and nested references only.
+    # Top-level references/*.md are auto-discovered.
+  references:
+    <ref-id>:
+      path: references/<file>.md
+      mime_type: text/markdown
+      title: <short title>
+---
+```
+
+## Repository Metadata Field Rules
+
+Rules for `x-personal-mcp`:
+
+1. `id` is required, must follow the skill id rules from the content contract, and must equal the directory name.
+2. `version` is required and must be a semantic version string.
+3. `tags` is optional and should be a list of kebab-case discovery labels.
+4. `capabilities` is required and lists the MCP URIs the skill publishes.
+5. `references` is an optional map keyed by `ref-id` for overrides and nested entries.
+
+Prompt-specific additions:
+
+1. `arguments` is an optional map keyed by argument name.
+2. Each argument supports optional `title`, optional `description`, and optional `required`.
+3. This aligns with MCP `PromptArgument` shape (`name`, optional `title`, optional `description`, optional `required`) where `name` is represented by the map key.
+4. Prompt `capabilities` must include `resource://prompts/<prompt-id>/document`.
+
+Example prompt frontmatter:
+
+```yaml
+---
+name: initial-test-structure
+description: Generate a baseline pytest test layout for a target scope.
+x-personal-mcp:
+    id: initial-test-structure
+    version: 1.0.0
+    tags:
+        - pytest
+        - testing
+    capabilities:
+        - resource://prompts/initial-test-structure/document
+    arguments:
+        target_scope:
+            title: Target scope
+            description: Target package or module under test.
+            required: true
+---
+```
+
+Reference entry rules:
+
+1. `ref-id` is lowercase kebab-case.
+2. `path` is a skill-relative markdown path and must stay inside the same skill directory.
+3. Top-level files under `references/*.md` are auto-discovered with `ref-id` derived from a normalized filename stem (lowercase kebab-case).
+4. Nested folders under `references/` are not auto-discovered and must be declared explicitly.
+5. `mime_type` defaults to `text/markdown` when omitted.
+6. `title` is an optional display label.
+7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
+
+## Auto-Generated Reference IDs
+
+Top-level markdown files directly under `references/` are auto-registered as MCP references even when `x-personal-mcp.references` is empty.
+
+How `ref-id` is derived:
+
+1. Start from the filename stem (without `.md`).
+2. Normalize to lowercase kebab-case.
+3. Publish at `resource://skills/<skill-id>/references/<ref-id>`.
+
+Examples:
+
+1. `references/ruff-docs.md` -> `ref-id: ruff-docs`
+2. `references/Ruff Integrations.md` -> `ref-id: ruff-integrations`
+3. `references/python_logging_docs.md` -> `ref-id: python-logging-docs`
+
+When to use explicit `x-personal-mcp.references` entries:
+
+1. The file is nested, for example `references/guides/ci.md`.
+2. You need to override defaults (`title`, `mime_type`, or custom `ref-id`).
+3. You need compatibility aliases during a rename.
+
+## Validation Models
+
+The normative runtime model uses strict Pydantic v2 validation:
+
+1. Models are immutable (`frozen=True`) and reject unknown fields (`extra="forbid"`).
+2. `SkillFrontmatter` accepts only `name`, `description`, and `x-personal-mcp`.
+3. `PromptFrontmatter` accepts only `name`, `description`, and `x-personal-mcp`.
+4. `PromptArgumentEntry` accepts only optional `title`, optional `description`, and optional `required`.
+5. Skill and prompt metadata enforce semver, kebab-case ids, capability requirements, and id/name/directory consistency.
+6. Reference paths are validated as markdown files under `references/`.
+
+Validation behavior contract:
+
+1. Validate required core fields and relationships during registry load before FastMCP resource or tool registration.
+2. Reject unknown or unsupported fields at parse and model-validation time.
+3. Treat hard contract violations, including missing required fields, invalid ids, and broken required mappings, as startup errors.
+4. Keep failure messages path-aware and field-specific for CI readability.
+
+Projection mode contract for Anthropic API upload pipelines:
+
+1. Parse with `SkillFrontmatter` first.
+2. Emit Anthropic-safe frontmatter with standard fields only.
+3. Preserve `x-personal-mcp` in source-of-truth documents; projection output is a build artifact.
+
+## Anthropic Upload Compatibility Rule
+
+1. Anthropic documentation guarantees behavior for standard frontmatter fields but does not explicitly guarantee handling of arbitrary unknown top-level keys.
+2. Publishing pipelines that target strict API compatibility should support a projection mode that emits only standard frontmatter fields for upload.
+3. Source-of-truth authoring remains in `x-personal-mcp`; upload payload shape is an explicit build concern.
+
+## FastMCP Native Metadata Surfaces
+
+Resources support native definition metadata:
+
+1. `name`
+2. `description`
+3. `mime_type`
+4. `tags`
+5. `annotations`, including `readOnlyHint` and `idempotentHint`
+6. `icons`
+7. `meta`
+8. `version`
+9. `enabled`, which is deprecated in FastMCP v3 in favor of server-level enable and disable controls
+
+Resources also support runtime metadata through `ResourceContent.meta` and `ResourceResult.meta`.
+
+Tools support native definition metadata:
+
+1. `name`
+2. `description`
+3. `tags`
+4. `annotations`, including `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`
+5. `icons`
+6. `meta`
+7. `version`
+8. `timeout`
+9. `output_schema`
+10. `run_in_thread`
+11. `enabled`, which is deprecated in FastMCP v3 in favor of server-level enable and disable controls
+
+Tools also support runtime metadata through `ToolResult.meta`.
+
+## Frontmatter To FastMCP Mapping Contract
+
+At server startup, map `x-personal-mcp` into FastMCP registration as follows:
+
+1. `x-personal-mcp.id` defines the canonical URI namespace and identity checks.
+2. `description` becomes the default description for the primary skill document resource.
+3. `x-personal-mcp.tags` maps to resource and tool tags.
+4. `x-personal-mcp.version` maps to resource and tool version metadata.
+5. `x-personal-mcp.capabilities` becomes the registered URI list and catalog exposure.
+6. `x-personal-mcp.references[*]` becomes resource templates or concrete resources with `mime_type`, read-only annotations, and `meta` that includes `skill_id`, `ref_id`, and source `path`.
+
+## Invariants
+
+This contract guarantees:
+
+1. Anthropic-required frontmatter stays valid for custom skill upload and Claude Code loading.
+2. MCP-specific metadata remains embedded in `SKILL.md` frontmatter, with no `metadata.yaml` sidecar.
+3. FastMCP registration uses native metadata fields for resources and tools.
+4. Reference ids and metadata can evolve with low-friction updates while internal file layout under `references/` stays refactor-friendly.
+
+## Non-Goals
+
+This contract does not define:
+
+1. URI versioning and deprecation rollout policy details.
+2. Migration script design from existing `metadata.yaml` files.
+3. Runtime caching and indexing performance tuning.

docs/contracts/index.md

@@ -0,0 +1,88 @@
+---
+icon: lucide/file-check-2
+---
+
+# Contracts
+
+This section groups the core data and contract documents for the repository.
+
+## Pages
+
+1. [Prompt Contract](./prompt.md)
+2. [Skill Contract](./skill_contract.md)
+3. [Frontmatter Contract](./frontmatter.md)
+4. [URI Contract](./uris.md)
+
+Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.
+
+## Content Contract
+
+This page defines the authored content contract for the docs-first MCP architecture.
+
+## Canonical Source Of Truth
+
+1. All authored Markdown lives under `docs/`.
+2. MCP resources and static docs are two distribution surfaces of the same authored files.
+3. No parallel authored markdown is allowed in `src/` or other package-only paths.
+
+## Canonical Content Shape
+
+Authored content is organized under `docs/`:
+
+```mermaid
+---
+config:
+    treeView:
+        rowIndent: 20
+        lineThickness: 2
+    themeVariables:
+        treeView:
+            labelColor: '#FFFFFF'
+            lineColor: '#FFFFFF'
+---
+treeView-beta
+  "docs/"
+    "*.md (top-level docs pages)"
+    "contracts/"
+      "prompt.md"
+      "skill_contract.md"
+      "frontmatter.md"
+      "uris.md"
+    "prompts/"
+      "<prompt-id>/"
+        "PROMPT.md"
+    "skills/"
+      "<skill-id>/"
+        "SKILL.md"
+        "references/..."
+```
+
+## File Placement And Ownership Boundaries
+
+1. Top-level project docs stay in `docs/*.md`.
+2. Skill docs stay in `docs/skills/<skill-id>/...`.
+3. Prompt docs stay in `docs/prompts/<prompt-id>/...`.
+4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
+5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
+
+## Delegated Contracts
+
+1. Skill-specific directory, metadata, and id rules are defined in [Skill Contract](./skill_contract.md).
+2. Prompt-specific directory, metadata, and id rules are defined in [Prompt Contract](./prompt.md).
+
+## Invariants
+
+This contract guarantees:
+
+1. One authored source tree in `docs/` for both website and MCP.
+2. Skill and prompt artifacts remain path-stable within their own sections.
+3. Cross-surface publishing remains deterministic because authored content paths are canonical.
+
+## Non-Goals
+
+This contract does not define:
+
+1. URI versioning policy details.
+2. The full frontmatter schema.
+3. Detailed skill rules (see [Skill Contract](./skill_contract.md)).
+4. Detailed prompt rules (see [Prompt Contract](./prompt.md)).

docs/contracts/prompt.md

@@ -0,0 +1,75 @@
+---
+icon: lucide/messages-square
+---
+
+# Prompt Contract
+
+This page defines the canonical contract for prompts in the docs-first MCP architecture.
+
+## Canonical Prompt Shape
+
+Each prompt is one directory under `docs/prompts/`:
+
+```mermaid
+---
+config:
+    treeView:
+        rowIndent: 20
+        lineThickness: 2
+    themeVariables:
+        treeView:
+            labelColor: '#FFFFFF'
+            lineColor: '#FFFFFF'
+---
+treeView-beta
+    "docs/"
+      "... (other docs)"
+      "prompts/"
+        "<prompt-id>/"
+          "PROMPT.md"
+          "references/"
+            "... (one or more markdown files, optional nested folders)"
+```
+
+Rules:
+
+1. `PROMPT.md` is required for every prompt.
+2. `references/` is the only place for prompt-specific supporting docs.
+3. Nested folders inside `references/` are allowed so a prompt can reorganize internals without changing global architecture.
+4. Prompt directories are independent ownership boundaries; no cross-prompt file writes.
+
+## Metadata Location Constraint
+
+1. Prompt metadata is embedded in YAML frontmatter in `PROMPT.md`.
+2. No `metadata.yaml` sidecar exists in the end state.
+3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `PROMPT.md` frontmatter declares overrides and nested mappings when needed.
+
+## Prompt Id Contract
+
+`prompt-id` is the public identifier and should satisfy all rules below:
+
+1. Format: lowercase kebab-case only.
+2. Character set: `a-z`, `0-9`, and `-`.
+3. Must start with a letter.
+4. No underscores, spaces, dots, or uppercase characters.
+5. Directory name should equal `prompt-id` in each committed revision.
+6. Frontmatter `id` should equal directory name in each committed revision.
+7. Treat `prompt-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
+
+Valid examples:
+
+1. `pytest-fill-scaffold`
+2. `review-pr-comments`
+3. `scaffold-fastapi-service`
+
+Invalid examples:
+
+1. `fill_pytest_scaffold`
+2. `Prompt-Template`
+3. `docs.prompt`
+
+## Direct Documentation Inclusion
+
+1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
+2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.
+

docs/contracts/skill_contract.md

@@ -0,0 +1,75 @@
+---
+icon: lucide/brain-circuit
+---
+
+# Skill Contract
+
+This page defines the canonical contract for skills in the docs-first MCP architecture.
+
+## Canonical Skill Shape
+
+Each skill is one directory under `docs/skills/`:
+
+```mermaid
+---
+config:
+		treeView:
+				rowIndent: 20
+				lineThickness: 2
+		themeVariables:
+				treeView:
+						labelColor: '#FFFFFF'
+						lineColor: '#FFFFFF'
+---
+treeView-beta
+	"docs/"
+		"... (other docs)"
+		"skills/"
+			"<skill-id>/"
+				"SKILL.md"
+				"references/"
+					"... (one or more markdown files, optional nested folders)"
+```
+
+Rules:
+
+1. `SKILL.md` is required for every skill.
+2. `references/` is the only place for skill-specific supporting docs.
+3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
+4. Skill directories are independent ownership boundaries; no cross-skill file writes.
+
+## Metadata Location Constraint
+
+1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
+2. No `metadata.yaml` sidecar exists in the end state.
+3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed.
+
+## Skill Id Contract
+
+`skill-id` is the public identifier and should satisfy all rules below:
+
+1. Format: lowercase kebab-case only.
+2. Character set: `a-z`, `0-9`, and `-`.
+3. Must start with a letter.
+4. No underscores, spaces, dots, or uppercase characters.
+5. Directory name should equal `skill-id` in each committed revision.
+6. Frontmatter `id` should equal directory name in each committed revision.
+7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
+
+Valid examples:
+
+1. `fastapi-uv-docker`
+2. `zensical-docs`
+3. `pytesting`
+
+Invalid examples:
+
+1. `fastapi_uv_docker`
+2. `Zensical-Docs`
+3. `docs.zensical`
+
+## Direct Documentation Inclusion
+
+1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
+2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.
+

docs/contracts/uris.md

@@ -0,0 +1,186 @@
+---
+icon: lucide/link
+---
+
+# URI Contract
+
+This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
+
+Conventions in this document follow [MCP resource semantics](https://modelcontextprotocol.io/docs/learn/server-concepts#resources), [URI generic syntax (RFC3986)](https://www.rfc-editor.org/rfc/rfc3986), and [URI templates (RFC6570)](https://www.rfc-editor.org/rfc/rfc6570).
+
+## Canonical URI Surface
+
+The public, preferred direct resource URIs are:
+
+1. `resource://catalog/skills_index`
+2. `resource://catalog/skills/{skill_id}`
+3. `resource://skills/{skill_id}/document`
+4. `resource://skills/{skill_id}/references/{ref_id}`
+5. `resource://docs/{path*}`
+6. `resource://catalog/prompts_index`
+7. `resource://catalog/prompts/{prompt_id}`
+8. `resource://prompts/{prompt_id}/document`
+
+The public, preferred resource template URIs are:
+
+1. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
+2. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
+
+Contract intent:
+
+1. Catalog URIs are discovery surfaces.
+2. Skill URIs are the primary per-skill guidance surfaces.
+3. Catalog query templates are additive discovery helpers for filtering and pagination.
+4. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
+
+Best-practice alignment:
+
+1. Resource identifiers are stable and noun-oriented.
+2. Dynamic lookup variants are represented as RFC6570 templates.
+3. Resources remain read-oriented and are described with explicit MIME types.
+
+## URI Semantics
+
+### `resource://catalog/skills_index`
+
+1. Returns a compact list of skill records for discovery.
+2. Contains one entry per `skill_id`.
+3. Includes enough metadata for client-side selection, at minimum `id`, `name`, `description`, `tags`, and `capabilities`.
+
+### `resource://catalog/skills/{skill_id}`
+
+1. Returns one normalized record for `skill_id`.
+2. Includes the canonical document URI and declared reference ids.
+3. Returns not found when `skill_id` does not exist.
+
+### `resource://skills/{skill_id}/document`
+
+1. Returns the canonical `SKILL.md` authored content for that skill.
+2. `skill_id` must satisfy the stable skill id rules from the content contract.
+
+### `resource://skills/{skill_id}/references/{ref_id}`
+
+1. Returns one reference document declared in the skill frontmatter references manifest.
+2. `ref_id` is the stable public handle for that reference document.
+
+### `resource://docs/{path*}`
+
+1. Returns authored markdown at a normalized relative path under `docs/`.
+2. Supports nested paths via [RFC6570 wildcard expansion](https://www.rfc-editor.org/rfc/rfc6570).
+3. Typical examples include `index.md`, `usage.md`, `skills/<skill-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.md`.
+
+### `resource://catalog/prompts_index`
+
+1. Returns a compact list of prompt records for discovery.
+2. Contains one entry per `prompt_id`.
+3. Includes `id`, `name`, `description`, `tags`, `version`, and canonical document URI.
+
+### `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
+
+1. Returns the same record family as `resource://catalog/skills_index` with optional filtering and pagination.
+2. Query parameters are optional and composable.
+3. Unknown query keys are ignored or rejected deterministically by server policy.
+
+### `resource://catalog/prompts_index{?q,tag,cursor,limit}`
+
+1. Returns the same record family as `resource://catalog/prompts_index` with optional filtering and pagination.
+2. Query parameters are optional and composable.
+3. Unknown query keys are ignored or rejected deterministically by server policy.
+
+### `resource://catalog/prompts/{prompt_id}`
+
+1. Returns one normalized record for `prompt_id`.
+2. Includes prompt argument metadata when declared in frontmatter.
+3. Returns not found when `prompt_id` does not exist.
+
+### `resource://prompts/{prompt_id}/document`
+
+1. Returns the canonical prompt markdown document.
+2. `prompt_id` must satisfy lowercase kebab-case rules.
+
+## Template Parameter And Validation Rules
+
+### `skill_id`
+
+1. Lowercase kebab-case.
+2. Must satisfy the stable skill id rules from the content contract.
+
+### `ref_id`
+
+1. Lowercase kebab-case.
+2. Must be declared in the skill's references manifest.
+
+### `path*`
+
+1. Relative POSIX path only, expressed as URI path segments under [RFC3986 path syntax](https://www.rfc-editor.org/rfc/rfc3986#section-3.3).
+2. No leading slash.
+3. No `..` traversal segments.
+4. Resolves only inside `docs/`.
+5. Markdown-only in the end state, meaning `.md` files.
+6. Any reserved URI characters in path segments must be [percent-encoded](https://www.rfc-editor.org/rfc/rfc3986#section-2.1).
+
+### `prompt_id`
+
+1. Lowercase kebab-case.
+2. Must be unique across prompt ids and must not collide with skill ids.
+
+## URI Hygiene Rules
+
+1. Use lowercase, human-readable path segments for stable discoverability.
+2. Keep identifiers immutable once public whenever practical.
+3. Keep template variables semantic (`skill_id`, `prompt_id`, `ref_id`, `path*`) and avoid overloading one variable for unrelated meanings.
+4. Do not include secrets, tokens, or user-identifying data in URI paths or query strings.
+5. Prefer additive query parameters for discovery over introducing parallel URI families, matching [MCP resource-template discovery patterns](https://modelcontextprotocol.io/docs/learn/server-concepts#resources).
+6. Return clear not-found semantics for unknown ids and invalid template resolution.
+
+## URI Versioning Policy
+
+Default rule:
+
+1. Keep URIs unversioned by default.
+2. Allow URI and payload updates when they improve clarity or implementation simplicity.
+
+Breaking-change rule:
+
+1. Breaking changes use direct replacement of the canonical URI family.
+2. No compatibility aliases or dual URI families are maintained.
+
+FastMCP version metadata usage:
+
+1. Resource `version` metadata may be used for implementation and version discovery.
+2. URI readability and maintainability remain the primary contract.
+
+## Reference Id Compatibility Policy
+
+`ref_id` is the public identifier for a reference document, separate from file path.
+
+Rules:
+
+1. Prefer keeping `ref_id` stable when practical.
+2. File paths may change without URI churn as long as the mapped `ref_id` still resolves.
+3. If a reference is renamed, introduce a new `ref_id` and treat the old one as retired.
+4. Avoid reusing retired `ref_id` values for unrelated content.
+
+## Invariants
+
+This contract guarantees:
+
+1. One canonical URI pattern per core capability surface.
+2. Fast, low-friction URI evolution through direct replacement of canonical URIs.
+3. A single canonical catalog URI family with no alias maintenance overhead.
+4. Reference mappings can evolve with minimal churn.
+
+## Non-Goals
+
+This contract does not define:
+
+1. Implementation-specific transform wiring details, such as `VersionFilter`, mounts, or provider composition.
+2. Migration script mechanics for auto-generating aliases.
+3. Authorization policy design for URI-level access control.
+
+## Sources
+
+1. [MCP Server Concepts: Resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources)
+2. [MCP Architecture Overview](https://modelcontextprotocol.io/docs/learn/architecture)
+3. [MCP Specification Repository](https://github.com/modelcontextprotocol/spec)
+4. [RFC6570 URI Template](https://www.rfc-editor.org/rfc/rfc6570)

docs/copilot.md

@@ -69,6 +69,15 @@ When resource attachment is unavailable in the active session, use ResourcesAsTo
 4. `get_pattern_by_id`
 5. `get_skill_document_by_id`
 
+Canonical naming policy:
+
+1. Prefer the five canonical tool names above in prompts and instructions.
+2. For compatibility with clients that emit `catalog_*` naming, the server also exposes:
+	- `catalog_search_patterns`
+	- `catalog_get_pattern_by_id`
+	- `catalog_get_skill_document_by_id`
+3. Canonical and compatibility alias tools return equivalent payloads for the same input.
+
 The first two are generated from the canonical resource surface and should be preferred in tool-only clients.
 
 These should stay read-only, minimal, and schema-aligned with catalog resources.
@@ -116,7 +125,7 @@ Use the personal-mcp catalog tools to search for the most relevant skill for Fas
 Example direct-load prompt:
 
 ```text
-Call get_skill_document_by_id for fastapi-async-sqlalchemy-modernization and use that document as the main context for this task.
+Call get_skill_document_by_id for async-fastapi-sqlmodel and use that document as the main context for this task.
 ```
 
 Example bounded-selection prompt:

docs/frontmatter.md

@@ -1,316 +0,0 @@
----
-icon: lucide/braces
----
-
-# Frontmatter Contract
-
-This page defines the `SKILL.md` frontmatter and FastMCP metadata contract.
-
-## Anthropic Frontmatter Support
-
-Across Anthropic API and Agent Skills surfaces:
-
-1. Required fields for custom skill bundles are `name` and `description`.
-2. `name` must be 1-64 characters, lowercase letters, numbers, and hyphens only, with no XML tags, and must not use the reserved words `anthropic` or `claude`.
-3. `description` must be 1-1024 characters, non-empty, and contain no XML tags.
-
-Portable optional fields from the Agent Skills specification:
-
-1. `license`
-2. `compatibility`
-3. `metadata`
-4. `allowed-tools`
-
-Claude Code-specific optional fields:
-
-1. `when_to_use`
-2. `argument-hint`
-3. `arguments`
-4. `disable-model-invocation`
-5. `user-invocable`
-6. `allowed-tools`
-7. `disallowed-tools`
-8. `model`
-9. `effort`
-10. `context`
-11. `agent`
-12. `hooks`
-13. `paths`
-14. `shell`
-
-Repository contract decisions:
-
-1. Treat `name` and `description` as required in all `SKILL.md` files.
-2. Keep Anthropic-facing semantics in standard fields.
-3. Keep MCP indexing metadata in a namespaced extension block.
-4. Preserve forward compatibility by allowing additive optional metadata fields over time.
-
-## Canonical Frontmatter Schema
-
-Use this two-layer pattern:
-
-1. Anthropic layer: top-level fields intended for Anthropic and Agent Skills behavior.
-2. Repository layer: one namespaced block, `x-personal-mcp`, for MCP catalog and routing metadata.
-
-Canonical shape:
-
-```yaml
----
-name: <skill-id>
-description: <what this skill does and when to use it>
-
-# Optional Anthropic and Agent Skills fields
-when_to_use: <extra trigger guidance>
-allowed-tools: <space-separated string or YAML list>
-disable-model-invocation: false
-user-invocable: true
-license: <optional>
-compatibility: <optional>
-
-# Repository-specific metadata
-x-personal-mcp:
-  id: <skill-id>
-  version: <semver>
-  tags:
-    - <tag>
-  capabilities:
-    - resource://skills/<skill-id>/document
-  depends_on: []
-    # Optional: overrides and nested references only.
-    # Top-level references/*.md are auto-discovered.
-  references:
-    <ref-id>:
-      path: references/<file>.md
-      mime_type: text/markdown
-      title: <short title>
----
-```
-
-## Repository Metadata Field Rules
-
-Rules for `x-personal-mcp`:
-
-1. `id` is required, must follow the skill id rules from the content contract, and must equal the directory name.
-2. `version` is required and must be a semantic version string.
-3. `tags` is optional and should be a list of kebab-case discovery labels.
-4. `capabilities` is required and lists the MCP URIs the skill publishes.
-5. `depends_on` is optional and lists other skill ids.
-6. `references` is an optional map keyed by `ref-id` for overrides and nested entries.
-
-Reference entry rules:
-
-1. `ref-id` is lowercase kebab-case.
-2. `path` is a skill-relative markdown path and must stay inside the same skill directory.
-3. Top-level files under `references/*.md` are auto-discovered with `ref-id` derived from a normalized filename stem (lowercase kebab-case).
-4. Nested folders under `references/` are not auto-discovered and must be declared explicitly.
-5. `mime_type` defaults to `text/markdown` when omitted.
-6. `title` is an optional display label.
-7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
-
-## Validation Models
-
-The normative model uses Pydantic v2 with change-friendly validation:
-
-```python
-from __future__ import annotations
-
-import re
-from pathlib import PurePosixPath
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-SKILL_ID_RE = re.compile(r"^[a-z][a-z0-9-]*$")
-SEMVER_RE = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:[-+][0-9A-Za-z.-]+)?$")
-
-
-class ReferenceEntry(BaseModel):
-    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
-
-    path: str
-    mime_type: str = "text/markdown"
-    title: str | None = None
-
-    @field_validator("path")
-    @classmethod
-    def validate_reference_path(cls, value: str) -> str:
-        p = PurePosixPath(value)
-        if p.is_absolute() or ".." in p.parts:
-            raise ValueError("reference path must be a relative in-skill path")
-        if not str(p).startswith("references/"):
-            raise ValueError("reference path must stay under references/")
-        if p.suffix.lower() != ".md":
-            raise ValueError("reference path must target a markdown file")
-        return str(p)
-
-
-class PersonalMcpMetadata(BaseModel):
-    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
-
-    id: str
-    version: str
-    tags: list[str] = Field(default_factory=list)
-    capabilities: list[str] = Field(min_length=1)
-    depends_on: list[str] = Field(default_factory=list)
-    references: dict[str, ReferenceEntry] = Field(default_factory=dict)
-
-    @field_validator("id")
-    @classmethod
-    def validate_id(cls, value: str) -> str:
-        if not SKILL_ID_RE.fullmatch(value):
-            raise ValueError("id must be lowercase kebab-case and start with a letter")
-        return value
-
-    @field_validator("version")
-    @classmethod
-    def validate_version(cls, value: str) -> str:
-        if not SEMVER_RE.fullmatch(value):
-            raise ValueError("version must be semver")
-        return value
-
-    @field_validator("depends_on")
-    @classmethod
-    def validate_depends_on(cls, value: list[str]) -> list[str]:
-        for dep in value:
-            if not SKILL_ID_RE.fullmatch(dep):
-                raise ValueError(f"invalid depends_on skill id: {dep}")
-        return value
-
-    @field_validator("references")
-    @classmethod
-    def validate_reference_ids(cls, value: dict[str, ReferenceEntry]) -> dict[str, ReferenceEntry]:
-        for ref_id in value:
-            if not SKILL_ID_RE.fullmatch(ref_id):
-                raise ValueError(f"invalid reference id: {ref_id}")
-        return value
-
-    @model_validator(mode="after")
-    def ensure_primary_capability(self) -> "PersonalMcpMetadata":
-        expected = f"resource://skills/{self.id}/document"
-        if expected not in self.capabilities:
-            raise ValueError(f"capabilities must include {expected}")
-        return self
-
-
-class SkillFrontmatter(BaseModel):
-    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
-
-    name: str = Field(min_length=1, max_length=64)
-    description: str = Field(min_length=1, max_length=1024)
-    when_to_use: str | None = None
-    allowed_tools: str | list[str] | None = Field(default=None, alias="allowed-tools")
-    disallowed_tools: str | list[str] | None = Field(default=None, alias="disallowed-tools")
-    disable_model_invocation: bool | None = Field(default=None, alias="disable-model-invocation")
-    user_invocable: bool | None = Field(default=None, alias="user-invocable")
-    argument_hint: str | None = Field(default=None, alias="argument-hint")
-    arguments: str | list[str] | None = None
-    license: str | None = None
-    compatibility: str | None = None
-    metadata: dict[str, str] | None = None
-
-    x_personal_mcp: PersonalMcpMetadata = Field(alias="x-personal-mcp")
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, value: str) -> str:
-        if not SKILL_ID_RE.fullmatch(value):
-            raise ValueError("name must be lowercase kebab-case and start with a letter")
-        if "anthropic" in value or "claude" in value:
-            raise ValueError("name must not contain reserved words anthropic or claude")
-        return value
-
-    @model_validator(mode="after")
-    def cross_validate(self) -> "SkillFrontmatter":
-        if self.x_personal_mcp.id != self.name:
-            raise ValueError("x-personal-mcp.id must exactly match name")
-        return self
-
-
-def validate_skill_frontmatter(raw: dict[str, Any], skill_dir_name: str) -> SkillFrontmatter:
-    model = SkillFrontmatter.model_validate(raw)
-    if model.name != skill_dir_name:
-        raise ValueError("frontmatter name must exactly match skill directory name")
-    return model
-```
-
-Validation behavior contract:
-
-1. Validate required core fields and relationships during registry load before FastMCP resource or tool registration.
-2. Allow unknown additive fields so frontmatter can evolve without blocking startup.
-3. Treat hard contract violations, including missing required fields, invalid ids, and broken required mappings, as startup errors.
-4. Treat non-critical compatibility issues as warnings when possible.
-5. Error messages should include the skill path and failing field for CI readability.
-
-Projection mode contract for Anthropic API upload pipelines:
-
-1. Parse with `SkillFrontmatter` first.
-2. Emit Anthropic-safe frontmatter with standard fields only.
-3. Serialize repository metadata into standard `metadata` as namespaced keys.
-4. Preserve the canonical authored source in `x-personal-mcp`; projection output is a build artifact.
-
-## Anthropic Upload Compatibility Rule
-
-1. Anthropic documentation guarantees behavior for standard frontmatter fields but does not explicitly guarantee handling of arbitrary unknown top-level keys.
-2. Publishing pipelines that target strict API compatibility should support a projection mode that emits only standard frontmatter fields for upload.
-3. In projection mode, repository extension metadata is serialized into the standard `metadata` field as namespaced keys or JSON-encoded values, while source-of-truth authoring remains in `x-personal-mcp`.
-
-## FastMCP Native Metadata Surfaces
-
-Resources support native definition metadata:
-
-1. `name`
-2. `description`
-3. `mime_type`
-4. `tags`
-5. `annotations`, including `readOnlyHint` and `idempotentHint`
-6. `icons`
-7. `meta`
-8. `version`
-9. `enabled`, which is deprecated in FastMCP v3 in favor of server-level enable and disable controls
-
-Resources also support runtime metadata through `ResourceContent.meta` and `ResourceResult.meta`.
-
-Tools support native definition metadata:
-
-1. `name`
-2. `description`
-3. `tags`
-4. `annotations`, including `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`
-5. `icons`
-6. `meta`
-7. `version`
-8. `timeout`
-9. `output_schema`
-10. `run_in_thread`
-11. `enabled`, which is deprecated in FastMCP v3 in favor of server-level enable and disable controls
-
-Tools also support runtime metadata through `ToolResult.meta`.
-
-## Frontmatter To FastMCP Mapping Contract
-
-At server startup, map `x-personal-mcp` into FastMCP registration as follows:
-
-1. `x-personal-mcp.id` defines the canonical URI namespace and identity checks.
-2. `description` becomes the default description for the primary skill document resource.
-3. `x-personal-mcp.tags` maps to resource and tool tags.
-4. `x-personal-mcp.version` maps to resource and tool version metadata.
-5. `x-personal-mcp.capabilities` becomes the registered URI list and catalog exposure.
-6. `x-personal-mcp.references[*]` becomes resource templates or concrete resources with `mime_type`, read-only annotations, and `meta` that includes `skill_id`, `ref_id`, and source `path`.
-7. `x-personal-mcp.depends_on` becomes catalog dependency graph metadata and validation inputs.
-
-## Invariants
-
-This contract guarantees:
-
-1. Anthropic-required frontmatter stays valid for custom skill upload and Claude Code loading.
-2. MCP-specific metadata remains embedded in `SKILL.md` frontmatter, with no `metadata.yaml` sidecar.
-3. FastMCP registration uses native metadata fields for resources and tools.
-4. Reference ids and metadata can evolve with low-friction updates while internal file layout under `references/` stays refactor-friendly.
-
-## Non-Goals
-
-This contract does not define:
-
-1. URI versioning and deprecation rollout policy details.
-2. Migration script design from existing `metadata.yaml` files.
-3. Runtime caching and indexing performance tuning.

docs/index.md

@@ -22,10 +22,10 @@ Install dependencies first:
 uv sync
 ```
 
-Run the app locally with the static docs rebuilt first:
+Run the app locally with the static docs rebuilt first, using [Uvicorn factory mode](https://www.uvicorn.org/settings/#application):
 
 ```bash
-uv run zensical build && uv run uvicorn personal_mcp.main:app --host 127.0.0.1 --port 8765
+uv run zensical build && uv run uvicorn personal_mcp.main:create_app --factory --host 127.0.0.1 --port 8765
 ```
 
 Build and run the Docker image with the same exposed port:
@@ -39,9 +39,10 @@ When the server is running, the health check is available at `/healthz` and the
 ## Architecture
 
 - [Resource-First Pattern Module Architecture](./architecture.md)
-- [Content Contract](./content.md)
-- [Frontmatter Contract](./frontmatter.md)
-- [URI Contract](./uris.md)
+- [Contracts](./contracts/index.md)
+- [Content Contract](./contracts/index.md#content-contract)
+- [Frontmatter Contract](./contracts/frontmatter.md)
+- [URI Contract](./contracts/uris.md)
 - [Static Docs Hosting Pattern](./mcp_layout.md)
 - [Skill Usage Mechanics](./usage.md)
 - [Copilot MCP Mechanics](./copilot.md)

docs/javascripts/mathjax.js

@@ -0,0 +1,25 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [['\\(', '\\)']],
+    displayMath: [['\\[', '\\]']],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: '.*|',
+    processHtmlClass: 'arithmatex'
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache();
+  MathJax.typesetClear();
+  MathJax.texReset();
+  MathJax.typesetPromise();
+});
+
+component$.subscribe(({ ref }) => {
+  if (ref.classList.contains('md-annotation')) {
+    MathJax.typesetPromise([ref]);
+  }
+});

docs/mcp_layout.md

@@ -32,55 +32,35 @@ treeView-beta
       "zensical.toml"
       "docs"
          "index.md"
-         "architecture.md"
-         "content.md"
-         "frontmatter.md"
+         "<project-docs>.md"
+         "contracts"
+            "index.md"
+            "<contract-pages>.md"
          "mcp_layout.md"
-         "uris.md"
+         "prompts"
+            "<prompt-id>"
+               "PROMPT.md"
+               "references"
          "skills"
-            "new-skill"
-               "SKILL.md"
-               "references"
-            "copilot-customization"
-               "SKILL.md"
-               "references"
-            "fastapi-async-sqlalchemy-modernization"
-               "SKILL.md"
-               "references"
-            "fastapi-uv-docker"
-               "SKILL.md"
-               "references"
-            "nicegui"
-               "SKILL.md"
-               "references"
-            "nicegui-ui-customization"
-               "SKILL.md"
-               "references"
-            "pytest-scaffolding"
-               "SKILL.md"
-               "references"
-            "python-logging-dictconfig"
-               "SKILL.md"
-               "references"
-            "vscode-configuration"
-               "SKILL.md"
-               "references"
-            "zensical-docs"
+            "<skill-id>"
                "SKILL.md"
                "references"
+                  "<reference>.md"
       "site"
          "static build output"
       "src"
          "personal_mcp"
+            "__init__.py"
             "main.py"
             "mcp.py"
-            "web"
-               "app.py"
-               "docs_mount.py"
             "catalog"
-               "server.py"
+               "<catalog-modules>.py"
+            "registry"
+               "<registry-modules>.py"
+            "web"
+               "<web-modules>.py"
             "skills"
-               "document_loader.py"
+               "<skills-modules>.py"
 ```
 
 Notes:
@@ -88,7 +68,8 @@ Notes:
 1. docs contains both project-authored pages and the canonical skill Markdown tree.
 2. site contains static build output only.
 3. docs/skills contains canonical skill Markdown and reference Markdown.
-4. MCP resources and docs site read from the same Markdown sources.
+4. docs/prompts contains canonical prompt Markdown used for prompt catalog and document surfaces.
+5. MCP resources and docs site read from the same Markdown sources.
 
 ## Runtime Composition
 
@@ -146,7 +127,11 @@ Example mapping model:
 Catalog discovery resources are:
 
 1. resource://catalog/skills_index
-2. resource://catalog/skills/{skill_id}
+2. resource://catalog/skills_index{?q,tag,capability,cursor,limit}
+3. resource://catalog/skills/{skill_id}
+4. resource://catalog/prompts_index
+5. resource://catalog/prompts_index{?q,tag,cursor,limit}
+6. resource://catalog/prompts/{prompt_id}
 
 Registry-backed registration details:
 
@@ -208,8 +193,9 @@ This keeps docs publication explicit and predictable.
 
 Existing reference docs remain valid content inputs in this pattern:
 
-1. docs/skills/pytest-scaffolding/references/pytest-docs.md
-2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
-3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
+1. docs/skills/pytesting/references/pytest-docs.md
+2. docs/skills/python-logging/references/python-logging-docs.md
+3. docs/skills/python-logging/references/json-file-logging.md
+4. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
 
 These are source documents, not deployment artifacts.

docs/new_skill.md

@@ -1,129 +0,0 @@
----
-icon: lucide/file-plus
----
-
-# Hooking Up a New Skill
-
-Use this checklist to add a new skill in the docs-first model.
-
-For the full contract details, see [Content Contract](./content.md), [Frontmatter Contract](./frontmatter.md), and [URI Contract](./uris.md).
-
-## Canonical Skill Shape
-
-Create one skill directory under `docs/skills/`:
-
-```text
-docs/
-  skills/
-    <skill-id>/
-      SKILL.md
-      references/
-        ... (optional markdown files, nested folders allowed)
-```
-
-Rules:
-
-1. `SKILL.md` is required.
-2. All skill-specific supporting docs live under `references/`.
-3. Skill directories are ownership boundaries; no cross-skill writes.
-4. `skill-id` is lowercase kebab-case and should remain stable.
-
-## SKILL.md Frontmatter
-
-`SKILL.md` frontmatter is authoritative for metadata.
-
-Required top-level fields:
-
-1. `name`
-2. `description`
-3. `x-personal-mcp`
-
-Required `x-personal-mcp` fields:
-
-1. `id`
-2. `version`
-3. `capabilities`
-
-Optional `x-personal-mcp` fields:
-
-1. `tags`
-2. `depends_on`
-3. `references`
-
-Canonical frontmatter template:
-
-```yaml
----
-name: <skill-id>
-description: <what this skill does and when to use it>
-
-x-personal-mcp:
-  id: <skill-id>
-  version: 1.0.0
-  tags: []
-  capabilities:
-    - resource://skills/<skill-id>/document
-  depends_on: []
-  # Optional: only for nested references or metadata overrides.
-  references:
-    <ref-id>:
-      path: references/<file>.md
-      mime_type: text/markdown
-      title: <optional short title>
----
-```
-
-Reference manifest rules:
-
-1. `ref-id` is lowercase kebab-case.
-2. `path` is skill-relative and must stay under `references/`.
-3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
-4. Nested `references/**` markdown files must be declared explicitly.
-5. Reference paths are markdown files.
-
-No `metadata.yaml` sidecar is part of this model.
-
-## URI Surface
-
-Canonical resource URIs for a skill:
-
-1. `resource://skills/<skill_id>/document`
-2. `resource://skills/<skill_id>/references/<ref_id>`
-
-Canonical discovery URIs:
-
-1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
-
-Docs passthrough URI:
-
-1. `resource://docs/{path*}`
-
-Compatibility rule:
-
-1. Keep URI families unversioned by default.
-2. For breaking changes, update clients to the canonical replacement URIs directly.
-
-## Checklist
-
-1. Create `docs/skills/<skill-id>/SKILL.md`.
-2. Add optional references under `docs/skills/<skill-id>/references/`.
-3. Populate frontmatter with `name`, `description`, and `x-personal-mcp` metadata.
-4. Ensure `x-personal-mcp.id` equals `name` and directory `<skill-id>`.
-5. Ensure `capabilities` includes `resource://skills/<skill-id>/document`.
-6. Add supporting docs under `references/`; top-level markdown files are exposed automatically.
-7. Declare `x-personal-mcp.references` only for nested paths or to override defaults.
-
-## Quick Validation
-
-1. Confirm docs build succeeds:
-
-```bash
-uv run zensical build
-```
-
-2. Confirm tests succeed:
-
-```bash
-uv run pytest -q
-```

docs/prompts/authoring/PROMPT.md

@@ -0,0 +1,88 @@
+---
+name: authoring
+description: Provide a practical checklist and baseline template for authoring docs-first MCP modules and repository-specific Copilot instruction shims.
+x-personal-mcp:
+  id: authoring
+  version: 1.0.0
+  tags:
+    - authoring
+    - mcp
+    - fastmcp
+    - copilot
+    - prompts
+    - scaffolding
+  capabilities:
+    - resource://prompts/authoring/document
+  arguments:
+    artifact_type:
+      title: Artifact type
+      description: "Enum (case-sensitive): skill | prompt | shim."
+      required: true
+    artifact_id:
+      title: Artifact id
+      description: Lowercase kebab-case id for the module or shim.
+      required: true
+    goal:
+      title: Goal
+      description: One-sentence capability statement describing what to create and when to use it.
+      required: true
+    scope_glob:
+      title: Scope glob
+      description: Optional applyTo glob for shim outputs.
+      required: false
+---
+
+# Authoring Bootstrap
+
+Use this prompt to author or update docs-first MCP modules in this repository, including repository-specific Copilot thin shims.
+
+## Inputs
+
+1. artifact_type: one of skill, prompt, shim
+2. artifact_id: lowercase kebab-case id
+3. goal: one-sentence capability statement
+4. optional scope_glob for shim outputs
+
+## Required References
+
+Load only what matches the requested artifact:
+
+1. Authoring workflow and validation policy: [Authoring Guide](../../authoring.md)
+2. Prompt metadata and structure: [Prompt Contract](../../contracts/prompt.md)
+3. Skill metadata and structure (only for skill outputs): [Skill Contract](../../contracts/skill_contract.md)
+4. Thin shim mechanics and path binding: [Skill Usage Mechanics](../../usage.md)
+5. Copilot resource attachment and fallback behavior: [Copilot MCP Mechanics](../../copilot.md)
+
+## Workflow
+
+1. Validate required inputs and ask one clarifying question if any required input is missing.
+2. Keep ids and slugs aligned with folder names and frontmatter ids.
+3. Enforce artifact_type enum values exactly: skill, prompt, shim.
+4. If artifact_type is outside the enum, ask one correction question and stop before generating output.
+5. Apply YAML safety rules for frontmatter values:
+  - quote values containing `:`
+  - prefer quotes for punctuation-heavy scalars
+  - use block scalars for multiline descriptions
+6. Run immediate validation after frontmatter edits:
+  - `uv run zensical build`
+  - `uv run pytest -q`
+7. Produce only the requested artifact type.
+8. Keep guidance deterministic and minimal, with explicit references to source docs.
+9. If artifact_type is shim:
+   - bind one applyTo scope to one primary skill resource URI
+   - prefer MCP resource attachment first
+   - if resource attachment is unavailable, use fallback tool order:
+     1. list_resources
+     2. read_resource
+     3. search_patterns
+     4. get_pattern_by_id
+     5. get_skill_document_by_id
+10. Return created or updated file paths and any validation commands that should be run.
+
+## Output Contract
+
+Return:
+
+1. Files created or updated.
+2. Which references were used.
+3. Validation commands and outcomes (or commands to run if execution is not requested).

docs/prompts/greenfield-architecture/PROMPT.md

@@ -0,0 +1,111 @@
+---
+name: greenfield-architecture
+description: Research established patterns and design a high-level architecture for a new app or library with explicit tradeoffs and test strategy.
+x-personal-mcp:
+  id: greenfield-architecture
+  version: 1.0.0
+  tags:
+    - architecture
+    - planning
+    - greenfield
+    - design
+    - testing
+    - prompts
+  capabilities:
+    - resource://prompts/greenfield-architecture/document
+  arguments:
+    scope_type:
+      title: Scope type
+      description: "Scope type: app or library."
+      required: true
+    intent_document:
+      title: Intent document
+      description: Optional full document describing goals, context, and desired outcomes.
+      required: false
+    problem_domain:
+      title: Problem domain
+      description: Domain and business goal for the new app or library when no full intent document is provided.
+      required: false
+    constraints:
+      title: Constraints
+      description: Runtime, deployment, and non-functional constraints.
+      required: false
+---
+
+# Greenfield Architecture Planner
+
+Use this prompt to design a new software app or library architecture in generic terms.
+
+## Inputs
+
+1. intent_document: optional full document that explains goals, context, constraints, and desired outcomes
+2. problem_domain: concise domain and one-sentence business goal when no full intent document is provided
+3. scope_type: app or library
+4. optional constraints: runtime, deployment, scale, non-functional priorities
+
+If both intent_document and problem_domain are provided, treat intent_document as the primary source and use problem_domain as a summary cross-check.
+
+## Workflow
+
+1. Validate required inputs.
+  - scope_type is required
+  - at least one of intent_document or problem_domain must be provided
+  - ask one concise clarification question if inputs are incomplete or contradictory
+2. Start with research before proposing architecture:
+   - identify at least three established patterns or methodologies used for similar systems
+   - summarize what each pattern optimizes for
+   - compare strengths, risks, and implementation complexity
+3. Ask which aspects of those patterns matter most for the user context.
+4. Identify major libraries or frameworks commonly used for this problem space and explain tradeoffs for each:
+   - strengths and weaknesses
+   - ecosystem maturity
+   - performance profile
+   - operational complexity
+   - learning curve
+5. Recommend one primary stack and one fallback stack, with rationale tied to stated priorities.
+6. Produce the architecture deliverables:
+   - high-level concepts, features, and requirements
+   - intended use cases and key workflows
+   - high-level package/module structure
+   - conceptual boundaries for each module (what belongs there and what does not)
+   - dependency and data-flow direction between modules
+7. Plan incremental delivery with explicit growth paths:
+  - define the initial prototype slice with the smallest valuable feature set
+  - identify which features are intentionally deferred from the prototype
+  - describe extension paths that add complexity in controlled stages
+  - ensure each stage preserves clean module boundaries and low migration risk
+8. Design a test strategy aligned to the proposed structure and staged delivery plan:
+   - unit, integration, contract, and end-to-end layers
+  - what each layer should cover in prototype stage vs extension stages
+   - fixture and environment setup for fast, deterministic tests
+   - boundary seams for mocks/fakes and minimization of nondeterministic external I/O
+   - CI execution approach for fast feedback and confidence
+9. Call out key risks, assumptions, and open questions.
+
+## Output Contract
+
+Return these sections in order:
+
+1. Research Summary
+2. Pattern Comparison
+3. Library and Framework Tradeoffs
+4. Recommended Stack
+5. Architecture Overview
+6. Concepts, Features, and Requirements
+7. Intended Use Cases
+8. Package and Module Layout
+9. Conceptual Boundary Map
+10. Initial Prototype Scope
+11. Extension Roadmap
+12. Test Strategy
+13. Risks and Open Questions
+14. Next Implementation Steps
+
+## Quality Rules
+
+1. Keep language generic and project-agnostic.
+2. Prefer established patterns over novelty unless there is a strong reason to diverge.
+3. Tie each recommendation to an explicit requirement or tradeoff.
+4. Make assumptions explicit and concise.
+5. Ask one focused clarifying question when confidence is low instead of over-speculating.
+6. Prefer architecture decisions that support starting simple and growing complexity without major rewrites.

docs/prompts/mcp-consumer-repo-shim/PROMPT.md

@@ -0,0 +1,111 @@
+---
+name: mcp-consumer-repo-shim
+description: Create one repository-specific thin shim instruction file that binds a file scope to a user-selected Personal MCP skill resource and enforces resource-first Copilot retrieval behavior.
+x-personal-mcp:
+  id: mcp-consumer-repo-shim
+  version: 1.0.0
+  tags:
+    - copilot
+    - mcp
+    - instructions
+    - shims
+    - prompts
+  capabilities:
+    - resource://prompts/mcp-consumer-repo-shim/document
+  arguments:
+    apply_to_glob:
+      description: File glob scope for the shim applyTo field, such as tests/** or **/*.md.
+      required: true
+    primary_skill_resource:
+      description: Primary skill resource URI, usually resource://skills/<skill-id>/document.
+      required: true
+    shim_title:
+      description: Human-readable name for the instruction shim frontmatter.
+      required: false
+    companion_docs_page:
+      description: Optional relative docs link for human-facing companion guidance.
+      required: false
+---
+
+# MCP Consumer Repository Shim
+
+Use this prompt to generate exactly one repository-scoped Copilot instruction shim for an MCP consumer repository.
+
+## Inputs
+
+- Required:
+  - apply_to_glob
+  - primary_skill_resource
+- Optional:
+  - shim_title
+  - companion_docs_page
+
+## Required References
+
+Load only sections relevant to the requested shim:
+
+1. Thin shim pattern and scope guidance: [Skill Usage Mechanics](../../usage.md)
+2. VS Code Copilot MCP behavior and fallback mechanics: [Copilot MCP Mechanics](../../copilot.md)
+3. Authoring workflow and validation checklist: [Authoring Guide](../../authoring.md)
+4. Instruction metadata expectations and examples: [Copilot customization skill](../../skills/copilot-customization/SKILL.md)
+
+## Workflow
+
+1. Validate that apply_to_glob and primary_skill_resource are present.
+2. If either value is missing or ambiguous, ask exactly one clarifying question before generating output.
+3. Generate one .instructions.md file content block only.
+4. Keep the shim concise and deterministic:
+   - include YAML frontmatter with name, description, and applyTo
+   - include a primary rule that uses the selected primary_skill_resource first
+   - include a bounded execution pattern (load primary doc, apply only relevant sections, keep edits minimal)
+5. Include VS Code/Copilot integration mechanics in the shim body:
+   - prefer MCP resource attachment when available
+   - if attachment is unavailable, use tool fallback order:
+     1. list_resources
+     2. read_resource
+     3. search_patterns
+     4. get_pattern_by_id
+     5. get_skill_document_by_id
+   - ask one clarifying question when confidence is low
+6. If companion_docs_page is provided, include it as a companion docs link line.
+7. Do not generate additional files, code changes, or batch shim packs.
+
+## Output Format
+
+Return exactly:
+
+1. Suggested file path line under .github/instructions/.
+2. One fenced markdown block containing the full .instructions.md content.
+3. A brief note (max 3 lines) describing what the shim routes and why.
+
+## Output Template
+
+````md
+Path: .github/instructions/<slug>.instructions.md
+
+```md
+---
+name: <shim-title>
+description: Route <scope> edits to the Personal MCP <skill-id> resource.
+applyTo: '<apply_to_glob>'
+---
+
+When editing files matching <apply_to_glob>, use <primary_skill_resource> as the primary guidance source.
+
+Execution pattern:
+
+1. Load the primary skill document first.
+2. Apply only sections relevant to the file being edited.
+3. Keep edits minimal and aligned with repository conventions.
+4. Prefer MCP resource attachment when available in the current chat surface.
+5. If MCP resource attachment is unavailable, use tool fallback in this order:
+   1. list_resources
+   2. read_resource
+   3. search_patterns
+   4. get_pattern_by_id
+   5. get_skill_document_by_id
+6. If confidence is low, ask one clarifying question before editing.
+
+Companion docs page: <optional-relative-doc-link>
+```
+````

docs/prompts/pytest-fill-scaffold/PROMPT.md

@@ -0,0 +1,90 @@
+---
+name: pytest-fill-scaffold
+description: Fill scaffolded pytest test methods with assertions, fixtures, and minimal test data while preserving concise test names and one-line intent docstrings.
+x-personal-mcp:
+  id: pytest-fill-scaffold
+  version: 1.0.0
+  tags:
+    - pytest
+    - testing
+    - scaffolding
+    - prompts
+  capabilities:
+    - resource://prompts/pytest-fill-scaffold/document
+  arguments:
+    target_files:
+      description: Target test file paths under tests/.
+      required: true
+    stack:
+      description: Runtime stack type for fixture and marker choices.
+      required: true
+    strategy:
+      description: Balance between minimal and comprehensive implementation.
+      required: false
+    marker_lane:
+      description: Preferred marker lane when applicable.
+      required: false
+---
+
+# Pytest Fill Scaffold
+
+Use this prompt after test scaffolding exists and method names/docstrings are already in place.
+
+## Inputs
+
+- Target test file(s) under tests/.
+- Stack type:
+  - pure-python
+  - fastapi
+  - sqlalchemy-sync
+  - sqlalchemy-async
+  - mixed
+- Optional constraints:
+  - keep implementation minimal vs comprehensive
+  - marker lane target (unit, integration, smoke)
+
+## Required References
+
+Load these in order and use only what matches the task:
+
+1. Core defaults: [pytest scaffolding skill](../../skills/pytesting/SKILL.md)
+2. Naming/hierarchy preservation: [naming and organization](../../skills/pytesting/references/naming-and-organization.md)
+3. Baseline pytest fixtures/markers: [pytest docs notes](../../skills/pytesting/references/pytest-docs.md)
+4. FastAPI-specific behavior (only when needed): [fastapi testing](../../skills/pytesting/references/fastapi-testing.md)
+5. SQLAlchemy-specific behavior (only when needed): [sqlalchemy testing](../../skills/pytesting/references/sqlalchemy-testing.md)
+
+## Workflow
+
+1. Inspect target files and treat human-reviewed docstring-only scaffolds as invariant.
+2. Convert each scaffolded method into an executable test with a single behavior focus.
+3. Keep one-line docstrings for class and method intent.
+4. Add or refine fixtures at the nearest useful scope:
+   - global in tests/conftest.py only when broadly reusable
+   - subtree conftest.py for domain-specific fixtures
+5. Assign markers consistent with cost and dependencies:
+   - unit for pure logic
+   - integration for framework/DB contracts
+   - smoke for thin critical-path checks
+6. Validate in this order:
+   - uv run pytest --collect-only -q
+   - uv run pytest -m unit -q when unit tests are touched
+   - uv run pytest -q if dependencies are available
+
+## Authoring Rules
+
+- Prefer deterministic tests and explicit setup/teardown.
+- Keep assertions precise and readable.
+- Do not overfit tests to private implementation details.
+- If a scaffolded class or method has only a docstring body, treat its name and hierarchy as locked.
+- Do not rename, move, merge, split, or re-nest docstring-only scaffolded tests unless explicitly requested.
+- Preserve existing one-line docstrings on scaffolded classes and methods unless they are factually incorrect.
+- If stack details are missing and would change fixture strategy, ask one concise clarifying question before editing.
+
+## Output Format
+
+Return:
+1. Files updated.
+2. Fixture and marker decisions.
+3. Which references were used and why.
+4. Validation command results.
+5. Risks or open questions.

docs/prompts/pytest-scaffold/PROMPT.md

@@ -0,0 +1,97 @@
+---
+name: pytest-scaffold
+description: Plan and optionally scaffold pytest file and class structure for selected Python modules while preserving concise behavior-focused test names and one-line intent docstrings.
+x-personal-mcp:
+  id: pytest-scaffold
+  version: 1.0.0
+  tags:
+    - pytest
+    - testing
+    - scaffolding
+    - prompts
+  capabilities:
+    - resource://prompts/pytest-scaffold/document
+  arguments:
+    target_modules:
+      description: Target module path(s) under src/.
+      required: true
+    mode:
+      description: Execution mode, either plan-only or scaffold.
+      required: true
+    path_strategy:
+      description: Optional mapping preference for src to tests paths.
+      required: false
+    naming_style:
+      description: Optional preference for concise method naming style.
+      required: false
+---
+
+# Pytest Scaffold
+
+Use this prompt to consistently plan and scaffold pytest test modules for selected Python source modules.
+
+## Inputs
+
+- Required:
+  - target_modules: one or more module paths under src/
+  - mode: one of plan-only or scaffold
+- Optional:
+  - path_strategy: preference for how source paths map into tests/
+  - naming_style: preference for concise method naming style
+
+## Required References
+
+Load these in order and apply only the relevant sections:
+
+1. Primary conventions: [Pytesting Skill](../../skills/pytesting/SKILL.md)
+2. Hierarchy and naming: [Naming and Organization](../../skills/pytesting/references/naming-and-organization.md)
+3. Marker and fixture defaults: [Pytest Docs Notes](../../skills/pytesting/references/pytest-docs.md)
+
+## Workflow
+
+1. Inspect the current tests/ layout and infer existing naming and grouping conventions.
+2. Propose a concise hierarchy plan first:
+   - test file paths
+   - class hierarchy
+   - method naming pattern
+   - fixture placement choices (tests/conftest.py or subtree conftest.py)
+3. If mode is scaffold, implement only the scaffold structure:
+   - create missing test modules
+   - create class hierarchy
+   - add one-line docstrings to each class and test method
+   - keep test method names short and behavior-focused
+4. Treat docstring-only scaffolds as an intentionally stable baseline for later fill-in work.
+5. Validate collection with:
+   - uv run pytest --collect-only -q
+6. Report outcomes:
+   - files created or updated
+   - collection result
+   - ambiguities and follow-up choices
+
+## Naming Defaults
+
+- Class naming:
+  - Test<PrimarySubject> as a top-level subject class
+  - nested Test<MethodOrArea> classes where extra context improves readability
+  - Test<FunctionName> top-level classes for standalone module functions
+- Method naming:
+  - test_<short_outcome>
+  - one behavior target per method
+  - one-line docstring for full intent
+
+## Authoring Rules
+
+1. Keep scope focused on structure and naming in this prompt.
+2. Do not fill test implementation details unless explicitly requested.
+3. Preserve established repository conventions when they are already present.
+4. If input constraints conflict, ask one concise clarifying question before editing.
+
+## Output Contract
+
+Return:
+
+1. Discovery summary and references used.
+2. Proposed or applied test tree.
+3. Class and method naming map.
+4. Validation command result.
+5. Open questions only when they block completion.

docs/skills/async-fastapi-sqlmodel/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: async-fastapi-sqlmodel
+description: 'Explain and apply async database principles for FastAPI, SQLAlchemy 2.x, and SQLModel. Use when: learning or reviewing AsyncEngine and AsyncSession lifecycles, FastAPI lifespan and yield dependencies, transaction boundaries, concurrency safety, implicit ORM I/O, AsyncExitStack, pooling, testing, or SQLModel integration.'
+x-personal-mcp:
+  id: async-fastapi-sqlmodel
+  version: 1.1.0
+  tags:
+    - fastapi
+    - sqlalchemy
+    - sqlmodel
+    - async
+    - asyncio
+    - database
+    - transactions
+    - resource-lifecycle
+    - architecture
+  capabilities:
+    - resource://skills/async-fastapi-sqlmodel/document
+---
+
+# Async FastAPI, SQLAlchemy, and SQLModel
+
+Use this skill to explain how an async database layer works, why the recommended patterns exist, and how to evaluate code against them. Teach the runtime model before suggesting implementation changes.
+
+Primary targets: PostgreSQL with asyncpg and SQLite with aiosqlite.
+
+## When to Use
+
+- Explain an async engine, session factory, session, connection, or transaction.
+- Review FastAPI lifespan or dependency-based database management.
+- Diagnose shared-session concurrency, implicit I/O, cleanup, or transaction problems.
+- Compare SQLModel's model conveniences with SQLAlchemy's async runtime APIs.
+- Decide whether a context manager, `AsyncExitStack`, eager loading, pooling option, or explicit transaction is appropriate.
+
+## Outcome
+
+Produce a focused technical explanation that:
+
+- Defines the objects involved and identifies who owns each one.
+- Traces acquisition, use, transaction behavior, and cleanup.
+- Separates required invariants from defaults and situational choices.
+- Explains failure modes and concurrency consequences.
+- Uses a minimal canonical pattern when code clarifies the mechanics.
+- Links claims to the relevant reference and upstream documentation.
+
+Do not default to producing a project plan. Give sequencing advice only when the user explicitly asks for implementation steps.
+
+## Mental Model
+
+Keep three ownership scopes distinct:
+
+| Scope | Object | Purpose | Typical owner |
+|---|---|---|---|
+| Application process | `AsyncEngine` and `async_sessionmaker` | Dialect, connection pool, and repeatable session configuration | FastAPI lifespan |
+| Request or concurrent task | `AsyncSession` | Mutable ORM identity map and transactional state | A `yield` dependency or explicit unit of work |
+| Atomic operation | `SessionTransaction` | Commit all changes together or roll them back together | Service or use-case boundary |
+
+The engine is a long-lived factory and pool, not a single database connection. The session is a mutable unit-of-work object, not a concurrency-safe global. A transaction is a consistency boundary, not merely a call to `commit()`.
+
+## Core Principles
+
+### Match lifetime to ownership
+
+- Create one `AsyncEngine` per process and database configuration in the normal case.
+- Dispose it explicitly in an awaitable shutdown path; garbage collection cannot reliably await async driver cleanup.
+- Configure `async_sessionmaker` once and call it to create short-lived sessions.
+- Close each session deterministically with `async with` or a FastAPI dependency that yields once.
+
+See [engine lifecycle](references/engine.md) and [session management](references/session.md).
+
+### Isolate mutable session state
+
+An `AsyncSession` represents one stateful transaction in progress. Never use one session in multiple concurrent tasks, including branches of `asyncio.gather()`. Give each task its own session and pass sessions explicitly rather than relying on mutable scoped globals.
+
+See [session management](references/session.md).
+
+### Make I/O visible
+
+Async ORM code must not unexpectedly issue SQL during ordinary attribute access. Load relationships and deferred columns explicitly with eager loader options such as `selectinload()`, use `awaitable_attrs` or `refresh()` for deliberate fallback loading, and consider `lazy="raise"` where accidental access should fail fast. `expire_on_commit=False` is a common async configuration because post-commit expiration can otherwise turn attribute reads into implicit I/O.
+
+See [implicit ORM I/O](references/implicit_io.md).
+
+### Put transactions around business invariants
+
+Use `async with session.begin():` when several operations must commit or roll back as one unit. A successful exit flushes and commits; an exception rolls back. Reads still participate in SQLAlchemy's autobegin behavior unless the connection uses true DBAPI autocommit, so describe a path as read-only because of application intent and permissions, not because a session silently has no transaction.
+
+Use `begin_nested()` only for a real SAVEPOINT requirement and account for backend-specific behavior. In SQLAlchemy 2.x, calling `session.commit()` commits the outermost transaction, not the current savepoint.
+
+See [transaction boundaries](references/transactions.md).
+
+### Keep framework boundaries explicit
+
+FastAPI lifespan owns resources shared by many requests. A dependency with one `yield` owns request-scoped resources and runs cleanup after use. These are related context-manager mechanisms but solve different lifetime problems.
+
+Use `AsyncExitStack` when lifespan acquires a variable, conditional, or mixed collection of context-managed resources. It records cleanup as resources are acquired and unwinds callbacks in reverse order. A single engine with one cleanup callback can use a plain `try/finally`; `AsyncExitStack` is a composition tool, not a requirement.
+
+See [engine lifecycle](references/engine.md).
+
+### Use SQLModel as the primary modeling layer
+
+Default to SQLModel for table models and API data models in FastAPI applications. A SQLModel table model is also a SQLAlchemy model, and every SQLModel model is also a Pydantic model, so shared base models can reduce schema duplication while preserving access to SQLAlchemy's full ORM.
+
+SQLModel does not replace SQLAlchemy's async engine, session, transaction, or loader mechanics. Its main tutorial currently demonstrates synchronous sessions and its advanced guide still lists comprehensive async documentation as future work. For async applications, combine SQLModel models and statements with SQLAlchemy's `AsyncSession` APIs. Use SQLAlchemy declarative models only when a concrete unsupported mapping or library constraint justifies the exception.
+
+See [SQLModel integration](references/sqlmodel.md).
+
+### Configure from evidence
+
+Pool sizing, overflow, recycle, pre-ping, isolation, statement timeouts, and health checks depend on the driver, database, deployment concurrency, and failure model. Explain defaults and tradeoffs before recommending values. Avoid treating pool checkout as proof that a useful query can succeed.
+
+See [observability and resilience](references/observability.md).
+
+## Reference Map
+
+| Concept | Reference |
+|---|---|
+| Engine lifecycle and ownership | [Engine lifecycle reference](references/engine.md) |
+| Session factory and scope | [Session management reference](references/session.md) |
+| Transaction boundaries | [Transaction boundaries reference](references/transactions.md) |
+| Lifespan composition | [Engine lifecycle reference](references/engine.md) |
+| Dependency injection | [Session management reference](references/session.md) |
+| Implicit I/O control in ORM | [Implicit I/O reference](references/implicit_io.md) |
+| Observability and resilience | [Observability reference](references/observability.md) |
+| SQLModel-first modeling | [SQLModel integration reference](references/sqlmodel.md) |
+| CRUD repository and standalone functions | [Basic CRUD reference](references/crud.md) |
+
+## Canonical Composition Pattern
+
+This example shows the ownership boundaries. Adapt state storage and dependency wiring to the application's conventions.
+
+```python
+from contextlib import AsyncExitStack, asynccontextmanager
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    async with AsyncExitStack() as stack:
+        engine = create_async_engine(settings.database_url)
+        stack.push_async_callback(engine.dispose)
+
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        app.state.session_factory = session_factory
+        yield
+
+
+async def get_session() -> AsyncIterator[AsyncSession]:
+   async with app.state.session_factory() as session:
+      yield session
+```
+
+For direct construction without `AsyncExitStack`, put `await engine.dispose()` in a `finally` block. For background work that outlives a request, create a new session inside that task instead of retaining the request's session.
+
+## Explanation Procedure
+
+1. Identify the exact concept or observed behavior in question.
+2. Name the owning scope: application, request/task, or transaction.
+3. Trace what state the object holds and where actual database I/O can occur.
+4. Explain normal entry, successful exit, exceptional exit, and concurrent use.
+5. Distinguish an invariant from a recommended default or backend-specific choice.
+6. Load only the matching reference documents and cite upstream sources.
+7. Show the smallest useful code pattern or contrast when prose is insufficient.
+8. End with concrete checks the reader can use to inspect their own code.
+
+When reviewing code, verify:
+
+- The URL uses an asyncio-compatible dialect.
+- Engine creation and disposal have one clear owner.
+- Every session has a bounded lifetime and is not shared across tasks.
+- Transaction boundaries match business invariants and exception behavior.
+- Relationship and deferred-column access cannot surprise the event loop with implicit I/O.
+- Pool and timeout settings are justified by deployment behavior.
+- Tests exercise rollback, cleanup, concurrency, and lifespan behavior where relevant.
+
+## Anti-Patterns to Flag
+
+- Creating engines inside request handlers.
+- Sharing one AsyncSession across concurrent tasks.
+- Implicit commit/rollback behavior with unclear ownership.
+- Global mutable session state.
+- Lifespan cleanup that depends on implicit garbage collection.
+- Treating `AsyncExitStack` as mandatory for a fixed single resource.
+- Treating SQLModel's synchronous tutorial examples as the async runtime pattern.
+- Allowing lazy relationship access to hide database I/O.
+- Copying pool settings without relating them to worker count and database capacity.
+
+## Output Contract
+
+Answer in the shape best suited to the question, usually:
+
+1. Direct explanation.
+2. Underlying lifecycle or transaction mechanics.
+3. Required invariants and situational tradeoffs.
+4. Minimal example or code-review findings when useful.
+5. Verification questions and source links.
+
+## References
+
+!!! info "Primary sources"
+   - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
+   - [SQLAlchemy transaction management](https://docs.sqlalchemy.org/en/21/orm/session_transaction.html)
+   - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
+   - [FastAPI dependencies with `yield`](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/)
+   - [Python `AsyncExitStack`](https://docs.python.org/3/library/contextlib.html#contextlib.AsyncExitStack)
+   - [SQLModel session dependency pattern](https://sqlmodel.tiangolo.com/tutorial/fastapi/session-with-dependency/)

docs/skills/async-fastapi-sqlmodel/references/crud.md

@@ -0,0 +1,334 @@
+# Basic CRUD Repository and Functions
+
+!!! info "Primary sources"
+    - [SQLModel create-data tutorial](https://sqlmodel.tiangolo.com/tutorial/fastapi/multiple-models/)
+    - [SQLModel update-data tutorial](https://sqlmodel.tiangolo.com/tutorial/fastapi/update-extra-data/)
+    - [SQLModel select tutorial](https://sqlmodel.tiangolo.com/tutorial/select/)
+    - [SQLAlchemy `AsyncSession` API](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html#sqlalchemy.ext.asyncio.AsyncSession)
+
+??? abstract "Decision metadata"
+    - Status: adopted
+    - Decision level: advisory
+    - Applies to: api-runtime, workers, tests
+    - Last reviewed: 2026-07-26
+
+---
+
+## Purpose
+
+Show a small SQLModel CRUD layer in two forms:
+
+- independent functions for convenient standalone or composed operations;
+- a repository object that groups those functions behind one domain-oriented interface.
+
+Every public operation accepts an optional `AsyncSession`. When omitted, reads resolve the cached session factory and own a short-lived session, while writes resolve the same factory and own a complete session-and-transaction scope. When supplied, reads borrow the session and writes borrow its already-active caller-owned transaction. The repository stores configuration and delegates to the same functions without changing those semantics.
+
+Use the same vocabulary at every layer:
+
+| Operation | Function | Repository method | Scope when session is omitted | Missing-row result |
+|---|---|---|---|---|
+| Create | `create_widget()` | `create()` | Owned transaction | Not applicable |
+| Read one | `get_widget()` | `get()` | Owned session | `None` |
+| Read many | `list_widgets()` | `list()` | Owned session | Empty list |
+| Update | `update_widget()` | `update()` | Owned transaction | `None` |
+| Delete | `delete_widget()` | `delete()` | Owned transaction | `None` |
+
+Functions and repository methods both put domain arguments first. Database configuration and sessions are keyword-only infrastructure arguments. This keeps call sites analogous and makes ownership choices visible.
+
+---
+
+## Models
+
+Start with one table model when the application does not need distinct persistence and API schemas.
+
+```python
+from sqlmodel import Field
+from sqlmodel import SQLModel
+
+
+class Widget(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    description: str | None = None
+```
+
+This reference uses direct field arguments and full-update semantics to keep the CRUD mechanics visible. Introduce separate create, update, or public schemas only when an API boundary needs different validation, field visibility, or partial-update behavior. See [SQLModel integration](sqlmodel.md) for that larger modeling pattern.
+
+---
+
+## Independent CRUD Functions
+
+Functions are the simplest default when grouping state or behavior in an object adds no value. Each function is a complete operation boundary: it can run standalone by resolving the cached factory from `database_url`, or compose into a caller-owned scope through `session`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from .session import session_scope
+from .session import transaction_scope
+
+
+async def create_widget(
+    name: str,
+    description: str | None = None,
+    *,
+    database_url: str,
+    session: AsyncSession | None = None,
+) -> Widget:
+    async with transaction_scope(
+        database_url=database_url,
+        session=session,
+    ) as active_session:
+        widget = Widget(name=name, description=description)
+        active_session.add(widget)
+        await active_session.flush()
+        return widget
+
+
+async def get_widget(
+    widget_id: int,
+    *,
+    database_url: str,
+    session: AsyncSession | None = None,
+) -> Widget | None:
+    async with session_scope(
+        database_url=database_url,
+        session=session,
+    ) as active_session:
+        return await active_session.get(Widget, widget_id)
+
+
+async def list_widgets(
+    *,
+    database_url: str,
+    offset: int = 0,
+    limit: int = 100,
+    session: AsyncSession | None = None,
+) -> list[Widget]:
+    if offset < 0:
+        raise ValueError("offset must be non-negative")
+    if not 1 <= limit <= 100:
+        raise ValueError("limit must be between 1 and 100")
+
+    async with session_scope(
+        database_url=database_url,
+        session=session,
+    ) as active_session:
+        statement = select(Widget).order_by(Widget.id).offset(offset).limit(limit)
+        return list(await active_session.scalars(statement))
+
+
+async def update_widget(
+    widget_id: int,
+    name: str,
+    description: str | None,
+    *,
+    database_url: str,
+    session: AsyncSession | None = None,
+) -> Widget | None:
+    async with transaction_scope(
+        database_url=database_url,
+        session=session,
+    ) as active_session:
+        widget = await active_session.get(Widget, widget_id)
+        if widget is None:
+            return None
+
+        widget.name = name
+        widget.description = description
+        await active_session.flush()
+        return widget
+
+
+async def delete_widget(
+    widget_id: int,
+    *,
+    database_url: str,
+    session: AsyncSession | None = None,
+) -> Widget | None:
+    async with transaction_scope(
+        database_url=database_url,
+        session=session,
+    ) as active_session:
+        widget = await active_session.get(Widget, widget_id)
+        if widget is None:
+            return None
+
+        await active_session.delete(widget)
+        await active_session.flush()
+        return widget
+```
+
+Update and delete load the row through the same session that mutates it. This avoids accepting detached instances from an earlier standalone read and gives both operations an explicit `None` result that the application layer can map to a domain or HTTP error. Delete returns the loaded object for callers that need its values, but that object represents a row scheduled for deletion and must not be reused as persistent state. List operations validate their bounds and order by the primary key so pagination is deterministic. Add a unique tiebreaker whenever ordering by a non-unique field.
+
+`flush()` sends pending writes and populates ordinary generated primary keys. It does not itself commit. For a standalone write, the surrounding owned `transaction_scope()` commits after the function body succeeds. For a supplied session, the caller's outer transaction retains commit and rollback ownership. Use `await active_session.refresh(widget)` only when the operation deliberately needs database-generated state that was not returned during the flush; an unconditional refresh adds another query.
+
+---
+
+## Repository Object
+
+A repository can provide a stable domain-facing interface when several callers need the same grouped operations. It stores repeatable database configuration, never a mutable session. Every method delegates to the analogous function and exposes the same optional-session contract.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+class WidgetRepository:
+    def __init__(self, database_url: str) -> None:
+        self.database_url = database_url
+
+    async def create(
+        self,
+        name: str,
+        description: str | None = None,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Widget:
+        return await create_widget(
+            name,
+            description,
+            database_url=self.database_url,
+            session=session,
+        )
+
+    async def get(
+        self,
+        widget_id: int,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Widget | None:
+        return await get_widget(
+            widget_id,
+            database_url=self.database_url,
+            session=session,
+        )
+
+    async def list(
+        self,
+        *,
+        offset: int = 0,
+        limit: int = 100,
+        session: AsyncSession | None = None,
+    ) -> list[Widget]:
+        return await list_widgets(
+            database_url=self.database_url,
+            offset=offset,
+            limit=limit,
+            session=session,
+        )
+
+    async def update(
+        self,
+        widget_id: int,
+        name: str,
+        description: str | None,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Widget | None:
+        return await update_widget(
+            widget_id,
+            name,
+            description,
+            database_url=self.database_url,
+            session=session,
+        )
+
+    async def delete(
+        self,
+        widget_id: int,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Widget | None:
+        return await delete_widget(
+            widget_id,
+            database_url=self.database_url,
+            session=session,
+        )
+```
+
+The object is intentionally thin. Tests can construct it with a test database URL or pass a transaction-scoped test session to individual methods. A caller-provided session always wins and remains open after the method returns. A standalone operation closes its owned session before returning, so returned objects are detached; load every required scalar, deferred column, and relationship explicitly before the scope exits, and do not mutate those objects expecting persistence.
+
+If a read participates in a later write, pass the same session and place both operations inside the explicit transaction. This avoids splitting one use case across sessions and keeps SQLAlchemy's autobegin behavior from obscuring transaction ownership. Add a repository only when its naming, shared query policy, dependency substitution, or domain boundary improves the application. Independent functions remain a valid and often clearer design.
+
+---
+
+## Transaction Ownership
+
+Compose multiple calls under one use-case transaction. At this boundary, a supplied session joins its already-active caller-owned transaction, while omitting the session creates a standalone session and transaction. Each nested CRUD write receives `active_session`, detects that transaction, and borrows it instead of committing independently.
+
+The scope names describe exactly what they own: `session_scope()` manages session lifetime but never commits, while `transaction_scope()` manages a complete transaction only when it also creates the session. Both yield the name `active_session` because downstream CRUD code does not need to know whether the session was borrowed or owned.
+
+```python
+from .session import transaction_scope
+
+
+async def replace_widget(
+    repository: WidgetRepository,
+    widget_id: int,
+    replacement_name: str,
+    replacement_description: str | None = None,
+    *,
+    session: AsyncSession | None = None,
+) -> Widget | None:
+    async with transaction_scope(
+        database_url=repository.database_url,
+        session=session,
+    ) as active_session:
+        deleted_widget = await repository.delete(
+            widget_id,
+            session=active_session,
+        )
+        if deleted_widget is None:
+            return None
+
+        return await repository.create(
+            replacement_name,
+            replacement_description,
+            session=active_session,
+        )
+```
+
+If creation fails, deletion rolls back with it. For a caller-owned transaction, wrap the call in `async with session.begin():` and pass that session. For a standalone use case, omit the session; the outer `transaction_scope()` commits on successful exit, rolls back on exception, and closes its owned session. Do not add direct `commit()` calls to CRUD functions or repository methods because that prevents callers from composing several operations atomically. See [transaction boundaries](transactions.md) and [session management](session.md) for ownership details.
+
+---
+
+## Anti-Patterns
+
+- Storing one mutable `AsyncSession` on a long-lived repository object.
+- Constructing ad hoc factories or sessions instead of resolving the cached factory through the scope helpers.
+- Using `session_scope()` for an optional write, which would close an owned session without committing.
+- Accepting a supplied session for a write without requiring an active caller-owned transaction.
+- Calling `commit()` or `rollback()` directly instead of expressing ownership through `transaction_scope()`.
+- Accepting unbounded list queries.
+- Accepting detached ORM instances for update or delete when an identifier can be resolved in the active session.
+- Accessing unloaded attributes after a standalone repository read has closed its owned session.
+
+---
+
+## Operational Checks
+
+- Every CRUD call receives a task-local `AsyncSession`.
+- Standalone reads resolve the cached factory by database URL and close their owned session.
+- Standalone writes resolve the cached factory and own commit, rollback, and session cleanup through `transaction_scope()`.
+- Supplied write sessions already have an active caller-owned transaction.
+- Each complete operation, service, or use-case boundary borrows an active transaction or owns a complete session-and-transaction scope.
+- List operations have pagination and deterministic ordering where required.
+- Update requires values for both mutable fields; passing `None` explicitly clears the nullable description.
+- Get, update, and delete use the same identifier and missing-row semantics.
+- Functions and repository methods use domain arguments first and keyword-only infrastructure arguments consistently.
+- Standalone reads load all state needed after their owned session closes.
+- Repository objects hold configuration or policy, never request-scoped session state.
+
+---
+
+## Testing Checks
+
+- Create tests verify generated identifiers and persisted field values after commit.
+- Get and list tests cover found, missing, pagination, and ordering behavior.
+- List tests reject negative offsets and limits outside the supported range.
+- Update tests cover replacement of both mutable fields, including clearing the nullable description.
+- Update and delete tests cover missing identifiers without mutating the database.
+- Delete tests verify the returned row and its absence after commit.
+- Failure tests verify that a surrounding transaction rolls back all composed CRUD calls.
+- Optional-session read tests verify borrowed sessions remain open and owned sessions close without committing.
+- Optional-session write tests verify supplied transactions remain caller-owned and standalone transactions commit or roll back before closing.
+- Composition tests pass one active session through several CRUD calls and verify one atomic commit or rollback.

docs/skills/async-fastapi-sqlmodel/references/engine.md

@@ -0,0 +1,171 @@
+# Async SQLAlchemy Engine
+
+!!! info "Primary sources"
+    - [Python `functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache)
+    - [SQLAlchemy connections](https://docs.sqlalchemy.org/en/21/core/connections.html)
+    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
+    - [SQLAlchemy pooling and multiprocessing](https://docs.sqlalchemy.org/en/21/core/pooling.html#pooling-multiprocessing)
+    - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
+
+---
+
+## Engine Ownership Model
+
+Create one async engine per process per database URL and keep engine construction independent from FastAPI.
+
+- SQLAlchemy guidance: the engine is intended as a long-lived, concurrent registry over pooled DB connections, not a per-request object.
+- A cached function provides stable process-local engine identity without making framework state the only way to obtain it.
+- FastAPI lifespan starts and stops that independently defined resource; it does not contain the construction policy.
+
+!!! tip "Practical rule"
+    - Exactly one `create_async_engine(...)` call in the cached engine factory.
+    - Zero `create_async_engine(...)` calls in request handlers.
+    - Zero calls to the cached factory from repository code.
+
+---
+
+## Cached Engine Factory
+
+Use [`functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache) on a synchronous factory. Creating an `AsyncEngine` configures the dialect and pool; it does not need to await a database connection.
+
+```python
+from functools import cache
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+
+@cache
+def get_engine(database_url: str) -> AsyncEngine:
+    return create_async_engine(
+        database_url,
+        pool_pre_ping=True,
+    )
+
+
+async def dispose_engine(database_url: str) -> None:
+    engine = get_engine(database_url)
+    try:
+        await engine.dispose()
+    finally:
+        get_engine.cache_clear()
+
+
+async def refresh_engine(database_url: str) -> AsyncEngine:
+    await dispose_engine(database_url)
+    return get_engine(database_url)
+```
+
+The database URL is an explicit, hashable cache key. Calls with the same URL return the same engine; a different URL receives a different engine. If engine options vary at runtime, make them explicit hashable arguments too.
+
+Resolve settings at the composition boundary and call `get_engine(settings.database_url)`. Do not hide settings lookup or engine creation inside feature code.
+
+## Thin FastAPI Lifespan Wrapper
+
+The lifespan context manager only connects the cached resource to FastAPI ownership:
+
+```python
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    database_url = app.state.settings.database_url
+    engine = get_engine(database_url)
+    app.state.engine = engine
+
+    try:
+        yield
+    finally:
+        await dispose_engine(database_url)
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+`dispose()` closes checked-in connections and replaces the pool, but it does not remove the Python object from `functools.cache`. `dispose_engine()` clears the cache even if driver cleanup raises, preventing a later lifespan run or test from retrieving that engine instance.
+
+This simple cleanup assumes one configured database URL per process. If a process intentionally owns several cached engines, use a small registry with per-key removal instead of clearing the whole cache. For a fixed engine, `try/finally` is sufficient; use `AsyncExitStack` when lifespan composes multiple conditional or dynamically acquired resources.
+
+When directly testing engine construction or lifespan behavior:
+
+- Call `get_engine.cache_clear()` before the test to remove process-local state.
+- Dispose any engine the test creates.
+- Clear the cache again during teardown, even when the test fails.
+
+---
+
+## Driver URLs (Project Requirement: asyncpg + aiosqlite)
+
+Use SQLAlchemy async driver URLs:
+
+- PostgreSQL: `postgresql+asyncpg://user:pass@host:5432/dbname`
+- SQLite: `sqlite+aiosqlite:///./app.db`
+
+!!! warning "Driver compatibility"
+    - Do not mix sync drivers, for example `psycopg2`, with `create_async_engine()`.
+    - Keep URL construction centralized in settings/config, not in feature modules.
+
+---
+
+## Pooling Defaults and Tuning
+
+Default behavior is usually correct first:
+
+- Async engines use async-compatible pooling (`AsyncAdaptedQueuePool`) by default.
+- Start with defaults, then tune from observed load (`pool_size`, `max_overflow`, `pool_timeout`, `pool_recycle`).
+- Enable `pool_pre_ping=True` for safer stale-connection handling in long-running services.
+
+When to switch pool strategy:
+
+- `NullPool` if you explicitly need no pooling (special environments, some tests, or strict cross-loop constraints).
+- Keep in mind this increases connect/disconnect churn.
+
+---
+
+## Disposal Semantics
+
+`engine.dispose()` replaces/disposes the pool, but only checked-in connections are immediately closed.
+
+Rules:
+- Dispose when the app is shutting down.
+- Dispose before reusing an engine across event loops.
+- In forked child-process initialization, use `engine.dispose(close=False)` (sync API guidance) so child processes do not touch parent-held connections.
+
+Avoid relying on garbage collection for engine cleanup in async code.
+
+---
+
+## Event Loop and Process Boundaries
+
+Do not share pooled connections across boundaries:
+
+- Multiple event loops: do not reuse the same pooled async engine across loops unless you intentionally disable pooling (`NullPool`) or dispose before handoff.
+- Multiprocessing/fork: pooled connections must not be inherited for active use across process boundaries.
+
+This prevents broken socket state and cross-process connection corruption.
+
+---
+
+## What Not to Do
+
+- Create an engine inside every request dependency.
+- Create/dispose engines inside repository methods.
+- Call `get_engine()` from repositories instead of injecting their engine or session dependency.
+- Keep engine creation as a hidden side effect of import-time module globals.
+- Dispose a cached engine without clearing the cache during final teardown.
+- Use deprecated FastAPI startup/shutdown events together with lifespan.
+
+---
+
+## Engine Design Checklist
+
+- One engine per process per DB URL.
+- Engine created by one cached, framework-independent factory.
+- Lifespan only retrieves, exposes, disposes, and uncaches the engine.
+- Async driver URL matches backend (`asyncpg` or `aiosqlite`).
+- Pooling strategy is explicit for non-default needs.
+- No request-path engine creation.
+- Tests dispose engines and clear cached state deterministically.

docs/skills/async-fastapi-sqlmodel/references/implicit_io.md

@@ -66,13 +66,13 @@ roles = await user.awaitable_attrs.roles
 
 ## Practical Enforcement Model
 
-Use phased enforcement:
+Require explicit I/O behavior on every async ORM path:
 
-1. High-traffic and latency-sensitive routes: enforce explicit eager loading.
-2. Background tasks and less critical paths: track and progressively tighten.
-3. Add review checks to prevent newly introduced implicit-load hotspots.
+1. Define loader options for relationships and deferred columns needed by the operation.
+2. Use `refresh()` or awaitable attributes only when the additional query is deliberate and visible.
+3. Add review checks that reject unplanned lazy-load paths.
 
-This keeps modernization pragmatic while reducing hidden I/O over time.
+This keeps event-loop behavior predictable and makes query boundaries reviewable from the code.
 
 ---
 
@@ -99,9 +99,3 @@ This keeps modernization pragmatic while reducing hidden I/O over time.
 - Tests verify expected data is present without hidden secondary query surprises.
 - Regression tests exist for routes previously affected by implicit-load failures.
 
----
-
-## Migration Notes
-
-- Start advisory: target high-risk paths first.
-- As coverage improves, elevate selected rules to mandatory in code review policy.

docs/skills/async-fastapi-sqlmodel/references/index.md

@@ -1,6 +1,6 @@
 # FastAPI Async SQLAlchemy References Index
 
-Purpose: concept registry for modernization guidance used by this skill.
+Purpose: concept registry for the principles, mechanics, and implementation guidance used by this skill.
 
 ---
 
@@ -13,12 +13,14 @@ Purpose: concept registry for modernization guidance used by this skill.
 | Transaction boundaries | [transactions.md](transactions.md) | adopted | mandatory | platform/backend | 2026-06-17 |
 | Implicit ORM I/O under asyncio | [implicit_io.md](implicit_io.md) | adopted | advisory | platform/backend | 2026-06-17 |
 | Observability and resilience | [observability.md](observability.md) | adopted | mandatory | platform/backend | 2026-06-17 |
+| SQLModel modeling and async boundaries | [sqlmodel.md](sqlmodel.md) | adopted | mandatory | platform/backend | 2026-07-26 |
+| Basic CRUD repository and functions | [crud.md](crud.md) | adopted | advisory | platform/backend | 2026-07-26 |
 
 ---
 
 ## How to Use This Folder
 
-- `SKILL.md` defines the planning workflow and migration procedure.
+- `SKILL.md` defines the explanatory workflow and shared mental model.
 - Each concept doc defines policy-level guidance for one concern.
 - Use the template in [template.md](template.md) for new concept docs.
 - Keep references source-linked and implementation snippets minimal.
@@ -29,4 +31,4 @@ Purpose: concept registry for modernization guidance used by this skill.
 
 - If a PR changes database lifecycle/session/ORM loading behavior, update the relevant concept file.
 - Keep `Status`, `Decision Level`, and `Last Reviewed` current.
-- Use `advisory` only when incremental rollout is intended; use `mandatory` for required runtime policy.
+- Use `advisory` for recommendations that depend on application context; use `mandatory` for required runtime policy.

docs/skills/async-fastapi-sqlmodel/references/observability.md

@@ -105,10 +105,3 @@ Readiness checks should be lightweight and bounded (timeouts), not heavy diagnos
 - Readiness endpoint test covers healthy and unhealthy DB states.
 - Integration test simulates disconnect/reconnect behavior.
 - Load/concurrency tests validate pool behavior under stress.
-
----
-
-## Migration Notes
-
-- Start with resilient defaults (`pool_pre_ping`) and simple health policy.
-- Add deeper metrics/event hooks incrementally once baseline reliability is in place.

docs/skills/async-fastapi-sqlmodel/references/session.md

@@ -0,0 +1,383 @@
+# Async SQLAlchemy Session Management
+
+!!! info "Primary sources"
+    - [Python `functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache)
+    - [Python `asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager)
+    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
+    - [SQLAlchemy session basics](https://docs.sqlalchemy.org/en/21/orm/session_basics.html)
+    - [FastAPI dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/)
+
+---
+
+## Purpose
+
+Define one canonical session model for FastAPI + SQLAlchemy asyncio:
+
+- configure one shared session factory,
+- create one AsyncSession per request or per unit-of-work,
+- never share one AsyncSession across concurrent tasks.
+
+---
+
+## Scope and Non-Goals
+
+- In scope: session factory creation, FastAPI dependency wiring, request/task scoping, transaction demarcation.
+- Out of scope: ORM model design, query optimization strategy, schema migration tooling.
+
+---
+
+## Rules
+
+- Create one cached `async_sessionmaker` per app-owned AsyncEngine.
+- Let repositories resolve the cached maker by database URL.
+- Use a fresh AsyncSession for each request or explicit unit-of-work.
+- Pass an `AsyncSession` directly to data-access functions.
+- Borrow a caller-provided session without closing or committing it.
+- Do not share AsyncSession across `asyncio.gather()` or parallel tasks.
+- Prefer direct dependency injection over global scoped-session patterns in new code.
+- Use explicit transaction boundaries (`async with session.begin():`) for writes.
+- When a use case accepts an optional session, borrow only an active caller-owned transaction or own the complete session-and-transaction scope.
+
+---
+
+## Sessions and Transactions
+
+A session and a transaction solve related but different problems:
+
+| Concept | Responsibility | Typical lifetime |
+| --- | --- | --- |
+| `AsyncSession` | Provides the ORM workspace: executes queries, tracks loaded and changed objects in its identity map, and flushes pending changes. It also coordinates access to a database connection. | One request, task, or explicit unit of work. |
+| Transaction | Defines the atomic database boundary: all work inside it commits together on success or rolls back together on failure. | One complete operation that must have a single outcome. |
+
+A transaction belongs to a session; it is not an alternative to one. The session is the interface used by application and data-access code, while the transaction determines when that work becomes permanent. A session may coordinate sequential transactions during its lifetime, although short-lived application scopes commonly use one session for one transaction.
+
+Use a session without a helper-owned commit boundary for independent reads or lower-level functions that must participate in whatever transaction their caller controls:
+
+```python
+async with session_factory() as session:
+    item = await find_item(session, item_id)
+```
+
+Use an explicit transaction for writes, read-modify-write operations, or several statements that must succeed or fail as one unit:
+
+```python
+async with session_factory.begin() as session:
+    order = await create_order(session, order_data)
+    await reserve_inventory(session, order)
+```
+
+SQLAlchemy sessions use [autobegin](https://docs.sqlalchemy.org/en/21/orm/session_basics.html#auto-begin), so the first database operation normally starts a transaction even for a read. Therefore, “session-only” means that the surrounding helper owns only session lifetime and does not promise to commit; it does not mean that no database transaction exists. Closing such a session releases its resources and rolls back any unfinished transaction. An explicit `begin()` is valuable when application code must make the atomic boundary and commit ownership visible.
+
+For most read-only operations, a session context is sufficient. Use an explicit transaction for reads when they need a defined consistency boundary, participate in a larger atomic operation, or use locking such as `SELECT ... FOR UPDATE`.
+
+---
+
+## Session Factory Mechanics
+
+An `async_sessionmaker[AsyncSession]` is a reusable configuration object and callable session producer. It stores how sessions should be created, including the engine binding and options such as `expire_on_commit=False`. It is not itself a session, connection, or transaction, and calling it does not make a shared global `AsyncSession`.
+
+Cache it by the application-owned engine so repeated composition calls return the same maker:
+
+```python
+from functools import cache
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from .engine import dispose_engine
+from .engine import get_engine
+
+
+@cache
+def get_session_factory(database_url: str) -> async_sessionmaker[AsyncSession]:
+    return async_sessionmaker(
+        bind=get_engine(database_url),
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+
+async def dispose_session_factory(database_url: str) -> None:
+    get_session_factory.cache_clear()
+    await dispose_engine(database_url)
+```
+
+`functools.cache` caches by argument equality and requires hashable arguments. The database URL is an explicit string key shared with the cached engine factory. The cache retains the returned maker until `get_session_factory.cache_clear()` runs. Cache the synchronous maker function, never an async function and never a produced `AsyncSession`.
+
+Each call to `session_factory()` creates a distinct `AsyncSession`. The caller that invokes the factory owns that session lifetime and must close it, normally with `async with`:
+
+```python
+async with session_factory() as session:
+    ...
+```
+
+The factory can be shared across requests and tasks. Sessions produced by it cannot be shared across concurrent tasks.
+
+An `async_sessionmaker` has no connection pool or async `dispose()` method of its own. `dispose_session_factory()` means "invalidate the cached maker, then dispose its engine." Clearing the maker first ensures no subsequent composition call can retrieve a maker bound to the engine being shut down.
+
+Use the helper when shutting down or replacing the database resources:
+
+```python
+await dispose_session_factory(database_url)
+```
+
+Otherwise, a later call can return a maker that still references the old engine object. This matters in lifespan tests, application restarts within one process, and test suites that replace engines.
+
+---
+
+## Optional Session Ownership
+
+A small [`asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager) can make repository methods composable. It borrows an existing session when supplied; otherwise it creates and closes one from a supplied factory:
+
+```python
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+
+@asynccontextmanager
+async def session_scope(
+    *,
+    database_url: str,
+    session: AsyncSession | None = None,
+) -> AsyncIterator[AsyncSession]:
+    if session is not None:
+        yield session
+        return
+
+    async with get_session_factory(database_url)() as owned_session:
+        yield owned_session
+```
+
+The branch is intentionally explicit. Python's [`nullcontext`](https://docs.python.org/3/library/contextlib.html#contextlib.nullcontext) can express the same borrow-or-own idea, but the branch keeps ownership and typing obvious.
+
+This helper manages session lifetime only:
+
+- It does not close, commit, or roll back a supplied session; the caller owns it.
+- It closes a session that it creates. Closing releases resources and rolls back an unfinished transaction; it does not commit.
+- It does not start a transaction. Put `session.begin()` at the use-case boundary.
+- A supplied session wins; the cached factory is not resolved.
+- Otherwise, `database_url` selects the cached factory returned by `get_session_factory()`.
+
+Do not turn this into an implicit unit-of-work helper that sometimes commits. Whether work joins an existing transaction or creates a new one must remain visible to the caller.
+
+---
+
+## Optional Transaction Ownership
+
+Use a separate context manager when a service or use-case function must support both a caller-owned transaction and a standalone transaction. A supplied session must already be inside a transaction; otherwise the helper creates a session and transaction together with `async_sessionmaker.begin()`:
+
+```python
+@asynccontextmanager
+async def transaction_scope(
+    *,
+    database_url: str,
+    session: AsyncSession | None = None,
+) -> AsyncIterator[AsyncSession]:
+    if session is not None:
+        if not session.in_transaction():
+            raise RuntimeError("A supplied session must have an active transaction")
+        yield session
+        return
+
+    session_factory = get_session_factory(database_url)
+    async with session_factory.begin() as owned_session:
+        yield owned_session
+```
+
+Here, `begin()` is intentionally called on the [`async_sessionmaker`](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#sqlalchemy.ext.asyncio.async_sessionmaker.begin), not on an existing `AsyncSession`. The related APIs have different ownership semantics:
+
+- `session_factory()` creates a session whose lifetime the surrounding code must manage; it does not commit automatically.
+- `session_factory.begin()` creates a new session and transaction together, commits on successful exit or rolls back on exceptional exit, and then closes the session.
+- `session.begin()` manages a transaction on an existing session but does not own or close that session.
+
+The factory form is equivalent in ownership terms to creating a session and then entering that session's transaction:
+
+```python
+async with session_factory() as owned_session:
+    async with owned_session.begin():
+        yield owned_session
+```
+
+This helper makes transaction ownership follow the same explicit borrow-or-own mechanics as session ownership:
+
+- A supplied session and its active transaction remain caller-owned. The helper does not commit, roll back, or close them.
+- Without a supplied session, the helper owns the session and transaction. Successful exit commits; exceptional exit rolls back; either path closes the session.
+- Use this helper only at a complete operation, service, or use-case boundary. A public CRUD function or repository method may be such a boundary when its optional-session contract explicitly states that omitting the session owns and commits one transaction. Never use it inside a lower-level session-required helper.
+- Do not silently begin a transaction on a supplied session. That would make commit ownership depend on hidden helper behavior.
+
+Callers that supply a session make their ownership visible with an outer transaction:
+
+```python
+async with session_factory() as session:
+    async with session.begin():
+        await run_use_case(..., session=session)
+```
+
+Standalone callers omit the session and let the use case own the complete unit of work:
+
+```python
+await run_use_case(...)
+```
+
+---
+
+## Repository and Function Boundaries
+
+Pass the database URL to repository constructors. The repository stores repeatable database configuration, not mutable session state, and `session_scope()` resolves the cached factory when a standalone operation needs a session:
+
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+async def find_item(session: AsyncSession, item_id: int) -> Item | None:
+    statement = select(Item).where(Item.id == item_id)
+    return await session.scalar(statement)
+
+
+class ItemRepository:
+    def __init__(self, database_url: str) -> None:
+        self.database_url = database_url
+
+    async def find(
+        self,
+        item_id: int,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Item | None:
+        async with session_scope(
+            database_url=self.database_url,
+            session=session,
+        ) as active_session:
+            return await find_item(active_session, item_id)
+```
+
+This split gives each layer one job:
+
+- The repository object identifies its database configuration and creates a session only for a standalone call.
+- Standalone calls reuse the cached factory selected by database URL.
+- A caller can pass a session to join an existing unit of work; the repository borrows it.
+- The access function owns only the query and requires an existing `AsyncSession`.
+- Application wiring supplies the production factory.
+- Tests can use a test database URL or call `find_item()` with a transaction-scoped test session.
+
+When several repository operations must share one transaction, pass the same session through each call. Put the transaction at the use-case boundary:
+
+```python
+async with session_factory() as session:
+    async with session.begin():
+        item = await repository.find(item_id, session=session)
+        await update_item(session, item, changes)
+```
+
+This preserves atomicity without making repository objects hold mutable `AsyncSession` instances across calls.
+
+---
+
+## Canonical FastAPI Dependency Pattern
+
+```python
+from collections.abc import AsyncIterator
+
+from fastapi import Depends
+from fastapi import Request
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.ext.asyncio import async_sessionmaker
+
+
+type SessionFactory = async_sessionmaker[AsyncSession]
+
+
+def resolve_session_factory(request: Request) -> SessionFactory:
+    return get_session_factory(request.app.state.settings.database_url)
+
+
+async def get_db_session(
+    session_factory: SessionFactory = Depends(resolve_session_factory),
+) -> AsyncIterator[AsyncSession]:
+    async with session_factory() as session:
+        yield session
+```
+
+Route usage:
+
+```python
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .session import get_db_session
+
+router = APIRouter()
+
+
+@router.post("/items")
+async def create_item(session: AsyncSession = Depends(get_db_session)) -> dict:
+    async with session.begin():
+        # write operations here
+        ...
+    return {"status": "ok"}
+```
+
+---
+
+## Configuration Guidance
+
+- `expire_on_commit=False` is commonly preferred in asyncio applications to reduce accidental post-commit reload behavior.
+- `AsyncSession.refresh()` is preferred over broad expiration patterns when state refresh is needed.
+- [`async_sessionmaker.begin()`](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html#sqlalchemy.ext.asyncio.async_sessionmaker.begin) is a concise option when one scope must create a session, begin a transaction, commit on success, roll back on failure, and close. Do not use it when borrowing a caller's session.
+
+## SQLModel Alignment
+
+- Use SQLModel as the default model and statement layer while keeping the same session ownership model: one `async_sessionmaker`, one `AsyncSession` per request/unit-of-work.
+- SQLModel does not replace SQLAlchemy async lifecycle primitives; it provides model declaration, validation, and typing ergonomics on top of them.
+- Do not mix ad hoc session construction with the canonical async dependency.
+
+---
+
+## Concurrency Rules
+
+- One session per concurrent task.
+- If work fans out into parallel tasks, each task receives its own AsyncSession.
+- Pass sessions explicitly to service functions; avoid mutable global session state.
+
+---
+
+## Anti-Patterns
+
+- A singleton/global AsyncSession reused across requests.
+- Sharing one AsyncSession across parallel tasks.
+- Passing an application-global AsyncSession to a repository constructor.
+- Caching an `AsyncSession` instead of caching `async_sessionmaker`.
+- Leaving a cached maker pointing at a disposed or replaced engine.
+- Calling the session factory inside low-level access functions such as `find_item()`.
+- Hidden session creation in lower access functions with no caller control.
+- Closing or committing a session supplied by the caller.
+- Starting a new transaction inside a helper that may receive a session already in a transaction.
+- Silently starting or committing a transaction on a supplied session.
+- Mixing commit/rollback ownership across layers without a declared boundary.
+
+---
+
+## Operational Checks
+
+- Exactly one cached `async_sessionmaker` exists per application engine.
+- Session factory caches are cleared before their engines are disposed or replaced.
+- Request handlers receive sessions from one canonical dependency.
+- No code path creates AsyncSession in module import side effects.
+- Background jobs and API handlers each create task-local sessions.
+
+---
+
+## Testing Checks
+
+- Repository constructors accept a test database URL without FastAPI startup.
+- Session-taking access functions accept a transaction-scoped test session directly.
+- Optional-session tests verify that borrowed sessions remain open and created sessions close.
+- Optional-session tests verify that neither path commits implicitly.
+- Optional-transaction tests verify supplied sessions require an active transaction and remain caller-owned.
+- Optional-transaction tests verify owned transactions commit on success, roll back on failure, and close their sessions.
+- Cache tests clear `get_session_factory` before and after replacing engines.
+- Dependency override exists for the FastAPI session factory.
+- Rollback behavior is verified for failed write units.
+- Parallel-task tests verify no shared AsyncSession instances.
+- Lifespan tests confirm session factory is initialized and teardown-safe.
+

docs/skills/async-fastapi-sqlmodel/references/sqlmodel.md

@@ -0,0 +1,127 @@
+# SQLModel-First Modeling and Async Boundaries
+
+!!! info "Primary sources"
+    - [SQLModel documentation](https://sqlmodel.tiangolo.com/)
+    - [SQLModel features](https://sqlmodel.tiangolo.com/features/)
+    - [SQLModel advanced guide](https://sqlmodel.tiangolo.com/advanced/)
+    - [SQLModel FastAPI session dependency tutorial](https://sqlmodel.tiangolo.com/tutorial/fastapi/session-with-dependency/)
+    - [SQLModel release notes](https://sqlmodel.tiangolo.com/release-notes/)
+    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
+
+??? abstract "Decision metadata"
+    - Status: adopted
+    - Decision level: mandatory
+    - Applies to: api-runtime, workers, tests
+    - Last reviewed: 2026-07-26
+
+---
+
+## Purpose
+
+Define SQLModel as the primary model layer for async FastAPI applications and explain how it composes with SQLAlchemy's async runtime.
+
+SQLModel is designed for FastAPI, built on Pydantic and SQLAlchemy, and intended to minimize duplication while preserving the capabilities of both. Async engine, session, transaction, and loading behavior still follow SQLAlchemy's asyncio contract.
+
+---
+
+## Scope and Non-Goals
+
+- In scope: table models, API data models, SQLAlchemy interoperability, async session usage, and exception criteria.
+- Out of scope: replacing SQLAlchemy's async runtime primitives or claiming that synchronous tutorial examples are async patterns.
+
+---
+
+## Rules
+
+- Default to SQLModel for new table models and API data models.
+- Keep SQLAlchemy async primitives as the runtime base: `create_async_engine`, `async_sessionmaker`, and `AsyncSession`.
+- Keep transaction and session ownership policies identical whether models are SQLAlchemy Declarative or SQLModel.
+- Use SQLModel inheritance to share validated fields while keeping table, create, update, and public contracts distinct where their semantics differ.
+- Use SQLAlchemy declarative models only for a concrete unsupported mapping or third-party constraint; document the reason.
+- Use SQLAlchemy relationship loading options explicitly on async paths.
+
+---
+
+## Recommended Patterns
+
+### Pattern A: Data model split for API boundaries
+
+Use distinct models for persistence and external contracts.
+
+```python
+from sqlmodel import Field, SQLModel
+
+
+class UserBase(SQLModel):
+    email: str
+    display_name: str
+
+
+class User(UserBase, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+
+
+class UserCreate(UserBase):
+    pass
+
+
+class UserRead(UserBase):
+    id: int
+```
+
+### Pattern B: Keep SQLModel models with the async runtime
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlmodel import select
+
+engine = create_async_engine(settings.database_url, pool_pre_ping=True)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+async with session_factory() as session:
+    users = (await session.scalars(select(User))).all()
+```
+
+`sqlmodel.select()` keeps SQLModel's typing-oriented statement construction, while `AsyncSession.scalars()` and the surrounding lifecycle come from SQLAlchemy.
+
+---
+
+## Interoperability Notes
+
+- A SQLModel table model is a SQLAlchemy model and can participate in SQLAlchemy relationships, statements, loader options, and sessions.
+- A SQLModel model is also a Pydantic model; non-table models are useful for request and response contracts.
+- SQLModel's official FastAPI dependency tutorial currently uses synchronous `Session`; translate the ownership pattern, not the concrete session type, for async applications.
+- SQLModel's advanced guide still lists dedicated async documentation as future work, so use SQLAlchemy's asyncio documentation as the authority for runtime mechanics.
+- Prefer one query style per module to reduce cognitive overhead.
+- Keep loader strategies explicit in async paths to avoid implicit I/O surprises.
+
+---
+
+## Anti-Patterns
+
+- Treating SQLModel as an alternative to SQLAlchemy rather than a layer built on it.
+- Copying a synchronous `Session` example into an async request path.
+- Constructing sessions in handlers instead of using the application session factory.
+- Mixing multiple query/session idioms within the same module without clear conventions.
+
+---
+
+## Operational Checks
+
+- New model modules are SQLModel-first; exceptions state the unsupported need or constraint.
+- Session/transaction ownership remains consistent across both model styles.
+- Table, create, update, and public models share fields intentionally without exposing persistence-only data.
+
+---
+
+## Testing Checks
+
+- Module-level tests verify CRUD semantics for SQLModel models through `AsyncSession`.
+- API tests verify response/request model behavior for SQLModel-based endpoints.
+- Relationship tests verify async loader strategies do not depend on implicit I/O.
+
+---
+
+## Version Checks
+
+- Verify installed SQLModel, SQLAlchemy, and Pydantic versions together when using newly added typing or ORM features.

docs/skills/async-fastapi-sqlmodel/references/template.md

@@ -57,8 +57,3 @@ Describe what this concept governs and why it exists.
 - Test 1
 - Test 2
 
----
-
-## Migration Notes
-
-- Staged rollout notes and compatibility caveats.

docs/skills/async-fastapi-sqlmodel/references/transactions.md

@@ -30,7 +30,8 @@ Define consistent transaction demarcation for async SQLAlchemy so write behavior
 
 - Every mutating use case must run inside an explicit transaction boundary.
 - Prefer `async with session.begin():` for write units.
-- Keep transaction ownership at service/use-case boundary, not deep in helper internals.
+- Keep transaction ownership at a service, use-case, or explicitly documented complete-operation boundary, not deep in helper internals.
+- An optional-session write may own one transaction when omitting the session clearly means standalone execution; a supplied session must remain caller-owned.
 - Read paths should not auto-upgrade into hidden write behavior.
 - On exception in a transaction block, rely on rollback semantics and propagate or map exceptions intentionally.
 
@@ -82,7 +83,7 @@ Use nested transactions only when partial failure semantics are explicitly requi
 ## Anti-Patterns
 
 - Multiple commits scattered across one logical use case.
-- Helper functions that commit/rollback without caller awareness.
+- Helper functions that commit or roll back without an explicit ownership contract.
 - Mixing implicit and explicit transaction styles in confusing ways.
 - Using savepoints as a default pattern rather than a targeted tool.
 
@@ -90,8 +91,8 @@ Use nested transactions only when partial failure semantics are explicitly requi
 
 ## Operational Checks
 
-- All mutating service functions declare one clear transaction boundary.
-- No repository/helper performs hidden commit calls.
+- All mutating services and complete operations declare one clear transaction boundary.
+- No repository or helper performs hidden direct commit calls; standalone ownership is expressed through a documented transaction scope.
 - Transaction style is consistent across handlers and workers.
 
 ---
@@ -102,10 +103,3 @@ Use nested transactions only when partial failure semantics are explicitly requi
 - Failure path test verifies rollback behavior.
 - Tests cover concurrency-sensitive write flows.
 - Savepoint usage (if present) has dedicated behavior tests.
-
----
-
-## Migration Notes
-
-- First stabilize session scope, then normalize transaction ownership.
-- Replace ad hoc commit patterns incrementally with bounded write units.

docs/skills/copilot-customization/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: copilot-customization
 description: 'Plan, create, review, and debug GitHub Copilot and VS Code agent customizations, including instructions, prompt files, skills, custom agents, hooks, MCP servers, and repo-specific personal-mcp skill integration.'
-argument-hint: 'What Copilot behavior are you customizing, and should it be workspace-scoped, personal, or exposed as an MCP skill resource?'
 x-personal-mcp:
   id: copilot-customization
   version: 1.0.0
@@ -19,9 +18,6 @@ x-personal-mcp:
     - skills
   capabilities:
     - resource://skills/copilot-customization/document
-  depends_on:
-    - new-skill
-    - zensical-docs
 ---
 
 # Copilot Customization
@@ -30,7 +26,12 @@ Use this skill when a task is about changing how GitHub Copilot or VS Code agent
 
 ## When to Use
 
-- Creating or updating `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or `*.instructions.md` files.
+- Creating or updating:
+    - `.github/copilot-instructions.md`
+    - `AGENTS.md`
+    - `CLAUDE.md`
+    - `*.instructions.md` files
+    - `*.prompt.md` files
 - Creating prompt files, custom agents, hooks, or Agent Skills.
 - Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
 - Debugging why a customization is not discovered, loaded, or invoked.
@@ -55,6 +56,60 @@ If the request is ambiguous, ask only for the missing axis that changes the file
 
 Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.
 
+## Repo Shim Pattern For Personal MCP
+
+Use a shim when you want another repository to consume this server as a preference and documentation source without duplicating methodology content.
+
+### What the shim does
+
+1. Tells the agent when to consult this MCP server.
+2. Tells the agent how to retrieve relevant guidance.
+3. Keeps repo-local behavior thin while canonical guidance stays in Personal MCP resources.
+
+### Shim formats
+
+Use either:
+
+1. A repo instruction file (`*.instructions.md`) for always-on or file-scoped behavior.
+2. A prompt file (`*.prompt.md`) for explicit, on-demand guidance retrieval.
+
+### Retrieval strategies
+
+Choose one of these patterns:
+
+1. Direct URI strategy:
+  - Reference known resources directly, such as:
+    - `resource://catalog/skills_index`
+    - `resource://catalog/skills/{skill_id}`
+    - `resource://skills/<skill-id>/document`
+    - `resource://skills/<skill-id>/references/<ref-id>`
+2. Discovery-first strategy:
+  - Start at catalog discovery (`resource://catalog/skills_index`), select the best skill match, then load the skill document and only the minimal references needed.
+
+### Authoring guidance for shims
+
+1. Keep shim content short and procedural; avoid copying large guidance blocks from Personal MCP.
+2. State trigger conditions clearly (for example: "when creating a new skill" or "when editing docs contracts").
+3. Specify whether to use direct URIs or discovery for that repo's common workflows.
+4. Prefer loading only the most relevant skill document first; expand to references only when needed.
+5. For stable repeated workflows, use explicit URIs. For broader or ambiguous requests, use discovery-first.
+
+### Minimal shim examples
+
+Instruction-style shim intent:
+
+1. "For markdown edits (`applyTo: '**/*.md'`), load `resource://skills/zensical-docs/document` and apply Zensical-native documentation conventions unless they conflict with expected MkDocs compatibility."
+
+Prompt-style shim intent:
+
+1. "For docs authoring tasks, consult `resource://skills/zensical-docs/document`, summarize the relevant authoring constraints, then propose the smallest markdown change for this repository."
+
+### Validation for shim implementation
+
+1. Confirm the shim triggers in expected contexts.
+2. Confirm resource loading path is unambiguous (direct URI or discovery).
+3. Confirm repo-local customization remains thin and references Personal MCP as source of truth.
+
 ## Workspace Customization Workflow
 
 1. Identify the customization primitive and scope.
@@ -66,20 +121,6 @@ Use [VS Code customization references](./references/vscode-customization.md) for
 7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
 8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.
 
-## Repo Integration Workflow
-
-When adding a new skill to this `personal-mcp` repo, follow the resource-first pattern:
-
-1. Search the catalog for `new skill` and load `resource://skills/new-skill/document`.
-2. Create authored docs under `docs/skills/<skill-id>/SKILL.md`, with optional nested `references/` markdown files.
-3. Keep `skill-id` stable and consistent across directory name, `name`, and `x-personal-mcp.id`.
-4. Put discovery metadata in `SKILL.md` frontmatter under `x-personal-mcp`.
-5. Declare `resource://skills/<skill-id>/document` in `x-personal-mcp.capabilities`.
-6. Declare references in `x-personal-mcp.references` as `ref-id -> references/<file>.md` mappings.
-7. Validate with the registry loader and `uv run zensical build`.
-
-Keep runtime implementation registry-driven in `src/personal_mcp/mcp.py`; do not add per-skill Python server modules.
-
 ## Quality Checks
 
 Before finishing:

docs/skills/fastapi-async-sqlalchemy-modernization/SKILL.md

@@ -1,252 +0,0 @@
----
-name: fastapi-async-sqlalchemy-modernization
-description: 'Create a step-by-step modernization plan for an existing FastAPI app using SQLAlchemy async patterns, context managers, and AsyncExitStack. Use when: planning migration from legacy DB setup, standardizing async engine/session lifecycles, defining transaction boundaries, and aligning with SQLAlchemy 2.x best practices.'
-argument-hint: 'What is your current FastAPI + SQLAlchemy setup (sync/async driver, session pattern, lifespan usage, and deployment model)?'
-x-personal-mcp:
-   id: fastapi-async-sqlalchemy-modernization
-   version: 1.0.0
-   tags:
-      - fastapi
-      - sqlalchemy
-      - async
-      - modernization
-   capabilities:
-      - resource://skills/fastapi-async-sqlalchemy-modernization/document
-   depends_on: []
----
-
-# FastAPI Async SQLAlchemy Modernization Plan
-
-Create an implementation-ready plan that brings an existing FastAPI application in line with modern async SQLAlchemy practices, with explicit resource lifecycles and deterministic cleanup using async context managers and AsyncExitStack.
-
-Primary targets: PostgreSQL with asyncpg and SQLite with aiosqlite.
-
-## When to Use
-
-- Existing FastAPI app has ad hoc database setup or mixed sync/async access.
-- Session management is inconsistent across routes/services.
-- Lifespan startup and shutdown work is spread across globals and side effects.
-- Team needs a migration plan first, not immediate large-scale rewrites.
-
-## Outcome
-
-Produce a practical modernization plan with:
-
-- Current-state gap assessment.
-- Target architecture for engine/session/transaction lifecycle.
-- Branch-based migration path (low-risk staged rollout).
-- Quality gates and completion checks.
-- Risks, rollback strategy, and test plan.
-
-## Top-Level Concepts
-
-Use these concepts as the planning backbone:
-
-1. Engine lifecycle and ownership:
-   One AsyncEngine per process for each DB URL, created once and disposed explicitly when the app lifecycle ends.
-   See the [engine lifecycle reference](references/engine.md).
-2. Session factory and scope:
-   Use async_sessionmaker for configuration; create one AsyncSession per request or unit-of-work, never shared across concurrent tasks.
-   See the [session management reference](references/session.md).
-3. Transaction boundaries:
-   Prefer context-managed begin blocks for write units and explicit read-only sessions for queries.
-   See the [transaction boundaries reference](references/transactions.md).
-4. Lifespan composition:
-   Compose startup/shutdown resources with AsyncExitStack so cleanup is deterministic and ordered.
-   See the [engine lifecycle reference](references/engine.md).
-5. Dependency injection:
-   Provide sessions via FastAPI dependencies with async generators/context managers, not globals.
-   See the [session management reference](references/session.md).
-6. Implicit I/O control in ORM:
-   Avoid accidental lazy loads; use explicit eager-loading/refresh strategies for asyncio safety.
-   See the [implicit I/O reference](references/implicit_io.md).
-7. Observability and resilience:
-   Add pool/connection settings, logging, timeout, and health checks as first-class plan items.
-   See the [observability reference](references/observability.md).
-
-### Concept Reference Map
-
-| Concept | Reference |
-|---|---|
-| Engine lifecycle and ownership | [Engine lifecycle reference](references/engine.md) |
-| Session factory and scope | [Session management reference](references/session.md) |
-| Transaction boundaries | [Transaction boundaries reference](references/transactions.md) |
-| Lifespan composition | [Engine lifecycle reference](references/engine.md) |
-| Dependency injection | [Session management reference](references/session.md) |
-| Implicit I/O control in ORM | [Implicit I/O reference](references/implicit_io.md) |
-| Observability and resilience | [Observability reference](references/observability.md) |
-
-## Decision Points
-
-Use these branching decisions before proposing migration steps.
-
-| Decision | Branch A | Branch B |
-|---|---|---|
-| DB driver | Already async driver (e.g. asyncpg, aiosqlite): modernize in place | Sync driver: plan driver migration first |
-| ORM usage | Already ORM 2.x style (`select`, `session.execute`) | Legacy Query API: add compatibility stage and refactor incrementally |
-| Session scope | Request-scoped already | Global/shared sessions found: prioritize session-scope fix first |
-| Lifespan | Existing FastAPI lifespan hook | No lifespan hook: introduce lifespan before broader DB changes |
-| Concurrency | Background jobs/tasks use DB | No background DB use |
-| Transaction style | Explicit context-managed transactions | Implicit/autobegin side effects |
-
-## Procedure
-
-### Step 0: Audit Current State
-
-Inventory the app and write a concise gap list.
-
-- Engine creation location(s) and count.
-- Driver URL(s) and async compatibility.
-- Session creation patterns in routes/services/background tasks.
-- Transaction handling style (explicit begin/commit/rollback vs implicit).
-- Lifespan startup/shutdown and cleanup behavior.
-- ORM loading patterns that may trigger implicit I/O.
-
-Completion check: every DB touchpoint is mapped to its engine, session, and transaction source.
-
-### Step 1: Define the Target Runtime Model
-
-Define one canonical model to migrate toward.
-
-- Create AsyncEngine once per process.
-- Configure async_sessionmaker once.
-- Use per-request AsyncSession dependency.
-- Keep one AsyncSession per concurrent task.
-- Use context-managed transactions for writes.
-
-Completion check: architecture diagram can explain where engine/session are created, used, and closed.
-
-### Step 2: Plan Engine Modernization
-
-Plan engine creation and pool behavior.
-
-- Use `create_async_engine()` with async dialect URL.
-- Standardize pool settings and pre-ping strategy where relevant.
-- Decide isolation level strategy at engine level (avoid ad hoc per-operation switching unless justified).
-- Define explicit disposal policy for short-lived scopes and tests.
-
-Completion check: engine configuration is centralized and no per-request engine creation remains.
-
-### Step 3: Plan Session Lifecycle Modernization
-
-Define session factory and request dependency pattern.
-
-- Build `async_sessionmaker(engine, expire_on_commit=False)` unless a strict reason says otherwise.
-- Provide session via dependency that yields exactly one AsyncSession.
-- Explicitly prohibit sharing a single AsyncSession across concurrent tasks.
-- Prefer direct dependency passing over async_scoped_session for new designs.
-
-Completion check: all route/service entry points receive a session from one canonical dependency.
-
-### Step 4: Plan Transaction Demarcation
-
-Establish consistent write and read behavior.
-
-- Writes: `async with session.begin(): ...` for atomic units.
-- Reads: execute in managed session context with explicit loader options.
-- Nested/SAVEPOINT use only where required; call out backend caveats.
-- Define rollback behavior for service-layer exceptions.
-
-Completion check: every mutating use case has a declared transaction boundary.
-
-### Step 5: Compose Lifespan with AsyncExitStack
-
-Use async context composition as the preferred orchestration pattern.
-
-```python
-from contextlib import AsyncExitStack, asynccontextmanager
-from fastapi import FastAPI
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    async with AsyncExitStack() as stack:
-        # Compose resources in acquisition order; cleanup is automatic in reverse order.
-        engine = create_async_engine(settings.database_url)
-        stack.push_async_callback(engine.dispose)
-
-        session_factory = async_sessionmaker(engine, expire_on_commit=False)
-        app.state.session_factory = session_factory
-
-        # Add other async resources with stack.enter_async_context(...) as needed.
-        yield
-```
-
-Planning rules:
-
-- Register every acquired resource with AsyncExitStack at acquisition time.
-- Prefer `enter_async_context()` for resources that already expose async context managers.
-- Prefer `push_async_callback()` for async cleanup callables.
-- Keep resource ownership in lifespan, not in route handlers.
-
-Completion check: startup/shutdown ordering is explicit and deterministic.
-
-### Step 6: Prevent Implicit ORM I/O Under Asyncio (Advisory Mode)
-
-Plan for explicit loading behavior, but treat this as progressive guidance rather than a hard gate.
-
-- Recommend eager-loading strategies (for example selectin-style loading) where relationship access is required.
-- For lazy/deferred attributes, define explicit awaitable or refresh paths on high-risk and high-traffic paths first.
-- Document model-level defaults and known exceptions so teams can migrate incrementally.
-
-Completion check: critical request paths have explicit loading plans; non-critical paths have tracked follow-up items.
-
-### Step 7: Testing and Verification Plan
-
-Create modernization quality gates.
-
-- Unit tests for session dependency and transaction behavior.
-- Integration tests for commit/rollback semantics.
-- Concurrency tests confirming one-session-per-task behavior.
-- Lifespan tests verifying cleanup calls and ordering.
-- Health/readiness tests including DB connectivity checks.
-
-Completion check: all quality gates pass under the target async configuration.
-
-### Step 8: Rollout Strategy
-
-Plan low-risk migration phases.
-
-1. Introduce centralized engine/session factory and lifespan orchestration.
-2. Migrate read paths to new session dependency.
-3. Migrate write paths to explicit transaction blocks.
-4. Remove legacy globals/helpers and dead code.
-5. Enable stricter linting/review checks for forbidden patterns.
-
-Completion check: no legacy session/engine creation path remains in production code.
-
-## Quality Criteria
-
-A plan is complete only when it includes:
-
-- Clear current vs target architecture.
-- Branch decisions with rationale.
-- Explicit context-manager patterns for resource ownership.
-- AsyncExitStack composition strategy.
-- Transaction policy and exception behavior.
-- Concrete tests and rollout checkpoints.
-- A documented advisory backlog for non-critical implicit I/O improvements.
-
-## Anti-Patterns to Flag
-
-- Creating engines inside request handlers.
-- Sharing one AsyncSession across concurrent tasks.
-- Implicit commit/rollback behavior with unclear ownership.
-- Global mutable session state.
-- Lifespan cleanup that depends on implicit garbage collection.
-
-## Output Contract
-
-Return the plan as:
-
-1. Current-state gap summary.
-2. Target architecture summary.
-3. Phased migration checklist with branch notes.
-4. Risk register and rollback approach.
-5. Verification matrix (tests + operational checks).
-
-## References
-
-!!! info "Primary sources"
-   - [SQLAlchemy engine and connections](https://docs.sqlalchemy.org/en/21/core/connections.html)
-   - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
-   - [Python async context managers and AsyncExitStack](https://docs.python.org/3/library/contextlib.html)

docs/skills/fastapi-async-sqlalchemy-modernization/references/engine.md

@@ -1,133 +0,0 @@
-# Async SQLAlchemy Engine
-
-!!! info "Primary sources"
-    - [SQLAlchemy connections](https://docs.sqlalchemy.org/en/21/core/connections.html)
-    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
-    - [SQLAlchemy pooling and multiprocessing](https://docs.sqlalchemy.org/en/21/core/pooling.html#pooling-multiprocessing)
-    - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
-
----
-
-## Engine Ownership Model
-
-Create one async engine per process per database URL and keep it for the app lifetime.
-
-- SQLAlchemy guidance: the engine is intended as a long-lived, concurrent registry over pooled DB connections, not a per-request object.
-- In FastAPI, app startup and shutdown ownership belongs in lifespan.
-- Use `FastAPI(lifespan=...)` (not startup/shutdown events) for modern lifecycle wiring.
-
-!!! tip "Practical rule"
-    - Exactly one `create_async_engine(...)` call in app bootstrap code.
-    - Zero `create_async_engine(...)` calls in request handlers.
-
----
-
-## Canonical Lifespan Pattern (AsyncExitStack)
-
-Use `@asynccontextmanager` + `AsyncExitStack` to make teardown deterministic and composable.
-
-```python
-from contextlib import AsyncExitStack, asynccontextmanager
-
-from fastapi import FastAPI
-from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    async with AsyncExitStack() as stack:
-        engine: AsyncEngine = create_async_engine(
-            app.state.settings.database_url,
-            pool_pre_ping=True,
-            # Optional examples:
-            # echo=app.state.settings.sql_echo,
-            # pool_size=10,
-            # max_overflow=20,
-        )
-        app.state.engine = engine
-
-        # Ensure engine disposal always runs at shutdown.
-        stack.push_async_callback(engine.dispose)
-
-        yield
-
-
-app = FastAPI(lifespan=lifespan)
-```
-
-Why this pattern:
-- FastAPI executes code before `yield` at startup and after `yield` at shutdown.
-- `AsyncExitStack` lets you register multiple async cleanups in one place while preserving order.
-- Explicit disposal (directly awaited or via `AsyncExitStack` callback) avoids event-loop-closed warnings when objects fall out of scope.
-
----
-
-## Driver URLs (Project Requirement: asyncpg + aiosqlite)
-
-Use SQLAlchemy async driver URLs:
-
-- PostgreSQL: `postgresql+asyncpg://user:pass@host:5432/dbname`
-- SQLite: `sqlite+aiosqlite:///./app.db`
-
-!!! warning "Driver compatibility"
-    - Do not mix sync drivers, for example `psycopg2`, with `create_async_engine()`.
-    - Keep URL construction centralized in settings/config, not in feature modules.
-
----
-
-## Pooling Defaults and Tuning
-
-Default behavior is usually correct first:
-
-- Async engines use async-compatible pooling (`AsyncAdaptedQueuePool`) by default.
-- Start with defaults, then tune from observed load (`pool_size`, `max_overflow`, `pool_timeout`, `pool_recycle`).
-- Enable `pool_pre_ping=True` for safer stale-connection handling in long-running services.
-
-When to switch pool strategy:
-
-- `NullPool` if you explicitly need no pooling (special environments, some tests, or strict cross-loop constraints).
-- Keep in mind this increases connect/disconnect churn.
-
----
-
-## Disposal Semantics
-
-`engine.dispose()` replaces/disposes the pool, but only checked-in connections are immediately closed.
-
-Rules:
-- Dispose when the app is shutting down.
-- Dispose before reusing an engine across event loops.
-- In forked child-process initialization, use `engine.dispose(close=False)` (sync API guidance) so child processes do not touch parent-held connections.
-
-Avoid relying on garbage collection for engine cleanup in async code.
-
----
-
-## Event Loop and Process Boundaries
-
-Do not share pooled connections across boundaries:
-
-- Multiple event loops: do not reuse the same pooled async engine across loops unless you intentionally disable pooling (`NullPool`) or dispose before handoff.
-- Multiprocessing/fork: pooled connections must not be inherited for active use across process boundaries.
-
-This prevents broken socket state and cross-process connection corruption.
-
----
-
-## What Not to Do
-
-- Create an engine inside every request dependency.
-- Create/dispose engines inside repository methods.
-- Keep engine creation as a hidden side effect of import-time module globals.
-- Use deprecated FastAPI startup/shutdown events together with lifespan.
-
----
-
-## Engine Design Checklist
-
-- One engine per process per DB URL.
-- Engine created in lifespan startup.
-- Engine disposed in lifespan shutdown.
-- Async driver URL matches backend (`asyncpg` or `aiosqlite`).
-- Pooling strategy is explicit for non-default needs.
-- No request-path engine creation.

docs/skills/fastapi-async-sqlalchemy-modernization/references/session.md

@@ -1,141 +0,0 @@
-# Async SQLAlchemy Session Management
-
-!!! info "Primary sources"
-    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
-    - [SQLAlchemy session basics](https://docs.sqlalchemy.org/en/21/orm/session_basics.html)
-    - [FastAPI dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/)
-
-??? abstract "Decision metadata"
-    - Status: adopted
-    - Decision level: mandatory
-    - Applies to: api-runtime, workers, tests
-    - Last reviewed: 2026-06-17
-
----
-
-## Purpose
-
-Define one canonical session model for FastAPI + SQLAlchemy asyncio:
-
-- configure one shared session factory,
-- create one AsyncSession per request or per unit-of-work,
-- never share one AsyncSession across concurrent tasks.
-
----
-
-## Scope and Non-Goals
-
-- In scope: session factory creation, FastAPI dependency wiring, request/task scoping, transaction demarcation.
-- Out of scope: ORM model design, query optimization strategy, schema migration tooling.
-
----
-
-## Rules
-
-- Create `async_sessionmaker` once from app-owned AsyncEngine.
-- Use a fresh AsyncSession for each request or explicit unit-of-work.
-- Do not share AsyncSession across `asyncio.gather()` or parallel tasks.
-- Prefer direct dependency injection over global scoped-session patterns in new code.
-- Use explicit transaction boundaries (`async with session.begin():`) for writes.
-
----
-
-## Canonical FastAPI Dependency Pattern
-
-```python
-from collections.abc import AsyncIterator
-
-from fastapi import Depends, Request
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-
-
-def get_session_factory(request: Request) -> async_sessionmaker[AsyncSession]:
-    return request.app.state.session_factory
-
-
-async def get_db_session(
-    session_factory: async_sessionmaker[AsyncSession] = Depends(get_session_factory),
-) -> AsyncIterator[AsyncSession]:
-    async with session_factory() as session:
-    yield session
-```
-
-Route usage:
-
-```python
-from fastapi import APIRouter, Depends
-from sqlalchemy.ext.asyncio import AsyncSession
-
-router = APIRouter()
-
-
-@router.post("/items")
-async def create_item(session: AsyncSession = Depends(get_db_session)) -> dict:
-    async with session.begin():
-    # write operations here
-    ...
-    return {"status": "ok"}
-```
-
----
-
-## Configuration Guidance
-
-Typical session factory setup:
-
-```python
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-
-session_factory = async_sessionmaker(
-    engine,
-    class_=AsyncSession,
-    expire_on_commit=False,
-)
-```
-
-Notes:
-
-- `expire_on_commit=False` is commonly preferred in asyncio applications to reduce accidental post-commit reload behavior.
-- `AsyncSession.refresh()` is preferred over broad expiration patterns when state refresh is needed.
-
----
-
-## Concurrency Rules
-
-- One session per concurrent task.
-- If work fans out into parallel tasks, each task receives its own AsyncSession.
-- Pass sessions explicitly to service functions; avoid mutable global session state.
-
----
-
-## Anti-Patterns
-
-- A singleton/global AsyncSession reused across requests.
-- Sharing one AsyncSession across parallel tasks.
-- Hidden session creation in lower repository helpers with no caller control.
-- Mixing commit/rollback ownership across layers without a declared boundary.
-
----
-
-## Operational Checks
-
-- Exactly one `async_sessionmaker` is registered in app lifecycle.
-- Request handlers receive sessions from one canonical dependency.
-- No code path creates AsyncSession in module import side effects.
-- Background jobs and API handlers each create task-local sessions.
-
----
-
-## Testing Checks
-
-- Dependency override exists for test session factory.
-- Rollback behavior is verified for failed write units.
-- Parallel-task tests verify no shared AsyncSession instances.
-- Lifespan tests confirm session factory is initialized and teardown-safe.
-
----
-
-## Migration Notes
-
-- If current code uses global/shared sessions, fix scope first before refactoring query style.
-- If legacy sync patterns are present, keep session boundary rules stable while migrating incrementally.

docs/skills/fastapi-uv-docker/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: fastapi-uv-docker
 description: 'Audit and migrate an existing Python project to best practices for a cloud-native ASGI FastAPI app managed with uv and run with uvicorn in Docker. Use when: conforming a project to production standards, setting up src layout, configuring pyproject.toml, writing multi-stage Dockerfiles, wiring lifespan and settings, adding health endpoints, enforcing non-root container user, migrating from requirements.txt to uv.'
-argument-hint: 'What is the current state of the project (bare Python, requirements.txt, pip, etc.)?'
 x-personal-mcp:
   id: fastapi-uv-docker
   version: 1.0.0
   tags:
     - fastapi
     - uv
+    - uvicorn
     - docker
+    - architecture
   capabilities:
     - resource://skills/fastapi-uv-docker/document
-  depends_on: []
 ---
 
 # FastAPI Project Best Practices

docs/skills/mcp-details/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: mcp-details
+description: "Reference hub for MCP and FastMCP source documentation links. Use when you need authoritative protocol, SDK, transport, and deployment docs without loading broad implementation guidance."
+x-personal-mcp:
+  id: mcp-details
+  version: 1.0.0
+  tags:
+    - mcp
+    - model-context-protocol
+    - fastmcp
+    - references
+    - source-docs
+  capabilities:
+    - resource://skills/mcp-details/document
+---
+
+# MCP Details
+
+This skill is a reference index only. It is optimized for fast retrieval of upstream documentation links for MCP and FastMCP.
+
+## When to Use
+
+- You need official MCP protocol and architecture docs.
+- You need MCP SDK links for Python or TypeScript.
+- You need FastMCP docs and source references.
+- You need ecosystem links for tooling, inspection, and client configuration.
+
+## How To Use This Skill
+
+1. Classify the request by intent: protocol, SDK usage, FastMCP, or ecosystem integration.
+2. Open only the matching reference page first.
+3. Load at most one additional reference page if the request spans multiple areas.
+4. Return links grouped by category, with a one-line reason for each group.
+
+## Intent Router
+
+1. MCP fundamentals, protocol architecture, resources, tools, prompts, transports, security: [mcp-protocol-and-spec.md](./references/mcp-protocol-and-spec.md)
+2. MCP SDK and FastMCP implementation references for Python and TypeScript: [sdk-and-fastmcp.md](./references/sdk-and-fastmcp.md)
+3. MCP client integration and operational tooling references: [ecosystem-and-tooling.md](./references/ecosystem-and-tooling.md)
+
+## Load Order
+
+1. Start with the single best-match reference page from the Intent Router.
+2. If the question includes both protocol and implementation details, load [mcp-protocol-and-spec.md](./references/mcp-protocol-and-spec.md) then [sdk-and-fastmcp.md](./references/sdk-and-fastmcp.md).
+3. Load [ecosystem-and-tooling.md](./references/ecosystem-and-tooling.md) only when the request includes client setup, inspector usage, or deployment/operations context.
+
+## Load Budget
+
+1. Single-focus request: 1 reference page.
+2. Mixed protocol and implementation request: 2 reference pages.
+3. Broad audit or migration planning request: up to 3 reference pages.
+
+## Output Contract
+
+When this skill is applied, return:
+1. Which reference files were consulted.
+2. The discovery path used (intent classification and load order).
+3. Curated source-document links grouped by topic.
+4. Any notable gaps or ambiguities in the currently indexed links.

docs/skills/mcp-details/references/ecosystem-and-tooling.md

@@ -0,0 +1,29 @@
+# Ecosystem and Tooling
+
+Use this page for MCP client setup, operational tools, and integration references.
+
+## VS Code and Copilot MCP Integration
+
+!!! info "VS Code MCP docs"
+    - [VS Code MCP servers overview](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+    - [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
+    - [VS Code Copilot customization overview](https://code.visualstudio.com/docs/copilot/customization/overview)
+
+## Debugging and Inspection
+
+!!! info "Inspector and diagnostics"
+    - [MCP inspector repository](https://github.com/modelcontextprotocol/inspector)
+    - [MCP protocol repository issues](https://github.com/modelcontextprotocol/spec/issues)
+    - [Python logging configuration docs](https://docs.python.org/3/library/logging.config.html)
+
+## Runtime and API Framework References
+
+!!! info "Runtime references"
+    - [FastAPI documentation](https://fastapi.tiangolo.com/)
+    - [Uvicorn settings](https://www.uvicorn.org/settings/)
+    - [AnyIO documentation](https://anyio.readthedocs.io/en/stable/)
+
+## Notes
+
+- Use these links when tasks include IDE wiring, MCP server runtime setup, or production operations.
+- Keep protocol and SDK references separate to avoid overloading implementation prompts.

docs/skills/mcp-details/references/mcp-protocol-and-spec.md

@@ -0,0 +1,32 @@
+# MCP Protocol and Specification
+
+Use this page for authoritative links about MCP concepts, protocol shape, and official specification assets.
+
+## Official Documentation
+
+!!! info "MCP docs"
+    - [MCP introduction](https://modelcontextprotocol.io/docs/getting-started/intro)
+    - [Architecture overview](https://modelcontextprotocol.io/docs/learn/architecture)
+    - [Server concepts](https://modelcontextprotocol.io/docs/learn/server-concepts)
+    - [Client concepts](https://modelcontextprotocol.io/docs/learn/client-concepts)
+    - [Security overview](https://modelcontextprotocol.io/docs/learn/security-overview)
+
+## Protocol and Schema Sources
+
+!!! info "Specification repositories"
+    - [MCP specification repository](https://github.com/modelcontextprotocol/spec)
+    - [Specification schema directory](https://github.com/modelcontextprotocol/spec/tree/main/schema)
+    - [Specification issues and proposals](https://github.com/modelcontextprotocol/spec/issues)
+
+## Core Capability References
+
+!!! info "Capability details"
+    - [Resources concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#resources)
+    - [Tools concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#tools)
+    - [Prompt objects concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts)
+    - [Sampling concept docs](https://modelcontextprotocol.io/docs/learn/client-concepts)
+
+## Notes
+
+- Prefer these links when the user asks about protocol correctness, transport semantics, capability naming, or compatibility.
+- For implementation-level examples, use [sdk-and-fastmcp.md](./sdk-and-fastmcp.md).

docs/skills/mcp-details/references/sdk-and-fastmcp.md

@@ -0,0 +1,31 @@
+# SDK and FastMCP
+
+Use this page for implementation-oriented links across MCP SDKs and FastMCP.
+
+## MCP SDKs
+
+!!! info "SDK sources"
+    - [Python SDK repository](https://github.com/modelcontextprotocol/python-sdk)
+    - [TypeScript SDK repository](https://github.com/modelcontextprotocol/typescript-sdk)
+    - [Python SDK documentation](https://modelcontextprotocol.github.io/python-sdk/)
+
+## FastMCP
+
+!!! info "FastMCP sources"
+    - [FastMCP project documentation](https://gofastmcp.com/)
+    - [FastMCP GitHub repository](https://github.com/jlowin/fastmcp)
+    - [FastMCP examples directory](https://github.com/jlowin/fastmcp/tree/main/examples)
+    - [FastMCP PyPI package](https://pypi.org/project/fastmcp/)
+
+## Server Implementation Patterns
+
+!!! info "Implementation references"
+    - [MCP server concepts](https://modelcontextprotocol.io/docs/learn/server-concepts)
+    - [MCP architecture patterns](https://modelcontextprotocol.io/docs/learn/architecture)
+    - [Python packaging and resources](https://docs.python.org/3/library/importlib.resources.html)
+
+## Notes
+
+- Prefer official SDK repositories for API shape and compatibility checks.
+- Use FastMCP references for rapid server scaffolding and implementation examples.
+- For protocol-first questions, start from [mcp-protocol-and-spec.md](./mcp-protocol-and-spec.md).

docs/skills/new-skill/SKILL.md

@@ -1,42 +0,0 @@
----
-name: new-skill
-description: Provide a practical checklist and baseline template for creating a new docs-first MCP skill in this repository.
-argument-hint: What skill are you creating, and what problem should it solve?
-x-personal-mcp:
-  id: new-skill
-  version: 1.0.0
-  tags:
-    - fastmcp
-    - bootstrap
-    - scaffolding
-    - skills
-    - mcp
-  capabilities:
-    - resource://skills/new-skill/document
-  depends_on: []
-  references: {}
----
-
-# New Skill Bootstrap
-
-Use this skill to bootstrap a new skill in the docs-first architecture.
-
-## Scope
-
-1. Create docs under docs/skills/<skill-id>/.
-2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields.
-3. Declare references via x-personal-mcp.references when needed.
-4. Validate the docs build and MCP resource reads.
-
-## Authoring Checklist
-
-1. Create docs/skills/<skill-id>/SKILL.md.
-2. Add docs/skills/<skill-id>/references/ files as needed.
-3. Keep skill id and directory name aligned.
-4. Keep frontmatter name equal to x-personal-mcp.id.
-5. Include resource://skills/<skill-id>/document in capabilities.
-
-## Validation
-
-1. uv run zensical build
-2. uv run pytest -q

docs/skills/nicegui-ui-customization/SKILL.md

@@ -1,145 +0,0 @@
----
-name: nicegui-ui-customization
-description: 'Design and implement production NiceGUI UIs with reusable components, Tailwind-first styling, event-driven interactions, and troubleshooting for uploads, state, and static assets. Use when building or refactoring NiceGUI pages and interaction flows.'
-argument-hint: 'What UI outcome should this workflow produce?'
-x-personal-mcp:
-  id: nicegui-ui-customization
-  version: 1.0.0
-  tags:
-    - nicegui
-    - ui
-    - customization
-    - frontend
-  capabilities:
-    - resource://skills/nicegui-ui-customization/document
-  depends_on: []
----
-
-# NiceGUI UI Customization Workflow
-
-Create, style, and ship production NiceGUI UI flows with a repeatable process. The workflow keeps structure in Python, favors Tailwind and Quasar APIs for styling, and uses event-driven interaction patterns over ad-hoc polling.
-
-## When To Use
-
-- Building a new NiceGUI page or dashboard
-- Refactoring a page into reusable components
-- Adding file upload, form submission, live status, or background-job UX
-- Troubleshooting race conditions, stale assets, or inconsistent state updates
-
-## Target Outcome
-
-Deliver a responsive, accessible UI flow that:
-
-- keeps clear boundaries between page adapters, reusable components, and services
-- uses Tailwind-first styling with minimal custom CSS
-- updates UI through events and bindings
-- has validation, user feedback, and failure handling
-- passes a production-readiness check at the end
-
-## Progressive Loading References
-
-Load these references only when needed:
-
-- Architecture and styling rules: [architecture and styling](./references/architecture-and-styling.md)
-- Event and state interaction patterns: [interaction patterns](./references/interaction-patterns.md)
-- Troubleshooting and release gates: [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md)
-
-## Procedure
-
-### 1. Define the UI Slice
-
-- Capture the user-visible outcome for this task in one sentence.
-- Identify route-level page modules to touch.
-- Identify service operations needed by the UI.
-
-Completion check:
-
-- You can name the target page, component candidates, and service calls before coding.
-
-### 2. Choose Component Extraction Strategy
-
-Decision point:
-
-- If a layout pattern appears in 2 or more pages, extract it to `ui/components/`.
-- If a pattern is page-specific, keep it in the page module.
-
-Completion check:
-
-- Reused UI patterns are encapsulated as callable components.
-
-### 3. Build Responsive Layout First
-
-- Use Tailwind utility classes for structure and spacing.
-- Use responsive breakpoints (`sm:`, `md:`, `lg:`).
-- Reserve `.style()` for dynamic values that cannot be expressed with classes.
-
-Completion check:
-
-- Layout works at mobile and desktop widths without custom CSS overrides.
-
-### 4. Add Reactive State And Events
-
-- Use bindable dataclasses for local page state.
-- Prefer event handlers (`on_click`, `on_upload`, etc.) over periodic polling.
-- Trigger explicit refreshes with `@ui.refreshable` where needed.
-
-Decision point by interaction type:
-
-- File upload: validate size/type, delegate storage to a service, notify success/failure.
-- Form submit: bind inputs to dataclass fields, validate in service layer, clear state on success.
-- Real-time status: use SSE or WebSocket for push updates.
-- Long jobs: run in background task, update status endpoint or stream.
-
-Completion check:
-
-- Every user action has explicit positive and negative feedback via `ui.notify()`.
-
-### 5. Apply Styling Strategy
-
-Preferred order:
-
-1. Tailwind utility classes
-2. Quasar props
-3. Reusable styled component functions
-
-Only if absolutely necessary:
-
-- Load minimal custom CSS once at startup in `bootstrap.py`.
-- Keep custom CSS tokenized (variables) and documented.
-
-Completion check:
-
-- Styling is mostly class/props-driven and not dependent on scattered ad-hoc CSS.
-
-### 6. Harden Against Common Failures
-
-- Prevent duplicate submissions by disabling controls during in-flight operations.
-- Avoid overlapping timers for the same state target.
-- Serialize dependent updates (`await` service call before mutation/render).
-- Verify static mount paths and cache behavior for changed assets.
-
-Completion check:
-
-- Race conditions and stale asset symptoms are addressed with explicit safeguards.
-
-### 7. Final Production Readiness Review
-
-Pass all checks:
-
-- Structure: pages, components, services follow one-way dependency flow.
-- Responsiveness: tested at small and large viewport widths.
-- Accessibility: labels, button text, and action visibility are clear.
-- Reliability: validation and exception paths produce user-facing notifications.
-- Maintainability: repeated UI patterns are extracted; business logic stays in services.
-
-If any check fails, return to the relevant step and iterate.
-
-## Completion Contract
-
-This workflow is complete when:
-
-- the page flow meets the target outcome
-- architecture boundaries are preserved
-- chosen interaction pattern is implemented with explicit success and failure feedback
-- troubleshooting checks pass
-- production-readiness gate passes

docs/skills/nicegui-ui-customization/references/architecture-and-styling.md

@@ -1,77 +0,0 @@
-# Architecture and Styling Reference
-
-## Project Boundaries
-
-Use this dependency direction:
-
-- pages import components and services
-- components contain presentation logic only
-- services contain business logic and do not import UI
-- static assets are mounted and loaded once at bootstrap
-
-Suggested module split:
-
-```text
-src/app/
-  ui/pages/
-  ui/components/
-  ui/static/
-  services/
-  api/
-  bootstrap.py
-```
-
-## Component Extraction Rules
-
-Extract to ui/components when a pattern appears in two or more pages.
-
-Keep in-page if the layout is specific to a single route.
-
-```python
-def card_section(title: str, content: str) -> ui.card:
-    with ui.card().classes("w-full max-w-md") as card:
-        ui.label(title).classes("text-lg font-bold")
-        ui.label(content).classes("text-gray-600")
-    return card
-```
-
-## Tailwind-First Layout Pattern
-
-Use Tailwind utility classes for structure and spacing.
-Use breakpoint classes for responsive behavior.
-Use .style() only for values that must be computed dynamically.
-
-```python
-with ui.column().classes("w-full"):
-    with ui.row().classes("w-full gap-4 flex-wrap sm:flex-nowrap"):
-        ui.card().classes("flex-1 min-w-64")
-        ui.card().classes("flex-1 min-w-64")
-```
-
-## Styling Decision Order
-
-1. Tailwind utility classes
-2. Quasar props
-3. Reusable styled component functions
-4. Minimal custom CSS loaded once at bootstrap (only when needed)
-
-```python
-from fastapi.staticfiles import StaticFiles
-
-app.mount("/static", StaticFiles(directory="src/app/static"), name="static")
-ui.add_css(open("src/app/static/css/base.css").read())
-```
-
-## Static Asset Rules
-
-- Keep custom CSS small and tokenized with variables.
-- Avoid per-page CSS injection.
-- Verify static mount paths and reverse proxy rewrites.
-
-## Links
-
-!!! info "Primary sources"
-    - [NiceGUI elements](https://nicegui.io/documentation/element)
-    - [NiceGUI binding properties](https://nicegui.io/documentation/section_binding_properties)
-    - [Tailwind utility-first styling](https://tailwindcss.com/docs/utility-first)
-    - [Quasar components](https://quasar.dev/vue-components)

docs/skills/nicegui/SKILL.md

@@ -1,207 +1,157 @@
 ---
 name: nicegui
-description: 'Design and scaffold a production-ready NiceGUI + FastAPI application architecture. Use for multi-page app planning, package boundaries, optional DB/LangGraph/docs integration, and implementation checklists.'
-argument-hint: 'What should this app include (pages, DB, AI, docs, constraints)?'
+description: 'Reference hub for NiceGUI and FastAPI application structure, typed configuration, ASGI and Uvicorn startup, UI composition, styling, bindable state, interactions, troubleshooting, testing, and source documentation. Use when planning, implementing, reviewing, deploying, or debugging NiceGUI applications; load only the references relevant to the task.'
 x-personal-mcp:
   id: nicegui
-  version: 1.0.0
+  version: 2.5.0
   tags:
     - nicegui
     - fastapi
+    - asgi
+    - uvicorn
+    - pydantic-settings
+    - configuration
+    - deployment
     - ui
     - architecture
+    - scaffolding
+    - customization
+    - frontend
+    - testing
+    - source-docs
   capabilities:
     - resource://skills/nicegui/document
-  depends_on: []
 ---
 
-# NiceGUI
+# NiceGUI Reference
 
-Design a production-minded NiceGUI + FastAPI architecture with clear boundaries, optional extensions, and a concrete implementation checklist.
+Use this skill as a progressive reference for NiceGUI applications built with FastAPI. Start with the routing map, load only the material needed for the current question, and reconcile it with the target project's NiceGUI version and established conventions.
 
 ## When to Use
 
-- You need a reusable architecture plan before implementing a NiceGUI app.
-- You want FastAPI app-factory structure and lifespan wiring.
-- You need optional guidance for database, LangGraph workflows, or mounted static docs.
-- You want output that is concise, structured, and implementation-ready.
+- Planning or reviewing NiceGUI application structure and FastAPI composition.
+- Building or refactoring pages, components, layouts, and static assets.
+- Modeling UI state with bindings or bindable dataclasses.
+- Implementing forms, uploads, refreshes, live updates, or background work.
+- Diagnosing UI state, concurrency, navigation, or asset problems.
+- Verifying framework behavior against primary documentation.
 
-## Inputs to Collect
+## How to Use This Skill
 
-Collect these inputs up front. If not provided, make safe defaults and state assumptions.
+1. Classify the request using the discovery map below.
+2. Load the smallest relevant reference, or at most two references for a mixed concern.
+3. Inspect the target repository before applying guidance; preserve its sound local patterns.
+4. Check the pinned NiceGUI and integration versions before relying on version-specific APIs.
+5. Validate the changed behavior with focused tests and, for UI work, relevant viewport checks.
 
-- Product scope and primary user journeys.
-- Required pages and route map.
-- Whether persistent data is required.
-- Whether AI orchestration (multi-step, streaming, approvals) is required.
-- Whether generated docs should be mounted in-app.
-- Runtime/deployment constraints (single service vs split services, environment requirements).
+## Progressive Discovery Map
 
-## Outcome
+### Application Architecture
 
-Produce:
+Load [application architecture](./references/architecture.md) for:
 
-- A concise architecture explanation.
-- How core services, UI pages, and UI components fit together.
-- Explicit decision on DB ownership or involvement.
-- Explicit decision on AI workflow (or no AI).
-- A checklist implementation plan organized by package and domain.
+- FastAPI app factories and lifespan ownership
+- package boundaries and dependency direction
+- page registration and health routes
+- optional persistence, LangGraph, or mounted documentation
+- async responsiveness and baseline tests
 
-## Procedure
+### FastAPI And Uvicorn Startup
 
-1. Frame the baseline architecture.
-2. Choose optional extensions (DB, AI, docs) using decision points below.
-3. Map modules, dependencies, and key boundaries.
-4. Define async behavior and UI responsiveness expectations.
-5. Define key functions/classes and configuration surfaces.
-6. Produce phased checklist with rollout or migration notes when relevant.
-7. Run completion checks before returning.
+Load [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) for:
 
-### 1) Baseline architecture
+- choosing between `ui.run()` and `ui.run_with()`
+- understanding the parent FastAPI app and NiceGUI's internal app
+- composing ASGI lifespan and mounted routes
+- loading one typed settings snapshot for server and application configuration
+- serving an app instance or factory with Uvicorn
+- exposing programmatic startup through `[project.scripts]`
+- reload, worker, and process-local state constraints
 
-Use a src-layout with FastAPI as the ASGI app and NiceGUI registered via composition.
+### Components And Styling
 
-- App factory pattern: `create_app()`.
-- Lifespan for startup and shutdown resource management.
-- `api/` for HTTP handlers, `services/` for business logic.
-- `ui/pages/` for page modules, `ui/components/` for shared UI.
-- Health endpoint on FastAPI side: `/healthz`.
+Load [architecture and styling](./references/architecture-and-styling.md) for:
 
-Recommended base shape:
+- page, component, and service boundaries
+- component extraction decisions
+- Quasar props, Tailwind utilities, and custom CSS boundaries
+- responsive layout and static asset conventions
+- Tailwind and Quasar breakpoint scales, container queries, and responsive testing
+- uniformly scaling dialogs on mobile
+- preserving Quasar field proportions
+- keeping detached `QSelect` menus anchored
+- sizing scrollable dialog cards under CSS `zoom`
+- validating zoomed controls with Playwright or a browser
 
-```text
-.
-├─ pyproject.toml
-├─ .env.example
-├─ README.md
-├─ src/
-│  └─ app/
-│     ├─ __init__.py
-│     ├─ main.py
-│     ├─ bootstrap.py
-│     ├─ config.py
-│     ├─ logging.py
-│     ├─ api/
-│     │  ├─ __init__.py
-│     │  └─ health.py
-│     ├─ services/
-│     │  ├─ __init__.py
-│     │  └─ example_service.py
-│     └─ ui/
-│        ├─ __init__.py
-│        ├─ components/
-│        │  ├─ __init__.py
-│        │  └─ nav.py
-│        └─ pages/
-│           ├─ __init__.py
-│           ├─ home.py
-│           ├─ dashboard.py
-│           └─ about.py
-└─ tests/
-   ├─ test_health.py
-   └─ test_pages_registration.py
-```
+### Bindable State
 
-### 2) Decision points
+Load [bindable dataclasses](./references/binding-dataclasses.md) for:
 
-#### Database needed?
+- typed local UI state
+- propagation and refresh behavior
+- nested structures and strict bindings
+- mutable defaults, performance, and version notes
 
-- If no: keep `services/` pure and skip persistence layers.
-- If yes: add `db/` package with engine/session/model/repository layering.
-- Prefer one process-level engine and request-scoped sessions via `yield`.
-- Prefer Alembic migrations for schema changes.
+### Interaction Patterns
 
-#### AI workflow needed?
+Load [interaction patterns](./references/interaction-patterns.md) for:
 
-- If no: keep `services/` focused on app logic only.
-- If yes: add `ai/` package (state, nodes, graph, runtime, contracts).
-- Keep graph internals out of `ui/pages/` and API handlers.
-- Use stable thread/session IDs for resumable flows.
+- uploads and form submission
+- explicit refreshes
+- server-sent events and WebSockets
+- background work and duplicate-submission guards
 
-#### Mounted docs needed?
+### Troubleshooting And Quality
 
-- If no: skip docs mounting.
-- If yes: mount generated static site under configurable route (default `/docs`).
-- Keep docs mounting in composition layer, not page modules.
+Load [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md) for:
 
-### 3) Page and component registration
+- upload failures and UI race conditions
+- stale assets and navigation drift
+- responsiveness, accessibility, reliability, and maintainability checks
 
-- Require at minimum page modules for `/`, `/dashboard`, `/about`.
-- Prefer explicit registration pattern:
-  - `ui/pages/__init__.py` exports `register_pages()`.
-  - Each page module exports `register_page()`.
-- Shared shell components (header/nav/drawer) live in `ui/components/`.
+### Primary Sources
 
-### 4) Dependency direction rules
+Load [source documentation](./references/source-documentation.md) when:
 
-Prefer:
+- behavior is version-sensitive or uncertain
+- an integration recommendation needs verification
+- upstream NiceGUI, FastAPI, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation is required
 
-- `main/bootstrap` -> `config/logging` + `api` + `ui/pages` + `services`
-- `api` -> `services`
-- `ui/pages` -> `ui/components` + `services`
-- `services` -> helpers/clients (and `db/` when enabled)
+## Common Discovery Paths
 
-Avoid reverse imports from services into API or UI modules.
+### New Application Or Architecture Review
 
-### 5) Async and UI responsiveness rules
+1. Load [application architecture](./references/architecture.md).
+2. Add [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) when FastAPI owns the application or startup must be exposed as a project command.
+3. Add [architecture and styling](./references/architecture-and-styling.md) only when page and component design is in scope.
 
-- Prefer `async def` for page handlers, service methods, and integrations when the call path includes I/O.
-- Use non-blocking clients/libraries where possible so long-running I/O does not freeze UI updates.
-- Do not run blocking calls (`time.sleep`, blocking HTTP/database clients) in UI event handlers.
-- For heavy CPU work, offload to worker/background execution and keep the UI loop free.
-- Show progress states for long actions (disable action button, show spinner/progress text, re-enable on completion).
-- Stream or chunk incremental results to the UI when workflows are multi-step or long-running.
-- Keep cancellation and timeout behavior explicit for user-triggered long tasks.
-- Ensure exceptions from async tasks are surfaced with user-friendly feedback and logged for diagnostics.
+### Page Or Component Work
 
-### 6) Testing minimums
+1. Load [architecture and styling](./references/architecture-and-styling.md).
+2. Add [interaction patterns](./references/interaction-patterns.md) or [bindable dataclasses](./references/binding-dataclasses.md) according to the page behavior.
 
-- Test FastAPI health route behavior.
-- Test page registration wiring.
-- If DB enabled: session lifecycle and rollback behavior tests.
-- If AI enabled: graph happy path and interrupt/resume coverage.
-- If docs enabled: mounted docs route returns index page.
-- For async flows: test long-running actions preserve UI responsiveness (loading state, completion state, and error state).
+### Debugging Or Production Review
 
-### 7) Styling architecture
+1. Start with [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md).
+2. Follow the symptom to one detailed reference.
+3. Confirm uncertain behavior in [source documentation](./references/source-documentation.md).
 
-- Keep structure and layout in Python modules using NiceGUI class composition.
-- Keep visual polish in shared CSS files, loaded once at startup.
-- Prefer semantic reusable classes over ad hoc per-page styling.
+## General Defaults
 
-## Completion Checks
+- Keep composition, transport, services, pages, and components directionally separated.
+- Keep business logic out of UI components and event handlers.
+- Avoid blocking I/O and CPU-heavy work in the UI event loop.
+- Prefer event-driven updates and explicit refreshes over unrelated polling.
+- Prefer Tailwind utilities, then Quasar props, then reusable component helpers; use minimal shared CSS when those are insufficient.
+- Provide loading, success, and failure states for user-triggered work.
+- Treat version-specific guidance as a prompt to verify the project's dependency version.
 
-- Uses app factory and FastAPI lifespan.
-- Pages are modularized (not single-file UI).
-- Health endpoint exists on FastAPI side.
-- Dependency direction is clean and one-way.
-- Async-first guidance is applied where I/O exists, with explicit non-blocking UX states.
-- Optional DB/AI/docs decisions are explicit and reflected in structure.
-- Output includes architecture summary and package-organized checklist.
+## Reference Use Contract
 
-## Output Contract
+When applying this skill:
 
-Return:
-
-- Concise high-level architecture.
-- How core services, pages, and shared components fit.
-- DB involvement and ownership stance.
-- AI workflow stance and runtime flow.
-- Checklist plan by package and domain:
-  - key functions/classes
-  - settings/config surfaces
-  - rollout/migration notes (when relevant)
-
-## Guardrails
-
-- Do not collapse all pages into one file.
-- Do not use globals or implicit global side effects.
-- Do not block UI event handlers with synchronous I/O or long CPU tasks.
-- Always define loading/progress/error states for long user-triggered actions.
-- Keep code minimal but production-minded.
-- Prefer clarity and maintainability over clever abstractions.
-
-## References
-
-- Architecture and integration details: [NiceGUI architecture reference](./references/architecture.md)
-- Source documentation links: [NiceGUI source documentation](./references/source-documentation.md)
+- return only guidance relevant to the current task
+- distinguish repository facts from reference recommendations
+- cite the appropriate source reference for framework-level claims
+- state assumptions when application requirements are missing
+- report the focused checks used to validate implementation changes

docs/skills/nicegui/references/architecture-and-styling.md

@@ -0,0 +1,289 @@
+# NiceGUI Page Layout And Styling
+
+Use this reference to structure NiceGUI pages, choose component boundaries, apply responsive layout, and introduce custom CSS without fighting Quasar's internal geometry.
+
+## Ownership And Dependency Boundaries
+
+Keep dependencies flowing in one direction:
+
+- pages import components and services
+- components contain presentation logic only
+- services contain business logic and do not import UI
+- bootstrap code mounts static assets and loads shared CSS once
+
+Suggested module split:
+
+```text
+src/my_app/
+  ui/
+    pages/
+    components/
+    static/
+  services/
+  api/
+```
+
+Page modules should compose a route from reusable presentation and service calls. They should not own domain rules, persistence, or long-running synchronous work.
+
+## Page Composition
+
+Build the outer layout before styling individual controls:
+
+1. Define the page shell and width constraints.
+2. Establish responsive rows, columns, gaps, and wrapping.
+3. Add semantic sections and repeated components.
+4. Configure Quasar component appearance with props.
+5. Add custom CSS only for behavior that props and utilities cannot express safely.
+
+```python
+with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4"):
+    page_header(title="Inventory")
+
+    with ui.row().classes("w-full gap-4 flex-wrap lg:flex-nowrap items-start"):
+        filters_panel().classes("w-full lg:w-72 shrink-0")
+        item_grid().classes("w-full flex-1 min-w-0")
+```
+
+Use stable width, minimum-width, and flex constraints so labels, icons, validation messages, and loaded content do not shift the surrounding layout.
+
+## Component Extraction
+
+Extract a presentation pattern to `ui/components/` when it appears on two or more pages or when it owns a meaningful interaction boundary. Keep one-off route layout in the page module.
+
+```python
+def card_section(title: str, content: str) -> ui.card:
+    with ui.card().classes("w-full max-w-md") as card:
+        ui.label(title).classes("text-lg font-bold")
+        ui.label(content).classes("text-gray-600")
+    return card
+```
+
+Reusable components should accept data and event callbacks rather than import page state or business services implicitly.
+
+## Styling Decision Order
+
+NiceGUI wraps Quasar components. Choose the styling mechanism according to what it owns:
+
+1. Use Quasar props for component appearance, density, labels, and popup behavior.
+2. Use NiceGUI `.classes()` and Tailwind utilities for width, spacing, alignment, and responsive layout.
+3. Use reusable component functions for repeated visual patterns.
+4. Use `.style()` for genuinely dynamic inline values.
+5. Use minimal shared CSS only when props and utilities are insufficient.
+
+Common Quasar props include:
+
+- `outlined`
+- `dense`
+- `stack-label`
+- `popup-content-class`
+- `input-class`
+- `input-style`
+
+Avoid overriding internal selectors such as:
+
+- `.q-field__label`
+- `.q-field__native`
+- `.q-field__control`
+- `.q-field__input`
+
+Quasar coordinates field height, padding, labels, values, icons, and floating-label transforms. Changing only one internal part tends to cause clipping or overlap.
+
+## Responsive Layout
+
+Support these layouts only:
+
+- mobile: a single-column layout with wrapping toolbars and full-width controls
+- landscape desktop: $1920 \times 1080$ with side-by-side panels where they improve scanning
+- portrait desktop: $1080 \times 1920 with stacked panels or a narrow fixed sidebar
+
+Build the mobile layout first, then add one desktop breakpoint when a row or grid needs more space. Prefer flex wrapping and fluid grids before adding another breakpoint. Use Tailwind classes for page layout and Quasar props for component behavior.
+
+```python
+with ui.row().classes('w-full flex-wrap gap-4 lg:flex-nowrap items-start'):
+    filters_panel().classes('w-full lg:w-72 shrink-0')
+    item_grid().classes('w-full flex-1 min-w-0')
+```
+
+Use `min-w-0` for flexible children, `flex-wrap` for toolbars, and `max-w-* mx-auto` to keep portrait layouts readable. Do not add device-specific component trees, container queries, or custom breakpoints unless a supported layout demonstrates a concrete failure.
+
+## Static Assets And Shared CSS
+
+- Mount static assets from the composition layer.
+- Load shared CSS once rather than injecting it from individual pages.
+- Keep custom CSS tokenized with variables and scoped to application classes.
+- Avoid broad rules against Quasar internals.
+- Verify mount paths, reverse-proxy rewrites, and cache behavior.
+
+```python
+from pathlib import Path
+
+from fastapi.staticfiles import StaticFiles
+
+STATIC_DIR = Path(__file__).parent / "ui" / "static"
+
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+ui.add_css((STATIC_DIR / "css" / "base.css").read_text(encoding="utf-8"))
+```
+
+## Responsive Dialog Pattern
+
+Use whole-card scaling when a form dialog must become uniformly larger on mobile while preserving Quasar's internal proportions. Keep detached select menus unscaled and make the card itself scrollable.
+
+### Use Normal Field Density
+
+Normal Quasar fields are approximately `56px` high, while dense fields are approximately `40px` high. Remove `dense` when larger controls are needed.
+
+```python
+ui.input("Name").props("outlined")
+ui.number("Quantity").props("outlined")
+ui.select(...).props(
+    "outlined popup-content-class=app-item-detail-menu"
+)
+ui.textarea("Description").props("outlined autogrow")
+```
+
+Add a scoped class to the dialog card:
+
+```python
+ui.card().classes("app-detail-card app-item-detail-card")
+```
+
+### Scale The Complete Card
+
+```css
+:root {
+    --item-dialog-scale: 1;
+    --item-dialog-max-height: calc(100dvh - 3rem);
+}
+
+.app-item-detail-card {
+    width: min(50rem, 50vw);
+    max-height: var(--item-dialog-max-height);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    zoom: var(--item-dialog-scale);
+}
+
+/* Restore Quasar's baseline if a global rule overrides it. */
+.app-item-detail-card .q-field,
+.app-item-detail-menu {
+    font-size: 14px;
+}
+
+@media (max-width: 599px) {
+    :root {
+        --item-dialog-scale: 1.2;
+        /* 75dvh becomes 90dvh after 1.2x zoom. */
+        --item-dialog-max-height: 75dvh;
+    }
+
+    .app-item-detail-card {
+        width: 80vw;
+    }
+
+    .app-item-detail-menu {
+        font-size: 16.8px;
+    }
+}
+```
+
+The main mobile tuning knob is:
+
+```css
+--item-dialog-scale: 1.2;
+```
+
+### Keep Detached Popups Unscaled
+
+Do not apply `zoom` or `transform: scale()` to a `QSelect` popup menu. Quasar renders menus outside the dialog and positions them from the unscaled anchor geometry. Scaling the menu container afterward separates it from its field.
+
+Avoid:
+
+```css
+.app-item-detail-card,
+.app-item-detail-menu {
+    zoom: 1.2;
+}
+```
+
+Use:
+
+```css
+.app-item-detail-card {
+    zoom: 1.2;
+}
+
+.app-item-detail-menu {
+    font-size: 16.8px;
+}
+```
+
+Use `popup-content-class=app-item-detail-menu` to target the detached menu and enlarge its text without changing its coordinate system.
+
+### Account For Zoom When Scrolling
+
+The card's pre-zoom maximum height must account for the scale:
+
+\[
+\begin{aligned}
+h_{\mathrm{pre}} &= \frac{h_{\mathrm{visible}}}{s} \\
+\text{where } s &= \text{the zoom scale}
+\end{aligned}
+\]
+
+For a desired visual height of `90dvh` at \(1.2\times\):
+
+\[
+\frac{90\,\mathrm{dvh}}{1.2} = 75\,\mathrm{dvh}
+\]
+
+Therefore:
+
+```css
+--item-dialog-max-height: 75dvh;
+```
+
+Apply scrolling to the card itself:
+
+```css
+.app-item-detail-card {
+    max-height: var(--item-dialog-max-height);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+}
+```
+
+This keeps the dimmed page stationary while the form scrolls.
+
+### Match The Quasar Breakpoint
+
+Quasar's extra-small breakpoint ends at `599.98px`. A mobile-only rule can use:
+
+```css
+@media (max-width: 599px) {
+    /* Mobile rules. */
+}
+```
+
+Confirm custom breakpoint values against the target application's Quasar configuration.
+
+## Validation Checklist
+
+Check each completed page at these three viewports:
+
+1. A representative mobile viewport, such as $390 \times 844$.
+2. Landscape desktop at $1920 \times 1080$.
+3. Portrait desktop at $1080 \times 1920$.
+
+Confirm that page sections do not overlap, toolbars wrap on mobile, desktop panels use the available space without becoming excessively wide, and dialogs remain visible and scroll to their final field.
+
+## Sources
+
+!!! info "Primary sources"
+    - [NiceGUI element styling and props](https://nicegui.io/documentation/element)
+    - [NiceGUI binding properties](https://nicegui.io/documentation/section_binding_properties)
+    - [Quasar components](https://quasar.dev/vue-components)
+    - [Quasar field](https://quasar.dev/vue-components/field/)
+    - [Quasar select](https://quasar.dev/vue-components/select/)
+    - [Tailwind responsive design](https://tailwindcss.com/docs/responsive-design)
+    - [MDN `zoom`](https://developer.mozilla.org/en-US/docs/Web/CSS/zoom)

docs/skills/nicegui/references/architecture.md

@@ -1,32 +1,77 @@
-# NiceGUI Architecture Reference
+# NiceGUI Application Architecture
 
-This reference expands the workflow in the main skill file and is loaded only when needed.
+Load this reference for application composition, package boundaries, and optional subsystem decisions.
 
-## Baseline package boundaries
+## Baseline Package Boundaries
 
-- `main.py`: process entrypoint only.
-- `bootstrap.py`: app composition, router wiring, page registration, lifespan orchestration.
-- `config.py`: typed settings and env parsing.
+- `main.py`: process entry point and app factory exposure.
+- `bootstrap.py`: app composition, router wiring, page registration, and lifespan orchestration.
+- `config.py`: typed settings and environment parsing.
 - `logging.py`: centralized logging setup.
-- `api/`: HTTP transport layer; delegates to services.
-- `services/`: business/use-case logic.
+- `api/`: HTTP transport that delegates to services.
+- `services/`: business and use-case logic.
 - `ui/pages/`: route-level NiceGUI pages.
-- `ui/components/`: shared UI building blocks.
+- `ui/components/`: shared presentation building blocks.
 
-## Required baseline behavior
+Recommended base shape:
+
+```text
+.
+├─ pyproject.toml
+├─ .env.example
+├─ src/
+│  └─ app/
+│     ├─ __init__.py
+│     ├─ main.py
+│     ├─ bootstrap.py
+│     ├─ config.py
+│     ├─ logging.py
+│     ├─ api/
+│     │  ├─ __init__.py
+│     │  └─ health.py
+│     ├─ services/
+│     │  ├─ __init__.py
+│     │  └─ example_service.py
+│     └─ ui/
+│        ├─ __init__.py
+│        ├─ components/
+│        │  ├─ __init__.py
+│        │  └─ nav.py
+│        └─ pages/
+│           ├─ __init__.py
+│           ├─ home.py
+│           ├─ dashboard.py
+│           └─ about.py
+└─ tests/
+   ├─ test_health.py
+   └─ test_pages_registration.py
+```
+
+## Required Baseline Behavior
 
 - FastAPI is the base ASGI app.
-- NiceGUI pages are modular and registered from page modules.
-- Minimum pages: `/`, `/dashboard`, `/about`.
-- FastAPI health route: `/healthz`.
-- Lifespan handles startup/shutdown resources.
-- No global side effects at import time.
+- `create_app()` composes routes, resources, and NiceGUI.
+- Lifespan owns startup and shutdown resources.
+- NiceGUI pages are modular and explicitly registered.
+- FastAPI exposes a health route such as `/healthz`.
+- Imports do not trigger runtime global side effects.
 
-## Optional extension: Database
+For the ownership relationship between a caller-created FastAPI app, `nicegui.app`, `ui.run_with()`, Uvicorn, and a packaged startup command, load [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md).
 
-Use only if persistence is required.
+## Dependency Direction
 
-Suggested additions:
+Prefer:
+
+- `main/bootstrap` -> `config/logging` + `api` + `ui/pages` + `services`
+- `api` -> `services`
+- `ui/pages` -> `ui/components` + `services`
+- `services` -> helpers, clients, and `db/` when enabled
+
+Avoid imports from services back into API or UI modules.
+
+## Optional Persistence
+
+Use only when the product requires durable data.
 
 ```text
 src/app/db/
@@ -37,19 +82,15 @@ src/app/db/
 └─ repositories/
 ```
 
-Guidelines:
+- Create one engine and sessionmaker per process.
+- Provide request- or operation-scoped sessions with `yield`.
+- Keep transaction boundaries explicit in service or repository flows.
+- Never share sessions across concurrent tasks.
+- Use Alembic as the schema migration source of truth.
 
-- One engine and one sessionmaker per process.
-- Request-scoped session dependency using `yield`.
-- Explicit transaction boundaries in service/repository flows.
-- Avoid shared sessions across concurrent tasks.
-- Use Alembic as schema source of truth.
+## Optional LangGraph AI
 
-## Optional extension: LangGraph AI
-
-Use only for multi-step AI orchestration or human-in-the-loop workflows.
-
-Suggested additions:
+Use only for multi-step orchestration, resumable work, streaming, or human approval.
 
 ```text
 src/app/ai/
@@ -60,33 +101,37 @@ src/app/ai/
 └─ contracts.py
 ```
 
-Guidelines:
-
-- Keep graph internals outside API/UI modules.
-- Invoke graph through `services/ai_service.py`.
-- Use stable thread/session IDs for resumable sessions.
+- Keep graph internals outside API and UI modules.
+- Invoke graphs through a service such as `services/ai_service.py`.
+- Use stable thread or session IDs for resumable flows.
 - Keep interrupt payloads JSON-serializable.
 
-## Optional extension: Mounted static docs
+## Optional Mounted Docs
 
-Use only when generated docs should be served in-app.
+Use only when generated docs must be served by the application.
 
 Suggested settings:
 
 - `docs_enabled`
 - `docs_mount_path`
 - `docs_site_dir`
-- `docs_require_build` (optional)
+- `docs_require_build`
 
-Guidelines:
+Mount docs in the composition layer, normalize the mount path, avoid route conflicts, and define behavior for missing build artifacts.
 
-- Mount docs in composition layer (`bootstrap.py`).
-- Normalize mount path and avoid route conflicts.
-- Warn on missing build artifacts unless strict mode is enabled.
+## Async And Responsiveness
 
-## Suggested output quality criteria
+- Use `async def` where a handler or service path performs I/O.
+- Prefer non-blocking clients and libraries.
+- Offload CPU-heavy work to worker or background execution.
+- Define progress, cancellation, timeout, completion, and error states for long actions.
+- Stream or chunk results when workflows are long-running or multi-step.
 
-- Clear architecture summary with assumptions.
-- Explicit decisions for DB, AI, and docs.
-- Package-scoped implementation checklist.
-- Minimal test plan aligned to enabled features.
+## Testing Minimums
+
+- Test the FastAPI health route.
+- Test page registration wiring.
+- If persistence is enabled, test session lifecycle and rollback behavior.
+- If AI is enabled, test happy paths and interrupt/resume behavior.
+- If docs are enabled, test the mounted index route.
+- For long actions, test loading, completion, and error states.

docs/skills/nicegui/references/binding-dataclasses.md

@@ -0,0 +1,100 @@
+# Binding Dataclasses Deep Dive
+
+Use this reference to model NiceGUI state with bindable dataclasses and avoid common propagation and performance pitfalls.
+
+## Primary Sources
+
+- NiceGUI binding docs: [binding properties](https://www.nicegui.io/documentation/section_binding_properties)
+- Python dataclass docs: [dataclasses module](https://docs.python.org/3/library/dataclasses.html)
+- Data class design rationale: [PEP 557](https://peps.python.org/pep-0557/)
+
+## Bindable Dataclass Behavior
+
+`@binding.bindable_dataclass` extends standard dataclasses by turning fields into bindable properties, allowing UI bindings to propagate when a field is assigned.
+
+```python
+from nicegui import binding, ui
+
+
+@binding.bindable_dataclass
+class Profile:
+    name: str = "Ada"
+    age: int = 37
+
+
+profile = Profile()
+
+ui.input("Name").bind_value(profile, "name")
+ui.number("Age", min=0).bind_value(profile, "age")
+ui.label().bind_text_from(profile, "name", backward=lambda name: f"User: {name}")
+```
+
+## Propagation And Performance
+
+NiceGUI distinguishes between two link types:
+
+- Bindable properties propagate efficiently when values are assigned.
+- Active links are checked in a refresh loop.
+
+Prefer bindable dataclasses for frequently updated form state. Keep binding transforms pure and inexpensive. If an application has many active links, tune `binding_refresh_interval` in `ui.run(...)` only after measuring the impact.
+
+## Dataclass Modeling Rules
+
+- Use `field(default_factory=...)` for mutable defaults.
+- Avoid `frozen=True` for models edited by UI controls.
+- Use `slots=True` only after confirming compatibility with inheritance and extension needs.
+- Keep UI-editable fields explicit and typed.
+
+```python
+from dataclasses import field
+
+from nicegui import binding
+
+
+@binding.bindable_dataclass
+class Filters:
+    query: str = ""
+    tags: list[str] = field(default_factory=list)
+```
+
+## Nested Structures
+
+NiceGUI supports tuple paths for nested data structures.
+
+```python
+from nicegui import ui
+
+data = {"user": {"name": "Ada"}}
+
+ui.input("Name").bind_value(data, ("user", "name"))
+ui.label().bind_text_from(data, ("user", "name"))
+```
+
+Keep nested dataclass updates explicit and predictable at the field level.
+
+## Strictness And Refactor Safety
+
+- Object attributes are checked by default.
+- Dictionary keys are not checked by default.
+- Use `strict=True` when missing dictionary keys should produce warnings.
+
+```python
+from nicegui import app, ui
+
+ui.input().bind_value(app.storage.user, "display_name", strict=True)
+```
+
+## Common Pitfalls
+
+- In-place mutation may not produce immediate UI synchronization. Assign the updated value back to the bound field.
+- Heavy binding transforms can degrade refresh performance. Move expensive work to event handlers or services.
+- State shared across unrelated pages or users can leak data. Scope models to the appropriate page, client, or user context.
+
+## Version Checks
+
+- `bindable_dataclass` was added in NiceGUI 2.11.0.
+- Depth-first binding propagation was documented in NiceGUI 2.16.0.
+- Binding `strict` behavior was documented in NiceGUI 3.0.0.
+- Tuple paths for nested properties were documented in NiceGUI 3.10.0.
+
+Verify these behaviors against the NiceGUI version pinned by the target project.

docs/skills/nicegui/references/fastapi-uvicorn-startup.md

@@ -0,0 +1,315 @@
+# FastAPI And Uvicorn Startup
+
+Use this reference when FastAPI owns the application and NiceGUI is one part of it. The central distinction is between **composing an ASGI application** and **starting an ASGI server**:
+
+- [`ui.run_with()`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui_run_with.py) composes NiceGUI with a caller-owned FastAPI application. It does not start Uvicorn.
+- [`uvicorn.run()`](https://www.uvicorn.org/#running-programmatically) starts the server and tells it which ASGI application to serve.
+
+## Ownership Model
+
+```mermaid
+flowchart TD
+    E["Project script: my-app"] --> M["main()"]
+    M --> S["get_settings()"]
+    M --> U["uvicorn.run()"]
+    U --> F["create_app()"]
+    F --> S
+    F --> P["Parent FastAPI app"]
+    P --> A["API routes and middleware"]
+    P -->|"mount_path=/gui"| N["NiceGUI App"]
+    U -->|"ASGI requests and lifespan"| P
+```
+
+The objects have separate responsibilities:
+
+| Object | Owner | Responsibility |
+| --- | --- | --- |
+| Parent `FastAPI` instance | Application code | Root ASGI app, API routes, middleware, lifespan, and mounted applications |
+| `Settings` instance | Application code | Immutable, process-local configuration snapshot shared by startup and composition |
+| `nicegui.app` | NiceGUI | A process-local [`App`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py) instance that subclasses `FastAPI` |
+| `ui.run_with(parent_app)` | NiceGUI integration | Configures NiceGUI, mounts `nicegui.app` into `parent_app`, and integrates lifecycle handling |
+| Uvicorn | Server process | Imports or receives the root ASGI app, opens sockets, drives lifespan, and serves requests |
+
+Uvicorn must serve the **parent FastAPI app** when using `ui.run_with()`. Passing `nicegui.app` to `ui.run_with()` is rejected because it would mount NiceGUI into itself and recurse on unmatched routes.
+
+## Choose One Startup Mode
+
+### Let NiceGUI Own Startup
+
+Use `ui.run()` when NiceGUI is the main application. Add ordinary FastAPI routes to the exported `nicegui.app` object:
+
+```python
+from nicegui import app, ui
+
+
+@app.get('/healthz')
+def health() -> dict[str, str]:
+    return {'status': 'ok'}
+
+
+@ui.page('/')
+def home() -> None:
+    ui.label('Home')
+
+
+ui.run()
+```
+
+In this mode, NiceGUI configures and starts its own [Uvicorn-derived server](https://github.com/zauberzeug/nicegui/blob/main/nicegui/server.py). Do not also call `uvicorn.run()`.
+
+### Let FastAPI Own The Application
+
+Use `ui.run_with()` when an existing FastAPI application owns middleware, API routers, OpenAPI configuration, lifespan resources, or deployment startup. The [official NiceGUI FastAPI example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py) follows this model.
+
+`mount_path` controls where the NiceGUI application appears externally. A NiceGUI page declared as `/` is reachable at `/gui/` when mounted at `/gui`, while parent routes such as `/healthz` remain at the root. A dedicated UI prefix usually makes ownership and route conflicts clearer than mounting both applications at `/`.
+
+## Canonical Factory Layout
+
+Keep application composition importable and server startup explicit:
+
+```text
+.
+├─ pyproject.toml
+└─ src/
+   └─ my_app/
+      ├─ __init__.py
+      ├─ config.py
+      └─ main.py
+```
+
+```python title="src/my_app/config.py"
+from functools import cache
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ServerSettings(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    host: str = '0.0.0.0'
+    port: int = 8000
+    log_level: Literal['critical', 'error', 'warning', 'info', 'debug', 'trace'] = (
+        'info'
+    )
+    reload: bool = False
+
+
+class GuiSettings(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    mount_path: str = '/gui'
+    storage_secret: SecretStr | None = None
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix='MY_APP_',
+        env_nested_delimiter='__',
+        env_file='.env',
+        env_file_encoding='utf-8',
+        frozen=True,
+    )
+
+    server: ServerSettings = Field(default_factory=ServerSettings)
+    gui: GuiSettings = Field(default_factory=GuiSettings)
+
+
+@cache
+def get_settings() -> Settings:
+    return Settings()
+```
+
+`ServerSettings` and `GuiSettings` inherit from `BaseModel` because they share one application owner, source policy, and process lifecycle. The root `BaseSettings` reads the sources once and validates one atomic snapshot. Environment variables use names such as `MY_APP_SERVER__PORT`, `MY_APP_SERVER__RELOAD`, `MY_APP_GUI__MOUNT_PATH`, and `MY_APP_GUI__STORAGE_SECRET`.
+
+The argument-free [`functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache) provider is appropriate here because both the project entry point and Uvicorn's zero-argument factory need process-lifetime access. Each reload or worker process gets its own settings instance. Do not add override arguments to `get_settings()`; inject a `Settings` instance directly into `create_app()` in tests or alternate composition roots. See the [Pydantic settings implementation guide](../../pydantic-settings/SKILL.md) for source precedence, independent settings boundaries, cache clearing, and runtime reload guidance.
+
+```python title="src/my_app/main.py"
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI
+from nicegui import ui
+
+from my_app.config import Settings, get_settings
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    app.state.ready = True
+    try:
+        yield
+    finally:
+        app.state.ready = False
+
+
+def register_pages() -> None:
+    @ui.page('/')
+    def dashboard() -> None:
+        ui.label('Dashboard')
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or get_settings()
+    app = FastAPI(lifespan=lifespan)
+    app.state.settings = settings
+
+    @app.get('/healthz')
+    def health() -> dict[str, str]:
+        return {'status': 'ok'}
+
+    register_pages()
+    ui.run_with(
+        app,
+        mount_path=settings.gui.mount_path,
+        storage_secret=(
+            settings.gui.storage_secret.get_secret_value()
+            if settings.gui.storage_secret is not None
+            else None
+        ),
+    )
+    return app
+
+
+def main() -> None:
+    settings = get_settings()
+    uvicorn.run(
+        'my_app.main:create_app',
+        factory=True,
+        host=settings.server.host,
+        port=settings.server.port,
+        log_level=settings.server.log_level,
+        reload=settings.server.reload,
+    )
+
+
+if __name__ == '__main__':
+    main()
+```
+
+The `storage_secret` is optional unless the application uses `ui.storage.user` or `ui.storage.browser`. `SecretStr` prevents accidental plaintext display in logs and model representations, while `get_secret_value()` unwraps it only at the NiceGUI integration boundary. Supply production secrets through environment variables or a supported settings secret source rather than committing them.
+
+The example passes an [import string and `factory=True`](https://www.uvicorn.org/settings/#application) to Uvicorn. Uvicorn imports `my_app.main`, calls the zero-argument `create_app` factory, and serves the returned parent FastAPI app. Import strings are also required when Uvicorn creates reload or worker subprocesses; passing `create_app()` directly only supports the simple single-process case.
+
+NiceGUI keeps framework state in its process-local app singleton. Treat `create_app()` as a once-per-worker factory. Calling it repeatedly in one interpreter can register the same pages and lifecycle handlers more than once; tests that create multiple apps must isolate or reset NiceGUI state.
+
+## Lifespan Ordering
+
+The [ASGI lifespan protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) is driven by the server. Uvicorn sends startup before accepting requests and sends shutdown while terminating the process. Lifespan runs once per event loop, including once in each worker process.
+
+Current NiceGUI source integrates with the parent application by:
+
+1. Capturing the parent FastAPI lifespan context.
+2. Mounting NiceGUI's internal app on the parent.
+3. Replacing the parent lifespan with a wrapper.
+4. Starting NiceGUI before entering the original parent lifespan.
+5. Exiting the original parent lifespan before shutting down NiceGUI.
+
+This exact ordering comes from the current [`ui.run_with` implementation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui_run_with.py) and is version-sensitive. Check the pinned NiceGUI version before making one startup handler depend on another framework's internal ordering.
+
+Create database pools, HTTP clients, and similar resources in the parent [FastAPI lifespan](https://fastapi.tiangolo.com/advanced/events/), then close them after `yield`. Do not create event-loop-bound resources at import time or assume that globals are shared between workers.
+
+## Expose The Server As A Project Script
+
+Map a command name to the no-argument startup function:
+
+```toml title="pyproject.toml"
+[project]
+name = "my-app"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi",
+    "nicegui",
+    "pydantic-settings",
+    "uvicorn[standard]",
+]
+
+[project.scripts]
+my-app = "my_app.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/my_app"]
+```
+
+Run the installed command through uv:
+
+```bash
+uv run my-app
+```
+
+The uv [project entry-point documentation](https://docs.astral.sh/uv/concepts/projects/config/#entry-points) requires a build system so uv installs the project and generates its command. The `[project.scripts]` target follows the [PyPA entry-point specification](https://packaging.python.org/en/latest/specifications/entry-points/#use-for-scripts): its generated wrapper imports `main`, calls it without arguments, and uses the return value as the process exit status. Returning `None` means successful completion.
+
+The settings model now owns host, port, logging, reload, mount path, and storage-secret configuration. Add an explicit CLI settings source or another CLI parser only when the project command needs user-supplied arguments; the entry-point callable itself still receives no arguments.
+
+## Development Reload
+
+Because `main()` supplies an import string, it can enable Uvicorn reload for local development:
+
+```dotenv title=".env"
+MY_APP_SERVER__HOST=127.0.0.1
+MY_APP_SERVER__RELOAD=true
+```
+
+The cached settings object is a process-start snapshot. Changing an environment variable or dotenv file does not mutate a running instance; restart the process, or let the development reloader create a new worker when a watched file changes. Keep reload disabled in production. Uvicorn documents [`reload` and `workers` as mutually exclusive](https://www.uvicorn.org/settings/#production), and each worker would have independent settings, NiceGUI state, lifespan resources, and WebSocket connections. Use one worker by default unless the application has explicitly validated session affinity and externalized every stateful dependency needed across processes.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails | Preferred approach |
+| --- | --- | --- |
+| `ui.run_with(nicegui.app)` | Mounts NiceGUI into itself | Pass a separately created `FastAPI()` instance |
+| Calling both `ui.run()` and `ui.run_with()` | Gives two paths responsibility for startup | Choose one ownership model |
+| `uvicorn.run(create_app(), reload=True)` | Reload subprocesses cannot import the app object | Use an import string with `factory=True` |
+| Calling `uvicorn.run()` at module import time | Importing the module starts a blocking server and breaks subprocess startup | Call it from `main()` |
+| Top-level `ui.label(...)` with `ui.run_with()` | Script-mode elements are discarded by this integration | Register UI in `@ui.page` functions or a root callable |
+| Multiple workers by default | Process-local UI state and WebSockets are not automatically shared | Start with one worker and validate a distributed design explicitly |
+| Reconstructing `Settings()` throughout the app | Re-reads sources and obscures the active configuration lifecycle | Inject the startup snapshot or use the argument-free provider at framework boundaries |
+| Adding kwargs to cached `get_settings()` | Retains one hidden process-lifetime instance per argument combination | Construct explicit `Settings(...)` overrides and inject them |
+
+## Verification
+
+Use `TestClient` as a context manager so the parent ASGI lifespan runs:
+
+```python
+from fastapi.testclient import TestClient
+
+from my_app.config import GuiSettings, Settings
+from my_app.main import create_app
+
+
+def test_application_routes() -> None:
+    settings = Settings(
+        gui=GuiSettings(storage_secret='test-storage-secret'),
+    )
+
+    with TestClient(create_app(settings)) as client:
+        assert client.get('/healthz').json() == {'status': 'ok'}
+        assert client.get('/gui/').status_code == 200
+```
+
+Also verify:
+
+- startup resources exist while the client context is active and are released afterward
+- the mounted UI returns HTML and parent API failures retain FastAPI's JSON responses
+- `uv run my-app` starts the server and responds on both the API and UI paths
+- shutdown signals complete without orphaned background tasks
+
+## Primary Sources
+
+- [NiceGUI pages, routing, and FastAPI integration](https://www.nicegui.io/documentation/section_pages_routing)
+- [NiceGUI `ui.run_with` implementation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui_run_with.py)
+- [NiceGUI FastAPI example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py)
+- [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
+- [ASGI lifespan protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
+- [Uvicorn settings](https://www.uvicorn.org/settings/)
+- [Uvicorn programmatic startup](https://www.uvicorn.org/#running-programmatically)
+- [Pydantic settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)
+- [`functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache)
+- [uv project entry points](https://docs.astral.sh/uv/concepts/projects/config/#entry-points)
+- [PyPA entry points specification](https://packaging.python.org/en/latest/specifications/entry-points/)

docs/skills/nicegui/references/source-documentation.md

@@ -1,6 +1,16 @@
 # Source Documentation
 
-Use these links for framework-specific details.
+Use these links to verify framework-specific behavior before relying on version-sensitive or integration-specific guidance.
+
+## NiceGUI
+
+!!! info "NiceGUI sources"
+    - [Pages, routing, and FastAPI integration](https://www.nicegui.io/documentation/section_pages_routing)
+    - [`ui.run_with` implementation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui_run_with.py)
+    - [FastAPI integration example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py)
+    - [Binding properties and bindable dataclasses](https://www.nicegui.io/documentation/section_binding_properties)
+    - [Action events](https://www.nicegui.io/documentation/section_action_events)
+    - [Security best practices](https://www.nicegui.io/documentation/section_security)
 
 ## FastAPI
 
@@ -8,33 +18,53 @@ Use these links for framework-specific details.
     - [Lifespan events](https://fastapi.tiangolo.com/advanced/events/)
     - [Settings and environment variables](https://fastapi.tiangolo.com/advanced/settings/)
     - [Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/)
-    - [SQL databases tutorial](https://fastapi.tiangolo.com/tutorial/sql-databases/)
+    - [Server-sent events](https://fastapi.tiangolo.com/advanced/server-sent-events/)
+    - [WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
 
-## SQLAlchemy and Alembic
+## ASGI And Uvicorn
+
+!!! info "Server and lifespan sources"
+    - [ASGI lifespan protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
+    - [Uvicorn settings](https://www.uvicorn.org/settings/)
+    - [Uvicorn programmatic startup](https://www.uvicorn.org/#running-programmatically)
+    - [Uvicorn deployment](https://www.uvicorn.org/deployment/)
+
+## uv And Project Scripts
+
+!!! info "Packaging and command sources"
+    - [uv project entry points](https://docs.astral.sh/uv/concepts/projects/config/#entry-points)
+    - [uv project packaging](https://docs.astral.sh/uv/concepts/projects/config/#project-packaging)
+    - [PyPA entry points specification](https://packaging.python.org/en/latest/specifications/entry-points/)
+
+## Styling
+
+!!! info "Styling sources"
+    - [Tailwind utility-first styling](https://tailwindcss.com/docs/utility-first)
+    - [Tailwind responsive design and container queries](https://tailwindcss.com/docs/responsive-design)
+    - [Quasar components](https://quasar.dev/vue-components)
+    - [Quasar Screen plugin documentation source](https://github.com/quasarframework/quasar/blob/dev/docs/src/pages/options/screen-plugin.md)
+    - [CSS media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries)
+    - [CSS container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries)
+
+## Persistence
 
 !!! info "Persistence sources"
     - [SQLAlchemy engine configuration and pooling](https://docs.sqlalchemy.org/en/20/core/engines.html)
-    - [SQLAlchemy session lifecycle basics](https://docs.sqlalchemy.org/en/20/orm/session_basics.html)
+    - [SQLAlchemy session lifecycle](https://docs.sqlalchemy.org/en/20/orm/session_basics.html)
     - [Alembic tutorial](https://alembic.sqlalchemy.org/en/latest/tutorial.html)
 
-## Pydantic
+## Configuration And Dataclasses
 
-!!! info "Pydantic source"
-    - [Pydantic settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)
-
-## NiceGUI
-
-!!! info "NiceGUI sources"
-    - [Pages, routing, and FastAPI integration](https://www.nicegui.io/documentation/section_pages_routing)
-    - [Security best practices](https://www.nicegui.io/documentation/section_security)
+!!! info "Python and Pydantic sources"
+    - [Pydantic settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
+    - [Python dataclasses](https://docs.python.org/3/library/dataclasses.html)
+    - [PEP 557: Data Classes](https://peps.python.org/pep-0557/)
 
 ## LangGraph
 
 !!! info "LangGraph sources"
     - [Overview](https://docs.langchain.com/oss/python/langgraph/overview)
-    - [Quickstart](https://docs.langchain.com/oss/python/langgraph/quickstart)
     - [Workflows and agents](https://docs.langchain.com/oss/python/langgraph/workflows-agents)
     - [Persistence](https://docs.langchain.com/oss/python/langgraph/persistence)
-    - [Memory concepts](https://docs.langchain.com/oss/python/concepts/memory)
     - [Streaming](https://docs.langchain.com/oss/python/langgraph/streaming)
     - [Interrupts and human-in-the-loop](https://docs.langchain.com/oss/python/langgraph/interrupts)

docs/skills/pydantic-settings/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: pydantic-settings
+description: "Practical guide for implementing typed application configuration with pydantic-settings. Use when designing BaseSettings models, choosing nested or independent settings boundaries, managing settings lifecycles, configuring dotenv or secrets, and customizing source priority safely."
+x-personal-mcp:
+  id: pydantic-settings
+  version: 1.1.0
+  tags:
+    - python
+    - pydantic
+    - pydantic-settings
+    - configuration
+    - env-vars
+    - secrets
+    - dotenv
+    - source-priority
+    - caching
+    - lifecycle
+  capabilities:
+    - resource://skills/pydantic-settings/document
+---
+
+# Pydantic Settings Implementation Guide
+
+Use this skill to implement robust, typed application configuration with `pydantic-settings` in production Python services.
+
+## When to Use
+
+- You need a single typed configuration model for app settings.
+- You are migrating from ad-hoc `os.getenv(...)` calls.
+- You need predictable precedence across init args, env vars, dotenv files, and secrets.
+- You need nested settings models and reliable parsing behavior.
+- You need to choose between one nested application settings object and independently owned settings objects.
+- You need a deliberate construction, caching, or reload lifecycle.
+- You need to customize settings sources or source order safely.
+
+## Procedure
+
+### 1. Baseline Model
+
+Create a single settings model for the service boundary:
+
+```python
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DatabaseSettings(BaseModel):
+  host: str = "localhost"
+  port: int = 5432
+  user: str
+  password: str
+
+
+class Settings(BaseSettings):
+  model_config = SettingsConfigDict(
+    env_prefix="APP_",
+    env_file=".env",
+    env_file_encoding="utf-8",
+    extra="ignore",
+    frozen=True,
+  )
+
+  debug: bool = False
+  log_level: str = "info"
+  database: DatabaseSettings
+  api_key: str = Field(validation_alias="MY_API_KEY")
+```
+
+Quality gate:
+
+1. Required fields fail fast when missing.
+2. Defaults are intentional and safe.
+
+### 2. Pick Env Naming Rules
+
+1. Choose one prefix and apply it consistently.
+2. Use aliases only for compatibility or external contracts.
+3. Document whether env names are case-sensitive.
+
+Quality gate:
+
+1. Team can derive env variable names without guessing.
+2. Legacy names are supported only where needed.
+
+### 3. Decide Nested Parsing
+
+For nested models via env vars, configure delimiters intentionally:
+
+```python
+model_config = SettingsConfigDict(
+  env_prefix="APP_",
+  env_nested_delimiter="__",
+  env_nested_max_split=1,
+)
+```
+
+Typical vars:
+
+1. `APP_DATABASE={"host": "db", "port": 5432, "user": "svc", "password": "pw"}`
+2. `APP_DATABASE__HOST=db.internal`
+
+Quality gate:
+
+1. Nested overrides behave as expected.
+2. Delimiter choice does not collide with field names.
+
+### 4. Confirm Source Priority
+
+Default priority (higher first):
+
+1. CLI args (if enabled)
+2. init kwargs
+3. env vars
+4. dotenv
+5. secrets dir
+6. defaults
+
+Only customize when required:
+
+```python
+from pydantic_settings import PydanticBaseSettingsSource
+
+
+@classmethod
+def settings_customise_sources(
+  cls,
+  settings_cls: type[BaseSettings],
+  init_settings: PydanticBaseSettingsSource,
+  env_settings: PydanticBaseSettingsSource,
+  dotenv_settings: PydanticBaseSettingsSource,
+  file_secret_settings: PydanticBaseSettingsSource,
+) -> tuple[PydanticBaseSettingsSource, ...]:
+  return (init_settings, env_settings, dotenv_settings, file_secret_settings)
+```
+
+Quality gate:
+
+1. Priority order is explicit in code.
+2. Tests verify conflict resolution.
+
+### 5. Add Secrets Strategy
+
+1. In local development, dotenv is acceptable for non-production values.
+2. In deployed environments, prefer env vars or secret managers.
+3. For file-mounted secrets, use `secrets_dir`.
+
+Example:
+
+```python
+model_config = SettingsConfigDict(
+  env_prefix="APP_",
+  env_file=".env",
+  secrets_dir="/run/secrets",
+)
+```
+
+Quality gate:
+
+1. No secret literals in repository code.
+2. Missing secrets behavior is understood per environment.
+
+### 6. Choose Nested Or Independent Settings Boundaries
+
+Prefer one root `BaseSettings` object with nested `BaseModel` sections when the configuration belongs to one application lifecycle:
+
+```python
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DatabaseSettings(BaseModel):
+  host: str = "localhost"
+  port: int = 5432
+
+
+class ObservabilitySettings(BaseModel):
+  log_level: str = "INFO"
+  json_logs: bool = True
+
+
+class Settings(BaseSettings):
+  model_config = SettingsConfigDict(
+    env_prefix="APP_",
+    env_nested_delimiter="__",
+    frozen=True,
+  )
+
+  database: DatabaseSettings = Field(default_factory=DatabaseSettings)
+  observability: ObservabilitySettings = Field(
+    default_factory=ObservabilitySettings
+  )
+```
+
+This produces names such as `APP_DATABASE__HOST` and gives the application one validated, atomic configuration snapshot. Nested sections should normally inherit from `BaseModel`, not `BaseSettings`; otherwise each nested settings model can collect sources independently and produce surprising results.
+
+Use independent `BaseSettings` classes when the objects have genuinely independent ownership:
+
+1. Different packages or deployable components own the schemas.
+2. Each object needs its own env prefix or source policy.
+3. A component is optional or loaded lazily.
+4. Components need different reload lifecycles.
+5. The same component must run outside the application.
+
+Construct independent objects explicitly at the composition root and inject each dependency. Do not nest one `BaseSettings` class inside another merely to reuse its fields. Extract a shared `BaseModel` schema when models need common structure.
+
+Quality gate:
+
+1. Nested sections share one source policy and lifecycle.
+2. Independent settings have distinct owners, prefixes, or lifecycles.
+3. The application does not repeatedly scan the same sources through accidental nested `BaseSettings` construction.
+
+### 7. Own The Settings Lifecycle
+
+For most applications, construct settings once at the composition root and pass the validated object to services:
+
+```python
+def main() -> None:
+  settings = Settings()
+  application = Application(settings=settings)
+  application.run()
+```
+
+This makes ownership, startup failure, and test overrides explicit. Treat the object as a snapshot: environment variables and files changing later do not update an existing instance. Prefer `frozen=True` for shared settings so consumers cannot silently mutate process-wide configuration.
+
+Use [`functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache) only when process-lifetime singleton access is intentional and explicit injection is awkward, such as a framework dependency provider:
+
+```python
+from functools import cache
+
+
+@cache
+def get_settings() -> Settings:
+  return Settings()
+```
+
+Keep the cached factory argument-free. Passing override kwargs creates one cached instance per argument combination, retains those values for the process lifetime, and obscures which configuration is active. In tests, instantiate `Settings(...)` directly or override the dependency; when a test must exercise the cached getter, isolate environment changes with `get_settings.cache_clear()` before and after the assertion.
+
+`cache` is process-local. Every worker process gets its own instance, and concurrent first calls can construct more than one instance before the cache is populated. Settings construction must therefore be side-effect free; create engines, clients, and sessions in their own lifecycle-managed providers.
+
+Quality gate:
+
+1. Settings are created once per intended application or worker lifecycle.
+2. Cached factories are argument-free and side-effect free.
+3. Tests do not leak cached settings or environment changes.
+4. Resource construction is separate from configuration parsing.
+
+### 8. Reload Deliberately
+
+Static service configuration should normally require a process restart. If runtime reload is a real requirement, construct a fresh settings instance and atomically replace the owned reference. Do not call `__init__()` on a shared instance: readers can observe mutation in progress, and resources derived from old values may remain alive.
+
+Settings sources are synchronous. In an async application, construction or reload that reads dotenv, secrets, JSON, TOML, or YAML files should run in a worker thread:
+
+```python
+import asyncio
+
+
+async def load_settings() -> Settings:
+  return await asyncio.to_thread(Settings)
+```
+
+Clearing `get_settings` is sufficient for controlled tests or single-threaded administration, but it is not an atomic live-reload protocol. Concurrent applications should own the current reference behind an application-specific lock or lifecycle manager, swap in a fully validated replacement, and then rebuild dependent resources.
+
+Quality gate:
+
+1. Reload creates and validates a replacement before publication.
+2. Readers cannot observe a partially mutated object.
+3. Dependent resources are recreated after the settings reference changes.
+4. File-backed source reads do not block an async event loop.
+
+### 9. Add Focused Lifecycle Tests
+
+Do not add tests that re-validate baseline `pydantic-settings` functionality unless custom behavior is layered on top. Test the application-owned behavior instead:
+
+1. Repeated cached getter calls return the same instance.
+2. Cache clearing after an environment change returns a newly validated instance.
+3. Explicitly injected settings bypass global cached state.
+4. Reload swaps the settings snapshot and rebuilds dependent resources, when reload is supported.
+
+Suggested invocation:
+
+1. `uv run pytest -q`
+
+## Completion Checks
+
+1. Settings ownership matches the application or component lifecycle.
+2. Source precedence is documented and tested.
+3. Env naming conventions and aliases are explicit and stable.
+4. Nested parsing behavior is tested when custom parsing behavior is added.
+5. Secrets and dotenv usage are environment-appropriate and do not leak sensitive defaults.
+6. Validation errors are actionable and fail fast for required values.
+7. Cached factories are argument-free, process-local, and cleared deliberately in tests.
+8. Nested models share one source policy; independent settings have an explicit ownership reason.
+9. Runtime reload, if supported, replaces a validated snapshot and rebuilds dependent resources.
+
+## Output Contract
+
+When this skill is applied, return:
+
+1. Which references were consulted.
+2. The chosen source-precedence model and why.
+3. The exact parsing and alias decisions made.
+4. Any deferred choices and their risk.
+5. The validation commands or tests run to confirm behavior.
+
+Use these upstream docs when implementing or reviewing `pydantic-settings` behavior.
+
+## Source Docs
+
+### Primary
+
+- [Settings Management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)
+- [pydantic-settings package repository](https://github.com/pydantic/pydantic-settings)
+
+### Core Concepts
+
+- [Field aliases](https://pydantic.dev/docs/validation/latest/concepts/fields/#field-aliases)
+- [Alias choices](https://pydantic.dev/docs/validation/latest/concepts/alias#aliaspath-and-aliaschoices)
+- [Validation default behavior](https://pydantic.dev/docs/validation/latest/concepts/fields#validate-default-values)
+- [ImportString type](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.ImportString)
+
+### Priority And Sources
+
+- [Field value priority](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#field-value-priority)
+- [Customise settings sources](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#customise-settings-sources)
+- [Other settings source types](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#other-settings-source)
+
+### Environment And Parsing
+
+- [Environment variable names and prefix behavior](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#environment-variable-names)
+- [Case sensitivity behavior](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#case-sensitivity)
+- [Parsing environment variable values](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#parsing-environment-variable-values)
+- [Nested model default partial updates](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#nested-model-default-partial-updates)
+
+### Lifecycle And Reloading
+
+- [In-place reloading](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#in-place-reloading)
+- [Async environments](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#async-environments)
+- [`functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache)
+
+### Dotenv And Secrets
+
+- [Dotenv support](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support)
+- [Secrets](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#secrets)
+- [Nested secrets](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#nested-secrets)

docs/skills/pytest-scaffolding/SKILL.md

@@ -1,126 +0,0 @@
----
-name: pytest-scaffolding
-description: "Scaffold a maintainable, hierarchical pytest suite with fast defaults and clear escalation paths for FastAPI and SQLAlchemy tests. Use when creating or reorganizing tests, defining fixture/marker boundaries, or making test strategy progressively discoverable."
-argument-hint: "Target scope plus stack details (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed)"
-x-personal-mcp:
-  id: pytest-scaffolding
-  version: 1.0.0
-  tags:
-    - pytest
-    - testing
-    - python
-  capabilities:
-    - resource://skills/pytest-scaffolding/document
-  depends_on: []
----
-
-# Pytest Scaffolding
-
-Create test scaffolding that stays fast for daily work and scales safely as dependencies increase.
-
-This skill is optimized for progressive discoverability:
-1. Start with the shortest path in this file.
-2. Load exactly one deeper reference only when a decision requires it.
-3. Continue only as far as needed for the current task.
-
-Repository defaults:
-- `uv run pytest` is the canonical invocation.
-- pytest settings live in `pyproject.toml` under `[tool.pytest.ini_options]`.
-- strict marker checking is expected (`--strict-markers`).
-
-## Discovery Ladder
-
-### Level 0: Scope And Stack Triage (always)
-Collect:
-1. Target scope (repo, package, module).
-2. Stack shape (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed).
-3. Speed target (what must stay instant).
-4. CI gate policy (which marker groups block merge).
-
-If any are missing, ask concise clarifying questions before scaffolding.
-
-### Level 1: Core pytest scaffold (default)
-Use this for all stacks first:
-1. Mirror `src/` into `tests/` with one starter file per core module.
-2. Classify test intent by cost:
-	- `unit`: no DB/network/filesystem side effects.
-	- `integration`: framework, DB, or multi-layer contracts.
-	- `smoke`: thin critical-path checks.
-3. Scaffold each new module with:
-	- one happy-path test,
-	- one failure/edge test,
-	- TODO anchors for deeper assertions.
-4. Keep fixtures layered:
-	- global lightweight fixtures in `tests/conftest.py`,
-	- domain fixtures in subtree `conftest.py` only when needed.
-5. Register markers early: `unit`, `integration`, `smoke`, `slow`, `external`.
-6. Validate in order:
-	- `uv run pytest --collect-only -q`
-	- `uv run pytest -m unit -q`
-	- `uv run pytest -q` when dependencies are available.
-
-Load next reference only if needed:
-- Baseline details and rationale: [pytest-docs.md](./references/pytest-docs.md)
-
-### Level 2: FastAPI branch (only for HTTP/dependency/lifespan concerns)
-Escalate here when testing API routes, dependency injection boundaries, or app lifespan behavior.
-
-Apply these defaults:
-1. Prefer `TestClient` with sync `def` tests for route behavior.
-2. Use `AsyncClient` + `@pytest.mark.anyio` only when test logic must await other async work.
-3. Prefer `app.dependency_overrides` over patching internals.
-4. Reset dependency overrides in teardown after every test/fixture.
-5. For startup/shutdown semantics:
-	- use `TestClient` as context manager, or
-	- use `LifespanManager` with async client.
-
-Marker intent in FastAPI-heavy suites:
-- `unit`: service logic without HTTP/DB.
-- `integration`: route + DI + DB contract checks.
-- `smoke`: one request per critical user path.
-
-Reference: [fastapi-testing.md](./references/fastapi-testing.md)
-
-### Level 3: SQLAlchemy branch (only for DB transaction/session design)
-Escalate here when session lifecycle, transaction isolation, or async ORM behavior matters.
-
-Apply these defaults:
-1. Create engine once per test session.
-2. Open connection + outer transaction per test.
-3. Bind session with `join_transaction_mode="create_savepoint"`.
-4. Allow code under test to call `commit()` safely; rollback outer transaction at test end.
-5. Keep unit tests DB-free; DB tests belong under `integration`.
-
-Async additions:
-- use async fixtures and `@pytest.mark.anyio`.
-- set `expire_on_commit=False` for `AsyncSession`.
-- avoid implicit lazy IO; use eager loading (`selectinload`) or explicit refresh.
-
-SQLite in-memory with threaded test clients:
-- use `StaticPool` when required by thread/connection sharing.
-
-Reference: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
-
-## Branching Logic Summary
-- If pure logic can be faked cleanly, keep in `unit`.
-- If framework/DB contract is the behavior under test, use `integration`.
-- If external service credentials/network is required, gate behind `external`.
-- If suite slows down, split by marker before broadening fixture scope.
-- If async relationship access raises `MissingGreenlet`, switch to eager loading strategy.
-
-## Completion Checks
-A scaffold pass is complete when all are true:
-1. Core source areas map to clear test modules.
-2. Fast path (`-m unit`) is deterministic and quick.
-3. Integration and external paths are isolated by fixtures and markers.
-4. No unregistered-marker failures occur.
-5. Structure is understandable without extra oral context.
-6. Clear TODO extension points exist for deeper assertions.
-
-## Output Contract
-When this skill is applied, return:
-1. Proposed test tree diff.
-2. Marker and fixture plan.
-3. Exact fast-path and full-path commands.
-4. Which reference level was loaded and why.
-5. Risks or open questions before expanding assertions.

docs/skills/pytesting/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: pytesting
+description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Optimized for progressive discovery so naming and hierarchy guidance are loaded first when shaping or reorganizing tests."
+x-personal-mcp:
+  id: pytesting
+  version: 1.0.0
+  tags:
+    - pytest
+    - testing
+    - python
+    - fastapi
+    - asyncio
+    - anyio
+    - deterministic
+  capabilities:
+    - resource://skills/pytesting/document
+---
+
+# Pytesting
+
+This skill is a collection of preferences and links to source documentation for building and maintaining pytest suites.
+
+Use it to quickly find the right guidance for:
+1. Baseline pytest structure and marker strategy.
+2. Naming conventions and test hierarchy organization.
+3. FastAPI route, dependency override, and lifespan testing patterns.
+4. SQLAlchemy transaction and session testing patterns.
+5. AsyncIO loop-scope, fixture-lifecycle, and cancellation-safe testing patterns.
+
+Repository defaults:
+- `uv run pytest` is the canonical invocation.
+- pytest settings live in `pyproject.toml` under `[tool.pytest.ini_options]`.
+- strict marker checking is expected (`--strict-markers`).
+
+## Progressive Discovery Start
+
+Use this load order by default so guidance stays targeted and naming conventions are pulled in early:
+
+1. Classify intent first: naming and organization, baseline pytest mechanics, FastAPI testing, SQLAlchemy testing, or mixed.
+2. For create/restructure/rename tasks, load [naming-and-organization.md](./references/naming-and-organization.md) first.
+3. Load [pytest-docs.md](./references/pytest-docs.md) next for fixture and marker defaults.
+4. Load at most one stack-specific reference unless the request is explicitly mixed stack.
+5. If confidence is low after two references, ask one clarifying question before loading more.
+
+Load budget defaults:
+
+1. Single-stack task: 1 to 2 references.
+2. Mixed-stack task: up to 3 references.
+3. Avoid loading all references unless the user explicitly asks for a broad audit.
+
+## Intent Router
+
+Open only the reference that matches the immediate task.
+
+1. Naming, file layout, discovery prefixes, class/function naming: [naming-and-organization.md](./references/naming-and-organization.md)
+2. Fixture layering, marker policy, collect-only and fast-path commands: [pytest-docs.md](./references/pytest-docs.md)
+3. Route tests, dependency overrides, lifespan handling: [fastapi-testing.md](./references/fastapi-testing.md)
+4. Session and transaction fixtures, async ORM behavior: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
+5. Async test mode selection, event loop scope, cancel-scope teardown issues: [asyncio-testing.md](./references/asyncio-testing.md)
+
+## Naming Pull-In Triggers
+
+Always consult [naming-and-organization.md](./references/naming-and-organization.md) before recommending structure when any of these are true:
+
+1. New tests are being added.
+2. Existing tests are being reorganized or renamed.
+3. The request mentions conventions, readability, hierarchy, or discoverability.
+4. The task introduces parametrization where case naming affects failure readability.
+
+## Guiding Principles
+
+These principles are abstract, but are the highest priority to follow.
+
+- Much of testing is very well-trodden. In general, tests should follow whatever conventions there are.
+- Tests will be run very frequently, so it's important that they run quickly and deterministically.
+- When tests fail, it should be easy to determine what failed and fix it.
+- Always be on guard against tests that are tautological. Every test should provide specific value by capturing something about the intent of the program.
+
+## Pytest Best Practices
+
+These are stable defaults regardless of stack:
+
+1. Apply pytest naming and hierarchy conventions first so discovery and ownership stay predictable; see [naming-and-organization.md](./references/naming-and-organization.md).
+2. Mirror `src/` into `tests/` so ownership and coverage are obvious.
+3. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
+4. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
+5. Separate fast feedback (`-m unit`) from broader integration/external lanes.
+6. Validate structure early with collection checks before expanding assertions.
+7. Keep test scope tight and count intentional; add tests only when each case protects a distinct behavior.
+8. Start with the single core-intent behavior path, then add edge cases based on real risk.
+9. Prefer parametrized tests for behavior variants instead of cloning near-identical test functions.
+10. Reject low-signal assertions (for example `assert True` patterns) and avoid tests that only assert a mock was called.
+11. Prefer behavior-first tests that exercise real code paths and concrete inputs over patching internals.
+12. Use monkeypatching, mocks, and fakes extremely sparingly, only when no practical real-input alternative exists, and only after explicit user confirmation.
+
+## Universal Test Double Policy (Repo-Local Placement)
+
+To avoid over-using monkeypatching, mocks, fakes, etc, apply this policy whenever a test change introduces one of them:
+
+1. Attempt a real-input, real-object test design first.
+2. If that approach is impractical, explain why and request user confirmation before adding monkeypatching, mocks, or fakes.
+3. Keep any approved test double narrowly scoped and document the exact boundary it replaces.
+4. Do not treat call-only verification as sufficient; pair any test double with assertions on observable behavior or outputs.
+5. Revisit approved test doubles when implementation seams improve so they can be removed.
+
+## Stack-Specific Guidance
+
+- For FastAPI, prefer dependency overrides and clear lifecycle handling; see [fastapi-testing.md](./references/fastapi-testing.md).
+- For SQLAlchemy, prefer transaction-safe session fixtures and explicit async loading strategy; see [sqlalchemy-testing.md](./references/sqlalchemy-testing.md).
+- For async fixtures, loop-scope selection, and cancellation-safe teardown, see [asyncio-testing.md](./references/asyncio-testing.md).
+- For naming and tree organization, use the conventions in [naming-and-organization.md](./references/naming-and-organization.md).
+
+## Source Documentation Entry Points
+
+Primary upstream docs are curated in each reference page. Start with:
+
+1. Pytest good practices: [pytest docs](https://docs.pytest.org/en/stable/explanation/goodpractices.html)
+2. Pytest fixtures: [fixture how-to](https://docs.pytest.org/en/stable/how-to/fixtures.html)
+3. Pytest markers: [marker examples](https://docs.pytest.org/en/stable/example/markers.html)
+4. FastAPI testing: [FastAPI testing tutorial](https://fastapi.tiangolo.com/tutorial/testing/)
+5. SQLAlchemy transaction testing: [SQLAlchemy external transaction pattern](https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#joining-a-session-into-an-external-transaction-such-as-for-test-suites)
+6. Pytest monkeypatch usage and limits: [monkeypatch how-to](https://docs.pytest.org/en/stable/how-to/monkeypatch.html)
+7. pytest-asyncio configuration: [pytest-asyncio config](https://pytest-asyncio.readthedocs.io/en/stable/reference/configuration.html)
+8. AnyIO cancellation semantics: [AnyIO cancellation and timeouts](https://anyio.readthedocs.io/en/stable/cancellation.html)
+
+## Quick Validation Commands
+
+Use these commands to check structure and execution lanes:
+
+1. `uv run pytest --collect-only -q`
+2. `uv run pytest -m unit -q`
+3. `uv run pytest -m "not external" -q`
+4. `uv run pytest -q`
+
+## Output Contract
+When this skill is applied, return:
+1. Which references were consulted.
+2. The discovery path used (intent classification, load order, and why).
+3. Recommended structure, naming, fixture, and marker decisions.
+4. Concrete naming outcomes: file/module naming pattern, class usage decision, and any parametrization `ids` conventions.
+5. Exact validation commands.
+6. Relevant source-doc links for any non-trivial recommendation.
+7. Risks, assumptions, or open questions.
+8. Explicit confirmation status if monkeypatching, mocks, or fakes were requested or used.

docs/skills/pytesting/references/asyncio-testing.md

@@ -0,0 +1,108 @@
+# AsyncIO Testing Patterns (Pytest, FastAPI, AnyIO)
+
+!!! info "Primary sources"
+    - [pytest-asyncio configuration](https://pytest-asyncio.readthedocs.io/en/stable/reference/configuration.html)
+    - [pytest-asyncio concepts](https://pytest-asyncio.readthedocs.io/en/stable/concepts.html)
+    - [pytest-asyncio fixture loop scope how-to](https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/change_fixture_loop.html)
+    - [pytest-asyncio default fixture loop scope how-to](https://pytest-asyncio.readthedocs.io/en/stable/how-to-guides/change_default_fixture_loop.html)
+    - [AnyIO cancellation and cancel-scope safety](https://anyio.readthedocs.io/en/stable/cancellation.html)
+    - [FastAPI async tests](https://fastapi.tiangolo.com/advanced/async-tests/)
+
+## Agent Quick Path
+Use this reference when tests involve asynchronous fixtures, HTTP clients, task groups, or teardown failures.
+
+1. Confirm async plugin mode in pytest config (`asyncio_mode`).
+2. Keep async fixture loop scope predictable, defaulting to `function` unless there is a measured need to broaden it.
+3. Prefer one async testing model per lane (pytest-asyncio or AnyIO-style markers), and keep it consistent.
+4. Keep async fixtures small and isolate stateful resources to the narrowest useful scope.
+5. If teardown errors mention cancel scopes or task groups, validate that setup and teardown run in the same task context.
+
+## Baseline Configuration
+
+Recommended defaults for most projects using `pytest-asyncio`:
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+```
+
+Why:
+- [Strict mode](https://pytest-asyncio.readthedocs.io/en/stable/concepts.html#test-discovery-modes) is safer for multi-plugin environments, but [auto mode](https://pytest-asyncio.readthedocs.io/en/stable/concepts.html#test-discovery-modes) is often simpler when the suite is primarily asyncio-based.
+- [Function loop scope](https://pytest-asyncio.readthedocs.io/en/stable/reference/configuration.html#asyncio-default-fixture-loop-scope) minimizes cross-test coupling and avoids many lifecycle surprises.
+
+If a fixture or test needs broader loop sharing, make it explicit instead of changing suite-wide defaults:
+
+```python
+import pytest
+import pytest_asyncio
+
+
+@pytest_asyncio.fixture(loop_scope="module")
+async def shared_resource():
+    ...
+
+
+@pytest.mark.asyncio(loop_scope="module")
+async def test_uses_shared_loop(shared_resource):
+    ...
+```
+
+## FastAPI Endpoint Test Patterns
+
+Use [FastAPI's async testing guidance](https://fastapi.tiangolo.com/advanced/async-tests/) as the default:
+
+1. Use `httpx.AsyncClient` with `ASGITransport` for async endpoint tests.
+2. Mark async tests with one consistent marker style for the suite.
+3. If app lifespan hooks matter, add [LifespanManager](https://fastapi.tiangolo.com/advanced/async-tests/#httpx) support because `AsyncClient` alone does not trigger lifespan events.
+
+Example:
+
+```python
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+
+@pytest.mark.asyncio
+async def test_healthz(app):
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        response = await client.get("/healthz")
+
+    assert response.status_code == 200
+```
+
+## Fixture Design For Async Reliability
+
+Apply these patterns first:
+
+1. Keep async fixtures narrow (`function` scope by default).
+2. Keep one responsibility per fixture when possible.
+3. Prefer yield fixtures and pair each setup step with teardown in the same fixture.
+4. Avoid mixing many independent event-loop lifecycles in one fixture chain.
+
+When using transports that manage internal task groups (for example, streaming clients), avoid patterns that risk splitting lifecycle across different task contexts.
+
+## Troubleshooting Cancel-Scope Teardown Failures
+
+When you see errors like `Attempted to exit cancel scope in a different task than it was entered in`, treat it as an async lifecycle-ownership issue first.
+
+Checklist:
+
+1. Verify fixture and test loop scopes are compatible and explicit.
+2. Confirm async resource setup and teardown are owned by the same fixture context.
+3. Reduce fixture scope (`module` or `session` -> `function`) to test for loop/task ownership drift.
+4. Ensure the suite uses one primary async plugin model for the failing lane.
+5. Re-run with focused selection and skip reasons to isolate first failing fixture:
+   - `uv run --group test python -m pytest -m smoke tests/web -q -rs`
+
+Relevant references:
+- [Avoiding cancel scope stack corruption](https://anyio.readthedocs.io/en/stable/cancellation.html#avoiding-cancel-scope-stack-corruption)
+- [pytest-asyncio configuration](https://pytest-asyncio.readthedocs.io/en/stable/reference/configuration.html)
+- [pytest fixture teardown behavior](https://docs.pytest.org/en/stable/how-to/fixtures.html#teardown-cleanup-aka-fixture-finalization)
+
+## Commands Worth Remembering
+
+- `uv run --group test python -m pytest --collect-only -q`
+- `uv run --group test python -m pytest -m smoke tests/web -q -rs`
+- `uv run --group test python -m pytest -m integration -q`
+- `uv run --group test python -m pytest -q`

docs/skills/pytesting/references/naming-and-organization.md

@@ -0,0 +1,118 @@
+# Pytest Naming Conventions and Test Organization
+
+!!! info "Primary sources"
+    - [Good integration practices](https://docs.pytest.org/en/stable/explanation/goodpractices.html)
+    - [Changing standard (Python) test discovery](https://docs.pytest.org/en/stable/example/pythoncollection.html)
+    - [How to use fixtures](https://docs.pytest.org/en/stable/how-to/fixtures.html)
+    - [How to parametrize fixtures and test functions](https://docs.pytest.org/en/stable/how-to/parametrize.html)
+    - [Marker examples](https://docs.pytest.org/en/stable/example/markers.html)
+
+## Agent Quick Path
+Use this when creating or reorganizing test modules so naming and hierarchy stay predictable.
+
+1. Mirror the product domain structure in `tests/` so ownership is obvious.
+2. Encode broad context in module and class names (`test_*.py`, `Test*`).
+3. Keep leaf test names short and behavior-focused (`test_*`).
+4. Use `class Test<Subject>:` only for grouping related scenarios.
+5. Place fixtures in the nearest `conftest.py` needed by scope.
+6. Separate expensive tests with markers first, directories second.
+
+## Naming Conventions
+
+### File and directory naming
+- Use lowercase snake_case for test file names: `test_user_service.py`.
+- Keep directories domain-oriented and stable over time: `tests/orders/`, `tests/billing/`.
+- Prefer descriptive test names over internal ticket numbers or implementation details.
+
+### Test function naming
+- Prefer hierarchical naming: put broad context in folder/module/class, and keep the function name focused on the final assertion.
+- Keep pytest discovery prefixes intact:
+  - modules start with `test_`
+  - classes start with `Test`
+  - functions start with `test_`
+- Start with user-visible behavior or contract, not private helper names.
+
+Recommended pattern:
+- module: `test_<subject>.py`
+- class: `Test<Operation>` or `Test<Scenario>`
+- function: `test_<expected_outcome>`
+
+Examples:
+- Flat (still valid): `test_create_order_rejects_invalid_currency`
+- Class-context: `TestOrder -> TestCreate -> test_rejects_invalid_currency`
+- Module-context: `test_order.py -> TestCreate -> test_rejects_invalid_currency`
+- Module + class context can similarly shorten:
+  - `test_token.py -> TestRefresh -> test_rotates_session_id`
+  - `test_user_list.py -> TestListUsers -> test_returns_empty_for_new_tenant`
+
+### Test class naming
+- Use `class Test<SubjectOrScenario>:` for scenario grouping and context reduction.
+- Keep class names noun-focused (`TestOrderService`) rather than action-focused.
+- Avoid xUnit style setup inheritance when fixtures can express dependencies directly.
+
+## Hierarchy and Organization Patterns
+
+Two patterns work well; choose one and apply it consistently.
+
+### Pattern A: Source-mirror hierarchy (default for product code ownership)
+
+```text
+src/
+  app/
+    orders/service.py
+    billing/invoice.py
+
+tests/
+  app/
+    orders/test_service.py
+    billing/test_invoice.py
+```
+
+Use this when teams own modules by source path and want direct test-to-source mapping.
+
+### Pattern B: Cost-lane hierarchy (default for CI policy clarity)
+
+```text
+tests/
+  unit/
+    orders/test_service.py
+  integration/
+    api/test_orders.py
+    persistence/test_order_repository.py
+  smoke/
+    test_health.py
+```
+
+Use this when CI gating is based on cost lanes and marker filtering.
+
+### Hybrid rule (recommended)
+- Keep a source-mirror tree for local ownership.
+- Add markers (`unit`, `integration`, `smoke`, `external`) for runtime policy.
+- Avoid duplicating both trees unless the repository already requires it.
+
+## Fixture Placement Strategy
+- Put universal lightweight fixtures in `tests/conftest.py`.
+- Put domain fixtures in subtree `conftest.py` files close to where they are used.
+- Keep fixtures composable and explicit; avoid large fixture "god objects".
+- Use `yield` fixtures for teardown so cleanup is always paired with setup.
+
+## Parametrize and ID Naming
+- Use `pytest.mark.parametrize` for behavior matrices instead of copy/paste tests.
+- Provide explicit `ids=` labels when case names are not obvious.
+- Keep IDs business-meaningful (`"expired-token"`, `"zero-balance"`) so failures are readable.
+
+## Collection and Structure Checks
+Use these checks after introducing new test files or renaming modules:
+
+- `uv run pytest --collect-only -q`
+- `uv run pytest -m unit -q`
+- `uv run pytest -m "not external" -q`
+
+If collection surprises appear, verify file names, marker registration, and directory placement first.
+
+## Common Anti-Patterns
+- Mixed naming styles (`testFoo.py`, `test_foo.py`, `foo_test.py`) in one repository.
+- Deep fixture chains that hide setup behavior.
+- Test names that encode implementation details instead of behavior.
+- Moving slow tests into `unit` directories without marker updates.
+- Sharing mutable module-level state across tests.

docs/skills/pytesting/references/pytest-docs.md

@@ -19,6 +19,7 @@ Use this file when you need fast pytest scaffolding defaults without framework-s
 Load other references only when needed:
 - FastAPI routes/dependency injection/lifespan: `fastapi-testing.md`
 - SQLAlchemy sessions/transactions/DB fixtures: `sqlalchemy-testing.md`
+- Naming conventions and test hierarchy: `naming-and-organization.md`
 
 ## Practical Guidance For This Skill
 - Use src-aligned test layout and keep test discovery conventional.

docs/skills/python-logging-dictconfig/SKILL.md

@@ -1,117 +0,0 @@
----
-name: python-logging-dictconfig
-description: 'Set up idiomatic Python logging with logging.config.dictConfig. Use when creating or refactoring logging setup, standardizing handlers/formatters, and enforcing centralized config.'
-argument-hint: 'Target context (single script, package, FastAPI app, or CLI) and desired log destinations'
-x-personal-mcp:
-    id: python-logging-dictconfig
-    version: 1.0.0
-    tags:
-        - logging
-        - python
-        - observability
-    capabilities:
-        - resource://skills/python-logging-dictconfig/document
-    depends_on: []
----
-
-# Idiomatic Python Logging with dictConfig
-
-Use this skill to produce a minimal, centralized logging setup using `logging.config.dictConfig`.
-
-Load references only when needed:
-- Python logging overview and hierarchy: [Python logging references](./references/python-logging-docs.md)
-
-## When to Use
-
-- A project configures logging ad hoc with `basicConfig` across multiple modules.
-- You need one canonical logging configuration for app startup.
-- You need consistent formatting and levels across console/file handlers.
-- You want library modules to use named loggers without configuring logging themselves.
-
-## Inputs To Collect
-
-1. Runtime type: script, library, web app, worker, CLI.
-2. Destinations: stdout only, file only, or both.
-3. Desired default level: `INFO`, `DEBUG`, etc.
-4. Whether third-party loggers should be tuned (for example `uvicorn`, `sqlalchemy`).
-
-If missing, assume:
-- stdout handler
-- human-readable formatter
-- root level `INFO`
-- `disable_existing_loggers: False`
-
-## Procedure
-
-1. Define a single `LOGGING` dictionary in one startup-oriented module (for example `logging_config.py`).
-2. Include `version: 1` and set `disable_existing_loggers: False` unless there is a specific reason to silence existing loggers.
-3. Define formatters first, then handlers, then logger routing (`root` and optional named `loggers`).
-4. Use `logging.config.dictConfig(LOGGING)` exactly once during application startup.
-5. In all modules, get loggers via `logger = logging.getLogger(__name__)` and never call `basicConfig`.
-6. Keep libraries configuration-free: libraries should emit logs, applications decide routing.
-7. Verify behavior with a quick smoke check at multiple levels (`DEBUG`, `INFO`, `WARNING`, `ERROR`).
-
-## Minimal Baseline Templates
-
-### Configuration
-
-!!! warning "Don't use the name `logging.py` because it will conflict
-
-```python title="logging_config.py"
-import logging.config
-
-LOGGING = {
-    "version": 1,
-    "disable_existing_loggers": False,
-    "formatters": {
-        "basic": {
-            "format": "%(asctime)s.%(msecs)03d [%(levelname)s] %(message)s",
-            "datefmt": "%Y-%m-%d %H:%M:%S",
-        }
-    },
-    "handlers": {
-        "console": {
-            "class": "logging.StreamHandler",
-            "formatter": "basic",
-            "stream": "ext://sys.stdout",
-        }
-    },
-    "root": {
-        "level": "INFO",
-        "handlers": ["console"],
-    },
-}
-
-def configure_logging() -> None:
-    logging.config.dictConfig(LOGGING)
-```
-
-```python title="app.py"
-# app startup
-from .logging_config import configure_logging
-
-configure_logging()
-```
-
-### Usage
-
-The preferred way of instantiating loggers is at the top of modules like this:
-
-```python
-import logging
-
-logger = logging.getLogger(__name__)
-```
-
-## Completion Checks
-1. `dictConfig` is called once at startup, not per module.
-2. No `basicConfig` calls remain.
-3. Modules use `getLogger(__name__)`.
-4. Logs appear at expected level and destination.
-5. Third-party logger noise is intentionally configured or left at defaults.
-6. No module named `logging.py` in the project.
-
-## Branching Guidance
-- If structured logs are required: switch formatter output to JSON while keeping `dictConfig` topology unchanged.
-- If both console and file output are needed: add a file handler and attach it to `root`.
-- If a specific framework logger is too noisy: add a named logger override under `loggers`.

docs/skills/python-logging/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: python-logging
+description: 'Design, review, or refactor Python logging. Use when choosing logger names, levels, handlers, library/application boundaries, basicConfig, dictConfig, structured logs, or operational logging defaults.'
+x-personal-mcp:
+    id: python-logging
+    version: 1.0.0
+    tags:
+        - logging
+        - python
+        - observability
+    capabilities:
+        - resource://skills/python-logging/document
+---
+
+# Python Logging
+
+Use this skill to produce idiomatic Python logging guidance or a small logging setup for an application, library, CLI, worker, or web service.
+
+Load references only when needed:
+
+[Python logging references](./references/python-logging-docs.md)
+: Python logging overview, library guidance, handlers, and dictConfig schema
+
+[JSON file logging pattern](./references/json-file-logging.md)
+: Queue-backed rotating JSON file pattern for local machine-readable logs
+
+[Network logging minimal example](./references/network-logging-minimal-example.md)
+: Minimal network logging example with a receiver and queue-backed client
+
+[HTTPX logging handler example](./references/httpx-logging-handler-example.md)
+: HTTP JSON logging example with `httpx` and a queue-backed client
+
+## When to Use
+
+- A project mixes `print`, root logger calls, scattered `basicConfig`, or ad hoc handlers.
+- You need to choose logging levels, destinations, formatter fields, or logger names.
+- You need a clear boundary between library logging and application logging configuration.
+- You need a centralized logging setup, including a `logging.config.dictConfig` section.
+- You are tuning framework or third-party loggers such as `uvicorn`, `sqlalchemy`, or HTTP clients.
+
+## Inputs To Collect
+
+1. Runtime type: script, library, CLI, web app, worker, service, or notebook.
+2. Audience: humans in a terminal, operators in files, machines in JSON, or test assertions.
+3. Destinations: stdout/stderr, file, rotating file, queue, syslog, external collector, or none for libraries.
+4. Default level and verbosity controls: `INFO`, `DEBUG`, CLI flag, environment variable, or config file.
+5. Operational constraints: async event loop, multiprocessing, container logs, sensitive data, or high-volume paths.
+
+If missing, assume:
+- application code, not a reusable library
+- stdout console logging
+- human-readable formatter
+- root level `INFO`
+- no file logging unless requested
+
+## Procedure
+
+1. Classify the project boundary first: application code configures logging; library code emits logs and avoids configuring handlers.
+2. In modules, create loggers with `logger = logging.getLogger(__name__)` so logger names follow the package hierarchy.
+3. Use level semantics consistently: `DEBUG` for diagnosis, `INFO` for normal milestones, `WARNING` for notable recoverable conditions, `ERROR` for failed operations, and `CRITICAL` for process-threatening failures.
+4. Prefer parameterized logging calls such as `logger.info("Processed %s items", count)` so message formatting is deferred until the record is emitted.
+5. Configure handlers and formatters once during application startup.
+6. Keep third-party logger overrides explicit and narrow. Tune noisy loggers by name instead of muting broad logger hierarchies.
+7. Smoke-check output at expected levels and destinations, including one suppressed `DEBUG` message and one exception path if errors are logged.
+
+## Best Practices
+
+- Do not name a module `logging.py`; it shadows the standard library package.
+- Do not call `basicConfig` or attach handlers in every module.
+- Do not log to the root logger from libraries. Use named loggers and, only if needed, attach `logging.NullHandler()` to the library's top-level logger.
+- Do not create loggers per request, user, file, or connection. Use contextual fields, adapters, or filters instead.
+- Use `logger.exception(...)` only inside an exception handler when the traceback is useful.
+- For async or high-throughput code, avoid slow network or file handlers on the hot path; consider `QueueHandler` and a listener.
+- Avoid custom levels unless there is a strong interoperability reason.
+
+## Examples
+
+### `logging.basicConfig`
+
+```python title="Bare minimum"
+import logging
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+logging.info("Hello, world!")
+```
+
+```python title="With a little formatting"
+import logging
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s.%(msecs)03d %(levelname)-8s %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logging.info("Hello, world!")
+```
+
+### `logging.config.dictConfig`
+
+```python title="Minimal dictConfig example"
+import logging
+import logging.config
+
+logging.config.dictConfig(
+    {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "console": {
+                "format": "%(asctime)s.%(msecs)03d %(levelname)-8s %(message)s",
+                "datefmt": "%Y-%m-%dT%H:%M:%S",
+            }
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "formatter": "console",
+            }
+        },
+        "root": {"level": "INFO", "handlers": ["console"]},
+    }
+)
+
+logging.info("Hello world")
+```
+
+### Config Composition
+
+Example function suitable for merging dicts for `dictConfig`
+
+```python title="composed config"
+from collections.abc import Iterable
+from collections.abc import Mapping
+from collections.abc import Sequence
+from copy import copy
+from functools import reduce
+
+
+BASE = ...
+CONSOLE = ...
+JSON_FILE = ...
+RICH = ...
+
+
+def merge(a: Mapping, b: Mapping) -> Mapping:
+    """Recursively merge config dicts"""
+    a = dict(a)
+    for k, v in b.items():
+        match a.get(k), v:
+            case Mapping() as inner, Mapping():
+                a[k] = merge(inner, v)
+            case Sequence() as inner, Iterable():
+                new = list(copy(inner))
+                a[k] = new + [sub_v for sub_v in v if sub_v not in new]
+            case _:
+                a[k] = v
+    return a
+
+
+def configure_logging(
+    base_config: dict | None = None,
+    *,
+    enable_console: bool = True,
+    enable_file: bool = True,
+    enable_rich: bool = True,
+) -> dict:
+    """Configure logging using the merged configuration."""
+    configs = [base_config or BASE]
+    if enable_console:
+        configs.append(CONSOLE)
+    if enable_file:
+        configs.append(JSON_FILE)
+    if enable_rich:
+        configs.append(RICH)
+    final_config = dict(reduce(merge, configs))
+    logging.config.dictConfig(final_config)
+    return final_config
+```
+
+## Using dictConfig
+
+Use `logging.config.dictConfig` when configuration should be centralized, data-driven, or richer than `basicConfig`.
+
+1. Define one `LOGGING` dictionary in a startup-oriented module such as `logging_config.py`.
+2. Include `version: 1` and usually set `disable_existing_loggers: False` so existing named loggers are not silently disabled.
+3. Define formatters, then handlers, then logger routing with `root` and optional named `loggers`.
+4. Call `logging.config.dictConfig(LOGGING)` once during application startup.
+5. Keep application logging calls unchanged when adding new destinations or formats.
+
+## Application Usage
+
+Concrete examples of how logging should be configured and used.
+
+!!! warning "It's important to avoid the obvious name of `logging.py` to avoid weird clashes with IDEs and python internals."
+
+=== "dictConfig"
+
+    ```python title="logging_config.py"
+    import logging.config
+
+    LOGGING = ...
+
+    def configure_logging() -> None:
+        logging.config.dictConfig(LOGGING)
+    ```
+
+=== "basicConfig"
+
+    ```python title="logging_config.py"
+    import logging.config
+
+    LOGGING = ...
+
+    def configure_logging() -> None:
+        logging.basicConfig(**LOGGING)
+    ```
+
+```python title="app.py"
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def run(count: int) -> None:
+    logger.info("Processing %s items", count)
+```
+
+```python title="main.py"
+from app import run
+from logging_config import configure_logging
+
+configure_logging()
+run(5)
+```
+
+## Branching Guidance
+
+- If the code is a tiny script: use `basicConfig` once near the entry point and module loggers elsewhere.
+- If the code is a library: remove handlers and configuration calls; document logger names and optionally add `NullHandler` at the package root.
+- If structured logs are required: keep the same logger and handler topology, but switch formatter output to JSON or a structured formatter.
+- If console and file output are needed: add one file or rotating-file handler and attach it centrally. For a queue-backed JSON file setup, use the [JSON file logging pattern](./references/json-file-logging.md).
+- If multiple processes write to one file: use a queue/listener or process-safe collection path rather than opening the same file independently in each process.
+- If logs must cross a network: send records to a receiver or collector from a queue-backed handler, keep the receiver responsible for final destinations, and avoid exposing unauthenticated logging ports.
+- If a framework logger is noisy: add a named logger override with a level and leave unrelated logger propagation alone.
+
+## Completion Checks
+
+1. Modules use `logging.getLogger(__name__)`.
+2. Application startup configures logging once.
+3. Libraries do not configure application handlers.
+4. Levels match the severity semantics in this skill.
+5. Logs include enough context to identify source, severity, and event without leaking secrets.
+6. Expected destinations receive messages and suppressed levels stay quiet.
+7. No source file or package is named `logging.py`.

docs/skills/python-logging/references/httpx-logging-handler-example.md

@@ -0,0 +1,131 @@
+# HTTPX Logging Handler Example
+
+Use this reference when an application should emit JSON logs to an HTTP collector while keeping startup logging configuration declarative.
+
+This page follows the top-level skill pattern:
+
+- define one `LOGGING` dictionary
+- apply it once with `logging.config.dictConfig(LOGGING)`
+- keep modules focused on logger calls
+
+Source docs to keep nearby:
+
+- [HTTPX clients](https://www.python-httpx.org/advanced/clients/)
+- [HTTPX timeouts](https://www.python-httpx.org/advanced/timeouts/)
+- [`logging.config.dictConfig`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig)
+
+## Minimal Topology
+
+```text
+application code -> named logger -> HttpxJsonLogHandler -> HTTP collector
+```
+
+## Reusable Handler Type
+
+Keep transport behavior in one handler class and wire it declaratively through `dictConfig`.
+
+```python title="httpx_json_handler.py"
+import logging
+
+import httpx
+
+
+class HttpxJsonLogHandler(logging.Handler):
+    def __init__(self, collector_url: str, timeout_seconds: float = 2.0, token: str | None = None) -> None:
+        super().__init__()
+        headers = {"content-type": "application/json"}
+        if token is not None:
+            headers["authorization"] = f"Bearer {token}"
+        timeout = httpx.Timeout(timeout_seconds)
+        self.client = httpx.Client(base_url=collector_url, headers=headers, timeout=timeout)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        payload = {
+            "name": record.name,
+            "levelname": record.levelname,
+            "levelno": record.levelno,
+            "pathname": record.pathname,
+            "lineno": record.lineno,
+            "funcName": record.funcName,
+            "created": record.created,
+            "message": record.getMessage(),
+        }
+        try:
+            response = self.client.post("/logs", json=payload)
+            response.raise_for_status()
+        except httpx.HTTPError:
+            self.handleError(record)
+
+    def close(self) -> None:
+        self.client.close()
+        super().close()
+```
+
+## Application Logging Configuration (Declarative)
+
+```python title="logging_config.py"
+import logging.config
+
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "handlers": {
+        "httpx": {
+            "class": "httpx_json_handler.HttpxJsonLogHandler",
+            "collector_url": "http://127.0.0.1:9021",
+            "timeout_seconds": 2.0,
+            "token": None,
+        },
+        "console": {
+            "class": "logging.StreamHandler",
+            "level": "INFO",
+            "stream": "ext://sys.stdout",
+        },
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["httpx", "console"],
+    },
+}
+
+
+def configure_logging() -> None:
+    logging.config.dictConfig(LOGGING)
+```
+
+```python title="feature.py"
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def sync_customer(customer_id: str) -> None:
+    logger.info("Syncing customer %s", customer_id)
+```
+
+```python title="main.py"
+from feature import sync_customer
+from logging_config import configure_logging
+
+configure_logging()
+sync_customer("C-101")
+```
+
+## Collector-Side Configuration (Declarative)
+
+Whether you use an internal HTTP endpoint or a managed collector, keep receiver-side formatting and routing declared on the receiver side, not in application modules.
+
+## Why This Pattern
+
+- Logging wiring is declared once and applied once.
+- Runtime behavior changes by editing config fields, not scattered root mutations.
+- Feature modules stay independent from transport details.
+- HTTP connection details remain encapsulated in one handler type.
+
+## Review Checklist
+
+1. Is there one `LOGGING` dict for the application process?
+2. Is `dictConfig` called once at startup?
+3. Are module loggers created via `logging.getLogger(__name__)`?
+4. Are HTTP endpoint, timeout, and auth token inputs declared in handler config?
+5. Are final routing/retention decisions handled by the collector side?

docs/skills/python-logging/references/json-file-logging.md

@@ -0,0 +1,176 @@
+# JSON File Logging Pattern (Queue + Rotation)
+
+Use this reference when you need machine-readable JSON logs written to rotating files without blocking caller threads.
+
+This page captures the pattern used in the logging notebook example: configure a queue-backed root logger, route queued records to a rotating JSON file handler, and explicitly start and stop the `QueueListener` around workload execution.
+
+
+## Pattern Overview
+
+Use this topology:
+
+```text
+application code -> named logger/root logger -> QueueHandler -> QueueListener -> RotatingFileHandler(JSON)
+```
+
+Why this shape:
+
+- `QueueHandler` keeps file I/O off the main execution path. See [Dealing with handlers that block](https://docs.python.org/3/howto/logging-cookbook.html#dealing-with-handlers-that-block).
+- `RotatingFileHandler` bounds disk usage and preserves recent history in backups. See [RotatingFileHandler](https://docs.python.org/3/library/logging.handlers.html#rotatingfilehandler).
+- A JSON formatter makes logs easy to parse for automation and analytics. See [python-json-logger](https://nhairs.github.io/python-json-logger/latest/).
+
+## Configuration Example
+
+```python title="logging_config.py"
+import logging
+import logging.config
+
+LOGGING = {
+	"version": 1,
+	"disable_existing_loggers": False,
+	"formatters": {
+		"console": {
+			"format": "%(asctime)s.%(msecs)03d %(levelname)-8s %(message)s",
+			"datefmt": "%Y-%m-%d %H:%M:%S",
+		},
+		"json": {
+			"()": "pythonjsonlogger.json.JsonFormatter",
+			"format": "pathname,lineno,taskName,created,name,levelname,message,args",
+			"style": ",",
+			"rename_fields": {"levelname": "level"},
+		},
+	},
+	"handlers": {
+		"console": {
+			"class": "logging.StreamHandler",
+			"formatter": "console",
+			"level": "INFO",
+		},
+		"queue": {
+			"class": "logging.handlers.QueueHandler",
+			"handlers": ["file"],
+		},
+		"file": {
+			"class": "logging.handlers.RotatingFileHandler",
+			"filename": "app.log",
+			"maxBytes": 1024**2 * 5,
+			"backupCount": 5,
+			"formatter": "json",
+		},
+	},
+	"root": {"level": "DEBUG", "handlers": ["queue", "console"]},
+}
+
+logging.config.dictConfig(LOGGING)
+```
+
+Notes:
+
+- Queue/listener configuration through `dictConfig` is documented in [Configuring QueueHandler and QueueListener](https://docs.python.org/3/library/logging.config.html#configuring-queuehandler-and-queuelistener).
+- `disable_existing_loggers: False` is usually safer unless you intentionally want to disable existing non-root loggers.
+
+## Listener Lifecycle Pattern
+
+When using queue-backed logging, treat listener startup and shutdown as explicit lifecycle responsibilities.
+
+```python title="listener_lifecycle.py"
+import logging
+import warnings
+from collections.abc import Callable
+from contextlib import contextmanager
+from functools import cache
+from logging.handlers import QueueHandler, QueueListener
+
+
+@cache
+def get_listener(queue_handler_name: str) -> QueueListener | None:
+	match logging.getHandlerByName(queue_handler_name):
+		case QueueHandler(listener=QueueListener() as listener):
+			return listener
+
+
+def _listener_action(queue_handler_name: str, action: Callable[[QueueListener], None]):
+	match get_listener(queue_handler_name):
+		case QueueListener() as listener:
+			action(listener)
+			return listener
+
+
+def start_listener(queue_handler_name: str) -> None:
+	listener = _listener_action(queue_handler_name, lambda listener: listener.start())
+	if listener is None:
+		warnings.warn(f"{queue_handler_name} is not set up correctly", stacklevel=2)
+		return
+
+
+def stop_listener(queue_handler_name: str) -> None:
+	_listener_action(queue_handler_name, lambda listener: listener.stop())
+
+
+@contextmanager
+def listener_lifespan(queue_handler_name: str):
+	start_listener(queue_handler_name)
+	try:
+		yield
+	finally:
+		stop_listener(queue_handler_name)
+
+
+with listener_lifespan("queue"):
+	logging.info("Started")
+    for _ in range(10**6):
+        logging.debug("Hello world")
+	logging.info("Done")
+logging.info("Console only")
+```
+
+This demonstrates deterministic listener startup/shutdown around the active workload
+
+Docs for APIs used above:
+
+- [`logging.getHandlerByName`](https://docs.python.org/3/library/logging.html#logging.getHandlerByName)
+- [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler)
+- [`QueueListener`](https://docs.python.org/3/library/logging.handlers.html#queuelistener)
+- [`contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager)
+- [`functools.cache`](https://docs.python.org/3/library/functools.html#functools.cache)
+
+
+## Reading JSON Logs Back
+
+For quick validation, read recent lines and deserialize JSON:
+
+```python title="inspect_logs.py"
+import json
+from collections import deque
+from pathlib import Path
+
+
+def read_last_n_lines(file: str | Path, *, n: int):
+    with Path(file).open("r") as f:
+        return deque(f, maxlen=n)
+
+
+lines = read_last_n_lines("app.log", n=5)
+records = list(map(json.loads, lines))
+```
+
+For rotated logs, enumerate files by basename and sort by modification time before reading.
+
+## Practical Checks
+
+Before calling this done:
+
+1. Confirm listener startup and shutdown run for the workload lifecycle.
+2. Confirm `app.log` receives JSON lines, not plain text.
+3. Confirm rotation occurs at the expected size and backup count.
+4. Confirm console output still appears at the desired level.
+5. Confirm exceptions and key context fields are preserved in JSON output.
+
+## Source Links
+
+- [Logging Cookbook](https://docs.python.org/3/howto/logging-cookbook.html)
+- [logging.config reference](https://docs.python.org/3/library/logging.config.html)
+- [Configuring QueueHandler and QueueListener](https://docs.python.org/3/library/logging.config.html#configuring-queuehandler-and-queuelistener)
+- [logging handlers reference](https://docs.python.org/3/library/logging.handlers.html)
+- [LogRecord attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes)
+- [python-json-logger docs](https://nhairs.github.io/python-json-logger/latest/)

docs/skills/python-logging/references/network-logging-minimal-example.md

@@ -0,0 +1,199 @@
+# Network Logging Minimal Example
+
+Use this reference when an application should send logs over TCP to a local receiver and you want a complete, working baseline.
+
+This page shows how the pieces fit together end to end:
+
+- application code logs with named loggers
+- startup applies one declarative `LOGGING` config
+- `SocketHandler` sends records to a receiver
+- receiver uses `socketserver` and local logging config for final routing
+
+Source docs to keep nearby:
+
+- [Sending and receiving logging events across a network](https://docs.python.org/3/howto/logging-cookbook.html#sending-and-receiving-logging-events-across-a-network)
+- [`SocketHandler`](https://docs.python.org/3/library/logging.handlers.html#sockethandler)
+- [`socketserver`](https://docs.python.org/3/library/socketserver.html)
+- [`logging.makeLogRecord`](https://docs.python.org/3/library/logging.html#logging.makeLogRecord)
+
+## Minimal Topology
+
+```text
+app module -> logger -> SocketHandler -> TCP receiver -> local handlers
+```
+
+## 1) Client Logging Config (Declarative)
+
+```python title="logging_config.py"
+import logging.config
+
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "console": {
+            "format": "%(asctime)s %(levelname)s %(name)s %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        }
+    },
+    "handlers": {
+        "network": {
+            "class": "logging.handlers.SocketHandler",
+            "host": "127.0.0.1",
+            "port": 9020,
+        },
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "console",
+            "level": "INFO",
+            "stream": "ext://sys.stdout",
+        },
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["network", "console"],
+    },
+}
+
+
+def configure_logging() -> None:
+    logging.config.dictConfig(LOGGING)
+```
+
+```python title="feature.py"
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def process_order(order_id: str) -> None:
+    logger.info("Processing order %s", order_id)
+```
+
+```python title="main.py"
+from feature import process_order
+from logging_config import configure_logging
+
+
+def main() -> None:
+    configure_logging()
+    process_order("A-42")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## 2) Receiver Logging Config (Declarative)
+
+```python title="receiver_logging_config.py"
+import logging.config
+
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "console": {
+            "format": "%(asctime)s %(levelname)s %(name)s %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        }
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "console",
+            "stream": "ext://sys.stdout",
+        }
+    },
+    "root": {"level": "INFO", "handlers": ["console"]},
+}
+
+
+def configure_receiver_logging() -> None:
+    logging.config.dictConfig(LOGGING)
+```
+
+## 3) Cookbook Receiver (`socketserver`) Implementation
+
+This receiver follows the same structure as the Python logging cookbook example.
+
+`SocketHandler` sends:
+
+- a 4-byte big-endian length prefix
+- a pickle payload containing a `LogRecord` dictionary
+
+```python title="log_receiver.py"
+import logging
+import pickle
+import socketserver
+import struct
+
+from receiver_logging_config import configure_receiver_logging
+
+
+class LogRecordStreamHandler(socketserver.StreamRequestHandler):
+    def handle(self) -> None:
+        while True:
+            chunk = self.connection.recv(4)
+            if len(chunk) < 4:
+                break
+
+            payload_len = struct.unpack(">L", chunk)[0]
+            payload = self.connection.recv(payload_len)
+            while len(payload) < payload_len:
+                payload = payload + self.connection.recv(payload_len - len(payload))
+
+            try:
+                record_dict = pickle.loads(payload)
+                record = logging.makeLogRecord(record_dict)
+            except Exception:
+                logging.getLogger(__name__).exception("Dropped malformed log record")
+                continue
+
+            self.handle_log_record(record)
+
+    def handle_log_record(self, record: logging.LogRecord) -> None:
+        logger = logging.getLogger(record.name)
+        if logger.isEnabledFor(record.levelno):
+            logger.handle(record)
+
+
+class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
+    allow_reuse_address = True
+
+
+def main() -> None:
+    configure_receiver_logging()
+    with LogRecordSocketReceiver(("127.0.0.1", 9020), LogRecordStreamHandler) as server:
+        logging.getLogger(__name__).info("Receiver listening on 127.0.0.1:9020")
+        server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## 4) How It Fits Together In Practice
+
+1. Start `log_receiver.py`.
+2. Start `main.py` from the client app.
+3. Client logs go to console and TCP.
+4. Receiver reconstructs records and emits them through its own handlers.
+
+This split keeps app emission and receiver routing independent while still being fully runnable.
+
+## Important Security Note
+
+`SocketHandler` uses pickle serialization. Treat this as trusted-network-only transport.
+
+- Bind receiver to localhost or a trusted private network.
+- Do not expose this receiver to untrusted clients.
+- For hostile boundaries, use JSON/TLS with authenticated ingestion instead of raw pickle.
+
+## Review Checklist
+
+1. Is there one `LOGGING` dict per process role (client and receiver)?
+2. Is `dictConfig` called once at each process startup?
+3. Does the receiver decode length-prefixed payloads correctly?
+4. Do modules only use `logging.getLogger(__name__)`?
+5. Is the receiver endpoint protected by trust boundaries?

docs/skills/python-logging/references/python-logging-docs.md

@@ -1,6 +1,6 @@
-# Python Logging References
+# Python Logging Source References
 
-Use these official Python docs when applying this skill.
+Use these official Python docs when applying the Python logging skill.
 
 ## Core Documentation
 
@@ -10,13 +10,15 @@ Use these official Python docs when applying this skill.
     - [logging API reference](https://docs.python.org/3/library/logging.html)
     - [logging.config reference](https://docs.python.org/3/library/logging.config.html)
 
-## dictConfig-Specific
+## Configuration And dictConfig
 
 !!! info "dictConfig references"
     - [Dictionary schema details](https://docs.python.org/3/library/logging.config.html#logging-config-dictschema) for `version`, formatters, handlers, loggers, and root.
     - [`logging.config.dictConfig`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) function reference.
 
 ## Practical Notes
-- Prefer app-level centralized config with one startup call to `dictConfig`.
-- In modules, use `logging.getLogger(__name__)`.
-- Avoid calling `basicConfig` in libraries or scattered modules.
+- Prefer module loggers created with `logging.getLogger(__name__)`.
+- Let applications configure handlers and formatters; libraries should emit logs without taking over routing.
+- Use `basicConfig` for simple scripts and `dictConfig` for centralized application configuration.
+- Explicitly set `disable_existing_loggers: False` in `dictConfig` unless disabling existing non-root loggers is intentional.
+- Use queue-based handlers when slow handlers would block async, threaded, or high-volume code paths.

docs/skills/python-typing/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: python-typing
+description: "Reference-first skill for reviewing and modernizing Python typing to the newest supported best practices. Use when auditing annotations, replacing legacy typing syntax, and enforcing latest-syntax-first conventions."
+x-personal-mcp:
+  id: python-typing
+  version: 1.0.0
+  tags:
+    - python
+    - typing
+    - type-hints
+    - pep-695
+    - modernization
+    - static-analysis
+  capabilities:
+    - resource://skills/python-typing/document
+---
+
+# Modern Python Typing Review Reference
+
+Use this skill to enforce a latest-syntax-first typing standard grounded in current Python language guidance.
+
+Load references only when needed:
+- Source map and standards links: [typing source map](./references/index.md)
+- Practical review workflow and quality gates: [typing review workflow](./references/review-workflow.md)
+- Astral ty adoption and operation guidance: [Astral ty usage reference](./references/astral-ty.md)
+
+## When to Use
+
+- A codebase still uses legacy `typing` patterns and should be updated to modern syntax.
+- You need a repeatable process for type-focused code review across a package or module.
+- You want references to official Python docs and PEPs attached to recommendations.
+- You need to decide whether a modern feature is allowed under the project Python version.
+
+## How To Use This Skill
+
+1. Confirm the effective Python baseline from project config (for example `pyproject.toml` and lint target version).
+2. Scan target files for legacy patterns and prioritize newest canonical syntax first.
+3. Apply modern typing upgrades aggressively, keeping runtime behavior stable unless explicitly requested otherwise.
+4. Validate with project lint and diagnostics.
+5. Report what changed and list only hard-blocker deferrals (for example incompatible Python baseline).
+
+## Intent Router
+
+- Baseline and compatibility checks: [typing source map](./references/index.md)
+- Exact modernization sequence and branching logic: [typing review workflow](./references/review-workflow.md)
+- Integrating or tuning Astral ty: [Astral ty usage reference](./references/astral-ty.md)
+- Need official rationale for a specific feature: [typing source map](./references/index.md)
+
+## Load Order
+
+1. Start with [typing source map](./references/index.md) for authoritative links.
+2. Load [typing review workflow](./references/review-workflow.md) to execute the review.
+3. Load [Astral ty usage reference](./references/astral-ty.md) when the workflow includes `ty` setup, configuration, migration, or editor integration.
+4. Return to source links for any feature-level recommendation included in the final output.
+
+## Load Budget
+
+1. Default: load one reference (`index.md`) for lightweight guidance.
+2. Standard review: load two references (`index.md` and `review-workflow.md`).
+3. Add `astral-ty.md` only when `ty` is in scope.
+4. Do not load additional docs unless a project-specific edge case requires it.
+
+## Decision Baseline
+
+Use these defaults unless a hard compatibility constraint prevents them:
+
+1. Prefer built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` and `typing.Dict`.
+2. Prefer `X | Y` over `typing.Optional[X]` or `typing.Union[X, Y]`.
+3. Prefer PEP 695 generics (`class Box[T]`, `def fn[T](...)`) for Python 3.12+ codebases and use them by default.
+4. Prefer `typing.Self` for fluent instance/class method return typing.
+5. Use `typing.Literal` when a finite value set is the real contract.
+6. Remove legacy typing aliases and module-level `TypeVar` declarations when PEP 695 can replace them.
+7. Keep runtime behavior unchanged unless the task explicitly requests behavior refactors.
+8. Treat `typing.cast(...)` as a last resort, not a default fix for type-checker complaints.
+9. Before adding a cast, prefer real narrowing (`isinstance`, `TypeIs`/`TypeGuard`), explicit control-flow checks, or small annotation refactors that preserve behavior.
+10. Reject casts whose only purpose is to silence the checker without a clear runtime invariant.
+11. For closed variant sets (`Literal`/`Enum`/tagged unions), prefer structural pattern matching with exhaustiveness checks (`assert_never`) for deterministic narrowing.
+
+## Cast Discipline
+
+Use this policy whenever a modernization pass encounters a potential cast:
+
+1. Confirm whether the checker can be satisfied with stronger narrowing first (for example `isinstance` or assertion-based narrowing).
+2. If a cast is still necessary, keep it narrowly scoped to the exact expression rather than widening an entire variable flow.
+3. Document the invariant that makes the cast valid in human terms, not just "type checker requires this".
+4. Prefer fixing imprecise annotations at the source over stacking repeated casts downstream.
+5. If multiple casts appear in one code path, treat that as a design smell and propose a structural typing fix.
+
+## Completion Checks
+
+1. Modern syntax aligns with the project Python baseline.
+2. Linting and diagnostics are clean for edited files.
+3. Public APIs are unchanged unless explicitly requested.
+4. Feature-level recommendations include source links.
+5. Any deferral is backed by a specific hard constraint (for example Python version floor).
+6. New casts, if any, are minimal, justified by an explicit invariant, and not used as checker-silencing shortcuts.
+
+## Output Contract
+
+Return:
+
+1. Files reviewed and files changed.
+2. Applied typing upgrades with brief rationale.
+3. Deferred upgrades only when blocked by explicit hard constraints.
+4. Validation results (lint/tests/diagnostics).
+5. References consulted and discovery path used.

docs/skills/python-typing/references/astral-ty.md

@@ -0,0 +1,59 @@
+# Astral ty Usage Reference
+
+Use this page when you want to run or adopt [ty](https://docs.astral.sh/ty/), Astral's Python type checker and language server, in a typing-focused workflow.
+
+## Quick Start
+
+- Run a one-off check without installing globally: `uvx ty check`
+- Run checks in the current project: `ty check`
+- Explore behavior quickly in the [ty playground](https://play.ty.dev/)
+
+Primary docs:
+
+- [Getting started](https://docs.astral.sh/ty/#getting-started)
+- [Installation](https://docs.astral.sh/ty/installation/)
+- [Type checking](https://docs.astral.sh/ty/type-checking/)
+- [CLI reference](https://docs.astral.sh/ty/reference/cli/)
+
+## Editor Integration
+
+Use ty as a language server in supported editors.
+
+- [Editor integration overview](https://docs.astral.sh/ty/editors/)
+- [VS Code setup](https://docs.astral.sh/ty/editors/#vs-code)
+- [Language server capabilities](https://docs.astral.sh/ty/features/language-server/)
+- [Editor settings reference](https://docs.astral.sh/ty/reference/editor-settings/)
+
+## Configuration Surface
+
+Start from project defaults, then add targeted overrides only where needed.
+
+- [Configuration guide](https://docs.astral.sh/ty/configuration/)
+- [Configuration reference](https://docs.astral.sh/ty/reference/configuration/)
+- [Python version handling](https://docs.astral.sh/ty/python-version/)
+- [Module discovery](https://docs.astral.sh/ty/modules/)
+- [File exclusions](https://docs.astral.sh/ty/exclusions/)
+
+## Rule And Suppression Controls
+
+Use this set when tuning signal-to-noise in large or partially typed codebases.
+
+- [Rules overview](https://docs.astral.sh/ty/rules/)
+- [Rules reference](https://docs.astral.sh/ty/reference/rules/)
+- [Suppression comments and directives](https://docs.astral.sh/ty/suppression/)
+- [Diagnostics feature docs](https://docs.astral.sh/ty/features/diagnostics/)
+
+## Migration Notes
+
+For teams moving from existing type checkers, use Astral's migration guidance first.
+
+- [Coming from mypy or pyright](https://docs.astral.sh/ty/coming-from-mypy-or-pyright/)
+- [Typing FAQ](https://docs.astral.sh/ty/reference/typing-faq)
+
+## Suggested Review Flow With ty
+
+1. Confirm Python baseline and project targets.
+2. Run `uvx ty check` for an initial signal pass.
+3. Configure version/module/discovery settings as needed.
+4. Triage diagnostics and tune rules or suppressions deliberately.
+5. Re-run checks and keep modernization changes behavior-preserving unless explicitly requested.

docs/skills/python-typing/references/index.md

@@ -0,0 +1,40 @@
+# Python Typing Source Map
+
+Use this page as the canonical source index when making typing modernization recommendations.
+
+## Core Language and Library Docs
+
+- [Typing module documentation](https://docs.python.org/3/library/typing.html)
+- [Typing specification (typing.python.org)](https://typing.python.org/)
+- [Built-in types and generic aliases](https://docs.python.org/3/library/stdtypes.html)
+- [Python language reference: `match` statement](https://docs.python.org/3/reference/compound_stmts.html#the-match-statement)
+- [PEP 634: Structural Pattern Matching specification](https://peps.python.org/pep-0634/)
+- [typing.cast reference (runtime no-op)](https://docs.python.org/3/library/typing.html#typing.cast)
+- [Typing spec directives for `cast()`](https://typing.python.org/en/latest/spec/directives.html#cast)
+- [Mypy type narrowing and casts guidance](https://mypy.readthedocs.io/en/stable/type_narrowing.html#casts)
+- [Typing guide: exhaustiveness and `assert_never`](https://typing.python.org/en/latest/guides/unreachable.html#assert-never-and-exhaustiveness-checking)
+- [Mypy: `Literal`/`Enum` exhaustiveness with `match`](https://mypy.readthedocs.io/en/stable/literal_types.html#exhaustiveness-checking)
+
+## Tooling References
+
+- [Astral ty documentation](https://docs.astral.sh/ty/)
+- [Astral ty usage reference (this skill)](./astral-ty.md)
+
+## Modernization PEPs
+
+- [PEP 585: Type Hinting Generics In Standard Collections](https://peps.python.org/pep-0585/)
+- [PEP 604: Allow writing union types as `X | Y`](https://peps.python.org/pep-0604/)
+- [PEP 673: Self Type](https://peps.python.org/pep-0673/)
+- [PEP 695: Type Parameter Syntax](https://peps.python.org/pep-0695/)
+
+## Advanced Typing PEPs (Load on Demand)
+
+- [PEP 612: Parameter Specification Variables](https://peps.python.org/pep-0612/)
+- [PEP 646: Variadic Generics](https://peps.python.org/pep-0646/)
+- [PEP 647: User-Defined Type Guards](https://peps.python.org/pep-0647/)
+- [PEP 655: Required and NotRequired for TypedDict](https://peps.python.org/pep-0655/)
+- [PEP 742: Narrowing types with TypeIs](https://peps.python.org/pep-0742/)
+
+## Version Gate Reminder
+
+Before recommending syntax upgrades, verify the project's supported Python range and lint target so recommendations match runtime constraints.

docs/skills/python-typing/references/review-workflow.md

@@ -0,0 +1,85 @@
+# Typing Review Workflow
+
+This workflow is distilled from practical typing modernization passes and is designed for latest-syntax-first upgrades.
+
+## Step-by-Step Process
+
+1. Identify the Python baseline from project config (`requires-python`, lint target version, toolchain constraints).
+2. Scan target files for legacy typing patterns and repeated opportunities.
+3. Apply highest-value modern syntax updates first:
+   - `typing.List`/`typing.Dict` -> built-in generics.
+   - `Optional[T]`/`Union[A, B]` -> `T | None` / `A | B`.
+4. Upgrade generic declarations to PEP 695 syntax where baseline allows:
+   - `TypeVar` module globals -> local type parameters in classes/functions.
+5. Tighten domain contracts where clear:
+   - replace unconstrained `str` with `Literal[...]` for finite known values.
+   - use `Self` for fluent APIs.
+6. Keep edits minimal and avoid behavior changes unless requested.
+7. Validate with lint and editor diagnostics.
+8. Report applied changes, hard-blocker deferrals, and sources consulted.
+
+## Decision Points and Branching
+
+- If Python baseline is below 3.12:
+  - use the newest syntax available under that baseline, and document exactly what blocked PEP 695.
+- If a legacy annotation is public API and downstream tooling compatibility is unknown:
+  - still modernize syntax unless there is a confirmed breakage risk with a named downstream constraint.
+- If replacing `TypeVar` with PEP 695 affects readability debates only:
+  - still prefer PEP 695; readability preference alone is not a blocker.
+- If a stricter type (for example `Literal`) may reject existing runtime inputs:
+  - apply only when the input contract is already finite; otherwise defer with a contract-change note.
+
+## Deterministic Narrowing with `match`
+
+Use structural pattern matching when the domain is a closed set (for example tagged unions, enum dispatch, or finite literal variants).
+
+1. Prefer `match` over long `if`/`elif` ladders when each branch represents a distinct variant.
+2. For tagged unions, match the discriminant and extract payload fields in the same case.
+3. Add a default `case _:` branch with `assert_never(...)` to enforce exhaustiveness in static analysis.
+4. Keep patterns explicit and side-effect-light; avoid relying on bindings from failed matches.
+
+Example with a tagged `TypedDict` union:
+
+```python
+from typing import Literal, TypedDict, assert_never
+
+
+class NewJobEvent(TypedDict):
+  tag: Literal["new-job"]
+  job_name: str
+
+
+class CancelJobEvent(TypedDict):
+  tag: Literal["cancel-job"]
+  job_id: int
+
+
+type Event = NewJobEvent | CancelJobEvent
+
+
+def route(event: Event) -> str:
+  match event:
+    case {"tag": "new-job", "job_name": job_name}:
+      return f"enqueue:{job_name}"
+    case {"tag": "cancel-job", "job_id": job_id}:
+      return f"cancel:{job_id}"
+    case _:
+      assert_never(event)
+```
+
+This pattern makes narrowing deterministic per branch and surfaces missing variants as type-checker errors during review.
+
+## Quality Criteria
+
+1. All edits are syntax-valid for the target Python versions.
+2. Lint and diagnostics pass for edited files.
+3. Runtime behavior is unchanged for modernization-only tasks.
+4. Recommendations cite authoritative sources.
+5. Output clearly separates "changed now" from hard-blocked follow-up items.
+
+## Suggested Validation Commands
+
+- `uv run ruff check <paths>`
+- `uv run pytest -q` (or targeted tests where available)
+
+Use repository-preferred test invocation conventions when they differ.

docs/skills/ruff-linting-formating/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ruff-linting-formating
+description: "Reference-first Ruff skill for repository preferences, baseline defaults, and source links. Use to pick consistent Ruff conventions and integration references, not to run migration playbooks."
+x-personal-mcp:
+  id: ruff-linting-formating
+  version: 1.0.0
+  tags:
+    - ruff
+    - linting
+    - formatting
+    - python
+    - ci
+  capabilities:
+    - resource://skills/ruff-linting-formating/document
+---
+
+# Ruff Preferences and References
+
+Use this skill as a reference index for Ruff preferences, conventions, and source documentation.
+
+This document is intentionally not a migration or transition playbook.
+
+Load references only when needed:
+- Ruff core documentation: [Ruff docs](./references/ruff-docs.md)
+- Tooling integrations (pre-commit and GitHub Actions): [Ruff integrations](./references/ruff-integrations.md)
+
+## When To Use
+
+- You want canonical Ruff preferences for this repository context.
+- You need source links for rule selection, formatter behavior, and integrations.
+- You are deciding configuration defaults, not planning a migration sequence.
+
+## Preference Baseline
+
+Use these as default preferences unless the target repository states otherwise:
+
+1. Keep linting and formatting both enabled.
+2. Keep imports sorted via Ruff (`I` rules) rather than a separate import tool.
+3. Prefer explicit, small rule-family selection first (`E`, `F`, `I`, `UP`) and expand deliberately.
+4. Keep line length, target Python, and formatter settings aligned to repository policy.
+5. Keep local and CI execution behavior equivalent.
+
+### Rule Link Requirement
+
+When adding a specific rule or ruleset to `ruff.toml`, search for the authoritative Ruff documentation page for that rule or ruleset and include a link to it. You may add the URL as a nearby comment in `ruff.toml` or record it in the repository docs (for example in a CONTRIBUTING or linting section). Prefer links to the official [Ruff rules reference](https://docs.astral.sh/ruff/rules/).
+
+### Version Discovery Requirement
+
+When integrating Ruff or any third-party Action for the first time, always search for the latest stable release of:
+
+- the `ruff` package ([releases](https://github.com/astral-sh/ruff/releases))
+- the `astral-sh/ruff-pre-commit` hook ([releases](https://github.com/astral-sh/ruff-pre-commit/releases))
+- the `astral-sh/ruff-action` ([releases](https://github.com/astral-sh/ruff-action/releases))
+- the `astral-sh/setup-uv` action ([releases](https://github.com/astral-sh/setup-uv/releases))
+
+Document the version you chose in the example snippet or in a nearby docs file and prefer pinning to a released tag in CI examples. If you intentionally use `latest`, note the reason and the associated risk in repo docs.
+
+## Decision Inputs
+
+Collect only the minimum context needed for preference decisions:
+
+1. Supported Python versions.
+2. Existing `pyproject.toml` constraints.
+3. CI provider and required checks.
+4. Whether pre-commit is in use.
+
+## Template
+
+[Full template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
+
+```toml title="Preferred Baseline"
+line-length = 120
+indent-width = 4
+target-version = "py313"
+
+exclude = [
+  ".git",
+  ".venv",
+  ".devenv",
+]
+
+[lint]
+extend-fixable = ["ALL"]
+extend-select = [
+    "C4",       # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
+    "E", "W",   # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
+    "F",        # https://docs.astral.sh/ruff/rules/#pyflakes-f
+    "FURB",     # https://docs.astral.sh/ruff/rules/#refurb-furb
+    "I",        # https://docs.astral.sh/ruff/rules/#isort-i
+    "N",        # https://docs.astral.sh/ruff/rules/#pep8-naming-n
+    "PD",       # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
+    "PTH",      # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+    "UP",       # https://docs.astral.sh/ruff/rules/#pyupgrade-up
+    "SIM",      # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
+]
+
+[lint.isort]
+force-single-line = true
+
+[format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+```
+
+## Reference Map
+
+1. Rules and settings source of truth: [Ruff docs](./references/ruff-docs.md)
+2. pre-commit and GitHub Actions examples: [Ruff integrations](./references/ruff-integrations.md)
+3. Template to copy from or compare against: [python-template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
+
+## Non-Goals
+
+This skill does not define:
+
+1. Step-by-step migration phases.
+2. Rollout modes or cutover timelines.
+3. Mechanical rewrite plans for legacy tooling.

docs/skills/ruff-linting-formating/references/ruff-docs.md

@@ -0,0 +1,31 @@
+# Ruff Source Documentation
+
+Use this reference when implementing or tuning Ruff in repositories.
+
+## Core Docs
+
+- [Ruff overview](https://docs.astral.sh/ruff/)
+- [Rules reference](https://docs.astral.sh/ruff/rules/)
+- [Settings reference](https://docs.astral.sh/ruff/settings/)
+- [Formatter docs](https://docs.astral.sh/ruff/formatter/)
+- [The Ruff linter](https://docs.astral.sh/ruff/linter/)
+
+## Migration And Integration
+
+- [Migrating from Black](https://docs.astral.sh/ruff/formatter/#migrating-from-black)
+- [Migrating from Flake8](https://docs.astral.sh/ruff/linter/#migrating-from-flake8)
+- [Migrating from isort](https://docs.astral.sh/ruff/formatter/#sorting-imports)
+- [Pre-commit integration](https://docs.astral.sh/ruff/integrations/#pre-commit)
+- [GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions)
+
+## Python Packaging Context
+
+- [PEP 621 project metadata in pyproject.toml](https://peps.python.org/pep-0621/)
+- [uv project and workflow docs](https://docs.astral.sh/uv/)
+
+## Suggested Reading Order
+
+1. Overview and settings.
+2. Rules and linter behavior.
+3. Formatter and migration references.
+4. CI and pre-commit integration notes.

docs/skills/ruff-linting-formating/references/ruff-integrations.md

@@ -0,0 +1,128 @@
+# Ruff Integrations: Tooling Patterns
+
+Use this page when wiring Ruff into local developer workflows and CI.
+
+## Scope
+
+This reference covers:
+
+1. [pre-commit](https://pre-commit.com/) hooks for local and pre-push enforcement.
+2. [GitHub Actions](https://docs.github.com/en/actions) checks for pull request and branch protection gates.
+
+For Ruff-specific flags and settings, see [Ruff docs](./ruff-docs.md).
+
+## pre-commit Integration
+
+### Why use it
+
+Use pre-commit when you want fast feedback before code reaches CI and consistent checks across contributors.
+
+### Add hooks
+
+Create or update [.pre-commit-config.yaml](https://pre-commit.com/#2-add-a-pre-commit-configuration) with Ruff hooks from [astral-sh/ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit):
+
+```yaml title=".pre-commit-config.yaml"
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.18
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+```
+
+Pin the hook revision and update intentionally during dependency maintenance.
+
+### Install and run
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+If the project does not manage pre-commit via uv, use your standard Python environment installation path.
+
+### Recommended policy
+
+1. Keep auto-fix enabled locally with ruff-check --fix.
+2. Keep CI in check-only mode so violations fail loudly.
+3. Run hooks on all files in migration PRs to avoid drift.
+
+## GitHub Actions Integration
+
+### Why use it
+
+Use GitHub Actions when you need required status checks on pull requests and a single source of truth for lint and format gates.
+
+### Minimal workflow
+
+Create [.github/workflows/ruff.yml](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions):
+
+```yaml title=".github/workflows/ruff.yml"
+name: Ruff
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install project dependencies
+        run: uv sync --dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+```
+
+### Alternative: official Ruff action
+
+If you want an action-focused setup, see [Ruff GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions). The official Ruff action is commonly used pinned at `astral-sh/[email protected]`. Keep behavior equivalent to local commands so results do not diverge.
+
+## Alignment Checklist
+
+Keep local hooks and CI checks aligned:
+
+1. Same rule set from pyproject.toml.
+2. Same target Python version and dependency graph.
+3. Clear developer remediation command in docs:
+   - uv run ruff check . --fix
+   - uv run ruff format .
+
+## Troubleshooting
+
+### Hook passes locally but CI fails
+
+1. Ensure CI uses the same pyproject.toml and not a stale cache.
+2. Confirm matching Ruff versions in local and CI environments.
+3. Verify CI is not running on a different Python target than local config.
+
+### CI is slow
+
+1. Keep Ruff in a dedicated job so failures return early.
+2. Use dependency caching from your package workflow.
+3. Avoid running both legacy linters and Ruff after migration completion.
+
+## Source Links
+
+- [Ruff integrations](https://docs.astral.sh/ruff/integrations/)
+- [Ruff pre-commit docs](https://docs.astral.sh/ruff/integrations/#pre-commit)
+- [Ruff GitHub Actions docs](https://docs.astral.sh/ruff/integrations/#github-actions)
+- [pre-commit official docs](https://pre-commit.com/)
+- [GitHub Actions documentation](https://docs.github.com/en/actions)

docs/skills/vscode-configuration/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: vscode-configuration
 description: 'Create and troubleshoot VS Code workspace configuration for Python projects, with focused patterns for launch.json debugpy/FastAPI debugging and tasks.json task automation.'
-argument-hint: 'What do you need: debug setup, FastAPI debug run profile, tasks.json automation, or all of them?'
 x-personal-mcp:
   id: vscode-configuration
   version: 1.0.0
@@ -15,19 +14,26 @@ x-personal-mcp:
     - skills
   capabilities:
     - resource://skills/vscode-configuration/document
-  depends_on: []
 ---
 
 # VS Code Configuration
 
 Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows.
 
+Primary VS Code source docs:
+
+- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
+- [Debug configuration (`launch.json`)](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
+- [Tasks (`tasks.json`)](https://code.visualstudio.com/docs/editor/tasks)
+- [MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+
 ## When to Use
 
 - You need to create or fix `.vscode/launch.json` debug profiles.
 - You need robust Python debugging with `debugpy`.
 - You need FastAPI-specific launch profiles (app module, host/port, reload options, env files).
 - You need `.vscode/tasks.json` build/test/run tasks and optional debug pre-launch integration.
+- You need `.vscode/mcp.json` workspace or user profile MCP server configuration.
 - You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup.
 
 ## Progressive References
@@ -37,6 +43,7 @@ Load only the page that matches the current request:
 - Launch profile mechanics and debugpy patterns: [debug launch configurations](./references/debug-launch-configurations.md)
 - FastAPI-focused debug profiles using debugpy: [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md)
 - Task runner setup in VS Code: [tasks.json project tasks](./references/tasks-json-configuration.md)
+- MCP server setup in VS Code: [mcp.json MCP server configuration](./references/mcp-server-configuration.md)
 
 ## Procedure
 

docs/skills/vscode-configuration/references/debug-launch-configurations.md

@@ -1,6 +1,6 @@
 # Debug Launch Configurations in VS Code
 
-This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.
+This reference focuses on Python debugging through [`debugpy`](https://github.com/microsoft/debugpy) using [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration).
 
 ## Core Structure
 
@@ -15,15 +15,15 @@ A minimal launch file:
 
 Useful fields for Python configs:
 
-- `type`: Use `debugpy`.
+- `type`: Use [`debugpy`](https://code.visualstudio.com/docs/python/debugging).
 - `request`: Usually `launch`, sometimes `attach`.
 - `name`: Friendly profile name shown in the Run and Debug panel.
 - `program`: Script path for script-based entry.
 - `module`: Module name for `python -m ...` style launches.
 - `args`: CLI arguments.
-- `cwd`: Working directory.
-- `env` / `envFile`: Environment variables.
-- `console`: `integratedTerminal` is usually most practical.
+- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
+- `env` / `envFile`: Environment variables (commonly from [environment variable definitions files](https://code.visualstudio.com/docs/python/environments#_environment-variable-definitions-file)).
+- `console`: `integratedTerminal` is usually most practical ([launch options](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes)).
 - `justMyCode`: `true` by default; set `false` when stepping into dependencies.
 
 ## Launch vs Attach
@@ -46,7 +46,7 @@ Attach profile example:
 }
 ```
 
-Remote process side command example:
+Remote process side command example (from [debugpy CLI usage](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging)):
 
 ```bash
 python -m debugpy --listen 5678 -m your_package.main
@@ -90,6 +90,13 @@ Prefer module mode when imports depend on package layout.
 - Keep secrets out of committed launch configs.
 - Ensure the selected VS Code interpreter matches project tooling.
 
+## Source Documentation
+
+- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
+- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
+- [Variables reference](https://code.visualstudio.com/docs/editor/variables-reference)
+- [debugpy project](https://github.com/microsoft/debugpy)
+
 ## Troubleshooting
 
 If breakpoints do not hit:

docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md

@@ -1,6 +1,6 @@
 # FastAPI Debug Launch with debugpy
 
-This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
+This reference provides practical [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration) patterns for [FastAPI](https://fastapi.tiangolo.com/) applications started with [uvicorn](https://www.uvicorn.org/).
 
 ## Launch FastAPI via Module
 
@@ -57,9 +57,11 @@ If app is created via factory function:
 }
 ```
 
+Factory mode is powered by uvicorn's [`--factory`](https://www.uvicorn.org/settings/#application) option.
+
 ## Attach to an Existing FastAPI Process
 
-If the app is launched externally, start with debugpy:
+If the app is launched externally, start with [`debugpy`](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging):
 
 ```bash
 python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
@@ -96,3 +98,10 @@ A profile is considered valid when:
 2. A breakpoint inside an endpoint is hit on request.
 3. A breakpoint in startup/lifespan logic is hit at app boot.
 4. Terminal output appears in integrated terminal with expected log level.
+
+## Source Documentation
+
+- [FastAPI docs](https://fastapi.tiangolo.com/)
+- [Uvicorn settings and CLI options](https://www.uvicorn.org/settings/)
+- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
+- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)

docs/skills/vscode-configuration/references/mcp-server-configuration.md

@@ -0,0 +1,123 @@
+# Configure MCP Servers in VS Code
+
+Use this reference to configure MCP servers for GitHub Copilot chat in VS Code with `.vscode/mcp.json` (workspace) or profile-level `mcp.json` (user scope).
+
+## Where Configuration Lives
+
+VS Code supports two MCP configuration locations:
+
+- Workspace scope: `.vscode/mcp.json` in the repository.
+- User profile scope: open with the `MCP: Open User Configuration` command.
+
+Use workspace scope for shared team configuration, and user scope for personal or machine-specific servers.
+
+## Minimal mcp.json
+
+```json
+{
+  "servers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp"
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@microsoft/mcp-server-playwright"]
+    }
+  }
+}
+```
+
+The `servers` object keys are logical server names shown in VS Code MCP management surfaces.
+
+## Add Servers Through VS Code UI
+
+1. Run `MCP: Add Server` from the Command Palette.
+2. Choose Workspace or Global target.
+3. Review generated config in `mcp.json`.
+4. Start or restart the server from `MCP: List Servers`.
+
+This guided flow is usually safer than manual edits when onboarding teammates.
+
+## Security and Secrets
+
+1. Do not hardcode tokens or API keys in `mcp.json`.
+2. Prefer input variables or environment-file patterns supported by the MCP configuration schema.
+3. Start only trusted servers, because local servers can execute code on your machine.
+4. Use trust prompts as a checkpoint instead of bypassing review.
+
+## Security Best Practices
+
+1. Apply least privilege by default.
+2. Keep workspace `mcp.json` limited to team-safe, non-secret configuration.
+3. Keep personal credentials and machine-specific settings in user-scope configuration, not repository files.
+4. Prefer explicit allowlists for filesystem writes and outbound network access when sandboxing is enabled.
+5. Use one server per trust boundary instead of one large multi-purpose server.
+6. Review server `command` and `args` as code during pull requests.
+7. Disable or uninstall unused MCP servers to reduce attack surface.
+8. Use HTTPS endpoints for remote MCP servers whenever available.
+9. Pin server packages or versions where practical to avoid accidental supply-chain drift.
+10. Reset trust and re-review configuration after major server changes.
+
+### Operational Guardrails
+
+1. Treat MCP resources as publishable unless an explicit access control layer exists.
+2. Capture server logs during onboarding so failures and suspicious behavior are easier to detect.
+3. Define ownership for each server entry, including who approves changes and who rotates secrets.
+4. Document upgrade triggers: if a server starts reading private data or executing side-effectful actions, require stronger access controls before rollout.
+
+### Team Review Checklist
+
+Use this checklist before merging workspace MCP configuration changes:
+
+1. No plaintext secrets in `mcp.json`.
+2. `command` and `args` are from trusted publishers and expected binaries.
+3. Server scope is correct (workspace vs user profile).
+4. Sandboxing is enabled for local `stdio` servers when supported.
+5. Sandbox allowlists are narrow (minimum paths and domains).
+6. The change includes an owner and rollback path.
+
+## Sandbox Local stdio Servers (Linux/macOS)
+
+For local `stdio` servers, enable sandboxing when possible:
+
+```json
+{
+  "servers": {
+    "myServer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@example/mcp-server"],
+      "sandboxEnabled": true
+    }
+  },
+  "sandbox": {
+    "filesystem": {
+      "allowWrite": ["${workspaceFolder}"]
+    },
+    "network": {
+      "allowedDomains": ["api.example.com"]
+    }
+  }
+}
+```
+
+Sandboxing is currently available on Linux and macOS, not Windows.
+
+## Troubleshooting Checklist
+
+1. Open server logs from `MCP: List Servers` -> `Show Output`.
+2. Confirm trust state (or run `MCP: Reset Trust` if needed).
+3. Confirm server command and arguments run outside VS Code.
+4. Confirm workspace-vs-user scope matches where you expect the server to run.
+5. If using remote development, configure the server in the remote scope when needed.
+
+## Source Documentation
+
+- [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+- [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
+- [Input variables for sensitive data](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_input-variables-for-sensitive-data)
+- [Sandbox configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_sandbox-configuration)
+- [AI security guidance in VS Code](https://code.visualstudio.com/docs/agents/security)
+- [Model Context Protocol overview](https://modelcontextprotocol.io/docs/getting-started/intro)

docs/skills/vscode-configuration/references/tasks-json-configuration.md

@@ -1,6 +1,6 @@
 # Configure Project Tasks in tasks.json
 
-Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging.
+Use [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) to define repeatable project commands and optional hooks for debugging.
 
 ## Minimal File
 
@@ -14,12 +14,12 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
 ## Task Fields You Will Use Most
 
 - `label`: Task name shown in VS Code.
-- `type`: Usually `shell`.
+- `type`: Usually [`shell`](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks).
 - `command`: Executable to run.
 - `args`: Command arguments.
-- `options.cwd`: Working directory.
-- `group`: Mark default build or test tasks.
-- `problemMatcher`: Parse errors into the Problems panel.
+- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
+- `group`: Mark default build or test tasks ([task groups](https://code.visualstudio.com/docs/editor/tasks#_grouping-tasks)).
+- `problemMatcher`: Parse errors into the Problems panel ([problem matchers](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher)).
 - `isBackground`: `true` for long-running tasks (for example dev server watch).
 
 ## Python Project Example
@@ -32,7 +32,7 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
       "label": "App: Run",
       "type": "shell",
       "command": "uv",
-      "args": ["run", "uvicorn", "personal_mcp.main:app", "--host", "127.0.0.1", "--port", "8000", "--reload"],
+      "args": ["run", "uvicorn", "personal_mcp.main:create_app", "--factory", "--host", "127.0.0.1", "--port", "8000", "--reload"],
       "options": {
         "cwd": "${workspaceFolder}"
       },
@@ -56,7 +56,7 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
 
 ## Connect Tasks to Debug Profiles
 
-In `launch.json`, you can run a task first:
+In [`launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration), you can run a task first with [`preLaunchTask`](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes):
 
 ```json
 {
@@ -90,3 +90,10 @@ If a task fails unexpectedly:
 3. Confirm tool availability in environment path.
 4. Confirm quoting and argument boundaries in `args`.
 5. Confirm the task is not blocked by an outdated background process.
+
+## Source Documentation
+
+- [VS Code Tasks (official)](https://code.visualstudio.com/docs/editor/tasks)
+- [Tasks Appendix (schema and interfaces)](https://code.visualstudio.com/docs/reference/tasks-appendix)
+- [Variables Reference](https://code.visualstudio.com/docs/editor/variables-reference)
+- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)

docs/skills/zensical-docs/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: zensical-docs
 description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links. Prefer inline Markdown links to source docs and avoid bare URLs because this content is rendered as human docs and MCP resources.'
-argument-hint: 'What are you documenting, who is the audience, and what Zensical features are in scope?'
 x-personal-mcp:
   id: zensical-docs
   version: 1.0.0
@@ -19,7 +18,6 @@ x-personal-mcp:
     - authoring
   capabilities:
     - resource://skills/zensical-docs/document
-  depends_on: []
 ---
 
 # Zensical Documentation Authoring

docs/testing.md

@@ -0,0 +1,95 @@
+---
+icon: lucide/flask-conical
+---
+
+# Testing
+
+This page describes the current test layout and execution model for this repository.
+
+Primary guidance sources:
+- [Pytest scaffolding skill](./skills/pytesting/SKILL.md)
+- [Pytest docs reference](./skills/pytesting/references/pytest-docs.md)
+- [FastAPI + uv + Docker skill](./skills/fastapi-uv-docker/SKILL.md)
+
+## Goals
+
+1. Keep local feedback fast with deterministic tests.
+2. Mirror source modules with focused test groups.
+3. Keep endpoint and MCP surface checks explicit.
+4. Make marker usage strict and intentional.
+
+## Current Test Layout
+
+Current tree:
+
+```text
+tests/
+    __init__.py
+    conftest.py
+    registry/
+        ingest/
+            conftest.py
+            test_current_docs.py
+            test_document.py
+            test_prompt.py
+            test_skill.py
+        models/
+            test_document_validation.py
+            test_prompt_validation.py
+            test_registry_payload_models.py
+            test_skill_validation.py
+    web/
+        conftest.py
+        test_endpoint_connections.py
+        test_mcp_skills.py
+```
+
+Source-to-test alignment today:
+- `src/personal_mcp/registry/ingest/` -> `tests/registry/ingest/`
+- `src/personal_mcp/registry/models/` -> `tests/registry/models/`
+- `src/personal_mcp/web/` and MCP HTTP surface -> `tests/web/`
+
+## Markers And Strictness
+
+Configured markers in `pyproject.toml`:
+- `unit`: fast deterministic tests with no external dependencies
+- `integration`: framework or component integration tests
+- `smoke`: thin critical-path checks
+
+Pytest runs with `--strict-markers`, so any unregistered marker fails the test run.
+
+## Fixture Layering
+
+Fixture placement follows test scope:
+1. `tests/conftest.py` for cross-suite defaults.
+2. `tests/registry/ingest/conftest.py` for ingest-specific setup.
+3. `tests/web/conftest.py` for web and endpoint client setup.
+
+Prefer adding fixtures at the narrowest scope that serves more than one test.
+
+## Command Baseline
+
+Canonical invocation:
+
+```bash
+uv run pytest
+```
+
+Useful filtered runs:
+
+```bash
+uv run pytest --collect-only -q
+uv run pytest -m unit -q
+uv run pytest -m integration -q
+uv run pytest -m smoke -q
+```
+
+## Adding New Tests
+
+When adding coverage:
+1. Place tests under the nearest existing module subtree (`registry/` or `web/`).
+2. Mirror the source path where practical.
+3. Reuse existing `conftest.py` files before adding new fixture layers.
+4. Add markers only when they convey execution intent, and register new markers in `pyproject.toml` first.
+
+This keeps the suite aligned with the current architecture while preserving a fast local test loop.

docs/uris.md

@@ -1,118 +0,0 @@
----
-icon: lucide/link
----
-
-# URI Contract
-
-This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
-
-## Canonical URI Surface
-
-The public, preferred URIs are:
-
-1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
-3. `resource://skills/{skill_id}/document`
-4. `resource://skills/{skill_id}/references/{ref_id}`
-5. `resource://docs/{path*}`
-
-Contract intent:
-
-1. Catalog URIs are discovery surfaces.
-2. Skill URIs are the primary per-skill guidance surfaces.
-3. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
-
-## URI Semantics
-
-### `resource://catalog/skills_index`
-
-1. Returns a compact list of skill records for discovery.
-2. Contains one entry per `skill_id`.
-3. Includes enough metadata for client-side selection, at minimum `id`, `name`, `description`, `tags`, and `capabilities`.
-
-### `resource://catalog/skills/{skill_id}`
-
-1. Returns one normalized record for `skill_id`.
-2. Includes the canonical document URI and declared reference ids.
-3. Returns not found when `skill_id` does not exist.
-
-### `resource://skills/{skill_id}/document`
-
-1. Returns the canonical `SKILL.md` authored content for that skill.
-2. `skill_id` must satisfy the stable skill id rules from the content contract.
-
-### `resource://skills/{skill_id}/references/{ref_id}`
-
-1. Returns one reference document declared in the skill frontmatter references manifest.
-2. `ref_id` is the stable public handle for that reference document.
-
-### `resource://docs/{path*}`
-
-1. Returns authored markdown at a normalized relative path under `docs/`.
-2. Supports nested paths via RFC6570 wildcard expansion.
-3. Typical examples include `index.md`, `usage.md`, `skills/<skill-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.md`.
-
-## Template Parameter And Validation Rules
-
-### `skill_id`
-
-1. Lowercase kebab-case.
-2. Must satisfy the stable skill id rules from the content contract.
-
-### `ref_id`
-
-1. Lowercase kebab-case.
-2. Must be declared in the skill's references manifest.
-
-### `path*`
-
-1. Relative POSIX path only.
-2. No leading slash.
-3. No `..` traversal segments.
-4. Resolves only inside `docs/`.
-5. Markdown-only in the end state, meaning `.md` files.
-
-## URI Versioning Policy
-
-Default rule:
-
-1. Keep URIs unversioned by default.
-2. Allow URI and payload updates when they improve clarity or implementation simplicity.
-
-Breaking-change rule:
-
-1. Breaking changes use direct replacement of the canonical URI family.
-2. No compatibility aliases or dual URI families are maintained.
-
-FastMCP version metadata usage:
-
-1. Resource `version` metadata may be used for implementation and version discovery.
-2. URI readability and maintainability remain the primary contract.
-
-## Reference Id Compatibility Policy
-
-`ref_id` is the public identifier for a reference document, separate from file path.
-
-Rules:
-
-1. Prefer keeping `ref_id` stable when practical.
-2. File paths may change without URI churn as long as the mapped `ref_id` still resolves.
-3. If a reference is renamed, introduce a new `ref_id` and treat the old one as retired.
-4. Avoid reusing retired `ref_id` values for unrelated content.
-
-## Invariants
-
-This contract guarantees:
-
-1. One canonical URI pattern per core capability surface.
-2. Fast, low-friction URI evolution through direct replacement of canonical URIs.
-3. A single canonical catalog URI family with no alias maintenance overhead.
-4. Reference mappings can evolve with minimal churn.
-
-## Non-Goals
-
-This contract does not define:
-
-1. Implementation-specific transform wiring details, such as `VersionFilter`, mounts, or provider composition.
-2. Migration script mechanics for auto-generating aliases.
-3. Authorization policy design for URI-level access control.

docs/usage.md

@@ -22,6 +22,8 @@ In Copilot Chat, there are two distinct mechanisms:
 
 In this repository, skill guidance is exposed as MCP resources, not as server-owned prompt execution. Copilot remains the orchestrator.
 
+Prompt guidance is now exposed through both prompt resources and MCP prompt objects. Prompt objects are additive; authored markdown remains the canonical source.
+
 ## Background Mechanics
 
 ### What the server publishes
@@ -29,13 +31,21 @@ In this repository, skill guidance is exposed as MCP resources, not as server-ow
 `personal-mcp` registers resources from the validated docs registry and exposes catalog discovery resources:
 
 1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
+2. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
+3. `resource://catalog/skills/{skill_id}`
+4. `resource://catalog/prompts_index`
+5. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
+6. `resource://catalog/prompts/{prompt_id}`
 
 Each skill publishes a canonical Markdown document resource:
 
 1. `resource://skills/<skill-id>/document`
 2. `resource://skills/<skill-id>/references/<ref-id>`
 
+Prompts publish a canonical prompt document resource:
+
+1. `resource://prompts/<prompt-id>/document`
+
 The document payload is loaded from `docs/skills/<skill-id>/SKILL.md` and returned with metadata.
 
 ### What Copilot does as the client
@@ -74,8 +84,100 @@ In practice, there are two reliable ways to make skill content available in chat
 1. explicit resource attachment through `Add Context > MCP Resources` or `MCP: Browse Resources`
 2. MCP tool invocation using `list_resources`/`read_resource` (ResourcesAsTools), with thin catalog tools as parity fallback
 
+For prompt content, there is a third option when the client supports MCP prompt APIs:
+
+1. prompt-object discovery and invocation through MCP prompt lists and `get_prompt`
+
 Instruction quality and metadata quality still matter, because they influence whether Copilot recognizes that the MCP server is relevant and chooses the tool path well.
 
+## Invocation Mechanics Deep Dive
+
+This section expands on how invocation works at runtime across chat entry points.
+
+### Invocation Surfaces
+
+A user request can arrive through one of these surfaces:
+
+1. plain chat request in Ask/Edit/Agent mode
+2. slash command invocation of a prompt or skill
+3. chat request with manually attached MCP resources
+
+Each surface changes how much discovery Copilot must do before applying guidance.
+
+### Resolution Order
+
+When multiple retrieval paths are possible, use this priority order:
+
+1. attached MCP resources already in context
+2. explicit slash-command workflow steps
+3. catalog-first discovery via MCP resources
+4. tool fallback (`list_resources` then `read_resource`, then thin catalog parity tools)
+
+This ordering keeps behavior predictable while minimizing unnecessary context expansion.
+
+### Prompt Invocation Pipeline
+
+For prompt-oriented flows, treat invocation as this sequence:
+
+1. parse prompt frontmatter and argument hints
+2. validate required inputs and ask one clarifying question if blocked
+3. run bounded discovery against prompt or skill catalogs
+4. fetch only selected document resources
+5. apply instructions to produce edits, recommendations, or commands
+6. report what was loaded and why
+
+Prompt objects and prompt document resources are additive mechanisms. The authored Markdown prompt document remains the canonical contract.
+
+### Argument Syntax Nuance
+
+Invocation strings such as target_modules=src/personal_mcp/registry/ingest/skill.py, mode=plan-only are a structured authoring convention, not a guaranteed client-level grammar.
+
+In practice:
+
+1. Prompt metadata defines expected argument names and intent.
+2. Prompt body instructions define how those inputs should be interpreted.
+3. Copilot may receive equivalent intent in freeform phrasing and still resolve it correctly.
+
+Implication for authors:
+
+1. Treat key=value examples as clarity aids for users.
+2. Do not assume strict parser enforcement unless your prompt explicitly validates and rejects malformed input.
+3. Include accepted invocation examples and one fallback freeform example so behavior is predictable for both humans and the model.
+
+This distinction is important because argument hints improve discoverability, while robust prompt instructions determine actual runtime reliability.
+
+### Skill Invocation Pipeline
+
+For guided skill loading, use this sequence:
+
+1. start from `resource://catalog/skills_index` or scoped index query
+2. inspect one or two top candidates for intent and capability fit
+3. fetch `resource://skills/<skill-id>/document`
+4. load references only when the task needs deeper detail
+5. apply only relevant sections and keep context bounded
+
+This avoids the common failure mode where many skill documents are loaded up front.
+
+### Determinism vs Flexibility
+
+Use this decision rule:
+
+1. choose slash-command invocation when repeatability and step order are critical
+2. choose guided loading when requests vary and speed matters more than strict orchestration
+3. escalate from guided loading to slash-command flow when confidence is low or conflicting skills appear
+
+### Invocation Trace (What to Log in Results)
+
+For transparent operation, include a concise invocation trace in task outputs:
+
+1. entry surface used (plain chat, slash command, or attached resource)
+2. discovery source used (catalog resource or tool path)
+3. resources fetched (ids only)
+4. clarifying questions asked (if any)
+5. reason for fallback or escalation (if used)
+
+This makes behavior auditable and easier to tune over time.
+
 ## Operating Pattern
 
 Use both modes intentionally in Copilot Chat.
@@ -124,16 +226,9 @@ flowchart TD
     H --> I
 ```
 
-## Authoring Requirements For Reliable Matching
+## Authoring Requirements
 
-For resource selection or tool-based matching to work well, each skill should have:
-
-1. precise `description`
-2. focused `tags`
-3. explicit `capabilities`
-4. stable `id` and slug naming
-
-Weak metadata reduces Copilot match quality and increases wrong context injection.
+Authoring rules for metadata quality and instruction patterns are maintained in [Authoring Guide](./authoring.md).
 
 ## Practical Guidelines
 
@@ -161,54 +256,6 @@ Behavior:
 2. `bm25` uses ranked natural-language matching.
 3. `list_resources` and `read_resource` stay visible so resource-backed fallback remains primary.
 
-## Copilot Instruction Pattern
-
-If you want Copilot to use `personal-mcp` skill content more reliably, the instruction file should describe three things clearly:
-
-1. when MCP-backed skill guidance is relevant
-2. which retrieval path Copilot should prefer first
-3. how much skill context it should load before answering
-
-That matters because instructions can strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. A good instruction tells Copilot to prefer the canonical MCP content path while remaining accurate about the fallback path.
-
-In this repository, the right policy is:
-
-1. start from catalog discovery
-2. prefer MCP resources when the current chat surface exposes resource attachment
-3. fall back to catalog tools when resource attachment is unavailable
-4. keep loaded skill context bounded
-
-Suggested instruction text:
-
-```md
-When a task may match a documented implementation pattern from `personal-mcp`:
-
-1. Start with catalog-first discovery.
-2. Prefer MCP resources when the chat surface exposes resource attachment.
-3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
-4. Load only the most relevant skill document, or at most 2 skill documents.
-5. Reconcile loaded skill guidance with the actual repository code before making changes.
-
-Preferred resource order:
-
-1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
-3. `resource://skills/<skill-id>/document`
-4. `resource://skills/<skill-id>/references/<ref-id>` when needed
-
-Preferred tool fallback order:
-
-1. `list_resources`
-2. `read_resource`
-3. `search_patterns`
-4. `get_pattern_by_id`
-5. `get_skill_document_by_id`
-
-If confidence is low after discovery, ask one clarifying question before loading more context.
-```
-
-This is intentionally guidance, not a guarantee. It gives Copilot a strong policy for when to use resources and when to fall back to discovery tools, while preserving the resource-first architecture.
-
 ## Failure Modes and Recovery
 
 Common failure modes:
@@ -234,11 +281,13 @@ Use this checklist when configuring GitHub Copilot in VS Code against `personal-
 2. verify catalog resources are readable
 3. verify at least one `resource://skills/<id>/document` can be fetched
 4. add one deterministic `/` command for fallback
-5. add Copilot instruction: prefer catalog-first discovery, then targeted skill fetch
+5. confirm your workspace instruction policy exists (see [Authoring Guide](./authoring.md))
 6. verify context size remains bounded
 7. validate behavior in Ask/Edit/Agent-style workflows with at least one task each
 
-Suggested instruction policy text:
+## Runtime Discovery Workflow
+
+Use this runtime sequence in chat sessions:
 
 1. Start with catalog-first discovery.
 2. Prefer MCP resources when the chat surface exposes resource attachment.
@@ -246,6 +295,66 @@ Suggested instruction policy text:
 4. Prefer `list_resources`/`read_resource` first when operating in tool-only clients.
 5. If confidence is low, ask one clarifying question before loading more.
 
+## Thin Shim Path Binding Pattern
+
+For repositories that consume this MCP server, thin shims are a usage pattern for binding path scopes to the right MCP resources. The "thin shims" are just lightweight, repo-specific instructions files that tell Copilot to use certain MCP resources when editing files that match a pattern. That helps with ensuring Copilot uses the intended resources without too much specific goading in the prompt.
+
+Use thin shims in Copilot instruction files to bind file-path scopes to:
+
+1. the most relevant docs page for human-readable conventions
+2. the matching MCP resource URI for machine retrieval
+
+Keep each shim short: trigger, primary resource, minimal execution pattern, and one fallback rule.
+
+Recommended binding pattern:
+
+1. Put shims in `.github/instructions/*.instructions.md`.
+2. Scope each shim with `applyTo` so it activates only where needed.
+3. Point to one primary `resource://skills/<skill-id>/document` URI.
+4. Link one repository docs page as the human-facing companion.
+5. Expand to references only when the task needs deeper detail.
+
+Current repository examples:
+
+| applyTo scope | Primary docs page | Primary MCP resource |
+| --- | --- | --- |
+| `**/*.md` | [docs/authoring.md](./authoring.md) | `resource://skills/zensical-docs/document` |
+| `tests/**` | [docs/testing.md](./testing.md) | `resource://skills/pytesting/document` |
+| `.vscode/**` | [docs/skills/vscode-configuration/SKILL.md](./skills/vscode-configuration/SKILL.md) | `resource://skills/vscode-configuration/document` |
+
+Minimal shim shape:
+
+```md
+---
+name: <short scope name>
+description: Route <path scope> edits to the Personal MCP <skill-id> resource.
+applyTo: '<glob>'
+---
+
+When editing files matching <glob>, use `resource://skills/<skill-id>/document` as the primary guidance source.
+
+Execution pattern:
+
+1. Load the primary skill document first.
+2. Apply only sections relevant to the file being edited.
+3. Keep edits minimal and aligned with repository conventions.
+4. If confidence is low, ask one clarifying question before editing.
+
+Companion docs page: [docs/<page>.md](./<page>.md)
+```
+
+When to use thin shims:
+
+1. Repositories that want thin local policy while keeping canonical guidance in MCP resources.
+2. Stable, repeated workflows with clear path ownership.
+3. Cases where teams need predictable retrieval behavior.
+
+When not to use thin shims:
+
+1. Broad, ambiguous tasks with unclear ownership boundaries.
+2. Cases where one shim would need many exceptions.
+3. Situations better handled by catalog-first discovery at runtime.
+
 ## Summary
 
 The intended model is:

pyproject.toml

@@ -6,6 +6,7 @@ dependencies = [
     "fastapi>=0.115.0",
     "fastmcp>=2.10.0",
     "pydantic-settings>=2.0.0",
+    "python-json-logger>=4.1.0",
     "pyyaml>=6.0.2",
     "uvicorn[standard]>=0.34.0",
     "zensical>=0.0.45",
@@ -23,6 +24,26 @@ packages = ["src/personal_mcp"]
 
 [dependency-groups]
 dev = [
+    "ipywidgets>=8.1.8",
     "pre-commit>=4.6.0",
     "ruff>=0.15.18",
+    "ty>=0.0.51",
 ]
+test = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.pytest.ini_options]
+addopts = ["--strict-markers"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "unit: fast deterministic tests with no external dependencies",
+    "integration: framework or component integration tests",
+    "smoke: thin critical-path checks",
+]
+
+[tool.ty.src]
+include = ["src", "tests"]

ruff.toml

@@ -0,0 +1,63 @@
+line-length = 120
+indent-width = 4
+target-version = "py313"
+
+exclude = [
+    ".venv",
+    ".devenv",
+    ".git",
+    ".vscode",
+    "build",
+    "site",
+    "__pycache__",
+]
+
+[lint]
+preview = true
+
+extend-select = [
+    "ARG",      # https://docs.astral.sh/ruff/rules/#flake8-unused-arguments-arg
+	"B",        # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
+	"C4",       # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
+    "DOC102",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-parameter/
+    "DOC202",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-returns/
+    "DOC403",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-yields/
+    "DOC502",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-exception/
+	"E", "W",   # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
+	"F",        # https://docs.astral.sh/ruff/rules/#pyflakes-f
+    "FURB",     # https://docs.astral.sh/ruff/rules/#refurb-furb
+	"I",        # https://docs.astral.sh/ruff/rules/#isort-i
+    "N",        # https://docs.astral.sh/ruff/rules/#pep8-naming-n
+    "PD",       # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
+    "PTH",      # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+	"UP",       # https://docs.astral.sh/ruff/rules/#pyupgrade-up
+	"SIM",      # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
+    "PLR0202",  # https://docs.astral.sh/ruff/rules/no-classmethod-decorator/
+    "PLR0203",  # https://docs.astral.sh/ruff/rules/no-staticmethod-decorator/
+    "PLR0206",  # https://docs.astral.sh/ruff/rules/property-with-parameters/
+    "PLR0915",  # https://docs.astral.sh/ruff/rules/too-many-statements/
+    "PLR1702",  # https://docs.astral.sh/ruff/rules/too-many-nested-blocks/
+    "TRY002",
+]
+extend-fixable = ["ALL"]
+ignore = [
+    "UP046",
+    "UP047",
+]
+
+[lint.extend-per-file-ignores]
+"*.ipynb" = [
+    "F401", # unused imports
+    "F841", # unused local variable
+    "F821", # undefined name in exploratory notebook cells,
+    "LOG015", # root logger calls
+]
+
+[lint.isort]
+force-single-line = true
+
+[format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

scripts/link_skill.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Create directory and symlink for Copilot skills."""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def add_skill(markdown_path: str) -> None:
+    """Add a skill by creating symlink in ~/.copilot/skills/.
+
+    Args:
+        markdown_path: Path to the markdown file (relative or absolute)
+
+    Raises:
+        FileNotFoundError: If markdown file doesn't exist
+        RuntimeError: If symlink creation fails
+    """
+    md_file = Path(markdown_path)
+
+    if not md_file.exists():
+        raise FileNotFoundError(f"Markdown file not found: {markdown_path}")
+
+    # Get absolute path
+    abs_md_path = md_file.resolve()
+
+    # Extract skill name from filename (without .md extension)
+    skill_name = md_file.stem
+
+    # Create skill directory
+    skills_dir = Path.home() / ".copilot" / "skills" / skill_name
+    skills_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create symlink
+    symlink_path = skills_dir / "SKILL.md"
+
+    # Remove existing symlink if it exists
+    if symlink_path.exists() or symlink_path.is_symlink():
+        symlink_path.unlink()
+
+    # Create the symlink using ln -s for compatibility
+    result = subprocess.run(
+        ["ln", "-s", str(abs_md_path), str(symlink_path)],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(f"Failed to create symlink: {result.stderr}")
+
+    print(f"✓ Created skill link: {symlink_path} -> {abs_md_path}")
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Create directory and symlink for Copilot skills")
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # Add subcommand
+    add_parser = subparsers.add_parser("add", help="Add a skill")
+    add_parser.add_argument("markdown", help="Path to markdown skill file")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "add":
+        try:
+            add_skill(args.markdown)
+        except (FileNotFoundError, RuntimeError, OSError) as e:
+            print(f"✗ Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/personal_mcp/catalog/__init__.py

@@ -1,13 +1,19 @@
-from personal_mcp.catalog.server import (
-    build_skill_detail_payload,
-    build_skills_index_payload,
-    get_pattern_by_id_payload,
-    search_patterns_payload,
-)
+from personal_mcp.catalog.server import build_prompt_detail_payload
+from personal_mcp.catalog.server import build_prompts_index_payload
+from personal_mcp.catalog.server import build_skill_detail_payload
+from personal_mcp.catalog.server import build_skills_index_payload
+from personal_mcp.catalog.server import get_pattern_by_id_payload
+from personal_mcp.catalog.server import get_prompt_by_id_payload
+from personal_mcp.catalog.server import search_patterns_payload
+from personal_mcp.catalog.server import search_prompts_payload
 
 __all__ = [
+    "build_prompt_detail_payload",
+    "build_prompts_index_payload",
     "build_skill_detail_payload",
     "build_skills_index_payload",
     "get_pattern_by_id_payload",
+    "get_prompt_by_id_payload",
     "search_patterns_payload",
+    "search_prompts_payload",
 ]

src/personal_mcp/catalog/server.py

@@ -2,45 +2,17 @@ from __future__ import annotations
 
 from typing import Any
 
-from personal_mcp.skills.document_loader import DocsRegistry, SkillRecord
+from personal_mcp.registry.models.registry import DocsRegistry
+from personal_mcp.registry.models.registry import PromptRecord
+from personal_mcp.registry.models.registry import PromptSummaryPayload
+from personal_mcp.registry.models.registry import SkillPatternPayload
+from personal_mcp.registry.models.registry import SkillRecord
+from personal_mcp.registry.models.registry import SkillSummaryPayload
 
 DEFAULT_LIMIT = 20
 MAX_LIMIT = 100
 
 
-def _pattern_payload(skill: SkillRecord) -> dict[str, Any]:
-    return {
-        "id": skill.skill_id,
-        "name": skill.name,
-        "version": skill.version,
-        "description": skill.description,
-        "tags": list(skill.tags),
-        "depends_on": list(skill.depends_on),
-        "capabilities": list(skill.capabilities),
-        "resources": list(skill.capabilities),
-    }
-
-
-def _summary_payload(skill: SkillRecord) -> dict[str, Any]:
-    return {
-        "id": skill.skill_id,
-        "name": skill.name,
-        "description": skill.description,
-        "tags": list(skill.tags),
-        "capabilities": list(skill.capabilities),
-        "version": skill.version,
-        "document_uri": skill.document_uri,
-        "detail_uri": f"resource://catalog/skills/{skill.skill_id}",
-        "resources": {
-            "document": skill.document_uri,
-            "references": [
-                f"resource://skills/{skill.skill_id}/references/{ref_id}"
-                for ref_id in sorted(skill.references)
-            ],
-        },
-    }
-
-
 def _skill_matches(
     skill: SkillRecord,
     *,
@@ -66,10 +38,32 @@ def _skill_matches(
     if tag and tag not in skill.tags:
         return False
 
-    if capability and capability not in skill.capabilities:
+    return not (capability and capability not in skill.capabilities)
+
+
+def _prompt_matches(
+    prompt: PromptRecord,
+    *,
+    query: str | None,
+    tag: str | None,
+) -> bool:
+    if query:
+        lowered = query.strip().lower()
+        if lowered:
+            haystack = " ".join(
+                [
+                    prompt.prompt_id,
+                    prompt.name,
+                    prompt.description,
+                    " ".join(prompt.tags),
+                    " ".join(sorted(prompt.arguments)),
+                ]
+            ).lower()
+            terms = [term for term in lowered.replace("-", " ").split() if term]
+            if any(term not in haystack for term in terms):
                 return False
 
-    return True
+    return not (tag and tag not in prompt.tags)
 
 
 def build_skills_index_payload(
@@ -87,20 +81,14 @@ def build_skills_index_payload(
     except ValueError as exc:
         raise ValueError("cursor must be an integer string") from exc
 
-    ordered = [
-        registry.skills_by_id[skill_id] for skill_id in registry.skills_in_load_order
-    ]
-    matches = [
-        skill
-        for skill in ordered
-        if _skill_matches(skill, query=query, tag=tag, capability=capability)
-    ]
+    ordered = [registry.skills_by_id[skill_id] for skill_id in registry.skills_in_load_order]
+    matches = [skill for skill in ordered if _skill_matches(skill, query=query, tag=tag, capability=capability)]
 
     page = matches[start : start + normalized_limit]
     next_cursor = start + normalized_limit
 
     return {
-        "skills": [_summary_payload(skill) for skill in page],
+        "skills": [SkillSummaryPayload.from_record(skill).model_dump() for skill in page],
         "total": len(matches),
         "cursor": str(start),
         "limit": normalized_limit,
@@ -119,7 +107,6 @@ def build_skill_detail_payload(registry: DocsRegistry, skill_id: str) -> dict[st
         "description": skill.description,
         "version": skill.version,
         "tags": list(skill.tags),
-        "depends_on": list(skill.depends_on),
         "capabilities": list(skill.capabilities),
         "resources": {
             "document": skill.document_uri,
@@ -128,7 +115,7 @@ def build_skill_detail_payload(registry: DocsRegistry, skill_id: str) -> dict[st
                     "uri": ref.uri,
                     "mime_type": ref.mime_type,
                     "title": ref.title,
-                    "path": ref.relpath,
+                    "path": ref.relpath.as_posix(),
                 }
                 for ref_id, ref in sorted(skill.references.items())
             },
@@ -136,6 +123,56 @@ def build_skill_detail_payload(registry: DocsRegistry, skill_id: str) -> dict[st
     }
 
 
+def build_prompts_index_payload(
+    registry: DocsRegistry,
+    *,
+    query: str | None = None,
+    tag: str | None = None,
+    cursor: str | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    normalized_limit = DEFAULT_LIMIT if limit is None else max(1, min(limit, MAX_LIMIT))
+    try:
+        start = 0 if cursor is None else max(0, int(cursor))
+    except ValueError as exc:
+        raise ValueError("cursor must be an integer string") from exc
+
+    ordered = [registry.prompts_by_id[prompt_id] for prompt_id in registry.prompts_in_load_order]
+    matches = [prompt for prompt in ordered if _prompt_matches(prompt, query=query, tag=tag)]
+
+    page = matches[start : start + normalized_limit]
+    next_cursor = start + normalized_limit
+
+    return {
+        "prompts": [PromptSummaryPayload.from_record(prompt).model_dump() for prompt in page],
+        "total": len(matches),
+        "cursor": str(start),
+        "limit": normalized_limit,
+        "next_cursor": str(next_cursor) if next_cursor < len(matches) else None,
+    }
+
+
+def build_prompt_detail_payload(registry: DocsRegistry, prompt_id: str) -> dict[str, Any]:
+    if prompt_id not in registry.prompts_by_id:
+        raise KeyError(prompt_id)
+
+    prompt = registry.prompts_by_id[prompt_id]
+    return {
+        "id": prompt.prompt_id,
+        "name": prompt.name,
+        "description": prompt.description,
+        "version": prompt.version,
+        "tags": list(prompt.tags),
+        "capabilities": list(prompt.capabilities),
+        "resources": {
+            "document": prompt.document_uri,
+        },
+        "arguments": {
+            arg_name: arg.model_dump(exclude_none=True) for arg_name, arg in sorted(prompt.arguments.items())
+        },
+    }
+
+
 def search_patterns_payload(
     registry: DocsRegistry,
     *,
@@ -160,7 +197,7 @@ def search_patterns_payload(
 
     page = matches[normalized_skip : normalized_skip + normalized_limit]
     return {
-        "patterns": [_pattern_payload(skill) for skill in page],
+        "patterns": [SkillPatternPayload.from_record(skill).model_dump() for skill in page],
         "total": len(matches),
         "skip": normalized_skip,
         "limit": normalized_limit,
@@ -170,4 +207,44 @@ def search_patterns_payload(
 def get_pattern_by_id_payload(registry: DocsRegistry, skill_id: str) -> dict[str, Any]:
     if skill_id not in registry.skills_by_id:
         return {"found": False, "id": skill_id}
-    return {"found": True, "pattern": _pattern_payload(registry.skills_by_id[skill_id])}
+    return {"found": True, "pattern": SkillPatternPayload.from_record(registry.skills_by_id[skill_id]).model_dump()}
+
+
+def search_prompts_payload(
+    registry: DocsRegistry,
+    *,
+    query: str = "",
+    tags: list[str] | None = None,
+    skip: int = 0,
+    limit: int = DEFAULT_LIMIT,
+) -> dict[str, Any]:
+    normalized_skip = max(skip, 0)
+    normalized_limit = max(1, min(limit, MAX_LIMIT))
+
+    requested_tags = [tag.strip() for tag in (tags or []) if tag and tag.strip()]
+
+    matches: list[PromptRecord] = []
+    for prompt_id in registry.prompts_in_load_order:
+        prompt = registry.prompts_by_id[prompt_id]
+        if not _prompt_matches(prompt, query=query, tag=None):
+            continue
+        if requested_tags and any(tag not in prompt.tags for tag in requested_tags):
+            continue
+        matches.append(prompt)
+
+    page = matches[normalized_skip : normalized_skip + normalized_limit]
+    return {
+        "prompts": [PromptSummaryPayload.from_record(prompt).model_dump() for prompt in page],
+        "total": len(matches),
+        "skip": normalized_skip,
+        "limit": normalized_limit,
+    }
+
+
+def get_prompt_by_id_payload(registry: DocsRegistry, prompt_id: str) -> dict[str, Any]:
+    if prompt_id not in registry.prompts_by_id:
+        return {"found": False, "id": prompt_id}
+    return {
+        "found": True,
+        "prompt": build_prompt_detail_payload(registry, prompt_id),
+    }

src/personal_mcp/config.py

@@ -0,0 +1,43 @@
+from functools import cache
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic import DirectoryPath
+from pydantic import Field
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+DEFAULT_ENV_FILE = Path(".env").resolve()
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+class Mounts(BaseModel):
+    docs: str = "/docs"
+    mcp: str = "/mcp"
+
+
+class Settings(BaseSettings):
+    """Runtime settings for the HTTP MCP and docs server."""
+
+    model_config = SettingsConfigDict(
+        env_file=DEFAULT_ENV_FILE,
+        env_prefix="PERSONAL_MCP_",
+        extra="ignore",
+    )
+
+    debug: bool = False
+    log_level: str = "info"
+    mounts: Mounts = Field(default_factory=Mounts)
+    mcp_transport: Literal["http", "sse"] = "http"
+    site_dir: DirectoryPath = Field(default=_REPO_ROOT / "site")
+
+
+@cache
+def get_settings(**overrides) -> Settings:
+    return Settings(**overrides)
+
+
+def refresh_settings(**overrides):
+    get_settings.cache_clear()
+    return get_settings(**overrides)

src/personal_mcp/docs

@@ -0,0 +1 @@
+../../docs

src/personal_mcp/main.py

@@ -1,12 +1,19 @@
-from personal_mcp.mcp import mcp
-from personal_mcp.web.app import app
+from fastapi import FastAPI
 
-__all__ = ["app", "main", "mcp"]
+from personal_mcp.mcp import create_mcp
+from personal_mcp.web.app import create_app as create_fastapi
+
+__all__ = ["create_app", "main"]
+
+
+def create_app() -> FastAPI:
+    """Create the HTTP application for ASGI servers using factory mode."""
+    return create_fastapi()
 
 
 def main() -> None:
     """Run the root MCP server."""
-    mcp.run()
+    create_mcp().run()
 
 
 if __name__ == "__main__":

src/personal_mcp/mcp.py

@@ -1,35 +1,34 @@
 from __future__ import annotations
 
 import os
+import re
+from inspect import Parameter
+from inspect import Signature
 from typing import Any
+from typing import cast
 
 from fastmcp import FastMCP
 from fastmcp.server.transforms import ResourcesAsTools
-from fastmcp.server.transforms.search import BM25SearchTransform, RegexSearchTransform
+from fastmcp.server.transforms.search import BM25SearchTransform
+from fastmcp.server.transforms.search import RegexSearchTransform
 
-from personal_mcp.catalog.server import (
-    build_skill_detail_payload,
-    build_skills_index_payload,
-    get_pattern_by_id_payload,
-    search_patterns_payload,
-)
-from personal_mcp.skills.document_loader import (
-    DocsRegistry,
-    load_docs_registry,
-    read_docs_markdown_path,
-    read_skill_document,
-    read_skill_reference,
-)
+from personal_mcp.catalog.server import build_prompt_detail_payload
+from personal_mcp.catalog.server import build_prompts_index_payload
+from personal_mcp.catalog.server import build_skill_detail_payload
+from personal_mcp.catalog.server import build_skills_index_payload
+from personal_mcp.catalog.server import get_pattern_by_id_payload
+from personal_mcp.catalog.server import get_prompt_by_id_payload
+from personal_mcp.catalog.server import search_patterns_payload
+from personal_mcp.catalog.server import search_prompts_payload
+from personal_mcp.registry.load import get_docs_registry
+from personal_mcp.registry.models.registry import DocsRegistry
+from personal_mcp.registry.read import read_docs_markdown_path
+from personal_mcp.registry.read import read_prompt_document
+from personal_mcp.registry.read import read_skill_document
+from personal_mcp.registry.read import read_skill_reference
 
-DOCS_ROOT = os.getenv("PERSONAL_MCP_DOCS_ROOT", "../../docs")
 TOOL_SEARCH_MODE = os.getenv("PERSONAL_MCP_TOOL_SEARCH", "none").strip().lower()
 TOOL_SEARCH_MAX_RESULTS = os.getenv("PERSONAL_MCP_TOOL_SEARCH_MAX_RESULTS", "5")
-REGISTRY: DocsRegistry = load_docs_registry(
-    package_anchor="personal_mcp",
-    docs_root=DOCS_ROOT,
-)
-
-mcp = FastMCP("personal-mcp", on_duplicate="error")
 
 
 def _parse_positive_int(value: str, *, env_name: str) -> int:
@@ -42,7 +41,7 @@ def _parse_positive_int(value: str, *, env_name: str) -> int:
     return parsed
 
 
-def _install_tool_fallback_transforms() -> None:
+def _install_tool_fallback_transforms(mcp: FastMCP) -> None:
     # Expose list_resources/read_resource for tool-only clients.
     mcp.add_transform(ResourcesAsTools(mcp))
 
@@ -65,9 +64,7 @@ def _install_tool_fallback_transforms() -> None:
         mcp.add_transform(BM25SearchTransform(**kwargs))
         return
 
-    raise ValueError(
-        "PERSONAL_MCP_TOOL_SEARCH must be one of: none, regex, bm25"
-    )
+    raise ValueError("PERSONAL_MCP_TOOL_SEARCH must be one of: none, regex, bm25")
 
 
 def _ro_annotations() -> dict[str, bool]:
@@ -77,6 +74,55 @@ def _ro_annotations() -> dict[str, bool]:
     }
 
 
+def _render_prompt_markdown(content: str, arguments: dict[str, Any]) -> str:
+    rendered = content
+    for key, value in arguments.items():
+        rendered = rendered.replace(f"{{{{{key}}}}}", str(value))
+    return rendered
+
+
+def _make_prompt_handler(content: str):
+    def prompt_handler(**kwargs: Any) -> str:
+        return _render_prompt_markdown(content, kwargs)
+
+    return prompt_handler
+
+
+def _register_prompt_objects(mcp: FastMCP, registry: DocsRegistry) -> None:
+    for prompt_id in registry.prompts_in_load_order:
+        prompt = registry.prompts_by_id[prompt_id]
+        annotations: dict[str, Any] = {}
+        params: list[Parameter] = []
+
+        for arg_name, arg in sorted(prompt.arguments.items()):
+            annotations[arg_name] = str
+            default = Parameter.empty if arg.required else None
+            params.append(
+                Parameter(
+                    arg_name,
+                    kind=Parameter.KEYWORD_ONLY,
+                    default=default,
+                    annotation=str,
+                )
+            )
+
+        signature = Signature(parameters=params, return_annotation=str)
+
+        prompt_handler = _make_prompt_handler(prompt.document_content)
+
+        prompt_handler.__name__ = re.sub(r"[^a-zA-Z0-9_]", "_", prompt_id)
+        prompt_handler.__doc__ = prompt.description
+        prompt_handler.__annotations__ = annotations
+        cast(Any, prompt_handler).__signature__ = signature
+        mcp.prompt(
+            prompt_handler,
+            name=prompt_id,
+            description=prompt.description,
+            tags=set(prompt.tags),
+        )
+
+
+def _register_components(mcp: FastMCP, registry: DocsRegistry) -> None:
     @mcp.resource(
         "resource://catalog/skills_index",
         mime_type="application/json",
@@ -84,8 +130,7 @@ def _ro_annotations() -> dict[str, bool]:
         annotations=_ro_annotations(),
     )
     def skills_index() -> dict[str, Any]:
-    return build_skills_index_payload(REGISTRY)
-
+        return build_skills_index_payload(registry)
 
     @mcp.resource(
         "resource://catalog/skills_index{?q,tag,capability,cursor,limit}",
@@ -101,7 +146,7 @@ def skills_index_query(
         limit: int | None = None,
     ) -> dict[str, Any]:
         return build_skills_index_payload(
-        REGISTRY,
+            registry,
             query=q,
             tag=tag,
             capability=capability,
@@ -109,7 +154,6 @@ def skills_index_query(
             limit=limit,
         )
 
-
     @mcp.resource(
         "resource://catalog/skills/{skill_id}",
         mime_type="application/json",
@@ -117,8 +161,7 @@ def skills_index_query(
         annotations=_ro_annotations(),
     )
     def skill_detail(skill_id: str) -> dict[str, Any]:
-    return build_skill_detail_payload(REGISTRY, skill_id)
-
+        return build_skill_detail_payload(registry, skill_id)
 
     @mcp.resource(
         "resource://skills/{skill_id}/document",
@@ -127,8 +170,7 @@ def skill_detail(skill_id: str) -> dict[str, Any]:
         annotations=_ro_annotations(),
     )
     def skill_document(skill_id: str) -> dict[str, str]:
-    return read_skill_document(REGISTRY, skill_id)
-
+        return read_skill_document(registry, skill_id)
 
     @mcp.resource(
         "resource://skills/{skill_id}/references/{ref_id}",
@@ -137,8 +179,7 @@ def skill_document(skill_id: str) -> dict[str, str]:
         annotations=_ro_annotations(),
     )
     def skill_reference(skill_id: str, ref_id: str) -> dict[str, str]:
-    return read_skill_reference(REGISTRY, skill_id=skill_id, ref_id=ref_id)
-
+        return read_skill_reference(registry, skill_id=skill_id, ref_id=ref_id)
 
     @mcp.resource(
         "resource://docs/{path*}",
@@ -147,8 +188,54 @@ def skill_reference(skill_id: str, ref_id: str) -> dict[str, str]:
         annotations=_ro_annotations(),
     )
     def docs_markdown(path: str) -> dict[str, str]:
-    return read_docs_markdown_path(REGISTRY, path)
+        return read_docs_markdown_path(registry, path)
 
+    @mcp.resource(
+        "resource://catalog/prompts_index",
+        mime_type="application/json",
+        tags={"catalog"},
+        annotations=_ro_annotations(),
+    )
+    def prompts_index() -> dict[str, Any]:
+        return build_prompts_index_payload(registry)
+
+    @mcp.resource(
+        "resource://catalog/prompts_index{?q,tag,cursor,limit}",
+        mime_type="application/json",
+        tags={"catalog"},
+        annotations=_ro_annotations(),
+    )
+    def prompts_index_query(
+        q: str | None = None,
+        tag: str | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        return build_prompts_index_payload(
+            registry,
+            query=q,
+            tag=tag,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    @mcp.resource(
+        "resource://catalog/prompts/{prompt_id}",
+        mime_type="application/json",
+        tags={"catalog"},
+        annotations=_ro_annotations(),
+    )
+    def prompt_detail(prompt_id: str) -> dict[str, Any]:
+        return build_prompt_detail_payload(registry, prompt_id)
+
+    @mcp.resource(
+        "resource://prompts/{prompt_id}/document",
+        mime_type="text/markdown",
+        tags={"prompt-doc"},
+        annotations=_ro_annotations(),
+    )
+    def prompt_document(prompt_id: str) -> dict[str, str]:
+        return read_prompt_document(registry, prompt_id)
 
     @mcp.tool
     def search_patterns(
@@ -159,30 +246,55 @@ def search_patterns(
     ) -> dict[str, Any]:
         """Search normalized pattern metadata with optional tags and pagination."""
         return search_patterns_payload(
-        REGISTRY,
+            registry,
             query=query,
             tags=tags,
             skip=skip,
             limit=limit,
         )
 
-
     @mcp.tool
     def get_pattern_by_id(id: str) -> dict[str, Any]:
         """Return one normalized pattern by stable id."""
-    return get_pattern_by_id_payload(REGISTRY, id)
-
+        return get_pattern_by_id_payload(registry, id)
 
     @mcp.tool
     def get_skill_document_by_id(skill_id: str) -> dict[str, Any]:
         """Return the canonical skill document payload for a stable skill id."""
-    if skill_id not in REGISTRY.skills_by_id:
+        if skill_id not in registry.skills_by_id:
             return {"found": False, "id": skill_id}
 
         return {
             "found": True,
-        "document": read_skill_document(REGISTRY, skill_id),
+            "document": read_skill_document(registry, skill_id),
         }
 
+    @mcp.tool
+    def search_prompts(
+        query: str = "",
+        tags: list[str] | None = None,
+        skip: int = 0,
+        limit: int = 20,
+    ) -> dict[str, Any]:
+        """Search prompt metadata with optional tags and pagination."""
+        return search_prompts_payload(
+            registry,
+            query=query,
+            tags=tags,
+            skip=skip,
+            limit=limit,
+        )
 
-_install_tool_fallback_transforms()
+    @mcp.tool
+    def get_prompt_by_id(prompt_id: str) -> dict[str, Any]:
+        """Return one prompt by stable id."""
+        return get_prompt_by_id_payload(registry, prompt_id)
+
+
+def create_mcp() -> FastMCP:
+    registry = get_docs_registry()
+    mcp = FastMCP("personal-mcp", on_duplicate="error")
+    _register_components(mcp, registry)
+    _register_prompt_objects(mcp, registry)
+    _install_tool_fallback_transforms(mcp)
+    return mcp