Memoir NovelToGame experiment

This package supplies the shared runtime, journey/asset helpers and standalone
NovelToGame evaluation runner. The active memoir-story-game uses these helpers
through apps/api/novel_game.py after owner scene confirmation. Higgsfield remains
an explicitly configured backup.

Fixed game format

Build one continuous chronological path. The author can walk forward or
backward and reread any nearby memory, including after completion. Keep the Read
button available after a visit; progress counts each unique memory once. Arrange
the supplied timeline along that same path. Later visits to
the same place occur further right. Keep uncertain dates and ordering explicit.
Illustrations pan within a place and blend smoothly into the next while the
player, ground baseline and camera remain continuous. Keep keyboard/touch,
untimed readable passages, visible focus, reduced motion, progress, ending,
restart and the complete unchanged source view.

Treat this format as a product requirement throughout analysis, concept, design,
art, build and QA. Read the journey policy before concept or
design. The adapter, structured format_contract and host-owned
runtime/ enforce this format across future generations. Models supply the route,
art plan and styling; the host owns movement, scene blending, HTML, JavaScript and
replay. Use continuous global coordinates in either direction, without hub trips
or travel portals. Chronology controls the layout, not the user's reading order.

Stage workflow

Run make deps-install when the dependency is missing. Read the pinned
upstream entrypoint and its
pipeline contract. Keep its stage skills separate and unmodified. Use GPT-6.1 Sol
with max effort for this experiment. Source analysis may be reused only when its
receipt and complete input match; the fictional age-eight source analysis is
preserved under examples/age-eight-patch/.

Use stages.py one persisted stage at a time: analyze, concept, design,
whitebox, art, then production. Design returns GAME_DESIGN.md and
JOURNEY_PLAN.json; journey.py validates complete chapter coverage, timeline
order, contiguous scenery and increasing memory positions. It binds avatars to
source life stages and optional owner-approved professions. Whitebox is already
playable using the fixed runtime and its generated ordinary-input replay, so
separate model calls for movement logic and replay are unnecessary. After art,
prepare the scene assets below. Production supplies styling and BUILD_BRIEF.
Use production_style only for a focused CSS repair. A matching checkpoint reuses
the saved result. Changing the request invalidates reuse. Keep failed attempts;
split a failed large build by output file before retrying. Report observed usage;
the previous pool exceeded requested token ceilings, so they are not hard bounds.

The runner prepares a request without credentials or network by default:

python3 experiments/novel-to-game/stages.py concept --output var/novel-to-game-rpg-scroller

Add --execute --env-file /path/to/owner.env only for an authorised live run.
Continue later stages in the same output directory after their required handoffs
exist. The default input is the fictional age-eight benchmark. For another memoir,
start analyze --source /approved/composer-timeline.json --brief /approved/PRODUCT_BRIEF.md
in a fresh output directory. The JSON contains input.chapters, linked
input.timeline, locale, and optional title/fictional metadata. The runner saves
the input and brief for later stages and requires fresh analysis; it never seeds
another memoir with the benchmark's facts. The standalone CLI remains separate from authenticated generation; the application
uses the fenced coordinator in apps/api/novel_game.py.

After whitebox play, save actual feedback as whitebox-feedback.json before art.
Read the asset policy at this point. The runner supplies
illustrated-lifetime-v1: childhood, teenage, young adult, midlife and older
avatars, professional/workwear variants, CSS markers and original opt-in music.
Reuse these files; generate only scene backgrounds. A profession/outfit comes
only from the optional owner-approved character profile, never from a model's
guess or a parent's job. The age-eight source stays a child throughout. These are
imagined generic avatars; choose another approved family when appropriate.
Upstream NovelToGame remains independently updatable.

The art stage saves ART_DIRECTION.md and SCENE_ART_PLAN.json. Restore cached
illustrations before making image calls:

python3 experiments/novel-to-game/game_assets.py prepare --output <workspace>

For each missing scene illustration, apply the image-generation skill with that
entry's complete prompt. Prefer one atlas for compatible locations. Inspect the
result, then register the original PNG:

python3 experiments/novel-to-game/game_assets.py record --output <workspace> --id places --image /absolute/generated.png

The cache uses the exact scene prompt, style and grid; a changed requirement gets
a new key. It lives under ignored var/novel-to-game-scene-cache/. The host stages
verified stock bytes and cached scenes into the app and passes paths, hashes and
actual cell dimensions to production. Production execution waits for ready scene
assets; previews remain offline. Shared characters, UI, portraits, music and sound
are reused, so only missing scene illustrations incur image-generation calls.

For a runnable candidate, run verify.py --output <workspace> --stage production
and repeat with --phone. The replay must demonstrate player movement, camera
movement in both directions, continuous travel between settings, rereading, progress, ending
and restart. Verify bounded player/camera positions, reversible smooth overlap in normal
motion and stable reduced-motion scenery. Host runtime files must match their
reviewed bytes; model outputs cannot replace them.
Run journey_checks.py --output <workspace> for independent normal-speed blend,
backtracking/rereading, source, reader pause, avatar-family and opt-in audio probes.
Add independent probes for passage fidelity, revisit/full-text credit, movement
bounds, locked areas, focus, 320px layout and offline assets. extra_checks.py
targets the archived first RPG's selectors and state; adapt these probes to the
actual build before using them on another game. Also exercise stock avatar
idle/walk/facing, reduced motion, scene atlas cells and opt-in/mute audio as
specified in the asset policy.
Record all six upstream QA checks from one complete clean run. Physical-device
and subjective-experience claims require their own evidence.

Integration boundary and provenance

deps/novel-to-game/ is an unmodified MIT-licensed Git submodule. Git records the
reviewed revision; make deps-install restores it and make deps-update checks
out upstream's latest main. Review and commit the changed submodule pin before
sharing an upgrade. The runner records the installed commit in every request and
receipt, and rejects local upstream edits. Memoir requirements belong in the adapter.

Repository agents discover the seven upstream skills and this Memoir entrypoint
through .agents/skills/ links. Codex lists the upstream plugin's skills as
novel-to-game:<skill>. Dependency updates preserve the adapter and the
historical examples, whose recorded upstream revisions describe their original runs.

examples/age-eight-patch/ preserves the earlier repair-puzzle experiment,
including its original instructions, code, handoffs and receipts. It is a
historical comparison, and its PASS receipts do not establish RPG QA. Full raw
requests, responses and screenshots remain private under ignored var/ in this
worktree. snapshot.json fingerprints the tracked historical files.

Memoir adapter, journey, asset and stage prompts are managed under
skills/memoir-story-game/prompts/novel-to-game. These local links resolve to
that single source; live calls verify published receipts. Upstream instructions
remain outside the managed registry and are fingerprinted separately. Publishing
follows the repository's merged-main prompt workflow.

The live-generated age-eight RPG
and its run receipt preserve the fresh
Sol max example, observed browser results and separately recorded host repairs.
Serve its build/app/ directory or open its HTML directly for offline play.