# 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.

## Completed-State Layout

```text
project-root/
|
|- pyproject.toml
|- uv.lock
|- zensical.toml
|
|- docs/
|  |- 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 ...
|
|- src/
   |- personal_mcp/
      |- main.py
      |- web/
      |  |- app.py
      |  |- docs_mount.py
      |- catalog/
      |  |- server.py
      |- skills/
         |- pytest_scaffolding/
         |- python_logging_dictconfig/
         |- fastapi_uv_docker/
```

Notes:

1. docs contains authored pages and generated markdown pages.
2. site contains static build output only.
3. MCP resources and docs generation share the same content contract.

## 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[FastMCP Root Server] --> B[MCP Transport]
    A --> C[FastAPI Application]
    C --> D[Static Mount /docs]
    D --> E[Zensical site output directory]
```

## Build and Publish Flow

The docs flow is pre-build only.

1. Read module resources and catalog metadata.
2. Generate docs markdown pages into docs/generated.
3. Build static site with Zensical into site.
4. 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. Resource-derived pattern pages

This ensures the public docs reflect both architectural guidance and live pattern knowledge.

## Resource-to-Docs Mapping

Pattern resources map directly to docs sections.

Example mapping model:

1. resource://skills/<id>/overview -> docs/generated/patterns/<id>.md section Overview
2. resource://skills/<id>/rules -> docs/generated/patterns/<id>.md section Rules
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.

## 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

Resource-derived pages align docs with the exact methodology contracts exposed to agents.

### 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 markdown and resource content.
2. Regenerate docs markdown from resources.
3. Rebuild static site.
4. 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. ../skills/pytest-scaffolding/references/pytest-docs.md
2. ../skills/python-logging-dictconfig/references/python-logging-docs.md
3. ../skills/fastapi-uv-docker/references/fastapi-best-practices.md

These are source documents, not deployment artifacts.