Gamewright

Docs Design

Contents

The October 2026 audit: where Gamewright falls short of best-in-class, and the plan

On 2026-10-09 the owner asked for a critical analysis of everything still missing, then a plan, then the building. Six audits ran that day, each against best-in-class and with evidence:

  • the desktop Studio, from fresh screenshots at 1280×720 and the published 0.2.1 build timed;
  • the Director;
  • the engine, kits and templates;
  • the web: site, onboarding and publishing;
  • the 2026 market;
  • engineering health.

This is what they found, ranked, and the order of the work. It is kept current as items land: each landed item names its commit.

Where Gamewright is already ahead

Keep these, and say them out loud:

  • Changes are proven, not judged.
    • Every proposal is replayed by seed and compared by state hash.
    • Bots play it, and its frames are checked on a monitor and a phone.
    • The restyle gate proves a look-only change did not change play.
    • Roblox's and Unity's playtest agents are model-judged and in beta, and their own forums report false passes.
  • Games are data, not generated code.
    • The Director writes schema-checked JSON, so it never drifts into Godot 3 syntax or paints itself into a 1,400-line file.
    • A shared bundle cannot carry a script, so other people's games are safe to play.
  • Reviewable, stacked change sets with undo, verified before the person sees them.
  • One bundle runs on desktop, web and phone with the same state hash.
  • The art and music it makes are seeded procedural code, so provenance is clean while 52% of developers call generative AI harmful (GDC 2026).
  • Web turns can run on the person's own computer and Claude plan (M12).

Positioning that follows: "the AI proposes, you approve, and every change is proven." Not "prompt to game": the Godot community is openly hostile to vibe coding.

What falls short (ranked within each area)

