# Paperclips Terminal Demo Backlog

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

## Current Baseline

Implemented:
- [x] Clean-room terminal implementation inspired by the public Paperclips
      premise without copying original game code or assets.
- [x] `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.
- [x] Game state is local to the `paperclips` process and disappears when the
      process exits.
- [x] The pure rules layer lives in `demos/paperclips-content` and is
      host-testable separately from the terminal adapter.
- [x] 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.
- [x] 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.
- [x] Manual `make` produces one clip only; counted manual make requests are
      rejected.
- [x] 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`:

   ```bash
   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.