contract updates

docs/contracts/index.md

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