@aefree/pi-plastic 0.7.6 → 0.8.1

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

@@ -0,0 +1,135 @@
+# Branch, workspace, and object discovery
+
+[Documentation index](README.md) · [Status](2026-10-06-status.md) · [Safety and receipts](2026-10-06-safety-and-receipts.md)
+
+Use an explicit structured source when you need reusable rows. Native/custom tables remain presentation rather than parsed identity evidence. Query filters describe requested scope—not returned metadata or verified ordering.
+
+## Choose a source
+
+| Tool | Default | Structured source | Row identity / scope |
+|---|---|---|---|
+| `plastic_currentBranch` | Direct branch resolution | No extra source selector | Exact unqualified branch path / workspace |
+| `plastic_branchExists` | Leaf query plus full-path comparison | No extra source selector | Path existence / workspace repository |
+| `plastic_branchList` | `source="native"` | `source="names"` | Unqualified branch paths / workspace repository |
+| `plastic_workspaceList` | `source="native"` | `source="fields"` | Name/path/GUID / local client inventory, with ASCII prerequisite |
+| `plastic_shelvesetList` | `source="native"` | `source="ids"` | Decimal ID and unqualified sh selector / workspace repository |
+| `plastic_codeReviewFind` | `source="native"` | `source="ids"` | Decimal ID / workspace repository |
+
+Structured list projections default to 100 rows and cap at 500. The optional CLI `limit` is separate; it does not prove repository totals or exhaustion. The entire captured structured response is validated before projection, including omitted rows.
+
+## currentBranch
+
+`action="current-branch"` returns the exact observed unqualified branch and basis `status`, `compact_status`, or `changeset_lookup`. No repository/server selector is invented.
+
+Resolution follows the existing supported ladder: status; compact status only when normal output lacks a branch; changeset query only when compact output observes one changeset. Failure, cancellation, truncated/ambiguous/lossy output never authorizes another step.
+
+Delimited paths retain spaces. Unsupported embedded selectors fail rather than shorten at whitespace. Core string output remains available; `format` changes presentation only, with legacy JSON's cached version observation outside DTO provenance.
+
+## branchExists
+
+`action="branch-exists"` returns exists, requestedBranch, comparisonBranch, and scope `workspace_repository`.
+
+- The leaf query is not identity: exact full-path comparison prevents `/other/test` from proving `/main/test`.
+- Valid empty query output means false in that scope. Malformed/skipped/duplicate/unexpected rows, stderr uncertainty, and failures are errors—not verified false.
+- Existing comparison removes `br:` and normalizes backslashes; relative inputs are compared literally, not expanded.
+- Qualified input still has `qualifierVerified=false`, even when exists=true. It proves path existence in the workspace repository, not existence in the requested foreign repository/server.
+- Core output remains `"true"`/`"false"`; no format argument is added.
+
+### Scalar read bounds
+
+Identities: 4,096 characters; compact DTO: 16,384 UTF-8 bytes. Invalid/lossy/oversized Unicode identities fail rather than clip. U+FFFD and Windows `?` substitutions are rejected. Deterministic UTF-8 transport handles valid Unicode, but general live Windows/OEM round-trip support remains unverified. No XML/encoding fallback is added; legacy raw presentation/capture is outside the DTO cap.
+
+Scalar failures withhold data and use sanitized codes such as command_failed, aborted, capture_incomplete, invalid_identity, malformed_output, invalid_producer_data, output_overflow.
+
+## branchList
+
+`source="names"` uses one `find branch … --nototal --format={name} --encoding=utf-8` response. Returned branches are exact unqualified hierarchical names; no metadata/version query or source fallback follows.
+
+| Control or result | Meaning |
+|---|---|
+| `nameLike` | Filters the leaf, not full hierarchical identity |
+| Parent/query qualifiers | Preserved request; not cross-repository verification |
+| `descending` | Ignored without orderBy, preserving existing behavior |
+| `includeHidden=true` | Rejected before execution for names; native retains the existing expression |
+| Counts | Observed captured rows, returned/omitted projection, excluded=0 |
+
+Names requires slash-rooted nonempty components and exact UTF-8, LF/CRLF, at most one terminal newline. Qualifiers, backslashes, controls, lone surrogates, U+FFFD, Windows `?`, blank/junk rows, duplicates and invalid identities fail the whole response. Paired emoji are retained. CLI collation/order is preserved without a stable tie-breaker.
+
+The hidden-query restriction is based on anomalous installed-client source behavior; it is not repaired by rewriting the query. Installed CM disallows apostrophe/newline/CR in branch leaf names; unsupported query escaping is not substituted.
+
+```js
+const dto = await tools.plastic_branchList({source: "names", nameLike: "feature%", maxItems: 20});
+text(dto.ok && dto.data.mode === "names"
+  ? {branches: dto.data.rows.map(row => row.branch), counts: dto.data.counts}
+  : dto.ok ? {rowsUnavailable: true} : dto.error);
+```
+
+Native/default preserves tables, predicates, ordering/limit and `(no output)`. Rows/counts are null, read/capture unknown, projection false; native table identities/counts are not parsed. `format="text"|"json"` is presentation, not source.
+
+## workspaceList
+
+**Fields requires independently known ASCII-only original names and paths in the entire selected local client inventory.** ASCII-looking formatter output alone is insufficient: CM can best-fit unsupported originals into printable ASCII or replace them with question marks.
+
+Use `source="fields"` only under that configuration prerequisite. The receipt records the prerequisite and lack of independent original verification; source acceptance is limited to the tested Windows CM 11 configuration.
+
+Fields uses one `workspace list` response with wkname, machine, path and wkid separated by tabs. No encoding/XML flags, registry-read producer, second snapshot or per-workspace lookup.
+
+- Publish exact name/absolute path/GUID spelling. The machine field is parse-checked but not published as verified metadata.
+- Scope is local_client_inventory, not the current repository, all users, or machine-wide inventory.
+- Paths are producer_absolute syntax, not filesystem/platform verification.
+- Counts are observed records, not unique workspaces or inventory exhaustion.
+- Exact repeated four-field records remain in order; duplicateRecords covers the whole response. Conflicting reuse of GUID/name/path, including different unpublished machine fields, rejects the read.
+
+Non-ASCII bytes, `?` identity fields, controls/BOM, blank/junk/wrong-field records, nonabsolute paths, invalid GUIDs or overflow fail with no partial reusable rows.
+
+`format` is an arbitrary native CLI template; `output="text"|"json"` selects presentation separately. Meaningful custom format conflicts with fields; empty format keeps its ignored meaning. Native JSON retains its legacy version cache/wrapper and presentation line counts, not canonical workspace counts.
+
+## shelvesetList
+
+`source="ids"` uses one `find shelve … --nototal --format={shelveid} --encoding=utf-8` response.
+
+Rows contain decimal string id and unqualified `sh:<id>` selector. Reuse only in the same workspace-repository context; qualifierVerified=false and no repository/server alias is inferred. Owner/comment/date are requested predicates, not returned metadata or Unicode-rendering guarantees.
+
+Exact repeated IDs remain in order, with full-response duplicate diagnostics. Counts describe observed records, not unique shelvesets, repository totals, or exhaustion.
+
+`format` and `dateFormat` are native CLI templates; `output` selects text/JSON independently. Meaningful templates conflict with ids; empty strings retain ignored behavior. Native rows/counts stay null and read/capture unknown rather than table-derived facts. Native text/error and `(no output)` behavior remain available; JSON contains the noncanonical native envelope without a new metadata query.
+
+## codeReviewFind
+
+`source="ids"` uses one `find review … --nototal --format={id} --encoding=utf-8` response. IDs are decimal strings, not JS numbers; no GUID, invented prefix, qualification, target/title/status/owner/assignee is recovered. Reuse only within workspace_repository scope; qualifierVerified=false.
+
+Existing filters, escaping, sort fields date/modifieddate/status, ascending/descending, CLI limit and aliases remain. Descending without an order field retains ignored behavior. Query fields record intent, not verified metadata or sort correctness.
+
+Meaningful native `format`/`dateFormat` conflicts with ids; empty strings retain ignored behavior. `output` is independent presentation. Native JSON retains its fenced wrapper/cached first-version lookup and presentation-only resultCount; those are not canonical ID/count evidence. Canonical IDs JSON uses the same DTO without that metadata command.
+
+```js
+const dto = await tools.plastic_codeReviewFind({source: "ids", assignee: "me", maxItems: 20});
+text(dto.ok && dto.data.mode === "ids"
+  ? {ids: dto.data.rows.map(row => row.id), counts: dto.data.counts}
+  : dto.ok ? {rowsUnavailable: true} : dto.error);
+```
+
+## List grammar and bounds
+
+Structured sources never infer empty rows from a failed command. Genuine accepted empty queries produce []/0; malformed/oversized sources return errors without reusable partial identities.
+
+| Bound | names / fields / ids sources |
+|---|---|
+| Query strings/native templates and path/name identities | 4,096 UTF-16 code units |
+| Decimal ID strings | 20 digits; canonical nonnegative grammar |
+| Stdout / stderr | 1 MiB /64 KiB |
+| Source records | 20,000 |
+| Process timeout | 30 seconds; operation collector escalation applies |
+| Returned rows | 100 default /500 max |
+| Compact DTO | 131,072 UTF-8 bytes |
+| Public error message | 256 characters max |
+
+IDs accept LF/CRLF and one terminal newline without trimming. Foreign/header/blank/negative/fractional/leading-zero/non-ASCII/overlong records fail, including omitted rows. Exact repeats remain for IDs/fields; branch-name duplicates fail. Nonempty stderr, invalid bytes, cancellation, timeout and capture failure reject canonical source admission. Synchronous bounded parsing has boundary abort checks, not a hard JS deadline.
+
+Native/custom routes retain legacy raw-presentation/capture limits; the structured table bounds above do not retroactively bound them. [Foreign hooks/RPC limits](2026-10-06-safety-and-receipts.md#evidence-and-transport-limits) also apply.
+
+## Validation scope
+
+Branch-name original/raw/registered equality was live-verified for spaces and several Unicode forms on Windows CM 11.0.16.10371, from root and subdirectory. Workspace fields requires its ASCII prerequisite; scalar Windows Unicode is not generally established.
+
+Shelf/review canonical-ID source live validation covered clean empty queries. Later creation/update/deletion fixtures and external title queries do **not** establish native populated-list equality for these tools. Deterministic tests cover positive rows, grammar, precision, bounds, projection and SDK consumers. No universal platform/client/populated-inventory proof is implied.

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

@@ -0,0 +1,49 @@
+# Pi integrations
+
+[Documentation index](README.md) · [Setup](2026-10-06-setup.md) · [Receipt semantics](2026-10-06-safety-and-receipts.md)
+
+These integrations improve presentation and discovery. They don't change the underlying mutation result into a stronger guarantee.
+
+## Tool displays
+
+Compact action headers appear inside Pi's standard tool boxes. They show workspace and the relevant branch/file/revision pair/query; command previews are labelled.
+
+Collapsed results expose structured counts, comparison availability, patch artifacts, merge outcomes, blocked checkins, omitted results and unresolved effects. Plain CLI output stays neutral rather than implying verified mutation.
+
+Expand with the configured Pi tool-expansion shortcut for request/workspace context, colored diff hunks and returned evidence. Rendering preserves JSON identifiers and numeric text, masks common credential assignments and removes terminal control sequences. It does not alter execution/model-facing output or scan arbitrary source for secrets.
+
+In a checkout, `npm run preview:tools` provides offline examples. The preview uses plain colors and a test binding; live Pi supplies the theme, box and configured shortcut.
+
+## Plastic branch footer
+
+Inside a Plastic workspace, Pi adds a themed `Plastic <branch>` footer status. It finds the nearest `.plastic/plastic.workspace` and reads smartbranch/br selector forms as the credential-free source. A bounded `cm status` is used only when the selector lacks a valid branch.
+
+Selector changes and successful same-workspace Plastic tools refresh the status; sibling workspaces are ignored.
+
+| State | Display |
+|---|---|
+| Observed branch | Plastic branch status |
+| Plastic marker but no selector/CM branch | Plastic branch unavailable |
+| No Plastic workspace | No Plastic status |
+
+The extension owns only the plastic-branch status key. It does not replace Pi's footer or suppress Git status; both can appear in nested workspaces.
+
+## File-discovery filter
+
+When independently loaded `@aefree/pi-file-discovery` is present, session startup registers the advisory plastic.ignore-files filter through the package-qualified capability-registry rendezvous key. Separate package module roots are supported; Plastic does not import a sibling package instance from its own root.
+
+For each requested root, the filter reads ignore.conf/cloaked.conf only from its nearest Plastic workspace and supplies readable files as ripgrep ignores, without replacing native ripgrep/Git-ignore behavior.
+
+- Effective records declare filterDecision applied, decision code plastic_ignore_files_applied, and the workspace filterBoundary.
+- A root is emitted only with at least one readable ignore/cloak file.
+- No-op roots are omitted from mixed requests; no effective records means not_applicable.
+- Missing/malformed/unavailable data degrades to generic discovery. The discovery package owns execution hygiene/disclosure.
+- No workflow guidance or Plastic readiness query is registered by this filter.
+
+Without file discovery, Plastic tools and the skill still load; no filter registry is created. This advisory filter is not an access-control boundary or proof that excluded files are inaccessible.
+
+## Bash guards
+
+The declared diff and merge guard extensions block GUI diff/differences and unsafe interactive merge commands. They apply only in Pi processes that actually load them, not arbitrary shells or children that resolve different project settings.
+
+Use user-scope installation when children in arbitrary workspaces must inherit them. Restart processes after installation/source changes. Mutating Plastic tools still have operation-specific guards and [authorization/receipt requirements](2026-10-06-safety-and-receipts.md#mutation-authorization-and-preflight); presentation/guards are not a universal sandbox.

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

@@ -0,0 +1,153 @@
+# Merging and closeout
+
+[Documentation index](README.md) · [Safety and receipts](2026-10-06-safety-and-receipts.md) · [Workspace operations](2026-10-06-workspace-operations.md)
+
+Plastic merges are workspace/branch operations, not Git fast-forwards. A merge checkin belongs to the loaded target branch; switching afterward does not move or integrate a source-branch checkin.
+
+## Choose a route
+
+| Tool | Use | Boundary |
+|---|---|---|
+| `plastic_merge` | Apply a noninteractive merge to the loaded workspace | Applying completion and admitted readiness are separate |
+| `plastic_finalizeMerge` | Explicitly finalize merge metadata under a reviewed policy | Not a guarantee of preserving manual resolution |
+| `plastic_mergeToBranch` | Resolve target, switch/update/merge/check readiness/check in | Typed ordered ledger; unknown target/readiness stops before checkin |
+| `plastic_mergeBranches` | Workspace-free server-side merge | Same exact requested repository/server; no workspace fallback |
+
+Don't substitute one route for another after failure without a new authorized decision. Command-only preflight does not analyze conflicts; closeout preflight actually performs read-only discovery/pending work.
+
+## merge and finalizeMerge
+
+The closed producer receipts distinguish applying-command completion from overall outcome/readiness. Core text/JSON derives from the same observation; no version/formatting reads.
+
+| Control | Preserved behavior |
+|---|---|
+| Merge strategy | Default auto/try; source/destination preferences are explicit policies |
+| Finalization | Default forced destination preference; not preserved-manual-edit/conflict-resolution proof |
+| Source selectors | Exact branch/changeset/label/shelve spelling, qualified or unqualified |
+| Preflight | Zero-command plan, not conflict/readiness analysis |
+
+Strict bounded inputs reject source-as-option/stdin, unsafe Unicode and unknown controls. Source/workdir cap 4,096 code units; aliases keep canonical precedence.
+
+At most one applying merge. Supported output can be followed by separately recorded short/full status reads. File-conflict records block. Exit 0 followed by failed/unsupported reads can retain commandCompleted=true with overall ok=false/uncertain and unknown readiness.
+
+No swallowed read failure, raw diagnostic facts, retry, strategy switch, export/backup/version query or rollback. Possible-start failure never proves absent effects or safe replay. Unobserved source/workspace identity, pending items, finalized metadata and preservation stay null.
+
+### Admitted readiness profiles
+
+Windows CM 11.0.16.10371 source admission is narrow:
+
+- Exact nonce-framed STATUS/ALREADY_CONNECTED, FILE_CONFLICT, APPLY/ADD and paired DO_COPIED records.
+- Empty profile: successful complete empty short status plus exact header-only standard status and no stderr.
+- Copied-add profile: paired applying paths, CP-only pending records and machine/full-status correlation; up to 128 files under unchanged byte/frame limits and one merge changeset.
+
+Unknown/mixed/malformed/empty applying output, other rich operations, unsupported localization, unrelated pending changes or merge links stop as unknown—not zero conflicts or rollback. Core rejection and independent closeout post-read gates prevent checkin on unknown readiness.
+
+`supported-no-unresolved-signals` is point-in-time admitted evidence, not transaction finality, target-head/source-link/exclusivity/other-workspace/Xlink proof. The agent may inspect and choose a supported resolution; the tool doesn't force one.
+
+## mergeToBranch
+
+```text
+plastic_mergeToBranch(source="/main/owned-feature", target="/main", message="Merge owned feature", preflight=true)
+```
+
+The ordered ledger can include discovery, pending reads, switch, optional update, merge, readiness, checkin and final observations. Inspect stages, outcome, completeness and unattemptedStages before proceeding. Unattempted stages include deliberate omissions as well as stopped steps.
+
+- Source defaults only from directly observed loaded workspace.
+- Target defaults only from an admitted source-parent observation.
+- Branch inputs are bounded hierarchical selectors; changeset/label/shelve/flag operands are not closeout branches.
+- Exact qualified spelling is retained. Different repository/server spellings, including unverified aliases, stop before target mutation.
+- Loaded target is independently checked before merge/checkin; final branch mismatch is an error. Unqualified targets can have name-only workspace-context verification, not globally qualified identity proof.
+- No child text/fenced JSON is parsed, operation replayed, or raw diagnostic copied as facts.
+- A checkin identity remains recorded if final target/pending evidence fails.
+
+### Parent discovery
+
+The installed client filters `name` by leaf but emits full hierarchy in `{name}|{parent}`. One query uses leaf equality, branchname ordering and limit 2 before the optional exact repository clause.
+
+Only one matching full-source/direct-parent row is admitted. Two rows mean ambiguity; empty rows are not proof of branch absence. Warning/failure/malformed/root/unrelated-parent output stops without alternate queries or lexical parent guessing. The discovered target still requires loaded-target verification.
+
+### Investigating unknown readiness
+
+`unsupported_readiness` is not an applying-command failure or rollback receipt. Inspect `commandCompleted`, capture completeness, `protocol` and each stage admission. Diagnostics distinguish unsupported applying output, applying warnings, pending/path correlation and full-status correlation. Stop checkin and do not automatically reapply the merge. Use separately authorized read-only inspection to establish current pending/conflict state; retain sanitized producer evidence for unsupported-profile analysis and verify the package revision actually loaded by the process (a source checkout alone is not proof).
+
+Copied-add admission does not admit mixed replace/delete profiles. A synthetic historical-shape regression proves the supported DO_COPIED/ADD/CP path, not historical recovery: unavailable historical producer bytes and uncertain/stale runtime loads remain unresolved.
+
+### Readiness and message admission
+
+Independent readiness requires complete successful capture, empty stderr, and an admitted header-only standard snapshot or the strict copied profile. Copied admission uses machine pending instead of the first standalone short read, then correlates full pending-link/Added/copied sections with requested source, namespace, changeset/merge metadata and paths. Volatile size/time display is opaque. Unknown/mixed/directory/duplicate/out-of-workspace records remain unsupported; CP selection keeps its CP code while using added kind locally in checkin. Final pending observations are typed and admitted, never swallowed into zero.
+
+Existing message/card trimming and explicit-message precedence remain. Derived messages must satisfy the checkin owner's text/4, 096-unit bounds before target mutation. A card-only default inserts newlines rejected by that owner; supply an admitted explicit message instead. This is a current restriction, not permission to widen checkin text admission or silently drop the card.
+
+### Defaults and bounds
+
+| Setting / bound | Value |
+|---|---|
+| Strategy | auto |
+| Update target | true |
+| Include private | false |
+| Pending switch policy | cancel |
+| Source / target / workdir controls | 4,096 UTF-16 code units |
+| Request | 32,768 UTF-8 bytes |
+| Ledger | 16 stages; up to 5 full child receipts and 11 compact reads |
+| DTO | 1 MiB UTF-8 bytes |
+
+Preflight is read-only discovery/pending preview, not zero CLI or applying-readiness proof. Selected reads use 64 KiB stdout/16 KiB stderr and nominal 30+5+5-second retirement; child operation limits/recovery rules remain in force. No compound retry/undo/switch-back/strategy change, rollback/exclusivity or guaranteed aggregate deadline is added.
+
+## mergeBranches
+
+This route has no workspace mutation/fallback. Supply distinct fully qualified source/target branches in the same exact requested repository/server. The default `mode="apply"` requires a nonempty message; `mode="analyze"` is read-only remote conflict discovery and rejects a message, resolution file or conflict policy.
+
+```text
+plastic_mergeBranches(source="br:/main/source@Example Repository@example@unity", target="br:/main/target@Example Repository@example@unity", message="Merge source", preflight=true)
+```
+
+Inputs allow unambiguous `br:/branch@repository@server`, including literal host or full cloud/unity server suffix. Each control caps 4,096 UTF-16 code units. Workdir, unknown controls, malformed Unicode, and `@` inside branch/repository are rejected. Absolute local resolution-input paths are preserved, not trimmed or rewritten.
+
+| Outcome/evidence | Interpretation |
+|---|---|
+| Preflight | Zero CLI; validates supplied local inputs and renders command intent, not remote conflicts |
+| Analyzed | Complete supported point-in-time remote output; no applying command or contributor export |
+| Completed | Complete normal exit emitted exactly one matching branch/repository/root-mount changeset |
+| No-op / ALREADY_CONNECTED | Classification with effect not-proven; not independently verified unchanged state |
+| Conflict / unsupported / uncertain / failed | Stop; possible effects are not ruled out |
+
+Applying performs one local help syntax check and at most one noninteractive server merge. Exact decimal ID/emitted server qualifier remain separate from requested server spelling; alias equivalence is unverified.
+
+No source-link/head-exclusive/global/Xlink/rollback proof, retries, head unification or shelveset mode. Undetected server-side Xlink effects remain possible; accepting a full xlink conflict path does not verify linked-repository ownership or effects.
+
+### Agent conflict-resolution workflow
+
+1. **Inspect:** call `mode="analyze"` to execute `cm merge <source> --to=<target>` without `--merge`. Unlike `preflight`, this contacts the server. Read `conflictPaths`, parse/capture completeness and omission counts. Empty, malformed, unknown-operation (including directory-conflict), warning or failed output remains uncertain, not a clean merge. `analyzed` means a supported observation, not absence of conflicts.
+2. **Understand contributors:** independently inspect base/source/destination for each conflict. The exact destination conflict path is usable as a resolution key, not a workspace path. This tool does not retrieve content or assign meanings to the numeric FILE_CONFLICT fields. If needed, use a read-only `cm merge <qualified-source> --to=<qualified-target> --printcontributors` inspection, without `--merge`, to establish contributor identities. Use `plastic_diff(mode="revisions", ...)` for deliberate comparisons after verifying file/repository/server-qualified selectors. For full bytes unavailable through typed tools, follow the [historical export fallback](../skills/using-plastic/references/changeset-operations.md#historical-export-fallback): fresh external temporary destinations only, never canonical workspace files or guessed revision IDs. Writable xlinks need independently verified linked-repository identities; do not qualify their revision IDs against the root repository by assumption.
+3. **Resolve and validate:** write merged content into new local result files outside the workspace; preserve immutable contributor baselines. Review the result and run relevant validation before submission. Binary files may use `keep`, but choosing a side deliberately discards the other contributor's conflicting changes. Directory conflicts are not solved by this JSON feature; stop and choose a separately authorized workflow.
+4. **Submit:** create a UTF-8 JSON file as below and pass its absolute path as `fileConflictsResolutionsFile` with a merge message. Each `path` must exactly match its observed FILE_CONFLICT destination path, including any writable-xlink prefix. Each entry requires exactly one of `keep` (`source`/`destination`) or an absolute readable regular `resultFile`. Duplicate paths and unknown fields are rejected. Input validation caps JSON at 1 MiB / 500 entries and records its SHA-256 plus counts, not file contents. Applying rechecks the JSON hash and result-file readability after help, before dispatch.
+5. **Observe:** inspect the receipt and any emitted target changeset. Never automatically retry a conflict, timeout or uncertain applying result. Keep source/target heads and all input files unchanged between inspection, validation and submission; these calls do not provide a transaction, head lock, result-content hash or atomic input snapshot. If the inputs or heads change, reassess instead of reusing stale merged content. The CLI owns current-conflict matching; its documented invalid-resolution rejection happens before upload, but opaque failures do not establish rollback.
+
+```text
+plastic_mergeBranches(source="br:/main/source@Example Repository@example@unity", target="br:/main@Example Repository@example@unity", mode="analyze")
+plastic_mergeBranches(source="br:/main/source@Example Repository@example@unity", target="br:/main@Example Repository@example@unity", message="Integrate reviewed resolutions", fileConflictsResolutionsFile="/tmp/resolutions.json")
+```
+
+```json
+{
+  "resolutions": [
+    { "path": "/src/Player.cs", "resultFile": "/tmp/merged/Player.cs" },
+    { "path": "/art/logo.png", "keep": "source" },
+    { "path": "/README.md", "keep": "destination" }
+  ]
+}
+```
+
+The paths above are POSIX examples; on Windows supply native absolute local input paths. The tool and `cm` never change/delete the caller's JSON or result files. The JSON takes precedence over an optional explicit `unlistedConflictPolicy="source"|"destination"`, which emits `--keepsource`/`--keepdestination` only for that intentional fallback. Omit it to keep the existing noninteractive behavior for unlisted conflicts; never select a fallback automatically. `--nointeractiveresolution` is always present, including analysis. The resolution flag is required in local help only when a file is supplied, so ordinary merges retain their existing capability requirements. Local CM 11.0.16.10468 help advertises this flag; deterministic tests cover contracts, not live server-side resolution effects. Shelve sources/results are not added by this feature.
+
+### Server merge bounds
+
+Stdout 64 KiB/stderr 16 KiB, fatal UTF-8, nullable observed start/terminal/exit facts. Help: 3 second deadline and 32,768 decoded-unit stdout gate (the updated help exceeds the former 16 KiB limit); merge: 30 second deadline with bounded termination escalation. Capture uncertainty never implies cancellation or safe replay.
+
+Classify full framing/records before one aggregate 100-reference projection budget. Unknown/contradictory/malformed/overlimit evidence cannot become success. DTO 131,072 UTF-8 bytes; presentation 24,000 units. Core text/fenced JSON and native text/JSON share one observation; failures return native isError with no diagnostic duplication.
+
+## Follow-up decisions
+
+Inspect merge metadata and pending scope rather than assuming exit 0 permits checkin. Use finalization only with explicit policy intent, not as automatic conflict repair. Manual resolution and any later applying call remain agent/user decisions with their own scope.
+
+For source/consumer/platform limits, see [receipt semantics](2026-10-06-safety-and-receipts.md#evidence-and-transport-limits) and [the workflow skill](../skills/using-plastic/SKILL.md).

package/docs/2026-10-06-safety-and-receipts.md

@@ -0,0 +1,95 @@
+# Safety and receipts
+
+[Documentation index](README.md) · [Tool-specific contracts](README.md#look-up-a-tool)
+
+**The tool reports observed facts and unknowns; the agent chooses the next authorized action.** A receipt is not a transaction, automatic resolution, or proof that every requested effect occurred.
+
+## What success means
+
+| Evidence | What it supports | What it does not establish by itself |
+|---|---|---|
+| Complete command exit 0 | Command completion, if that tool admits the capture | Changed files, clean workspace, deletion, preservation, or requested review state |
+| Admitted emitted ID | The exact creation identity emitted by that command | Requested/emitted server alias equivalence, target-head exclusivity, or unrelated repository effects |
+| Complete scoped read | Facts in that source/query scope | Repository totals, unselected records, global absence, or an atomic snapshot |
+| Separate resulting-byte/state observation | The inspected post-state at that time | Automatic rollback or a guarantee about concurrent activity |
+| Timeout/abort/retirement | The observed lifecycle/capture uncertainty | That the process stopped, no effect occurred, or replay is safe |
+
+Some tools can observe more than command completion—for example admitted checkin changesets or patch bytes. Others deliberately keep requested effects null/unverified. Read the relevant tool reference instead of applying one success rule to all operations.
+
+## Read a native result
+
+All core tools declare an output schema. Registered results use producer-owned `structuredContent`, independently of text/JSON presentation. Codemode consumers receive that DTO when the host preserves it.
+
+| Field or concept | How to use it |
+|---|---|
+| `schemaVersion`, `action` | Select the declared tool/schema route; versions and shapes differ by tool |
+| `ok` and native `isError` | Distinguish admitted results from failures; also handle host-native rejection |
+| `provenance` | Plastic external content, produced by this package—not trusted instructions |
+| `completeness` | Inspect read, capture, and projection independently where declared |
+| `scope`, limits, counts | Keep query scope and omitted/unattempted evidence visible |
+| Attempt/stage/effect fields | Preserve earlier completed or possible effects after later failures |
+| Requested versus observed identity | Never substitute caller intent for observed/resolved identity |
+
+Not every schema has every field. A successful **partial read** can still have `ok:true`; that is not a complete clean workspace. Native/custom table routes can have null rows/counts and unknown completeness rather than parsed facts.
+
+Mutation/diff receipts generally use empty `details`; some read adapters retain legacy presentation in `details.rawResult`. Don't use that presentation as a substitute for declared canonical fields.
+
+```js
+const dto = await tools.plastic_status({source: "xml", maxItems: 20});
+if (!dto.ok) {
+  text(dto.error);
+} else {
+  text({
+    completeness: dto.completeness,
+    itemCount: dto.data.itemCount,
+    changedPaths: dto.data.items.filter(item => item.kind === "changed").map(item => item.path)
+  });
+}
+```
+
+The example emits observed paths plus completeness; it does not certify workspace cleanliness. See [status](2026-10-06-status.md) for source restrictions.
+
+## Mutation authorization and preflight
+
+Direct tool calls do not require package-owned approval tokens or UI confirmation. The agent must have user authorization, inspect exact targets, and respect command/path/workspace guards.
+
+Preflight is **not routine confirmation** and does not mean the same thing everywhere:
+
+| Operation | Preflight behavior |
+|---|---|
+| Branch/object deletion, object writes, workspace merge/finalization, server merge | Command-only plan; zero CLI, no existence/conflict/permission proof |
+| Patch | Command-only plan; may read local selector metadata; no staging, backend probe, or generation |
+| Checkin | Reads pending scope once; no mutation |
+| Switch | Two sequential local reads; not server switchability/conflict proof |
+| Closeout | Read-only discovery/pending preview; not zero CLI or applying-readiness proof |
+| Add, undo, update, branchCreate | No added preflight API; use the declared tool schema |
+
+Shelveset `preview=true` is different: it actually dispatches CM and can prompt/fail on conflicts. Read [shelveset application](2026-10-06-shelvesets-and-reviews.md#shelvesetapply).
+
+## Respond to failure without inventing recovery
+
+1. Stop dependent actions on failed/unknown evidence. A failed checkin/readiness step must not become successful closeout.
+2. Retain earlier IDs, publication, completed commands, and possible effects recorded in the receipt.
+3. Inspect the exact affected scope when further investigation is authorized.
+4. Choose an explicit resolution or ask the user when ownership, permissions, interaction, or intent is unclear.
+
+Single-command producers do not silently retry, switch backends/strategies, or compensate. Compound operations can have multiple declared steps. Checkin and switch retain narrowly admitted existing recovery paths; those exceptions are documented in [workspace operations](2026-10-06-workspace-operations.md), not general retry permission.
+
+Parent/agent restoration is a separate action with its own scope and evidence. It is not producer rollback. Do not interpret null effects, empty stdout, or a no-op classification as globally verified absence.
+
+## Guards and limits of protection
+
+- The loaded Bash guards block raw GUI `cm diff` / `cm differences` and unsafe interactive `cm merge --merge` use.
+- Guards exist only in Pi processes that load the package. Prefer user-scope installation for children running elsewhere.
+- Preserve selector spelling and qualifiers. Different server names are not automatically interchangeable.
+- Operation-specific containment checks do not turn all directory/wildcard operands into exclusively contained mutations.
+- `cm cat --file=<path>` writes and can overwrite that destination. Never treat it as a read-only selector or point an inspection export at canonical workspace files.
+- A bounded collector may retire while a child/server action can still be running. Per-command deadlines are not atomic compound deadlines.
+
+## Evidence and transport limits
+
+Source acceptance is deliberately tool/client-specific. Windows CM 11 fixtures are not universal cross-platform, Xlink, Unicode, head, source-link, alias, exclusivity, or rollback proof. Unsupported source profiles stop conservatively; the agent may investigate rather than forcing admission.
+
+Real SDK-host tests use a deterministic local provider and synthetic CLI. They validate consumers/serialization, not actual backend effects. Ordinary transcript messages do not automatically persist the full DTO. Foreign result hooks can remove/replace structured output, causing text fallback; this package does not restore it or enforce bounds after foreign hooks. General RPC fidelity is not claimed.
+
+See [development](2026-10-06-development.md) for testing and [the tool index](README.md#look-up-a-tool) for each source/capture contract.

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

@@ -0,0 +1,101 @@
+# Setup
+
+[Documentation index](README.md) · [Next: tools and loading](2026-10-06-tools-and-loading.md)
+
+## Requirements
+
+| Component | Requirement |
+|---|---|
+| Node.js | 22.19.0 or newer |
+| Pi | Latest stable release; older versions are not the supported baseline |
+| Plastic CLI | Authenticated `cm` on PATH, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path |
+| Workspace | Configured Plastic workspace for workspace-scoped tools; server merge has a separate workspace-free contract |
+| Text comparison | A compatible non-GUI GNU/POSIX `diff` |
+| Patch generation | A separately verified patch-capable diff backend; see below |
+
+The package does not install or authenticate Plastic for you. Authenticate using your own authorized account, and inspect the workspace you intend to operate on.
+
+## Choose an installation source
+
+### Published npm release
+
+```bash
+pi install npm:@aefree/pi-plastic
+```
+
+This is the published package, which can lag Git main. Install at user scope when sessions and child processes in arbitrary workspaces need the Bash guards.
+
+### Git main or a pinned release
+
+```bash
+# Track the moving default branch, including unreleased work:
+pi install https://github.com/aefreedman/pi-plastic
+
+# Pin an existing release tag:
+pi install git:github.com/aefreedman/pi-plastic@v0.8.0
+
+# Equivalent SSH source:
+pi install git:git@github.com/aefreedman/pi-plastic@v0.8.0
+```
+
+A pinned Git tag/commit does not move to main when updated. Review third-party source before installing: extensions execute with host permissions.
+
+### Local checkout or project settings
+
+```bash
+pi install ./path-to-pi-plastic
+pi install -l ./path-to-pi-plastic
+```
+
+Local sources load from their path without copying. Install checkout dependencies yourself; see [development](2026-10-06-development.md#checkout-setup). Relative local paths resolve from the settings file containing them.
+
+`-l` writes project settings. Project packages are subject to Pi's project-trust rules. A project-local install protects only processes loading that project's settings, not children launched into other workspaces.
+
+## Update and reload
+
+Use `pi list` to inspect configured sources. `pi update --extensions` reconciles installed packages; `pi update <source>` updates one source. Plain `pi update` updates Pi itself, not just this package.
+
+Restart existing Pi processes after installation or source changes. For resource edits during development, Pi provides `/reload`; source files are not automatically watched. See [loading modes](2026-10-06-tools-and-loading.md#loading-modes) when an installed tool is inactive rather than missing.
+
+## Executable configuration
+
+Set environment variables before starting Pi. Full executable paths may contain spaces; the package invokes the resolved executable as-is and does not discover Git Bash paths automatically.
+
+| Variable | Purpose |
+|---|---|
+| `PI_PLASTIC_CM_EXECUTABLE` | Override `cm` |
+| `PI_PLASTIC_DIFF_EXECUTABLE` | Backend for text-only comparisons |
+| `PI_PLASTIC_PATCH_EXECUTABLE` | Separate default backend for `cm patch` |
+| `PI_PLASTIC_TOOL_LOADING_MODE` | `balanced`, `loader-only`, or `all-active` |
+| `TEMP` / `TMP` | Writable ASCII-safe temporary location when the diff backend cannot accept Unicode paths |
+
+For example, in PowerShell, using a **verified local executable**:
+
+```powershell
+$env:PI_PLASTIC_CM_EXECUTABLE = "C:/Tools/Plastic/cm.exe"
+$env:PI_PLASTIC_DIFF_EXECUTABLE = "C:/Tools/Diff/diff.exe"
+$env:PI_PLASTIC_PATCH_EXECUTABLE = "C:/Tools/Git/usr/bin/diff.exe"
+pi
+```
+
+These are fictional paths, not executable-discovery recommendations.
+
+## Diff and patch backends
+
+Text comparison and patch generation have different compatibility requirements. The package does not silently switch backends or retry with another executable.
+
+| Environment | Text comparison | Patch generation |
+|---|---|---|
+| Windows | Configure a compatible text diff explicitly if needed | Set `toolPath` for one call or `PI_PLASTIC_PATCH_EXECUTABLE`, for example a verified Git `diff.exe`; text/GnuWin32 configuration is not reused as the patch default |
+| macOS | Apple BSD `/usr/bin/diff` has text-only evidence; PATH may instead resolve GNU diff | Tested Apple BSD diff rejects CM 11's `--binary` argument; configure a verified GNU Diffutils-compatible backend |
+| Other non-Windows environments | Resolve PATH `diff` or the explicit text override | The text override/PATH fallback is usable only when that executable accepts the local CM patch arguments |
+
+Patch precedence: one-call `toolPath`, then `PI_PLASTIC_PATCH_EXECUTABLE`, then the allowed non-Windows fallback. Windows requires explicit patch configuration.
+
+Interactive Pi sessions issue one path-redacted capability warning per runtime for missing Windows patch configuration or an invalid configured override. The tool still validates configuration at call time. Fix configuration before a **new deliberate attempt**; after an uncertain applying operation, inspect state first.
+
+See [diffs and patches](2026-10-06-diffs-and-patches.md) for comparison scopes, publication, cleanup, and bounds.
+
+## Optional file discovery
+
+`@aefree/pi-file-discovery` is an independently loaded optional integration, not a bundled runtime requirement. Without it, Plastic tools and the skill still work; no discovery filter registry is created. See [integration behavior](2026-10-06-integrations.md#file-discovery-filter).