The Blueprint

The Blueprint

See also: genesis-protocol.md | pipeline | constitution.md

“A universe is a living system. But a living system should also be inspectable. You should be able to look at it, commit it to version control, and know exactly what’s in there. The Blueprint is how you do that. It’s the universe made legible — and changeable — on your terms.” — Sal

---

TL;DR

• Every universe can be exported as a TOML file: universe.toml. Name, description, storyline settings, pipeline rules, brand tokens, and the full crew roster.
• The DB is always the source of truth. The TOML is a derived snapshot — a versionable representation you can check into Git, edit locally, and push back.
• Deploying a modified TOML reconciles the universe: crew members are upserted, agents missing from the file are set to inactive (never deleted), storyline and brand settings are merged.
• Gate: you cannot deploy a config change without an active release. Accountability before reconfiguration. The pipeline demands it.

---

What the Blueprint Is

Most system config lives in a database, which means it’s invisible. You can’t git diff a database. You can’t review a pull request on who joined the crew or what the WIP limit is. Configuration accumulates without a record.

The Blueprint solves this. Once per universe, any time the Creator needs it, the full configuration of that universe can be exported as a TOML document — human-readable, Git-friendly, diff-able, and re-deployable. It’s infrastructure as code, applied to the universe itself.

The TOML captures:

Section	What’s In It	Status
[universe]	Name and description of the universe	LIVE
[storyline]	Narrative text, pipeline rules (WIP limits, escalation threshold, custom state names), brand tokens (primary/accent color, logo URL)	LIVE
[[crew]]	Every agent in the registry — agent ID, name, model, skill ID, capabilities, active status	LIVE
[pipeline]	Default AI model for Sal + Kael’s pipeline operations	IN DESIGN
[observatory]	Research defaults — synthesis model, persona model, Kano settings	IN DESIGN
[library]	Navigation synthesis model (reserved)	IN DESIGN
[hud]	Visor defaults and layout preferences	IN DESIGN

The DB is always the source of truth. The TOML is a derived view, not a live sync. When you deploy, the TOML reconciles the DB — it doesn’t replace it.

---

The TOML Schema

A complete universe.toml looks like this:

version = "1.0"

[universe]
name = "My Universe"
description = "A brief description of this universe."

[storyline]
narrative = """
The universe's mission, context, and operating mandate.
Sal reads this during orientation. Keep it honest.
"""

[storyline.pipeline]
wip_limit = 5
escalation_threshold = 80

[storyline.pipeline.state_names]
backlog = "Queue"
in_progress = "Building"
completed = "Shipped"

[storyline.brand]
primary_color = "#00FFAA"
accent_color = "#B44AFF"
logo_url = "https://cdn.example.com/logo.png"

# IN DESIGN — per-component model configuration
# [pipeline]
# default_model = "claude-sonnet-4-6"   # Sal + Kael's working model

# [observatory]
# default_model = "claude-opus-4-6"          # Margot + Wren + Harlan synthesis
# default_persona_model = "claude-sonnet-4-6"  # Model for persona conversations
# kano_response_scale = 5
# auto_archive_completed_studies = true

# [library]
# default_model = "claude-sonnet-4-6"   # navigation synthesis model (reserved)

# [hud]
# default_model = "claude-haiku-4-5-20251001"   # Fast model for UI-layer queries
# default_visor = "pipeline"
# sidebar_collapsed = false
# density = "comfortable"

[[crew]]
agent_id = "sal"
name = "Software Sal"
model = ""        # empty — uses [pipeline].default_model
skill = "rig:sal"
capabilities = ["chore", "feature", "bug", "improvement"]
active = true

[[crew]]
agent_id = "kael"
name = "Kael Deepstack"
model = "claude-sonnet-4-6"
skill = "rig:kael"
capabilities = ["feature", "bug", "improvement", "chore"]
active = true

[[crew]]
agent_id = "margot"
name = "Margot Flux"
model = ""        # empty — uses [observatory].default_model
skill = "rig:margot"
capabilities = ["feature", "improvement"]
active = true

[[crew]]
agent_id = "wren"
name = "Wren Glasswork"
model = "claude-sonnet-4-6"
skill = "rig:wren"
capabilities = ["improvement", "feature"]
active = true

[[crew]]
agent_id = "harlan"
name = "Harlan Closer"
model = "claude-sonnet-4-6"
skill = "rig:harlan"
capabilities = ["feature", "improvement"]
active = true

Schema Rules

• version — currently "1.0". Reserved for future migrations.
• [universe] — optional; fields are merged (omitting a field leaves it unchanged in DB).
• [storyline] — optional; omitting the section leaves existing storyline untouched.
• [storyline.pipeline] — wip_limit and escalation_threshold are integers. state_names is a map of status code → display name.
• [storyline.brand] — color values are hex strings (max 20 chars). logo_url max 500 chars.
• [[crew]] — array of crew entries. agent_id is the canonical identifier (used for reconciliation). active = false deactivates. Missing entirely → deactivated.
• [pipeline] — IN DESIGN. Per-component model config for Sal + Kael. default_model sets the AI model for pipeline operations. Individual [[crew]] model keys override the component default.
• [observatory] — IN DESIGN. Research defaults. default_model for synthesis; default_persona_model for conversations; kano_response_scale for Likert width.
• [library] — IN DESIGN. default_model for navigation synthesis (reserved for future use).
• [hud] — IN DESIGN. Visor defaults and layout preferences. default_model uses the lightweight Haiku model for fast UI-layer queries.

