Lorewright Wiki

currentCatalog of engineering wiki pages grouped by page kind and subsystem.

Lorewright Engineering Wiki

This wiki is maintained as compiled engineering knowledge from repo sources, not as standalone prose. Every page traces back to concrete source files — schemas, route modules, pipeline scripts — through its source_paths frontmatter. The goal is to make the wiki a derived artifact of the codebase rather than an independent document that drifts out of sync.

Lorewright exposes that content through two repo-owned surfaces:

  • Public static wiki: site/ builds wiki/ into https://madsenjake0.wiki for public browsing.
  • FastAPI wiki API: server/wiki.py serves /api/wiki/* for engineering consumers and API-only diagnostics.

Design Rationale

The wiki exists because code comments and docstrings capture what but rarely capture why or how subsystems relate. A separate documentation site would drift from reality, so the wiki is kept inside the repo and maintained as part of every code change (see the ingest operation in AGENTS.md). Two publishing surfaces serve two audiences: the static site gives read-only public access with zero runtime cost, while the FastAPI API provides machine-readable metadata (staleness, health, commit history) for internal tooling and agent workflows.

The alternative — a standalone Notion/Confluence wiki — was rejected because it breaks the single-source-of-truth principle. Wiki pages here are versioned with the code, reviewed in the same PRs, and validated by the same CI pipeline.

Assumptions & Constraints

  • Source-backed provenance: every non-index page must cite at least one source_paths entry. This is enforced by the lint operation and the /api/wiki/health endpoint. If a page can't point at real code, it doesn't belong in this wiki.
  • Flat file structure: all pages live at wiki/*.md with no subdirectories. The hierarchy is expressed through parent frontmatter, not filesystem nesting. This keeps the static site build simple (glob wiki/*.md) and the FastAPI walker trivial.
  • Frontmatter is the schema: the eight required fields (title, parent, order, tags, kind, status, summary, source_paths) are validated at read time by server/wiki.py. Missing or invalid fields produce 422 errors from the API and broken pages on the static site. The field set is intentionally small and stable — adding a field means updating the parser, the static build, and every existing page.
  • Append-only log: wiki/log.md is the audit trail. It records what changed and why, not the full diff. This is a lightweight alternative to git-log archaeology when you need to understand wiki evolution quickly.

Catalog By Kind

Overview

  • current Architecture: System map, boundaries, and cross-cutting invariants.
  • current Decisions: Decision index and architecture records.

Subsystems

  • current Engine: Core package ownership and runtime extension points.
  • current Server: FastAPI route ownership and request/response patterns.
  • current Data Pipeline: SRD and homebrew ingest and generation flow.
  • current SQLite Schema: SQLite storage and merged view conventions.
  • current Progressions: Generated artifact layout and schema anchors.
  • current Homebrew: Canonical authoring model and projection behavior.
  • current DM Orchestration: Model gateway, tool registry, and session orchestration.
  • current GRPO Combat: 36-example GRPO combat enrichment workflow with exact FIREBALL-sourced allied HP and app DB dependency.

API Contracts

  • current API Contracts: Stable API surfaces for progression, homebrew, rebuild, and wiki endpoints.
  • current SRD Level-Up Contracts: Canonical SRD level-up schema and apply/validate error semantics.

Runbooks

  • current Rebuild Runbook: Repeatable db-refresh and progression rebuild operations.
  • current Testing Strategy: Test matrix and required checks per subsystem change.
  • current MVP Prototype Backlog: Prototype backlog for a playable SRD 2014 DM loop with Mem0-backed memory and deterministic combat.
  • current Vercel Deployment Runbook: Public static wiki deployment and redeploy operations.
  • current Wiki Log: Append-only wiki ingest and lint timeline.

Decisions

Glossary

  • current Glossary: Shared terms used across pipeline, APIs, and docs.

Conceptual Model

The wiki forms a directed acyclic graph rooted at this index page. Each page declares a parent and links to related pages via double-bracket wiki-link syntax. The graph has three structural roles:

  1. Hub pages (this index, Architecture, Decisions) organize the catalog and provide cross-cutting context. They link downward to subsystem and decision pages.
  2. Leaf pages (subsystem, API, runbook, decision, glossary) carry the actual engineering content. They link upward to a parent and laterally to related pages.
  3. The log (Wiki Log) is a special append-only page that records temporal events — ingests, lint fixes, decision additions — forming a timeline orthogonal to the graph structure.

The kind field partitions pages into six categories that map to distinct reading patterns: overviews for orientation, subsystems for deep dives, API pages for contract lookup, runbooks for operational procedures, decisions for historical context, and the glossary for term definitions. This partitioning is reflected in the catalog groupings above.

Operating Notes

  • Frontmatter schema and maintenance rules live in AGENTS.md.
  • The static site reads top-level wiki/*.md files at build time; the FastAPI wiki API walks wiki/ recursively and attaches backlink, staleness, and source metadata. That difference is documented behavior for now.
  • API-only wiki capabilities include GET /api/wiki/health, GET /api/wiki/commits, GET /api/wiki/source, and the toc plus source_metadata fields returned by GET /api/wiki/pages/{slug}.
  • Any task that changes routes, pipeline logic, schemas, manifests, or rebuild workflow must update impacted pages, this catalog, and Wiki Log.