shims

.github/instructions/new-skill.instructions.md

@@ -0,0 +1,16 @@
+---
+name: New Skill Configuration
+description: Route docs/skills edits to the Personal MCP new-skill resource.
+applyTo: 'docs/skills/**/*.md'
+---
+
+When editing files under `docs/skills/`, use `resource://skills/new-skill/document` as the primary guidance source for skill structure and authoring decisions.
+
+Execution pattern:
+
+1. Load `resource://skills/new-skill/document` first.
+2. Apply only the portions relevant to the file being edited (`SKILL.md` or `references/*.md`).
+3. Keep edits minimal and aligned with repository skill conventions.
+4. Include source-document links for any feature-level recommendation.
+
+If task intent is ambiguous, ask one clarifying question before editing.

.github/instructions/pytest-scaffolding.instructions.md

@@ -0,0 +1,16 @@
+---
+name: Pytest Scaffolding Guidance
+description: Route tests edits to the Personal MCP pytest-scaffolding resource.
+applyTo: 'tests/**'
+---
+
+When editing files under `tests/`, use `resource://skills/pytest-scaffolding/document` as the primary guidance source for test scaffolding and pytest authoring decisions.
+
+Execution pattern:
+
+1. Load `resource://skills/pytest-scaffolding/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.

.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/prompts/plan-fastMcpServerGreenfield.prompt.md

@@ -3,12 +3,12 @@
 Create a docs-first FastMCP architecture where all Markdown remains in docs/ as the only source of truth, each skill is Anthropic-compatible in its own directory, skill metadata lives in SKILL.md frontmatter, and packaged docs are served through importlib.resources so stdio deployments work from installed wheels.
 
 **Steps**
-1. Phase 1: Define the end-state content contract. Confirm canonical structure as docs/skills/<skill-id>/SKILL.md plus docs/skills/<skill-id>/references/..., with strict per-skill ownership and no metadata.yaml sidecar. Also define stable skill-id rules (kebab-case, immutable after release). 
+1. Phase 1: Define the end-state content contract. Confirm canonical structure as docs/skills/<skill-id>/SKILL.md plus docs/skills/<skill-id>/references/..., with strict per-skill ownership and no metadata.yaml sidecar. Also define stable skill-id rules (kebab-case, immutable after release). Deliverable: update the current docs/ directory with the finalized end-state content contract from this step.
-2. Phase 1: Define SKILL.md frontmatter schema with Pydantic-compatible fields: id, version, name, description, tags, capabilities, depends_on, and references manifest entries. The references manifest must map logical reference ids to relative paths so each skill can reorganize references internally without changing global server code. Depends on step 1.
+2. Phase 1: Define SKILL.md frontmatter schema with Pydantic-compatible fields: id, version, name, description, tags, capabilities, depends_on, and references manifest entries. The references manifest must map logical reference ids to relative paths so each skill can reorganize references internally without changing global server code. Depends on step 1. Deliverable: update the current docs/ directory with the finalized SKILL.md frontmatter schema from this step.
-3. Phase 1: Define URI contract and lightweight compatibility 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*}. Add change-friendly guidance for evolving URIs and reference ids with optional short-lived aliases when needed. Depends on steps 1-2.
+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.
@@ -43,4 +43,4 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
 **Further Considerations**
 1. Prefer recursive references support under each skill plus frontmatter manifest ids, so skill teams can reorganize internal reference folders without URI churn.
 2. Define a hard rule that skill_id and directory name must match exactly to eliminate namespace/slug drift classes of bugs.
-3. Prefer optional, short-lived URI aliases only when active clients depend on older catalog or skill resource paths; otherwise simplify quickly.
+3. Do not provide URI aliases; client updates must track canonical URI contract changes directly.

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

@@ -0,0 +1,169 @@
+**Phase 3 Results: Packaging Contract and Surface Decoupling (Wheel/sdist Resources + Docs-Only Authoring)**
+
+This section finalizes Phase 3 by defining how authored docs are packaged as runtime resources, how runtime loading avoids filesystem assumptions, and how website and MCP distribution surfaces are decoupled while sharing one authored source.
+
+### Greenfield Framing (Normative)
+
+This Phase 3 design assumes a full refactor with intentional break-and-replace behavior:
+
+1. No compatibility shims, aliases, adapter layers, or dual-read runtime paths.
+2. No runtime dependency on repository checkout layout.
+3. Runtime docs access is package-resource-only.
+4. Canonical authoring remains in `docs/` in source control.
+
+### Research Baseline (Packaging + Runtime)
+
+Authoritative references used for this phase:
+
+1. Python `importlib.resources` docs (`files`, `Traversable`, and zip-safe behavior)
+2. Python packaging guidance for wheel/sdist data inclusion
+3. Hatchling build target configuration guidance for including non-code files
+4. Existing repository constraints from Steps 4-5 (registry-first, deterministic startup, resource-first discovery)
+
+Best-practice conclusions applied to this design:
+
+1. Package docs as build artifacts so runtime reads work from installed wheels.
+2. Keep docs source-of-truth in one place (`docs/`) and project into package resource space at build time.
+3. Avoid `Path(__file__)`/repo-root probing in runtime paths.
+4. Enforce parity across wheel and sdist so local/dev/prod behavior does not drift.
+
+### Phase 3 Responsibilities (Normative)
+
+Phase 3 MUST:
+
+1. Ensure authored markdown under `docs/` is included in wheel and sdist artifacts.
+2. Ensure runtime docs registry/document reads use `importlib.resources` only.
+3. Ensure MCP runtime behavior is independent of current working directory or checkout structure.
+4. Ensure website docs build continues to consume source `docs/` directly.
+5. Remove materialization/path-probing coupling from runtime loader code.
+6. Preserve deterministic packaged docs layout for registry/resource URI generation.
+
+### Packaging Contract (Wheel + sdist)
+
+Canonical packaging behavior:
+
+1. Source-authored docs remain at repository root: `docs/`.
+2. Build projects docs into package resource space under `personal_mcp/docs/` inside artifacts.
+3. Runtime anchor for docs loading is `importlib.resources.files("personal_mcp").joinpath("docs")`.
+4. Build artifacts MUST include:
+   - top-level docs pages used by discovery/overview
+   - `docs/skills/<skill-id>/SKILL.md`
+   - `docs/skills/<skill-id>/references/**`
+
+Parity requirements:
+
+1. Wheel and sdist contain equivalent docs content for runtime use.
+2. Missing docs resources in either artifact is a hard validation failure.
+
+### Build-System Plan (pyproject + build)
+
+Primary target file:
+
+1. `pyproject.toml`
+
+Configuration goals:
+
+1. Add explicit build inclusion rules so docs resources are shipped in wheel artifacts.
+2. Add explicit sdist inclusion rules so docs are present for source builds.
+3. Keep inclusion deterministic and auditable (no implicit glob side effects beyond intended docs content).
+4. Ensure packaged destination path matches runtime anchor (`personal_mcp/docs`).
+
+Implementation note:
+
+1. Use Hatchling-native inclusion mapping (for example force-include or equivalent target-level include mapping) to project `docs/` into package resource space.
+2. Prefer one clear packaging path over multiple fallback packaging mechanisms.
+
+### Runtime Loader Contract (No Filesystem Assumptions)
+
+Primary target file:
+
+1. `src/personal_mcp/skills/document_loader.py`
+
+Required runtime behavior:
+
+1. Remove repository-root discovery helpers and path-probing candidates.
+2. Remove metadata-based document path overrides that bypass canonical skill layout.
+3. Resolve SKILL and reference documents via package-resource-relative paths only.
+4. Keep reads UTF-8 and deterministic.
+5. Raise explicit errors for missing packaged resources; no fallback probing.
+
+Prohibited runtime behavior:
+
+1. No `Path(__file__).resolve().parents[...]` lookup for docs.
+2. No implicit fallback to source-tree `docs/` during runtime reads.
+3. No slug-guessing or namespace substitution for path recovery.
+
+### Surface Decoupling Contract (Website vs MCP)
+
+Website surface:
+
+1. Website build pipeline consumes source `docs/` directly (`uv run zensical build`).
+2. Static output (`site/`) remains a build artifact served by web mounting logic.
+
+MCP surface:
+
+1. MCP runtime serves docs from packaged resources loaded by registry/resource handlers.
+2. MCP does not read `site/` and does not depend on website build artifacts.
+
+Decoupling guarantees:
+
+1. One authored source (`docs/`), two distribution surfaces (website + MCP runtime).
+2. Changes to website serving do not alter MCP resource loading semantics.
+3. Changes to MCP runtime loader do not require website materialization logic.
+
+### Integration Plan for Existing Modules
+
+Primary integration targets:
+
+1. `pyproject.toml`: add wheel/sdist docs inclusion mapping.
+2. `src/personal_mcp/skills/document_loader.py`: replace filesystem probing with package-resource loading.
+3. `src/personal_mcp/main.py`: keep startup composition deterministic once registry/resource registration is in place.
+4. `src/personal_mcp/mcp.py`: maintain registry-driven resource composition as canonical runtime surface.
+5. `src/personal_mcp/web/docs_mount.py`: continue static-site mount behavior without coupling to MCP runtime docs loading.
+
+Cleanup targets:
+
+1. Remove obsolete references to materialization-only modules if no longer present/used.
+2. Remove dead code paths that attempt source-tree fallback loading.
+
+### Validation and Test Plan (Phase 3 Scope)
+
+Build/package validation:
+
+1. Build wheel and sdist in CI/local.
+2. Inspect artifacts to confirm `personal_mcp/docs/**` exists and includes representative skill/reference files.
+3. Install built wheel in isolated environment and verify resource reads via `importlib.resources.files(...)`.
+
+Runtime validation:
+
+1. Run MCP in an environment where repo-root docs paths are unavailable and confirm reads still succeed.
+2. Verify representative URIs resolve (skill document and reference document).
+3. Confirm startup fails clearly if required packaged docs resources are missing.
+
+Decoupling validation:
+
+1. Run `uv run zensical build` to verify website pipeline still consumes source `docs/`.
+2. Confirm MCP runtime does not require `site/` presence.
+3. Confirm web static serving behavior is unchanged when docs are built.
+
+Expected command path in this repo:
+
+1. `uv run pytest -q`
+2. `uv run zensical build`
+
+### Acceptance Criteria for Phase 3 Completion
+
+Phase 3 is complete when all are true:
+
+1. Wheel and sdist include docs resources in deterministic package paths.
+2. Runtime docs loading works from installed artifacts using `importlib.resources` only.
+3. Runtime docs loading has no checkout-path dependency and no fallback probing.
+4. Website docs build remains source-docs-driven and independent of MCP runtime loading.
+5. No compatibility shims, aliases, or dual runtime loader paths exist.
+
+### Non-goals for Phase 3
+
+1. No Step 6 discovery-tool fallback implementation details.
+2. No URI aliasing or backward-compat transition mechanics.
+3. No redesign of skill frontmatter/schema contracts already finalized in earlier steps.
+4. No web UI visual redesign or docs IA overhaul.

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

@@ -2,6 +2,10 @@
 
 This section finalizes Step 1 by defining the canonical authored content model.
 
+### Step Deliverable
+
+- Update the current `docs/` directory with the finalized Step 1 content contract from this document.
+
 ### Canonical source of truth
 
 - All authored Markdown lives under `docs/`.
@@ -51,7 +55,7 @@ Rules:
 - No underscores, spaces, dots, or uppercase characters.
 - Directory name should equal `skill-id` in each committed revision.
 - Frontmatter `id` should equal directory name in each committed revision.
-- Prefer keeping `skill-id` stable, but renames are allowed when needed if mappings are updated together.
+- Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
 
 Example valid ids:
 

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

@@ -2,6 +2,10 @@
 
 This section finalizes Step 2 by defining the canonical SKILL.md frontmatter schema, separating Anthropic-supported fields from repository extension fields, and mapping frontmatter to FastMCP-native metadata surfaces for resources and tools.
 
+### Step Deliverable
+
+- Update the current `docs/` directory with the finalized Step 2 frontmatter and metadata contract content from this document.
+
 ### Anthropic Frontmatter Support (Research Baseline)
 
 Across Anthropic API and Agent Skills specification surfaces:

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

@@ -2,6 +2,10 @@
 
 This section finalizes Step 3 by defining the canonical resource URI contract, template parameter rules, and explicit compatibility/versioning policy for URIs and reference ids.
 
+### Step Deliverable
+
+- Update the current `docs/` directory with the finalized Step 3 URI contract and compatibility policy content from this document.
+
 ### Canonical URI Surface (Normative)
 
 The public, preferred URIs are:
@@ -68,16 +72,6 @@ Contract intent:
 - Resolves only inside `docs/`.
 - This surface is markdown-only in end state (`.md` files).
 
-### Legacy URI Policy (Current-to-Target Transition)
-
-Current catalog URIs in this repo (`resource://catalog/patterns`, `resource://catalog/patterns_by_id`, `resource://catalog/skills_details`) are treated as compatibility aliases during migration.
-
-Rules:
-
-- Keep aliases only when needed for active clients.
-- Prefer simple canonical URIs for new clients.
-- Remove aliases once consumers have moved.
-
 ### URI Versioning Policy
 
 Default rule:
@@ -87,30 +81,14 @@ Default rule:
 
 Breaking-change rule:
 
-- If clients are already using an older shape, provide either:
+- Breaking changes use direct replacement of the canonical URI family.
-   - a short-lived alias, or
+- No compatibility aliases or dual URI families are maintained in this greenfield phase.
-   - a versioned URI family such as `resource://catalog/v2/...`.
-- Choose the lightest migration path that minimizes maintenance overhead.
 
 FastMCP version metadata usage:
 
 - Resource `version` metadata MAY be used for implementation/version discovery.
 - URI readability and maintainability remain the primary contract.
 
-### Deprecation Policy For URIs
-
-When deprecating a URI:
-
-1. Document the replacement URI in changelog/docs.
-2. Optionally return deprecation metadata while an alias exists.
-3. Remove deprecated aliases when no active client needs them.
-
-Recommended deprecation metadata fields in resource responses:
-
-- `deprecated: true`
-- `replacement_uri: <uri>`
-- `sunset_at: <ISO-8601 timestamp>`
-
 ### Reference ID Compatibility Policy
 
 `ref_id` is the public identifier for a reference document, separate from file path.
@@ -119,19 +97,14 @@ Rules:
 
 - Prefer keeping `ref_id` stable when practical.
 - File paths may change without URI churn as long as the mapped `ref_id` resolves.
-- If a reference is renamed, introduce a new `ref_id`; keep an alias only if clients depend on the old id.
+- If a reference is renamed, introduce a new `ref_id` and treat the old one as retired.
 - Avoid reusing retired `ref_id` values for unrelated content.
 
-Alias behavior for renamed references:
-
-- If alias is kept, old `ref_id` continues to resolve and points to the replacement.
-- Remove old alias as soon as migration is complete.
-
 ### Invariants This Contract Guarantees
 
 - One canonical URI pattern per core capability surface.
-- Fast, low-friction URI evolution with optional compatibility aliases.
+- Fast, low-friction URI evolution through direct replacement of canonical URIs.
-- Explicit migration path for catalog URI consolidation when needed.
+- A single canonical catalog URI family with no alias maintenance overhead.
 - Reference mappings can evolve with minimal churn.
 
 ### Non-goals For Step 3

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

@@ -2,6 +2,15 @@
 
 This section finalizes Step 4 by defining a production-ready docs registry loader that reads packaged docs through Python resource APIs, parses SKILL.md frontmatter, validates schema and cross-links, and builds an immutable in-memory registry keyed by skill_id.
 
+### Greenfield Framing (Normative)
+
+This Step 4 design is for the greenfield target state:
+
+1. No legacy metadata sidecars (`metadata.yaml`) are part of the runtime contract.
+2. No dual-loader compatibility path is required.
+3. Registry loading from packaged resources is the only runtime source of truth.
+4. Compatibility shims are prohibited.
+
 ### Research Baseline (Python + Design Guidance)
 
 Authoritative references used for this step:
@@ -171,11 +180,11 @@ Runtime safety rules:
 
 Primary integration target:
 
-1. Replace path-based logic in `src/personal_mcp/skills/document_loader.py` with package-resource-based registry loading.
+1. Implement the canonical package-resource-based registry loader in `src/personal_mcp/skills/document_loader.py` as the only supported runtime loader path.
 
 Catalog integration:
 
-1. Update `src/personal_mcp/catalog/server.py` to consume the shared in-memory registry instead of scanning `metadata.yaml` files.
+1. Update `src/personal_mcp/catalog/server.py` to consume the shared in-memory registry as the only catalog data source.
 2. Keep catalog payload normalization deterministic and sourced from registry records only.
 
 Startup wiring:
@@ -235,4 +244,5 @@ Step 4 is complete when all are true:
 1. No FastMCP resource registration wiring details (Step 5).
 2. No discovery-tool fallback behavior design (Step 6).
 3. No final packaging/build-system migration mechanics (Step 7).
-4. No backward-compat alias rollout mechanics beyond validation readiness.
+4. No backward-compat alias rollout mechanics in the greenfield baseline.
+5. No compatibility layer of any kind (URI aliases, dual reads, adapter shims, or legacy schema bridges).

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

@@ -2,6 +2,16 @@
 
 This section finalizes Step 5 by defining how FastMCP resources are registered from the Step 4 docs registry using RFC6570 URI templates, explicit metadata, and strict duplicate-registration safety.
 
+### Greenfield Framing (Normative)
+
+This Step 5 design is for the greenfield target state:
+
+1. Registry-driven resources are the primary and authoritative discovery/read surface.
+2. No legacy per-skill hardcoded resource registration is retained.
+3. Resource contracts are defined for net-new clients and replace prior contracts without transition shims.
+4. Step 6 tool fallback layers on top of this resource contract, not as a competing source of truth.
+5. Breaking changes are intentional in this full-refactor phase.
+
 ### Research Baseline (FastMCP + URI Templates)
 
 Authoritative references used for this step:
@@ -159,9 +169,9 @@ Wildcard docs handler:
 
 Primary composition updates:
 
-1. Introduce registry-driven registration in [src/personal_mcp/mcp.py](src/personal_mcp/mcp.py).
+1. Implement registry-driven registration in [src/personal_mcp/mcp.py](src/personal_mcp/mcp.py) as the canonical resource composition path.
 2. Keep [src/personal_mcp/main.py](src/personal_mcp/main.py) responsible for startup wiring order (load registry first, then register resources).
-3. Refactor [src/personal_mcp/catalog/server.py](src/personal_mcp/catalog/server.py) toward registry-backed handlers.
+3. Use [src/personal_mcp/catalog/server.py](src/personal_mcp/catalog/server.py) as registry-backed handlers only.
 
 Lifecycle order (required):
 
@@ -206,5 +216,6 @@ Step 5 is complete when all are true:
 1. No tool fallback discovery behavior implementation (Step 6).
 2. No packaging build inclusion mechanics (Step 7).
 3. No CI gate expansion details (Step 9).
-4. No migration shims for legacy URI aliases beyond what is needed to preserve current behavior.
+4. No migration shims for legacy URI aliases in the greenfield baseline.
 5. No ranking-strategy implementation for discovery tools beyond what is needed to preserve deterministic resource-first discovery contracts.
+6. No backward-compat resource aliases, adapter handlers, or dual registration paths.

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

@@ -0,0 +1,243 @@
+**Step 6 Results: Resource-First Discovery and Tool Fallback Contract**
+
+This section finalizes Step 6 by defining discovery behavior for clients that can attach MCP resources and the fallback behavior for clients or chat surfaces that must rely on MCP tools.
+
+### Step Deliverable
+
+- Update the current `docs/` directory with the finalized Step 6 discovery and fallback contract content from this document.
+
+### Primary Source Baseline (Repository Docs)
+
+Step 6 is based on the current project contracts in:
+
+1. `docs/architecture.md` (resource-first architecture and catalog role)
+2. `docs/usage.md` (operating flows, bounded loading, and fallback sequence)
+3. `docs/copilot.md` (client capability lanes and practical fallback behavior)
+4. `docs/mcp_layout.md` (shared content source and thin-tool fallback position)
+5. `docs/securing.md` (read-only/public-docs security invariant)
+
+Normative conclusions from those sources:
+
+1. Discovery stays resource-first.
+2. Tool fallback is allowed, thin, and read-only.
+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:
+
+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}` only when needed
+
+Rules:
+
+1. Start from catalog discovery before loading any skill document.
+2. Do not skip straight to broad document loading when catalog metadata can narrow choices first.
+3. Use `resource://docs/{path*}` only for direct authored-doc access outside skill-specific flows.
+
+### Fallback Activation Rule
+
+Fallback is used only when the active client path cannot reliably attach MCP resources (for example, tool-only chat surfaces).
+
+Rules:
+
+1. Keep the same discovery order semantics as the resource path.
+2. If resource attachment is available, prefer resources over tools.
+3. Tool fallback must never become a second authoritative content source.
+
+### Tool Fallback Surface (Normative)
+
+The fallback tool surface includes:
+
+1. `list_resources`
+2. `read_resource`
+3. `search_patterns`
+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
+2. call `read_resource` for catalog URIs and selected skill URIs
+3. use thin catalog tools only when additional metadata-first narrowing is needed
+
+Tool behavior requirements:
+
+1. read-only and idempotent semantics
+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
+
+Step 6 includes a resources-as-tools compatibility layer for clients that can call tools but not attach resources.
+
+Rules:
+
+1. It wraps canonical resource reads rather than re-implementing content transforms.
+2. It preserves canonical URIs and metadata semantics.
+3. It does not replace the minimal catalog tools listed above.
+4. It is interoperability-driven and remains read-only.
+
+### Resource/Tool Parity Contract
+
+Resources and fallback tools must agree on identity and routing metadata.
+
+Parity requirements:
+
+1. `skill_id` and `ref_id` are identical across both paths.
+2. canonical URIs in payloads match Step 3 URI rules.
+3. skill metadata (`id`, `name`, `description`, `tags`, `capabilities`, `version`) remains consistent.
+4. document payload returned by `get_skill_document_by_id` resolves to the same canonical `SKILL.md` content as `resource://skills/{skill_id}/document`.
+
+### Relevance and Ranking Contract
+
+Baseline matching behavior is metadata-first and deterministic.
+
+Rules:
+
+1. Search primarily over normalized skill metadata (id, name, description, tags).
+2. Keep deterministic ordering and deterministic pagination behavior.
+3. Keep ranking logic transparent and bounded for predictable client behavior.
+
+Optional extension policy:
+
+1. BM25/regex augmentation is allowed only when catalog/tool volume meaningfully harms token efficiency or precision.
+2. Any augmentation must preserve canonical ids, URIs, and deterministic tie-breaking.
+3. Any augmentation remains discovery-only and does not create alternate content payloads.
+
+### Context-Bounding and Clarification Policy
+
+To prevent context bloat and improve answer quality:
+
+1. load only the most relevant skill document by default
+2. load at most two skill documents in one pass unless the user explicitly asks for more
+3. if confidence is low after catalog discovery, ask one clarifying question before loading additional skill documents
+4. fetch references lazily and only when required
+
+### Security and Safety Constraints
+
+Fallback tools must preserve the project security invariant.
+
+Rules:
+
+1. tool surfaces stay documentation-only and read-only
+2. no mutation, shell execution, secret access, or private filesystem exposure
+3. all returned content remains safe to publish publicly
+
+### Integration Boundaries
+
+Step 6 integrates with prior steps as follows:
+
+1. Step 4 provides the validated in-memory registry.
+2. Step 5 provides canonical resource registration.
+3. Step 6 adds fallback discovery/read behavior that reuses the same registry and canonical markdown sources.
+
+Separation-of-concerns rule:
+
+1. Catalog/resource contracts remain canonical.
+2. Fallback tools are interoperability adapters, not a parallel architecture.
+
+### Acceptance Criteria for Step 6 Completion
+
+Step 6 is complete when all are true:
+
+1. Resource-first discovery remains the documented and implemented default path.
+2. `list_resources` and `read_resource` are available for tool-only clients.
+3. Thin catalog tools remain minimal, read-only parity surfaces.
+4. Fallback tool outputs map to canonical skill identities and URIs.
+5. Context loading is bounded and clarifying-question behavior is documented for low-confidence cases.
+6. No second content source is introduced; resources and tools resolve the same authored markdown.
+
+### Non-goals for Step 6
+
+1. No write or side-effecting tools.
+2. No alternate authored markdown stores or duplicated skill content pipelines.
+3. No guarantee that every client session exposes MCP resource attachment UI.
+4. No packaging/build contract changes (handled in Step 7).
+5. No CI gate expansion details (handled in later validation/governance steps).

.github/prompts/skill-bootstrap.prompt.md

@@ -0,0 +1,12 @@
+---
+name: New Skill Bootstrap
+description: Create and fully implement a new docs-first skill in this repository.
+argument-hint: skill-id and goal for the new skill
+agent: agent
+---
+
+# New Skill Bootstrap
+
+Use the canonical bootstrap guidance in [docs/skills/new-skill/SKILL.md](../../docs/skills/new-skill/SKILL.md).
+
+If the request is to create or implement a new skill, load that skill document and follow it as the source of truth.

docs/architecture.md

@@ -16,6 +16,18 @@ 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.
 
+This architecture is anchored by three contracts:
+
+1. Docs-first authored content contract under `docs/` with strict per-skill ownership.
+2. `SKILL.md` frontmatter contract with Anthropic fields plus `x-personal-mcp` metadata.
+3. Canonical resource URI contract with break-and-replace policy for contract changes.
+
+Detailed contract pages:
+
+1. [Content Contract](./content.md)
+2. [Frontmatter Contract](./frontmatter.md)
+3. [URI Contract](./uris.md)
+
 This architecture keeps authored content human-friendly while preserving machine-stable contracts.
 
 ## Intent
@@ -30,7 +42,14 @@ The architecture is designed to satisfy three long-term requirements:
 
 ### Pattern Modules
 
-Each module encapsulates one methodology domain and publishes resource families:
+Each skill encapsulates one methodology domain in a docs-owned directory:
+
+1. `docs/skills/<skill-id>/SKILL.md`
+2. `docs/skills/<skill-id>/references/...`
+
+The skill document and references are the authored source of truth; runtime code indexes and serves these files without becoming a second authored source.
+
+Each skill publishes resource families:
 
 1. document
 
@@ -42,10 +61,23 @@ The catalog is the canonical discovery layer and publishes normalized records fo
 
 Typical catalog resources:
 
-1. resource://catalog/patterns
+1. resource://catalog/skills_index
-2. resource://catalog/patterns_by_id
+2. resource://catalog/skills/{skill_id}
-3. resource://catalog/skills_index
+
-4. resource://catalog/skills_details
+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.
+
+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.
+
+Registry load failure is a startup error, not a partial runtime warning.
 
 ### Content Sources
 
@@ -76,27 +108,65 @@ flowchart TD
 
 ### Metadata Contract
 
-Each pattern module declares:
+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).
+
+Anthropic-facing required fields:
+
+1. name
+2. description
+
+Repository indexing metadata is declared in `x-personal-mcp`:
 
 1. id
-2. name
+2. version
-3. version
+3. tags
-4. description
+4. capabilities
-5. tags
+5. depends_on
-6. capabilities
+6. optional references map (for nested entries, overrides, and aliases)
-7. depends_on
+
+No `metadata.yaml` sidecar is part of the end-state contract.
 
 ### URI Contract
 
-Module resource URIs are stable and follow:
+Canonical resource URIs are:
+
+For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./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*}
 
-Catalog resource URIs are stable and discovery-focused.
+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 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
+
+Resources are registered from the validated registry, not by ad hoc per-skill hardcoding.
+
+Registration rules:
+
+1. Use RFC6570 URI templates where appropriate.
+2. Mark documentation resources as read-only and idempotent.
+3. Set explicit mime types for resource responses.
+4. Configure duplicate URI handling with `on_duplicate="error"` for startup safety.
+
+This keeps runtime behavior deterministic and prevents accidental URI collisions.
 
 ### Versioning Rule
 
-Published URIs are immutable. Behavioral or schema changes are versioned in metadata and documented through additive migration notes.
+URIs are unversioned and canonical in this phase.
+
+1. Breaking URI changes are handled as direct replacement.
+2. No compatibility aliases or dual URI families are maintained.
 
 ## Static Hosting Pattern
 
@@ -161,8 +231,8 @@ 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
+1. docs/skills/pytest-scaffolding/references/pytest-docs.md
-2. ../docs/skills/python-logging-dictconfig/references/python-logging-docs.md
+2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
-3. ../docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
+3. 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/content.md

@@ -0,0 +1,88 @@
+---
+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 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. `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/copilot.md

@@ -18,7 +18,7 @@ Copilot interacts with MCP servers through separate capability lanes:
 
 These lanes are related but independently gated in the client.
 
-The documented reliable paths are:
+Reliable paths are:
 
 1. attach MCP resources explicitly through `Add Context > MCP Resources` or `MCP: Browse Resources`
 2. let Copilot invoke MCP tools when the task and tool descriptions make that relevant
@@ -57,18 +57,33 @@ Use this sequence to confirm behavior:
 
 ## Recommended Usage Pattern
 
-1. rely on catalog resources for discovery (`skills_index`, `patterns`, etc.)
+1. rely on canonical catalog resources for discovery (`skills_index`, then `skills/{skill_id}`)
 2. fetch only selected skill documents for context
 3. keep slash commands for deterministic fallback flows
 
-When resource attachment is unavailable in the active session, use thin catalog discovery tools as operational fallback:
+When resource attachment is unavailable in the active session, use ResourcesAsTools first, then thin catalog discovery tools as parity fallback:
 
-1. `search_patterns`
+1. `list_resources`
-2. `get_pattern_by_id`
+2. `read_resource`
-3. `get_skill_document_by_id`
+3. `search_patterns`
+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.
 
+For very large tool catalogs, server operators can optionally enable tool search mode (`regex` or `bm25`) while keeping `list_resources` and `read_resource` pinned as always-visible fallback tools.
+
 ## What To Type In Copilot Chat
 
 Use prompts that tell Copilot which MCP feature path to take.
@@ -91,7 +106,15 @@ I attached personal-mcp catalog resources first. Use them to identify the best m
 
 ### If only tools are available
 
-Ask Copilot to explicitly use the catalog tools.
+Ask Copilot to explicitly use resource-backed tools first.
+
+Example resource-backed prompt:
+
+```text
+Use personal-mcp tool fallback by first calling list_resources, then read_resource for resource://catalog/skills_index and the selected resource://skills/<skill-id>/document URI. Use only that loaded skill context in your answer.
+```
+
+If needed, use the thin catalog tools.
 
 Example discovery prompt:
 
@@ -128,20 +151,24 @@ When a task may benefit from personal-mcp skills, use this sequence:
 
 1. Start with personal-mcp catalog discovery when the task appears to match documented implementation patterns.
 2. Prefer MCP resources when the chat surface exposes resource attachment.
-3. If MCP resource attachment is unavailable, use catalog tools instead.
+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. Treat skill documents as guidance, then reconcile them with the actual repository code before making changes.
 
 Preferred discovery order:
 
-1. `resource://catalog/skills_index` or `resource://catalog/patterns`
+1. `resource://catalog/skills_index`
-2. `resource://skills/<skill-id>/document`
+2. `resource://catalog/skills/{skill_id}`
+3. `resource://skills/<skill-id>/document`
+4. `resource://skills/<skill-id>/references/<ref-id>` when needed
 
 Tool fallback order:
 
-1. `search_patterns`
+1. `list_resources`
-2. `get_pattern_by_id`
+2. `read_resource`
-3. `get_skill_document_by_id`
+3. `search_patterns`
+4. `get_pattern_by_id`
+5. `get_skill_document_by_id`
 
 If confidence is low after catalog discovery, ask one clarifying question before loading more skill documents.
 ```

docs/frontmatter.md

@@ -0,0 +1,338 @@
+---
+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.
+
+## 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 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

@@ -4,11 +4,11 @@ icon: lucide/rocket
 
 # Personal MCP
 
-This is a document library of software patterns, best practices, and structured references to external documentation, which are available in 2, equivalent ways. The same, exact markdown files are reused for both cases, so there is never any incongruity between them. 
+This project is a document library of software patterns, best practices, and structured references to external documentation. The same markdown files are published through two equivalent surfaces, so human-readable docs and MCP resources stay aligned.
 
 ## MCP Server
 
-An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` to provide context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), like VSCode.
+An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` provides context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), such as VS Code.
 
 ## Docs
 
@@ -39,6 +39,9 @@ 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)
 - [Static Docs Hosting Pattern](./mcp_layout.md)
 - [Skill Usage Mechanics](./usage.md)
 - [Copilot MCP Mechanics](./copilot.md)

docs/mcp_layout.md

@@ -1,3 +1,7 @@
+---
+icon: lucide/server
+---
+
 # Static Docs Hosting Pattern
 
 ## Purpose
@@ -29,15 +33,39 @@ treeView-beta
       "docs"
          "index.md"
          "architecture.md"
+         "content.md"
+         "frontmatter.md"
          "mcp_layout.md"
+         "uris.md"
          "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"
-            "fastapi-uv-docker"
+            "vscode-configuration"
+               "SKILL.md"
+               "references"
+            "zensical-docs"
                "SKILL.md"
                "references"
       "site"
@@ -45,15 +73,14 @@ treeView-beta
       "src"
          "personal_mcp"
             "main.py"
+            "mcp.py"
             "web"
                "app.py"
                "docs_mount.py"
             "catalog"
                "server.py"
             "skills"
-               "pytest_scaffolding"
+               "document_loader.py"
-               "python_logging_dictconfig"
-               "fastapi_uv_docker"
 ```
 
 Notes:
@@ -72,12 +99,21 @@ The runtime process serves two surfaces:
 
 ```mermaid
 flowchart TD
-    A[FastMCP Root Server] --> B[MCP Transport]
+   A[Docs Registry Loader] --> B[Validated In-Memory Registry]
-    A --> C[FastAPI Application]
+   B --> C[FastMCP Resource Registration]
-    C --> D[Static Mount /docs]
+   C --> D[MCP Transport]
-    D --> E[Zensical site output directory]
+   C --> E[FastAPI Application]
+   E --> F[Static Mount /docs]
+   F --> G[Zensical site output directory]
 ```
 
+Runtime guarantees:
+
+1. Docs registry load and validation happen before resource exposure.
+2. Duplicate resource and template registration fails startup (`on_duplicate="error"`).
+3. Resource registration is metadata-driven from SKILL frontmatter and reference manifests.
+4. Legacy per-skill Python servers and `metadata.yaml` sidecars are not part of the runtime.
+
 ## Build and Publish Flow
 
 The docs flow is pre-build only.
@@ -103,12 +139,29 @@ MCP resources map directly to canonical Markdown documents.
 
 Example mapping model:
 
-1. docs/skills/<slug>/SKILL.md -> resource://skills/<id>/document
+1. docs/skills/<skill-id>/SKILL.md -> resource://skills/<skill_id>/document
-2. docs/skills/<slug>/references/*.md -> referenced sections or linked companion documents
+2. docs/skills/<skill-id>/references/<file>.md -> resource://skills/<skill_id>/references/<ref_id> (via frontmatter references manifest)
+3. docs/<path>.md -> resource://docs/{path*}
 
-Catalog resources provide discovery metadata and stable identifiers.
+Catalog discovery resources are:
 
-When clients cannot attach MCP resources directly, catalog-level tools may retrieve the same underlying skill documents indirectly. This does not create a second content source; it is only an alternate access path to the same markdown-backed contract.
+1. resource://catalog/skills_index
+2. resource://catalog/skills/{skill_id}
+
+Registry-backed registration details:
+
+1. `resource://skills/{skill_id}/document` resolves to each skill's SKILL.md.
+2. `resource://skills/{skill_id}/references/{ref_id}` resolves through frontmatter reference manifests.
+3. `resource://docs/{path*}` resolves normalized markdown paths under `docs/`.
+4. Resource metadata includes explicit mime type and read-only/idempotent annotations.
+
+When clients cannot attach MCP resources directly, thin catalog tools may retrieve the same underlying skill documents indirectly. This does not create a second content source.
+
+## URI Compatibility Policy
+
+1. Canonical URIs are the only supported URIs in this runtime.
+2. No backward-compatibility aliases or dual registration paths are maintained.
+3. Contract changes should update clients to canonical URIs directly.
 
 ## Why This Pattern
 
@@ -155,8 +208,8 @@ 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
+1. docs/skills/pytest-scaffolding/references/pytest-docs.md
-2. ../docs/skills/python-logging-dictconfig/references/python-logging-docs.md
+2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
-3. ../docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
+3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
 
 These are source documents, not deployment artifacts.

docs/new_skill.md

@@ -1,178 +0,0 @@
-# Hooking Up a New Skill
-
-Use this checklist after generating a new skill under `docs/skills/<slug>/`.
-
-## Checklist
-
-1. Create the authored docs content.
-   Add `docs/skills/<slug>/SKILL.md` and any companion files under `docs/skills/<slug>/references/`.
-
-2. Choose the three names up front.
-   Use a docs slug like `fastapi-uv-docker`, a resource id like `fastapi-uv-docker`, and a Python package name like `fastapi_uv_docker`.
-
-3. Add the runtime package.
-   Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
-
-4. Expose the document resource in `server.py`.
-   Follow the existing pattern: create a `FastMCP` instance, register `resource://skills/<skill-id>/document`, and return the shared loader result.
-   For the default layout, load `docs/skills/<slug>/SKILL.md`.
-   For special cases, set `document_path` in `metadata.yaml` to a repo-relative Markdown file and load from metadata instead of hardcoding a path in the server.
-
-5. Register the catalog metadata.
-   In `metadata.yaml`, add the skill `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`. The `capabilities` list should include `resource://skills/<skill-id>/document`.
-
-6. Mount the skill in the root server.
-   Import the new server in `src/personal_mcp/mcp.py` and add an `mcp.mount(...)` call with the Python namespace.
-
-7. Let the loader and catalog do the rest.
-   The document loader reads canonical Markdown from `docs/skills/<slug>/SKILL.md` by default, or from `metadata.yaml`'s optional `document_path` override when present. The catalog discovers metadata from `src/personal_mcp/skills/*/metadata.yaml` automatically.
-
-8. Rebuild and smoke-test.
-   Run `uv run zensical build` to publish the docs site, then run a quick Python check or start the app to confirm the new resource loads.
-
-## Discovery Tool Policy
-
-To keep behavior consistent across MCP clients and Copilot session types, follow this boundary:
-
-1. Keep per-skill servers resource-only.
-2. Keep discovery/query tools centralized in the catalog server.
-3. Keep canonical content in `docs/skills/<slug>/SKILL.md` and expose it through `resource://skills/<skill-id>/document`.
-
-### Do
-
-1. Add or update `metadata.yaml` fields (`id`, `description`, `tags`, `capabilities`) so catalog discovery quality stays high.
-2. Use `document_path` when a skill should expose a Markdown file outside `docs/skills/<slug>/SKILL.md`.
-3. Use catalog resources as the primary discovery surface.
-4. Add thin, read-only catalog tools only when client behavior needs a fallback path.
-
-### Don't
-
-1. Do not add duplicate discovery tools to each skill package.
-2. Do not duplicate canonical skill guidance in tool descriptions.
-3. Do not create mutating catalog tools for skill discovery.
-
-## Minimal Shape
-
-- Docs content: `docs/skills/<slug>/SKILL.md`
-- Optional references: `docs/skills/<slug>/references/*.md`
-- Runtime package: `src/personal_mcp/skills/<python_namespace>/`
-- Resource URI: `resource://skills/<skill-id>/document`
-
-## Quick Validation
-
-1. Confirm the Markdown document resolves through the loader.
-   `uv run python -c "from personal_mcp.skills.document_loader import load_skill_document; print(load_skill_document(skill_id='<skill-id>', skill_slug='<slug>')['source_path'])"`
-
-2. Confirm the docs build still works.
-   `uv run zensical build`
-
-## server.py Template
-
-```python
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-<python_namespace>_server = FastMCP("<skill-id>")
-
-
-@<python_namespace>_server.resource("resource://skills/<skill-id>/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="<skill-id>",
-        skill_slug="<slug>",
-    )
-```
-
-## metadata.yaml Template
-
-```yaml
-id: <skill-id>
-name: <Human Readable Name>
-version: 1.0.0
-description: <One sentence describing what the skill provides.>
-tags:
-  - <tag-one>
-  - <tag-two>
-document_path: <optional repo-relative path to a markdown file>
-capabilities:
-  - resource://skills/<skill-id>/document
-depends_on: []
-```
-
-Omit `document_path` when the canonical document is `docs/skills/<slug>/SKILL.md`.
-
-## Root Mount Template
-
-Add an import in `src/personal_mcp/mcp.py`:
-
-```python
-from personal_mcp.skills.<python_namespace>.server import <python_namespace>_server
-```
-
-Add a mount call:
-
-```python
-mcp.mount(<python_namespace>_server, namespace="<python_namespace>")
-```
-
-## Example Scaffold
-
-For a new skill called `sqlmodel-patterns`:
-
-1. Docs content lives in `docs/skills/sqlmodel-patterns/SKILL.md`.
-2. The Python package lives in `src/personal_mcp/skills/sqlmodel_patterns/`.
-3. The resource id is `sqlmodel-patterns`.
-
-Example `server.py`:
-
-```python
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-sqlmodel_patterns_server = FastMCP("sqlmodel-patterns")
-
-
-@sqlmodel_patterns_server.resource("resource://skills/sqlmodel-patterns/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="sqlmodel-patterns",
-        skill_slug="sqlmodel-patterns",
-    )
-```
-
-Example `metadata.yaml`:
-
-```yaml
-id: sqlmodel-patterns
-name: SQLModel Patterns
-version: 1.0.0
-description: Provide reusable patterns for building apps with SQLModel.
-tags:
-  - sqlmodel
-  - python
-  - patterns
-capabilities:
-  - resource://skills/sqlmodel-patterns/document
-depends_on: []
-```
-
-Example `mcp.py` additions:
-
-```python
-from personal_mcp.skills.sqlmodel_patterns.server import sqlmodel_patterns_server
-
-mcp.mount(sqlmodel_patterns_server, namespace="sqlmodel_patterns")
-```
-
-## Bootstrap Sequence
-
-1. Create `docs/skills/<slug>/SKILL.md`.
-2. Copy the `server.py` template into `src/personal_mcp/skills/<python_namespace>/server.py`.
-3. Copy the `metadata.yaml` template into `src/personal_mcp/skills/<python_namespace>/metadata.yaml`.
-4. Add `__init__.py` in the new package directory.
-5. Import and mount the server in `src/personal_mcp/mcp.py`.
-6. Run the validation commands above.

