diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index e142cf0..fb58dce 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -8,18 +8,19 @@ This workspace contains detailed planning artifacts derived from the finalized m ## Folder Layout -- `epics/` - One file per epic with implementation slices. -- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `epics/` - One file per **player-facing** epic (E1–E9) with implementation slices. +- `tooling/` - Cross-cutting **operator** tracks (e.g. content authoring) that are **not** numbered with the nine core epics; same slice style, separate **CT.\*** module IDs. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (E1–E9 and CT modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. - `milestones/` - Phase-gated implementation tracks and pass/fail checklists. ## Working Rules 1. Do not rewrite baseline vision in these files; link back to the master plan. 2. Keep slices backlog-ready (clear owner, dependencies, acceptance criteria). -3. Use stable IDs (E1, E1.M1, P1.M1, etc.) to preserve traceability. +3. Use stable IDs (`E1`, `E1.M1`, etc.) for core game epics; use **`CT.M1`**-style IDs for [content tooling](tooling/internal_authoring.md) so tooling stays out of the E1–E9 sequence. 4. Every new slice must reference telemetry and validation where applicable. -## Epic Files +## Epic files (E1–E9, master plan) | Epic | Document | |------|----------| @@ -35,6 +36,12 @@ This workspace contains detailed planning artifacts derived from the finalized m Template for new epics or major revisions: [epics/_epic_template.md](epics/_epic_template.md) +## Cross-cutting tooling (not E1–E9) + +| Track | Document | Modules (register) | +|-------|----------|-------------------| +| Internal authoring & content pipeline | [tooling/internal_authoring.md](tooling/internal_authoring.md) | **CT.M1–M3** | + ## Next Actions 1. Expand slices into engineering tickets; keep module IDs aligned with the master plan. diff --git a/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md b/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md new file mode 100644 index 0000000..84758a0 --- /dev/null +++ b/docs/decomposition/modules/CT_M1_ContentValidationPipeline.md @@ -0,0 +1,45 @@ +# CT.M1 — ContentValidationPipeline + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | CT.M1 | +| **Track** | [Content tooling — internal authoring](../tooling/internal_authoring.md) (cross-cutting; not E1–E9) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Own **content schema artifacts**, **automated validation** in CI and locally, and (when wired) **server-side smoke loading** so file-backed catalogs cannot drift from enforced contracts. + +## Responsibilities + +- Publish and version **JSON Schema** (or agreed equivalent) for catalogs consumed by **E2.M1**, **E3.M2–M3**, **E4.M1**, **E7.M1**. +- Run **structural** and **cross-reference** validation before merge; expose the same rules to **CT.M2**. +- Optional: **C#** deserialize test or boot check aligned with `ContentCatalogRegistry` (or successor). + +## Key contracts + +| Contract | Role | +|----------|------| +| Content schema files | `$id` + versioning per [contracts.md](contracts.md) | +| Validation CLI | Stable exit codes and machine-readable errors for CI and studio | + +## Module dependencies + +- **Soft:** Gameplay modules above must define or stabilize the **shapes** being validated; pipeline can ship **minimal** schemas first. + +## Dependents (by design) + +- **CT.M2** — AuthoringStudioApplication +- **CT.M3** — ContentReferenceAndBundleWorkflows + +## Related implementation slices + +Content tooling **Slice 1** — schemas + CI; **Slice 4** — server parity hardening. + +## Source anchors + +- Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md) +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/CT_M2_AuthoringStudioApplication.md b/docs/decomposition/modules/CT_M2_AuthoringStudioApplication.md new file mode 100644 index 0000000..5d0eb53 --- /dev/null +++ b/docs/decomposition/modules/CT_M2_AuthoringStudioApplication.md @@ -0,0 +1,45 @@ +# CT.M2 — AuthoringStudioApplication + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | CT.M2 | +| **Track** | [Content tooling — internal authoring](../tooling/internal_authoring.md) (cross-cutting; not E1–E9) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Internal **authoring UI** (TypeScript-first per [tech stack](../../architecture/tech_stack.md)) for editing **`content/**`** with **validation parity** with CI and a practical **zone graph** authoring experience. + +## Responsibilities + +- Browse and edit catalog files; **forms** and **pickers** for IDs (items, zones, quests) as catalogs exist. +- **Topology:** Visual **graph** for **ZoneDef** / **ZoneEdge** / **TravelRule** aligned with **E4.M1**. +- **Security:** Internal-only deployment; filesystem or local API access must not become part of the public game surface. + +## Key contracts + +| Contract | Role | +|----------|------| +| Studio ↔ repo | Read/write JSON (or YAML) under agreed roots; no separate authoring DB as source of truth | +| Validator integration | Invokes **CT.M1** rules for inline feedback | + +## Module dependencies + +- **CT.M1** — ContentValidationPipeline + +## Dependents (by design) + +- **CT.M3** — optional integrated UX for reference index and bundles + +## Related implementation slices + +Content tooling **Slice 2** — studio core + topology editor. + +## Source anchors + +- Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md) +- [E4.M1 — ZoneGraphAndTravelRules](E4_M1_ZoneGraphAndTravelRules.md) +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/CT_M3_ContentReferenceAndBundleWorkflows.md b/docs/decomposition/modules/CT_M3_ContentReferenceAndBundleWorkflows.md new file mode 100644 index 0000000..878a415 --- /dev/null +++ b/docs/decomposition/modules/CT_M3_ContentReferenceAndBundleWorkflows.md @@ -0,0 +1,45 @@ +# CT.M3 — ContentReferenceAndBundleWorkflows + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | CT.M3 | +| **Track** | [Content tooling — internal authoring](../tooling/internal_authoring.md) (cross-cutting; not E1–E9) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +**Workflow depth** after the MVP studio: project-wide **reference graph**, safer **renames**, **schema version** warnings across files, and optional **content bundle** manifests to reduce client/server drift. + +## Responsibilities + +- Build an index of IDs and references across `content/**` for find-usages and rename planning. +- Emit optional **hash/version manifest** for CI and deploy pipelines (aligns with tech stack bundle note). +- Document operational practices (PR review for content, bundle promotion). + +## Key contracts + +| Contract | Role | +|----------|------| +| `ContentBundleManifest` (optional) | Lists files, schema versions, content hashes | +| Reference report | Machine-readable graph for CI or review tools | + +## Module dependencies + +- **CT.M1** — ContentValidationPipeline +- **CT.M2** — AuthoringStudioApplication (recommended for integrated UX) + +## Dependents (by design) + +- None within the CT track; ops/deploy may consume manifests. + +## Related implementation slices + +Content tooling **Slice 3** — reference index and optional bundles. + +## Source anchors + +- Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md) +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 3d4745e..c633e12 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -104,6 +104,18 @@ Gameplay **content and curves** default to **boot load** with optional **dev-onl | E9.M3 | LiveBalanceControlPlane | E9.M2, E5.M1, E2.M4, E3.M5 | BalancePatch, ConfigVersion, RolloutState | Production | Planned | | E9.M4 | IntegrityAndAbuseResponse | E9.M1 | IntegritySignal, IncidentTicket, EnforcementAction | Pre-production | Planned | +### Cross-cutting — Content tooling (not E1–E9) + +Operator-facing authoring infrastructure; module IDs use the **CT** prefix. Program doc: [`tooling/internal_authoring.md`](../tooling/internal_authoring.md). + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| CT.M1 | ContentValidationPipeline | Soft: E2.M1, E3.M2–M3, E4.M1, E7.M1 (shape alignment) | JSON Schema bundle, validation CLI, error schema | Prototype | Planned | +| CT.M2 | AuthoringStudioApplication | CT.M1 | Studio project layout, optional local content API | Prototype | Planned | +| CT.M3 | ContentReferenceAndBundleWorkflows | CT.M1; CT.M2 (recommended) | ContentBundleManifest (optional), reference graph | Pre-production | Planned | + +**CT.\*** modules consume **gameplay content** contracts from E1–E9; they do not replace **E7** runtime quest semantics or **E4** server travel evaluation. + ## Per-module documentation | Module ID | Document | @@ -145,6 +157,9 @@ Gameplay **content and curves** default to **boot load** with optional **dev-onl | E9.M2 | [E9_M2_KpiDashboardsAndAlerting.md](E9_M2_KpiDashboardsAndAlerting.md) | | E9.M3 | [E9_M3_LiveBalanceControlPlane.md](E9_M3_LiveBalanceControlPlane.md) | | E9.M4 | [E9_M4_IntegrityAndAbuseResponse.md](E9_M4_IntegrityAndAbuseResponse.md) | +| CT.M1 | [CT_M1_ContentValidationPipeline.md](CT_M1_ContentValidationPipeline.md) | +| CT.M2 | [CT_M2_AuthoringStudioApplication.md](CT_M2_AuthoringStudioApplication.md) | +| CT.M3 | [CT_M3_ContentReferenceAndBundleWorkflows.md](CT_M3_ContentReferenceAndBundleWorkflows.md) | ## Status Legend diff --git a/docs/decomposition/tooling/internal_authoring.md b/docs/decomposition/tooling/internal_authoring.md new file mode 100644 index 0000000..f5c07cf --- /dev/null +++ b/docs/decomposition/tooling/internal_authoring.md @@ -0,0 +1,99 @@ +# 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. diff --git a/docs/plans/internal-content-authoring.md b/docs/plans/internal-content-authoring.md new file mode 100644 index 0000000..5843f67 --- /dev/null +++ b/docs/plans/internal-content-authoring.md @@ -0,0 +1,102 @@ +# Internal world and content authoring (plan) + +**Status:** Planning only — not an implementation backlog ticket. Use this doc to decide scope, phasing, and ownership before building tooling. + +**Vision plan:** **Tooling epic — Internal authoring and content pipeline (CT)** in [`neon_sprawl_vision.plan.md](../../neon_sprawl_vision.plan.md) (Core Epic Map + **Content tooling modules (CT)** under System Modules). + +**Decomposition:** [Internal authoring (cross-cutting)](../decomposition/tooling/internal_authoring.md) — modules **CT.M1–M3** (not numbered with core epics E1–E9). + +**Related:** [Tech stack — content pipeline](../architecture/tech_stack.md), [Contract kinds — Content](../decomposition/modules/contracts.md), [content/README.md](../../content/README.md). + +--- + +## Why this exists + +Neon Sprawl is **data-driven** for skills, items, recipes, quests, and (eventually) world topology. An **internal authoring stack** reduces friction for world designers and content authors: valid IDs, consistent JSON, and a fast loop from edit → CI → server/client consumption — without giving the game client authority over definitions. + +--- + +## Context in the repo (today) + +- **Content:** [`content/`](../../content/) holds catalogs; skills exist today with a co-located schema under `content/schemas/`. Items, recipes, quests, and zone graphs will follow the same pattern as those modules land. +- **Decomposition:** Shapes are named in epics and modules — e.g. `ItemDef` / `RecipeDef` ([Epic 3 — Crafting](../decomposition/epics/epic_03_crafting_economy.md)), `ZoneDef` / `ZoneEdge` / `TravelRule` ([Epic 4 — World topology](../decomposition/epics/epic_04_world_topology.md)), `QuestDef` ([Epic 7 — Quest / Faction](../decomposition/epics/epic_07_quest_faction.md)), with detail in [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md) and [E7.M1](../decomposition/modules/E7_M1_QuestStateMachine.md). +- **Stack:** The [tech stack](../architecture/tech_stack.md) locks **authoritative** simulation to **C#** and allows **TypeScript/JavaScript** for **content tooling** (validators, internal UIs, one-off scripts). + +--- + +## Goals (v1 of the tooling program) + +1. **Single source of truth:** Definitions live in **versioned files** in git (JSON/YAML), not a private database, unless a later phase adds an explicit export from a temp store. +2. **Fast iteration:** Authors get **inline validation**, **ID pickers** (items, zones, quests), and clear errors before merge. +3. **Topology:** Support **zone graph** authoring (nodes, edges, travel rules) aligned with **E4.M1**; treat seamless region handoff ([E4.M3](../decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md)) as a later editor concern once the sim consumes it. +4. **Safety:** Internal-only use; any HTTP surface for the tool stays **separate** from the public game API and uses **proportionate auth** per phase ([tech stack — security](../architecture/tech_stack.md)). + +--- + +## Non-goals (first release) + +- Replacing Godot (or a DCC) for **full 3D world sculpting** — optional **import/preview** later. +- **Client-authoritative** definitions — the tool **authors data**; the **server** remains authoritative at runtime. + +--- + +## Target architecture (high level) + +| Piece | Role | +|--------|------| +| **Content files + JSON Schema** | Canonical definitions; validate in **CI** and locally ([contracts — Content kind](../decomposition/modules/contracts.md)). | +| **Validator** | Same rules in CI and in the editor: schema compliance + **cross-table checks** (e.g. recipe inputs reference real `ItemDef` IDs). | +| **Authoring UI** | Small **TypeScript** app (e.g. Vite + React) or desktop shell (Tauri/Electron) for filesystem-backed projects — decision at kickoff. | +| **Server** | Loads the same files at boot (and optional **smoke tests** that deserialize all catalogs). | +| **Godot (optional)** | Read-only debug preview of district/zone data — not required for MVP. | + +--- + +## Phased roadmap (suggested) + +### Phase 0 — Contracts and validation spine + +- Publish minimal **JSON Schemas** for `ItemDef`, `RecipeDef`, `QuestDef`, and zone graph payloads; align **one** canonical schema location with [contracts.md](../decomposition/modules/contracts.md) (`contracts/schemas/content/` vs co-located — pick once). +- Wire **CI** so `content/**/*.json` cannot merge invalid (Node `ajv` / CLI or `dotnet` validator). +- Optional: **dotnet** test that **loads** all content (catches deserialization drift). + +### Phase 1 — “Content Studio” MVP + +- **File-backed** project: browse `content/`, edit with **forms** guided by schema (hand-built or generated). +- **Topology:** Visual **graph** for zones + edges + `TravelRule` forms; export to the agreed JSON shape. +- **Economy / quests:** Tables or forms for items, recipes, quest steps with **pickers** for IDs. +- **Ergonomics:** `npm run validate`, optional watch mode, pre-commit hook if desired. + +### Phase 2 — Workflow polish + +- **Reference index** for find-references and safer renames across files. +- **Schema versioning** policy per contracts doc; warn on mixed versions in one bundle. +- **Optional bundles:** Hash-versioned content blobs for client/server drift control ([tech stack](../architecture/tech_stack.md)). + +### Phase 3 — Depth (when simulation supports it) + +- Spawn / ecology authoring ([E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md)). +- Spatial helpers (Godot marker export, CSV import, 2D overlays if `ZoneDef` gains coordinates). +- Documented flows for applying bulk content updates to **staging** DBs while **git** remains truth. + +--- + +## Open decisions (before implementation) + +- **UI shell:** Browser + local API vs Tauri/Electron for native “open folder.” +- **Authoring format default:** JSON vs YAML for hand editing. +- **Zone graph storage:** One graph file per district vs split `zones` / `edges` files — trade merge conflicts vs navigation. + +--- + +## Success metrics (when you implement) + +- Adding **item + recipe + quest** that ties them together takes **minutes**, with **zero** validation surprises on `main`. +- Zone graph edits do not introduce **illegal transitions** in playtests relative to server **TravelRule** evaluation. + +--- + +## Security and operations + +- Run the tool on **VPN/localhost** until hardening is explicit. +- **Audit trail:** prefer **git history**; use PR review for `content/` if the team grows. diff --git a/neon_sprawl_vision.plan.md b/neon_sprawl_vision.plan.md index fd91f2f..b3c718a 100644 --- a/neon_sprawl_vision.plan.md +++ b/neon_sprawl_vision.plan.md @@ -346,6 +346,14 @@ Transform the validated prototype into a scalable production-ready development m - **Scope:** Metrics pipeline, tuning controls, event tooling, anti-cheat/anti-bot workflows, incident runbooks. - **Success criteria:** Team can operate, balance, and protect the game continuously post-launch with fast feedback loops. +### Tooling epic — Internal authoring and content pipeline (CT) + +**Type:** Operator- and build-focused **tooling epic**, parallel to the numbered **E1–E9** player/product epics above. It does **not** extend the sequence to “Epic 10”; modules use the **`CT.M#`** prefix. Full program doc (slices, risks, DoD): [`docs/decomposition/tooling/internal_authoring.md`](docs/decomposition/tooling/internal_authoring.md). + +- **Ownership focus:** Content Engineering + Tools + Build/CI +- **Scope:** JSON (or YAML) schemas for catalogs, **CI and local validation** (including cross-table reference checks), optional **internal authoring UI** (TypeScript-friendly per tech stack), reference/rename workflows, optional content bundles; consumes contract *shapes* from **E2 / E3 / E4 / E7** as those stabilize. +- **Success criteria:** Zones, items, recipes, and quests can be authored as **file-backed, versioned** data with merge gates that prevent broken references; no separate authoring database as source of truth. + ## System Modules by Epic (Level 2) Module template: @@ -566,6 +574,26 @@ Module template: - Dependencies: E9.M1. - Stage target: Pre-production. +### Content tooling modules (CT) — Internal authoring + +**Tooling track** (not E1–E9). Depends **softly** on catalog shapes from **E2.M1**, **E3.M2–M3**, **E4.M1**, **E7.M1**; see [`docs/decomposition/tooling/internal_authoring.md`](docs/decomposition/tooling/internal_authoring.md). + +- **CT.M1 ContentValidationPipeline** + - Responsibility: Canonical schemas for content files; CI and local validation; optional server/test smoke load of catalogs. + - Key contracts: JSON Schema bundle, validation CLI, stable error format for editors. + - Dependencies: Soft alignment with E2/E3/E4/E7 content contracts; can start with minimal schemas. + - Stage target: Prototype. +- **CT.M2 AuthoringStudioApplication** + - Responsibility: Internal authoring app (e.g. Vite + React) for `content/**`, forms and ID pickers, zone graph editing aligned with **E4.M1** payloads. + - Key contracts: Repo read/write paths; optional local API for dev browser; invokes **CT.M1** rules. + - Dependencies: CT.M1. + - Stage target: Prototype. +- **CT.M3 ContentReferenceAndBundleWorkflows** + - Responsibility: Project-wide reference index, safer renames, schema-version warnings; optional bundle manifest for client/server parity. + - Key contracts: `ContentBundleManifest` (optional), reference graph for CI/review. + - Dependencies: CT.M1; CT.M2 recommended for integrated UX. + - Stage target: Pre-production. + ## Module Dependency Flow (Level 2) ```mermaid