Game-Building Friction

What is actually wrong with using PressRaven to build games — traced to specific lines, with a tiered fix plan.

31 July 2026 · 16 annotations answered · all four tiers built · branch stellar-projections

Built — and three corrections to my own diagnosis

Tiers 0–3 are implemented. App builds clean, RavenKit's tests pass, export-machine.py stellar --verify still exits 0, and nothing is committed in any of the three repos. Jump to what was built.

Three things below turned out to be wrong, and the third matters more than anything in the original diagnosis:

Data defect #4 was a false positive. Those four mini games carry bank_target: 0, which says no corpus bank is expected — they're driven app-side. Nothing to fix.
"De-duplicate the resolved schema" as I wrote it would have deleted data. displayed_positions legitimately has one declaration per mini game; de-duping by key would drop a whole game's fields. It has to happen after applies_when filtering, per entry. Built that way.
I missed the real reason your fields look empty. Six fields carrying live content were declared by no schema block at all — including the entire 87-entry rules bank. Undeclared fields don't render, so that content was invisible in the app while shipping fine to the game. the-rally had no schema block whatsoever.

The short version

Almost nothing you asked for is missing. The round trip into the game app exists and works. The Claude-Code session launcher exists, copies to your clipboard, and opens Terminal. The mini games carry a rich authored layer — mechanic, build status, bank target, divergence notes.

What's wrong is that these are reachable only by paths you'd have to already know about, and two of them are actively mislabelled. The friction is real, but it is surface friction, not absence.

Three things you thought were missing that already exist

Pushing changes into the game app. File → Export to App…, backed by tools/export-machine.py, with a Write / Dry Run / Cancel confirm that lists every file it will overwrite. It was greyed out because you were on Test Game, which declares no machine target. Stellar declares eleven outputs into ~/Developer/Stellar/Data/.
The terminal session. Ways In → Start a Session… writes a session log, copies the packet to your clipboard, and launches Terminal running claude in the game repo.
The game's own description. mini_games[] holds nine games with mechanic, build status, bank target and a long divergence essay each. Nothing renders it.

The single highest-cost defect

Two different buttons are both called "Start a Session." The prominent one in the brief exports a markdown file. The one buried in the Ways In menu opens the terminal. You clicked the prominent one and got a file, exactly as designed. That alone explains annotation #5.

I also verified the corpus and the shipping game are currently in sync — export-machine.py stellar --verify exits 0.

Your sixteen, answered

Tags: exists already built, just hidden · bug code defect · gap genuinely absent · data corpus problem

#	Your note	What's actually happening
1	Why would I choose New Seed?	gap New Seed captures one entry idea into an existing guide — it's the ⌃⌥Space global-capture action, topmost because it's highest-frequency. It's useless as a first action, and the File menu omits the explanatory subtitles the sidebar `+` menu has.
2	Guide appears in sidebar, but we stay on Dashboard	bug `NewGuideSheet.swift:47` discards `createGuide`'s return value and never sets `selection`. The navigation helper already exists at `AppMainView.swift:214`. One-line fix.
3–5	What am I supposed to do? Which button?	bug The prominent Start a Session posts `.pressRavenExportPacket` → save panel → `.md` file. Ways In → Start a Session… posts `.pressRavenStartSession` → clipboard + Terminal. Same name, different actions.
6	Scope is empty — what now?	exists The `(0)` is the entry count. An empty guide has nothing to scope, and the group rows below it are the guide's mini games — Test Game declares none. Your instinct was right.
7	Draft Here brings up… this	gap Draft Here lays out one section per mini game. Test Game has no `mini_games`, so it lays out zero sections and collapses the brief. Root cause: `categories/game/category.json` declares nothing about mini games, so every new Game guide is born an empty husk.
8–10	Games secondary, titles not clickable, no game view	gap Correct on all three. Category headers are inert `Section` strings; `SidebarItem` has three cases and a category isn't even representable as a selection; the detail pane has three arms. No per-game view exists anywhere. Also: no recency state at all — window restoration is deliberately off, so selection resets to Dashboard every launch.
11	No description of the game itself	gap The description is authored and unrendered. `mini_games[]` carries label, mechanic, build status, bank target, priorities, reskin and a divergence essay per game. Its only consumer is the session-launcher's picker.
12	Descriptive text looks like notes + tags	bug Neither. It's every scalar schema field's value with the field name stripped, joined by " · ". Your example is ten fields: family, class, concept, difficulty, time_tier, rotation (not number), phase, rule_tier, verdict, moment.
13	No example of how an item is constructed	gap Correct. The only example generator writes into the exported packet, never the UI — and it ignores `applies_when`, so it mixes fields from all nine mini games into one incoherent example. That's what Claude currently sees.
14	Fields appearing twice	bug Two independent defects. (a) `FieldDef.id` is its `key`, and the resolver appends extension blocks with no de-duplication — Stellar resolves to 75 fields with 14 colliding keys. `ForEach` builds identity before `applies_when` is checked. (b) a boxed `string_map` prints its label twice — the same bug already fixed for `string_list`.
15	Fields empty, but the game WORKS	bug Three compounding causes, none of them a corpus fault — see below.
16	Is commit unsafe? Live render? Integrate back?	exists Not unsafe — see below.

