@aefree/pi-plastic 0.7.6 → 0.8.1

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## [0.8.1] - 2026-10-12
+
+### Fixed
+
+- Restored useful bounded direct status text and parseable JSON for standard, machine and XML sources, including exact admitted paths/moves, merge hints, uncertainty and presentation omissions. Native DTOs remain unchanged; opt-in raw diagnostics are separately bounded and cannot restore excluded machine identities.
+
+## [0.8.0] - 2026-10-08
+
+### Added
+
+- Producer-owned structured output schemas for all 27 core tools, with explicit request snapshots, bounded observations, capture/read completeness, and uncertainty-aware mutation receipts. The on-demand capability loader remains schema-less.
+- Agent-driven server conflict resolution through `plastic_mergeBranches`: read-only conflict analysis, validated per-file JSON resolutions, explicit source/destination fallback policy for unlisted conflicts, and conditional installed-client capability checks.
+- Opt-in XML status with absolute Unicode paths and typed v2 results for supported text-file and directory records. XML capture and parsing reject malformed, unsupported, lossy, overflowing, or incomplete observations; base revisions remain unavailable.
+- Structured branch reads/listing, workspace listing, shelveset listing, and code-review queries, including bounded identities, exact decimal IDs, query-scoped counts, and documented source prerequisites.
+- Typed workspace merge and merge-to-branch closeout stage receipts, including narrow Windows copied-add admission, independently checked readiness, and actionable evidence gates for unsupported merge profiles.
+- A task-oriented installed manual, concise README, tool/task navigation, progressive skill references, and deterministic documentation/link/packing checks.
+
+### Changed
+
+- **Breaking:** replace `plastic_diffFile`, `plastic_diffRevisions`, and `plastic_workspaceDiff` registrations with `plastic_diff` and explicit `file`, `revisions`, or `workspace` modes. The old tool names have no aliases or redirects. Pending review requires selected paths or explicit `allPending=true`; raw GUI diff remains blocked.
+- Consolidated diffs use qualified, hash-verified loaded bases, bounded stable local snapshots, explicit binary/unavailable results, and truthful partial workspace outcomes.
+- Mutation receipts distinguish command completion, emitted identity, observed state, partial effects, and unverified outcomes. Failed core operations reject so compound callers cannot proceed from success-looking presentation text; uncertainty never authorizes blind retries or rollback.
+- Review-patch receipts expose selector/backend fidelity, bounded hash/byte/excerpt observations, atomic no-overwrite publication, and owned cleanup/retention without applying patches.
+- Admit bounded multiline checkin and closeout comments while retaining strict validation of paths, selectors, identities, and other control characters.
+- Align active development, deterministic host/rendering checks, and tool-loading evals with stable Pi 1.1.0; host framework packages remain peers.
+- Modularize execution, domain, operations, presentation, and Pi adapters while preserving canonical-root loading and core export ownership.
+- Keep tests, evals, and contributor tooling repository-only while packaging the consumer manual and required runtime resources.
+- Remove the post-publish registry-visibility gate while retaining fail-closed version/commit reconciliation before publishing.
+
+### Fixed
+
+- Correct cross-platform deterministic tests to assert Windows-only source rejection on other platforms and use physical workspace fixture paths when the temporary root is a junction.
+- Accept observed checked-out `CO` pending records with unavailable (`-1`) revisions, preserving selected paths so unrelated excluded checkouts do not block checkins.
+- Resolve closeout parents through bounded installed-client leaf-name queries with emitted full-name/direct-parent validation; preserve repository/server qualifiers and stop on ambiguous or failed observations.
+- Read the explicit loaded-branch status header independently of pending merge-link changeset references; reject malformed, ambiguous, lossy, or incomplete branch observations without guessing alternate identities.
+- Stop compound merge/checkin continuation after failed switches, updates, readiness reads, or checkins, and retain observed created identities and earlier-effect uncertainty across later failures.
+- Bound selected command collectors even when terminal or pipe closure never arrives, preserving escalation, listener cleanup, incomplete-capture facts, and no-retry behavior.
+- Preserve split UTF-8 sequences across subprocess chunks; reject unsupported Windows pre-decoding path substitutions without adding an encoding fallback.
+- Fail consolidated diffs closed on permission/I/O errors and unsupported workspace markers, and enforce aggregate UTF-8 response bounds without changing retained identities or completed counts.
+- Preserve full cloud/server qualifiers and exact large decimal identities in server merge results; enforce one aggregate reference budget and retain contradictory-output uncertainty.
+- Separate XML unsupported profiles, malformed contract data, and observation overflow without exposing source values.
+- Isolate SDK rendering-test configuration before runtime imports and validate canonical package ownership in deterministic host tests.
+
 ## [0.7.6] - 2026-09-29
 
 ### Changed

package/README.md

@@ -1,209 +1,83 @@
 # Pi Plastic
 