Trust and safety (fix first)

  1. Fixed: people's own pages ran on the host's origin.
    • /api/file served a game's .html and .svg unsandboxed, on the web Studio's origin through gamewright.diy's rewrite, where they ran with the person's session.
    • Landed in 976314f: everything but raster pictures, sound and video is sandboxed, and the Studio's page refuses other sites' frames.
  2. Releases are not gated on CI.
    • v0.2.1 was tagged on a commit whose CI run had been cancelled, and release.yml runs no tests.
    • 55 of the last 100 CI runs were cancelled by a newer push, so most commits never get a verdict.
  3. Desktop builds are unsigned. Smart App Control blocks them outright. This waits on the owner's Apple Developer account and a Windows signing service.
  4. Host deploys are ungated. They come from whatever tree is checked out, and the Fly volume (the database and every person's games) has no stated backup or restore.
  5. The per-IP sign-in limit is global behind Vercel. One person can lock everyone out.
  6. The host has no per-person memory or CPU limits. A runaway job can take down the one machine.
  7. The licence is inconsistent. LICENSE says "All rights reserved, placeholder" while core/package.json says MIT. The owner decides.

The first ten minutes (conversion)

  1. The welcome promises "say what you want" and has nowhere to say it.
    • The AI path is New game ▸ From nothing ▸ empty ▸ a key card.
    • Best-in-class (Lovable, Bolt, Roblox Build) is a prompt box on the first screen.
  2. The Director needs an API key or a terminal. Running it on your Claude plan is an environment variable with nothing in the UI.
  3. Checkpoint C2 hard-blocks every look (Style, Model, Sound, Screen, Score) until the person has played and pressed "I've played it". A first game cannot look finished in one turn.
  4. Studio turns are capped at $1, below what a first playable costs on Opus ($2.6 to $5.9).
  5. The web Studio is invite-only and the desktop download is unsigned. Rivals are playable in minutes, in a browser or on a phone.

The Studio (desktop and web)

  1. AI changes cannot be undone from the Studio.
    • An approved card says "Applied" with no Undo.
    • Ctrl+Z covers only the person's own form edits this session.
    • The core has changes.undo.
  2. Fixed: Play did not give the game the keys, so the arrow keys changed the Inspector instead (efbc794).
  3. No creating, duplicating, renaming or deleting a document by hand.
  4. The Director has no context.
    • It doesn't see the selected document, the open level or the play state.
    • It shows no pictures.
    • The conversation is gone on reopen, though the core keeps it.
  5. Proposal review is thin.
    • A field row doesn't say which document it changes, and values are JSON cut at 90 characters.
    • No word diff, no "adjust", no link to open the document.
  6. No bringing in your own files. No drag and drop, and no import of images, sounds or models.
  7. The middle shows read-only JSON, while forms are squeezed into the dock. "Change them in JSON" is a dead end, and there is no table across all documents of a kind.
  8. Visual editors cover about 7 of 30 kinds.
    • Missing: Theme, Screen/HUD layout, a dialogue graph, a rules or state-machine editor, a world map.
    • Expressions are bare text.
  9. The Inspector shows engine internals (root seed, template version, Remove on SIM). Colours are hex text, with no picker anywhere.
  10. The play view has no debugging. No speed, frame step, live state or log, and every change restarts from the title.
  11. Chat rough edges.
    • A failed turn has no Retry.
    • The cost line keeps the last turn's figure.
    • The view always jumps to the bottom.
    • Markdown has no code or links.
    • No copy, regenerate or edit-and-resend.
  12. Not native on a Mac.
    • Godot's own file dialogs.
    • No trackpad pan or pinch on the level canvas.
    • Minimum window 1100×680.
  13. No lock in the UI, though locks are a core AI control.
  14. No crash reporting or diagnostics. The update check only tells; it never installs.
  15. Thin Settings. No theme, spending cap, key rebinding or default folder.

The Director

  1. No generated or imported assets. M7 has not started, and no document kind refers to a media file. Everything is procedural Tier 1.
  2. KitRequests are a dead end. All five samples' requests are drafts; local kits (ADR-0003) are not built.
  3. Memory.
    • History grows with no compaction.
    • too_long starts over with nothing carried across.
    • The designed NOTES.md was never built.
    • The 5-minute prompt cache lapses on every play break.
  4. Blind to decisions. Reject takes no reason, and approvals, rejections and hand edits are never reported back to the Director.
  5. No plan for ambitious asks. There is no Plan document or plan mode, and no triage of "can, can approximate, can't".
  6. Every change needs a click. There is no person-set auto-approve policy.
  7. Proposals verify inside the propose call, one tool at a time, with no progress. Turns run from 12 s to 40 min.
  8. No motion evidence.
    • Previews are stills: no proof clips, no drive tool, no record of the person's own play.
    • L4 vision is out of reach.
  9. Text-only input. No reference images or sketches.
  10. Tool gaps. No delete or rename tool, no reading other games, no thinking or effort settings.

The games (engine, kits, templates)

The samples are micro-games of 3 to 8 minutes. The vocabulary is narrow.

  1. A player can't save, continue, pause or change a setting. The engine saves; nothing reaches it.
  2. Five of nine samples make no sound. The three 2D templates leave out kit.audio.
  3. No VFX at all. No particles, screen shake, hit flash or tweens.
  4. One world per game.
    • No doors, interiors or dungeons.
    • No Timeline: no cutscenes, boss phases or delays.
  5. No pointer input. That rules out point-and-click, cards, strategy, tower defense and mouse aim.
  6. One attack per body; no Ability or Effect kinds. Platformer enemies can't be beaten; no bosses or status effects.
  7. No top-down 2D tile world, and no autotiles. That is the RPG Maker and Zelda look.
  8. No localization. One 104-glyph pixel font, ASCII only.
  9. No in-game accessibility. No rebinding, volume, text size, colour-blind palettes or captions.
  10. Quests and shops exist only as dialogue tricks.
  11. No perspective 3D, no physics bodies, no multiplayer, though local co-op is cheap here because input already comes in frames.
  12. No mobile export, Steam, achievements or leaderboards.

The web: site, funnel and trust

  1. No way in.
    • The web Studio is invite-only: "Ask whoever runs this host to invite you".
    • No waitlist, no Google or GitHub sign-in. Every interested visitor is lost.
    • A phone visitor's only call to action is a desktop download.
  2. No free AI.
    • The Director needs the person's own Anthropic key on both Studios.
    • The key card has no "get a key" link.
    • The host already has per-account caps and a ceiling for a starter allowance.
  3. Stale copy on the main path.
    • The install guide still says downloads are coming.
    • "Your first game" tells people to copy from a private checkout.
    • Download, support, features and the homepage still say "first release", "cannot start a new one yet" and "web Studio later".
    • No check ties prose to the released version.
  4. No support channel (Report a problem leads back to "comes with the first release"), no privacy, terms, licence or pricing pages (all 404), though the host keeps emails, games and sealed keys.
  5. The proof doesn't show the magic.
    • No video anywhere.
    • The hero is a scripted change to a description, which shows nothing.
    • The homepage is 15 screens of engineering (L0–L5, seeds, planted bugs), and never says who it's for or why it beats the alternatives.
  6. No analytics. No funnel events, so nothing above can be measured.
  7. Share cards and SEO slips. /support and /features share the home card, there are no canonicals, and the play links have bare titles.
  8. Docs serve the builders, not the makers. 38 of 46 pages are design docs.

Already strong: the download page (OS detection, checksums, honest warnings), the Director run pages, accessibility, and page weight (about 190 KB compressed).

Distribution and community

  1. No audience yet. The gallery has a handful of games: no accounts for players, publishing from the Studio, share links, remix, ratings or creator profiles.
  2. No publish step from the Studio. Export is a zip.
  3. No pricing or plans story. Rivals compete on "no credit meter on your first game".

Engineering

  1. CI takes 37 minutes, on its critical path:
    • the planted-bug job runs one pack at a time;
    • heavy.sh adds about 20 s per frame job on CI;
    • shards are unbalanced.
  2. CI checks less than local:
    • the boundary lint runs locally but not in CI;
    • the web harness and the site's next build never run in CI;
    • the root-only isolation tests never run.
  3. 147 files copied from Reelwright are drifting, with no tooling to see upstream fixes.
  4. The 600-line rule holds for GDScript, not TypeScript. 30 TS files are over it.
  5. Big downloads. The web player's wasm is 39.5 MB, and nothing tracks load time.
  6. Contributor docs are stale. The verify skill's baselines, ARCHITECTURE §11–13 (Better Auth, Neon) and the ROADMAP's CI line.

The plan

The order:

  1. Safety and broken basics first.
  2. Then the quick wins a person feels in the first session.
  3. Then the first ten minutes.
  4. Then the Director's depth.
  5. Then breadth.
  6. Then distribution, which also needs the owner's decisions.

Each wave's items are small, proven units that land on main as they go.

Wave 0: safety and gates (now)

  • Sandbox people's files on the host; no framing of the Studio (976314f).
  • Gate releases on CI: the release workflow runs the whole CI on the tagged commit before it packages (5eb2233). Main's runs still replace each other on a newer push: the repository is private, so every CI minute is billed.
  • CI covers what local covers: the boundary lint, next build (5eb2233).
  • CI time (5eb2233): the planted corpus in three jobs of about 12 minutes; heavy.sh takes one reading on CI. Next: balance the four core shards by duration.
  • Host: deploy only a clean tree at a pushed commit (tools/host/deploy.sh refuses others; GAMEWRIGHT_DEPLOY_ANY_TREE=1 for an emergency).
  • Volume snapshots confirmed (daily, kept 5 days), with a restore drill written down (docs/design/web-studio.md, "Backups and the restore drill"). Running the drill touches the live app: with the owner.
  • Owner decisions:
    • the licence;
    • signing accounts;
    • a support address (email or Discord) for Report a problem;
    • privacy and terms pages before the door opens;
    • a starter Director allowance funded by the host's key.

Wave 1: what a person feels in the first session

  • Every stale page and guide rewritten for the released app (9ec8248, then the CLI page, support and features). A check fails when prose says "first release", "not packaged" or "after the desktop release" once a version is out (tools/site/prose.ts, in CI's lint job).

  • Share cards and canonicals fixed per page (227d346). A check reads every built page for its own title, canonical and card (tools/site/pages.ts, in CI's lint job). Still open: a game's full page on the play origin is titled "Gamewright" (its shell is the engine's).

  • Play gives the game the keys (efbc794).

  • Undo, then Redo, on an approved change's card (a91f4d3). Approvals join Ctrl+Z's history: it takes back the last proposal approved as it does an edit.

  • The conversation comes back when a game reopens (35fc45c).

  • Proposal rows name their document, with Open, and colours as swatches (c6bf814).

  • A colour picker for every colour field.

  • Chat: Try again on a failed turn, the cost line per turn, scroll that follows only from the bottom, Copy on a reply (8e57c01).

  • The system's own file dialogs (d1a0a3b).

  • Sound in the 2D templates and their samples (0fd67b5): a Style maps any event to a sound, scene beds crossfade, and the five 2D samples each have their own sounds and score.

  • Pause, continue and options in every game: a pause menu, saves a player can reach, and volume.

Wave 2: the first ten minutes

  • A prompt on the welcome ("Describe a game"). It makes the game and starts the Director's first turn.
  • The Director on your Claude plan, chosen in Settings and in the key card (M12 phase 2 in the UI).
  • "Dress it first": the person may waive C2 for looks. The restyle gate keeps play safe.
  • A per-turn budget the person sets, shown before the turn; the step limit follows the budget.
  • Reject with a reason. Each turn starts with "since your last turn": approvals, rejections with their reasons, undos and the person's own edits. The history tool reads older changes back, with what the person said, or one document's.
  • The site leads with a prompt box and a 45-second unscripted video. Who it's for and why comes first; L0–L5 moves lower, as "why your game doesn't break".
  • A waitlist that invites in batches, then self-serve sign-up. "Get a key" on the key card.
  • Cookieless funnel analytics:
    • download click and code requested;
    • not invited;
    • first Director turn, first play, first export.

Wave 3: the Director's depth

  • Memory: past about 60k tokens a conversation's older turns become one note (decided, open, the person), its last two turns kept whole (compact.ts).
  • More memory: .gamewright/director/memory.md the Director keeps with remember and the person edits from the Director panel's book; the 1-hour prompt cache; each step saved.
  • Context: the document in the Inspector, the open level and whether the game plays go with each message ("As they ask, …").
  • Images in the chat: a step's pictures (a preview's frames) show under it, click to open. A preview of a proposal (changeId) puts its frames on that proposal's card too.
  • A Plan document for big asks: the brief's plan, milestones with acceptance Playtests, approved once, then "Continue the plan"; only complete_milestone marks one done, after its Playtests pass. A real Sonnet turn on the owner's plan planned "five nights" in six milestones and asked five design questions first.
  • An auto-approve policy the person sets: Settings' "Its changes apply", When I approve them or When every check passes (a proposal passing during a turn applies at once, with Undo; the Director is told). "Green looks" alone waits for a look-only ladder.
  • assess_ask triage: the ask's words against the kits' vocabulary, the nearest templates, what each kit does and the gaps filed; the playbook has the Director say what it can make, approximate or not yet, and the nearest game.
  • Proof clips from L2 replays on cards: "Watch it play" draws the run a proposal's checks recorded (changes.clip, the player's --clip).
  • A drive tool: tour lines on the game or a proposal; the tour's end or where it stopped, the events by count, and with shots, the frames.
  • The person's own plays recorded and summarized: each desktop play keeps a trace in .gamewright/plays/, and the Director's next turn opens with a line for each new one.
  • The Director's tool listing: 28 tools, 66.7 KB as the model gets it (schemas most of it: file_kit_request 5.9 KB, try 4.8 KB, propose_slice 4.5 KB). Cached an hour, a turn reads it at a tenth of the price (about 1.6K tokens' worth); watch it, and defer rare tools behind a search if it grows.

Wave 4: what games can be

  • Import your own media (880887e): an Asset kind holds files pinned by SHA-256 with a provenance ledger (who made it, licence, AI or not); drop on the Studio, File ▸ Import… or gamewright import; Sprites cut imported sheets, Sounds play imported files. Later: a picture as a backdrop or 3D texture, glTF, music past 60 s, the disclosure forms from the ledger.
  • Tier 2 generation (M7) through the same Asset path, with a provenance ledger that fills in the Steam and itch AI disclosures. A "procedural only" mode stays.
  • Juice (2178a98): kit.vfx answers events from the Style's vfx.effects with particles, flashes, squashes and shakes, worked out from tick and seed so shots and replays match; every template but the visual novel, each sample and starter has juice; Options offer shake and flashes.
  • A top-down 2D tile world with autotiles (aabcba4): a Style whose profile is flat_2d draws its world flat from above (a topdown2d CameraRig): later grounds spill over earlier ones in wobbly bands, water laps at the shore with foam, cliffs show faces, and props and bodies are sprites baked from their Models (side, front, back; idle and walk); clicks pick the sprite. Larkmead is the adventure template drawn flat (docs/design/topdown-2d.md).
  • A Timeline kind for cutscenes and boss phases (7bf2c6d): steps in order over ticks (wait, until, do, say, move, camera), a run per self, cutscenes that take control and skip doing what is left, saves that go on mid-step; Thornwick opens on one (docs/design/timelines.md).
  • Scenes joined by doors (fa24ade): a GameManifest lists places, each a world grown from its own seed on first entry; a door on a usable or the travel action takes the player there, the scene left is put aside and comes back as it was, saves keep every scene's worked props; Thornwick's third thornback nests in Thorn Hollow, down a burrow (docs/design/scenes.md).
  • Pointer input (7c08dc7): the input frame carries a snapped point, a click and a picked target, so replays repeat it; mouse aim (Saltwell), click to walk and use (Thornwick), the menu and Screens by mouse, tour verbs point/aim/click. Since: top-down 2D worlds pick sprites (aabcba4), a grid puzzle's cells are clicked or tapped to walk there (e154ce0). Later: bots that point, drag, a platformer's world.
  • Abilities and Effects on every mover; beatable platformer enemies (e122b00): an Effect is a status every moving and fighting kit reads in one place (slow, root, stun, shield, rage, ward, poison); an Ability is a power with a cooldown and a cost, pressed or used on its own (dash, blast, fire, strike); a beatable foe is stomped or struck. Burrow Run's crawlers can be stomped; Saltwell's spitters slime the keeper (docs/design/abilities-effects.md).
  • Localization (040850a): a Locale document carries a game in another language, keyed by document id and path, with phrases for the texts a game works out as it plays; it is overlaid at boot, so every language ends a tour on the same state hash and switching mid-game keeps the state. The face composes the Latin alphabets' accented letters; Options pick the language (the device's first); gamewright strings lists what to translate. Larkmead plays in French (docs/design/localization.md).
  • The game's own accessibility options (9ff853c): a Sound's caption comes up when Captions are on, with an arrow toward where it came from ("← [beast snorts]"); a colour filter daltonizes the frame for protanopia, deuteranopia or tritanopia; the Controls page changes any key a person presses in play, a taken key swapping over. A tool run given --options is drawn as that person sees it, on the same state hash (docs/design/accessibility.md).
  • Checked as those people see it: a Playtest names a person's options and colour-blind eyes, and L3 draws its frames that way (e1d4a89); every L3 frame measures each subject through protan, deutan and tritan eyes and signals one that only hue set apart; Game ▸ See it as in the Studio (05e03da). Found at once: a caption over the HUD message at 200% (fixed), and HUD lines cut on a phone held upright at 200%: kit.ui text now reflows as it grows (5d16e3c) and a talk's box grows to hold its words (dfda46c), 15 red frames down to 8 on Thornwick there; a list takes the room it has and scrolls, so the menu fits a phone at 200% (19a2e8b); a HUD's quieter lines yield to a message while there's no room for both, 8 down to 1 (90a9c12); a choice's answers join its question in its box, 1 down to 0 (25bfdae1). Fog Signal there: a list's long row wraps, 5 down to 3. Next: its last 3 (accessibility.md, "Not yet").
  • More of the guidelines' list: a controller's buttons, triggers and sticks and the mouse's buttons rebound on the Controls page (6cc32fb); music captioned when it tells the player something, "♪ tense music ♪" (32d7942); captions' size and background chosen, words outlined on less than a solid strip (9611619).

Wave 5: distribution and community

  • Publish from the Studio to the gallery, with a share link and its proof (replays, the verified badge).
  • Remix a published game (safe: bundles carry no scripts).
  • itch.io upload; store-ready packages. Started: gamewright store writes the store page and its AI disclosure from the game's own records (9c3a053); every export puts them beside the zip, each desktop zip carries an .itch.toml (5529534); store --shots draws the cover and screenshots from the game's own tours (66a106c). Next: the pictures from the Studio's Export; the upload waits on the owner's account.
  • Owner decisions:
    • open sign-up for the web Studio (cost and abuse);
    • pricing: bring your own plan free, pay for hosting and runs.

Later

  • Local co-op on the frame input.
  • Lockstep online play on the deterministic sim.
  • Local kits from KitRequests (ADR-0003).
  • Parallel Directors.
  • Analytics on published games.

From docs/design/audit-2026-10.md in the Gamewright repository.