Paperclips Terminal Demo Backlog

This backlog tracks future expansion of the clean-room Paperclips terminal demo described in docs/demos/paperclips.md. It is not the current selected milestone.

Current Baseline

Implemented:

• Clean-room terminal implementation inspired by the public Paperclips premise without copying original game code or assets.
• make run-paperclips boots a focused manifest, launches the terminal demo through the shell, grants explicit StdIO and Timer caps, drives the first production loop, and exits cleanly.
• Game state is local to the paperclips process and disappears when the process exits.
• The pure rules layer lives in demos/paperclips-content and is host-testable separately from the terminal adapter.
• Paperclips content is authored in CUE, exported through the pinned CUE tool, serialized as Cap’n Proto CueValue bytes, checked in as generated Rust data, then deserialized by paperclips-content at runtime.
• Core game balance and content live in CUE: initial state, purchases, projects, unlock effects, production rates, tick duration, currency formatting, price limits, trust thresholds, and phase transition values.
• Manual make produces one clip only; counted manual make requests are rejected.
• Automation advances from the Timer capability in real time, while run <ticks> remains an explicit fast-forward command.

Known limits:

• The current generated content format embeds generic CueValue Cap’n Proto bytes rather than a bounded Paperclips-specific Cap’n Proto schema.
• Autonomous, cosmic, and completion-stage transcript coverage remains future work.
• There is no save/load path; process exit discards game state.

Remaining Gameplay Work

• Tune progression once the current terminal loop is stable enough for a full playthrough. The CUE file should remain the only place for balance values.
• Add end-to-end smoke coverage for at least one project unlock chain after repeatable marketing investment, including a phase transition out of the business phase.
• Add save/load or restart-resume behavior after capOS has a durable user storage path appropriate for spawned demos.
• Add a compact status --json or equivalent machine-readable command only if future smoke tests need stronger assertions than the human transcript.

Schema-Aware Content Migration

Future Paperclips content expansion should migrate from the generic generated CueValue payload to the shared host conversion flow instead of growing a second content compiler:

1. Define a bounded Cap’n Proto root struct for data-only rules, such as project definitions, stage thresholds, cost curves, and deterministic transcript fixtures. Do not put live capOS capabilities or interface objects in that schema.

2. Keep authoring data in CUE under demos/paperclips-content/content/, with all ids, labels, text, costs, and list lengths explicitly bounded by the Rust validator and, where practical, by CUE constraints.

3. Convert with pinned tools through mkmanifest cue-to-capnp:

   make cue-ensure capnp-ensure
   CAPOS_CUE="$(make -s cue-path)" \
   CAPOS_CAPNP="$(make -s capnp-path)" \
   cargo run --manifest-path tools/mkmanifest/Cargo.toml --target "$(rustc -vV | awk '/^host:/ {print $2}')" -- \
       cue-to-capnp --package paperclips_content --import-path schema \
       demos/paperclips-content/content/rules.cue schema/paperclips-content.capnp \
       PaperclipsContent target/generated-paperclips-content.bin
   

4. Decode or validate the produced Cap’n Proto message on the host, then generate deterministic Rust data or embed a reviewed no-std-friendly binary representation. Do not add runtime CUE parsing to the demo.

5. Wire the conversion and freshness check into make generated-code-check before checking in generated content.

6. Keep the focused QEMU transcript representative: one launch, one production loop, one automation purchase or project unlock, and clean exit. Cover larger rule validation with host tests.

Capability And IPC Follow-Ups

• Keep the demo as a shell-spawned process using explicit StdIO and Timer grants until the native interactive command surface proposal is implemented.
• Do not turn Paperclips game state into a resident shared service unless a later design needs cross-process observers or multiplayer coordination. The current demo is an IPC/capability exercise for process launch, terminal I/O, and timer delivery, not a distributed game-state service.