@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/docs/plans/2026-08-16-workflow-updates-plan.md

@@ -10,7 +10,7 @@ This plan implements the contracts in [WORKFLOW_UPDATES.md](../WORKFLOW_UPDATES.
 
 ## Outcome
 
-Pi Workflows will let a running agent, function action, shell action, or claimed runner publish durable structured updates without completing a node. Progress will be one optional update type with shared estimation and presentation helpers.
+pi-workflows will let a running agent, function action, shell action, or claimed runner publish durable structured updates without completing a node. Progress will be one optional update type with shared estimation and presentation helpers.
 
 The built-in monitor will report every accepted check, support optional progress tracks, show live timing in the widget, and deliver notifications without starting an assistant turn.
 
@@ -18,7 +18,7 @@ Interactive agent steps will keep their full model prompts while appearing as co
 
 ## Scope
 
-### Pi Workflows engine
+### pi-workflows engine
 
 - Add public update types and the action context that publishes them.
 - Add fenced update publication to the engine and run store.
@@ -456,7 +456,7 @@ Run package and real-Pi checks again after updating OnurPi. Run the tools skill
 - The built-in monitor reports every accepted check and has no quiet path.
 - The monitor discloses its finite safety ceiling.
 - TypeScript and Rust viewers agree on replayed progress.
-- All required checks pass in Pi Workflows and OnurPi.
+- All required checks pass in pi-workflows and OnurPi.
 - The published package, OnurPi pin, monitor skill source, and installed Pi copy agree.
 
 ## Risks and controls

package/docs/plans/2026-08-17-bundled-skills-plan.md

@@ -1,12 +1,12 @@
 ---
-title: Bundle Pi Workflows skills with the extension
+title: Bundle pi-workflows skills with the extension
 author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
 date: 2026-08-17
 ---
 
-# Bundle Pi Workflows skills with the extension
+# Bundle pi-workflows skills with the extension
 
-Pi Workflows should be the single source of truth for instructions that teach an agent how to use its extension and built-in workflows. Installing the Pi package should discover those skills with the extension, while Pi's normal package filters let users disable either resource type or an individual skill.
+pi-workflows should be the single source of truth for instructions that teach an agent how to use its extension and built-in workflows. Installing the Pi package should discover those skills with the extension, while Pi's normal package filters let users disable either resource type or an individual skill.
 
 ## Outcome
 
@@ -61,9 +61,9 @@ The `workflow` tool description remains the small always-available call contract
 4. Add tests that validate declared paths, required frontmatter, unique skill names, and packed files.
 5. Update README installation and configuration examples, including independent resource filtering.
 6. Pack the package and start the real Pi runtime from that artifact. Verify that `/skill:pi-workflows` and `/skill:monitor` are discovered with the extension, then verify that package filtering can hide the monitor skill without hiding the extension.
-7. Run all repository checks and Pi Reviewer, merge, release `0.7.0`, and verify npm contents.
+7. Run all repository checks and pi-reviewer, merge, release `0.7.0`, and verify npm contents.
 8. Pin `0.7.0` in OnurPi, forward the dependency's skills, and run OnurPi checks.
-9. Remove `agents/skills/monitor` from Tools, run the sync script, and verify that the installed skill now comes from the Pi Workflows package only.
+9. Remove `agents/skills/monitor` from Tools, run the sync script, and verify that the installed skill now comes from the pi-workflows package only.
 
 ## Acceptance criteria
 
@@ -73,7 +73,7 @@ The `workflow` tool description remains the small always-available call contract
 - The model can use the `workflow` tool from the new skill without larger workflow step messages.
 - npm contains the two `SKILL.md` files and their referenced documentation.
 - Tools contains no monitor skill source or synced duplicate.
-- Local checks, real-Pi end-to-end tests, Pi Reviewer, and CI pass.
+- Local checks, real-Pi end-to-end tests, pi-reviewer, and CI pass.
 
 ## Verification
 

package/docs/plans/2026-08-19-human-decision-gates-plan.md

@@ -6,9 +6,9 @@ date: 2026-08-19
 
 # Add reusable human decision gates
 
-Pi Workflows must let any workflow stop after a proposal, ask the operator in Pi and Telegram, and continue from a verified human choice. A `replan` choice must collect the operator's exact alternative text, send it back to planning, and present the revised plan for another decision.
+pi-workflows must let any workflow stop after a proposal, ask the operator in Pi and Telegram, and continue from a verified human choice. A `replan` choice must collect the operator's exact alternative text, send it back to planning, and present the revised plan for another decision.
 
-The canonical behavior and public contracts are in [Human decisions](../HUMAN_DECISIONS.md). This plan covers the practical implementation in Pi Workflows without changing Pi core or adding a persistent operating-system service.
+The canonical behavior and public contracts are in [Human decisions](../HUMAN_DECISIONS.md). This plan covers the practical implementation in pi-workflows without changing Pi core or adding a persistent operating-system service.
 
 ## Outcome
 
@@ -62,7 +62,7 @@ Pi and Telegram implement one channel interface. Workflows address a named audie
 - Add a Telegram channel using the Bot API and private profiles.
 - Add named audience resolution and private channel configuration.
 - Add a setup command that writes private configuration with mode `600`, references an existing mode-`0600` token file, and verifies the Telegram bot without reading the token into a prompt or printing it.
-- Keep Telegram optional. Pi Workflows must start and run normal workflows without Telegram configuration.
+- Keep Telegram optional. pi-workflows must start and run normal workflows without Telegram configuration.
 - Use one leased long-poll owner per Telegram profile across active Pi processes.
 
 ### Documentation and display
@@ -281,7 +281,7 @@ npx -y @simpledoc/simpledoc check
 git diff --check
 ```
 
-Run Pi Reviewer against the pushed branch. Fix every P0 and P1 finding and rerun it. Address valid P2 findings, but do not rerun review solely because of a P2-only change. Open or update a pull request and leave it unmerged unless merge is separately authorized.
+Run pi-reviewer against the pushed branch. Fix every P0 and P1 finding and rerun it. Address valid P2 findings, but do not rerun review solely because of a P2-only change. Open or update a pull request and leave it unmerged unless merge is separately authorized.
 
 ## Release
 
@@ -293,4 +293,4 @@ This work adds compatible public APIs and additive persisted records. Release it
 - **Other persistent data:** additive decision records, a rebuildable private channel index, and private channel configuration.
 - **Pi internals:** none.
 - **Public Pi API:** documented extension lifecycle plus command and UI methods only.
-- **Public Pi Workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.
+- **Public pi-workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.

package/docs/plans/2026-08-19-human-decision-presentations-plan.md

@@ -6,7 +6,7 @@ date: 2026-08-19
 
 # Add readable human decision presentations
 
-Pi Workflows currently sends a structured human decision body to Telegram with
+pi-workflows currently sends a structured human decision body to Telegram with
 `JSON.stringify()`. A plan approval therefore reaches the operator as machine
 JSON. Pi also shows only the decision title in its basic selection prompt.
 

package/docs/plans/2026-08-19-provider-compatible-workflow-tool-schema-plan.md

@@ -41,5 +41,5 @@ Fix the workflow tool schema so strict OpenAI-compatible providers accept it wit
 - The strict local endpoint accepts both workflow tool schemas.
 - Runtime parsing rejects malformed calls before execution.
 - `npm run check`, `npm run test:e2e`, Rust tests, Slophammer checks, and `git diff --check` pass.
-- Pi Reviewer reports no P0 or P1 findings.
+- pi-reviewer reports no P0 or P1 findings.
 - PR #33 CI passes before merge.

package/docs/plans/2026-08-19-workflow-composition-plan.md

@@ -6,7 +6,7 @@ date: 2026-08-19
 
 # Add typed workflow composition and automatic repair
 
-Pi Workflows needs reusable nested workflows with normal TypeScript imports. Monitor must be able to devise and implement a repair when mutation is authorized. Autoimplement must move back to solution design when new evidence invalidates its plan, correct failed reviewer commands, track P0, P1, and P2 findings, and use long CI waits for additional local testing.
+pi-workflows needs reusable nested workflows with normal TypeScript imports. Monitor must be able to devise and implement a repair when mutation is authorized. Autoimplement must move back to solution design when new evidence invalidates its plan, correct failed reviewer commands, track P0, P1, and P2 findings, and use long CI waits for additional local testing.
 
 The canonical behavior is in [Workflow composition](../WORKFLOW_COMPOSITION.md).
 
@@ -56,7 +56,7 @@ The package will ship `autoplan`, `autoimplement`, and `monitor` as compatible b
 - Track P0, P1, and P2 review findings by round.
 - Rerun review only after P0 or P1 work.
 - Permit P2 work without another reviewer round.
-- Generate, validate, execute, and correct exact Pi Reviewer commands.
+- Generate, validate, execute, and correct exact pi-reviewer commands.
 - Track PR comments, CI, merge, and final PR reporting.
 - Bound one CI watch to five minutes.
 - Route a long CI wait to useful local testing before checking CI again.
@@ -71,7 +71,7 @@ The package will ship `autoplan`, `autoimplement`, and `monitor` as compatible b
 - Do not permit recursive include graphs.
 - Do not add unrestricted model-selected node names.
 - Do not let monitor mutate a target without explicit authorization.
-- Do not replace Pi Reviewer with another reviewer after an invocation failure.
+- Do not replace pi-reviewer with another reviewer after an invocation failure.
 - Do not merge before required gates pass or an allowed unrelated failure is recorded.
 - Do not rewrite existing terminal run bundles.
 
@@ -214,7 +214,7 @@ CI
 
 The structured plan input is optional because the plan can already exist in conversation context or canonical documentation. Its absence never authorizes initial autoplan. Autoimplement blocks when no clear plan exists, skips autodoc for current documentation, and records every evidence-driven revision through autodoc before continuing.
 
-The workflow will collect all review rounds in its final output. It will never rerun Pi Reviewer solely because P2 work changed files.
+The workflow will collect all review rounds in its final output. It will never rerun pi-reviewer solely because P2 work changed files.
 
 ### 8. Monitor repair
 
@@ -278,7 +278,7 @@ npx -y @simpledoc/simpledoc check
 git diff --check
 ```
 
-Run Pi Reviewer against the pushed branch. Fix every P0 and P1 finding and rerun it. P2-only changes do not require another reviewer run unless they expose a new P0 or P1 concern. Check PR comments and CI after review passes.
+Run pi-reviewer against the pushed branch. Fix every P0 and P1 finding and rerun it. P2-only changes do not require another reviewer run unless they expose a new P0 or P1 concern. Check PR comments and CI after review passes.
 
 ## Release
 
@@ -305,4 +305,4 @@ The package and Rust viewer version is `0.10.0`.
 - **Other persistent data:** additive mount, source, digest, review, and CI evidence in existing run bundles.
 - **Pi internals:** none.
 - **Public Pi API:** existing documented extension APIs only.
-- **Public Pi Workflows API:** generic input and exits, direct and dynamic `includeWorkflow()`, and `defineWorkflowRegistry()`.
+- **Public pi-workflows API:** generic input and exits, direct and dynamic `includeWorkflow()`, and `defineWorkflowRegistry()`.

package/docs/plans/2026-08-20-autoimplement-blocker-challenge-plan.md

@@ -12,7 +12,7 @@ The canonical workflow behavior is in [Workflow authoring reference](../workflow
 
 ## Outcome
 
-Add one independent `challengeBlocker` agent node to the built-in autoimplement workflow. Use only existing public Pi Workflows primitives. Keep the graph explicit and reuse the existing redesign include and terminal blocked result.
+Add one independent `challengeBlocker` agent node to the built-in autoimplement workflow. Use only existing public pi-workflows primitives. Keep the graph explicit and reuse the existing redesign include and terminal blocked result.
 
 The challenge asks these questions in plain terms:
 
@@ -120,7 +120,7 @@ Review the final diff for missing blocker routes, accidental unbounded loops, an
 ## Boundaries
 
 - Preserve current run-bundle schemas unless a schema change is required. Do not add a persistence layer.
-- Use existing public Pi Workflows primitives only. Do not change Pi core.
+- Use existing public pi-workflows primitives only. Do not change Pi core.
 - Keep explicit human and protected authorization boundaries intact.
 - Use a hard cutover. Do not retain a legacy blocker route.
 - Preserve unrelated work and do not modify other repositories.
@@ -135,4 +135,4 @@ Review the final diff for missing blocker routes, accidental unbounded loops, an
 - **Other persistent data:** none beyond the existing run bundle records for normal node outputs.
 - **Pi internals:** none.
 - **Public Pi API:** existing documented extension APIs only.
-- **Public Pi Workflows API:** existing agent, compute, edge, and included-workflow primitives only.
+- **Public pi-workflows API:** existing agent, compute, edge, and included-workflow primitives only.

package/docs/plans/2026-08-20-bounded-command-batches-plan.md

@@ -0,0 +1,206 @@
+---
+title: Run independent commands in bounded batches
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Run independent commands in bounded batches
+
+Autoimplement runs independent commands one after another today. This makes multi-repository review and CI waits take longer than needed.
+
+Add one public `runCommandBatch` helper. Use it for independent pi-reviewer commands, pending CI watches, and independent local verification commands. Keep model turns and commands that change repositories or remote systems in their current order.
+
+The canonical workflow behavior is in [Workflow authoring reference](../workflows.md#built-in-planning-and-implementation). Command progress follows [Workflow updates](../WORKFLOW_UPDATES.md#command-batch-updates).
+
+## Outcome
+
+Add one Pi-independent helper under `src/workflows`. The helper runs a validated list of commands with a fixed concurrency limit. It uses the existing `runShellAction` implementation for process creation, output capture, timeout, and process-group cleanup.
+
+This is a function called by ordinary action nodes. It is not a workflow node, graph scheduler, fan-out primitive, controller, service, or new persistence system.
+
+## Public contract
+
+The public request contains a command list and one concurrency limit:
+
+```ts
+type CommandBatchItem = {
+  id: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxOutputChars: number;
+};
+
+type CommandBatchRequest = {
+  items: CommandBatchItem[];
+  maxConcurrency: number;
+};
+```
+
+Each item ID must be unique in the request. `cwd` must be absolute. Timeouts, output limits, item count, and concurrency must stay within package limits. Items cannot set `env`, `stdin`, `shell`, or `allowNonZeroExit`. Commands run without a shell.
+
+The result uses the schema `pi-workflows.command-batch-result.v1`. Results stay in input order even when commands finish in a different order. Each item records:
+
+- its ID;
+- `succeeded`, `failed`, `timedOut`, or `cancelled`;
+- command, arguments, and working directory;
+- stdout and stderr;
+- exit code and signal;
+- duration;
+- stdout and stderr truncation flags;
+- a bounded error message when one exists.
+
+A nonzero exit, spawn failure, or item timeout affects only that item. Invalid batch input is a batch error.
+
+## Execution
+
+`runCommandBatch` uses a fixed worker pool. It starts no more than `maxConcurrency` commands. Each worker checks the abort signal before it takes an item. `runShellAction` checks again before it starts the process.
+
+The helper accepts an optional completion callback. Autoimplement uses the callback for small progress updates. The callback is observational. Its updates cannot complete a node or satisfy review, CI, or verification routing.
+
+The helper does not interpret repository, review, CI, or test results. Autoimplement owns that meaning.
+
+## Cancellation and interruption
+
+The workflow action passes its abort signal to the helper. An abort stops active process groups through the existing `runShellAction` SIGTERM and bounded SIGKILL path. Workers do not start queued items after the abort.
+
+Accepted batch outputs use the existing run trace and artifact files. Large strings use normal artifact externalization.
+
+If the process stops before the action output is accepted, resume runs that batch again. This is allowed only for read-only reviewer and CI commands or isolated local verification commands. The first implementation does not add partial-item recovery or another store.
+
+## Autoimplement use
+
+### Review
+
+Publication reports every repository with a pushed pull request:
+
+```ts
+type PublishedRepository = {
+  repository: string;
+  baseBranch: string;
+  headRevision: string;
+  pr: string;
+  dependencyFingerprint?: string;
+};
+```
+
+Autoimplement derives a stable item ID from the canonical repository path. It builds `pi-reviewer --base <branch>` directly from each published record and runs ready reviewer commands in one bounded batch.
+
+Review findings stay grouped by repository ID and reviewed head. A later round runs only for a repository whose pushed head or relevant dependency fingerprint changed. P0 and P1 findings still require another review after fixes. P2-only work keeps the current rule: address proportionate findings, verify and push, then continue without another review only because of that P2 work.
+
+### CI watches
+
+Autoimplement first inspects every pull request without waiting. It accepts only supported pending `gh pr checks --watch` or `gh run watch` descriptors, then normalizes each one to `gh pr checks <validated PR URL> --watch`. It rejects repository and pull-request overrides, so a watch result cannot satisfy a different pull request. Each watch keeps the current five-minute limit. Results are assessed per pull request. A failed or timed-out watch does not hide results for other pull requests.
+
+If checks remain pending, autoimplement runs other useful local tests before it inspects CI again. It does not invent an ETA.
+
+### Local verification
+
+The verification model step selects commands, but does not run the batch itself. Autoimplement validates the descriptors, runs one command per independent repository with a low concurrency limit, then uses a later model step to assess all results.
+
+Verification batches reject shell wrappers, environment overrides, stdin, Git or GitHub mutation commands, package publication commands, duplicate working directories, and paths outside the reported repositories. Fixes and other model work remain outside the batch.
+
+### Concurrency settings
+
+Autoimplement adds optional reviewer, CI-watch, and verification concurrency settings. Existing input remains valid. One command always runs with concurrency one.
+
+Use conservative defaults:
+
+- reviewer: 4;
+- CI watch: 4;
+- verification: 2.
+
+Cap each value at 8. Repository instructions or explicit input can lower these values.
+
+## Progress and reporting
+
+Each settled item can publish a metadata-only `pi-workflows.command-batch-item.v1` update. The update contains the batch kind, item ID, outcome, completed count, and total count. It does not contain stdout, stderr, environment data, credentials, or private provider payloads.
+
+Only the accepted action output controls routing. Final reports group review, CI, and verification evidence by repository and revision. Single-repository reports keep their current fields and meaning.
+
+Reviewer or CI output that reaches its capture limit is incomplete. Autoimplement must not classify truncated output as clean.
+
+## Implementation
+
+1. Add command-batch types, validation, worker-pool execution, per-item results, truncation flags, cancellation, and the completion callback in `src/workflows/command-batch.ts`.
+2. Export the public helper and types from `src/workflows/index.ts`.
+3. Add an internal truncation check in `src/workflows/shell.ts` without changing `ShellActionResult` or singular shell output.
+4. Add autoimplement-only publication normalization, command validation, stable repository IDs, and concurrency parsing in `src/builtins/autoimplement-command-batches.ts` when separation keeps the main workflow clear.
+5. Refactor `src/builtins/autoimplement.workflow.ts` to use batch actions for review, pending CI watches, and independent verification.
+6. Remove the superseded singular reviewer and CI-watch paths in the same change.
+7. Add `examples/workflows/command-batch.workflow.ts` and update the bundled autoimplement skill.
+8. Bump the built-in autoimplement revision from 4 to 5 in `src/builtins/catalog.ts`.
+
+## Tests
+
+Add `test/command-batch.test.ts` for:
+
+- descriptor validation and bounds;
+- empty and one-item requests;
+- deterministic input-order results;
+- measured concurrency limits;
+- mixed success and failure;
+- spawn failure and nonzero exit;
+- per-item timeout;
+- abort before and during execution;
+- no queued starts after abort;
+- process-group cleanup;
+- output limits, truncation flags, and UTF-8;
+- completion callback behavior.
+
+Update autoimplement tests for:
+
+- current single-repository input and output;
+- one and several published repositories;
+- parallel reviewer execution and isolated findings;
+- changed-head and dependency-fingerprint reruns;
+- P0, P1, P2, lower, command failure, timeout, and truncation;
+- parallel pending CI watches and per-PR assessment;
+- independent verification and its lower limit;
+- unsafe verification command rejection;
+- accepted-output resume and full replay of an unaccepted batch;
+- metadata-only progress updates;
+- built-in revision 5 and old active-run refusal.
+
+Use temporary repositories and fake `pi-reviewer` and `gh` commands in end-to-end tests. Do not call a real model or mutate a remote system.
+
+## Verification
+
+Run these checks before completion:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+git diff --check
+```
+
+Keep coverage at or above 85 percent. Verify discovery through a fresh Pi process and the installed package path.
+
+## Rollout
+
+Keep the command-batch result and update schemas at v1 during alpha. Use a hard cutover. Do not keep singular reviewer or CI-watch execution beside the batch path. Do not add migration readers, dual paths, aliases, or feature flags.
+
+The autoimplement built-in revision changes from 4 to 5. Active runs from revision 4 must start again. Terminal bundles remain readable.
+
+Do not publish a package or create a release without separate authorization.
+
+## Boundaries
+
+- Do not add a workflow-engine primitive.
+- Do not add a controller, child workflow, service, database, queue, webhook receiver, distributed worker, or artifact store.
+- Do not parallelize model turns, code edits, comment fixes, pushes, pull request mutations, merges, releases, or rollbacks.
+- Do not add a full multi-repository campaign or target graph.
+- Do not add partial-item durable recovery until measured replay cost justifies it.
+- Do not infer command independence, dependency relations, resource limits, remote authority, or CI ETA.
+- Do not change Pi core, private Pi APIs, external tools, providers, credentials, or repository policy.
+
+## Contract impact
+
+- **Session state:** normal workflow messages and tool results only.
+- **Other persistent data:** normal node outputs, updates, trace records, and artifacts in existing run bundles.
+- **Pi internals:** none.
+- **Public Pi API:** existing documented extension APIs only.
+- **Public Pi Workflows API:** new `runCommandBatch` helper and command-batch types; existing action, update, shell, timeout, and cancellation interfaces.

package/docs/plans/2026-08-20-herdr-plugin-sync-plan.md

@@ -6,9 +6,9 @@ date: 2026-08-20
 
 # Keep the Herdr plugin linked after package updates
 
-Pi Workflows ships its Herdr plugin inside the npm package. Herdr records the package's absolute path. npm can move an installed package between nested and hoisted `node_modules` directories during an update, which leaves Herdr linked to a path that no longer exists.
+pi-workflows ships its Herdr plugin inside the npm package. Herdr records the package's absolute path. npm can move an installed package between nested and hoisted `node_modules` directories during an update, which leaves Herdr linked to a path that no longer exists.
 
-Pi Workflows will own one explicit command that finds its own package and repairs this link. OnurPi will call that command after it installs an exact reviewed Pi Workflows release. OnurPi will not contain Herdr paths, manifests, or link-repair rules.
+pi-workflows will own one explicit command that finds its own package and repairs this link. OnurPi will call that command after it installs an exact reviewed pi-workflows release. OnurPi will not contain Herdr paths, manifests, or link-repair rules.
 
 ## Outcome
 
@@ -24,7 +24,7 @@ The command validates the bundled package before it changes Herdr. It then creat
 
 ## Scope
 
-### Pi Workflows
+### pi-workflows
 
 - Resolve the installed package root from the running CLI.
 - Validate `package.json`, `herdr-plugin.toml`, and the bundled viewer before changing Herdr.
@@ -37,9 +37,9 @@ The command validates the bundled package before it changes Herdr. It then creat
 
 ### OnurPi
 
-- Keep the Pi Workflows dependency pinned to an exact reviewed release.
+- Keep the pi-workflows dependency pinned to an exact reviewed release.
 - Invoke the local `pi-workflows herdr sync --json` command from an explicit TypeScript sync script after dependency installation.
-- Accept the versioned result and keep Herdr-specific behavior in Pi Workflows.
+- Accept the versioned result and keep Herdr-specific behavior in pi-workflows.
 - Keep package installation free of `postinstall` side effects.
 
 ## Non-goals
@@ -66,19 +66,19 @@ The JSON result uses schema `pi-workflows.herdr-sync.v1` and contains:
 
 A missing Herdr executable returns `unavailable` with exit code zero because Herdr is an optional integration. Every other failure returns a nonzero exit code and does not claim success.
 
-The command preflights the new package before unlinking an old registration. Herdr currently exposes separate unlink and link commands, so replacement cannot be atomic. If replacement fails, Pi Workflows makes one restore attempt only when the previous package root still passes the same validation. It then reports the state found by a fresh Herdr query.
+The command preflights the new package before unlinking an old registration. Herdr currently exposes separate unlink and link commands, so replacement cannot be atomic. If replacement fails, pi-workflows makes one restore attempt only when the previous package root still passes the same validation. It then reports the state found by a fresh Herdr query.
 
 Concurrent sync commands converge on the same target. After a failed or ambiguous mutation, the command queries Herdr and adopts the result only when another process already reached the exact expected state. It does not repeat the same mutation blindly.
 
 ## Compatibility
 
-Existing `herdr setup` callers use the same implementation. Other Pi Workflows CLI commands do not change. The npm package remains the only source of the plugin manifest and viewer.
+Existing `herdr setup` callers use the same implementation. Other pi-workflows CLI commands do not change. The npm package remains the only source of the plugin manifest and viewer.
 
 OnurPi adds only invocation timing and result handling. It does not parse the Herdr manifest or issue link commands.
 
 ## Verification
 
-### Pi Workflows
+### pi-workflows
 
 - Test first link, unchanged link, disabled link, moved package path, stale path, and version update.
 - Test missing Herdr, malformed manifests, malformed plugin records, command failures, post-action mismatches, and bounded restore behavior.
@@ -95,7 +95,7 @@ OnurPi adds only invocation timing and result handling. It does not parse the He
 
 ### Adoption
 
-After a separately approved Pi Workflows release, update OnurPi to that exact version and run:
+After a separately approved pi-workflows release, update OnurPi to that exact version and run:
 
 ```bash
 npm run workflows:sync