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.
-4. Zensical builds a static site that is served by the FastAPI app in the FastMCP runtime process.
+3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it 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
-2. rules
-3. checklist
-4. references
+1. document
 
-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]
-    D --> E
-    E --> F[Generated Docs Markdown]
-    F --> G[Zensical Static Build]
-    G --> H[FastAPI Static Mount]
+    A --> E[Zensical Static Build]
+    E --> 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
-2. resource://skills/<skill_id>/rules
-3. resource://skills/<skill_id>/checklist
-4. resource://skills/<skill_id>/references
+1. resource://skills/<skill_id>/document
 
 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.
-4. Build static docs with Zensical.
-5. Serve built output through FastAPI static mount.
+3. Build static docs with Zensical.
+4. Serve built output through FastAPI static mount.
 
 ## Scope and Non-Goals