docs/skills/copilot-customization/SKILL.md

@@ -2,6 +2,26 @@
 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
+  tags:
+    - copilot
+    - vscode
+    - customization
+    - instructions
+    - prompts
+    - agent-skills
+    - custom-agents
+    - hooks
+    - mcp
+    - personal-mcp
+    - skills
+  capabilities:
+    - resource://skills/copilot-customization/document
+  depends_on:
+    - new-skill
+    - zensical-docs
 ---
 
 # Copilot Customization
@@ -10,7 +30,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.
@@ -35,6 +60,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.
@@ -46,21 +125,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/<slug>/SKILL.md`, with optional one-level `references/` files.
-3. Choose consistent names: docs slug and resource id use kebab-case; Python namespace uses snake_case.
-4. Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
-5. Expose only `resource://skills/<skill-id>/document` from the per-skill server.
-6. Put discovery metadata in `metadata.yaml`, including `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`.
-7. Mount the skill server in `src/personal_mcp/mcp.py` using the Python namespace.
-8. Validate with the document loader and `uv run zensical build`.
-
-Keep per-skill servers resource-only. Catalog-level discovery is the only place for thin fallback discovery tools.
-
 ## Quality Checks
 
 Before finishing:

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

@@ -2,6 +2,17 @@
 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

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

