Legendary Arena Lab

wiki

Operator Wiki

An internal engineering reference for the Legendary Arena hosting migration: moving api.legendary-arena.com and its PostgreSQL off Render onto a self-hosted DigitalOcean Ubuntu droplet behind Cloudflare, and relocating the ewiki to Cloudflare Pages.

Last updated: 2026-07-24

What this wiki is

A markdown-only reference that explains how the migration’s host subsystems and infra artifacts work, for an operator reading and running them. Each page is an entity — a host subsystem, an infra artifact, a migration concept, or an operational procedure — with cross-references and citations to the artifacts that govern it.

The wiki answers questions like:

  • “What is X, and which file in this repo owns it?”
  • “Which plan phase and infra script govern X?”
  • “What does X interact with, and what edge cases bite during cutover?”

What this wiki is not

  • Authoritative. Every claim cites a higher-authority source (docs/PLAN.md , the infra/ artifacts, content/ runbooks). The wiki explains; the cited artifacts govern and execute.
  • The operator runbook. The step-by-step, copy-paste runbooks live under content/ as Hugo pages behind Cloudflare Access. This wiki is the longer-form companion that points back at them.
  • The plan. docs/PLAN.md owns the migration sequence, locked decisions, and phase exit criteria. The wiki cites the plan; it never re-decides.

Relationship to content/

This repo already ships an operator wiki as Hugo sections under content/ (foundations / runtime / web / data / app / ops), rendered behind Cloudflare Access. Those pages are the execution surface — the exact commands an operator runs.

This wiki/ directory is the explainer layer on top of them, modelled on the engine repo’s engineering wiki at C:\pcloud\BB\DEV\legendary-arena\wiki. It is deliberately flat, schema-governed, and cross-referenced. Where a content/ runbook says “run this,” the matching wiki page says “here is what it does, what it touches, and what bites.” The two are kept in sync by citation, not by duplication — the wiki links to the runbook rather than copying its command blocks.

  • INDEX.md — categorized list of all entity pages.
  • SCHEMA.md — the entity-page contract. Read this before adding a page.

Authority hierarchy

The wiki sits at position 6 in this repo’s authority hierarchy (canonical statement in SCHEMA.md § Authority Position ):

1. .claude/CLAUDE.md                 # repo identity + working model
2. docs/PLAN.md                      # migration plan & repo blueprint
3. docs/01-REPO-FOLDER-STRUCTURE.md  # repo map
4. infra/** and .github/workflows/** # executable artifacts (the source of truth)
5. content/**                        # operator runbooks
6. (this wiki)
7. Active conversation context

Wiki pages cite entries 1–5; they never override them. If a wiki page disagrees with a higher-authority artifact, the wiki is wrong and must be corrected.

How to read a wiki page

Every entity page has a fixed shape. Skim front-matter for the machine-readable contract (type, status, related, source); read the body sections in order:

  1. Summary — one to three sentences.
  2. Mechanics — how the owning artifact actually works.
  3. Interactions — which other entities touch it.
  4. Edge Cases — lockout hazards, cutover gotchas, drift risks.
  5. (optional) Execute, Verify, Code Touchpoints, History, Open Questions.
  6. References — bullet list of cited artifacts.

The full schema (front-matter fields, closed sets, status values, section ordering) lives in SCHEMA.md .

Status discipline

  • canonical — every claim is sourced and verified on a real host. Safe to rely on operationally.
  • draft — has uncited claims, content gaps, or (most commonly at this phase) pending real-host verification: the artifact exists and is described accurately, but the migration has not yet run against a production droplet. Do not treat draft pages as proof the step has been exercised.
  • deprecated — superseded; kept for history. Links to its replacement in the first paragraph of Summary.

Contribution conventions

For the full contract, read SCHEMA.md . The shorter working rules:

Adding a new page

  1. The entity must have an owning infra artifact or named subsystem that exists in the repo (do not document a script that isn’t there yet — the planned 50-backup.ps1 / 60-monitor.ps1 get pages when they land).
  2. Filename = the kebab-case transform of the front-matter title.
  3. Front-matter is YAML and wiki-only.
  4. Required sections in fixed order; closed-set type and status; last-reviewed present.
  5. Ground every factual claim in a citable artifact.

Linking conventions

The wiki uses the same incremental linking model as the reference wiki:

write → validate → retro-link

  • Forward-link rule. A page may only link to wiki pages that already exist on disk. Both body links and related lists follow this rule.
  • Bidirectional pattern. When a new page lands, add it to the related list of the pages it connects to.
  • Markdown-relative paths only. No Obsidian wiki-links, no bare URLs in body text.
  • Link integrity is a review gate. Broken internal links fail review.

Status promotion

Promote draft → canonical only when:

  • Every body factual claim has a source citation, and
  • The described behaviour has been verified on a real droplet, and
  • last-reviewed reflects that verification.

Working model

This repo edits shared/structural files serially and prefers additive new files (see .claude/CLAUDE.md and PLAN.md §3 ). Wiki entity pages are new files — safe to author in parallel sessions. SCHEMA.md, README.md, and INDEX.md are the shared files here: edit them serially.

Tradeoffs

An operator wiki that explains rather than executes is not free. It earns its keep by making the migration legible — what each artifact does, what it touches, what bites at 2 AM during cutover — without becoming a second, drifting copy of the runbooks. The guardrails that keep it honest:

  • Authority position (6). The wiki cites the plan and the scripts; it governs nothing. A wiki/artifact disagreement means the wiki is wrong. See SCHEMA.md § Authority Position .
  • No duplication. The wiki links to content/ runbooks and infra/ scripts; it does not restate their command blocks. See Relationship to content/ .
  • Honest status. On-host behaviour stays draft until verified on a real droplet, even when fully cited. See SCHEMA.md § Status Values .

Keep those three and the wiki compounds; drop any one and it decays into an unverifiable second source of truth.

Origin

Modelled on the engineering wiki in the engine repo (C:\pcloud\BB\DEV\legendary-arena\wiki), which is itself loosely inspired by Andrej Karpathy’s LLM Wiki pattern. The schema, conventions, and authority position here are specific to this migration repo and locked in SCHEMA.md .