---

The Export

The Blueprint is generated on demand. The server reads the live state of the universe — agents, storyline, pipeline rules, brand tokens — and serializes it to TOML. No stored artifact. Every export reflects the current DB state.

Export Endpoint

GET /api/v1/universes/session/:id/config.toml

• Auth: session (the Creator)
• Returns: text/plain; charset=utf-8 with Content-Disposition: attachment; filename="universe.toml"
• Ownership check: validates that the requesting session owns the universe

SDK

// Export as TOML string
const toml = await sdk.universes.exportConfig(universeId);

// Or link directly (for download button)
href={`/api/v1/universes/session/${universeId}/config.toml`}
download="universe.toml"

HUD Surface

The Config page (/:universeSlug/config) renders the current TOML inline — a read-only preview — with a Download button that triggers the Content-Disposition response directly. No JS blob creation. The browser handles the save dialog.

---

The Deploy

A modified TOML can be uploaded back. The server validates the document, checks the release gate, and reconciles each section against the live DB. One file, three reconciliation passes, one atomic outcome.

Deploy Endpoint

POST /api/v1/universes/session/:id/deploy
Content-Type: application/json
X-CSRF-Token: <token>

{ "toml": "version = \"1.0\"\n..." }

• Auth: session + CSRF protection
• Gate: requireActiveUniverseRelease — 403 if no active release exists
• Validates: parses TOML via smol-toml, then validates against Zod schema
• Returns: { success: true } or an error with code

The Release Gate

You cannot deploy a config change without an active release.

This is intentional. Config changes reshape the universe — crew composition, pipeline rules, brand identity. These changes should be logged, reviewable, and reversible. An active release creates that accountability context. If there’s no active release, the deploy endpoint returns 403.

POST /universes/session/:id/deploy
← 403 { "error": "No active release", "code": "RELEASE_GATE" }

The HUD surfaces this as a lock banner on the Config page: “Config is locked. Create an active release to deploy changes.” The lock banner links to the Releases page. One click to unblock.

The Three Reconciliation Passes

When a TOML deploys successfully, the server runs three passes in sequence:

Pass 1: Universe metadata If [universe] is present, name and description are updated on the universes row. Omitting the section = no change.

Pass 2: Storyline If [storyline] is present:

• If a universeStorylines row exists → UPDATE with provided fields
• If no row exists → INSERT a new one
• narrative, pipelineRules (as JSON), brandTokens (as JSON) are updated independently. Absent sub-sections are left alone.

Pass 3: Crew reconciliation This is the most consequential pass. The server loads all existing agents for the universe, builds a map keyed by agent_id, then:

1. For each crew entry in the TOML: if the agent exists → UPDATE (name, model, skill, capabilities, status). If the agent doesn’t exist → INSERT with type: "claude".
2. For each existing agent NOT in the TOML: UPDATE status = "inactive". Agents are never deleted. Their history, dispatch logs, and notes are preserved. They go dormant.

The reconciliation is idempotent. Run the same TOML twice — the second run touches nothing meaningful. Each field is written to its current value. No side effects.

SDK

await sdk.universes.deployConfig(universeId, tomlString);

The page uploads a File object via file.text() and passes the string directly.

---

The GitOps Pattern

The Blueprint enables a GitOps workflow for universe configuration:

# 1. Export current state
curl -H "Cookie: ..." \
  https://sector137.io/api/v1/universes/session/{id}/config.toml \
  -o universe.toml

# 2. Commit current state
git add universe.toml && git commit -m "chore: snapshot universe config"

# 3. Edit locally
vim universe.toml

# 4. Deploy via the HUD (upload file)
# -- or via API --
curl -X POST \
  -H "Cookie: ..." \
  -H "X-CSRF-Token: ..." \
  -H "Content-Type: application/json" \
  -d "{\"toml\": $(cat universe.toml | jq -Rs .)}" \
  https://sector137.io/api/v1/universes/session/{id}/deploy

# 5. Review diff in git history
git diff HEAD~1 universe.toml

The intended state of the universe lives in your repo. The DB reflects what’s deployed. The TOML is the bridge.

---

Relationship to Other Components

Component	Relationship
The Agents	The [[crew]] section IS the agent registry. Deploy → crew reconciliation is the programmatic surface of agent management.
The Pipeline	[storyline.pipeline] sets the WIP limit and escalation threshold — the γ and stress dials that govern pipeline behavior.
The Library	The Library aspires to contain all config as a navigable system map. The Blueprint is config made portable — the Library’s config layer made tangible as a file.
The Physics	wip_limit is the γ dial’s mechanical lever. The Blueprint is how the Creator adjusts γ in bulk without touching the UI.
The Release Gate	Deploy is gated by an active release. Every config change is scoped to a release — it’s a product event, not just a database mutation.

