implemented steps 1-5

docs/mcp_contract_steps_1_5.md

@@ -0,0 +1,66 @@
+# FastMCP Greenfield Contracts (Steps 1-5)
+
+## Step 1: End-State Content Contract
+
+1. All authored markdown lives under docs/.
+2. Skill docs live under docs/skills/<skill-id>/.
+3. Canonical skill shape is:
+
+```text
+docs/
+  skills/
+    <skill-id>/
+      SKILL.md
+      references/
+```
+
+4. SKILL.md is required for every skill.
+5. references/ is the only place for skill-specific supporting docs.
+6. Skill directories are ownership boundaries.
+7. Skill id rules:
+   - lowercase kebab-case
+   - starts with a letter
+   - directory name matches skill id
+   - SKILL frontmatter id matches directory name
+
+## Step 2: SKILL Frontmatter and Metadata Contract
+
+1. name and description are required top-level frontmatter fields.
+2. Repository indexing metadata lives in x-personal-mcp.
+3. x-personal-mcp fields:
+   - required: id, version, capabilities
+   - optional: tags, depends_on, references
+4. references maps stable ref ids to skill-relative markdown paths under references/.
+5. metadata.yaml sidecars are not part of the canonical model.
+
+## Step 3: URI Contract and Compatibility Policy
+
+Canonical URI surface:
+
+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*}
+
+Rules:
+
+1. skill_id and ref_id are lowercase kebab-case.
+2. docs path is markdown-only and cannot traverse outside docs/.
+3. URI families are unversioned and canonical in this phase.
+4. Breaking changes use direct replacement with no compatibility aliases.
+
+## Step 4: Docs Registry Loader Contract
+
+1. Loader uses importlib.resources.files(...) and Traversable APIs.
+2. Startup validates SKILL frontmatter schema, id invariants, reference integrity, dependency graph, and URI uniqueness.
+3. Registry is immutable for request-time reads.
+4. Invalid docs state is a hard startup error.
+
+## Step 5: Registry-Driven Resource Registration Contract
+
+1. FastMCP resources are registered from the validated registry.
+2. RFC6570 templates are used for parameterized routes.
+3. Docs resources declare explicit MIME types.
+4. Docs resources include readOnlyHint and idempotentHint annotations.
+5. Duplicate registrations fail startup via strict duplicate policy.