prompt_objects 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dd3c14942ef80d1979ded542802ad9d1a24b32cd479aa4ba0a08bb0bf2e349d
-  data.tar.gz: 3642d5424aa827754dfefde82a9e9e5c770935ebf08e36cfc429d8f86e5e8502
+  metadata.gz: 1127bb4c18c49c460ceb34d5ee7f86b81b5e00a3210faf100f4eef1fe6ccf19e
+  data.tar.gz: 0445d88c6bc2f9f125dad833f744b4c0ac828b7db0d9d7615b923fadaa6d84b1
 SHA512:
-  metadata.gz: f4e4449d2a8764a762c13ea14b6ccac17b07d1ae06a053a94e5b66ce7ebf38b8ca2903c140f0bb06810e09fa830bdac1dcfb8485d2f6f7fe32f7b0dffdf374bb
-  data.tar.gz: 1faa31a8c32f067cdfb133c06e6c3d45e55fec3381d86f649e8845b9d2c58bc367e2bed3821cbec4a92a18776b723ccf69c276f9e913347198816005c4608353
+  metadata.gz: 3756b5d465e82dd5faff921733131dbe03f14e023ab99812f5a75ffdfc201d6151a5dfa2aae32194b4d60261ebdec1d25ffb573011f8ecb2a6254d2783fb4b6d
+  data.tar.gz: 9f4b12151c992af3bfa326cb86fa1a3f3cb8d083777e81daa6946924c3561b021a547536f23832ef00f7202352c6368ef69fb1e667247d96867f61ee839fd3bd

data/CHANGELOG.md

@@ -2,6 +2,148 @@
 
 All notable changes to PromptObjects are documented in this file.
 
