Audit and correct package documentation

Author: aezell

README.md

@@ -9,7 +9,9 @@ First-class [Sprites](https://sprites.dev) environments for the [Pi coding agent
 
 ## Install
 
-Until the first npm release, install directly from GitHub:
+`pi-sprites` is not published to npm. Until the first npm release, install it
+directly from GitHub (the repository must be public or your Git client must
+already have access):
 
 ```bash
 pi install git:github.com/superfly/pi-sprites
@@ -24,6 +26,7 @@ pi install npm:pi-sprites
 For development from this checkout:
 
 ```bash
+npm ci
 pi -e ./extensions/core.ts \
   -e ./extensions/checkpoints.ts \
   -e ./extensions/services.ts \
@@ -85,7 +88,7 @@ See the [extension guide](./docs/README.md) for prerequisites, configuration, co
 
 ## Project configuration
 
-Copy [`templates/sprites.json`](./templates/sprites.json) to `.pi/sprites.json` and adjust it for the project. Project configuration overrides `~/.pi/agent/sprites.json`; ignored `.pi/sprites.local.json` overrides both.
+Copy [`templates/sprites.json`](./templates/sprites.json) to `.pi/sprites.json` and adjust it for the project. Project configuration overrides `~/.pi/agent/sprites.json`; a machine-local `.pi/sprites.local.json` overrides both. Add the local file to the project's `.gitignore` before putting machine-specific or sensitive values in it.
 
 The major sections are:
 
@@ -104,11 +107,11 @@ With the default `toolActivation: "auto"`, commands remain available but the eig
 
 ## Checkpoints
 
-The default `risky` mode creates one safety checkpoint before the first write, edit, destructive shell command, or mutating Sprite management tool in a Pi turn. `turn` applies the same once-per-turn checkpoint to any mutation; `off` disables automatic checkpoints.
+The default `risky` mode creates one safety checkpoint before the first write, edit, recognized destructive shell command, or service, policy, or RPC-host model tool in a Pi turn. Those three model tools are conservatively treated as risky even for read-only actions. `turn` applies the same once-per-turn checkpoint before any tool call; `off` disables automatic checkpoints.
 
 Restore remains command-only and requires confirmation. Checkpoints contain the filesystem, installed packages, configuration, and on-disk databases. They do not contain running processes, memory, or open connections.
 
-Checkpoint deletion and filesystem diffs are intentionally not implemented until the public Sprites SDK exposes stable APIs for them. The package does not reach through SDK internals or assume a private checkpoint mount layout.
+Checkpoint deletion and filesystem diffs are intentionally not implemented because the installed public JavaScript SDK does not expose stable APIs for them. The package does not reach through SDK internals or assume a private checkpoint mount layout.
 
 ## Services and networking
 
@@ -153,17 +156,17 @@ This installs Pi as a Sprite service and exposes it locally through a TCP proxy.
 - `POST /rpc`
 - `GET /events` as server-sent events
 
-The service has no public HTTP port by default. When `rpcHost.httpPort` is configured, the secret named by `rpcHost.secretEnv` must be present; requests must send it as `Authorization: Bearer ...`.
+The service is not routed through the Sprite URL by default. When `rpcHost.httpPort` is configured, the secret named by `rpcHost.secretEnv` must be present and requests must send it as `Authorization: Bearer ...`. Configuring the service port does not change the Sprite URL's own `sprite` (authenticated) or `public` access setting.
 
 ## Safety defaults
 
 - Sprite destruction and checkpoint restore are command-only and confirmed.
 - CI and workers are retained unless cleanup is explicitly configured.
 - The RPC host is local-proxy-only unless configured otherwise.
 - Public URL access is never enabled automatically.
-- Provider credentials are not copied into Sprites.
+- Local provider credentials are not copied into Sprites automatically.
 - Project setup commands run only from a trusted project's configuration.
-- New, resumed, and forked Pi sessions reset selection, proxies, and last-checkpoint state.
+- New, resumed, and forked Pi sessions reset transient selection to configured defaults and clear proxies and last-checkpoint state.
 
 Pi packages execute with the user's full permissions. Review package source before installation, just as you would any other Pi extension.
 

docs/README.md

@@ -21,7 +21,7 @@ Testing guides:
 
 ## How Pi treats these files
 
-Pi packages have runtime resource types for extensions, skills, prompts, and themes. There is no separate documentation resource type. These Markdown files are shipped in the npm package and linked from the top-level README, but are deliberately absent from the `pi` manifest. Pi therefore does not load them as prompts or place them in model context.
+Pi packages have runtime resource types for extensions, skills, prompts, and themes. There is no separate documentation resource type. These Markdown files are shipped with the package and linked from the top-level README, but are deliberately absent from the `pi` manifest. Pi therefore does not load them as prompts or place them in model context. See Pi's [package documentation](https://pi.dev/docs/latest/packages) for the resource and filtering model.
 
 Commands beginning with `/sprite-` are always available when their extension is loaded and are initiated by the user. Tools named `sprite_*` are callable by the model. With the default `toolActivation: "auto"`, those model tools become active only after a Sprite is selected or when Pi itself is running inside a Sprite. See [Core remote environment](./core.md#model-tool-activation) for the other activation modes.
 
@@ -30,19 +30,19 @@ Commands beginning with `/sprite-` are always available when their extension is
 - Node.js 24 or later.
 - A Sprites token in `SPRITES_TOKEN`, `SPRITE_TOKEN`, or the variable named by `tokenEnv`.
 - A selected or configured Sprite for extensions that operate on the current environment. Checkpoints can also use `sprite-env` when Pi itself runs inside a Sprite. Bootstrap, CI, and workers can provision explicitly named Sprites without changing the user's selection.
-- Project trust before `.pi/sprites.json` or `.pi/sprites.local.json` is honored. Global `~/.pi/agent/sprites.json` remains available outside a trusted project.
+- Project trust before `.pi/sprites.json` or `.pi/sprites.local.json` is honored. Global `~/.pi/agent/sprites.json` remains available outside a trusted project. Add `.pi/sprites.local.json` to the consuming project's `.gitignore` before using it for local-only values.
 
 Start with the configuration template at [`templates/sprites.json`](../templates/sprites.json).
 
 ## Filtering extensions
 
-Pi package filters can narrow the extension list. For example, this project setting keeps only core routing and checkpoints:
+Pi package filters can narrow the extension list. For example, this entry in the project's `.pi/settings.json` keeps only core routing and checkpoints for the current Git installation:
 
 ```json
 {
   "packages": [
     {
-      "source": "npm:pi-sprites",
+      "source": "git:github.com/superfly/pi-sprites",
       "extensions": [
         "+extensions/core.ts",
         "+extensions/checkpoints.ts"

docs/automated-testing.md

@@ -97,13 +97,16 @@ export SPRITES_TOKEN='...'
 pi -p --no-session \
    -e ./extensions/core.ts -e ./extensions/checkpoints.ts \
    -e ./extensions/services.ts -e ./extensions/policy.ts \
-   "Create a Sprite named agent-smoke, write /workspace/agent-smoke/ok.txt, \
-    read it back, create a checkpoint, then destroy the Sprite."
+   "Create a Sprite named agent-smoke, select /workspace/agent-smoke as its \
+    working directory, write ok.txt, read it back, create a checkpoint, and \
+    report the Sprite name for manual cleanup."
 ```
 
 This is the closest match to "an agent does the testing," but it is
 non-deterministic (results depend on the model). Use it for exploratory or
 acceptance-style checks, and Approach A for deterministic regression gating.
+Destruction is intentionally unavailable to model tools; clean up afterward in
+an interactive Pi session with `/sprite-destroy agent-smoke` and confirm it.
 
 ## Approach C — Drive a durable Pi over RPC
 
@@ -115,8 +118,9 @@ host and talk to it over HTTP:
 /sprite-rpc proxy
 ```
 
-Then `POST /rpc` with JSON-line requests, subscribe to `GET /events`, and poll
-`GET /health`. See [rpc-host.md](./rpc-host.md). This is useful when the tester is
+Then send one JSON command object in each `POST /rpc` HTTP body, subscribe to
+`GET /events`, and poll `GET /health`. The host handles JSONL framing toward the
+Pi child process. See [rpc-host.md](./rpc-host.md). This is useful when the tester is
 itself an autonomous agent that needs a persistent session rather than one-shot
 prompts.
 

docs/checkpoints.md

@@ -31,8 +31,8 @@ A selected Sprite is required unless Pi itself is running inside a Sprite, where
 Modes are:
 
 - `off`: no automatic checkpoints.
-- `risky` (default): once per turn, before the first write, edit, recognized destructive shell command, or mutating service, policy, or RPC-host tool call.
-- `turn`: once per turn before the first mutating tool call.
+- `risky` (default): once per turn, before the first write, edit, recognized destructive shell command, or service, policy, or RPC-host model-tool call. Those three model tools are conservatively treated as risky for every action, including inspection.
+- `turn`: once per turn before the first tool call, whether or not that tool is expected to mutate state.
 
 If a required automatic checkpoint fails, the mutation is blocked rather than allowed to continue without a recovery point.
 
@@ -44,6 +44,6 @@ Bootstrap, CI, and worker tool calls do not checkpoint the user's selected Sprit
 
 ## Limitations
 
-Checkpoint deletion and filesystem diff are not implemented. Those operations currently require SDK internals or an unstable on-disk layout; `pi-sprites` waits for stable public SDK APIs instead.
+Checkpoint deletion and filesystem diff are not implemented. The installed public JavaScript SDK does not expose those operations, and implementing them would require a hand-written API call or an unstable on-disk layout. `pi-sprites` avoids both.
 
 Restoring may terminate active processes and sessions. Services should restart according to the Sprite service manager, but arbitrary foreground processes will not be recreated.

docs/core.md

@@ -10,7 +10,7 @@ After `/sprite-use` or `/sprite-new`, these normal Pi operations target `remoteC
 - interactive `!` shell commands
 - the working-directory line added to the agent's system prompt
 
-`/sprite-local` returns those operations to the machine running Pi. Selection and open proxies reset when a Pi session starts, ends, resumes, forks, or is replaced.
+`/sprite-local` returns those operations to the machine running Pi. When a Pi session starts, resumes, forks, or is replaced, transient selection resets and configuration is reapplied; a configured `sprite` may therefore become selected again. Open proxies and last-checkpoint state are cleared between sessions.
 
 ## Commands
 
@@ -74,7 +74,7 @@ The setting does not disable Pi's normal filesystem tools; it only changes wheth
 }
 ```
 
-- `mode`: `auto`, `local`, or `remote`. `auto` uses remote routing when a Sprite is selected.
+- `mode`: `local` always keeps native tools on the Pi host; `remote` routes them when a Sprite is selected, including when Pi itself runs inside a Sprite; `auto` routes to a selected Sprite only when Pi is running outside one.
 - `sprite`: initial configured Sprite name.
 - `remoteCwd`: workspace directory inside the Sprite; otherwise `/workspace/<local-project-name>`.
 - `baseURL`: optional Sprites API endpoint override.

docs/manual-test-plan.md

@@ -21,20 +21,24 @@ logic. This plan covers the interactive experience those tests cannot.
   ```bash
   export SPRITES_TOKEN='...'
   ```
-- This checkout installed, and a scratch Git project to point bootstrap/CI at.
+- This checkout with `npm ci` completed, and a scratch Git project whose
+  `origin` is reachable from a Sprite without copying local credentials. Its
+  configured CI commands should be safe to run.
 - A throwaway Sprite name to avoid touching real work, e.g. `pi-sprites-test`.
 
-Launch Pi with all extensions from this checkout:
+From the scratch project, set the checkout path and launch Pi with all
+extensions:
 
 ```bash
-pi -e ./extensions/core.ts \
-   -e ./extensions/checkpoints.ts \
-   -e ./extensions/services.ts \
-   -e ./extensions/policy.ts \
-   -e ./extensions/bootstrap.ts \
-   -e ./extensions/ci.ts \
-   -e ./extensions/workers.ts \
-   -e ./extensions/rpc-host.ts
+PI_SPRITES_CHECKOUT=/absolute/path/to/pi-sprites
+pi -e "$PI_SPRITES_CHECKOUT/extensions/core.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/checkpoints.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/services.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/policy.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/bootstrap.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/ci.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/workers.ts" \
+   -e "$PI_SPRITES_CHECKOUT/extensions/rpc-host.ts"
 ```
 
 Cleanup is at the end. Nothing here enables public URLs or copies credentials.
@@ -45,14 +49,15 @@ Cleanup is at the end. Nothing here enables public URLs or copies credentials.
 
 | Step | Action | Expect |
 |---|---|---|
-| 1.1 | `/sprite status` | Reports local mode, no Sprite selected. |
+| 1.1 | `/sprite status` | Reports the current mode. With no global `sprite` configured, this is local mode with no selection. |
 | 1.2 | `/sprite list` | Lists your Sprites (or empty). Confirms auth works. |
-| 1.3 | `/sprite new pi-sprites-test` | Creates and selects the Sprite. |
-| 1.4 | `!pwd` | Runs in the **remote** Sprite, prints `remoteCwd` (`/workspace/pi-sprites-test`). |
-| 1.5 | `write` a file `hello.txt` with some text | File is created remotely. |
-| 1.6 | `read hello.txt` / `ls` | Shows the remote file. Confirms `read`/`write`/`ls` are routed. |
-| 1.7 | `/sprite-local` then `!pwd` | Returns to your **local** machine's cwd. |
-| 1.8 | `/sprite-use pi-sprites-test` then `ls` | Back on the remote workspace, file still present. |
+| 1.3 | `/sprite new pi-sprites-test` | Creates and selects the Sprite. Its initial `remoteCwd` is derived from the local project unless configured. |
+| 1.4 | `/sprite-use pi-sprites-test /workspace/pi-sprites-test` | Selects an explicit test working directory. |
+| 1.5 | `!mkdir -p /workspace/pi-sprites-test` then `!pwd` | Creates the workspace and prints `/workspace/pi-sprites-test` from the **remote** Sprite. |
+| 1.6 | Ask Pi to write a file `hello.txt` with some text | The `write` tool creates the file remotely. |
+| 1.7 | Ask Pi to read `hello.txt` and list the directory | The `read` and `ls` tools show the remote file. |
+| 1.8 | `/sprite-local` then `!pwd` | Returns to your **local** machine's cwd. |
+| 1.9 | `/sprite-use pi-sprites-test /workspace/pi-sprites-test` then ask Pi to list the directory | Back in the remote workspace, the file is still present. |
 
 **Pass criteria:** native tools transparently switch between local and remote,
 and selection survives within the session.
@@ -79,7 +84,7 @@ asks for confirmation; the model cannot restore.
 
 | Step | Action | Expect |
 |---|---|---|
-| 3.1 | `/sprite-service create web npm run dev` (or any simple command that stays up) | Service definition created in `remoteCwd`. |
+| 3.1 | `/sprite-service create web python3 -m http.server 3000` | Creates a long-running service in `remoteCwd` without relying on project-specific scripts. |
 | 3.2 | `/sprite-services` | Lists services with status. |
 | 3.3 | `/sprite-service logs web 200` | Streams recent logs. |
 | 3.4 | `/sprite-service restart web` | Restarts cleanly. |
@@ -108,15 +113,16 @@ confirms; empty rules == unrestricted (not deny-all).
 
 ## 5. Bootstrap: reproducible environment
 
-Point config at a real repo first. Create `.pi/sprites.json` (see
-`templates/sprites.json`) and set `bootstrap.repository`, `branch`, and safe,
-repeatable `commands`. **Trust the project** in Pi so config is honored.
+Point config at the scratch repo first. Create `.pi/sprites.json` (see
+`templates/sprites.json`), set `remoteCwd` to `/workspace/pi-sprites-test`, and
+set `bootstrap.repository`, `branch`, and safe, repeatable `commands`.
+**Trust the project** in Pi so config is honored.
 
 | Step | Action | Expect |
 |---|---|---|
 | 5.1 | `/sprite-bootstrap pi-sprites-test` | Reuses the Sprite, clones repo if no `.git`, checks out branch, runs trusted commands, applies policy, creates services, checkpoints. |
 | 5.2 | Re-run `/sprite-bootstrap pi-sprites-test` | Idempotent: reuses checkout, only creates missing services, reapplies policy. |
-| 5.3 | `/sprite-use pi-sprites-test /workspace/<project>` | Point native tools at the bootstrapped tree. |
+| 5.3 | `/sprite-use pi-sprites-test /workspace/pi-sprites-test` | Point native tools at the configured bootstrapped tree. |
 | 5.4 | `/sprite-services` and `/sprite-checkpoints` | Show the reconciled services and known-good checkpoint. |
 
 **Pass criteria:** bootstrap converges, is safe to repeat, refuses commands
@@ -161,12 +167,13 @@ uncommitted changes; your selection is untouched.
 | 8.2 | `/sprite-rpc status` | Reports service state and internal port. |
 | 8.3 | `/sprite-rpc proxy` | Session-scoped local TCP proxy. |
 | 8.4 | `curl localhost:43120/health` | Returns healthy. |
-| 8.5 | `curl -XPOST localhost:43120/rpc -d '{...}'` | Round-trips a JSON-line RPC request. |
+| 8.5 | `curl -sS -H 'Content-Type: application/json' -d '{"type":"get_state"}' http://localhost:43120/rpc` | Sends one JSON command over HTTP and returns its correlated Pi RPC response. |
 | 8.6 | `/sprite-rpc remove`, confirm | Deletes the service (session data remains). |
 
 **Pass criteria:** host installs as a service, is reachable only via local proxy
 by default, and removal confirms. (Only test `httpPort` + bearer secret if you
-explicitly want public HTTP routing.)
+explicitly want routing through the Sprite URL. Making that URL public is a
+separate platform setting and is not part of this plan.)
 
 ---
 