-Pi tools, footer status, and skill guidance for Plastic SCM / Unity Version Control workflows.
+Plastic SCM / Unity Version Control tools and workflow guidance for [Pi](https://pi.dev).
 
-## Tool presentation
+Use it to inspect a workspace, review changes without opening a GUI, and perform explicitly scoped branch, checkin, merge, shelveset, and code-review operations.
 
-Plastic tools use compact action headers inside Pi's standard tool boxes. Headers show the workspace name and the branch, file, revision pair, or query being acted on; command previews are labeled explicitly. Collapsed results summarize structured status counts, diff availability, patch output, and server-merge outcomes. Blocked checkins, unresolved effects, omitted results, and unavailable comparisons remain visible without expansion. Plain CLI output stays neutral rather than implying a verified mutation.
+## What you get
 
-Expand a result using your configured tool-expansion shortcut to see the workspace, request, colored diff hunks, and complete original returned evidence. The display preserves JSON identifiers and numeric text, masks common credential assignments, and removes terminal control sequences. Rendering does not change tool execution or model-facing output; it is not a general source-code secret scanner.
-
-Run `npm run preview:tools` from a repository checkout for offline examples. The preview uses plain colors and a test expansion binding; Pi supplies the live theme, box, and configured shortcut.
-
-## Plastic branch footer status
-
-When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace` and reads either the selector's `smartbranch` or `br` form as the credential-free branch source. A bounded `cm status` call is used only when the selector has no valid branch. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
-
-The extension owns only the `plastic-branch` status key. It does not replace Pi's footer or suppress Pi's Git branch display, so Git and Plastic information can appear together in nested workspaces. If the Plastic marker exists but neither the selector nor `cm` yields a branch, the footer shows `Plastic branch unavailable`. Non-Plastic directories show no Plastic status.
-
-## File-discovery filter
-
-When `@aefree/pi-file-discovery` is also loaded, Pi session startup registers the independent advisory `plastic.ignore-files` file-discovery filter through the package-qualified capability-registry rendezvous key. The packages may have separate module roots; Plastic does not import file-discovery from its own root. It discovers readable `ignore.conf` and `cloaked.conf` only from the nearest Plastic workspace to each requested root, then supplies them as ripgrep ignore files without replacing native ripgrep/Git-ignore behavior. A root is emitted only when it has at least one readable ignore/cloak file; each emitted root declares `filterDecision: "applied"`, decision code `plastic_ignore_files_applied`, and that workspace as its `filterBoundary`. No-op Plastic roots are omitted from mixed requests, and a request with no effective ignore/cloak records is `not_applicable`. The integration is optional: without `pi-file-discovery`, all Plastic tools and skills still load and no filter registry is created. Missing, malformed, or unavailable Plastic filter data degrades to generic discovery; `pi-file-discovery` owns that execution hygiene and disclosure behavior. It does not register workflow guidance or perform Plastic CLI readiness checks; owning `plastic_*` tools validate their own workspace and CLI requirements.
-
-
-## Mutation execution
-
-Directly invoked mutating `plastic_*` tools do not require approval tokens or package-owned UI confirmation. After the tool's existing argument, command, workspace-readiness, exact-target, and path-containment checks pass, each command attempt proceeds to its intended `cm` spawn. The process layer makes one attempt and does not retry implicitly; inspect Plastic status before manually retrying an ambiguous side-effecting failure.
-
-Removing the approval layer does not relax Plastic safety guards. Command allowlists, exact mutation targets, workspace/path containment, non-interactive process selection, blocked `cm diff`, safe merge flags, and operation-specific preflight behavior remain authoritative. Compound tools may intentionally execute multiple validated command steps.
-
-## Tools
-
-- `plastic_tool_search` (dynamic capability search and loader)
-- `plastic_status`
-- `plastic_update`
-- `plastic_add`
-- `plastic_checkin`
-- `plastic_undo`
-- `plastic_resolveDeleteChangeConflict`
-- `plastic_diff`
-- `plastic_patch`
-- `plastic_diffRevisions`
-- `plastic_diffFile`
-- `plastic_workspaceDiff`
-- `plastic_branchCreate`
-- `plastic_switchBranch`
-- `plastic_merge`
-- `plastic_mergeBranches`
-- `plastic_mergeToBranch`
-- `plastic_finalizeMerge`
-- `plastic_currentBranch`
-- `plastic_branchList`
-- `plastic_branchExists`
-- `plastic_branchDelete`
-- `plastic_shelvesetCreate`
-- `plastic_shelvesetApply`
-- `plastic_shelvesetDelete`
-- `plastic_shelvesetList`
-- `plastic_codeReviewCreate`
-- `plastic_codeReviewUpdate`
-- `plastic_codeReviewDelete`
-- `plastic_codeReviewFind`
-- `plastic_workspaceList`
-
-## Dynamic tool loading
-
-The package exposes 30 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
-
-The default **balanced** session set keeps `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch` active. The other Plastic tools remain registered but inactive until selected; built-in and other-extension tools are not removed. Previous loader additions on the active session branch are restored on startup, resume, fork, and reload.
-
-For controlled comparisons, set `PI_PLASTIC_TOOL_LOADING_MODE` before starting Pi:
-
-```bash
-PI_PLASTIC_TOOL_LOADING_MODE=balanced    # default production candidate
-PI_PLASTIC_TOOL_LOADING_MODE=loader-only # maximum initial schema reduction
-PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 30 currently exposed tools; loader omitted
-```
-
-Pi uses canonical `sourceInfo` provenance to identify this package's effective tools before deferring, restoring, or activating them. If canonical provenance or ownership of the effective loader cannot be proven, `pi-plastic` fails safe: it preserves the complete current active set exactly, does not defer, remove, or activate any `plastic_*` name, and an effective package loader can only report known tools that are already active rather than activating inactive names. On sourceInfo-capable Pi instances, providers without native deferred definitions still receive the complete current active set after a loader call. Reload or restart Pi after source edits; source files are not watched automatically.
-
-## Safety behavior
-
-The Bash guards run only in Pi processes that actually load this package. A project-local install does not protect a delegated child process whose working directory resolves different project settings. Install `pi-plastic` at user scope (the default `pi install`, without `-l`) when subagents and sessions in arbitrary workspaces must inherit the guards. Restart existing Pi processes after installation or source changes.
-
-- `plastic_branchCreate` supports an explicit parent branch independent of the loaded workspace branch, defaults relative names to the current branch when no parent is supplied, and rejects top-level paths unless `allowRootBranch=true` is explicit.
-- `plastic_diff` remains a disabled alias by design. Use `plastic_status` for changed-path listing; do not diff as routine post-edit validation or checkin preflight. When change-boundary evidence is needed, use `plastic_diffFile` for one exact file, `plastic_workspaceDiff` with selected paths or explicit `allPending=true`, or `plastic_diffRevisions` for an explicit historical pair. Diff responses use small defaults and caller-controlled `maxChars` bounds. Automatic pending-file bases bind each status revision ID to its owning workspace or Xlink repository/server, including mixed-Xlink reviews. If ownership cannot be resolved, that comparison is reported unavailable rather than retrieving a bare revision from the caller repository. Historical and workspace bytes are copied to ASCII-safe package-owned paths before the backend runs, while normalized headers retain the logical Unicode labels.
-- `plastic_status(machineReadable=true, format="json")` returns parsed `items`, aggregate `summary`, and `itemCount` (`total`, `returned`, `omitted`) rather than requiring agents to parse Plastic rows. It returns at most 100 items by default; set `maxItems` (up to 500) when more are intentional. `includeRaw=true` adds the original unbounded Plastic output for diagnostics, so omit it for normal agent use to conserve context tokens.
-- Pending-diff ownership containment uses filesystem identity, so a workspace reached through a symlink, junction, or platform filesystem alias still resolves its workspace and nested Xlink bases safely. Plastic commands and returned labels retain the caller's original lexical path; missing deleted or moved ownership ancestors remain unavailable rather than falling back to a parent repository.
-- Preflight is not routine confirmation. Use it for ambiguous or broad mutation scope, moved/deleted path rewriting, compound operations, or explicit preview requests; otherwise rely on exact targets and the tools' runtime guards.
-- `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply. Unqualified `br:/...` selectors are qualified only with the current workspace selector's exact repository; otherwise pass `br:/<branch>@<repository>@<server>`.
-- Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
-- Merge tooling surfaces Plastic `FILE_CONFLICT` records and merge-state metadata from `cm status`.
-- `plastic_mergeBranches` is a separate workspace-free server-side route. It requires fully repository/server-qualified source and target branches in the same exact repository/server and a nonempty message. Its optional preflight only renders the command; it does not analyze remote conflicts. A completed result proves one emitted root-mount target changeset for this dispatch, not source merge-link identity, exclusive target-head ownership, server capability beyond the dispatch, rollback, or xlink effects. No-op and conflict records do not independently prove that no server effect occurred. The route has no workspace fallback, retries, target-head unification, xlink policy, shelve mode, or conflict-policy override; undetected server-side xlink effects remain possible.
-- `plastic_mergeToBranch` performs the common safe closeout flow: resolve the source branch's parent as the default target, switch to the target branch, optionally update, merge a source branch non-interactively, verify merge state, and check in the merge result. It verifies the loaded target before merge/checkin and rejects final-branch mismatches; Plastic checkins stay on the branch where they were created, so switching afterward is not a Git-style integration.
-- `plastic_finalizeMerge` supports reviewed/manual-resolution flows where Plastic still needs merge metadata finalized before checkin.
-
-## Patch generation examples
-
-```text
-plastic_patch(source="<branch-spec>", integration=true)
-plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
-plastic_patch(source="<left-spec>", destination="<right-spec>")
-plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
-```
-
-If `output` is omitted, the package returns patch content. If `output` is provided, it must be a new path: the package generates into a package-owned sibling staging file, validates it, and atomically publishes it without overwriting an existing path. Plastic/server patch output may encode a moved item either as a move or as delete/add records; `pi-plastic` does not claim a representation without a live backend fixture. Inspect patches before sharing them because they can contain source code, binary content, local paths, or secrets that were present in the changed files.
-
-## Included skill
-
-- `using-plastic` - PlasticSCM branch, workspace, merge, shelveset, checkin, and code-review workflow guidance
+- **27 core tools** with producer-owned structured results, plus an on-demand capability loader.
+- **Text-only diffs and generated review patches**, with explicit scope and bounded output.
+- **Agent-driven server conflict resolution:** inspect conflicts, validate merged files, and submit per-file JSON decisions without a merge UI.
+- **Truthful mutation receipts:** command completion, observed identities, partial effects, and uncertainty stay separate.
+- **Pi integration:** compact tool displays, a Plastic branch footer, Bash guards, and optional Plastic ignore/cloak filtering for file discovery.
+- **The `using-plastic` skill**, with task-specific references loaded only when needed.
 
 ## Install
 
-Install the latest stable npm release at user scope so the safety guards also load for delegated child processes in other workspaces:
+Install the npm release at user scope:
 
 ```bash
 pi install npm:@aefree/pi-plastic
 ```
 
-Install a pinned GitHub release over HTTPS:
-
-```bash
-pi install git:github.com/aefreedman/pi-plastic@v0.7.6
-```
-
-Equivalent SSH install:
-
-```bash
-pi install git:git@github.com/aefreedman/pi-plastic@v0.7.6
-```
-
-To intentionally track the moving default branch instead of a release tag:
+To test the current Git version instead:
 
 ```bash
 pi install https://github.com/aefreedman/pi-plastic
 ```
 
-Local development install:
-
-```bash
-pi install <path-to-pi-plastic>
-```
-
-Project-local install:
-
-```bash
-pi install -l <path-to-pi-plastic>
-```
-
-Project-local installation protects only Pi processes that load those project settings. It is insufficient as a global Bash safety rail when a subagent launches with another working directory.
-
-## Requirements
-
-- Node.js 22.19.0 or newer
-- Latest stable Pi; the current development and eval baseline is Pi 0.99.1
-- Plastic SCM / Unity Version Control CLI (`cm`) available on `PATH`, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path
-- A GNU/POSIX-compatible text `diff` available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path (including paths containing spaces), for text-only diff tools. Pi invokes that resolved executable as-is and does not discover Git Bash paths automatically. On macOS, bare `diff` is PATH-dependent: it may be GNU Diffutils (often installed as `diff` ahead of system paths) or Apple’s BSD `/usr/bin/diff`; the package does not substitute one for the other. Configure the intended text executable explicitly when that distinction matters.
-- Patch generation has a separate executable policy: `toolPath` is the one-call highest-priority override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, set one to a verified patch-capable non-GUI executable such as Git's `diff.exe`; the package deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32 as a patch default. macOS validation with Plastic 11 found that Apple BSD `/usr/bin/diff` supports text-only diffs but rejects the `--binary` argument supplied by `cm patch`; configure a verified GNU Diffutils-compatible executable explicitly for `plastic_patch`. The non-Windows fallback to `PI_PLASTIC_DIFF_EXECUTABLE` or bare `diff` remains only for environments whose resolved executable satisfies that patch contract. In an interactive Pi session, an invalid configured patch override or missing Windows patch setting produces one package capability warning per Pi runtime; the warning omits configured paths, and `plastic_patch` retains its tool-time validation.
-- A configured Plastic workspace for workspace-scoped operations. Text diffs require an ASCII-safe temporary directory; if the configured backend cannot accept Unicode paths, set `TEMP` and `TMP` to a writable ASCII-only location.
-- `pi-file-discovery` is an optional independently loaded integration. When its `discover_candidate_files` tool is active, it receives the advisory Plastic ignore/cloak filter through the shared global capability protocol; when absent, `pi-plastic` loads without file-discovery filtering. The tarball does not embed linked sibling workspaces or `node_modules` paths.
-
-## Testing
-
-```bash
-npm test
-```
-
-`npm test` first runs `npm run typecheck` with pinned TypeScript and Node 22 types. The strict, no-emit check covers `index.ts`, `src/`, every extension, and compile-only schema-inference contracts under `tests/types/`. Runtime tests and eval harnesses execute through `tsx`.
+Git main can contain unreleased changes; npm installs the published release. See [setup](docs/2026-10-06-setup.md) for pinned releases, local checkouts, configuration, and updating an existing installation.
 
-The default suite is credential-free and covers tool validation, schema conversion, path-resolution regressions, extension registration, rendering, OpenAI strict-schema compatibility classification, and bash guard behavior.
+### Requirements
 
-Run the opt-in read-only live smoke test against a dedicated clean sandbox workspace:
+- Node.js **22.19.0 or newer** and the latest stable Pi.
+- An authenticated Plastic CLI (`cm`) on `PATH`, or an explicit executable override.
+- A configured Plastic workspace for workspace-scoped tools.
+- A compatible non-GUI `diff` for text comparisons. Patch generation has a **separate backend policy**, particularly on Windows and macOS; see [diff and patch setup](docs/2026-10-06-setup.md#diff-and-patch-backends).
 
-```bash
-PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/sandbox npm run test:live
-```
+Restart existing Pi processes after installation or source changes. User-scope installation makes the guards available across workspaces; project-local settings alone do not protect child processes launched elsewhere.
 
-The live test requires `/main`, no pending changes, and no merge in progress. It does not mutate the repository. Mutation tools should still be rehearsed manually in a disposable sandbox before relying on them in a new environment.
+## Start with inspection
 
-### Dynamic tool-loading eval
+Open Pi in the intended Plastic workspace and ask it to inspect pending changes. The default balanced mode starts with `plastic_status`, `plastic_currentBranch`, and `plastic_tool_search` active.
 
-The package-local behavioral eval uses fresh Pi 0.99.1 JSON subprocesses against an explicitly attested dedicated Plastic sandbox and is not a skill eval. It compares all-active, balanced, and loader-only mode behavior, checks exact smallest-sufficient loader activations, blocks destructive calls unless they are supported `preflight: true` previews, captures tool calls and sanitized provider-schema measurements, and deletes raw provider payload captures by default.
+These are tool calls inside Pi, not shell commands:
 
-```bash
-npm run eval:tool-loading -- --dry-run
-PI_PLASTIC_EVAL_SANDBOX=/absolute/path/to/sandbox PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox npm run eval:tool-loading -- --model openai-codex/gpt-5.6-luna --condition balanced
+```text
+plastic_status(source="xml", maxItems=20)
+plastic_tool_search(query="text diff")
+plastic_diff(mode="workspace", paths=["Assets/Example.txt"])
 ```
 
-See [`evals/tool-loading/README.md`](evals/tool-loading/README.md) for approved model restrictions, cases, measurements, and result hygiene.
+XML status is opt-in and has Windows CM11 source validation. Pick the status source appropriate to your client using the [status guide](docs/2026-10-06-status.md). Load other capabilities as needed; don't enable all tools or run every preflight as routine ceremony.
 
-## Constrained sampling compatibility
+## Find the right documentation
 
-Pi supports provider-side constrained sampling for tools. `pi-plastic` does not currently opt in: every public Plastic schema includes optional fields (at minimum `workdir`), while OpenAI strict function schemas require closed objects and all declared properties to be required. Pi forwards the registered schema without converting those optional fields.
+| Need | Start here |
+|---|---|
+| Install, update, or configure executables | [Setup](docs/2026-10-06-setup.md) |
+| Find a tool or understand on-demand loading | [Tool catalog and loading](docs/2026-10-06-tools-and-loading.md) |
+| Interpret success, partial results, and failures | [Safety and receipts](docs/2026-10-06-safety-and-receipts.md) |
+| Inspect status, branches, workspaces, or object IDs | [Status](docs/2026-10-06-status.md) · [Discovery](docs/2026-10-06-discovery.md) |
+| Add, undo, switch, check in, or manage branches | [Workspace operations](docs/2026-10-06-workspace-operations.md) |
+| Merge or close out a branch | [Merging](docs/2026-10-06-merging.md) |
+| Compare changes or generate a patch | [Diffs and patches](docs/2026-10-06-diffs-and-patches.md) |
+| Save/apply a shelf or create/update a review | [Shelvesets and reviews](docs/2026-10-06-shelvesets-and-reviews.md) |
+| Understand the footer, displays, or file-discovery integration | [Integrations](docs/2026-10-06-integrations.md) |
+| Work on the package or consume its structured API | [Development](docs/2026-10-06-development.md) |
 
-Enabling `strict: "prefer"` now would therefore either produce invalid strict OpenAI requests or require a breaking redesign of the ordinary tool arguments. The test suite audits all registered tools and prevents accidental opt-in until a schema is genuinely strict-compatible. Existing TypeBox validation and Plastic runtime safety checks remain authoritative.
+The [documentation index](docs/README.md) routes by task and by tool. Agents should read the relevant page or section, not the whole manual. For operational workflows, start with [the skill](skills/using-plastic/SKILL.md).
 
-OpenAI Codex models may advertise grammar tools without advertising strict JSON-schema tools. Grammar sampling is not used here because Plastic operations have structured multi-field arguments rather than a single bounded string language.
+## Important safety behavior
 
-## Implementation notes
+- Prefer `plastic_*` tools. Raw `cm diff` / `cm differences` and unsafe interactive merge commands are blocked by the loaded Bash guards.
+- Mutations do **not** require package-owned approval tokens or UI confirmation. The agent must still have user authorization and inspect the intended scope.
+- A completed command is not automatically a verified effect. Read the receipt before chaining calls; after an uncertain mutation, inspect state rather than blindly retrying.
+- The tool reports supported facts and unknowns; the agent chooses further investigation or resolution within the user's authorization. No universal rollback, conflict-resolution, or cross-platform guarantee is implied.
 
-- The core implementation lives in `src/plastic-core.ts`.
-- Shared workspace discovery and branch parsing live in `src/plastic-workspace.ts`.
-- `extensions/plastic-branch-status.ts` owns the additive footer status and its session-scoped refresh lifecycle.
-- `index.ts` is the Pi tool registration layer.
-- `src/plastic-renderers.ts` owns compact calls, result summaries, and expanded evidence.
-- Output shapes are intentionally stable for prompt and workflow compatibility.
+## Contributing and license
 
-## License
+For a checkout, run `npm ci --ignore-scripts --no-audit --no-fund` and `npm test`. See [development](docs/2026-10-06-development.md), [contributing](https://github.com/aefreedman/pi-plastic/blob/main/CONTRIBUTING.md), and [security reporting](https://github.com/aefreedman/pi-plastic/blob/main/SECURITY.md).
 
-MIT. See `LICENSE`.
+MIT. See [LICENSE](LICENSE).

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

@@ -0,0 +1,101 @@
+# Development and structured API
+
+[Documentation index](README.md) · [Receipt semantics](2026-10-06-safety-and-receipts.md)
+
+For contributor policy, see [CONTRIBUTING](https://github.com/aefreedman/pi-plastic/blob/main/CONTRIBUTING.md). This page explains current source ownership, validation, and consumer limitations—not a one-time release procedure.
+
+## Checkout setup
+
+```bash
+npm ci --ignore-scripts --no-audit --no-fund
+npm test
+npm run test:host:status
+npm run eval:tool-loading -- --dry-run
+npm pack --dry-run
+```
+
+Run commands from the manifest root. `npm test` starts with `npm run typecheck`: strict no-emit coverage includes index/src/extensions and compile-only schema-inference contracts. Runtime tests/evals use tsx.
+
+The current pinned development/eval SDK and TUI baseline is **1.1.0**, as declared in package.json; older Pi releases are not a supported matrix. Historical fixture/evidence version strings are not alternate runtime targets. Host-provided framework packages remain peers, not bundled runtime dependencies.
+
+Default tests are credential-free. They cover schemas/semantic guards, registration/loading, aliases, paths/snapshots, lifecycles/retirement, rendering, Bash guards, documentation/navigation, ownership and constrained-sampling classification. The SDK-host harness uses real file loading/finalization/direct/codemode/nested consumers and JSON execution events, with a deterministic local provider and synthetic CLI—no network/backend-effect acceptance.
+
+## Structured API and transport
+
+All 27 core tools have closed output schemas and direct native producer execution. The capability loader is deliberately schema-less. Core exports remain string-returning views; selected failures reject so compound callers cannot proceed on presentation text.
+
+Producers own request snapshots, source admission, bounded projection and same-observation presentation. Native details vary by route: legacy read presentation can remain in rawResult, while mutation/diff receipts use empty details. Don't parse strings to reconstruct canonical facts.
+
+### Consumer caveats
+
+- Host policy/preabort can reject before a producer DTO exists; handle host-native rejection as well as DTO ok.
+- Optional null may be normalized to omission before delivery, and invalid enums may be rejected by the SDK before the producer. No universal raw-submitted-value fidelity is promised.
+- Foreign result hooks own replacements; content-only changes can remove structured output and cause text fallback. The producer doesn't restore it or enforce post-hook bounds.
+- Ordinary transcript messages don't automatically persist the full DTO; general RPC/provider fidelity is not claimed.
+- Identity, capture, request/argv/outcome/effect consistency matters beyond closed JSON shape. Keep adversarial semantic tests when changing schemas.
+
+The [family references](README.md#look-up-a-tool) describe the canonical fields/bounds; [receipt semantics](2026-10-06-safety-and-receipts.md) explains chaining decisions.
+
+## Source map
+
+| Area | Owner |
+|---|---|
+| Explicit core exports | src/plastic-core.ts; operation modules under src/operations |
+| Shared workspace discovery/branch parsing | src/plastic-workspace.ts |
+| CLI execution/capture/context | src/execution |
+| Source parsing/admission and domain contracts | src/domain |
+| Pi registry/parameters/structured adapters | src/pi; index.ts is the entry shim |
+| Text/JSON presentation | src/presentation |
+| Compact/expanded tool rendering | src/plastic-renderers.ts |
+| Footer lifecycle | extensions/plastic-branch-status.ts |
+| Bash safety guards | Declared extensions and their focused tests |
+| Task workflow guidance | skills/using-plastic and its on-demand references |
+| Public consumer manual | docs/README.md and dated topic pages |
+
+Keep stable public tool names/output shapes unless a deliberate breaking change is documented. Do not weaken guards, mutate dependencies/versions incidentally, or centralize another package's policy here.
+
+## Live validation
+
+Live CM runs require an authorized, dedicated disposable sandbox and the contributor's own authentication. Never add credentials, organization/server coordinates, original private files or raw provider payloads to public fixtures/docs.
+
+Read-only smoke, from an intentionally clean sandbox with /main and no merge in progress:
+
+```bash
+PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/dedicated/sandbox npm run test:live
+```
+
+For explicit branch-creation mutation validation:
+
+```bash
+PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/dedicated/sandbox \
+PI_PLASTIC_ALLOW_MUTATION_TESTS=true \
+npm run test:live:branch-create
+```
+
+The branch test creates uniquely named hierarchical branches, checks explicit-parent/root guards, does not switch the workspace and removes its temporary branches under its cleanup contract. Do not run broad mutation suites merely to add evidence; inspect exact scope first.
+
+For behavior changes, report the narrow actual live test and resulting-state/cleanup evidence without private coordinates. If unavailable, mark live validation pending. Documentation-only/internal changes can mark live validation not applicable with a reason. Source-backed platform/client limits remain in the family references.
+
+## Tool-loading eval
+
+The package-owned behavioral eval is not a skill eval. Fresh SDK 1.1.0 JSON subprocesses compare all-active/balanced/loader-only mode, smallest-sufficient activations and sanitized provider-schema measurements.
+
+Dry-run validates configuration without live provider trials. Actual trials require an explicitly attested dedicated Plastic sandbox and an approved model. Destructive calls are blocked unless supported preflight previews; raw payload captures are deleted by default.
+
+Read the repository [eval guide](https://github.com/aefreedman/pi-plastic/blob/main/evals/tool-loading/README.md) for model restrictions, cases, metrics and result hygiene. Tests/eval harness files are intentionally repository-only rather than packed consumer dependencies.
+
+## Constrained sampling
+
+The package does not opt in to provider-side strict sampling. Public schemas include optional fields (at least workdir); OpenAI strict function schemas require closed objects and every declared property required. Pi forwards schemas without converting optional fields.
+
+`strict="prefer"` would therefore need either invalid requests or a breaking argument redesign. Tests prevent accidental opt-in until schemas are genuinely compatible. Runtime/TypeBox admission remains authoritative.
+
+Codex grammar capability does not imply strict JSON-schema capability. Grammar sampling is not used because these operations have structured multi-field arguments, not one bounded string language.
+
+## Documentation and packaging checks
+
+Keep README as a landing page, docs as the consumer reference, skill files as progressive workflow guidance, and workspace plans/private evidence outside the package. New topic pages retain date-prefixed filenames; update navigation and links when adding/moving content.
+
+Documentation tests verify relative links/anchors, every core tool route, schema-bearing coverage, concise README, current baseline claims and packed-document closure. Review `npm pack --dry-run` content as well as its file list: no tests/evals/private coordination material is added by splitting the manual.
+
+These are structural and execution checks, not a browser accessibility audit or proof that every agent will choose the right page. No provider-backed doc-reading eval is implied.

package/docs/2026-10-06-diffs-and-patches.md

@@ -0,0 +1,136 @@
+# Diffs and patches
+
+[Documentation index](README.md) · [Backend setup](2026-10-06-setup.md#diff-and-patch-backends) · [Safety and receipts](2026-10-06-safety-and-receipts.md)
+
+Use `plastic_diff` for bounded comparison evidence. Use `plastic_patch` to generate a review artifact. Neither opens the GUI diff; patch application is not exposed.
+
+## Choose the output you need
+
+| Need | Tool |
+|---|---|
+| Loaded/historical base against one local file | diff, file mode |
+| Two explicit historical selectors | diff, revisions mode |
+| Selected pending paths or a bounded all-pending set | diff, workspace mode |
+| A generated branch/spec review patch or an intentional new output file | patch |
+
+Status is the changed-path listing tool; diff only when content evidence is needed. Inspect artifacts before sharing: changed content can contain secrets, local paths, code or binary data. Display masking is not a source-code secret scanner.
+
+## Diff modes
+
+`plastic_diff` requires one explicit closed mode. The former specialized names are removed, not aliases.
+
+| Mode | Required scope | Behavior |
+|---|---|---|
+| file | path; optional revision | Omitted revision uses a verified loaded base; explicit revision skips status/base queries |
+| revisions | leftRevision and rightRevision | Two sequential owned exports; selectors retain unresolved identity unless observed independently |
+| workspace | Nonempty paths or allPending=true | Match pending scopes; includePrivate only with allPending |
+
+```text
+plastic_diff(mode="file", path="Assets/Example.txt", maxChars=3000)
+plastic_diff(mode="revisions", leftRevision="<left file-revision selector>", rightRevision="<right file-revision selector>")
+plastic_diff(mode="workspace", paths=["Assets/Example.txt"])
+```
+
+Workspace paths cap 20. maxFiles is 1–20, default 3 for all-pending/20 for scoped paths. Directories select pending descendants, while directory rows themselves are skipped. A moved source or destination selects the same observation.
+
+All modes return a closed versioned action diff envelope independent of text/JSON format. Comparison data records pending/comparison kind, origins/selectors/paths, observed loaded identity when available, bytes/binary flags, backend/capture evidence, excerpts and counts.
+
+## Loaded bases and snapshots
+
+Loaded ownership comes from strict UTF-8 status/fileinfo/ls observations: a genuine qualified file revision ID, repository/server agreement, and exported bytes matching loaded metadata's MD5/SHA1 hash.
+
+- Deleted files use the frozen loaded root tree deliberately.
+- Local moves use observed OldPath metadata.
+- Added and explicitly selected private files use an intentional empty base; added-empty is distinct from unchanged.
+- Unavailable/nodata/unsupported ownership fails, never becomes an empty side.
+- No changeset number becomes a file revision, bare-ID ownership guess, or failed-query fallback.
+- Mixed-Xlink ownership remains unverified.
+
+Historical exports use new owned temporary destinations outside the workspace. `cm cat --file=` writes that destination; it is not an input selector. The tools own their exports/cleanup.
+
+Local snapshots require physical workspace containment, regular non-symlink files, bounded descriptor reads, and stable observable identity/size/timestamps/namespace. Retained bytes are independent of later edits, not an atomic filesystem/repository snapshot. Cleanup completes before success.
+
+## Diff result and failure interpretation
+
+Text comparison requires one configured GNU/POSIX `diff -u`:
+
+- Exit 0 with empty output, or exit 1 with complete fatal-UTF-8 structurally consistent unified hunks, is admitted.
+- NUL/invalid-UTF-8 content uses exact internal byte equality.
+- Signal/null terminal, stderr, timeout, malformed/partial streams, failed/oversized exports or cleanup failures return sanitized errors.
+- English GNU no-final-newline markers are supported; unverified variants fail closed.
+- No retry or backend substitution.
+
+Workspace results preserve per-file failures plus parsed/eligible/selected/attempted/completed/failed/skipped/unattempted/limited/returned/omitted counts, private exclusions and unmatched paths. Overall ok can be false while earlier comparisons remain recorded. Inspect read/projection completeness before declaring a review complete.
+
+```js
+const dto = await tools.plastic_diff({mode: "workspace", paths: ["Assets/Example.txt"]});
+text({ok: dto.ok, completeness: dto.completeness, data: dto.data});
+```
+
+This deliberately keeps partial evidence rather than turning failure into an empty comparison.
+
+### Diff bounds
+
+| Bound | Value |
+|---|---|
+| Each retained/export-read side | 4 MiB; not a hard cat disk-transfer quota |
+| Command capture | 1 MiB stdout /64 KiB stderr |
+| Process timeout initiation | 30 seconds plus collector escalation |
+| File/revisions excerpt | 8,000 characters default; 500–20,000 |
+| Workspace excerpt | 3,000 default; 500–8,000 |
+| Compact DTO | 131,072 UTF-8 bytes |
+| Presentation | 24,000 characters |
+
+Excerpts use surrogate-safe UTF-16 source/marker/omission counts and are not guaranteed applyable patches. Workspace aggregate projection may omit whole outcomes with explicit counts, never clip IDs. JSON remains valid and may direct callers to structuredContent instead of duplicating it.
+
+## Patch generation
+
+`plastic_patch` uses `cm patch` for generation only. Defaults: JSON presentation, clean=false, integration=false; current backend precedence and local-selector qualification remain.
+
+```text
+plastic_patch(source="br:/main/owned-feature", integration=true)
+plastic_patch(source="br:/main/owned-feature", clean=true, integration=true, output="new-review.patch")
+plastic_patch(source="<left spec>", destination="<right spec>")
+plastic_patch(source="<branch spec>", toolPath="<verified patch-capable executable>", format="text")
+```
+
+`output` is a new artifact path, not the text/JSON presentation selector. `format="text"` is additive presentation. `toolPath` is the highest-priority one-call backend override; consult [setup](2026-10-06-setup.md#diff-and-patch-backends) before selecting a backend.
+
+Unqualified branch selectors are qualified only from the current workspace selector's exact repository/server. Otherwise supply a complete qualified branch. No alias equivalence, immutable/head selection, move encoding, workspace-effect, custom-backend-effect or rollback proof is invented.
+
+The receipt separates:
+
+1. Requested/effective selectors and backend, with a redacted command projection.
+2. One generation attempt and capture.
+3. Bounded observed artifact bytes, SHA256, UTF-8/character/excerpt evidence where admitted.
+4. Atomic no-overwrite publication, separate from observation.
+5. Owned cleanup/retention and recovery directory information.
+
+No `--apply`, backend/strategy retry, probe fallback or workspace mutation follows. Server output may represent moves as moves or delete/add; don't assume representation without inspecting the generated artifact.
+
+## Publication and cleanup
+
+With no output path, admitted patch content is returned and owned temp cleanup follows the supported route. An empty omitted-output artifact is legitimate.
+
+Explicit output requires nonempty admitted bytes, then atomic exclusive hard-link publication from owned sibling staging. Existing destinations are never replaced. Failed/incomplete/warning captures cannot publish.
+
+Already observed artifacts/publication remain recorded after later failure. Possibly running/timed-out/aborted processes cause staging/recovery retention when cleanup cannot be justified; retirement does not prove the child stopped. Destination content, aliases and concurrent/global scope are not independently verified by publication alone.
+
+### Patch bounds and preflight
+
+| Bound | Value |
+|---|---|
+| Stable regular artifact read | 4 MiB |
+| Local selector read | 64 KiB |
+| Request / controls | 32 KiB UTF-8 /4096 UTF-16 code units |
+| DTO | 512 KiB UTF-8 |
+| Excerpt | 60,000 characters |
+| CM capture | 64 KiB stdout /16 KiB stderr |
+
+UTF-8 character/byte metrics are correlated, including truncated/opaque projections. Input/capture/observation/publication/outcome relationships are validated, not merely JSON shape.
+
+Preflight renders command intent; it may read local selector metadata, but does not stage, probe the backend, or generate a patch. It is not conflict analysis or artifact existence proof.
+
+## Validation scope
+
+Comparison source evidence is bounded to Windows CM 11.0.16.10371 and the tested GNU diff backends; macOS text-only/backend incompatibility evidence is documented in setup. Other client/platform/backends, mixed-Xlink/nodata ownership, foreign post-hooks and RPC remain unverified. Those limits are not permission to silently switch routes.