@@ -2,6 +2,16 @@
 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
+    - docker
+  capabilities:
+    - resource://skills/fastapi-uv-docker/document
+  depends_on: []
 ---
 
 # FastAPI Project Best Practices

docs/skills/new-skill/SKILL.md

@@ -0,0 +1,171 @@
+---
+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. Try to use the `/create-skill` where possible to structure the output, but place it alongside the other skills in this repo.
+
+## Inputs
+
+1. New skill id (lowercase kebab-case)
+2. One-sentence capability statement (what it does and when to use it)
+3. Optional list of references to include under `references/`
+
+## Source of Truth and Required References
+
+1. Use this file as the baseline template for new skill authoring.
+2. Read and follow these docs before implementing a new skill:
+  - [docs/architecture.md](../../architecture.md)
+  - [docs/content.md](../../content.md)
+  - [docs/frontmatter.md](../../frontmatter.md)
+  - [docs/mcp_layout.md](../../mcp_layout.md)
+  - [docs/uris.md](../../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.
+
+### Framing
+
+Phrasing and language in the skills should reflect the intent of providing preferences and reference documentation, rather than being for a migration or transition. When a particular resource is brought in, it should focus the general way something is done.
+
+## SKILL.md Frontmatter Contract
+
+`SKILL.md` frontmatter is authoritative for skill 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.
+
+## 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}`
+
+Compatibility rule:
+
+1. Keep URI families unversioned by default.
+2. For breaking changes, update clients to the canonical replacement URIs directly.
+
+## Scope
+
+1. Create docs under docs/skills/<skill-id>/.
+2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields.
+3. Treat top-level `references/*.md` as auto-discovered references with `ref-id` generated from filename.
+4. Declare `x-personal-mcp.references` only when you need overrides or nested `references/**` entries.
+5. 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.
+6. For each top-level `references/<name>.md`, expect `resource://skills/<skill-id>/references/<name>` (normalized to lowercase kebab-case).
+7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides.
+
+## Required Outcomes
+
+1. Create `docs/skills/<skill-id>/SKILL.md` with valid frontmatter and a practical skill body.
+2. Create and populate `docs/skills/<skill-id>/references/` with any needed markdown references.
+3. Ensure frontmatter follows repository contract, including `x-personal-mcp` fields and canonical capabilities.
+4. Keep URI and reference mapping consistent with repository conventions.
+5. Reconcile all updates with repository implementation and avoid introducing parallel metadata systems.
+
+## Validation
+
+1. uv run zensical build
+2. uv run pytest -q
+
+## Output Contract
+
+Return:
+
+1. Files created or updated
+2. Validation results
+3. Follow-up suggestions for improving the skill

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

@@ -2,6 +2,17 @@
 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

docs/skills/nicegui/SKILL.md

@@ -2,6 +2,17 @@
 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)?'
+x-personal-mcp:
+  id: nicegui
+  version: 1.0.0
+  tags:
+    - nicegui
+    - fastapi
+    - ui
+    - architecture
+  capabilities:
+    - resource://skills/nicegui/document
+  depends_on: []
 ---
 
 # NiceGUI

docs/skills/pytest-scaffolding/SKILL.md

@@ -1,116 +1,82 @@
 ---
 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."
+description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Use when you need best-practice guidance and source links for core pytest, FastAPI testing, and SQLAlchemy testing."
 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 a collection of best-practice references and source-documentation links for building and maintaining pytest suites.
 
-This skill is optimized for progressive discoverability:
+Use it to quickly find the right guidance for:
-1. Start with the shortest path in this file.
+1. Baseline pytest structure and marker strategy.
-2. Load exactly one deeper reference only when a decision requires it.
+2. Naming conventions and test hierarchy organization.
-3. Continue only as far as needed for the current task.
+3. FastAPI route, dependency override, and lifespan testing patterns.
+4. SQLAlchemy transaction and session 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`).
 
-## Discovery Ladder
+## Reference Map
 
-### Level 0: Scope And Stack Triage (always)
+Use this map to open only the reference that matches your immediate need.
-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.
+- Core pytest practices and command patterns: [pytest-docs.md](./references/pytest-docs.md)
+- Naming conventions and hierarchy organization: [naming-and-organization.md](./references/naming-and-organization.md)
+- FastAPI-specific testing patterns: [fastapi-testing.md](./references/fastapi-testing.md)
+- SQLAlchemy-specific testing patterns: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
 
-### Level 1: Core pytest scaffold (default)
+## Baseline Best Practices
-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:
+These are stable defaults regardless of stack:
-- Baseline details and rationale: [pytest-docs.md](./references/pytest-docs.md)
 
-### Level 2: FastAPI branch (only for HTTP/dependency/lifespan concerns)
+1. Mirror `src/` into `tests/` so ownership and coverage are obvious.
-Escalate here when testing API routes, dependency injection boundaries, or app lifespan behavior.
+2. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
+3. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
+4. Separate fast feedback (`-m unit`) from broader integration/external lanes.
+5. Validate structure early with collection checks before expanding assertions.
 
-Apply these defaults:
+## Stack-Specific Guidance
-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:
+- For FastAPI, prefer dependency overrides and clear lifecycle handling; see [fastapi-testing.md](./references/fastapi-testing.md).
-- `unit`: service logic without HTTP/DB.
+- For SQLAlchemy, prefer transaction-safe session fixtures and explicit async loading strategy; see [sqlalchemy-testing.md](./references/sqlalchemy-testing.md).
-- `integration`: route + DI + DB contract checks.
+- For naming and tree organization, use the conventions in [naming-and-organization.md](./references/naming-and-organization.md).
-- `smoke`: one request per critical user path.
 
-Reference: [fastapi-testing.md](./references/fastapi-testing.md)
+## Source Documentation Entry Points
 
-### Level 3: SQLAlchemy branch (only for DB transaction/session design)
+Primary upstream docs are curated in each reference page. Start with:
-Escalate here when session lifecycle, transaction isolation, or async ORM behavior matters.
 
-Apply these defaults:
+1. Pytest good practices: [pytest docs](https://docs.pytest.org/en/stable/explanation/goodpractices.html)
-1. Create engine once per test session.
+2. Pytest fixtures: [fixture how-to](https://docs.pytest.org/en/stable/how-to/fixtures.html)
-2. Open connection + outer transaction per test.
+3. Pytest markers: [marker examples](https://docs.pytest.org/en/stable/example/markers.html)
-3. Bind session with `join_transaction_mode="create_savepoint"`.
+4. FastAPI testing: [FastAPI testing tutorial](https://fastapi.tiangolo.com/tutorial/testing/)
-4. Allow code under test to call `commit()` safely; rollback outer transaction at test end.
+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)
-5. Keep unit tests DB-free; DB tests belong under `integration`.
 
-Async additions:
+## Quick Validation Commands
-- 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 these commands to check structure and execution lanes:
-- use `StaticPool` when required by thread/connection sharing.
 
-Reference: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
+1. `uv run pytest --collect-only -q`
-
+2. `uv run pytest -m unit -q`
-## Branching Logic Summary
+3. `uv run pytest -m "not external" -q`
-- If pure logic can be faked cleanly, keep in `unit`.
+4. `uv run pytest -q`
-- 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.
+1. Which references were consulted.
-2. Marker and fixture plan.
+2. Recommended structure, naming, fixture, and marker decisions.
-3. Exact fast-path and full-path commands.
+3. Exact validation commands.
-4. Which reference level was loaded and why.
+4. Relevant source-doc links for any non-trivial recommendation.
-5. Risks or open questions before expanding assertions.
+5. Risks, assumptions, or open questions.

docs/skills/pytest-scaffolding/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/pytest-scaffolding/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

@@ -2,6 +2,16 @@
 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

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

@@ -0,0 +1,121 @@
+---
+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."
+argument-hint: "Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?"
+x-personal-mcp:
+  id: ruff-linting-formating
+  version: 1.0.0
+  tags:
+    - ruff
+    - linting
+    - formatting
+    - python
+    - ci
+  capabilities:
+    - resource://skills/ruff-linting-formating/document
+  depends_on: []
+---
+
+# 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/ruff-action@v4.0.0`. 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

@@ -2,18 +2,40 @@
 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
+  tags:
+    - vscode
+    - launch-json
+    - tasks-json
+    - debugpy
+    - fastapi
+    - python
+    - 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
@@ -23,6 +45,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.
+- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
-- `env` / `envFile`: Environment variables.
+- `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.
+- `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.
+- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
-- `group`: Mark default build or test tasks.
+- `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.
+- `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
@@ -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,25 @@
 ---
 name: zensical-docs
-description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links, then edit this skill over time to record project preferences for when each feature should be used.'
+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
+  tags:
+    - zensical
+    - mkdocs
+    - mkdocs-material
+    - mkdocstrings
+    - docs
+    - documentation
+    - information-architecture
+    - skills
+    - bootstrap
+    - discovery
+    - authoring
+  capabilities:
+    - resource://skills/zensical-docs/document
+  depends_on: []
 ---
 
 # Zensical Documentation Authoring
@@ -81,6 +99,30 @@ Keep this section short and revise it over time.
 
 When making a recommendation, link back to the relevant reference file first, and when possible to the upstream docs linked from that reference.
 
+## Link Formatting Rule
+
+Because this project publishes the same markdown for both `/docs` and MCP resources, link quality is part of the content contract.
+
+- Never leave a bare URL in prose or list items.
+- Prefer using in-place Markdown links with meaningful labels.
+- For external sources, prefer `[descriptive label](https://...)` over raw `https://...`.
+- For internal files, prefer relative Markdown links so rendered docs remain navigable.
+- Any mention of a library or a specific library feature should include a link to source documentation somewhere on the page.
+- If inline linking is awkward or the citation payload is too large, use a footnote or tooltip citation instead.
+
+Example preferred style:
+
+- `See [importlib.resources](https://docs.python.org/3/library/importlib.resources.html) for packaging details.`
+
+Example to avoid:
+
+- `See https://docs.python.org/3/library/importlib.resources.html for packaging details.`
+
+Acceptable alternatives when inline links are not ideal:
+
+- Add a footnote-style source citation at the end of the section or page.
+- Add a tooltip citation when the docs pattern supports it.
+
 ## Compatibility Rule
 
 Prefer the Zensical-native way of doing something when it exists and is well-supported.
@@ -93,3 +135,4 @@ Return only what is useful for the current docs task:
 1. Which reference to read next.
 2. The smallest recommended docs or config change.
 3. Any repo-specific preference this suggests should be added back into this skill.
+4. For any library or feature-level claim, include a source-doc citation somewhere (inline link preferred; footnote or tooltip acceptable).

docs/uris.md

@@ -0,0 +1,118 @@
+---
+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

@@ -9,7 +9,7 @@ icon: lucide/workflow
 This page explains practical usage mechanics for the GitHub Copilot extension in VS Code when `personal-mcp` is configured as an MCP server:
 
 1. explicit `/` command flows when you want deterministic control
-2. automatic skill context loading when relevance can be inferred
+2. guided skill loading when relevance can be inferred
 
 The goal is to show how Copilot behaves as a client and how to shape that behavior.
 
@@ -26,18 +26,17 @@ In this repository, skill guidance is exposed as MCP resources, not as server-ow
 
 ### What the server publishes
 
-`personal-mcp` mounts skill modules and a catalog module. The catalog exposes discovery resources:
+`personal-mcp` registers resources from the validated docs registry and exposes catalog discovery resources:
 
 1. `resource://catalog/skills_index`