+## [Unreleased]
+
+## [0.7.0] - 2026-07-11
+
+### Added
+
+- **Durable concurrent run runtime** — Prompt Objects are reusable definitions;
+  mutable execution now belongs to persisted workspace sessions, PO-owned
+  threads, runs, messages, tool executions, artifacts, and ordered events.
+  Multiple threads and independent POs can execute concurrently with immutable
+  definition snapshots, strict per-thread ordering, cancellation, deadlines,
+  bounded queues, provider/tool permits, resource locking, recovery, retention,
+  diagnostics, and reconnect-safe snapshots.
+- **Parallel composition and delegation** — safe tool batches execute in
+  parallel, while `dispatch_po`, `get_run_status`, and `join_runs` support
+  non-blocking multi-PO fan-out with attached/detached lifetimes and follow-up
+  work. Independent operations overlap; conflicting resource keys serialize.
+- **First-class runtime surfaces** — Image Floor, Semantic Loom, Artifact
+  Cockpit, live run activity, multi-thread navigation, autonomous countdowns,
+  and the semantic Run Debugger expose the same durable runtime from different
+  working angles.
+- **Beginner and pro Sonic Pi templates** — `music-beginner` provides a curated,
+  talk-safe ensemble with connected phrases and coordinated movements;
+  `music-pro` exposes a live-pattern language, raw patches, transformations,
+  duration-aware gating, and open-ended musician identities. Both verify live
+  engine state instead of trusting prose claims.
+- **Current-generation model support** — OpenAI GPT-5.6 Luna/Terra/Sol and
+  GPT-5.4 Mini/Nano plus Gemini 3.5 Flash and 3.1 Flash Lite are available in
+  the model selector. Environment manifests can persist their provider/model;
+  `music-beginner` defaults to Gemini 3.5 Flash.
+- **Operational release gates** — content-free diagnostics, bounded event
+  retention, migration backups, recovery documentation, deterministic
+  concurrency tests, and an end-to-end release rehearsal cover long-running
+  environments and live music demos.
+- **The Floor** — a new default home view: a pannable, zoomable canvas where every PO is a draggable *station* showing its live, interactive BURP artifact (or a quiet identity card until it renders one). Active PO→PO delegations draw as animated edges between stations, autonomous POs show a tick indicator, new POs animate onto the floor, and station positions persist per environment. Clicking a station opens a right-hand conversation drawer (shared renderer with the Browser's Workspace: thoughts, delegations, tool calls inline) with a composer. The Smalltalk System Browser remains one click away as the "Browser" view, and the connection indicator now reports reconnect attempts truthfully.
+
+- **BURP — Bidirectional UI Rendering Protocol** — Artifacts are now interactive interfaces, not just output. Every artifact (in-app iframe and pop-out window) gets a `PromptObjects.send(message)` function; wiring it to buttons/forms/controls sends a natural-language message back to the PO that rendered the artifact, via `POST /api/artifacts/:key/message` → `inject_message` with provenance `artifact:<title>`. The PO responds by re-rendering the artifact, closing the loop — POs can build the UI the human uses to talk to them. `render_artifact`'s guidance teaches POs the pattern (including that a re-render resets the artifact's local JS state). Messages are validated (shape, length, iframe identity) before injection.
+- **`poop` CLI alias** — the gem now installs a `poop` executable (**P**rompt-**O**bject **O**riented **P**rogramming) alongside `prompt_objects`. Identical behavior, twice the dignity.
+- **POs are taught to build interfaces** — every PO's system prompt now includes an "interactive artifacts" section (artifacts are bidirectional, wire controls to `PromptObjects.send`, re-render on `artifact:<title>` messages, prefer an interface over walls of text for stateful work), and lists `artifact:<title>` / `timer:<name>` among message sources. The bundled templates lean in: both music conductors now render an interactive **Mixing Desk** (tempo nudges, voice mutes, mood switches wired back to the conductor), the developer and writer coordinators keep a **Workbench** / **Drafting Desk**, and the basic/minimal/empty assistants offer to build a panel when work has ongoing state.
+
+### Changed
+
+- **All entry points use runs** — WebSocket, REST, CLI, MCP, connectors,
+  services, timers, and artifact actions now share one durable enqueue and
+  execution path. The former mutable Prompt Object receive loop has been
+  removed.
+- **Thinking is opt-in** — visible thinking is no longer inherited by every
+  Prompt Object; `think` is a standard-library primitive that environments add
+  deliberately.
+- **Autonomous scheduling is live-editable** — timers wait for a human
+  initialization turn when configured, expose truthful countdown state, use a
+  dedicated coalesced thread, and adopt frontmatter message/interval changes
+  without a restart.
+- **CLI restructured** — `exe/prompt_objects` was 1,100 lines of inline command logic; it's now a thin shim over `PromptObjects::CLI.run`, with each command (`env`, `serve`, `repl`, `message`, `events`, `explore`) in its own class under `lib/prompt_objects/cli/`. Help/usage text uses the invoked program name, so `poop` introduces itself as `poop`. Added `PromptObjects::VERSION` as the single source of truth (gemspec and REPL header read it). Removed the unused `CLI.parse` and `CLI.list_templates`. No behavior changes to any command.
+- **Environment exports are now `.dump` files** — **D**eclarative **U**nified **M**emory **P**ackages. `env export` writes `<name>.dump` by default; `env import` still accepts legacy `.poenv` bundles (the format is unchanged — a git bundle by any other name).
+
+### Fixed
+
+- **Provider tool-call compatibility** — Gemini thought signatures survive
+  persisted multi-step tool calls, scalar tool results are normalized, and
+  GPT-5.6 function calls use the Chat Completions compatibility parameters they
+  require.
+- **Thread and surface stability** — a first message selects its newly created
+  thread; thinking, transcripts, and artifacts no longer disappear between
+  autonomous turns; Cockpit fills the screen; and featured Image Floor cards
+  no longer overlap later rows.
+- **Connected music playback** — beginner patterns separate onset step from
+  synth gate, while pro patterns derive envelopes from duration. Conductors
+  preserve rhythmic/connective anchors and evolve coordinated movements rather
+  than producing isolated notes or unrelated rewrites.
+- **Artifact pop-out and BURP buttons 404ing** — Falcon delivers `PATH_INFO` as ASCII-8BIT, and SQLite binds binary strings as BLOBs that never match TEXT columns, so every keyed lookup from a URL path (artifact pop-outs, BURP button posts, session activate/rename) silently missed. Paths are normalized to UTF-8 at the API entry point. Verified live end-to-end: a real PO rendered a counter panel, a posted button click came back as `artifact:<title>`, and the PO re-rendered the panel with the new count.
+- **Messages to a busy PO now queue instead of being lost or interleaving** — POs are single-actor; a message arriving mid-turn (human, artifact click, webhook) lands in a bounded per-PO inbox and is delivered as soon as the current turn finishes, broadcasting `message_queued` so the UI can show it. The composer is no longer locked while a PO is thinking — Enter queues your message.
+- **POs now actually close the BURP loop** — `from_source` provenance is UI metadata the LLM never saw, so POs answered artifact clicks with prose and never updated the panel. Artifact messages are now framed with their interface origin and a re-render nudge, so the PO updates the artifact the human is actually looking at.
+
+### Removed
+
+- **Three.js spatial canvas** — the `/canvas` view (~2,000 LOC plus the `three` and `d3-force` dependencies) is retired. The Floor does its job natively: live PO stations, status, and animated delegation edges on a pannable DOM surface — with the artifacts interactive instead of decorative.
+- **Inherited `ask_human` and visible-thinking tools** — `ask_human` is no
+  longer a universal capability, and thinking must be granted explicitly.
+
+### Runtime, environment, and artifact foundations
+
+#### Added
+
+- **Environment-level workspaces** — Workspace sessions own shared environment
+  data and artifacts, while each Prompt Object owns multiple durable human,
+  autonomous, and delegation threads. A universal run entry point handles every
+  message source, and `POST /api/messages` lets webhooks, cron, and bots enqueue
+  work with idempotency keys and explicit workspace/thread targeting.
+- **Autonomous Prompt Objects** — Declare `autonomous: { interval:, message:,
+  start_on_boot:, wait_for_human: }` in frontmatter. Timer turns use one durable,
+  summary-retained autonomous thread per PO and coalesce while work is pending,
+  so a slow model cannot create an unbounded backlog.
+- **Services framework** — A `Service` base class (`start`/`stop`/`tick`/`interval`) loaded from an environment's `services/` directory. Tick loops are async-native (cooperate with Falcon's event loop). Services read/write the shared env_data store scoped to the active session.
+- **Artifact system** — A `render_artifact` universal capability (`replace`/`version` modes) plus an `ArtifactPane` that renders PO-generated HTML/JSX in a sandboxed iframe (React 18 + ReactDOM + Babel + Tailwind via CDN). Resizable, dock toggle (bottom/right), fullscreen, pop-out to a window that live-polls `/artifacts/:key`, and persistence across session reloads.
+- **Music templates + Sonic Pi** — Two templates (`chiptune`, genre-specific; `music`, genre-agnostic) where a conductor PO orchestrates voice POs that play through Sonic Pi over OSC. A warm audio engine (master clock so voices lock in time, FX bus, "sound pack" presets), a shared composition contract (key/scale/tempo/progression/roles), and `query_sonic_pi` / `set_tempo` primitives.
+- **Raw frontmatter editing in the UI** — The Inspector's SourcePane has a Prompt / Raw .md toggle; Raw mode edits the whole file (frontmatter + body) and hot-reloads, so autonomous/`delegates_to`/`tools` can be tuned from the UI.
+- **Session management** — manage environment-level sessions (the shared-context "jams" that scope env_data): `GET/POST /api/sessions` and `POST /api/sessions/:id/{activate,rename,delete}`, plus a SessionSelector in the SystemBar to switch/create/rename/delete.
+- **Connector framework** — load connectors from an environment's `connectors/` directory (like services); they start/stop with the server and route inbound external events to POs via `Connectors::Base#inject` (Discord/Slack/webhook bridges; clients are user-supplied).
+- **Frontend test harness** — vitest + Testing Library scaffold (`npm test`) and a Ruby end-to-end smoke test for the chiptune template.
+- **Optional visible reasoning** — environments may grant the standard-library
+  `think` primitive when visible working notes are useful; it is not inherited
+  by every Prompt Object.
+- **New frontend views** — Session Timeline (chronological activity feed), Environment Dashboard (overview when no PO is selected), autonomous-PO indicators in the ObjectList, and a PO selector in the message input.
+- **Environment dependencies & vendored gems** — Manifests declare `dependencies.gems`; templates can vendor gems under `vendor/<gem>/lib/` (auto-added to `$LOAD_PATH`).
+- **`POST /api/prompt_objects`** — Create a Prompt-Object via the REST API.
+- **Simplified frontmatter** — `delegates_to:` + `tools:` (kept distinct for the author, merged internally).
+
+#### Changed
+
+- **env_data scoped to the environment session** — `set_env_data`/`get_env_data`/`list_env_data`/`delete_env_data` (and artifacts) now resolve scope through a single helper that prefers the environment-level session, so every PO and autonomous tick shares one durable store. `set_env_data` replaces the former `store_env_data` + `update_env_data`.
+- **Unified WebSocket path** — `handle_send_message` routes through `inject_message` instead of calling `po.receive()` directly.
+- **Tool-call narration is preserved** — The assistant's prose alongside a tool call is no longer dropped, so turns that narrate-and-act stay visible.
+- **MethodList split** — the Inspector shows a PO's "Delegates To" (other POs) and "Tools" (primitives) as separate sections.
+- **Inline delegation visibility** — PO-to-PO calls render as "→ &lt;po&gt;" with the delegate's reply inline (Workspace + Timeline), and external sources (timer/service/api/webhook) show with a ← indicator.
+- **Artifact pane** — download an artifact as standalone HTML, and browse versions (`mode: "version"`) grouped under one tab.
+
+#### Removed (breaking)
+
+- **`create_primitive`, `add_primitive`, `list_primitives` universals** — removed as redundant. Use `create_capability(type: "primitive", …)`, `add_capability(target:, capability:)`, and `list_capabilities(type: "primitives")` instead. Prompt objects in environments created from older templates that reference the removed names by prose will have those calls rejected by the capability guard with a hint; update the prompt text (all bundled templates were updated). The remaining primitive lifecycle universals (`delete_primitive`, `modify_primitive`, `verify_primitive`, `request_primitive`) are unchanged.
+
+#### Fixed
+
+- **Sonic Pi audio quality** — Tempo changes now reach the voice loops (`use_bpm` was thread-local and called in the wrong thread); a master clock keeps voices from drifting; per-note attack removes clicks; lower amps plus a master compressor stop clipping.
+- **No mid-conversation reload on in-app saves** — `create_capability`/`add_capability`/`modify_prompt` and the source editor no longer trigger a FileWatcher reload that swapped the live PO instance mid-turn.
+
+## [0.6.0] - 2026-02-17
+
+### Added
+
+- **Shared environment data** — 5 new universal capabilities (`store_env_data`, `get_env_data`, `list_env_data`, `update_env_data`, `delete_env_data`) provide a thread-scoped key-value store for delegation chains. Data is scoped to the root thread so separate conversations stay isolated. Entries include a `short_description` for lightweight LLM discovery without fetching full values.
+- **Live environment data pane** — New collapsible pane in the Inspector shows shared env data updating in real-time as POs store and modify entries during delegation chains. WebSocket broadcasting (`env_data_changed`, `env_data_list`), a REST endpoint (`GET /api/sessions/:id/env_data`), and env data rendering in the Thread Explorer.
+- **Delegation context** — POs now receive context about their delegation chain. An expanded system prompt teaches POs about their nature, a delegation preamble prepends caller context to delegated messages, and the full delegation chain is built from thread lineage.
+- **Capability guard** — `execute_tool_calls` now rejects tools not in a PO's allowed set (declared capabilities + universals). Previously the LLM could hallucinate calls to any registered tool and they would execute. Now it receives an error directing it to use `add_capability` first.
+- **Env data in thread exports** — `serialize_tree_for_export` includes env data entries at the root level of exported thread trees. Thread Explorer renders these in an amber-colored section.
+
+### Fixed
+
+- **Root font-size causing undersized text** — Removed a `font-size: 14px` on the root `html` element that made all rem-based Tailwind sizes ~12% smaller than intended (e.g. `text-xs` computed to 10.5px instead of 12px).
+- **Invisible resize handle boundaries** — Added border styling to horizontal and vertical resize handles so pane boundaries are visible without hovering.
+- **Stale MCP tools tests** — Fixed test expectations broken by PO serialization centralization in 0.5.0.
+
 ## [0.5.0] - 2026-02-13
 
 ### Added

