# Paperclips Terminal Demo

The Paperclips terminal demo is a small clean-room incremental game inspired by
the paperclip maximizer thought experiment and by Frank Lantz's browser game
`Universal Paperclips`. It runs as an ordinary capOS userspace process launched
from the native shell. The shell grants only `StdIO` and `Timer`; all game
state lives in the child process and disappears when that process exits.

No source code, CSS, images, generated tables, or copied resource files from
the original browser game are checked into this repository. The implementation
uses original Rust code and local CUE content in
`demos/paperclips-content/content/paperclips.cue`. During development, the
original site and a public mirror were inspected for license/provenance only;
neither exposed a permissive license that would allow copying assets into
capOS.

Reference sources:

- Original game site: <https://www.decisionproblem.com/paperclips/>
- Public mirror inspected for license/provenance:
  <https://github.com/jgmize/paperclips>
- Public gameplay/stage summaries:
  <https://universalpaperclips.fandom.com/wiki/Stages>
- Background overview: <https://en.wikipedia.org/wiki/Universal_Paperclips>

## Run It

Use the focused QEMU proof:

```bash
make run-paperclips
```

The scripted proof logs into the shell, launches the child process, drives a
short transcript, and asserts clean child and shell exit:

```text
run "paperclips" with { stdio: client @stdio, timer: @timer }
status
buy marketing
make

make 100
buy autoclipper
status
run 3
projects
exit
```

For default manual use, boot the ordinary playground:

```bash
make run
```

After login:

```text
run "paperclips" with { stdio: client @stdio, timer: @timer }
```

Useful commands inside the demo:

```text
status
projects
make
sell <n>
price <cents>
buy wire <n>
buy autoclipper
buy marketing
buy processor
buy memory
project <id>
run <ticks>
help
exit
```

`make` creates exactly one paperclip. Automation advances once per second while
the process is running; `run <ticks>` is only a fast-forward command. Blank
input repeats the last non-empty command. Later-stage purchase commands such as
`buy drone`, `buy factory`, and `buy probe` appear in `help` only after the
corresponding automation path is unlocked.

## Content Pipeline

Paperclips uses the same generated-content discipline expected for larger demos,
but with a stricter runtime data path:

```text
demos/paperclips-content/content/paperclips.cue
  -> cue export --out json
  -> tools/paperclips-content-gen
  -> serialized Cap'n Proto CueValue bytes in src/generated.rs
  -> paperclips-content deserializes the bytes at startup
```

The CUE file owns the game balance: initial state, purchase costs, tick rates,
autosell rules, trust milestones, project costs, project labels/descriptions,
and project effects. Rust owns mechanics, validation, command parsing, and the
terminal adapter. `make generated-code-check` fails if the checked-in generated
Cap'n Proto bytes drift from the CUE source.

## Unlock Flow

The tech progression is data-driven by the project list:

- retail phase starts with manual single-clip production, sales, wire purchases,
  autoclippers, processors, and memory;
- repeatable marketing investment raises dynamic demand, while early projects
  improve autoclippers, unlock creativity, and unlock Yomi generation;
- HypnoDrones moves the game into autonomous matter conversion;
- drone/factory/swarm projects scale harvesting, production, and compute;
- Von Neumann probes move the game into cosmic replication;
- Universal Paperclips completes the run once reachable matter is exhausted.

## What It Demonstrates

`make run-paperclips` currently shows:

- `capos-shell` launches `paperclips` as a normal child process;
- the child receives only explicit `StdIO` and `Timer` grants;
- the foreground shell services the child's stdio bridge while the game runs,
  so the demo exercises real endpoint IPC between shell and child process;
- the timer capability drives real-time automation without ambient clock access;
- the child maintains local game state without a kernel service or ambient
  authority;
- the pure rules layer in `paperclips-content` is host-testable separately from
  the terminal adapter and reads generated Cap'n Proto content data;
- exiting the game closes stdio, returns to the shell, and lets the focused
  manifest halt through the normal debug-exit path.

This is a capability and process-boundary demo, but not a distributed game-state
service. The shell and Paperclips process communicate over the granted `StdIO`
endpoint, and Paperclips independently calls its granted `Timer` cap. The game
rules themselves still run inside the Paperclips process; no separate economy or
project service participates yet.

## Current Limits

The demo intentionally implements a compact terminal adaptation, not a
browser-accurate port. It has no original artwork, CSS, JavaScript, exact
project list, exact balancing, save file, market UI, tournament model, or
complete original event text. The host tests cover early mechanics and project
locking; the focused QEMU proof covers launch and the first production loop.
Autonomous, cosmic, and completion-stage transcript coverage remains a future
test expansion.

Future rule/content expansion is tracked in
[`docs/backlog/paperclips.md`](../backlog/paperclips.md). New data-heavy
content should migrate through `mkmanifest cue-to-capnp`: author bounded CUE,
convert it to a specified Cap'n Proto root with pinned host tools, validate the
result on the host, and keep runtime CUE parsing out of the demo.