docs

docs/architecture.md

@@ -8,12 +8,11 @@ icon: lucide/library
 
 The platform is implemented as a resource-first MCP system with an integrated static documentation surface. The same methodology content powers both MCP resources and the published docs site.
 
-The system is complete in four layers:
+The system is complete in three layers:
 
-1. Pattern modules expose methodology as MCP resources.
+1. Canonical methodology is maintained in Markdown skill documents.
 2. Catalog resources provide normalized discovery.
-3. A docs export step materializes resource content into markdown.
+3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.
-4. Zensical builds a static site that is served by the FastAPI app in the FastMCP runtime process.
 
 This architecture keeps authored content human-friendly while preserving machine-stable contracts.
 
@@ -31,12 +30,9 @@ The architecture is designed to satisfy three long-term requirements:
 
 Each module encapsulates one methodology domain and publishes resource families:
 
-1. overview
+1. document
-2. rules
-3. checklist
-4. references
 
-Tools are intentionally narrow and optional. They exist only for deterministic export-like behavior.
+The document resource returns canonical Markdown, while clients can perform any downstream section extraction they need.
 
 ### Catalog Module
 
@@ -51,14 +47,14 @@ Typical catalog resources:
 
 ### Content Sources
 
-Content is authored in markdown and managed as long-form reference material. Resource handlers load authored content and expose it through stable resource URIs.
+Content is authored in markdown and managed as long-form reference material. Resource handlers expose the same authored documents through stable resource URIs.
 
 ### Static Docs Surface
 
-Static docs are generated from two merged content streams:
+Static docs are built directly from two markdown source streams:
 
 1. Project-authored docs pages
-2. Generated pages derived from MCP resources
+2. Skill and reference markdown pages
 
 The merged docs tree is built by Zensical into static files and served by the FastAPI app.
 
@@ -68,12 +64,10 @@ The merged docs tree is built by Zensical into static files and served by the Fa
 flowchart TD
     A[Authored Markdown] --> C[Resource Handlers]
     B[Pattern Metadata] --> D[Catalog Resources]
-    C --> E[Docs Export Step]
+    A --> E[Zensical Static Build]
-    D --> E
+    E --> H[FastAPI Static Mount]
-    E --> F[Generated Docs Markdown]
-    F --> G[Zensical Static Build]
-    G --> H[FastAPI Static Mount]
     H --> I[Served Docs Site]
+    D --> I
 ```
 
 ## Contracts
@@ -94,10 +88,7 @@ Each pattern module declares:
 
 Module resource URIs are stable and follow:
 
-1. resource://skills/<skill_id>/overview
+1. resource://skills/<skill_id>/document
-2. resource://skills/<skill_id>/rules
-3. resource://skills/<skill_id>/checklist
-4. resource://skills/<skill_id>/references
 
 Catalog resource URIs are stable and discovery-focused.
 
@@ -125,7 +116,7 @@ Methodology is authored once and reused in both MCP resources and docs pages.
 
 ### High-Fidelity Agent Context
 
-Resources expose explicit, attachable context for accurate implementation behavior.
+Resources expose the same canonical Markdown that humans author and review.
 
 ### Operational Simplicity
 
@@ -143,9 +134,8 @@ Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt
 
 1. Update markdown reference content.
 2. Update metadata if capability surface changes.
-3. Run resource export to generated docs markdown.
+3. Build static docs with Zensical.
-4. Build static docs with Zensical.
+4. Serve built output through FastAPI static mount.
-5. Serve built output through FastAPI static mount.
 
 ## Scope and Non-Goals
 

docs/mcp_layout.md

@@ -6,6 +6,8 @@ This document describes the completed layout and runtime pattern used to host a
 
 This design intentionally avoids runtime docs rendering and avoids a separate docs hosting service.
 
+It also treats Markdown as the single source of truth for both MCP resources and published docs.
+
 ## Completed-State Layout
 
 ```text
@@ -19,16 +21,21 @@ project-root/
 |  |- index.md
 |  |- architecture.md
 |  |- mcp_layout.md
-|  |- generated/
-|     |- patterns/
-|        |- index.md
-|        |- pytest-scaffolding.md
-|        |- python-logging-dictconfig.md
-|        |- fastapi-uv-docker.md
 |
 |- site/
 |  |- ... static files built by zensical ...
 |
+|- skills/
+|  |- pytest-scaffolding/
+|  |  |- SKILL.md
+|  |  |- references/
+|  |- python-logging-dictconfig/
+|  |  |- SKILL.md
+|  |  |- references/
+|  |- fastapi-uv-docker/
+|     |- SKILL.md
+|     |- references/
+|
 |- src/
    |- personal_mcp/
       |- main.py
@@ -45,9 +52,10 @@ project-root/
 
 Notes:
 
-1. docs contains authored pages and generated markdown pages.
+1. docs contains project-authored pages.
 2. site contains static build output only.
-3. MCP resources and docs generation share the same content contract.
+3. skills contains canonical skill Markdown and reference Markdown.
+4. MCP resources and docs site read from the same Markdown sources.
 
 ## Runtime Composition
 
@@ -68,10 +76,9 @@ flowchart TD
 
 The docs flow is pre-build only.
 
-1. Read module resources and catalog metadata.
+1. Read authored docs pages and skill markdown sources.
-2. Generate docs markdown pages into docs/generated.
+2. Build static site with Zensical into site.
-3. Build static site with Zensical into site.
+3. Start app and serve site directory as static files.
-4. Start app and serve site directory as static files.
 
 No runtime markdown conversion is required.
 
@@ -80,22 +87,20 @@ No runtime markdown conversion is required.
 The published docs site always contains both:
 
 1. Project-authored docs pages
-2. Resource-derived pattern pages
+2. Skill Markdown content from skills/*/SKILL.md and references
 
-This ensures the public docs reflect both architectural guidance and live pattern knowledge.
+This ensures the public docs reflect architectural guidance and the exact Markdown served by MCP.
 
-## Resource-to-Docs Mapping
+## Markdown-to-Resource Mapping
 
-Pattern resources map directly to docs sections.
+MCP resources map directly to canonical Markdown documents.
 
 Example mapping model:
 
-1. resource://skills/<id>/overview -> docs/generated/patterns/<id>.md section Overview
+1. skills/<slug>/SKILL.md -> resource://skills/<id>/document
-2. resource://skills/<id>/rules -> docs/generated/patterns/<id>.md section Rules
+2. skills/<slug>/references/*.md -> referenced sections or linked companion documents
-3. resource://skills/<id>/checklist -> docs/generated/patterns/<id>.md section Checklist
-4. resource://skills/<id>/references -> docs/generated/patterns/<id>.md section References
 
-Catalog resources generate index pages and navigation pages.
+Catalog resources provide discovery metadata and stable identifiers.
 
 ## Why This Pattern
 
@@ -109,7 +114,7 @@ Published docs are immutable static assets for a given build.
 
 ### Documentation Fidelity
 
-Resource-derived pages align docs with the exact methodology contracts exposed to agents.
+The docs site and MCP resources resolve from the same Markdown sources.
 
 ### Maintainer Experience
 
@@ -132,10 +137,9 @@ Recommended route conventions:
 
 For each documentation update:
 
-1. Edit authored markdown and resource content.
+1. Edit authored docs and skill markdown content.
-2. Regenerate docs markdown from resources.
+2. Rebuild static site.
-3. Rebuild static site.
+3. Restart runtime if needed.
-4. Restart runtime if needed.
 
 This keeps docs publication explicit and predictable.