data/README.md

@@ -12,11 +12,6 @@ Prompt Objects applies this to AI. Instead of treating LLMs as external APIs you
 
 This is a new computing primitive: semantic late binding at runtime, where natural language becomes the interface between intelligent components.
 
-Blog Posts
-==========
-
-- [What if we took message passing seriously?](https://worksonmymachine.ai/p/what-if-we-took-message-passing-seriously) — The origin story and motivation behind Prompt Objects.
-
 Who
 ===
 
@@ -32,8 +27,144 @@ A Ruby framework where:
 - **Markdown files** define autonomous entities (Prompt Objects)
 - **YAML frontmatter** declares capabilities and configuration
 - **Markdown body** becomes identity and behavior (the system prompt)
-- **Capabilities** are shared between primitives (Ruby) and Prompt Objects (markdown)
-- **Environments** isolate collections of objects with their own memory
+- **Capabilities** are shared between primitives (Ruby) and Prompt Objects (markdown) -- everything is a capability
+- **Environments** isolate collections of objects with their own memory, git history, and configuration
+- **PO-to-PO delegation** lets objects call each other through isolated threads with full provenance tracking
+- **Autonomous Prompt Objects** can act on their own interval (`autonomous:` frontmatter), thinking and delegating without a human in the loop
+- **Services** run background work alongside the server, and **environment-level sessions** give every object a shared, durable key-value memory (env_data)
+- **Artifacts** let a PO render live HTML/JSX dashboards in the UI; external systems can drive POs over a REST endpoint (`POST /api/messages`)
+
+### Prompt Object structure
+
+```markdown
+---
+name: reader
+description: Helps people understand files
+capabilities:
+  - read_file
+  - list_files
+---
+
+# Reader
+## Identity
+You are a careful, thoughtful file reader...
+```
+
+### Web UI
+
+The web interface treats the environment as a running image rather than a chat
+application. Its views share the same durable workspaces, threads, runs,
+artifacts, and environment data:
+
+- **Floor** -- the default view: freely arranged, resizable PO stations with
+  live artifacts, timer state, and delegation edges.
+- **Browser** -- a Smalltalk-style object browser for source, capabilities,
+  environment data, multiple threads, chat, live activity, and timelines.
+- **Image Floor** -- a responsive wall of every PO's latest visual interface.
+- **Semantic Loom** -- a factual map of delegation, tools, shared state, and
+  outputs around a selected PO.
+- **Artifact Cockpit** -- one live artifact at useful size with its revision,
+  owner, provenance, and action traffic.
+- **Run Debugger** -- a durable execution timeline with model context,
+  definition snapshots, tool executions, child runs, and state effects.
+
+The Transcript remains available across views, and reconnects hydrate
+authoritative snapshots before replaying newer events.
+
+### Interactive artifacts (BURP)
+
+POs can render HTML/JSX artifacts into a dockable pane (React 18, Tailwind, and Babel are available in a sandboxed iframe). Artifacts are **bidirectional** — the **B**idirectional **U**I **R**endering **P**rotocol injects a `PromptObjects.send(message)` function into every artifact, which delivers a natural-language message back to the PO that rendered it (provenance shows as `artifact:<title>` in the message log). A PO can build a dashboard with buttons and forms, the human clicks instead of typing, and the PO re-renders the artifact in response: generative UI as a second modality of conversation. Works in the in-app pane and popped-out artifact windows.
+
+### Durable concurrent runtime
+
+Each Prompt Object is a reusable definition; mutable execution belongs to
+durable runs inside PO-owned threads. A single PO can have multiple threads, and
+independent threads, delegations, and safe tool calls can execute concurrently.
+Resource keys serialize conflicting side effects, while bounded worker/provider
+permits, deadlines, cancellation, autonomous coalescing, and event retention
+keep long-running environments controlled. REST, WebSocket, CLI, MCP, services,
+connectors, timers, and artifact actions all enter through the same run path.
+
+### Generative music (Sonic Pi)
+
+Music environments connect an ensemble of Prompt Objects to
+[Sonic Pi](https://sonic-pi.net/) over OSC. The conductor establishes a shared
+musical contract and coordinates musicians that author and rewrite their own
+synchronized parts.
+
+- `music-beginner` is a constrained, talk-safe backing ensemble with curated
+  instruments, connected phrases, coordinated movements, and Gemini 3.5 Flash
+  as its persisted default model.
+- `music-pro` exposes chords, samples, subdivisions, alternation, transforms,
+  raw Sonic Pi parameters, runtime-defined patches, and duration-aware gating
+  while preserving an audible connective layer.
+- `music` remains the open-ended dynamic-band template, and `chiptune` remains
+  available for its original genre-specific workflow.
+
+### Demos
+
+| <a href="https://www.loom.com/share/32c17ccd07bf4b6e99f1ff06aab5bee0"><img src="docs/images/intro_walkthrough.png" alt="Intro walkthrough" width="600"></a> | <a href="https://www.loom.com/share/3a04fa73efd8407eae2b122740082268"><img src="docs/images/arc_agi_1_template.png" alt="ARC-AGI-1 template" width="600"></a> |
+|:---:|:---:|
+| **Intro walkthrough**: creating an environment, interacting with POs, and exploring the web UI | **ARC-AGI-1 template**: using the ARC-AGI-1 solver environment with multi-PO delegation |
+
+### MCP Server mode
+
+Run any environment as an MCP (Model Context Protocol) server for integration with Claude Desktop, Cursor, or any MCP-compatible client:
+
+```bash
+prompt_objects serve my-assistant --mcp
+```
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-assistant": {
+      "command": "prompt_objects",
+      "args": ["serve", "--mcp", "my-assistant"]
+    }
+  }
+}
+```
+
+Exposes tools for sending messages, listing POs, inspecting state, getting conversations, and responding to pending capability-approval requests.
+Message responses include durable workspace, thread, and run IDs. Pass a
+`client_request_id` when retries are possible; `thread_id` continues a specific
+conversation (`session_id` remains a compatibility alias).
+
+External services can enqueue the same runtime through REST:
+
+```bash
+curl -X POST http://127.0.0.1:3000/api/messages \
+  -H 'Content-Type: application/json' \
+  -d '{"target_po":"assistant","content":"Process this event","from_source":"service:webhook","client_request_id":"event-42"}'
+```
+
+The response contains `workspace_session_id`, `thread_id`, `run_id`, `status`,
+and the Prompt Object response. Workspace and thread IDs may be omitted to use
+source-appropriate defaults.
+
+### Multi-provider LLM support
+
+Choose a provider/model in the UI; the selection is stored in the environment
+manifest and survives restarts. API keys come from the corresponding environment
+variables. Adapters include:
+
+- **OpenAI** -- GPT-5.6 Luna, Terra, and Sol; GPT-5.4 Mini/Nano; GPT-5.2; GPT-4.1
+- **Anthropic** -- Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4
+- **Gemini** -- Gemini 3.5 Flash, Gemini 3.1 Flash Lite, Gemini 3 Flash, Gemini 2.5 Pro/Flash
+- **Ollama** -- any locally installed model, discovered automatically
+- **OpenRouter** -- access any model through a single API key
+
+### Thread Explorer
+
+A standalone HTML visualizer for exported conversation threads. Open it from the CLI to browse delegation chains, message flow, and tool call sequences:
+
+```bash
+prompt_objects explore my-env
+prompt_objects explore my-env --session abc123
+```
 
 How
 ===
@@ -54,25 +185,86 @@ prompt_objects env create my-project --template basic
 prompt_objects serve my-project --open
 ```
 