@@ -182,9 +189,13 @@ selection.
 
 ## 10. Session reset behavior
 
-Start a new/resumed/forked Pi session and run `/sprite status`: selection,
-proxies, and last-checkpoint state must reset. This guards against a stale
-session silently operating on the wrong environment.
+Select a Sprite other than the one declared in configuration, then start a new,
+resumed, or forked Pi session and run `/sprite status`. The transient selection
+must reset to the newly loaded configuration (or to no selection if none is
+configured), rather than carrying over the prior session's choice. Proxies are
+closed, and `/sprite-undo` must report that Pi has not created a checkpoint in
+the new session. This guards against stale state silently targeting the wrong
+environment.
 
 ---
 
@@ -206,7 +217,7 @@ no longer shows the test Sprites.
 | Extension | Covered by |
 |---|---|
 | Core | §1, §9, §10 |
-| Checkpoints | §2, plus auto checkpoints in §5/§6 |
+| Checkpoints | §2, plus bootstrap and CI failure checkpoints in §5/§6 |
 | Services | §3, §5.4 |
 | Policy | §4, §5.1 |
 | Bootstrap | §5, and reused by §6/§7 |

docs/releasing.md

@@ -1,6 +1,6 @@
 # Future npm releases
 
-`pi-sprites` is not currently published to npm, and this repository does not contain an active npm publishing workflow. Users should install directly from GitHub until maintainers announce otherwise.
+`pi-sprites` is not currently published to npm, and this repository does not contain an active npm publishing workflow. Until maintainers announce otherwise, install directly from GitHub; while the repository is not public, this requires existing GitHub access.
 
 ```bash
 pi install git:github.com/superfly/pi-sprites