-2. `resource://catalog/skills_details`
+2. `resource://catalog/skills/{skill_id}`
-3. `resource://catalog/patterns`
-4. `resource://catalog/patterns_by_id`
 
 Each skill publishes a canonical Markdown document resource:
 
 1. `resource://skills/<skill-id>/document`
+2. `resource://skills/<skill-id>/references/<ref-id>`
 
-The document payload is loaded from `docs/skills/<slug>/SKILL.md` and returned with metadata.
+The document payload is loaded from `docs/skills/<skill-id>/SKILL.md` and returned with metadata.
 
 ### What Copilot does as the client
 
@@ -73,7 +72,7 @@ In this project, "automatic loading" should be read as a preference you express
 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 such as `search_patterns` followed by `get_skill_document_by_id`
+2. MCP tool invocation using `list_resources`/`read_resource` (ResourcesAsTools), with thin catalog tools as parity fallback
 
 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.
 
@@ -147,6 +146,21 @@ Weak metadata reduces Copilot match quality and increases wrong context injectio
 
 If you skip the catalog/index step, behavior is less predictable and may either miss relevant skills or pull too much context.
 
+## Optional Tool Search Mode
+
+When tool catalogs grow, FastMCP search transforms can reduce tool-list noise for tool-only clients.
+
+Runtime switches:
+
+1. `PERSONAL_MCP_TOOL_SEARCH=none|regex|bm25` (default `none`)
+2. `PERSONAL_MCP_TOOL_SEARCH_MAX_RESULTS=<positive int>` (default `5`)
+
+Behavior:
+
+1. `regex` uses deterministic regex matching for targeted queries.
+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:
@@ -171,20 +185,32 @@ 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 catalog tools instead.
+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` or `resource://catalog/patterns`
+1. `resource://catalog/skills_index`
-2. `resource://skills/<skill-id>/document`
+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. `search_patterns`
+1. `list_resources`
-2. `get_pattern_by_id`
+2. `read_resource`
-3. `get_skill_document_by_id`
+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`
+
+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.
 ```
@@ -224,8 +250,9 @@ Suggested instruction policy text:
 
 1. Start with catalog-first discovery.
 2. Prefer MCP resources when the chat surface exposes resource attachment.
-3. Otherwise use catalog tools to search and load one or two likely skill documents.
+3. Otherwise use tool fallback to load one or two likely skill documents.
-4. If confidence is low, ask one clarifying question before loading more.
+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.
 
 ## Summary
 

pyproject.toml

@@ -20,3 +20,14 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/personal_mcp"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "ruff>=0.15.18",
+]
+test = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+]

src/personal_mcp/catalog/__init__.py

@@ -1,3 +1,13 @@
-from personal_mcp.catalog.server import catalog_server
+from personal_mcp.catalog.server import (
+    build_skill_detail_payload,
+    build_skills_index_payload,
+    get_pattern_by_id_payload,
+    search_patterns_payload,
+)
 
-__all__ = ["catalog_server"]
+__all__ = [
+    "build_skill_detail_payload",
+    "build_skills_index_payload",
+    "get_pattern_by_id_payload",
+    "search_patterns_payload",
+]

src/personal_mcp/catalog/server.py

@@ -1,172 +1,173 @@
-from pathlib import Path
+from __future__ import annotations
+
 from typing import Any
 
-import yaml
+from personal_mcp.skills.document_loader import DocsRegistry, SkillRecord
-from fastmcp import FastMCP
 
-from personal_mcp.skills.document_loader import load_skill_document_from_metadata
+DEFAULT_LIMIT = 20
-
+MAX_LIMIT = 100
-catalog_server = FastMCP("catalog")
 
 
-def _skills_dir() -> Path:
+def _pattern_payload(skill: SkillRecord) -> dict[str, Any]:
-    return Path(__file__).resolve().parents[1] / "skills"
-
-
-def _load_skill_registry() -> dict[str, Any]:
-    registry: dict[str, Any] = {}
-    for metadata_path in sorted(_skills_dir().glob("*/metadata.yaml")):
-        with metadata_path.open("r", encoding="utf-8") as handle:
-            metadata = yaml.safe_load(handle) or {}
-        skill_key = metadata_path.parent.name
-        registry[skill_key] = {
-            "namespace": skill_key,
-            "metadata": metadata,
-        }
-    return registry
-
-
-def _normalize_pattern(namespace: str, metadata: dict[str, Any]) -> dict[str, Any]:
-    pattern_id = metadata.get("id", namespace)
-    capabilities = metadata.get("capabilities", [])
     return {
-        "id": pattern_id,
+        "id": skill.skill_id,
-        "namespace": namespace,
+        "name": skill.name,
-        "name": metadata.get("name", pattern_id),
+        "version": skill.version,
-        "version": metadata.get("version", "0.1.0"),
+        "description": skill.description,
-        "description": metadata.get("description", ""),
+        "tags": list(skill.tags),
-        "tags": metadata.get("tags", []),
+        "depends_on": list(skill.depends_on),
-        "depends_on": metadata.get("depends_on", []),
+        "capabilities": list(skill.capabilities),
-        "capabilities": capabilities,
+        "resources": list(skill.capabilities),
-        # Expose resources explicitly for clients that treat resources as the primary interface.
-        "resources": capabilities,
     }
 
 