#15 — why correct entries look broken

The resolved schema is the union of all nine mini games. All 13 extension blocks append at top level, and applies_when mostly gates on family alone.
One mini game holds three disjoint entry classes. Within the-thread: 18 item, 87 rule, 48 flavor. Their populated fields barely overlap, so each renders the others' fields as empty.
Some fields are empty on purpose. For verdict: clean, faults is [] and explanation is "" by contract — a clean formation has no faults. The entry you screenshotted says so in its own confidence note.

Compounding it: empty string_map and object_list fields draw nothing at all inside their labelled box, because only prose and string_list have a ghost state. So "not applicable" and "not yet written" look identical — and both look like breakage.

The game works because the exporter projects each class through its own shape, using only that class's fields. The app has no class awareness when rendering.

#16 — commit, live render, and the round trip

Is committing ever unsafe?

In the "could it break the game" sense — no. It runs git add -A in the corpus repo only. It never touches the app repo or the game repo, and nothing is ever written back into the corpus by the exporter.

Real caveats, in order:

It's indiscriminate — no path scoping, and the commit sheet's change list is display-only with no checkboxes. Right now it would sweep up the junk test-game guide you made during this review.
"Commit All Changes" has no confirmation — no sheet, no review.
No branch check, no merge/conflict check, no fetch before push.
Edits autosave on an 800 ms debounce with no quit handler, so the last keystrokes before commit-and-quit can be unwritten.

"Commit Edit" ⌘S is not git. It flushes the in-progress text edit to JSON. Two unrelated things share the word "commit" — worth renaming on its own.

Do changes render live in the game?