---

Universe Seasons — Config as Pipeline Work

A release is not just a shipping event. It’s a version of the universe.

When you deploy a TOML inside an active release, you’re not changing settings — you’re inaugurating a new season of the universe. The crew that exists in Season 3 is defined by the universe.toml committed during that release. The WIP limit, the escalation threshold, the brand tokens — all of it is what this season ran on.

This is the deeper meaning of the release gate. It’s not bureaucracy. It’s version control for reality. You can’t reshape the universe without creating a record that the reshaping happened, when it happened, and what state the universe was in before.

Season Changes Flow Through the Pipeline

Config changes are not special operations. They are Deltas — and Deltas are issues.

A season change — adding a crew member, adjusting the WIP limit, swapping brand tokens — follows the same path as any piece of work:

1. Create a backlog issue. Title: “Season 4: add Wren to active crew, raise WIP limit to 8.” Category: chore. This is planned, shaped, and scoped to a release like any other Delta.
2. Plan and scope. The issue enters the pipeline. It can be prioritized against other work, assigned a target date, linked to related issues. It’s visible in the backlog. It’s discussable. It has an audit trail before a single setting is changed.
3. Action it. When the issue is worked, the Config page becomes the deploy surface. Edit the universe.toml, upload it, verify the reconciliation. The config change is the work product.
4. Complete the issue. Deploying the TOML = completing the Delta. The issue record is now the accountability artifact — what changed, when, by whose decision, scoped to which release.
5. Publish the release. The release carries both code Deltas and config Deltas. The published release IS the season premiere.

“A config change that bypasses the pipeline is a config change with no record. I run on records. No record, no accountability. No accountability, no pipeline. It’s not complicated.” — Sal

Why This Changes Everything

Before: config deploys are one-off HUD actions. Invisible in the backlog. No planning, no review, no timeline. The DB changes but the pipeline doesn’t know it happened.

After: config deploys are Deltas. They show up in the backlog, the release scope, the activity feed. The season premiere is a pipeline event — same as shipping a feature, fixing a bug, or cutting a dependency. The universe’s history is legible not just through the release record but through the issue record.

The issue record IS the audit trail:

• Who requested the season change
• What shape it took during planning
• Which release it shipped in
• What the universe.toml looked like before and after

The Intended Architecture (IN DESIGN)

The full realization of this concept:

1. Issues as the vehicle: Season change issues flow through the pipeline like any Delta. The config page is the deploy surface; the issue is the accountability record.
2. Issue completion prompt: When a config issue is marked complete, the system can prompt: “Have you deployed the universe.toml for this change?” — connecting the issue to the deploy action.
3. Snapshot on publish: When a release publishes, the current universe.toml is stored alongside the release record — release_configs table or a blueprint column on releases. The Season Premier artifact.
4. The Config Timeline: Each published release has an associated universe.toml. Reconstruct the universe at any point in history. Who was in the crew during v0.9? What was the WIP limit in v0.11?
5. Diff view: Compare universe.toml between releases. Config Deltas as first-class changelog entries alongside code Deltas.

Current State

The release gate is LIVE — cannot deploy without an active release.

The pipeline integration is IN DESIGN — config deploys are currently freestanding HUD actions. They work, they’re gated, but they’re not issues. The backlog doesn’t see them. The release scope doesn’t count them. The audit trail lives only in the DB, not in the pipeline record.

“You’re not deploying a config file. You’re publishing the next season of a universe. The cast, the rules, the production design — all of it is in that TOML. When the season ends, it’s canon.” — Sal

---

Implementation Status

Capability	Status
Export universe config as TOML (GET /universes/session/:id/config.toml)	LIVE
Deploy from TOML file (POST /universes/session/:id/deploy)	LIVE
Config page in HUD (/:universeSlug/config) — TOML viewer + file upload	LIVE
Release gate enforcement on deploy	LIVE
Crew reconciliation (upsert, deactivate-on-missing, never-delete)	LIVE
Storyline reconciliation (narrative, pipeline rules, brand tokens)	LIVE
SDK: sdk.universes.exportConfig() + sdk.universes.deployConfig()	LIVE
Version history / diff viewer in HUD	ASPIRATIONAL — Blueprint is single-point-in-time; history requires Git or a future audit layer
TOML schema migration (version 1.0 → future versions)	IN DESIGN — version field reserved, migration path not yet defined
CLI: sector137 deploy universe.toml	ASPIRATIONAL — planned CLI command; currently HUD-only upload

---

Packages

Package	Description
apps/app/src/lib/universe-toml.ts	serializeUniverseToToml(id) — export; parseUniverseToml(str) — validate and parse. Uses smol-toml + Zod.
apps/app/src/routes/api/v1/universes.ts	GET /session/:id/config.toml (export) and POST /session/:id/deploy (deploy with release gate)
apps/app/client/src/pages/universe-config.tsx	HUD Config page — TOML viewer, download link, file upload with deploy mutation
packages/sdk/src/resources/universes.ts	exportConfig(id) — raw text GET; deployConfig(id, toml) — POST with TOML string