-### Environment Commands
+The gem also installs `poop` (**P**rompt-**O**bject **O**riented **P**rogramming) as an alias for the `prompt_objects` command. Every example below works with either.
+
+### Commands
 
-```bash
-prompt_objects env list              # List all environments
-prompt_objects env create <name>     # Create new environment
-prompt_objects env info <name>       # Show environment details
-prompt_objects env clone <src> <dst> # Clone an environment
 ```
+prompt_objects serve <env>                  Start web server (default)
+prompt_objects serve <env> --open           Start and open browser
+prompt_objects serve <env> --mcp            Start as MCP server
+prompt_objects serve <env> --port 4000      Custom port (default: 3000)
+prompt_objects --version                    Print the installed version
+
+prompt_objects repl [name] [objects_dir]    Interactive REPL with a prompt object
+prompt_objects repl --sandbox               REPL in sandbox mode (isolates changes)
+
+prompt_objects message <env> <po> "text"    Send a message and print the response
+prompt_objects message <env> <po> "text" --json     JSON output
+prompt_objects message <env> <po> "text" --events   Include event log
+
+prompt_objects events <env>                 Show recent message bus events
+prompt_objects events <env> --session ID    Events for a specific session
+prompt_objects events <env> --json          JSON output
+prompt_objects diagnostics <env> --json     Content-free runtime health
+
+prompt_objects explore [env]                Open Thread Explorer in browser
+prompt_objects explore <env> --session ID   Visualize a specific thread
+```
+
+### Environment management
+
+```
+prompt_objects env list                     List all environments
+prompt_objects env create <name>            Create new environment
+prompt_objects env create <name> -t <tmpl>  Create from template
+prompt_objects env info <name>              Show environment details
+prompt_objects env clone <src> <dst>        Clone an environment
+prompt_objects env export <name>            Export as .dump bundle
+prompt_objects env import <file.dump>       Import from bundle (.poenv still works)
+prompt_objects env archive <name>           Soft-delete (archive)
+prompt_objects env restore <name>           Restore archived environment
+prompt_objects env delete <name> --permanent  Permanently delete archived env
+prompt_objects env default <name>           Set the default environment
+```
+
+Exports are **D**eclarative **U**nified **M**emory **P**ackages — a `.dump` file is a git bundle of the environment's complete state and history.
+
+Operational guidance: [runtime diagnostics and recovery](https://github.com/works-on-your-machine/prompt_objects/blob/main/docs/operations/runtime-recovery.md) and the [release rehearsal checklist](https://github.com/works-on-your-machine/prompt_objects/blob/main/docs/operations/release-rehearsal.md).
 
 ### Templates
 
-- `basic` - No capabilities, learns as needed (great for demos)
-- `minimal` - Basic assistant with file reading
-- `developer` - Code review, debugging, testing specialists
-- `writer` - Editor, researcher for content creation
+Create an environment from a template with `prompt_objects env create <name> --template <template>`:
+
+| Template | Description |
+|---|---|
+| `basic` | No capabilities, learns as needed -- great for demos |
+| `minimal` | Basic assistant with file reading |
+| `developer` | Code review, debugging, testing specialists |
+| `writer` | Editor, researcher for content creation |
+| `empty` | Start from scratch with just a bootstrap assistant |
+| `arc-agi-1` | ARC-AGI-1 challenge solver with grid primitives |
+| `arc-agi-3` | ARC-AGI-3 agent with player, analyst, and strategist POs |
+| `chiptune` | Collaborative chiptune band — conductor + voice POs driving Sonic Pi |
+| `music` | Genre-agnostic band — the conductor builds voices for any style on the fly |
+| `music-beginner` | Talk-safe generative backing ensemble with curated Sonic Pi instruments |
+| `music-pro` | Expressive live-pattern ensemble with independent voice POs and raw Sonic Pi patches |
 
 Extras
 ======
 
-- **License**: MIT
-- **Ruby**: >= 3.2.0
+### Community
+
+Join the [Discord](https://discord.gg/fcMvcwdrZS) for support, discussion, and updates.
+
+### Blog Posts
+
+- [What if we took message passing seriously?](https://worksonmymachine.ai/p/what-if-we-took-message-passing-seriously) -- the origin story and motivation behind Prompt Objects
+- [As complexity grows, architecture](https://worksonmymachine.ai/p/as-complexity-grows-architecture) -- on why the hard problems are structural, not generative
+
+### Links
+
 - **Repository**: https://github.com/works-on-your-machine/prompt_objects
+- **Changelog**: https://github.com/works-on-your-machine/prompt_objects/blob/main/CHANGELOG.md
+- **License**: MIT
+- **Ruby**: >= 3.2.0 (tested through Ruby 4)

data/exe/poop

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# poop — Prompt-Object Oriented Programming. Same CLI, prouder name.
+load File.expand_path("prompt_objects", __dir__)