implemented steps 1-5

docs/mcp_layout.md

@@ -30,14 +30,36 @@ treeView-beta
          "index.md"
          "architecture.md"
          "mcp_layout.md"
+         "mcp_contract_steps_1_5.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 +67,14 @@ treeView-beta
       "src"
          "personal_mcp"
             "main.py"
+            "mcp.py"
             "web"
                "app.py"
                "docs_mount.py"
             "catalog"
                "server.py"
             "skills"
-               "pytest_scaffolding"
-               "python_logging_dictconfig"
-               "fastapi_uv_docker"
+               "document_loader.py"
 ```
 
 Notes:
@@ -72,12 +93,21 @@ The runtime process serves two surfaces:
 
 ```mermaid
 flowchart TD
-    A[FastMCP Root Server] --> B[MCP Transport]
-    A --> C[FastAPI Application]
-    C --> D[Static Mount /docs]
-    D --> E[Zensical site output directory]
+   A[Docs Registry Loader] --> B[Validated In-Memory Registry]
+   B --> C[FastMCP Resource Registration]
+   C --> D[MCP Transport]
+   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 +133,31 @@ MCP resources map directly to canonical Markdown documents.
 
 Example mapping model:
 
-1. docs/skills/<slug>/SKILL.md -> resource://skills/<id>/document
-2. docs/skills/<slug>/references/*.md -> referenced sections or linked companion documents
+1. docs/skills/<skill-id>/SKILL.md -> resource://skills/<skill_id>/document
+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
+
+This phase is a greenfield break-and-replace baseline.
+
+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 +204,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
-2. ../docs/skills/python-logging-dictconfig/references/python-logging-docs.md
-3. ../docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
+1. docs/skills/pytest-scaffolding/references/pytest-docs.md
+2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
+3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
 
 These are source documents, not deployment artifacts.