-def _normalized_patterns() -> list[dict[str, Any]]:
+def _summary_payload(skill: SkillRecord) -> dict[str, Any]:
-    registry = _load_skill_registry()
+    return {
-    return [
+        "id": skill.skill_id,
-        _normalize_pattern(namespace, entry["metadata"])
+        "name": skill.name,
-        for namespace, entry in registry.items()
+        "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 _matches_query(pattern: dict[str, Any], query: str) -> bool:
+def _skill_matches(
-    if not query:
+    skill: SkillRecord,
-        return True
+    *,
-
+    query: str | None,
+    tag: str | None,
+    capability: str | None,
+) -> bool:
+    if query:
         lowered = query.strip().lower()
-    if not lowered:
+        if lowered:
-        return True
-
-    query_terms = [term for term in lowered.replace("-", " ").split() if term]
-    if not query_terms:
-        return True
-
             haystack = " ".join(
                 [
-            str(pattern.get("id", "")),
+                    skill.skill_id,
-            str(pattern.get("namespace", "")),
+                    skill.name,
-            str(pattern.get("name", "")),
+                    skill.description,
-            str(pattern.get("description", "")),
+                    " ".join(skill.tags),
-            " ".join(str(tag) for tag in pattern.get("tags", [])),
                 ]
             ).lower()
-    return all(term in haystack for term in query_terms)
+            terms = [term for term in lowered.replace("-", " ").split() if term]
+            if any(term not in haystack for term in terms):
+                return False
 
+    if tag and tag not in skill.tags:
+        return False
+
+    if capability and capability not in skill.capabilities:
+        return False
 
-def _matches_tags(pattern: dict[str, Any], tags: list[str] | None) -> bool:
-    if not tags:
     return True
 
-    requested = [tag.strip().lower() for tag in tags if tag and tag.strip()]
-    if not requested:
-        return True
 
-    pattern_tags = {str(tag).lower() for tag in pattern.get("tags", [])}
+def build_skills_index_payload(
-    return all(tag in pattern_tags for tag in requested)
+    registry: DocsRegistry,
+    *,
+    query: str | None = None,
+    tag: str | None = None,
+    capability: 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.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],
+        "total": len(matches),
+        "cursor": str(start),
+        "limit": normalized_limit,
+        "next_cursor": str(next_cursor) if next_cursor < len(matches) else None,
+    }
 
 
-@catalog_server.resource("resource://catalog/skills_index")
+def build_skill_detail_payload(registry: DocsRegistry, skill_id: str) -> dict[str, Any]:
-def skills_index() -> dict[str, Any]:
+    if skill_id not in registry.skills_by_id:
-    """Return a compact discovery index for all available pattern modules."""
+        raise KeyError(skill_id)
-    return {"patterns": _normalized_patterns()}
+
+    skill = registry.skills_by_id[skill_id]
+    return {
+        "id": skill.skill_id,
+        "name": skill.name,
+        "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,
+            "references": {
+                ref_id: {
+                    "uri": ref.uri,
+                    "mime_type": ref.mime_type,
+                    "title": ref.title,
+                    "path": ref.relpath,
+                }
+                for ref_id, ref in sorted(skill.references.items())
+            },
+        },
+    }
 
 
-@catalog_server.resource("resource://catalog/skills_details")
+def search_patterns_payload(
-def skills_details() -> dict[str, Any]:
+    registry: DocsRegistry,
-    """Return full metadata for all mounted pattern modules."""
+    *,
-    return {"patterns": _load_skill_registry()}
-
-
-@catalog_server.resource("resource://catalog/patterns")
-def patterns() -> dict[str, Any]:
-    """Return normalized pattern records for resource-first clients."""
-    return {"patterns": _normalized_patterns()}
-
-
-@catalog_server.resource("resource://catalog/patterns_by_id")
-def patterns_by_id() -> dict[str, Any]:
-    """Return normalized pattern records indexed by stable pattern id."""
-    indexed: dict[str, Any] = {}
-    for pattern in _normalized_patterns():
-        indexed[pattern["id"]] = pattern
-    return {"patterns_by_id": indexed}
-
-
-@catalog_server.tool
-def search_patterns(
     query: str = "",
     tags: list[str] | None = None,
     skip: int = 0,
-    limit: int = 20,
+    limit: int = DEFAULT_LIMIT,
 ) -> dict[str, Any]:
-    """Search normalized pattern metadata with optional tags and pagination."""
     normalized_skip = max(skip, 0)
-    normalized_limit = min(max(limit, 1), 100)
+    normalized_limit = max(1, min(limit, MAX_LIMIT))
 
-    matches = [
+    requested_tags = [tag.strip() for tag in (tags or []) if tag and tag.strip()]
-        pattern
+
-        for pattern in _normalized_patterns()
+    matches: list[SkillRecord] = []
-        if _matches_query(pattern, query) and _matches_tags(pattern, tags)
+    for skill_id in registry.skills_in_load_order:
-    ]
+        skill = registry.skills_by_id[skill_id]
+        if not _skill_matches(skill, query=query, tag=None, capability=None):
+            continue
+        if requested_tags and any(tag not in skill.tags for tag in requested_tags):
+            continue
+        matches.append(skill)
 
     page = matches[normalized_skip : normalized_skip + normalized_limit]
     return {
-        "patterns": page,
+        "patterns": [_pattern_payload(skill) for skill in page],
         "total": len(matches),
         "skip": normalized_skip,
         "limit": normalized_limit,
     }
 
 
-@catalog_server.tool
+def get_pattern_by_id_payload(registry: DocsRegistry, skill_id: str) -> dict[str, Any]:
-def get_pattern_by_id(id: str) -> dict[str, Any]:
+    if skill_id not in registry.skills_by_id:
-    """Return one normalized pattern by stable id."""
-    for pattern in _normalized_patterns():
-        if pattern["id"] == id:
-            return {"found": True, "pattern": pattern}
-
-    return {"found": False, "id": id}
-
-
-@catalog_server.tool
-def get_skill_document_by_id(skill_id: str) -> dict[str, Any]:
-    """Return the canonical skill document payload for a stable skill id."""
-    registry = _load_skill_registry()
-    for namespace, entry in registry.items():
-        metadata = entry.get("metadata", {})
-        pattern_id = metadata.get("id", namespace)
-        if pattern_id != skill_id:
-            continue
-
-        return {
-            "found": True,
-            "document": load_skill_document_from_metadata(
-                skill_id=skill_id,
-                namespace=namespace,
-                metadata=metadata,
-            ),
-        }
-
         return {"found": False, "id": skill_id}
+    return {"found": True, "pattern": _pattern_payload(registry.skills_by_id[skill_id])}

src/personal_mcp/mcp.py

@@ -1,38 +1,216 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
 from fastmcp import FastMCP
+from fastmcp.server.transforms import ResourcesAsTools
+from fastmcp.server.transforms.search import BM25SearchTransform, RegexSearchTransform
 
-from personal_mcp.catalog.server import catalog_server
+from personal_mcp.catalog.server import (
-from personal_mcp.skills.copilot_customization.server import (
+    build_skill_detail_payload,
-    copilot_customization_server,
+    build_skills_index_payload,
+    get_pattern_by_id_payload,
+    search_patterns_payload,
 )
-from personal_mcp.skills.fastapi_async_sqlalchemy_modernization.server import (
+from personal_mcp.skills.document_loader import (
-    fastapi_async_sqlalchemy_modernization_server,
+    DocsRegistry,
+    load_docs_registry,
+    read_docs_markdown_path,
+    read_skill_document,
+    read_skill_reference,
 )
-from personal_mcp.skills.fastapi_uv_docker.server import fastapi_uv_docker_server
-from personal_mcp.skills.new_skill.server import new_skill_server
-from personal_mcp.skills.nicegui.server import nicegui_server
-from personal_mcp.skills.nicegui_ui_customization.server import (
-    nicegui_ui_customization_server,
-)
-from personal_mcp.skills.pytest_scaffolding.server import pytest_scaffolding_server
-from personal_mcp.skills.python_logging_dictconfig.server import (
-    python_logging_dictconfig_server,
-)
-from personal_mcp.skills.vscode_configuration.server import vscode_configuration_server
-from personal_mcp.skills.zensical_docs.server import zensical_docs_server
 
-mcp = FastMCP("personal-mcp")
+DOCS_ROOT = os.getenv("PERSONAL_MCP_DOCS_ROOT", "../../docs")
-
+TOOL_SEARCH_MODE = os.getenv("PERSONAL_MCP_TOOL_SEARCH", "none").strip().lower()
-mcp.mount(catalog_server, namespace="catalog")
+TOOL_SEARCH_MAX_RESULTS = os.getenv("PERSONAL_MCP_TOOL_SEARCH_MAX_RESULTS", "5")
-mcp.mount(copilot_customization_server, namespace="copilot_customization")
+REGISTRY: DocsRegistry = load_docs_registry(
-mcp.mount(
+    package_anchor="personal_mcp",
-    fastapi_async_sqlalchemy_modernization_server,
+    docs_root=DOCS_ROOT,
-    namespace="fastapi_async_sqlalchemy_modernization",
 )
-mcp.mount(new_skill_server, namespace="new_skill")
+
-mcp.mount(nicegui_server, namespace="nicegui")
+mcp = FastMCP("personal-mcp", on_duplicate="error")
-mcp.mount(nicegui_ui_customization_server, namespace="nicegui_ui_customization")
+
-mcp.mount(pytest_scaffolding_server, namespace="pytest_scaffolding")
+
-mcp.mount(python_logging_dictconfig_server, namespace="python_logging_dictconfig")
+def _parse_positive_int(value: str, *, env_name: str) -> int:
-mcp.mount(vscode_configuration_server, namespace="vscode_configuration")
+    try:
-mcp.mount(fastapi_uv_docker_server, namespace="fastapi_uv_docker")
+        parsed = int(value)
-mcp.mount(zensical_docs_server, namespace="zensical_docs")
+    except ValueError as exc:
+        raise ValueError(f"{env_name} must be an integer") from exc
+    if parsed <= 0:
+        raise ValueError(f"{env_name} must be greater than zero")
+    return parsed
+
+
+def _install_tool_fallback_transforms() -> None:
+    # Expose list_resources/read_resource for tool-only clients.
+    mcp.add_transform(ResourcesAsTools(mcp))
+
+    if TOOL_SEARCH_MODE in {"", "none"}:
+        return
+
+    max_results = _parse_positive_int(
+        TOOL_SEARCH_MAX_RESULTS,
+        env_name="PERSONAL_MCP_TOOL_SEARCH_MAX_RESULTS",
+    )
+    kwargs: dict[str, Any] = {
+        "max_results": max_results,
+        "always_visible": ["list_resources", "read_resource"],
+    }
+
+    if TOOL_SEARCH_MODE == "regex":
+        mcp.add_transform(RegexSearchTransform(**kwargs))
+        return
+    if TOOL_SEARCH_MODE == "bm25":
+        mcp.add_transform(BM25SearchTransform(**kwargs))
+        return
+
+    raise ValueError(
+        "PERSONAL_MCP_TOOL_SEARCH must be one of: none, regex, bm25"
+    )
+
+
+def _ro_annotations() -> dict[str, bool]:
+    return {
+        "readOnlyHint": True,
+        "idempotentHint": True,
+    }
+
+
+@mcp.resource(
+    "resource://catalog/skills_index",
+    mime_type="application/json",
+    tags={"catalog"},
+    annotations=_ro_annotations(),
+)
+def skills_index() -> dict[str, Any]:
+    return build_skills_index_payload(REGISTRY)
+
+
+@mcp.resource(
+    "resource://catalog/skills_index{?q,tag,capability,cursor,limit}",
+    mime_type="application/json",
+    tags={"catalog"},
+    annotations=_ro_annotations(),
+)
+def skills_index_query(
+    q: str | None = None,
+    tag: str | None = None,
+    capability: str | None = None,
+    cursor: str | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    return build_skills_index_payload(
+        REGISTRY,
+        query=q,
+        tag=tag,
+        capability=capability,
+        cursor=cursor,
+        limit=limit,
+    )
+
+
+@mcp.resource(
+    "resource://catalog/skills/{skill_id}",
+    mime_type="application/json",
+    tags={"catalog"},
+    annotations=_ro_annotations(),
+)
+def skill_detail(skill_id: str) -> dict[str, Any]:
+    return build_skill_detail_payload(REGISTRY, skill_id)
+
+
+@mcp.resource(
+    "resource://skills/{skill_id}/document",
+    mime_type="text/markdown",
+    tags={"skill-doc"},
+    annotations=_ro_annotations(),
+)
+def skill_document(skill_id: str) -> dict[str, str]:
+    return read_skill_document(REGISTRY, skill_id)
+
+
+@mcp.resource(
+    "resource://skills/{skill_id}/references/{ref_id}",
+    mime_type="text/markdown",
+    tags={"reference"},
+    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)
+
+
+@mcp.resource(
+    "resource://docs/{path*}",
+    mime_type="text/markdown",
+    tags={"docs"},
+    annotations=_ro_annotations(),
+)
+def docs_markdown(path: str) -> dict[str, str]:
+    return read_docs_markdown_path(REGISTRY, path)
+
+
+@mcp.tool
+def search_patterns(
+    query: str = "",
+    tags: list[str] | None = None,
+    skip: int = 0,
+    limit: int = 20,
+) -> dict[str, Any]:
+    """Search normalized pattern metadata with optional tags and pagination."""
+    return search_patterns_payload(
+        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)
+
+
+@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:
+        return {"found": False, "id": skill_id}
+
+    return {
+        "found": True,
+        "document": read_skill_document(REGISTRY, skill_id),
+    }
+
+
+@mcp.tool
+def catalog_search_patterns(
+    query: str = "",
+    tags: list[str] | None = None,
+    skip: int = 0,
+    limit: int = 20,
+) -> dict[str, Any]:
+    """Compatibility alias for clients expecting catalog_* tool naming."""
+    return search_patterns(
+        query=query,
+        tags=tags,
+        skip=skip,
+        limit=limit,
+    )
+
+
+@mcp.tool
+def catalog_get_pattern_by_id(id: str) -> dict[str, Any]:
+    """Compatibility alias for clients expecting catalog_* tool naming."""
+    return get_pattern_by_id(id)
+
+
+@mcp.tool
+def catalog_get_skill_document_by_id(skill_id: str) -> dict[str, Any]:
+    """Compatibility alias for clients expecting catalog_* tool naming."""
+    return get_skill_document_by_id(skill_id)
+
+
+_install_tool_fallback_transforms()

src/personal_mcp/skills/__init__.py

@@ -1 +1 @@
-"""Mounted skill servers for the personal MCP app."""
+"""Docs registry and markdown loading utilities for personal MCP skills."""

src/personal_mcp/skills/copilot_customization/metadata.yaml

@@ -1,21 +0,0 @@
-id: copilot-customization
-name: Copilot Customization
-version: 1.0.0
-description: Plan, create, review, and debug GitHub Copilot and VS Code agent customizations for this repository.
-tags:
-  - copilot
-  - vscode
-  - customization
-  - instructions
-  - prompts
-  - agent-skills
-  - custom-agents
-  - hooks
-  - mcp
-  - personal-mcp
-  - skills
-capabilities:
-  - resource://skills/copilot-customization/document
-depends_on:
-  - new-skill
-  - zensical-docs

src/personal_mcp/skills/copilot_customization/server.py

@@ -1,14 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-copilot_customization_server = FastMCP("copilot-customization")
-
-
-@copilot_customization_server.resource("resource://skills/copilot-customization/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="copilot-customization",
-        skill_slug="copilot-customization",
-    )

src/personal_mcp/skills/document_loader.py

@@ -1,74 +1,610 @@
-from pathlib import Path
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import PurePosixPath
 from typing import Any
 
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
 
-def _repo_root() -> Path:
+SKILL_ID_RE = re.compile(r"^[a-z][a-z0-9-]*$")
-    return Path(__file__).resolve().parents[3]
+SEMVER_RE = re.compile(
+    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:[-+][0-9A-Za-z.-]+)?$"
+)
 
 
-def resolve_skill_document_path(
+@dataclass(frozen=True)
-    *, skill_id: str, namespace: str, metadata: dict[str, Any]
+class RegistryIssue:
-) -> Path:
+    code: str
-    """Resolve the canonical Markdown document path for a skill."""
+    message: str
-    document_path = metadata.get("document_path")
+    skill_id: str | None
-    if isinstance(document_path, str) and document_path.strip():
+    path: str
-        return _repo_root() / document_path.strip()
+    hint: str
 
-    candidates: list[str] = []
-    slug = metadata.get("slug")
-    if isinstance(slug, str) and slug.strip():
-        candidates.append(slug.strip())
 
-    candidates.extend(
+class DocsRegistryValidationError(Exception):
+    def __init__(self, errors: list[RegistryIssue]) -> None:
+        self.errors = errors
+        summary = "\n".join(
             [
-            skill_id,
+                (
-            namespace.replace("_", "-"),
+                    f"{issue.code}: {issue.message} "
-            namespace,
+                    f"(skill={issue.skill_id or 'unknown'}, path={issue.path})"
+                )
+                for issue in errors
+            ]
+        )
+        super().__init__(summary)
+
+
+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:
+        path = PurePosixPath(value)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError("reference path must be a relative in-skill path")
+        if not str(path).startswith("references/"):
+            raise ValueError("reference path must stay under references/")
+        if path.suffix.lower() != ".md":
+            raise ValueError("reference path must target a markdown file")
+        return path.as_posix()
+
+
+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("tags")
+    @classmethod
+    def validate_tags(cls, value: list[str]) -> list[str]:
+        for tag in value:
+            if not SKILL_ID_RE.fullmatch(tag):
+                raise ValueError(f"invalid tag: {tag}")
+        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
+
+
+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
+
+
+@dataclass(frozen=True)
+class ReferenceRecord:
+    ref_id: str
+    uri: str
+    relpath: str
+    mime_type: str
+    title: str | None
+    content: str
+
+
+@dataclass(frozen=True)
+class SkillRecord:
+    skill_id: str
+    name: str
+    description: str
+    version: str
+    tags: tuple[str, ...]
+    capabilities: tuple[str, ...]
+    depends_on: tuple[str, ...]
+    document_uri: str
+    document_relpath: str
+    document_content: str
+    references: dict[str, ReferenceRecord]
+
+
+@dataclass(frozen=True)
+class SkillSummaryRecord:
+    skill_id: str
+    name: str
+    description: str
+    tags: tuple[str, ...]
+    capabilities: tuple[str, ...]
+    document_uri: str
+    version: str
+
+
+@dataclass(frozen=True)
+class DocsRegistry:
+    skills_by_id: dict[str, SkillRecord]
+    skills_in_load_order: tuple[str, ...]
+    skills_summary_in_load_order: tuple[SkillSummaryRecord, ...]
+    docs_markdown_by_path: dict[str, str]
+    docs_markdown_path_index: tuple[str, ...]
+    tag_to_skill_ids: dict[str, tuple[str, ...]]
+    capability_to_skill_ids: dict[str, tuple[str, ...]]
+
+
+def _parse_frontmatter(markdown: str, *, path: str) -> tuple[dict[str, Any], str]:
+    if not markdown.startswith("---"):
+        raise ValueError(f"missing YAML frontmatter: {path}")
+
+    lines = markdown.splitlines()
+    if len(lines) < 3 or lines[0].strip() != "---":
+        raise ValueError(f"invalid YAML frontmatter start: {path}")
+
+    end_index: int | None = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end_index = i
+            break
+
+    if end_index is None:
+        raise ValueError(f"missing YAML frontmatter terminator: {path}")
+
+    raw_yaml = "\n".join(lines[1:end_index])
+    body = "\n".join(lines[end_index + 1 :])
+    parsed = yaml.safe_load(raw_yaml)
+    if not isinstance(parsed, dict):
+        raise ValueError(f"frontmatter must parse to an object: {path}")
+    return parsed, body
+
+
+def _walk_markdown(
+    node: Traversable,
+    *,
+    prefix: PurePosixPath = PurePosixPath(""),
+) -> list[tuple[str, Traversable]]:
+    results: list[tuple[str, Traversable]] = []
+    for child in sorted(node.iterdir(), key=lambda item: item.name):
+        relpath = prefix.joinpath(child.name)
+        if child.is_dir():
+            results.extend(_walk_markdown(child, prefix=relpath))
+            continue
+        if not child.is_file() or not child.name.lower().endswith(".md"):
+            continue
+        results.append((relpath.as_posix(), child))
+    return results
+
+
+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")
+    if model.x_personal_mcp.id != model.name:
+        raise ValueError("x-personal-mcp.id must exactly match name")
+    expected_capability = f"resource://skills/{model.name}/document"
+    if expected_capability not in model.x_personal_mcp.capabilities:
+        raise ValueError(f"capabilities must include {expected_capability}")
+    return model
+
+
+def _normalize_docs_path(path: str) -> str:
+    normalized = PurePosixPath(path)
+    if normalized.is_absolute() or ".." in normalized.parts:
+        raise ValueError("path must be a normalized docs-relative path")
+    if normalized.suffix.lower() != ".md":
+        raise ValueError("path must point to a markdown file")
+    return normalized.as_posix()
+
+
+def _title_from_reference_filename(filename: str) -> str:
+    stem = PurePosixPath(filename).stem
+    normalized = stem.replace("-", " ").replace("_", " ").split()
+    if not normalized:
+        return stem
+    return " ".join(token.capitalize() for token in normalized)
+
+
+def _reference_id_from_filename(filename: str) -> str | None:
+    stem = PurePosixPath(filename).stem.strip().lower().replace("_", "-")
+    normalized = re.sub(r"[^a-z0-9-]+", "-", stem)
+    normalized = re.sub(r"-+", "-", normalized).strip("-")
+    if not normalized:
+        return None
+    if not SKILL_ID_RE.fullmatch(normalized):
+        return None
+    return normalized
+
+
+def _discover_top_level_references(
+    *,
+    skill_dir: Traversable,
+) -> dict[str, ReferenceEntry]:
+    references_dir = skill_dir.joinpath("references")
+    if not references_dir.is_dir():
+        return {}
+
+    discovered: dict[str, ReferenceEntry] = {}
+    for child in sorted(references_dir.iterdir(), key=lambda item: item.name):
+        if child.is_dir() or not child.is_file():
+            continue
+        if not child.name.lower().endswith(".md"):
+            continue
+
+        ref_id = _reference_id_from_filename(child.name)
+        if ref_id is None:
+            continue
+
+        discovered[ref_id] = ReferenceEntry(
+            path=PurePosixPath("references").joinpath(child.name).as_posix(),
+            title=_title_from_reference_filename(child.name),
+        )
+    return discovered
+
+
+def _ensure_no_cycles(skills_by_id: dict[str, SkillRecord]) -> list[tuple[str, str]]:
+    visiting: set[str] = set()
+    visited: set[str] = set()
+    cycles: list[tuple[str, str]] = []
+
+    def walk(skill_id: str, stack: list[str]) -> None:
+        if skill_id in visited:
+            return
+        if skill_id in visiting:
+            cycle_from = stack[stack.index(skill_id) :]
+            cycles.append((skill_id, " -> ".join(cycle_from + [skill_id])))
+            return
+
+        visiting.add(skill_id)
+        stack.append(skill_id)
+        for dep in skills_by_id[skill_id].depends_on:
+            if dep in skills_by_id:
+                walk(dep, stack)
+        stack.pop()
+        visiting.remove(skill_id)
+        visited.add(skill_id)
+
+    for skill_id in sorted(skills_by_id):
+        walk(skill_id, [])
+    return cycles
+
+
+def load_docs_registry(
+    *,
+    package_anchor: str,
+    docs_root: str = "docs",
+) -> DocsRegistry:
+    docs_dir = files(package_anchor).joinpath(docs_root)
+    issues: list[RegistryIssue] = []
+
+    if not docs_dir.is_dir():
+        raise DocsRegistryValidationError(
+            [
+                RegistryIssue(
+                    code="missing_docs_root",
+                    message="docs root directory does not exist",
+                    skill_id=None,
+                    path=docs_root,
+                    hint="configure docs_root to a valid packaged docs path",
+                )
             ]
         )
 
-    seen: set[str] = set()
+    docs_markdown_by_path: dict[str, str] = {}
-    for candidate in candidates:
+    for relpath, doc_file in _walk_markdown(docs_dir):
-        if candidate in seen:
+        docs_markdown_by_path[relpath] = doc_file.read_text(encoding="utf-8")
-            continue
-        seen.add(candidate)
 
-        candidate_path = _repo_root() / "docs" / "skills" / candidate / "SKILL.md"
+    skills_root = docs_dir.joinpath("skills")
-        if candidate_path.exists():
+    if not skills_root.is_dir():
-            return candidate_path
+        raise DocsRegistryValidationError(
-
+            [
-    return _repo_root() / "docs" / "skills" / skill_id / "SKILL.md"
+                RegistryIssue(
-
+                    code="missing_skills_root",
-
+                    message="skills directory does not exist under docs root",
-def load_markdown_document(*, skill_id: str, document_path: Path) -> dict[str, str]:
+                    skill_id=None,
-    """Load an arbitrary Markdown document and expose it as a skill resource."""
+                    path=f"{docs_root}/skills",
-    if not document_path.exists():
+                    hint="ensure docs/skills is included in packaged docs",
-        raise FileNotFoundError(
+                )
-            f"Missing skill document for '{skill_id}': {document_path}"
+            ]
         )
 
+    skills_by_id: dict[str, SkillRecord] = {}
+    summaries: list[SkillSummaryRecord] = []
+
+    for skill_dir in sorted(skills_root.iterdir(), key=lambda item: item.name):
+        if not skill_dir.is_dir():
+            continue
+
+        skill_dir_name = skill_dir.name
+        skill_rel_root = PurePosixPath("skills").joinpath(skill_dir_name)
+        skill_doc_relpath = skill_rel_root.joinpath("SKILL.md").as_posix()
+        skill_doc_file = skill_dir.joinpath("SKILL.md")
+
+        if not skill_doc_file.is_file():
+            issues.append(
+                RegistryIssue(
+                    code="missing_skill_document",
+                    message="missing required SKILL.md",
+                    skill_id=skill_dir_name,
+                    path=skill_doc_relpath,
+                    hint="add docs/skills/<skill-id>/SKILL.md",
+                )
+            )
+            continue
+
+        skill_markdown = skill_doc_file.read_text(encoding="utf-8")
+        try:
+            raw_frontmatter, _ = _parse_frontmatter(
+                skill_markdown,
+                path=skill_doc_relpath,
+            )
+            frontmatter = _validate_skill_frontmatter(
+                raw_frontmatter,
+                skill_dir_name=skill_dir_name,
+            )
+        except (ValueError, ValidationError) as exc:
+            issues.append(
+                RegistryIssue(
+                    code="invalid_frontmatter",
+                    message=str(exc),
+                    skill_id=skill_dir_name,
+                    path=skill_doc_relpath,
+                    hint="fix SKILL.md YAML frontmatter to match the contract",
+                )
+            )
+            continue
+
+        effective_reference_entries = _discover_top_level_references(skill_dir=skill_dir)
+        effective_reference_entries.update(frontmatter.x_personal_mcp.references)
+
+        references: dict[str, ReferenceRecord] = {}
+        for ref_id, ref_entry in effective_reference_entries.items():
+            ref_relpath = skill_rel_root.joinpath(ref_entry.path).as_posix()
+            if ref_relpath not in docs_markdown_by_path:
+                issues.append(
+                    RegistryIssue(
+                        code="missing_reference",
+                        message=f"reference target is missing for ref_id '{ref_id}'",
+                        skill_id=frontmatter.name,
+                        path=ref_relpath,
+                        hint="fix x-personal-mcp.references path or add the referenced markdown file",
+                    )
+                )
+                continue
+
+            references[ref_id] = ReferenceRecord(
+                ref_id=ref_id,
+                uri=f"resource://skills/{frontmatter.name}/references/{ref_id}",
+                relpath=ref_relpath,
+                mime_type=ref_entry.mime_type,
+                title=ref_entry.title,
+                content=docs_markdown_by_path[ref_relpath],
+            )
+
+        skill_id = frontmatter.name
+        if skill_id in skills_by_id:
+            issues.append(
+                RegistryIssue(
+                    code="duplicate_skill_id",
+                    message="duplicate skill id discovered",
+                    skill_id=skill_id,
+                    path=skill_doc_relpath,
+                    hint="ensure each skill directory has a unique id",
+                )
+            )
+            continue
+
+        record = SkillRecord(
+            skill_id=skill_id,
+            name=frontmatter.name,
+            description=frontmatter.description,
+            version=frontmatter.x_personal_mcp.version,
+            tags=tuple(frontmatter.x_personal_mcp.tags),
+            capabilities=tuple(frontmatter.x_personal_mcp.capabilities),
+            depends_on=tuple(frontmatter.x_personal_mcp.depends_on),
+            document_uri=f"resource://skills/{skill_id}/document",
+            document_relpath=skill_doc_relpath,
+            document_content=skill_markdown,
+            references=references,
+        )
+        skills_by_id[skill_id] = record
+        summaries.append(
+            SkillSummaryRecord(
+                skill_id=record.skill_id,
+                name=record.name,
+                description=record.description,
+                tags=record.tags,
+                capabilities=record.capabilities,
+                document_uri=record.document_uri,
+                version=record.version,
+            )
+        )
+
+    for skill_id, record in sorted(skills_by_id.items()):
+        for dependency in record.depends_on:
+            if dependency == skill_id:
+                issues.append(
+                    RegistryIssue(
+                        code="self_dependency",
+                        message="skill must not depend on itself",
+                        skill_id=skill_id,
+                        path=record.document_relpath,
+                        hint="remove the skill id from depends_on",
+                    )
+                )
+            elif dependency not in skills_by_id:
+                issues.append(
+                    RegistryIssue(
+                        code="missing_dependency",
+                        message=f"depends_on target '{dependency}' does not exist",
+                        skill_id=skill_id,
+                        path=record.document_relpath,
+                        hint="add the missing skill or remove it from depends_on",
+                    )
+                )
+
+    for cycle_start, cycle in _ensure_no_cycles(skills_by_id):
+        issues.append(
+            RegistryIssue(
+                code="dependency_cycle",
+                message=f"depends_on cycle detected: {cycle}",
+                skill_id=cycle_start,
+                path=skills_by_id[cycle_start].document_relpath,
+                hint="remove at least one dependency edge in the cycle",
+            )
+        )
+
+    seen_uris: set[str] = set()
+    for skill_id, record in sorted(skills_by_id.items()):
+        uris = [record.document_uri] + [ref.uri for ref in record.references.values()]
+        for uri in uris:
+            if uri in seen_uris:
+                issues.append(
+                    RegistryIssue(
+                        code="duplicate_uri",
+                        message=f"duplicate resource URI generated: {uri}",
+                        skill_id=skill_id,
+                        path=record.document_relpath,
+                        hint="ensure unique skill ids and reference ids",
+                    )
+                )
+            seen_uris.add(uri)
+
+    if issues:
+        raise DocsRegistryValidationError(issues)
+
+    skill_ids = tuple(sorted(skills_by_id))
+    summary_by_id = {summary.skill_id: summary for summary in summaries}
+    ordered_summaries = tuple(summary_by_id[skill_id] for skill_id in skill_ids)
+
+    tag_index: dict[str, list[str]] = {}
+    capability_index: dict[str, list[str]] = {}
+    for skill_id in skill_ids:
+        record = skills_by_id[skill_id]
+        for tag in record.tags:
+            tag_index.setdefault(tag, []).append(skill_id)
+        for capability in record.capabilities:
+            capability_index.setdefault(capability, []).append(skill_id)
+
+    return DocsRegistry(
+        skills_by_id=skills_by_id,
+        skills_in_load_order=skill_ids,
+        skills_summary_in_load_order=ordered_summaries,
+        docs_markdown_by_path=docs_markdown_by_path,
+        docs_markdown_path_index=tuple(sorted(docs_markdown_by_path)),
+        tag_to_skill_ids={
+            key: tuple(sorted(values)) for key, values in sorted(tag_index.items())
+        },
+        capability_to_skill_ids={
+            key: tuple(sorted(values))
+            for key, values in sorted(capability_index.items())
+        },
+    )
+
+
+def read_skill_document(registry: DocsRegistry, skill_id: str) -> dict[str, str]:
+    if skill_id not in registry.skills_by_id:
+        raise KeyError(f"unknown skill_id: {skill_id}")
+    skill = registry.skills_by_id[skill_id]
     return {
-        "id": skill_id,
+        "id": skill.skill_id,
-        "uri": f"resource://skills/{skill_id}/document",
+        "uri": skill.document_uri,
         "format": "markdown",
-        "source_path": str(document_path),
+        "source_path": f"docs/{skill.document_relpath}",
-        "content": document_path.read_text(encoding="utf-8"),
+        "content": skill.document_content,
     }
 
 
-def load_skill_document(*, skill_id: str, skill_slug: str) -> dict[str, str]:
+def read_skill_reference(
-    """Load the canonical skill markdown document for an MCP skill."""
+    registry: DocsRegistry,
-    document_path = _repo_root() / "docs" / "skills" / skill_slug / "SKILL.md"
+    *,
-    return load_markdown_document(skill_id=skill_id, document_path=document_path)
+    skill_id: str,
-
+    ref_id: str,
-
-def load_skill_document_from_metadata(
-    *, skill_id: str, namespace: str, metadata: dict[str, Any]
 ) -> dict[str, str]:
-    """Load a skill document using metadata overrides when present."""
+    if skill_id not in registry.skills_by_id:
-    document_path = resolve_skill_document_path(
+        raise KeyError(f"unknown skill_id: {skill_id}")
-        skill_id=skill_id,
+    skill = registry.skills_by_id[skill_id]
-        namespace=namespace,
+    if ref_id not in skill.references:
-        metadata=metadata,
+        raise KeyError(f"unknown ref_id '{ref_id}' for skill '{skill_id}'")
-    )
+    reference = skill.references[ref_id]
-    return load_markdown_document(skill_id=skill_id, document_path=document_path)
+    return {
+        "id": ref_id,
+        "skill_id": skill_id,
+        "uri": reference.uri,
+        "format": "markdown",
+        "source_path": f"docs/{reference.relpath}",
+        "content": reference.content,
+    }
+
+
+def read_docs_markdown_path(registry: DocsRegistry, path: str) -> dict[str, str]:
+    normalized_path = _normalize_docs_path(path)
+    if normalized_path not in registry.docs_markdown_by_path:
+        raise KeyError(f"unknown docs path: {normalized_path}")
+    return {
+        "uri": f"resource://docs/{normalized_path}",
+        "format": "markdown",
+        "source_path": f"docs/{normalized_path}",
+        "content": registry.docs_markdown_by_path[normalized_path],
+    }

src/personal_mcp/skills/fastapi_async_sqlalchemy_modernization/__init__.py

@@ -1 +0,0 @@
-"""FastAPI async SQLAlchemy modernization skill server."""

src/personal_mcp/skills/fastapi_async_sqlalchemy_modernization/metadata.yaml

@@ -1,12 +0,0 @@
-id: fastapi-async-sqlalchemy-modernization
-name: FastAPI Async SQLAlchemy Modernization
-version: 1.0.0
-description: Create a step-by-step modernization plan for an existing FastAPI app using SQLAlchemy async patterns.
-tags:
-  - fastapi
-  - sqlalchemy
-  - async
-  - modernization
-capabilities:
-  - resource://skills/fastapi-async-sqlalchemy-modernization/document
-depends_on: []

src/personal_mcp/skills/fastapi_async_sqlalchemy_modernization/server.py

@@ -1,18 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-fastapi_async_sqlalchemy_modernization_server = FastMCP(
-    "fastapi-async-sqlalchemy-modernization"
-)
-
-
-@fastapi_async_sqlalchemy_modernization_server.resource(
-    "resource://skills/fastapi-async-sqlalchemy-modernization/document"
-)
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="fastapi-async-sqlalchemy-modernization",
-        skill_slug="fastapi-async-sqlalchemy-modernization",
-    )

src/personal_mcp/skills/fastapi_uv_docker/__init__.py

@@ -1,3 +0,0 @@
-from personal_mcp.skills.fastapi_uv_docker.server import fastapi_uv_docker_server
-
-__all__ = ["fastapi_uv_docker_server"]

src/personal_mcp/skills/fastapi_uv_docker/metadata.yaml

@@ -1,11 +0,0 @@
-id: fastapi-uv-docker
-name: FastAPI uv Docker
-version: 1.0.0
-description: Provide fast migration guidance to FastAPI plus uv plus Docker.
-tags:
-  - fastapi
-  - uv
-  - docker
-capabilities:
-  - resource://skills/fastapi-uv-docker/document
-depends_on: []

src/personal_mcp/skills/fastapi_uv_docker/server.py

@@ -1,14 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-fastapi_uv_docker_server = FastMCP("fastapi-uv-docker")
-
-
-@fastapi_uv_docker_server.resource("resource://skills/fastapi-uv-docker/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="fastapi-uv-docker",
-        skill_slug="fastapi-uv-docker",
-    )

src/personal_mcp/skills/new_skill/__init__.py

@@ -1 +0,0 @@
-"""Pseudo-skill exposing the new skill bootstrap guide."""

src/personal_mcp/skills/new_skill/metadata.yaml

@@ -1,14 +0,0 @@
-id: new-skill
-name: New Skill Bootstrap
-version: 1.0.0
-description: Provide the bootstrap checklist and templates for creating new MCP skills.
-tags:
-  - fastmcp
-  - bootstrap
-  - scaffolding
-  - skills
-  - mcp
-document_path: docs/new_skill.md
-capabilities:
-  - resource://skills/new-skill/document
-depends_on: []

src/personal_mcp/skills/new_skill/server.py

@@ -1,21 +0,0 @@
-from pathlib import Path
-
-import yaml
-
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document_from_metadata
-
-new_skill_server = FastMCP("new-skill")
-_METADATA_PATH = Path(__file__).with_name("metadata.yaml")
-_METADATA = yaml.safe_load(_METADATA_PATH.read_text(encoding="utf-8")) or {}
-
-
-@new_skill_server.resource("resource://skills/new-skill/document")
-def skill_document() -> dict[str, str]:
-    """Return the bootstrap guide used to scaffold new skills."""
-    return load_skill_document_from_metadata(
-        skill_id="new-skill",
-        namespace="new_skill",
-        metadata=_METADATA,
-    )

src/personal_mcp/skills/nicegui/__init__.py

@@ -1 +0,0 @@
-"""NiceGUI architecture skill server."""

src/personal_mcp/skills/nicegui/metadata.yaml

@@ -1,12 +0,0 @@
-id: nicegui
-name: NiceGUI
-version: 1.0.0
-description: Design and scaffold a production-ready NiceGUI plus FastAPI application architecture.
-tags:
-  - nicegui
-  - fastapi
-  - ui
-  - architecture
-capabilities:
-  - resource://skills/nicegui/document
-depends_on: []

src/personal_mcp/skills/nicegui/server.py

@@ -1,11 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-nicegui_server = FastMCP("nicegui")
-
-
-@nicegui_server.resource("resource://skills/nicegui/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(skill_id="nicegui", skill_slug="nicegui")

src/personal_mcp/skills/nicegui_ui_customization/__init__.py

@@ -1 +0,0 @@
-"""NiceGUI UI customization skill server."""

src/personal_mcp/skills/nicegui_ui_customization/metadata.yaml

@@ -1,12 +0,0 @@
-id: nicegui-ui-customization
-name: NiceGUI UI Customization
-version: 1.0.0
-description: Design and implement production NiceGUI interfaces with reusable components and event-driven interactions.
-tags:
-  - nicegui
-  - ui
-  - customization
-  - frontend
-capabilities:
-  - resource://skills/nicegui-ui-customization/document
-depends_on: []

src/personal_mcp/skills/nicegui_ui_customization/server.py

@@ -1,16 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-nicegui_ui_customization_server = FastMCP("nicegui-ui-customization")
-
-
-@nicegui_ui_customization_server.resource(
-    "resource://skills/nicegui-ui-customization/document"
-)
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="nicegui-ui-customization",
-        skill_slug="nicegui-ui-customization",
-    )

src/personal_mcp/skills/pytest_scaffolding/__init__.py

@@ -1,3 +0,0 @@
-from personal_mcp.skills.pytest_scaffolding.server import pytest_scaffolding_server
-
-__all__ = ["pytest_scaffolding_server"]

src/personal_mcp/skills/pytest_scaffolding/metadata.yaml

@@ -1,11 +0,0 @@
-id: pytest-scaffolding
-name: Pytest Scaffolding
-version: 1.0.0
-description: Scaffold a maintainable pytest structure quickly.
-tags:
-  - pytest
-  - testing
-  - python
-capabilities:
-  - resource://skills/pytest-scaffolding/document
-depends_on: []

src/personal_mcp/skills/pytest_scaffolding/server.py

@@ -1,14 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-pytest_scaffolding_server = FastMCP("pytest-scaffolding")
-
-
-@pytest_scaffolding_server.resource("resource://skills/pytest-scaffolding/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="pytest-scaffolding",
-        skill_slug="pytest-scaffolding",
-    )

src/personal_mcp/skills/python_logging_dictconfig/__init__.py

@@ -1,5 +0,0 @@
-from personal_mcp.skills.python_logging_dictconfig.server import (
-    python_logging_dictconfig_server,
-)
-
-__all__ = ["python_logging_dictconfig_server"]

src/personal_mcp/skills/python_logging_dictconfig/metadata.yaml

@@ -1,11 +0,0 @@
-id: python-logging-dictconfig
-name: Python Logging DictConfig
-version: 1.0.0
-description: Provide minimal logging.config.dictConfig setup guidance.
-tags:
-  - logging
-  - python
-  - observability
-capabilities:
-  - resource://skills/python-logging-dictconfig/document
-depends_on: []

src/personal_mcp/skills/python_logging_dictconfig/server.py

@@ -1,16 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-python_logging_dictconfig_server = FastMCP("python-logging-dictconfig")
-
-
-@python_logging_dictconfig_server.resource(
-    "resource://skills/python-logging-dictconfig/document"
-)
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="python-logging-dictconfig",
-        skill_slug="python-logging-dictconfig",
-    )

src/personal_mcp/skills/vscode_configuration/__init__.py

@@ -1 +0,0 @@
-"""VS Code configuration skill package."""

src/personal_mcp/skills/vscode_configuration/metadata.yaml

@@ -1,15 +0,0 @@
-id: vscode-configuration
-name: VS Code Configuration
-version: 1.0.0
-description: Create and troubleshoot VS Code launch and task configuration for Python and FastAPI projects.
-tags:
-  - vscode
-  - launch-json
-  - tasks-json
-  - debugpy
-  - fastapi
-  - python
-  - skills
-capabilities:
-  - resource://skills/vscode-configuration/document
-depends_on: []

src/personal_mcp/skills/vscode_configuration/server.py

@@ -1,20 +0,0 @@
-from pathlib import Path
-
-import yaml
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document_from_metadata
-
-vscode_configuration_server = FastMCP("vscode-configuration")
-_METADATA_PATH = Path(__file__).with_name("metadata.yaml")
-_METADATA = yaml.safe_load(_METADATA_PATH.read_text(encoding="utf-8")) or {}
-
-
-@vscode_configuration_server.resource("resource://skills/vscode-configuration/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document_from_metadata(
-        skill_id="vscode-configuration",
-        namespace="vscode_configuration",
-        metadata=_METADATA,
-    )

src/personal_mcp/skills/zensical_docs/__init__.py

@@ -1 +0,0 @@
-"""Zensical documentation authoring skill server."""

src/personal_mcp/skills/zensical_docs/metadata.yaml

@@ -1,19 +0,0 @@
-id: zensical-docs
-name: Zensical Documentation Authoring
-version: 1.0.0
-description: Plan, write, and improve high-quality documentation with Zensical.
-tags:
-  - zensical
-  - mkdocs
-  - mkdocs-material
-  - mkdocstrings
-  - docs
-  - documentation
-  - information-architecture
-  - skills
-  - bootstrap
-  - discovery
-  - authoring
-capabilities:
-  - resource://skills/zensical-docs/document
-depends_on: []

src/personal_mcp/skills/zensical_docs/server.py

@@ -1,14 +0,0 @@
-from fastmcp import FastMCP
-
-from personal_mcp.skills.document_loader import load_skill_document
-
-zensical_docs_server = FastMCP("zensical-docs")
-
-
-@zensical_docs_server.resource("resource://skills/zensical-docs/document")
-def skill_document() -> dict[str, str]:
-    """Return the canonical Markdown document for this skill."""
-    return load_skill_document(
-        skill_id="zensical-docs",
-        skill_slug="zensical-docs",
-    )

src/personal_mcp/web/docs_mount.py

@@ -11,7 +11,9 @@ def mount_docs_static(app: FastAPI, *, docs_route: str, site_dir: Path) -> None:
     docs_root = f"{normalized_route}/"
 
     async def redirect_to_docs_root() -> RedirectResponse:
-        return RedirectResponse(url=docs_root, status_code=status.HTTP_307_TEMPORARY_REDIRECT)
+        return RedirectResponse(
+            url=docs_root, status_code=status.HTTP_307_TEMPORARY_REDIRECT
+        )
 
     app.add_api_route(
         normalized_route,

uv.lock

@@ -178,6 +178,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
 ]
 
+[[package]]
+name = "cfgv"
+version = "3.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4e/b5/721b8799b04bf9afe054a3899c6cf4e880fcf8563cc71c15610242490a0c/cfgv-3.5.0.tar.gz", hash = "sha256:d5b1034354820651caa73ede66a6294d6e95c1b00acc5e9b098e917404669132", size = 7334, upload-time = "2025-11-19T20:55:51.612Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/db/3c/33bac158f8ab7f89b2e59426d5fe2e4f63f7ed25df84c036890172b412b5/cfgv-3.5.0-py2.py3-none-any.whl", hash = "sha256:a8dc6b26ad22ff227d2634a65cb388215ce6cc96bbcc5cfde7641ae87e8dacc0", size = 7445, upload-time = "2025-11-19T20:55:50.744Z" },
+]
+
 [[package]]
 name = "click"
 version = "8.4.1"
@@ -199,6 +208,75 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "coverage"
+version = "7.14.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9c/a3/3834a5564fe8f32154cd7032400d3c2f9c565b2a373fa671f2bbdad6f634/coverage-7.14.2.tar.gz", hash = "sha256:7a2da3d81cfe17c18038c6d98e6592aa9147d596d056119b0ee612c3c8bd5230", size = 923982, upload-time = "2026-06-20T14:49:30.885Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/d9/bdd141aa2c605096a8ef63b8435fd4f5fec78946a3cb7b9145840ec78291/coverage-7.14.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:37c94712e533ea06f0b1e4d934811c520b1914ce0e4da3916220717aa7a86bc6", size = 220528, upload-time = "2026-06-20T14:47:49.652Z" },
+    { url = "https://files.pythonhosted.org/packages/02/97/d24ae7d2afc62c54a36313d4dedb655c9afbba3003f0f7f1ae81e97af31f/coverage-7.14.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:c050bbc7bba94c77e4ed7438f4fda1babe98ab145691d80aa6f60df934a1468b", size = 220883, upload-time = "2026-06-20T14:47:51.036Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/0e/d8f00efd3df0d63e6843ebcbade9e4119d60f5376753c9705d84b014c775/coverage-7.14.2-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:a7af571767a2ee342a171c16fc1b1a07a0bf511606d381703fb7cf397fe49d46", size = 252395, upload-time = "2026-06-20T14:47:52.627Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/1c/ab9510dfe1a16a35a10f90efad0d9a9cf61b9876973752968f2ba882f73f/coverage-7.14.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8b4910cce599cd2438f8da65f5ef199a70a1cdb6ab314926df78271ca5954240", size = 255131, upload-time = "2026-06-20T14:47:54.235Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/dd/70171e9371003b33dc6b20f527ac216ff91bbe5c1088e754eb8950d79193/coverage-7.14.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c33e9e4878972f430b0cc06de3bf2a28d054a9efb4f8426d27de0d9cb81396ff", size = 256246, upload-time = "2026-06-20T14:47:55.61Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/80/a68b1dd81d5c011e17fd6ab0d707d33297df1d0c618114b9b750a2219c80/coverage-7.14.2-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e7967ea55c6dea6becba4d5870e2fa0aa4915a8be7ebff1bb79e6207aa75ce8d", size = 258504, upload-time = "2026-06-20T14:47:56.979Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/7b/40baaa946189f5317cd77d484e39b9b0727d02ebada0a12162374f2faee2/coverage-7.14.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d1322f237c2979b84096f4239c17828ff17fea6b3bbe96c44381c5f587c44c26", size = 252808, upload-time = "2026-06-20T14:47:58.418Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/05/b19517b09c43d1e8591de6c13178b0c03166c31e1adbebda378e64c66b9a/coverage-7.14.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:77849525340c99f516d793dddbcee16b18d50af892ac43c8de1a6f343d41e3b5", size = 254166, upload-time = "2026-06-20T14:48:00.004Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/f5/6e65da5957e041d2094a9b97736628dd80160f1cc007a50790bbb2668c1a/coverage-7.14.2-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:ef11695493ec3f06f7b2678ca274bcabb4ca04057317df268ddbfd8b05f661a8", size = 252310, upload-time = "2026-06-20T14:48:01.458Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/de/01b5274f0db63175b04d9354eff68d2d268b8b57a1b2db7d3dcb1f2c9dbb/coverage-7.14.2-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:8134f0e0723e080d1c27bbe8fc149f0162e429fa1852482150015d0fce83eaf1", size = 256379, upload-time = "2026-06-20T14:48:02.981Z" },
+    { url = "https://files.pythonhosted.org/packages/71/d6/9a2ffbca41e2f8f86f61e8b78b86afa433ec8cdeac4908ace93a28fe3ff0/coverage-7.14.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:914eead2b843fc357f733b3fe39cc94f1b53d466e8cfe03080b1ed9d24ccfc73", size = 251880, upload-time = "2026-06-20T14:48:04.463Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/ff/20bd54a43c88c08f474e6cb355a97e024e38412873ef0a581629abe1e26f/coverage-7.14.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:e4b2d5e847fb7958583b74910cc19e5ec4ece514487385677b26433b2546116e", size = 253753, upload-time = "2026-06-20T14:48:05.99Z" },
+    { url = "https://files.pythonhosted.org/packages/35/2a/2b3482c30d8344f301d8df6ff232a321f2ab87d5ac97ba21891a68638131/coverage-7.14.2-cp312-cp312-win32.whl", hash = "sha256:e753db9e40dda7302e0ac3e1e6e1325fb7f7b4694f87a7314ab15dd5d57911a7", size = 222584, upload-time = "2026-06-20T14:48:07.361Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/5e/83934ffff147edd313fe925db426e8f7ccad9e4663262eb5c4db4e345658/coverage-7.14.2-cp312-cp312-win_amd64.whl", hash = "sha256:d32e5ca5f16dafb269ee50b60d32b00c704b3f6f78e238105f1d94a3a5f24bf5", size = 223118, upload-time = "2026-06-20T14:48:08.837Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/ee/616b4f38a34f076f3045d3eedfa764d34d82e6a6cc6b300acb0f1ff22a98/coverage-7.14.2-cp312-cp312-win_arm64.whl", hash = "sha256:dc366f158e2fb2add9d4e57338ca48f12611024278688ee657eb0b853fcb5de5", size = 222504, upload-time = "2026-06-20T14:48:10.436Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/09/b5b334c27960e7aac0003b96491bada7838dc641099fa64a1a598abf33cd/coverage-7.14.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e5f077641a6713ce9d38df9e85d4fb9e008677fc0775cbaeb32ddfc3b319d4ca", size = 220552, upload-time = "2026-06-20T14:48:11.847Z" },
+    { url = "https://files.pythonhosted.org/packages/79/20/879a000c319b4df7b50e4d688c0f7c0f6b5ac9d7b18848cbc00eabf26efe/coverage-7.14.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:0907f39b49ae818fe8af50aaa0f19afbc8ca164aea0865181ca7af17a3ac690b", size = 220919, upload-time = "2026-06-20T14:48:13.397Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/b7/326dded4371bab60f42215797944a356e4d81a3cee106121c7f7dd531604/coverage-7.14.2-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:5734d47669118d75c28981e562d4530ceb77342d31ffef6def5edd5ad4f05d7b", size = 251917, upload-time = "2026-06-20T14:48:14.931Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/14/b3232ba218a0d1a70883d2675f18ff465de9e8e5e3346e81dc2b079838bd/coverage-7.14.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:1d9a1b5813d00ea6151f6ccf64d1fa16892771dfdda12ba87162d15ec4ea3e1e", size = 254515, upload-time = "2026-06-20T14:48:16.545Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/7a/d77bcbee1cad71b42776574114b462225cc9125b4982f43da1b66adc850f/coverage-7.14.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9f0a80f4c8ac3f774210b1cc1bc0e31e75502f2818dda9a144ff90e702c4d91d", size = 255749, upload-time = "2026-06-20T14:48:18.214Z" },
+    { url = "https://files.pythonhosted.org/packages/86/86/97377937b29e9e44a1529bb20cb74dbcf80ed9006d87d7e742ff69e44b67/coverage-7.14.2-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c2e66f3f22d6c1515ce70f2e7c3e9c6f3ff0ff33480125c9f9c53e8f6508e30f", size = 257882, upload-time = "2026-06-20T14:48:19.7Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/a4/0fc8fe68bc505450bb068a2823ac7797bd8495240ccb8b4a5a1da1ee7e62/coverage-7.14.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:6a2c37c3114f87ca7f10113756026eecb49656514debad600dcbec21f355ccea", size = 252144, upload-time = "2026-06-20T14:48:21.176Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/4a/450094ddc41ab0d2eb4a0457b3856400ea3329568d1303696e85de099ae6/coverage-7.14.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:3b16a7959d04b1497281c062c180413565c3f3469211d78799ad5b9a75f67796", size = 253882, upload-time = "2026-06-20T14:48:22.701Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/28/2f6ae6d98265d9aa6bac311c4a93403675905b03aca95dc4373080279d75/coverage-7.14.2-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:6466c6999545cf00c4c142dfcbbf2db396dc735f005dcf8f91d57e351a79472b", size = 251846, upload-time = "2026-06-20T14:48:24.295Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/6e/707281468400794d52874e8fb5e38ff7578a0ff32ed49fe4fe85f192d0fc/coverage-7.14.2-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5c60915ebb8f562317ba5ff6b8c32e25c0882289b201a9f2fb2987f91efd95d8", size = 256002, upload-time = "2026-06-20T14:48:26.015Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/83/5e963120de4011257a950ce4cfb7fc833ddf3fee19db495268d3dec28154/coverage-7.14.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:33b830850488acbcd358c78a4fecfafe7031667b4da8ddff5546295dc962cdeb", size = 251665, upload-time = "2026-06-20T14:48:27.654Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/78/66b482cd525083bcc0bc894c16db79dabac37490065b53b07d6e8ab77202/coverage-7.14.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:d0f845539230b8269aec902bc978b0cc403f52f002d18a04492efc943404d0bc", size = 253435, upload-time = "2026-06-20T14:48:29.354Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/61/0663fb8cb530c8b11819b920109694eee95a3b22960a9495be0200f657f1/coverage-7.14.2-cp313-cp313-win32.whl", hash = "sha256:a8ac51a2e441e9119b9395f4d893fbc4934c64c8ba58be9b9eaa85591249e548", size = 222591, upload-time = "2026-06-20T14:48:31.142Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/47/1536d2b009c2848c3682500f497053f4645e70911afe02f594000997831a/coverage-7.14.2-cp313-cp313-win_amd64.whl", hash = "sha256:039b264cdb31c44b48f9821e2afbf8f37df49e0fb837e24a942918b36c567e31", size = 223134, upload-time = "2026-06-20T14:48:32.696Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/33ba4f335dd60bb34350318283d784f46018070e67b7d4df7c910ec9d9a0/coverage-7.14.2-cp313-cp313-win_arm64.whl", hash = "sha256:7f2ef591e381cc36b8e53334e1b842c760c520c8a52d01e8626209400e93fe6a", size = 222529, upload-time = "2026-06-20T14:48:34.237Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/bc/120390669817ede714ab141ae0a2a73240fd7354aac992c41dc0bd19570f/coverage-7.14.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:7a0d1f026b72d627fa5c8a57cbc86ad209b64aa2a65833c83b290ace5cbee126", size = 220593, upload-time = "2026-06-20T14:48:35.755Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/a3/7f1cfacd76af91e585f7ad689d7168002b444ed2a8ce59f2daaff10089b5/coverage-7.14.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4d2b86f81c1c9310a7e774e3cc9e927a3d0bf583ecbfa01498dd626930025428", size = 220925, upload-time = "2026-06-20T14:48:37.35Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/10/6514b2525bb672eb8b43703e46d061d694111db21efe7609db722df2233f/coverage-7.14.2-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:d76bdc1f9396ae70a55d050cf9743d88141c62ce0a22a3f627fab1d11c2f8bc6", size = 251974, upload-time = "2026-06-20T14:48:39.109Z" },
+    { url = "https://files.pythonhosted.org/packages/23/b4/4533091541c6620ecd68115bbfa1c61265b775618adef3a5fd137f4582e9/coverage-7.14.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:cda36d8e7bfd63b3e44e75163265429caa5d935b672b00f71bccc8c010518c64", size = 254479, upload-time = "2026-06-20T14:48:40.871Z" },
+    { url = "https://files.pythonhosted.org/packages/06/af/e251a143d5d106385dbca696c553afab6b69f7f6bc376a34e089cc0b8b32/coverage-7.14.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0904f3b79d7b845bef0715afe1900da634d12b97f05b9479cb472880ca07cb9c", size = 255824, upload-time = "2026-06-20T14:48:42.608Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/53/9e5876e60efbaa79d743d1948a5015ddc05b808db1cd62228acf83e87d43/coverage-7.14.2-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b6795ca4198d6cb7fc2c6163214f6555a6bc5f0ae1e268e76139dec4b37c4499", size = 258139, upload-time = "2026-06-20T14:48:44.263Z" },
+    { url = "https://files.pythonhosted.org/packages/85/5a/d35a4f431fb594e46b81cad4a13b470b017e918f347c1c0b260f7494fa1e/coverage-7.14.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c41e9b60fc0fa57f5d73306417d2f9d668202cca6944f9435878c55a5e7ae213", size = 252002, upload-time = "2026-06-20T14:48:45.961Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/e2/f5b304c8139c606c4f1b230d3a257d0c88edfbbdf06c58364f07625dc45c/coverage-7.14.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:419d2aadd5746efc2e9df0f33c05570d8192e6f6a6098ab05acce586f44ce8a5", size = 253832, upload-time = "2026-06-20T14:48:47.582Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bc/bbbd283daa6be4f68aad4ad4066fd39ae98e4174db8c03ab26c5803d6234/coverage-7.14.2-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:1c5d273c5f1411c0d26c4f066c398d4a434b1f97bb5fa409189bedce86d4add4", size = 251799, upload-time = "2026-06-20T14:48:49.42Z" },
+    { url = "https://files.pythonhosted.org/packages/69/8d/0745fceb89c9e5f7dd8ed243d97dc8561b7a95545741e2409d2b34654824/coverage-7.14.2-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5fe465bc691264adce601527a972990c1174075d86bcbe9968fd20c95e0b1948", size = 256075, upload-time = "2026-06-20T14:48:51.065Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/a0/441d9a5255cf021ab41ee00c014a4607d1c72d5e5bef0a4fdaa5be86a907/coverage-7.14.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:6fbb61617af1c56f95d53170ae9fa6c9aef6de1abd02fcc50064bfc672efb18d", size = 251612, upload-time = "2026-06-20T14:48:52.653Z" },
+    { url = "https://files.pythonhosted.org/packages/50/37/3d19c5e32d4a529c068eb296abfa3e455bd2c0f9311ecf26280f408ff8e0/coverage-7.14.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e1eff22b831dfd5694989cc1f0789980f18391f614ac67c851af9a8e6d25e9ba", size = 253270, upload-time = "2026-06-20T14:48:54.3Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/b0/54dd13937297518da6d092cc2c39d9340ec2194bdfa92e0a64694d643e23/coverage-7.14.2-cp314-cp314-win32.whl", hash = "sha256:58e91be0a233adef698d3e6be54f10401bb91fd7854c0d4c4d50e0d3711e72f1", size = 222796, upload-time = "2026-06-20T14:48:56.084Z" },
+    { url = "https://files.pythonhosted.org/packages/51/45/7a10e0909919686e335fdd95869cfb222d55243ebff27dc5cf59ca259a1f/coverage-7.14.2-cp314-cp314-win_amd64.whl", hash = "sha256:d8429bf97906bfe6c61f9dbfb3342e0d88120da61939da8bd04f830cc3eab3b8", size = 223285, upload-time = "2026-06-20T14:48:57.729Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/03/9cb197eb4b3d1a2eccb2537c226a93c80522c5b8afc5dd93e1993d7bb021/coverage-7.14.2-cp314-cp314-win_arm64.whl", hash = "sha256:13609d9d77249447aa73357b14831b0f3b95f275026c9ff20dd105f981f53a0c", size = 222712, upload-time = "2026-06-20T14:48:59.413Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/3c/e59f498511080d20bf866b0af9eeab820feb91547dae2084cb9bb7fb0e58/coverage-7.14.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:9818486c2bac88ae931df7e04905ee29bef49fd218c00f5f02bed4855254a101", size = 221325, upload-time = "2026-06-20T14:49:01.447Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/37/8d7955f7e701e69198bd0a0132ea76518c078a635b930a4924e2ccfa70f0/coverage-7.14.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:58055adffabfa243516a197aa9f85f0dd56d905b0fba1a10193269759c29ccb0", size = 221594, upload-time = "2026-06-20T14:49:03.13Z" },
+    { url = "https://files.pythonhosted.org/packages/34/7a/6738e1e1533ce8ec4e2e472696eefdd4723864d7efaa140e433053bf576a/coverage-7.14.2-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:535747dbc200349d7fb434cffcb28e770f0290f69b225f56dc3803aa7210cdea", size = 262957, upload-time = "2026-06-20T14:49:04.829Z" },
+    { url = "https://files.pythonhosted.org/packages/35/c4/d1be863cd39e0955904315fece67c5c23e046563f5eea0ceac16c547a759/coverage-7.14.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:420c66e35d85c0ca5dc6a38147d83ef239762542900e5921ebbdb89333c540ea", size = 265081, upload-time = "2026-06-20T14:49:07.018Z" },
+    { url = "https://files.pythonhosted.org/packages/72/7f/412df3c3c251284a11834287fd6f7e3bb98c528c53e030589e9344a3ef80/coverage-7.14.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f2cf17b33773be446a588551ea6a746b2d70dd0bc90dc31f1dd7648975a63c6b", size = 267500, upload-time = "2026-06-20T14:49:08.709Z" },
+    { url = "https://files.pythonhosted.org/packages/54/68/7d0764e83459455384d5c04179ce2d2a837bef01b9ba463079c6e8b31361/coverage-7.14.2-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:adb4a5fef041f7179bb264203add873c147d169cf2f8d0adae89ff2e51271bac", size = 268619, upload-time = "2026-06-20T14:49:10.405Z" },
+    { url = "https://files.pythonhosted.org/packages/14/68/1292164ac70cbcc86ac3982da31a6fbb42bb4bcebf6e5cf73c99cfcfd50d/coverage-7.14.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9c012ec357dec9408a83dad5541172a63c5cfa1421709f2e5811480d31ae1b28", size = 262066, upload-time = "2026-06-20T14:49:12.257Z" },
+    { url = "https://files.pythonhosted.org/packages/20/44/fd6fdf3f63b6e00a1a9230022d072ded5189576001685706aa6524187c65/coverage-7.14.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:dacd0ecd08fda3cb2f85b60cabea7da326dcb2fc15fbb23a88830a80144cc9f2", size = 264953, upload-time = "2026-06-20T14:49:14.13Z" },
+    { url = "https://files.pythonhosted.org/packages/39/29/e803fea3da89eaeb5b6b41b3ccd039fe9f3300a900e3803baac1a998529f/coverage-7.14.2-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:f27e980f2feba5dfe7a32b22b125470de69c0bd113c75e16165de909a777f512", size = 262555, upload-time = "2026-06-20T14:49:15.803Z" },
+    { url = "https://files.pythonhosted.org/packages/32/3c/b360e48ac68e3236c04cb83658382e7f5be7efbbec2e1faae3dcca432783/coverage-7.14.2-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:105c00efb65c863630b2b63cbf7b8267e4da2d44b62284efbb19a03b04c337d4", size = 266289, upload-time = "2026-06-20T14:49:17.962Z" },
+    { url = "https://files.pythonhosted.org/packages/59/12/1ed6d9274d599c586e2d1aa9818765dcdae6bb52aa88afa2fcd868398191/coverage-7.14.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:571173fa04c8e8d6235ab32ae67fecca97777e2e1b4a1a30f3022c34e397c1c1", size = 261402, upload-time = "2026-06-20T14:49:19.708Z" },
+    { url = "https://files.pythonhosted.org/packages/44/17/eb6cf12a4538cda937aefbeabb15377a8a30b377b484e63d31c9da790966/coverage-7.14.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:e532f34d42d1a421fa00ed6b7735d14ac2e340256c1bad26a5e1dc1252b0bed7", size = 263715, upload-time = "2026-06-20T14:49:21.427Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/ca/4bafdb9d372ab05d6ed3a63e7f00d3195d169d0afea00f617c026e386c19/coverage-7.14.2-cp314-cp314t-win32.whl", hash = "sha256:243971550fb46c3039257f75e65610002d84304c505f609bbd9779e20a653a0a", size = 223103, upload-time = "2026-06-20T14:49:23.24Z" },
+    { url = "https://files.pythonhosted.org/packages/35/cb/0765dbd9011d2e47315f1da31e62c5fe231f04a6ec8da213e64c4505896d/coverage-7.14.2-cp314-cp314t-win_amd64.whl", hash = "sha256:60fb0ca084a92da96474b8b405a7ea76dfecac3c68db54383e7934b6f3871169", size = 223934, upload-time = "2026-06-20T14:49:25.347Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/ce/373dde027ecd0ae54511430fe7569f838d3a0376b70333ba9fd20c76b836/coverage-7.14.2-cp314-cp314t-win_arm64.whl", hash = "sha256:36a0a3f42ed7dfdbca2a69a541519ffd5064a5692152fc0018109e74370d7345", size = 223249, upload-time = "2026-06-20T14:49:27.241Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/5e/a8ba14ceb014f39bd5e3f7077150718c7de61c01ce326bfe7e8eae9b19b2/coverage-7.14.2-py3-none-any.whl", hash = "sha256:04d92589e481a8b68a005a5a1e0646a91c76f322c397c4635298c57cf63699b5", size = 212325, upload-time = "2026-06-20T14:49:28.991Z" },
+]
+
 [[package]]
 name = "cryptography"
 version = "49.0.0"
@@ -273,6 +351,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/2d/82/e5d2c1c67d19841e9edc74954c827444ae826978499bde3dfc1d007c8c11/deepmerge-2.0-py3-none-any.whl", hash = "sha256:6de9ce507115cff0bed95ff0ce9ecc31088ef50cbdf09bc90a09349a318b3d00", size = 13475, upload-time = "2024-08-30T05:31:48.659Z" },
 ]
 
