PaperClipAI/packages/paperclip-runner/docs/index.md

Native Runner Tutorials

The tutorials are cumulative and are always run from the repository root. Each tutorial starts with an explanation of what the phase is and what the phase proves.

Implemented phases

• Phase 0: standalone tracer — install the workspace, validate its Rust/TypeScript boundary and knowledge bundle, then run the deterministic Rust mock-core path and cross-language parity check.
• Phase 1: static PRP replay — validate the shared schema/fixture corpus, reduce a fixture in the CLI, and inspect the same final snapshot in the standalone browser page.
• Phase 2: local runner and fake harness — run a supervised Rust process, exercise scripted live scenarios, resolve requests, interrupt a turn, and confirm live/replay parity.
• Phase 3: break recovery on purpose — lose an ACK, drop the socket, restart the runner side, replay durable events, and inspect recovery diagnostics.
• Phase 4: run the skillless Codex driver — run a safe real-model task, inspect the exact context boundary, steer or interrupt it, and confirm one replay-safe result.
• Phase 4b: run the protocol demo server — exercise the server-only Codex boundary, canonical replay, typed controls, and reconnect with curl.
• Phase 4b: run the live Codex protocol console — chat with a live session in the browser, steer it, stop it three ways, answer its requests, change its goal, break its connection, and replay the record.
• Phase 5: run the SDK console and mini consumer — exercise the versioned public browser/React surface in two independent consumers against fake and real drivers.
• Phase 6: run the thin Paperclip adapter — prove mock/real conformance, run one feature-flagged local task, inspect replay/finalization, disable the kill switch, and verify legacy fallback.
• Cumulative end-to-end tutorial — the shortest complete workflow available at the current phase.

Reference

• Architecture and dependency boundary
• PRP compatibility and versioning policy
• Phase 2 local protocol and supervision
• Phase 3 durable transport and recovery
• Phase 4 skillless Codex driver
• Phase 4b protocol and demo server
• Phase 4b live console
• Phase 5 browser SDK and reference console
• Phase 6 thin Paperclip adapter
• Engineering journal guide
• Dated shadcn/ui and AI Elements compatibility note
• Phase 4b live-console interaction map
• Phase 4b component decision record (shadcn/ui, AI Elements)
• Phase 5 component and SDK surface plan
• Phase 5 SDK extraction decision record
• Phase 6 thin Paperclip adapter boundary
• Package README

Phase 6 is implemented as a default-off server integration at the public package boundary. Production Paperclip UI integration remains deferred.