doc updates

docs/architecture.md

@@ -26,9 +26,9 @@ This architecture is anchored by three contracts:
 
 Detailed contract pages:
 
-1. [Content Contract](./content.md)
-2. [Frontmatter Contract](./frontmatter.md)
-3. [URI Contract](./uris.md)
+1. [Content Contract](./contracts/content.md)
+2. [Frontmatter Contract](./contracts/frontmatter.md)
+3. [URI Contract](./contracts/uris.md)
 
 This architecture keeps authored content human-friendly while preserving machine-stable contracts.
 
@@ -125,7 +125,7 @@ flowchart TD
 
 Each skill declares frontmatter in `docs/skills/<skill-id>/SKILL.md`.
 
-For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./frontmatter.md).
+For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./contracts/frontmatter.md).
 
 Anthropic-facing required fields:
 
@@ -147,7 +147,7 @@ No `metadata.yaml` sidecar is part of the end-state contract.
 
 Canonical resource URIs are:
 
-For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./uris.md).
+For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./contracts/uris.md).
 
 1. resource://skills/<skill_id>/document
 2. resource://skills/<skill_id>/references/<ref_id>

docs/contracts/index.md

@@ -0,0 +1,15 @@
+---
+icon: lucide/file-check-2
+---
+
+# Contracts
+
+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)
+
+Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.

docs/index.md

@@ -39,9 +39,10 @@ When the server is running, the health check is available at `/healthz` and the
 ## Architecture
 
 - [Resource-First Pattern Module Architecture](./architecture.md)
-- [Content Contract](./content.md)
-- [Frontmatter Contract](./frontmatter.md)
-- [URI Contract](./uris.md)
+- [Contracts](./contracts/index.md)
+- [Content Contract](./contracts/content.md)
+- [Frontmatter Contract](./contracts/frontmatter.md)
+- [URI Contract](./contracts/uris.md)
 - [Static Docs Hosting Pattern](./mcp_layout.md)
 - [Skill Usage Mechanics](./usage.md)
 - [Copilot MCP Mechanics](./copilot.md)

docs/mcp_layout.md

@@ -32,55 +32,35 @@ treeView-beta
       "zensical.toml"
       "docs"
          "index.md"
-         "architecture.md"
-         "content.md"
-         "frontmatter.md"
+         "<project-docs>.md"
+         "contracts"
+            "index.md"
+            "<contract-pages>.md"
          "mcp_layout.md"
-         "uris.md"
+         "prompts"
+            "<prompt-id>"
+               "PROMPT.md"
+               "references"
          "skills"
-            "new-skill"
-               "SKILL.md"
-               "references"
-            "copilot-customization"
-               "SKILL.md"
-               "references"
-            "fastapi-async-sqlalchemy-modernization"
-               "SKILL.md"
-               "references"
-            "fastapi-uv-docker"
-               "SKILL.md"
-               "references"
-            "nicegui"
-               "SKILL.md"
-               "references"
-            "nicegui-ui-customization"
-               "SKILL.md"
-               "references"
-            "pytest-scaffolding"
-               "SKILL.md"
-               "references"
-            "python-logging-dictconfig"
-               "SKILL.md"
-               "references"
-            "vscode-configuration"
-               "SKILL.md"
-               "references"
-            "zensical-docs"
+            "<skill-id>"
                "SKILL.md"
                "references"
+                  "<reference>.md"
       "site"
          "static build output"
       "src"
          "personal_mcp"
+            "__init__.py"
             "main.py"
             "mcp.py"
-            "web"
-               "app.py"
-               "docs_mount.py"
             "catalog"
-               "server.py"
+               "<catalog-modules>.py"
+            "registry"
+               "<registry-modules>.py"
+            "web"
+               "<web-modules>.py"
             "skills"
-               "document_loader.py"
+               "<skills-modules>.py"
 ```
 
 Notes:
@@ -88,7 +68,8 @@ Notes:
 1. docs contains both project-authored pages and the canonical skill Markdown tree.
 2. site contains static build output only.
 3. docs/skills contains canonical skill Markdown and reference Markdown.
-4. MCP resources and docs site read from the same Markdown sources.
+4. docs/prompts contains canonical prompt Markdown used for prompt catalog and document surfaces.
+5. MCP resources and docs site read from the same Markdown sources.
 
 ## Runtime Composition
 

docs/prompts/initial-test-structure/PROMPT.md

@@ -0,0 +1,23 @@
+---
+name: initial-test-structure
+description: Create an initial pytest test structure for a target project scope using repository conventions.
+x-personal-mcp:
+  id: initial-test-structure
+  version: 1.0.0
+  tags:
+    - pytest
+    - testing
+  capabilities:
+    - resource://prompts/initial-test-structure/document
+  arguments:
+    target_scope:
+      type: string
+      description: Target project, package, or module to scaffold tests for.
+      required: false
+---
+
+# Prompt For Creating Initial Test Structure
+
+Create an initial test structure in `./tests` based around pytest best practices.
+
+Use for an overview of best practices `resource://skills/pytest-scaffolding/document`. Take into account the naming structure too and pull in other relevant resources like for fastapi testing

docs/skills/new-skill/SKILL.md

@@ -46,10 +46,10 @@ If the domain includes naming or hierarchy conventions, include a dedicated nami
 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/contracts/content.md](../../contracts/content.md)
+  - [docs/contracts/frontmatter.md](../../contracts/frontmatter.md)
   - [docs/mcp_layout.md](../../mcp_layout.md)
-  - [docs/uris.md](../../uris.md)
+  - [docs/contracts/uris.md](../../contracts/uris.md)
 
 ## Canonical Skill Shape
 

zensical.toml

@@ -48,9 +48,12 @@ nav = [
   { "Home" = "index.md" },
   { "Guide" = [
     { "Arch" = "architecture.md" },
-    { "Content" = "content.md" },
-    { "Frontmatter" = "frontmatter.md" },
-    { "URIs" = "uris.md" },
+    { "Contracts" = [
+      { "Overview" = "contracts/index.md" },
+      { "Content" = "contracts/content.md" },
+      { "Frontmatter" = "contracts/frontmatter.md" },
+      { "URIs" = "contracts/uris.md" },
+    ] },
     { "MCP" = "mcp_layout.md" },
     { "Copilot" = "copilot.md" },
     { "Usage" = "usage.md" },