Add a public API wiki at /wiki

Builds docs/ into a static site via mkdocs + mkdocs-material in its own
Docker build stage (docs-builder), so mkdocs itself never ends up in the
runtime image -- only the rendered HTML does, mounted at /wiki alongside
the existing /docs OpenAPI schema (unconditionally, unlike /docs, since
this is curated content meant to be public regardless of
AURORA_API_DOCS_ENABLED).

docs/aurora-core-spec.md (the internal build spec, referenced by "section
N" comments throughout the codebase) is excluded from the built site
entirely via exclude_docs, not just left out of the nav -- it was never
meant for public consumption.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

.gitignore

@@ -21,3 +21,5 @@ Thumbs.db
 .idea/
 .vscode/
 media_cache/
+site/
+/wiki/

app/main.py

@@ -94,6 +94,17 @@ app.mount(
     name="media",
 )
 
+# Public API documentation (mkdocs, built from docs/ -- see
+# docker/api.Dockerfile's docs-builder stage and mkdocs.yml). Unlike /docs
+# (the auto-generated OpenAPI schema, gated by AURORA_API_DOCS_ENABLED
+# since it can reveal more raw internal detail), this is curated,
+# intentionally public content -- always mounted regardless of that flag.
+# The directory only exists in the built Docker image; ensure it's present
+# so a local dev server that hasn't run `mkdocs build` doesn't crash on
+# startup, same reasoning as MEDIA_ROOT above.
+Path("wiki").mkdir(parents=True, exist_ok=True)
+app.mount("/wiki", StaticFiles(directory="wiki", html=True), name="wiki")
+
 
 @app.middleware("http")
 async def request_context_middleware(

docker/api.Dockerfile

@@ -23,6 +23,15 @@ COPY app ./app
 # import string against the CWD regardless.
 RUN pip install --no-cache-dir -e .
 
+# Builds the /wiki static site (mkdocs) in its own stage so mkdocs and its
+# dependencies never end up in the runtime image -- only the rendered HTML
+# does, copied in below.
+FROM base AS docs-builder
+RUN pip install --no-cache-dir mkdocs mkdocs-material
+COPY mkdocs.yml ./
+COPY docs ./docs
+RUN mkdocs build --strict -d /wiki_site
+
 FROM base AS runtime
 RUN useradd --create-home --uid 1000 aurora
 COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
@@ -30,6 +39,7 @@ COPY --from=builder /usr/local/bin /usr/local/bin
 COPY app ./app
 COPY migrations ./migrations
 COPY alembic.ini ./alembic.ini
+COPY --from=docs-builder /wiki_site ./wiki
 # Owned by aurora *before* the volume mount happens — see worker.Dockerfile
 # for why (a fresh named volume otherwise defaults to root-owned, which the
 # non-root `aurora` user below can't write into).

docs/api.md

@@ -2,7 +2,8 @@
 
 Base path: `/api/v1`. Interactive OpenAPI docs are available at `/docs` in
 any environment where `AURORA_API_DOCS_ENABLED=true` (default; set to
-`false` to hide docs in production — section 32).
+`false` to hide docs in production — section 32). This same document is
+also published as a browsable page at `/wiki/api/` (see `mkdocs.yml`).
 
 All responses are JSON, built from Pydantic response schemas
 (`app/schemas/`), never from serialized ORM objects (section 18). Errors use

docs/index.md

@@ -0,0 +1,33 @@
+# Aurora Core
+
+Aurora Core is the metadata backend behind [AMDBS](https://www.amdbs.net) — a
+TMDb/IMDb-style canonical data layer for movies, TV, people, and everything
+that connects them.
+
+This wiki documents the public, read-only HTTP API. If you're building
+against Aurora Core, start with the [API Reference](api.md).
+
+## Base URL
+
+```
+https://api.amdbs.net/api/v1
+```
+
+All responses are JSON. Every entity has a stable, type-prefixed id (e.g.
+`aur_movie_01m1q7p1c...`) — always use the id a response gave you rather
+than constructing one yourself.
+
+## Interactive docs
+
+A live, explorable OpenAPI schema (Swagger UI) is available at
+[`/docs`](/docs) alongside this wiki, when enabled in the current
+environment.
+
+## Where to go next
+
+- **[API Reference](api.md)** — every endpoint, grouped by resource, with
+  query parameters and real example responses.
+- **[Architecture](architecture.md)** — how Aurora Core is put together:
+  ingestion pipeline, caching, provider abstraction.
+- **[Database](database.md)** — the schema itself, table by table.
+- **[Entity relationships](erd.md)** — the same schema as a diagram.

mkdocs.yml

@@ -0,0 +1,51 @@
+site_name: Aurora Core
+site_description: API documentation for Aurora Core, the metadata backend behind AMDBS.
+site_url: https://api.amdbs.net/wiki/
+docs_dir: docs
+site_dir: site
+
+# The build spec is an internal planning document (build-phase instructions
+# referenced by "section N" comments throughout app/), not documentation
+# for API consumers -- excluded from the public wiki entirely rather than
+# just left out of the nav (exclude_docs stops it from being copied into
+# the built site at all, so it isn't reachable at a guessed URL either).
+exclude_docs: |
+  aurora-core-spec.md
+
+nav:
+  - Home: index.md
+  - API Reference: api.md
+  - Architecture: architecture.md
+  - Database: database.md
+  - Entity relationships: erd.md
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.top
+    - toc.follow
+    - content.code.copy
+    - search.suggest
+
+markdown_extensions:
+  - tables
+  - fenced_code
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences

pyproject.toml

@@ -41,6 +41,10 @@ dev = [
 load = [
     "locust>=2.31.0",
 ]
+docs = [
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+]
 
 [build-system]
 requires = ["setuptools>=68"]