+[[package]]
+name = "distlib"
+version = "0.4.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c9/02/bd72be9134d25ed783ecbbc38a539ffaefbf90c78418c7fb7229600dbac7/distlib-0.4.3.tar.gz", hash = "sha256:f152097224a0ae24be5a0f6bae1b9359af82133bce63f98a95f86cae1aede9ed", size = 615141, upload-time = "2026-06-12T08:04:52.847Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/02/08/9c41fb51ab5b43eb21674aff13df270e8ba6c4b29c8624e328dc7a9482af/distlib-0.4.3-py2.py3-none-any.whl", hash = "sha256:4b0ce306c966eb73bc3a7b6abad017c556dadd92c44701562cd528ac7fde4d5b", size = 470628, upload-time = "2026-06-12T08:04:50.506Z" },
+]
+
 [[package]]
 name = "dnspython"
 version = "2.8.0"
@@ -395,6 +482,15 @@ server = [
     { name = "websockets" },
 ]
 
+[[package]]
+name = "filelock"
+version = "3.29.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e6/dc/be6cbe99670cd6e4ad387123647cb08e0c32975e223f82551e914c5568a6/filelock-3.29.4.tar.gz", hash = "sha256:10cdb3656fc44541cdf30652a93fb10ec6b05325620eb316bd26893e4201538a", size = 63028, upload-time = "2026-06-13T16:12:00.744Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/37/a065dc3bd6e49423a6532c642ca7378d3f467b1ef44c2800c937af7f9739/filelock-3.29.4-py3-none-any.whl", hash = "sha256:dac1648087d5115554850d113e7dd8c83ab2d38e3435dde2d4f163847e57b767", size = 42757, upload-time = "2026-06-13T16:11:59.582Z" },
+]
+
 [[package]]
 name = "griffelib"
 version = "2.0.2"
