swapped docs symlink

2026-08-07 21:07:23 -05:00
parent 5005cd7001
commit f240486a7e
92 changed files with 69 additions and 42 deletions
@@ -0,0 +1,95 @@
+---
+icon: lucide/server
+---
+
+# Runtime And Static Docs Layout
+
+## Purpose
+
+The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `docs/`; runtime providers and Zensical consume that same packaged tree for different purposes.
+
+## Repository Layout
+
+```mermaid
+---
+config:
+    treeView:
+        rowIndent: 32
+        lineThickness: 2
+---
+treeView-beta
+   "project-root"
+      "docs"
+         "prompts/<prompt-id>/PROMPT.md"
+         "skills/<skill-id>/SKILL.md"
+         "skills/<skill-id>/<supporting-files>"
+         "<general-pages>.md"
+      "site"
+         "static build output"
+      "src/personal_mcp"
+         "mcp.py"
+         "prompts/content.py"
+         "prompts/models.py"
+         "prompts/provider.py"
+         "registry/"
+         "skills/provider.py"
+         "web/"
+```
+
+Ownership rules:
+
+1. `docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
+2. Each file under `docs/prompts/` owns its prompt metadata, argument schema, and prose.
+3. The docs registry owns only general Markdown resources and explicitly excludes skills.
+4. `site/` is generated output.
+5. The deleted custom `catalog/` package is not part of the runtime.
+
+## Runtime Composition
+
+```mermaid
+flowchart TD
+   A[Packaged Skills] --> B[SkillsDirectoryProvider]
+   C[Packaged Prompt Markdown] --> D[Markdown Prompt Provider]
+   E[Packaged Markdown] --> F[Docs Registry]
+   B --> G[FastMCP]
+   D --> G
+   F --> G
+   G --> H[MCP Transport]
+   H --> K[FastAPI Application]
+   L[Pre-built site] --> M[Static /docs Mount]
+   K --> M
+```
+
+Runtime guarantees:
+
+1. Providers are installed before serving requests.
+2. Prompt discovery rescans authored files on each list and get request.
+3. Duplicate components fail according to FastMCP's configured duplicate policy.
+4. Skills and prompts use native FastMCP component surfaces.
+5. General docs path parsing rejects traversal, backslashes, non-Markdown paths, and the skill namespace.
+
+## Build And Publish Flow
+
+1. Author prompt definitions and prose under `docs/prompts/`.
+2. Run `uv run zensical build` to produce `site/`.
+3. Build the wheel, which packages the authored docs under `personal_mcp/docs/`.
+4. Start the app and serve MCP plus the static site.
+
+No runtime Markdown-to-HTML conversion occurs.
+
+## Machine-Facing Mapping
+
+1. `docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
+2. Skill supporting files map to `skill://<skill-id>/<path>`.
+3. Declarative prompt documents map to native MCP prompt names.
+4. General `docs/<path>.md` maps to `resource://docs/{path*}`.
+
+The server publishes no tool projections of resources or prompts.
+
+## Public Surface Policy
+
+Canonical provider and protocol surfaces are the only public interfaces.
+
+## Static Mount Expectations
+
+The FastAPI app mounts the Zensical output, serves index and asset files, and returns a clear unavailable response when the static output is absent. The site directory is immutable for a given build and remains separate from packaged authored Markdown.