docs: Add static documentation site (Starlight / Astro)

[notyorch]

Overview

TUP currently has no public-facing documentation beyond the root README.md and individual module READMEs. A proper documentation site is essential for open-source adoption, client evaluation, and showcasing the project professionally.

Proposed Solution

Build a static documentation site using Starlight (Astro-based), hosted on Cloudflare Pages with automatic deploys from the main branch.

Why Starlight

• Built on Astro — generates fully static HTML, zero JS overhead
• Built-in full-text search (Pagefind) with no backend required
• Dark mode, sidebar navigation, and versioning out of the box
• Markdown + MDX support for interactive code examples

Proposed Site Structure

docs/
├── src/
│   ├── content/
│   │   ├── docs/
│   │   │   ├── getting-started/
│   │   │   │   ├── introduction.md
│   │   │   │   ├── quickstart.md        # docker compose up in 5 min
│   │   │   │   └── architecture.md
│   │   │   ├── detection-engine/
│   │   │   │   ├── how-it-works.md
│   │   │   │   ├── backends.md          # local, HF, NVIDIA, Sentinel
│   │   │   │   └── writing-policies.md
│   │   │   ├── configuration/
│   │   │   │   ├── environment-variables.md
│   │   │   │   └── deployment.md        # Caddy, TLS, production checklist
│   │   │   └── api-reference/
│   │   │       └── manager-api.md
│   └── assets/
├── astro.config.mjs
└── package.json

Changes Required

• Scaffold docs/ directory with npm create astro -- --template starlight
• Write getting-started/quickstart.md (the most important page)
• Write getting-started/architecture.md with a system diagram
• Document all environment variables from .env.example
• Write detection-engine/how-it-works.md explaining the pipeline
• Write detection-engine/backends.md for all supported backends
• Add docs service or separate Cloudflare Pages deployment config
• Add link to docs site in root README.md
• Add GitHub Actions workflow to deploy docs on push to main

Deployment

# .github/workflows/docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
    paths: ['docs/**']
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cd docs && npm ci && npm run build
      - uses: cloudflare/wrangler-action@v3
        with:
          command: pages deploy docs/dist --project-name=tup-docs

Acceptance Criteria

• Site accessible at a public URL (e.g. docs.tup.dev or Cloudflare Pages subdomain)
• Quickstart page lets someone run the stack in under 10 minutes
• All env vars documented with types, defaults, and descriptions
• Search works without a backend
• Site auto-deploys on every main push

Priority

🟡 Low (but high visibility) — major credibility boost for open-source presence and portfolio