# Internal authoring and content tooling (cross-cutting)

This document is the **program epic** for operator-facing authoring infrastructure. It sits **alongside** the [nine player-facing epics](../README.md) from the master plan (E1–E9): same decomposition style (modules, slices, acceptance criteria), but **not** a tenth numbered player epic. It is captured in the vision plan as the **Tooling epic — Internal authoring and content pipeline (CT)** ([`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map and **Content tooling modules (CT)**).

**Module IDs** use the **CT** prefix (**C**ontent **T**ooling): **CT.M1–M3**. That keeps E1.M1-style IDs reserved for the core game epics.

## Source anchors

- **Execution plan (phasing detail):** [`docs/plans/internal-content-authoring.md`](../../plans/internal-content-authoring.md)
- Master plan — **tooling epic + CT modules:** [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) (Core Epic Map; System Modules — Content tooling **CT**)
- Master plan — product/content assumptions: data-driven catalogs; TS/JS for tooling per [tech stack](../../architecture/tech_stack.md)
- **Contracts:** [`docs/decomposition/modules/contracts.md`](../modules/contracts.md)
- Related modules: **CT.M1**, **CT.M2**, **CT.M3**. **Consumes** gameplay content contract *shapes* from **E2.M1**, **E3.M2–M3**, **E4.M1**, **E7.M1** (schemas and loaders must stay aligned as those modules evolve).

## Ownership and success (Level 1)

- **Ownership focus:** Content Engineering + Tools + Build/CI
- **Success criteria:** Solo or small team can author **zones**, **items**, **recipes**, and **quests** quickly, with **CI and local validation** preventing broken references before merge; **no** shadow databases as source of truth.

## Objective

Deliver an **internal authoring stack**—schemas, validators, optional authoring UI, and workflow helpers—so bulk game data stays **file-backed**, **versioned**, and **consistent** with the authoritative server and with decomposition contracts. This track complements **Epic 3–4–7** (data *consumption* in the live game) by owning the **pipeline** that produces and checks that data.

## Module breakdown

### CT.M1 - ContentValidationPipeline

- **Responsibility:** Canonical JSON (or YAML) Schemas for content catalogs; **CI** and **local** validation (syntax + cross-table rules); optional **server boot** or **test** smoke load that deserializes catalogs.
- **Key contracts:** Schema documents (`$id` + version folders per [`contracts.md`](../modules/contracts.md)); validation CLI; error format consumed by studio.
- **Dependencies:** Stable enough shapes from **E2/E3/E4/E7** content contracts (can start minimal and extend).
- **Stage target:** Prototype

### CT.M2 - AuthoringStudioApplication

- **Responsibility:** Internal **TypeScript** application (e.g. Vite + React) for browsing `content/`, editing catalogs with **forms** and **ID pickers**, and running the same validation as CI; **zone graph** visualization and editing for **E4.M1**-shaped payloads.
- **Key contracts:** Read/write paths to repo `content/**`; optional tiny local HTTP API for filesystem access in browser dev mode.
- **Dependencies:** **CT.M1** (validator behavior and schema versions).
- **Stage target:** Prototype

### CT.M3 - ContentReferenceAndBundleWorkflows

- **Responsibility:** Project-wide **reference index** (find references, safer **rename** suggestions); warnings for **mixed schema versions** in one bundle; optional **content bundle manifest** + hash for client/server drift control (aligns with tech stack “bundles” note).
- **Key contracts:** `ContentBundleManifest` (optional); reference graph export for CI or review.
- **Dependencies:** **CT.M1**; **CT.M2** recommended for UX.
- **Stage target:** Pre-production

## Implementation slices (backlog-ready)

### Slice 1 - Schemas and CI validation (MVP pipeline)

- **Scope:** **CT.M1** — publish schemas for skills, items, recipes, quests, and zone graph; wire **PR CI** so invalid content cannot merge; document validate commands in [`content/README.md`](../../../content/README.md) or tooling README.
- **Dependencies:** Agreement on canonical schema path (`contracts/schemas/content/` vs co-located); see [`internal-content-authoring.md`](../../plans/internal-content-authoring.md).
- **Acceptance criteria:**
  - Every `content/**/*.json` (or agreed glob) is validated on PR.
  - Cross-table rules catch at least: missing **item** IDs on recipes, missing **zone** IDs on edges, missing **quest** IDs on travel rules where applicable.
- **Telemetry / signals:** CI job success/failure; optional `content_validation_failed` counter in ingest (internal) — **not** required for player telemetry.

### Slice 2 - Authoring studio core + topology editor

- **Scope:** **CT.M2** — file tree, JSON editing with validation feedback, **zone graph** editor (nodes/edges/`TravelRule` forms), save back to repo files.
- **Dependencies:** **CT.M1** stable for catalog types in use.
- **Acceptance criteria:**
  - Author can add a **zone**, **edge**, and **recipe** in one session without hand-editing invalid JSON (validator passes on save or shows blocking errors).
  - Internal runbook documents **localhost/VPN** usage; no exposure on public game API.
- **Telemetry / signals:** None required; optional anonymous local usage metrics off by default.

### Slice 3 - Reference index and optional bundles

- **Scope:** **CT.M3** — find references / rename helpers; optional bundle manifest for staging/prod artifact parity.
- **Dependencies:** **CT.M1**, **CT.M2** (for integrated UX).
- **Acceptance criteria:**
  - Renaming an **item** ID surfaces all JSON references before apply.
  - If bundles are in scope: manifest lists file hashes and schema versions; documented in ops runbook.
- **Telemetry / signals:** CI validates manifest integrity on build.

### Slice 4 - Server/content parity hardening (optional gate)

- **Scope:** **CT.M1** extension — `dotnet test` or startup path proves **ContentCatalogRegistry** (or equivalent) loads all files the server expects; fails CI when C# models drift from schema.
- **Dependencies:** Server project owns loader types; coordinate with **E3.M3 / E7.M1** implementation timing.
- **Acceptance criteria:**
  - One **test** or **host build step** fails if any catalog file is rejected by the server deserializer.
- **Telemetry / signals:** CI only.

**Scope note (Epic 7):** Epic 7 already lists “Tools” under ownership for narrative/quest work; this **CT** track owns **shared** authoring infrastructure (schemas, CI, studio shell). Quest-specific UX can land in **CT.M2** slices while **E7.M1** owns runtime `QuestDef` semantics.

## Risks and mitigations

- **Risk:** Tooling drifts from server deserialization.
  - **Mitigation:** Slice 4 parity test; single schema source of truth; align with [`contracts.md`](../modules/contracts.md).
- **Risk:** Authors bypass validation locally and break `main`.
  - **Mitigation:** Required CI on `content/**`; pre-commit hook optional.
- **Risk:** Internal studio exposed publicly.
  - **Mitigation:** Separate host/port, auth per [tech stack — security](../../architecture/tech_stack.md); VPN/local default.

## Definition of done

- **Prototype:** **CT.M1** + **CT.M2** slices 1–2 complete; designers can author core catalogs and zone graphs with CI enforcement.
- **Pre-production:** **CT.M3** reference workflows; optional bundles documented.
- Player-facing epics **3 / 4 / 7** remain the authority for **what** data means at runtime; this track is done when **changing** that data is safe, fast, and traceable in git.