No. The game reads ~/Developer/Stellar/Data/*.json, refreshed only by the export. Editing in PressRaven changes the corpus; the game sees nothing until you push. There's no risk of a commit overwriting unrendered work — the flow is strictly one-directional and the repos are separate.

The mechanism you asked for

It already exists. Why it feels absent:

It lives only in the File menu — no toolbar, no shortcut, no presence in the document.
No drift indicator. Nothing tells you the corpus is ahead of the game. --verify exists precisely for this and the app never calls it.
Undocumented — no mention in README.md, docs/, or DIVERGENCES.md.
Drive Corps has a pre-commit hook running --verify. Stellar does not.

Data defects found data

Independent of any UI work — the cheapest wins available.

blow-the-whistle is not declared in mini_games[], yet holds 225 of Stellar's 430 entries (52%). Undeclared families sort last and render with their raw slug as the heading. Meanwhile machine_target.outputs does reference it — so the exporter knows about a mini game the document doesn't. One array entry fixes it.
Duplicate schema declarations for family: "stories" — blocks 6 and 11 declare the same four fields with the same applies_when. Unlike the other duplicates, applies_when can't disambiguate these; they'll double regardless of the view fix.
Duplicate order: 8 on both show-up-or-lose-it and the-rally.
Four mini games marked built with zero entries — the-streak, tag-the-photo, called-shot, show-up-or-lose-it. Either the status is wrong or that content lives somewhere the corpus doesn't know about.

One more, found while verifying: Stellar's section strip currently reads BRIEF · THE · THE · STORIES · THE · THE · BLOW-THE-WHISTLE, because the tab label takes only the first word of the mini-game name. Four identical tabs.

Fix plan

Ordered by value per unit effort. Each tier is independently shippable.

Tier 0 — Corpus data · no code, ~20 min

Declare blow-the-whistle in mini_games[] — un-orphans 52% of the guide
Merge the duplicate stories extension blocks
Fix the duplicate order: 8
Reconcile the four zero-entry "built" mini games
Delete the untracked test-game guide

Tier 1 — Stop the bleeding · small, high-confidence code

Rename the brief's button to Export a Packet…, and put the real Open a Claude Session… beside it
Navigate to the new guide after creating it
De-duplicate the resolved schema, and filter by applies_when before the ForEach
Make string_map honour beat-label placement
Fix the section-strip labels for the game category
Rename "Commit Edit" → "Save Edit"
Add subtitles to the File menu's New Seed / New Guide

Tier 2 — Make the game legible

A game-level view — the brief, then one card per mini game with mechanic, build status, entry count vs bank target, and its divergence note. The data is already authored and merely unrendered. This is the biggest answer to #8–#11.
Label the meta line, or cut it to three or four significant fields
Distinguish "empty" from "not applicable" — gate applies_when on class, and give string_map/object_list a ghost state
Surface a worked example in the empty state

Tier 3 — Close the round trip

Surface drift — run --verify on a timer and badge it: "Stellar — 3 changes not yet in the app"
Promote Export to App… into the document toolbar for guides that declare a machine target
Seed the game category so a new Game guide is draftable on creation
Document the pipeline in README.md — it's described nowhere outside the script's docstring
Optional: give Stellar the pre-commit hook Drive Corps already has

What was built

All four tiers, plus one thing you raised while I was working. Nothing committed anywhere.

Tier 0 — corpus data

blow-the-whistle declared — its 225 entries have a home. Mechanic deliberately left unset, with a note saying why: the three-way call resembles checkpoint-authority but was never confirmed, and guessing would make the gap report show a resolved question that isn't. Your call.
Stale duplicate stories block merged into the current one, keeping the correct string_list shape for frames.
Duplicate order: 8 resolved.
test-game moved to .backups/ — out of the working tree, still recoverable.

Tier 1

Schema resolution filters by applies_when then de-dupes, last wins, warning in debug. Applied at every consumer.
newEntryExample takes a representative entry — it was emitting an object mixing all nine mini games, which is the shape sessions were being told to imitate.
Doubled string_map header fixed; section strip shows real mini-game names.
Open a Claude Session… and Export a Packet… are now separate and named for what they do, consistently everywhere.
Creating a guide navigates to it. "Commit Edit" → Save Edit. File menu gained subtitles.

Tier 2

A mini-game roster above the document: label, mechanic, build status, entries vs bank target, the reskin, the divergence essay, and a "What an item needs" field contract split by entry class. Undeclared families are named with their counts. Clicking a mini game isolates it.
Navigator group headings are buttons — click to isolate, click again to clear.
Meta line renders label value pairs, labels set back from values.
string_map and object_list gained ghost states — empty now reads as its prompt, not a blank box.
New bool field type through the whole interpreter. Required: the rules bank stores legal as a real boolean and there was no type to declare it.
Corpus: the-thread's item fields gated on class; new blocks declaring the rules bank, the-rally, and the whiteboard's missing fields. Every populated field in Stellar is now declared — a rule entry offers 26 fields instead of the whole union.

Tier 3

Drift badge — the document toolbar runs --verify in the background and shows an amber arrow when the corpus is ahead of the game. Click writes.
"Draft Here" now says why it can't act instead of doing nothing silently.
README.md documents the machine target — it appeared nowhere before.
Stellar got a pre-commit hook verifying Data/. Installed in .git/hooks, not via core.hooksPath, because Stellar uses your global hook dispatcher and a repo-level core.hooksPath would shadow every global hook. Tested both ways.

The thing you raised mid-flight

No way to add a mini game. You were right — mini_games[] was hand-edit-only. There's now a New Mini Game sheet with a mechanic picker sourced from the mechanics catalog, reachable from the roster and from Ways In. Same root cause as the empty Test Game: the game category had no authoring surface for its own structure.

Wants your judgment

The mechanic for blow-the-whistle.
The schema prompts I wrote for the rules bank, the rally and the whiteboard are factual and serviceable, but they are not in your editorial voice. Every other prompt in that file is. They want a pass.
Nothing is committed — three repos have uncommitted changes (app, corpus, and Stellar's hook is untracked by nature).

Final review

Pros

Tiers 0 and 1 are nearly all localised single-site changes against defects traced to specific lines. Several are provably correct — the string_list fix already in the codebase is the same fix as the string_map one.
The largest perceived gap — the round trip — needs surfacing, not building. Large win, small effort.
Tier 0 is pure data and can ship today with no build.

Cons and risks

Schema de-duplication has real blast radius. It changes what every guide renders, not just Stellar. Catalogs and the itinerary have their own extensions and need regression checks. "Last declaration wins" is my guess at intent; "first wins" or "error loudly" are defensible and I'd want your call.
The game-level view is a design task, not just implementation. I've described the data it should show, not the composition. Given this app treats composition as a conversation, the honest path is a design packet rather than me inventing a layout.
Adding class gating touches 13 extension blocks — mechanical but broad, and easy to get subtly wrong.

Edge cases this plan does not cover

Whether the four zero-entry "built" mini games mean content lives outside the corpus. If so, --verify passing is less reassuring than it looks.
The AppleScript terminal launch may fail silently on Automation permissions — the entitlements file is empty and failures are swallowed. I have not tested it live.
Not investigated: a 3-second echo-suppression window in the corpus watcher that discards genuine external writes landing inside it. Real, but a separate concern.

Adjustments worth considering

Rather than keeping two competing session entry points, fold both into a single Ways In action band rendered directly in the document.
Make schema de-duplication error loudly in debug builds instead of silently picking a winner — duplicate keys are almost always an authoring mistake, as the stories blocks demonstrate.

Confidence

82 / 100

High confidence in the diagnosis — every claim is traced to a specific line or verified against corpus data, and both rendering bugs are code-certain. Held below 90 by three things: I have not run the app to confirm the fixes behave as predicted; the schema de-duplication touches shared machinery whose full blast radius I have not measured; and Tier 2 is genuinely a design problem where my proposal is a starting point, not an optimal answer.

Plan source · .claude/plans/2026-07-31-game-building-friction.md