@@ -486,6 +582,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" },
 ]
 
+[[package]]
+name = "identify"
+version = "2.6.19"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/52/63/51723b5f116cc04b061cb6f5a561790abf249d25931d515cd375e063e0f4/identify-2.6.19.tar.gz", hash = "sha256:6be5020c38fcb07da56c53733538a3081ea5aa70d36a156f83044bfbf9173842", size = 99567, upload-time = "2026-04-17T18:39:50.265Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/94/84/d9273cd09688070a6523c4aee4663a8538721b2b755c4962aafae0011e72/identify-2.6.19-py2.py3-none-any.whl", hash = "sha256:20e6a87f786f768c092a721ad107fc9df0eb89347be9396cadf3f4abbd1fb78a", size = 99397, upload-time = "2026-04-17T18:39:49.221Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.18"
@@ -495,6 +600,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1e/5e/d4e9f1a599fb8e573b7b87160658329fbf28d19eac2718f51fc3def3aa5a/idna-3.18-py3-none-any.whl", hash = "sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2", size = 65455, upload-time = "2026-06-02T14:34:06.319Z" },
 ]
 
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
 [[package]]
 name = "jaraco-classes"
 version = "3.4.0"
@@ -756,6 +870,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e8/3d/1087453384dbde46a8c7f9356eead2c58be8a7bf156bca40243377c85715/more_itertools-11.1.0-py3-none-any.whl", hash = "sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192", size = 72226, upload-time = "2026-05-22T14:14:28.824Z" },
 ]
 
