# Plan: Paperclips Showcase

## Overview

Expand the clean-room Paperclips client/server showcase. Authoritative
Paperclips server owns generated content, game state, regular timer cadence,
proof controls, unlock checks, command discovery, structured plain-status
snapshots, project lists, and -- in this plan -- broader structured
state/events, command facets behind server-issued capabilities, capability
transfer/revocation ergonomics, and the future web-shell client path.
Terminal and web clients should consume server-issued capabilities instead of
reimplementing game rules.

Long-form decomposition: `docs/backlog/paperclips.md`. Clean-room mechanics
baseline: `docs/research/paperclips-clean-room-functional-spec.md`. Demo
description: `docs/demos/paperclips.md`. This plan must not copy
source-game implementation identifiers, text, assets, generated tables,
exact balance, CSS, or code.

## Conflict Surface

Owned by this plan:

- `demos/paperclips/` (the binary crate hosting both the authoritative
  server roles and the terminal client) and any new `demos/paperclips-*`
  crates introduced by this plan
- `demos/paperclips-content/` (content crate, including
  `demos/paperclips-content/content/paperclips.cue`)
- `tools/paperclips-content-gen/` only when the generated-content shape
  changes
- `system-paperclips.cue` and the matching `make run-paperclips` target
  (Makefile recipe lines for the Paperclips demo only)
- `schema/paperclips-content.capnp` and any new Paperclips-specific
  schema (demo-specific, not part of the shared serial surface)
- Paperclips-shared types in `schema/capos.capnp` (`PaperclipsGame`,
  `PaperclipsStatusSnapshot`, `PaperclipsCommandSpec`,
  `PaperclipsCommandList`, related project/event types) when the iteration
  extends them. These edits use the shared serial surface -- see
  `docs/plans/README.md` Concurrency Notes; only one plan at a time may
  change `schema/capos.capnp`, and `make generated-code-check` must pass
  before the next plan picks it up.
- `docs/demos/paperclips.md`, `docs/backlog/paperclips.md`

Do not touch from this plan:

- Kernel-side cap tables outside Paperclips schema additions
- `tools/remote-session-client/` (owned by remote-session plan)
- `demos/adventure-*` (owned by Aurelian plan)
- Repo-root `system-*.cue` migration-to-defaults work (owned by
  system-config slice 3 plan), except direct edits inside
  `system-paperclips.cue` for new Paperclips services

## Validation Commands

- `make fmt-check`
- `make generated-code-check`
- `cargo build --features qemu`
- `cargo test-config`
- `cargo test-lib`
- `cargo build-demos-capos`
- `make run-paperclips`

## Success Criteria

A reviewed showcase iteration ships when the focused QEMU proof keeps
exercising one-at-a-time manual production, the autonomous and cosmic phase
transitions, structured `help`/`projects`/`status`/`status --json`, and a new
slice from the task list below. `WORKPLAN.md`'s Paperclips ad-hoc note stays
in sync; record commit hashes there.

### Task 1: Structured state and event surface beyond status snapshot

- [ ] Extend the server-side status snapshot with structured event/log
      entries for production cadence, project completion, autonomous-phase
      crossings, and proof transitions. Keep `status --json` proof-only and
      server-gated; render plain-text events for normal terminal sessions.
- [ ] Cover the new fields with `paperclips-content-test` host tests and at
      least one focused QEMU assertion in `make run-paperclips`.
- [ ] Update `docs/demos/paperclips.md` and the proposal (if any) to
      describe the structured event channel.

### Task 2: Command facets behind server-issued capabilities

- [ ] Move the unlocked-command facets that today live in the terminal
      client behind server-issued capabilities. Each facet (production,
      market, projects, autonomous, cosmic, completion) should be a typed
      cap the server hands the client only after the corresponding unlock.
- [ ] Refactor the terminal client so it discovers facets through the cap
      surface rather than text. Keep raw text command execution for
      backwards compatibility, but route it through the facet caps.
- [ ] Add a focused proof that revoking a facet stops further command use
      from that client without crashing the server or the client.

### Task 3: Capability transfer and revocation ergonomics

- [ ] Add a proof slice that demonstrates server-driven facet revocation
      (e.g. when the cosmic phase ends or a proof control closes) without
      reaching for kernel-level revoke.
- [ ] Show the terminal client surfacing a clean error when a facet is
      revoked mid-command, and the server preserving game state across the
      revocation.
- [ ] Document the resulting transfer/revocation contract in
      `docs/demos/paperclips.md` so later web-shell clients implement the
      same shape.

### Task 4: Web-shell client preflight slice

- [ ] Sketch a remote-session DTO surface for Paperclips (status snapshot,
      project list, command list, single-command execution) that the
      future remote/web client will call. Do not yet wire the real
      remote-session client; this is a contract slice.
- [ ] Add a host-side test that drives the server through the DTO surface
      and matches `paperclips-client` rendering for at least the manual,
      autonomous, and cosmic phases.
- [ ] Note the wiring follow-up in `docs/backlog/paperclips.md` and link
      it from `docs/backlog/remote-session-capset-client.md` so the
      remote-session plan picks it up cleanly.

### Task 5: Update doc and changelog records

- [ ] Update `docs/demos/paperclips.md` with the new structured event,
      facet, and DTO contract.
- [ ] Add a `docs/changelog.md` entry referencing the commit that lands
      the showcase iteration.
- [ ] Refresh `WORKPLAN.md`'s Paperclips ad-hoc bullet to reflect what is
      now landed and what is still planned.