# Static Docs Hosting Pattern

## Purpose

This document describes the completed layout and runtime pattern used to host a pre-built static documentation site from the same FastAPI app process that runs the FastMCP server.

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

```mermaid
---
config:
    treeView:
        rowIndent: 40
        lineThickness: 2
    themeVariables:
        treeView:
            labelColor: '#FFFFFF'
            lineColor: '#FFFFFF'
---
treeView-beta
   "project-root"
      "pyproject.toml"
      "uv.lock"
      "zensical.toml"
      "docs"
         "index.md"
         "architecture.md"
         "mcp_layout.md"
         "mcp_contract_steps_1_5.md"
         "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.md"
               "references"
      "site"
         "static build output"
      "src"
         "personal_mcp"
            "main.py"
            "mcp.py"
            "web"
               "app.py"
               "docs_mount.py"
            "catalog"
               "server.py"
            "skills"
               "document_loader.py"
```

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.

## Runtime Composition

The runtime process serves two surfaces:

1. MCP protocol surface from FastMCP
2. Static docs surface from FastAPI static mount

```mermaid
flowchart TD
   A[Docs Registry Loader] --> B[Validated In-Memory Registry]
   B --> C[FastMCP Resource Registration]
   C --> D[MCP Transport]
   C --> E[FastAPI Application]
   E --> F[Static Mount /docs]
   F --> G[Zensical site output directory]
```

Runtime guarantees:

1. Docs registry load and validation happen before resource exposure.
2. Duplicate resource and template registration fails startup (`on_duplicate="error"`).
3. Resource registration is metadata-driven from SKILL frontmatter and reference manifests.
4. Legacy per-skill Python servers and `metadata.yaml` sidecars are not part of the runtime.

## Build and Publish Flow

The docs flow is pre-build only.

1. Read authored docs pages and skill markdown sources.
2. Build static site with Zensical into site.
3. Start app and serve site directory as static files.

No runtime markdown conversion is required.

## Content Merge Pattern

The published docs site always contains both:

1. Project-authored docs pages
2. Skill Markdown content from docs/skills/*/SKILL.md and references

This ensures the public docs reflect architectural guidance and the exact Markdown served by MCP.

## Markdown-to-Resource Mapping

MCP resources map directly to canonical Markdown documents.

Example mapping model:

1. docs/skills/<skill-id>/SKILL.md -> resource://skills/<skill_id>/document
2. docs/skills/<skill-id>/references/<file>.md -> resource://skills/<skill_id>/references/<ref_id> (via frontmatter references manifest)
3. docs/<path>.md -> resource://docs/{path*}

Catalog discovery resources are:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}

Registry-backed registration details:

1. `resource://skills/{skill_id}/document` resolves to each skill's SKILL.md.
2. `resource://skills/{skill_id}/references/{ref_id}` resolves through frontmatter reference manifests.
3. `resource://docs/{path*}` resolves normalized markdown paths under `docs/`.
4. Resource metadata includes explicit mime type and read-only/idempotent annotations.

When clients cannot attach MCP resources directly, thin catalog tools may retrieve the same underlying skill documents indirectly. This does not create a second content source.

## URI Compatibility Policy

This phase is a greenfield break-and-replace baseline.

1. Canonical URIs are the only supported URIs in this runtime.
2. No backward-compatibility aliases or dual registration paths are maintained.
3. Contract changes should update clients to canonical URIs directly.

## Why This Pattern

### Operational Simplicity

One application process serves both protocol and static docs surfaces.

### Deterministic Docs

Published docs are immutable static assets for a given build.

### Documentation Fidelity

The docs site and MCP resources resolve from the same Markdown sources.

### Maintainer Experience

Authors continue to work in markdown while resource contracts remain machine-consumable.

## FastAPI Static Mount Expectations

The FastAPI app is expected to:

1. Mount static directory containing Zensical output.
2. Serve index and asset files from that directory.
3. Keep docs route stable across releases.

Recommended route conventions:

1. /docs for static site root
2. /docs/* for static assets and page routes

## Update Lifecycle

For each documentation update:

1. Edit authored docs and skill markdown content.
2. Rebuild static site.
3. Restart runtime if needed.

This keeps docs publication explicit and predictable.

## Example Source Material

Existing reference docs remain valid content inputs in this pattern:

1. docs/skills/pytest-scaffolding/references/pytest-docs.md
2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md

These are source documents, not deployment artifacts.