started prompt mechanics

docs/architecture.md

@@ -16,6 +16,8 @@ The system is complete in three layers:
 2. Catalog resources provide normalized discovery.
 3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.
 
+Prompt documents under `docs/prompts/` are also indexed and exposed as first-class catalog and prompt surfaces.
+
 This architecture is anchored by three contracts:
 
 1. Docs-first authored content contract under `docs/` with strict per-skill ownership.
@@ -55,6 +57,17 @@ Each skill publishes resource families:
 
 The document resource returns canonical Markdown, while clients can perform any downstream section extraction they need.
 
+### Prompt Modules
+
+Prompt guidance can be authored in `docs/prompts/` using either canonical prompt directories (`docs/prompts/<prompt-id>/PROMPT.md`) or legacy markdown files during migration.
+
+Prompt modules publish two additive surfaces:
+
+1. prompt resources for catalog and document retrieval
+2. MCP prompt objects for prompt-list/get-prompt style client workflows
+
+This keeps authored markdown as source-of-truth while allowing clients to discover and invoke prompts directly.
+
 ### Catalog Module
 
 The catalog is the canonical discovery layer and publishes normalized records for all modules. It may also expose a minimal set of read-only discovery tools that resolve back to the same canonical markdown content when a client chat surface does not expose MCP resource attachment.
@@ -63,6 +76,8 @@ Typical catalog resources:
 
 1. resource://catalog/skills_index
 2. resource://catalog/skills/{skill_id}
+3. resource://catalog/prompts_index
+4. resource://catalog/prompts/{prompt_id}
 
 Only canonical catalog resources are part of the runtime contract in this phase.
 
@@ -139,6 +154,9 @@ For the full URI semantics, parameter validation rules, and compatibility policy
 3. resource://catalog/skills_index
 4. resource://catalog/skills/{skill_id}
 5. resource://docs/{path*}
+6. resource://catalog/prompts_index
+7. resource://catalog/prompts/{prompt_id}
+8. resource://prompts/{prompt_id}/document
 
 Validation rules:
 
@@ -200,7 +218,7 @@ Markdown remains easy to review, while contracts remain stable for clients.
 
 ### Client Independence
 
-Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt orchestration. However, MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.
+Clients can use Ask, Edit, or Agent modes without requiring prompt-first orchestration. Prompt objects are available as an additive MCP surface, while resource retrieval remains the canonical source path. MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.
 
 ## Authoring and Publishing Lifecycle