+[[package]]
+name = "nodeenv"
+version = "1.10.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/24/bf/d1bda4f6168e0b2e9e5958945e01910052158313224ada5ce1fb2e1113b8/nodeenv-1.10.0.tar.gz", hash = "sha256:996c191ad80897d076bdfba80a41994c2b47c68e224c542b48feba42ba00f8bb", size = 55611, upload-time = "2025-12-20T14:08:54.006Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/88/b2/d0896bdcdc8d28a7fc5717c305f1a861c26e18c05047949fb371034d98bd/nodeenv-1.10.0-py2.py3-none-any.whl", hash = "sha256:5bb13e3eed2923615535339b3c620e76779af4cb4c6a90deccc9e36b274d3827", size = 23438, upload-time = "2025-12-20T14:08:52.782Z" },
+]
+
 [[package]]
 name = "openapi-pydantic"
 version = "0.5.1"
@@ -807,6 +930,31 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/81/e6/cd9575ac904136b3cbf7aa7ee819ef86eedb7274e46f230e94ea4342e729/platformdirs-4.10.0-py3-none-any.whl", hash = "sha256:fb516cdb12eb0d857d0cd85a7c57cea4d060bee4578d6cf5a14dfdf8cbf8784a", size = 22743, upload-time = "2026-05-28T03:32:52.175Z" },
 ]
 
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "pre-commit"
+version = "4.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cfgv" },
+    { name = "identify" },
+    { name = "nodeenv" },
+    { name = "pyyaml" },
+    { name = "virtualenv" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8e/22/2de9408ac81acbb8a7d05d4cc064a152ccf33b3d480ebe0cd292153db239/pre_commit-4.6.0.tar.gz", hash = "sha256:718d2208cef53fdc38206e40524a6d4d9576d103eb16f0fec11c875e7716e9d9", size = 198525, upload-time = "2026-04-21T20:31:41.613Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/80/6e/4b28b62ecb6aae56769c34a8ff1d661473ec1e9519e2d5f8b2c150086b26/pre_commit-4.6.0-py2.py3-none-any.whl", hash = "sha256:e2cf246f7299edcabcf15f9b0571fdce06058527f0a06535068a86d38089f29b", size = 226472, upload-time = "2026-04-21T20:31:40.092Z" },
+]
+
 [[package]]
 name = "prompts"
 version = "0.1.0"
@@ -820,6 +968,17 @@ dependencies = [
     { name = "zensical" },
 ]
 
+[package.dev-dependencies]
+dev = [
+    { name = "pre-commit" },
+    { name = "ruff" },
+]
+test = [
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+    { name = "pytest-cov" },
+]
+
 [package.metadata]
 requires-dist = [
     { name = "fastapi", specifier = ">=0.115.0" },
@@ -830,6 +989,17 @@ requires-dist = [
     { name = "zensical", specifier = ">=0.0.45" },
 ]
 
+[package.metadata.requires-dev]
+dev = [
+    { name = "pre-commit", specifier = ">=4.6.0" },
+    { name = "ruff", specifier = ">=0.15.18" },
+]
+test = [
+    { name = "pytest", specifier = ">=9.1.1" },
+    { name = "pytest-asyncio", specifier = ">=1.4.0" },
+    { name = "pytest-cov", specifier = ">=7.1.0" },
+]
+
 [[package]]
 name = "py-key-value-aio"
 version = "0.4.5"
@@ -1018,6 +1188,62 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/df/80/fc9d01d5ed37ba4c42ca2b55b4339ae6e200b456be3a1aaddf4a9fa99b8c/pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273", size = 11063, upload-time = "2025-09-26T14:40:36.069Z" },
 ]
 
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
+]
+
+[[package]]
+name = "pytest-asyncio"
+version = "1.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/7c/d36d04db312ecf4298932ef77e6e4a9e8ad017906e24e34f0b0c361a2473/pytest_asyncio-1.4.0.tar.gz", hash = "sha256:c6c0d2259945122819f171a32ecea2c349ead889ee28176caaf492143424be42", size = 58514, upload-time = "2026-05-26T09:56:04.083Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/03/e2/08a497ef684b88559c9cc5f4ad53a37e7b99e727094a86d6ea32536d5d3c/pytest_asyncio-1.4.0-py3-none-any.whl", hash = "sha256:933ca923a23075a87fb7070c0ec272a6848489824d887c85c812670932835aa1", size = 16930, upload-time = "2026-05-26T09:56:02.576Z" },
+]
+
+[[package]]
+name = "pytest-cov"
+version = "7.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "coverage" },
+    { name = "pluggy" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/51/a849f96e117386044471c8ec2bd6cfebacda285da9525c9106aeb28da671/pytest_cov-7.1.0.tar.gz", hash = "sha256:30674f2b5f6351aa09702a9c8c364f6a01c27aae0c1366ae8016160d1efc56b2", size = 55592, upload-time = "2026-03-21T20:11:16.284Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9d/7a/d968e294073affff457b041c2be9868a40c1c71f4a35fcc1e45e5493067b/pytest_cov-7.1.0-py3-none-any.whl", hash = "sha256:a0461110b7865f9a271aa1b51e516c9a95de9d696734a2f71e3e78f46e1d4678", size = 22876, upload-time = "2026-03-21T20:11:14.438Z" },
+]
+
+[[package]]
+name = "python-discovery"
+version = "1.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "filelock" },
+    { name = "platformdirs" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0b/1a/cbbaf13b730abb0a16b964d984e19f2fe520c21a4dc664051359a3f5a9e7/python_discovery-1.4.2.tar.gz", hash = "sha256:8f3746c4b4968d22afbb97d36e1a0e5b66e6c0f297290f2e95f05b9b8bf18690", size = 70277, upload-time = "2026-06-11T16:10:42.383Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1a/82/a70006589557f267f15bd384c0642ad49f0d97b690c3a05b166b9dcbad3b/python_discovery-1.4.2-py3-none-any.whl", hash = "sha256:475803f53b7b2ed6e490e27373f9d8340f7d2eebf9acdaf645d7d714c97bb500", size = 33886, upload-time = "2026-06-11T16:10:41.192Z" },
+]
+
 [[package]]
 name = "python-dotenv"
 version = "1.2.2"
@@ -1260,6 +1486,31 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/79/cb/966040123eb102371559746908ef2c9471f4d43e17ec9a645a2258dab64b/rpds_py-2026.5.1-cp315-cp315t-win_amd64.whl", hash = "sha256:90bd6630002a1c7f09e7843dd79f0d24f3d2897cc25a753480917865d14f15b3", size = 225441, upload-time = "2026-05-28T12:01:51.408Z" },
 ]
 
+[[package]]
+name = "ruff"
+version = "0.15.18"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/74/98/1295ad5a5aa9bc85bdcdfa5d82fe7b49c61af5657df4f227637ff9de0da6/ruff-0.15.18.tar.gz", hash = "sha256:2698a964c70e8bf402dcb99c8810472d270d141e7aa8c4e13599fd52033a2f33", size = 4761437, upload-time = "2026-06-18T18:25:39.224Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b9/d0/686e984941269621e2be72612d5c1e461f8f7b38415a2a7d7a81c8ae6715/ruff-0.15.18-py3-none-linux_armv6l.whl", hash = "sha256:8b6850172348c8381b8b3084c5915a4393c2373b9b54cd5b5e1ea15812bc10df", size = 10887308, upload-time = "2026-06-18T18:25:03.062Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/21/bc4123e3f5515ee99f8ce1eb93a14a0628fe4d1678663cd08f933ac16931/ruff-0.15.18-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:3fccc153a85417dcd976883160cacce486997b0a0058dd18f54b8aaaac7d1ce2", size = 11281305, upload-time = "2026-06-18T18:25:30.026Z" },
+    { url = "https://files.pythonhosted.org/packages/51/93/4769464c25cf7ab2acb3c7dda9cad3d867eb41c59565b3e2a9d17249c90c/ruff-0.15.18-py3-none-macosx_11_0_arm64.whl", hash = "sha256:08d4c86a68f2c3ec2c9d56380a71fb4a4f65373055cbb8caabd645e9102f38d4", size = 10641215, upload-time = "2026-06-18T18:25:15.802Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/42/56926d17120db2c208d76bf60a1a019644dd9e91dc27f0f95c9caddb1366/ruff-0.15.18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:37e5108745c2c0705da916d7d4de533ddf547051ef45f62888c31bae73f66318", size = 10957224, upload-time = "2026-06-18T18:25:36.955Z" },
+    { url = "https://files.pythonhosted.org/packages/22/4f/d43fab8d8189afde803103022d000a8ef9f230616d436d52a8b2b8d63b50/ruff-0.15.18-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:56949a6ce8b3abde54c0bcb22cebfe57e8771cadc84b407ae8b8eaf67ebdcd43", size = 10699024, upload-time = "2026-06-18T18:25:05.707Z" },
+    { url = "https://files.pythonhosted.org/packages/63/42/1e3e4c68bd408b9768cf3e439acbe2c78245225faef253f7028a0cdb63e0/ruff-0.15.18-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:01a754cd6a1b630d3f97e33eb452cf7a98040482318e870f8bc52a5a30e62657", size = 11491458, upload-time = "2026-06-18T18:25:20.275Z" },
+    { url = "https://files.pythonhosted.org/packages/20/77/47a3484bea8521e14a203d98c389c5c97846675e4f02734672da4a69b52a/ruff-0.15.18-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6ba7a07e03a44dbf10bb086ee06705b173625014ec99f73a7e6836a5e5590a0c", size = 12383752, upload-time = "2026-06-18T18:25:22.535Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/ca/054159590787023d83b658a1a1819c4c8910114e7015069340b71c0961cb/ruff-0.15.18-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5a2c40a41a4cadbcf5897b548ab29dfe248b20c540961c0247d98a3973c70403", size = 11577923, upload-time = "2026-06-18T18:25:10.702Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/ff/d353d6b7bbd73cc0ec37f4463d7540e45e894338abdd9964eee0de332708/ruff-0.15.18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5f0480ce690cbb6c4db6e5d08f19fce98e10ba131a8b60c1bcdac42771e3ae2d", size = 11583925, upload-time = "2026-06-18T18:25:32.391Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/4a/891f89b9c296ed3e5f3ece1a5629badc989d9a8fdaa30431aaf4774bc1c2/ruff-0.15.18-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:2330215f1f393fa8733f55edce04fcf94c36a2c460fcde31f78cc84e4951e9b1", size = 11582834, upload-time = "2026-06-18T18:25:27.309Z" },
+    { url = "https://files.pythonhosted.org/packages/32/a3/ed9e370154bf85de360b93c03026157f02d4943b2d01ff4945f4429f8e8a/ruff-0.15.18-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a6aa6a3d979e48ae617578183674bf264fbe7d0114a796a26bd678d67963c7ff", size = 10927328, upload-time = "2026-06-18T18:25:34.676Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/d1/5cf5909329fedb5d39d555ee818ba5cf4638e1a301b89785d34f2905bfcb/ruff-0.15.18-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:a81beadbbff2c9c245561ae3f77b16709d87f35eec650d0501679239d3449b22", size = 10693187, upload-time = "2026-06-18T18:25:08.245Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/44/ff6c635cf2c4f4e7b618b6640da057376baa36014695487d88aed4794268/ruff-0.15.18-py3-none-musllinux_1_2_i686.whl", hash = "sha256:2186d9e940ae332ab293623a75b5f4fe49565f449954d50a72a046683aa6b809", size = 11208721, upload-time = "2026-06-18T18:25:41.327Z" },
+    { url = "https://files.pythonhosted.org/packages/88/d9/5baa2a30861adfb7022cf33c1e35b2fc18085b08c16f83eff4c7b99a5f48/ruff-0.15.18-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:5c2abf140438032bc77b2284a6c9944ecd8a19e5f1c7b52b1b8e4a0a80d19a7a", size = 11678599, upload-time = "2026-06-18T18:25:13.607Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/1a/0725a7cfdc32ff769efb96ee782bec882e16448c5d9e3be947ec4c04ce27/ruff-0.15.18-py3-none-win32.whl", hash = "sha256:02299e6e9fa5b297a3f6d5d10d7bcd655c925b028bb8b9d4588214549c6b9ec4", size = 10901903, upload-time = "2026-06-18T18:25:24.755Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/51/805d9f6fb7970505c3504794a5ec350f605361b807fef4dcf214ebd35e72/ruff-0.15.18-py3-none-win_amd64.whl", hash = "sha256:dac80dc8d26b2257dbefabed62f5d255c3937b4ccb122da1fc634794fa3578b3", size = 12041189, upload-time = "2026-06-18T18:25:17.915Z" },
+    { url = "https://files.pythonhosted.org/packages/29/4c/67bb45e41609eb4726f1bfeb59e083cf91d14c696d4bd14c234a980be93d/ruff-0.15.18-py3-none-win_arm64.whl", hash = "sha256:b2c9257fcbd4a3e5b977a1904e6facca016bafe2edc17df24db67cfaee03b4e4", size = 11329958, upload-time = "2026-06-18T18:25:43.686Z" },
+]
+
 [[package]]
 name = "secretstorage"
 version = "3.5.0"
@@ -1430,6 +1681,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e4/16/c1fd27e9549f3c4baf1dc9c20c456cd2f822dbf8de9f463824b0c0357e06/uvloop-0.22.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6cde23eeda1a25c75b2e07d39970f3374105d5eafbaab2a4482be82f272d5a5e", size = 4296730, upload-time = "2025-10-16T22:17:00.744Z" },
 ]
 
+[[package]]
+name = "virtualenv"
+version = "21.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "distlib" },
+    { name = "filelock" },
+    { name = "platformdirs" },
+    { name = "python-discovery" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f1/a5/81f987504738e6defeed61ec1c47e2aefab3c35d8eeb87e1b3f38cf28254/virtualenv-21.5.1.tar.gz", hash = "sha256:dca3bf98275a59c652b69d68e73433e597d977c2da9198882479d1a7188009c8", size = 4578798, upload-time = "2026-06-16T16:23:58.603Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/02/3623e6169bed617ed1e2d372f7c69f92ec28d54c4dfc997055c8578ec148/virtualenv-21.5.1-py3-none-any.whl", hash = "sha256:55aa670b67bbfb991b03fda39bd3276d92c419d702376e98c5df1c9989a26783", size = 4558820, upload-time = "2026-06-16T16:23:56.963Z" },
+]
+
 [[package]]
 name = "watchfiles"
 version = "1.2.0"

zensical.toml

@@ -48,14 +48,19 @@ nav = [
   { "Home" = "index.md" },
   { "Guide" = [
     { "Arch" = "architecture.md" },
+    { "Content" = "content.md" },
+    { "Frontmatter" = "frontmatter.md" },
+    { "URIs" = "uris.md" },
     { "MCP" = "mcp_layout.md" },
     { "Copilot" = "copilot.md" },
     { "Usage" = "usage.md" },
     { "Future Work" = "future_work.md" },
-    { "New Skill" = "new_skill.md" },
     { "Security" = "securing.md" },
   ] },
   { "Skills" = [
+    { "New Skill" = [
+      { "Overview" = "skills/new-skill/SKILL.md" },
+    ] },
     { "Copilot" = [
       { "Overview" = "skills/copilot-customization/SKILL.md" },
       { "VS Code" = "skills/copilot-customization/references/vscode-customization.md" },
@@ -88,7 +93,7 @@ nav = [
       { "Arch" = "skills/nicegui/references/architecture.md" },
       { "Sources" = "skills/nicegui/references/source-documentation.md" },
     ] },
-    { "NiceGUI UI" = [
+    { "NiceGUI Fine-Tuning" = [
       { "Overview" = "skills/nicegui-ui-customization/SKILL.md" },
       { "Style" = "skills/nicegui-ui-customization/references/architecture-and-styling.md" },
       { "Flows" = "skills/nicegui-ui-customization/references/interaction-patterns.md" },
@@ -102,6 +107,11 @@ nav = [
       { "Overview" = "skills/python-logging-dictconfig/SKILL.md" },
       { "Docs" = "skills/python-logging-dictconfig/references/python-logging-docs.md" },
     ] },
+    { "Ruff" = [
+      { "Overview" = "skills/ruff-linting-formating/SKILL.md" },
+      { "Docs" = "skills/ruff-linting-formating/references/ruff-docs.md" },
+      { "Integrations" = "skills/ruff-linting-formating/references/ruff-integrations.md" },
+    ] },
     { "Zensical" = [
       { "Overview" = "skills/zensical-docs/SKILL.md" },
       { "Map" = "skills/zensical-docs/references/index.md" },