@aefree/pi-plastic 0.7.6 → 0.8.0

package/docs/2026-10-06-shelvesets-and-reviews.md

@@ -0,0 +1,113 @@
+# Shelvesets and code reviews
+
+[Documentation index](README.md) · [Find object IDs](2026-10-06-discovery.md) · [Safety and receipts](2026-10-06-safety-and-receipts.md)
+
+Creation/application/update/deletion each returns its own bounded receipt. Preserve exact selectors and any earlier creation effects; do not chain on an inferred substring, hidden readback, or guessed namespace.
+
+## Presentation versus CLI formatting
+
+| Operation | Presentation | CLI template |
+|---|---|---|
+| Shelf create/apply; review create/update | `output="text"` or `output="json"`; default text | Creation review `format` remains an arbitrary CLI template |
+| Shelf/review deletion | `format="text"` or `format="json"`; default text | No new custom output grammar |
+| Shelf/review discovery | `output="text"` or `output="json"` | Native `format`/`dateFormat`; canonical ids source conflicts with meaningful templates |
+
+Custom review creation stdout stays opaque even if it looks like an ID. Defaults, ordered controls/duplicates and qualifiers are preserved; the tool does not force a formatter to manufacture reusable identity.
+
+## shelvesetCreate
+
+```text
+plastic_shelvesetCreate(paths=["Assets/Example.txt"], comment="Save owned work", summaryFormat=true, output="json")
+```
+
+One exact command preserves paths/all/dependencies/summaryFormat and exclusive comment/commentsFile. Omitted/empty path lists retain existing selection behavior; inspect intent before relying on broad scope.
+
+Only an entire supported emitted default or summary `sh:` scalar is created-identity evidence. No IDs are parsed from progress or fragments. Emitted qualifiers remain exact; requested/emitted namespace equivalence is not inferred.
+
+Comment-less creation with configured PLASTICEDITOR is refused before dispatch because it could launch an editor. Supply comment/commentsFile rather than overriding the environment. A command-only preflight still dispatches zero CLI commands.
+
+Successful emitted identity remains recorded if stderr warnings make completion uncertain. Root/Xlink/global effects and omitted other-repository information are not independently verified.
+
+## shelvesetApply
+
+```text
+plastic_shelvesetApply(shelveset="<exact observed shelf selector>", output="json")
+```
+
+Preserve selector, ordered changePaths, preview/dontCheckout and the documented comparison method. No automatic conflict input, strategy switch, readback/retry or undo.
+
+| Option | Meaning |
+|---|---|
+| `preflight=true` | Render command only; no CLI, no existence/conflict analysis |
+| `preview=true` | Real CM dispatch; can prompt/fail and does not prove no effects |
+| `dontCheckout` | Exact requested CLI policy; not proof of preservation |
+| `comparisonMethod` | ignoreeol, ignorewhitespaces, ignoreeolandwhitespaces, recognizeall |
+
+A tracked text change on the same clean base has conflict-free preview/apply evidence. An added-item case prompted for evil-twin resolution and failed. This does not establish general safe unattended conflict resolution.
+
+Complete apply output does not prove applied items/cleanliness/restoration; observedAppliedItems remains null. The agent can inspect state and choose an authorized resolution rather than assuming rollback or replay safety.
+
+## codeReviewCreate
+
+```text
+plastic_codeReviewCreate(target="br:/main/owned-feature", title="Owned feature review", output="json")
+```
+
+Preserve target/title and optional status/assignee/repository/format. **Assign someone only when requested.** Creating a review does not authorize changing another person's assignment or opening a real review conversation.
+
+An entire supported default numeric/GUID scalar can be emitted identity evidence. Custom stdout is always opaque; repository scope and requested review attributes stay unverified. A separate explicitly scoped query may provide its own identity evidence, never hidden creation verification.
+
+### Creation and find use different format grammars
+
+Installed CM 11 help documents creation `{0}` as ID and `{1}` as GUID. The positional formatter below completed in a fresh owned fixture:
+
+```text
+plastic_codeReviewCreate(target="br:/main/owned-feature", title="Owned formatted review", format="{0}|{1}", output="json")
+```
+
+The native receipt still reports observedCreatedIdentity=null for that custom format. A named `{id}|{title}` creation formatter failed with Invalid format string; no automatic substitution was performed.
+
+`cm find review` is different: the sourced fields `{id}|{status}|{title}` work, but a find `{guid}` field failed. Do not infer support from inconsistent help examples. The canonical tool [ids source](2026-10-06-discovery.md#codereviewfind) returns numeric IDs without attempting GUID/title/status recovery.
+
+## codeReviewUpdate
+
+```text
+plastic_codeReviewUpdate(id="<observed review ID>", status="Reviewed", output="json")
+```
+
+One exact `codereview -e` command preserves ID/selector plus optional status/assignee/repository. Empty optional review controls retain their existing omitted-flag behavior. No status enum redesign, assignment, readback or retry is added.
+
+An empty successful stdout means command completion, not verified requested state. In bounded fixtures, directly scoped observations still showed Under review after one requesting Reviewed update. The producer reports observedUpdatedState=null/effect not-proven; it does not infer cause, no-op, absence or eventual consistency.
+
+The agent may investigate the exact review and select a further authorized action. Uncertainty is not permission to repeat the mutation until an observation matches expectations.
+
+## Object deletion
+
+```text
+plastic_shelvesetDelete(shelveset="<explicitly owned exact selector>", preflight=true)
+plastic_codeReviewDelete(ids=["<explicitly owned ID>"], preflight=true)
+```
+
+Delete only when requested. Shelf deletion takes one scalar; review deletion preserves an ordered plural list, including duplicates, and optional exact repository spelling.
+
+Preflight is a zero-CLI command preview, not existence/permission/readiness proof. Completion does not establish deletion of any/all objects, namespace equivalence, restoration, exclusivity, history effects or rollback. Native errors/core rejection preserve possible-start/partial/capture uncertainty; no hidden query/retry follows.
+
+## Write/deletion bounds
+
+| Bound | Create/apply/update | Delete |
+|---|---|---|
+| Ordered operands | Up to 256 where lists are supported | 1 shelf /1–256 review IDs |
+| Controls | 4,096 UTF-16 code units | 4,096 UTF-16 code units |
+| Aggregate request | 32,768 UTF-8 bytes | 32,768 UTF-8 bytes |
+| Capture | 65,536 stdout /16384 stderr bytes |Same |
+| Compact receipt | 524,288 UTF-8 bytes | 131,072 UTF-8 bytes |
+
+Strict known keys, booleans, Unicode, list ownership and non-option operands are checked before dispatch. Explicit null, sparse/oversized lists, invalid modes and conflicting comments fail. Request/list snapshots precede await; aliases retain canonical precedence.
+
+Writes expose full admitted stdout as opaque command output. Only supported whole creation scalars become identity. Apply/update/repository observed-state fields remain null; scope requested-only/rollback not-proven. Unpaired Unicode and inconsistent overflow/truncation claims fail semantic validation.
+
+Shared retirement is the existing 30 second deadline plus bounded grace, not proof the process stopped. Failed applying calls can have effects; retained identity/partial effects survive uncertainty. See [safety and receipts](2026-10-06-safety-and-receipts.md#respond-to-failure-without-inventing-recovery).
+
+## Workflow references
+
+For operational guidance, load only [shelving](../skills/using-plastic/references/shelving.md) or [code-review creation](../skills/using-plastic/references/code-review-creation.md) when relevant. These remain package-local skill references, not instructions to create test fixtures, assign people or execute every example.

package/docs/2026-10-06-status.md

@@ -0,0 +1,116 @@
+# Status
+
+[Documentation index](README.md) · [Discovery](2026-10-06-discovery.md) · [Receipt semantics](2026-10-06-safety-and-receipts.md)
+
+`plastic_status` observes pending items or standard merge hints. Choose a source deliberately; unsupported/failed output is not retried in another mode.
+
+## Choose a source
+
+| Source | Select it with | Provides | Important boundary |
+|---|---|---|---|
+| Standard | Default, or `source="text"` | Short-output summary and text-derived merge hints | Read completeness unknown; not machine-verified conflict counts |
+| Machine | `machineReadable=true` or `source="machine"` | Parsed item rows, optional revision/source path, counts and diagnostics | Requested CLI scope, partial/lossy reads possible; no standard merge-state observation |
+| XML | `source="xml"` | Strict UTF-8 absolute pending paths and moved source paths | Opt-in workspace-wide snapshot; no base revisions; Windows CM 11 source validation |
+
+Tool-call examples:
+
+```text
+plastic_status(source="xml", maxItems=20)
+plastic_status(source="machine", maxItems=20, includeRevId=true)
+plastic_status(format="text")
+```
+
+`format="text"|"json"` changes presentation, not the native DTO. `source` is independent of presentation. Omitting `source` preserves `machineReadable` behavior.
+
+Conflicting controls fail before execution:
+
+- `source="text"` or `source="xml"` with `machineReadable=true`.
+- `source="machine"` with explicit `machineReadable=false`.
+- XML with `short=true` or `includeRevId=true`.
+
+## Common result fields
+
+Status declares `action="status"`. Standard/machine routes use `schemaVersion: 1`; XML uses `schemaVersion: 2`. Inspect `ok`, `completeness`, `data.mode`, diagnostics, summary basis, and returned/omitted counts.
+
+Rows default to 100 and cap at 500. Identity fields are excluded or rejected when unsupported, never clipped into plausible paths/revisions. A summary can describe more parsed records than the returned projection.
+
+| Concept | Meaning |
+|---|---|
+| `completeness.read` | Complete/incomplete/unknown source interpretation |
+| `completeness.capture` | Complete/unknown capture evidence for these routes |
+| `completeness.projection` | Whether the declared projection is complete |
+| Summary basis | Distinguishes parsed records from short-output classification |
+| Diagnostics | Evidence counters; a row can be both parsed and malformed/unsupported |
+
+A successful partial read is not a complete clean workspace. Native errors contain bounded sanitized code/message; unsupported CLI output is `command_failed`, not guessed capability absence.
+
+## XML
+
+XML yields `data.mode="xml"`, absolute CLI-observed paths, `pathBasis="absolute"`, and workspace-wide scope even when workdir is a subdirectory. Moved `Path` is the destination and `OldPath` is the source.
+
+- Supported codes: CH, AD, DE, LD, MV, PR; types: enTextFile/enDirectory.
+- Unsupported codes/types, duplicates, foreign/unknown important structures, malformed XML, warnings/errors, nonempty stderr, or command/capture failure reject the observation.
+- `baseRevisionAvailability="unavailable"`: changeset, size, and similarity never become per-item revisions.
+- Exact Unicode code points and emitted path spelling remain unchanged, including observed drive-letter case; no normalization/encoding guessing.
+- Text/JSON is synthesized from this one XML snapshot. No text/version commands are added.
+
+`@xmldom/xmldom` 0.9.12 parses strict application/xml, rejects warnings/errors, and conservatively rejects DTD/entity declaration tokens even in comments/CDATA. Literal U+FFFD is unsupported by the parser policy, not automatically evidence of CLI decoding loss. Numeric references use the same strict parser policy.
+
+`includeRaw=true` adds bounded, source-labelled XML to presentation only with a privacy warning. It may expose repository/server/workspace metadata; it never enters the compact native DTO.
+
+### XML bounds
+
+| Bound | Limit |
+|---|---|
+| Stdout/document | 1 MiB raw bytes |
+| Stderr | 64 KiB |
+| Process timeout | 30 seconds |
+| Element depth | 16 |
+| Source records | 20,000 |
+| Path/source path | 4,096 UTF-16 code units |
+| Status code | 64 code units |
+| Accumulated other scalar text | 8,192 code units |
+| Returned rows | 100 default, 500 maximum |
+| Compact DTO | 131,072 UTF-8 bytes |
+
+Invalid UTF-8, declaration/BOM disagreement, overflow, abort, or failed capture withholds reusable identities. Whole-document parsing is synchronous: depth/record/string checks follow DOM allocation and cancellation checks occur at parse boundaries, not midparse. The raw-byte cap bounds that phase; the process deadline is not a hard JS parser deadline.
+
+## Machine
+
+Machine yields `data.mode="machine"`, requestedShort, parsed-record summary, parse diagnostics, and itemCount. Rows include statusCode/kind/path/isDirectory and, when observed, decimal revisionId and moved sourcePath. Paths can be absolute; they are deliberately CLI-observed identities.
+
+- `parsed` counts all parsed records; returned/omitted/excluded/overCap describe projection and identity exclusions.
+- Summary totals precede projection. They are not independently verified workspace-wide counts.
+- Header repository/server identities, cwd, internal normalized paths, and raw output are not canonical DTO fields.
+- Recognized blank/header records are not pending items.
+- The CLI no-base revision `-1` is omitted, not reusable. Malformed tokens such as `41.5` withhold revision identity and make the read incomplete; a numeric prefix is never recovered.
+- Malformed/unsupported records or ambiguous legacy moves can produce a successful partial read, not complete status.
+- Successful stderr makes read/capture unknown without publishing stderr.
+
+### Encoding limitations
+
+U+FFFD in a path/source path causes exclusion from reusable identities and incomplete read. This also excludes literal replacement-character filenames because capture cannot distinguish them from loss.
+
+On Windows, `?` in identity-bearing paths is also excluded: the tested CM machine formatter substituted unsupported characters before capture. POSIX `?` filenames remain supported.
+
+The tested Windows client emitted OEM 437 bytes for some Latin text and replaced Japanese/emoji with `?`. `--encoding=utf-8` did not change that machine-output behavior; it is documented for XML. Streaming UTF-8 decoding preserves multibyte boundaries, but does not convert OEM bytes or recover originals. No XML fallback or general Windows Unicode round-trip guarantee is implied.
+
+### Machine bounds
+
+Paths: 4,096 characters; revision IDs: 128; status codes: 64; returned rows: 100 default/500 maximum; compact DTO: 131,072 UTF-8 bytes. Unsupported identity-bearing fields are excluded, not clipped. DTO overflow fails closed.
+
+Legacy machine/standard raw presentation (`includeRaw`, `details.rawResult`) and subprocess capture are not bounded by this DTO cap. Omit raw output for normal agent use. Text adds no version lookup; legacy JSON can use a cached `cm version` observation outside DTO provenance.
+
+## Standard
+
+Standard yields short-output classifications (`summaryBasis="short_output_classification"`) and text hints (`mergeHints.basis="text_hints"`). Counts include `other`; merge hints are not machine-verified conflict/readiness counts.
+
+Read completeness is unknown. Both existing status commands must succeed; there is no alternate-source fallback/retry. `requestedShort` describes requested scope, not unselected pending items.
+
+## Failures and follow-up
+
+Public codes include `command_failed`, `aborted`, `capture_incomplete`, `invalid_producer_data`, and `output_overflow`. XML schemaVersion 2 additionally emits `unsupported_source` for structurally valid but unadmitted record codes/types (including binary files), and `malformed_output` for invalid XML or observation-contract data. Parser bounds use `output_overflow`; transport truncation/timeouts use `capture_incomplete`. Unsupported records are not admitted or partially projected; malformed/unsafe data takes precedence over unsupported profiles. Errors expose only fixed messages/codes, not XML, record values or workdir paths, even with `includeRaw=true`.
+
+Parser rejections retain `read="incomplete"`, `capture="complete"`, `projection=false`: bytes were captured, not accepted as a complete read. Command/capture failures retain unknown capture. `invalid_producer_data` remains reserved for unexpected producer/internal DTO validation failures. This is an additive extension of the v2 error-code union (enum consumers must handle the new codes); v1 and successful v2 shapes are unchanged, and existing v2 error envelopes remain valid. Generic historical failures without retained XML do not establish a particular unsupported type. Inspect host-native rejection as well as DTO `ok`.
+
+Use the declared scope/completeness to choose a further authorized inspection. The separate strict XML/base protocol in [diff](2026-10-06-diffs-and-patches.md#loaded-bases-and-snapshots) is not a status-tool fallback; checkin and merge readiness have their own source admission.

package/docs/2026-10-06-tools-and-loading.md

@@ -0,0 +1,64 @@
+# Tools and loading
+
+[Documentation index](README.md) · [Tool-by-tool routing](README.md#look-up-a-tool)
+
+Pi Plastic registers **27 core tools** with output schemas, plus `plastic_tool_search`. The loader describes/activates capabilities and intentionally has no core receipt schema.
+
+## Capability loader
+
+When a tool is inactive, use the smallest sufficient capability search:
+
+```text
+plastic_tool_search(query="review pending changes")
+plastic_tool_search(toolNames=["plastic_patch"])
+```
+
+Matches are bounded, include workflow/safety guidance, and enable selected tools for the **next model request**. Activation is additive: it does not remove built-ins or other extensions' tools.
+
+| Controls | Meaning |
+|---|---|
+| `query` | Capability/workflow text |
+| `toolNames` | Up to four exact public tool names |
+| `limit` | 1–4 matches; default is the single best capability match |
+
+Use exact names only when you actually need those tools. Browsing the catalog does not require enabling everything. The [index](README.md#look-up-a-tool) maps every registered tool to its semantic reference.
+
+`plastic_workspaceCreate` is not registered or discoverable: the package does not yet provide the paired safe workspace-cleanup capability. It is not an alternative to the read-only `plastic_workspaceList` tool.
+
+## Loading modes
+
+Set `PI_PLASTIC_TOOL_LOADING_MODE` before starting Pi:
+
+| Mode | Initial package tools | Use |
+|---|---|---|
+| `balanced` | Loader, `plastic_status`, `plastic_currentBranch` | Default; inspect first and activate task capabilities as needed |
+| `loader-only` | Loader | Maximum initial schema reduction |
+| `all-active` | All 27 core tools; loader omitted from the active set | Controlled comparison or intentional full exposure |
+
+Inactive tools remain registered. Prior loader additions on the active session branch are restored on startup, resume, fork, and reload.
+
+## Ownership and fallback
+
+Pi's canonical `sourceInfo` identifies this package's effective tools before activation, deferral, or restoration.
+
+If ownership of the tools/loader cannot be established:
+
+- Preserve the existing active set exactly.
+- Do not defer, remove, or activate a same-named tool that could belong to another extension.
+- An effective package loader may report known tools already active, but cannot activate unowned inactive names.
+
+On a sourceInfo-capable host, providers without native deferred definitions still receive the current active set after a loader call. This is not a claim that every provider or RPC transport preserves every receipt.
+
+## Tool families
+
+| Family | Purpose |
+|---|---|
+| Status and discovery | Observe pending paths, branch paths/existence, workspace records, shelf IDs, review IDs |
+| Workspace operations | Add/undo/update/check in, create/delete/switch branches, request delete/change removal |
+| Merging | Workspace merge/finalization, server merge, staged branch closeout |
+| Diffs and patches | Compare explicitly scoped content or generate a review artifact—not patch application |
+| Shelvesets and reviews | Create/apply/delete shelvesets; create/update/delete code reviews |
+
+Use status to list changed paths. Use diff when content evidence is needed, not as routine ceremony. Use preflight only when scope is broad/ambiguous, a compound operation needs inspection, or the user asks for it; its meaning varies by tool.
+
+Read [safety and receipts](2026-10-06-safety-and-receipts.md) before chaining mutations. [Workflow skill references](../skills/using-plastic/SKILL.md) supply task-specific guidance; loading a tool is not authorization to mutate.

package/docs/2026-10-06-workspace-operations.md

@@ -0,0 +1,142 @@
+# Workspace operations
+
+[Documentation index](README.md) · [Safety and receipts](2026-10-06-safety-and-receipts.md) · [Merging](2026-10-06-merging.md)
+
+These tools act on explicitly requested workspace/branch scope. Command completion and resulting-state verification are separate. Prefer exact paths; broad directory/wildcard intent is not an exclusivity or containment guarantee for every operation.
+
+## Choose an operation
+
+| Tool | Intent | Receipt boundary |
+|---|---|---|
+| add | Add requested path operands | Added-item identity remains unverified |
+| update | Update with dontmerge/noinput | Changed items, branch/head, preservation and cleanliness unverified |
+| undo | Undo requested paths | Restored bytes, undone-item count and cleanliness unverified |
+| checkin | Check in selected pending work | Can admit an emitted root changeset; head/link/alias/Xlink/exhaustion unverified |
+| branchCreate | Create a hierarchical branch | Command completion, not observed created-branch identity |
+| branchDelete | Delete an exact branch | Command completion, not deletion/history/rollback proof |
+| switchBranch | Apply pending policy and switch | Ordered stage evidence; post-observation may remain uncertain |
+| resolveDeleteChangeConflict | Request source-side removal | Not verified conflict resolution or retention |
+
+Examples below are Pi tool calls and assume separately authorized mutation targets.
+
+## add
+
+```text
+plastic_add(paths=["Assets/Example.txt"])
+```
+
+One `cm add` attempt preserves ordered path expressions, duplicates, spaces/Unicode, relative/absolute paths, directories and requested wildcards. It does not rewrite or expand them in the producer.
+
+The array is not an option/stdin channel. Hyphen-leading or whitespace-prefixed switches and `-` are rejected; use `./-name` for a literal hyphen-leading filename. No automatic recursion/coparent/ignorefailed flags, containment inference, readback/retry/undo/checkin, format or preflight is added.
+
+Valid complete exit 0, including admitted warnings, establishes command-completed only. Requested operand count is not a verified added-item count; expanded/other-workspace/symlink/Xlink scope and preservation stay unverified. The separate internal checkin add path is unchanged.
+
+## update
+
+```text
+plastic_update()
+```
+
+Only workdir is accepted. Dispatch remains `cm update --dontmerge --noinput`, at most once, with no status/version/verification read or retry. No preview API is added.
+
+Complete exit 0, including admitted warnings, is not a verified no-op, changed-file list, workspace root, branch/head, preservation, cleanliness or merge readiness. Opaque progress is not returned as structured state. Failure stops dependent core closeout before merge/checkin.
+
+## undo
+
+```text
+plastic_undo(paths=["Assets/Example.txt"])
+```
+
+**Undo can irreversibly discard work.** The one-command path preserves exact requested expressions, ordering and duplicates. Broad paths/patterns do not certify exclusive scope.
+
+Reject CLI options/filters such as `--added`, `--unchanged`, `-r`, `--symlink`, whitespace-prefixed flags and stdin `-`. A filter without a path could imply destructive cwd-wide scope. Use `./-name` for a literal. No automatic filters/recursion/symlink/force flags, backup, preview/format, readback/retry or rollback.
+
+Even complete exit 0 cannot establish restored bytes, preservation or zero pending items. Choose independent scoped inspection when needed.
+
+## checkin
+
+```text
+plastic_checkin(paths=["Assets/Example.txt"], message="Implement feature", includeAll=false, includePrivate=false)
+```
+
+Inspect the declared selection defaults before omitting paths or enabling broad/private scope. `preflight=true` reads pending scope once and does not mutate; it is not a zero-command plan. `updateAfter` remains blocked before dispatch.
+
+The admitted Windows CM 11 source profile covers STATUS/pending and nonce-framed CI_START/STAGE/CO/AD/DE/MV/CHANGESET records, plus the narrow copied-path CP extension. Original Unicode, decimal-string changeset IDs, explicit branch prefixes and complete emitted server tails are preserved.
+
+Only one admitted root changeset on successful complete capture supports `changeset-created`. Empty output/exit 0 alone does not. Unknown/malformed/full-tail records, incomplete capture and invalid UTF-8 fail before projection.
+
+### Existing recovery, not general retry permission
+
+Eligible complete admitted failures may use the existing path fallback or sensitive-filtered private add/retry path. Timeout, abort, launch/capture uncertainty and unadmitted evidence never authorize retry.
+
+Per-step attempts/captures/effects retain successful earlier adds/checkins after later failure. Failed post/recovery reads stay null; even empty pending after failed checkin is not completion proof. Non-preflight core failures reject, preventing compound continuation based on a presentation string.
+
+### Checkin bounds
+
+At most 8 steps, 500 admitted source records per observation, one aggregate 100-reference projection budget with explicit omissions, 131,072-byte UTF-8 receipt and 24,000-byte presentation. Whole identity references cap 4,096 code units and are never trimmed into plausible selectors.
+
+## branchCreate
+
+```text
+plastic_branchCreate(branch="owned-feature", parent="/main")
+```
+
+Use an explicit parent independently of the loaded branch. If omitted, relative names require directly observed standard-status loaded branch; compact changeset-only status or a changeset-owner query cannot provide the parent.
+
+- Qualified relative names/parents are rejected rather than losing scope; use a full qualified hierarchical target.
+- Full hierarchical qualified targets remain verbatim.
+- Top-level creation requires explicit `allowRootBranch=true`.
+- A successful complete exit 0, even empty stdout, supports command completion with observedCreatedIdentity=null/effect not-proven.
+- No automatic switch, verification query or branch-create preflight is added.
+
+## branchDelete
+
+```text
+plastic_branchDelete(branch="/main/owned-feature", preflight=true)
+```
+
+One exact bounded branch operand and deleteChangesets policy are recorded. `deleteChangesets` defaults false; enable history deletion only with explicit intent. Preflight is a zero-CLI command plan, not existence/permission/readiness analysis. `format="text"|"json"` is presentation.
+
+Relative/qualified spelling is preserved; options/stdin/unsafe text are rejected. Complete exit 0 does not prove deleted branch identity, history effects, scope or rollback. Possible-start/nonzero/incomplete failures remain uncertain, with no query, retry or switch-back. Core non-preflight failures reject.
+
+## switchBranch
+
+```text
+plastic_switchBranch(branch="/main/owned-feature", pendingChanges="cancel", preflight=true)
+```
+
+The closed v1 receipt distinguishes preflight, already-loaded, canceled, blocked, switched, command-completed-unverified, failed and uncertain. Earlier shelf/switch completion and possible effects remain after later failure; shelveset identity, preservation, alias equivalence, Xlink results and rollback are not invented.
+
+Admission requires directly observed standard loaded branch and strict complete pending evidence. Compact changeset ownership is not a loaded branch; malformed/lossy/skipped pending rows never mean clean.
+
+Targets are bounded hierarchical selectors. Already-loaded comparison requires exact branch and, if requested, exact repository/server spelling. A completed switch with failed/mismatched post-read or unverified qualification returns an error retaining completion—not verified switched.
+
+### Pending policies
+
+- Tracked bring is blocked; explicit cancel with pending is canceled.
+- Private-only/defaulted cancel, bring, or shelve can switch directly without a shelf under the existing policy.
+- Tracked shelve creates a shelf then uses silent/noinput switch.
+- Recovery is limited to the complete exit 1 empty-stdout workspace-specific no-changes error plus an admitted read proving no tracked pending. Failed recovery stops, never substitutes empty.
+- Failed shelving retains uncertain preservation even if recovery observes the target. No automatic undo, shelf apply/delete, update/checkin or switch-back follows.
+
+Preflight performs 2 local reads. Direct application uses 4 commands, shelving 5, eligible recovery at most 6; observations are not atomic. Pending capture: 1 MiB stdout/64 KiB stderr, 20,000 records. Other steps: 64 KiB/16 KiB. Receipt: 6 steps/131072 UTF-8 bytes; identities 4,096 code units and admitted standard-header grammar.
+
+## resolveDeleteChangeConflict
+
+```text
+plastic_resolveDeleteChangeConflict(paths=["Assets/Example.txt"], keepOnDisk=true, preflight=true)
+```
+
+One `cm remove [--nodisk] <operands...>` requests source-side deletion. `keepOnDisk=true` is the default; explicit false omits nodisk and permits disk deletion. Requested retention is not a preservation guarantee, and requested operand count is not a resolved-item count.
+
+Directory removal is recursive under client defaults. Deliberate directories/wildcards/absolute operands do not certify exclusive scope, containment, symlink, other-workspace or Xlink effects. No automatic flags/expansion/backup/readback or merge continuation.
+
+Reject option/stdin operands and bare case-insensitive, outer-whitespace `private`/`controlled` mode tokens anywhere. For literal names use `./private`, `./controlled`, `./-name`, or a full path. Preflight is zero CLI; format selects text/JSON. Completed output, including admitted warnings, proves remove completion only; resolution/items/preservation/pending/workspace facts remain null.
+
+## Shared capture and input limits
+
+Add/undo/remove path lists: 1–256 operands, 4,096 UTF-16 code units each, 32,768 aggregate UTF-8 operand bytes; workdir 4096. Branch/checkin controls have their own aggregate schema/argv gates; see the loaded schema and operation-specific bounds above.
+
+Selected single-command captures retain 64 KiB stdout/16 KiB stderr with fatal UTF-8/BOM preserved. Nominal retirement is 30 seconds plus 5 seconds TERM→KILL grace and at most 5 seconds additional drain. Earlier abort/capture failure can initiate that grace sooner. Retirement preserves genuine observed lifecycle facts but is not process-stop or rollback proof.
+
+Nonzero/partial/invalid-UTF-8/overflow/abort/missing-terminal outcomes remain failed/uncertain as declared. Core failures reject, while native failures return their receipt. Legacy read and internal collectors are not globally migrated by these bounds. See [transport limitations](2026-10-06-development.md#structured-api-and-transport) for SDK normalization and foreign-hook behavior.

package/docs/README.md

@@ -0,0 +1,65 @@
+# Pi Plastic documentation
+
+[Package overview](../README.md) · [Workflow skill](../skills/using-plastic/SKILL.md)
+
+This is the public manual shipped with the package. Start with a task, then read only the relevant tool family. Topic filenames keep their creation-date prefix; the titles below are the navigation surface.
+
+## Choose a task
+
+| I want to… | Read |
+|---|---|
+| Install or update the package; configure CM/diff | [Setup](2026-10-06-setup.md) |
+| Enable a capability without loading every tool | [Tools and loading](2026-10-06-tools-and-loading.md#loading-modes) |
+| Understand what a result proves, or respond to uncertainty | [Safety and receipts](2026-10-06-safety-and-receipts.md) |
+| Inspect pending paths and merge hints | [Status](2026-10-06-status.md) |
+| Find branches, workspaces, shelvesets, or review IDs | [Discovery](2026-10-06-discovery.md) |
+| Add/undo/check in files, switch branches, create/delete a branch | [Workspace operations](2026-10-06-workspace-operations.md) |
+| Choose workspace merge versus server merge versus closeout | [Merging](2026-10-06-merging.md#choose-a-route) |
+| Review local/historical changes or generate a patch | [Diffs and patches](2026-10-06-diffs-and-patches.md) |
+| Save/apply/delete a shelf or manage a review | [Shelvesets and reviews](2026-10-06-shelvesets-and-reviews.md) |
+| Understand display, footer, or ignore/cloak behavior | [Integrations](2026-10-06-integrations.md) |
+| Run tests, understand schema/transport behavior, or change the package | [Development](2026-10-06-development.md) |
+
+## Look up a tool
+
+Argument descriptions in the loaded tool schema are the source for exact call parameters. The pages below explain semantics, defaults, bounds, and follow-up decisions; they are not alternate parsers or automatic recovery instructions.
+
+| Tool | Reference |
+|---|---|
+| `plastic_tool_search` | [Tools and loading](2026-10-06-tools-and-loading.md#capability-loader) |
+| `plastic_status` | [Status sources](2026-10-06-status.md#choose-a-source) |
+| `plastic_currentBranch` | [Current branch](2026-10-06-discovery.md#currentbranch) |
+| `plastic_branchExists` | [Branch existence](2026-10-06-discovery.md#branchexists) |
+| `plastic_branchList` | [Branch list](2026-10-06-discovery.md#branchlist) |
+| `plastic_workspaceList` | [Workspace list](2026-10-06-discovery.md#workspacelist) |
+| `plastic_shelvesetList` | [Shelveset IDs](2026-10-06-discovery.md#shelvesetlist) |
+| `plastic_codeReviewFind` | [Review IDs](2026-10-06-discovery.md#codereviewfind) |
+| `plastic_add` | [Add](2026-10-06-workspace-operations.md#add) |
+| `plastic_update` | [Update](2026-10-06-workspace-operations.md#update) |
+| `plastic_undo` | [Undo](2026-10-06-workspace-operations.md#undo) |
+| `plastic_checkin` | [Checkin](2026-10-06-workspace-operations.md#checkin) |
+| `plastic_branchCreate` | [Branch creation](2026-10-06-workspace-operations.md#branchcreate) |
+| `plastic_branchDelete` | [Branch deletion](2026-10-06-workspace-operations.md#branchdelete) |
+| `plastic_switchBranch` | [Switching](2026-10-06-workspace-operations.md#switchbranch) |
+| `plastic_resolveDeleteChangeConflict` | [Delete/change removal](2026-10-06-workspace-operations.md#resolvedeletechangeconflict) |
+| `plastic_merge` | [Workspace merge](2026-10-06-merging.md#merge-and-finalizemerge) |
+| `plastic_finalizeMerge` | [Finalization](2026-10-06-merging.md#merge-and-finalizemerge) |
+| `plastic_mergeBranches` | [Server merge](2026-10-06-merging.md#mergebranches) |
+| `plastic_mergeToBranch` | [Closeout](2026-10-06-merging.md#mergetobranch) |
+| `plastic_diff` | [Diff modes](2026-10-06-diffs-and-patches.md#diff-modes) |
+| `plastic_patch` | [Patch generation](2026-10-06-diffs-and-patches.md#patch-generation) |
+| `plastic_shelvesetCreate` | [Shelf creation](2026-10-06-shelvesets-and-reviews.md#shelvesetcreate) |
+| `plastic_shelvesetApply` | [Shelf application](2026-10-06-shelvesets-and-reviews.md#shelvesetapply) |
+| `plastic_shelvesetDelete` | [Object deletion](2026-10-06-shelvesets-and-reviews.md#object-deletion) |
+| `plastic_codeReviewCreate` | [Review creation](2026-10-06-shelvesets-and-reviews.md#codereviewcreate) |
+| `plastic_codeReviewUpdate` | [Review update](2026-10-06-shelvesets-and-reviews.md#codereviewupdate) |
+| `plastic_codeReviewDelete` | [Object deletion](2026-10-06-shelvesets-and-reviews.md#object-deletion) |
+
+## Reading results as an agent
+
+1. Load the smallest sufficient capability through `plastic_tool_search` when it is inactive.
+2. Read the tool schema and only the relevant reference section. Use [the workflow skill](../skills/using-plastic/SKILL.md) when the task calls for operational guidance.
+3. Use structured output where available. Inspect `ok`, completeness, scope, effects, and any unattempted stages; don't recover facts by scraping presentation text.
+4. Choose further read-only inspection or an authorized resolution when evidence is incomplete. A failed command may have effects; uncertainty is not permission to replay it.
+
+The package does not automatically load this manual into every agent context. The same-package links are readable relative to the installed skill/package, without a separate reference-reader dependency.

package/extensions/bash-cm-diff-guard.ts

@@ -6,7 +6,7 @@ import {
 } from "./shared/bash-command-guards";
 
 const BLOCK_MESSAGE =
-  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` when only changed paths are needed. Do not diff routinely; when change-boundary evidence is necessary, use a focused `plastic_diffFile`, explicitly scoped `plastic_workspaceDiff`, or `plastic_diffRevisions`.";
+  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` when only changed paths are needed. Do not diff routinely; when change-boundary evidence is necessary, use `plastic_diff` with explicit mode=file, revisions, or workspace and bounded scope.";
 
 const CM_EXECUTABLE = String.raw`(?:"(?:[^"]*[\\/])?cm(?:\.exe)?"|'(?:[^']*[\\/])?cm(?:\.exe)?'|(?:[^"'\s]*[\\/])?cm(?:\.exe)?)`;
 const DIFF_SUBCOMMAND = String.raw`(?:diff|differences)`;