From b2f2379709dcd6a4661dce2502bb9cd59a8c3213 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:36:00 -0400
Subject: [PATCH 01/16] docs: plan wfctl install lifecycle

---
 ...26-07-03-wfctl-install-lifecycle-design.md |  92 +++++++
 .../2026-07-03-wfctl-install-lifecycle.md     | 231 ++++++++++++++++++
 2 files changed, 323 insertions(+)
 create mode 100644 docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
 create mode 100644 docs/plans/2026-07-03-wfctl-install-lifecycle.md

diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md b/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
new file mode 100644
index 00000000..2eb48e7a
--- /dev/null
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
@@ -0,0 +1,92 @@
+# wfctl Install Lifecycle Design
+
+## Global Design Guidance
+
+Source: workspace `AGENTS.md`, `docs/AGENT_GUIDE.md`, `docs/REPO_LAYOUT.md`, `docs/PORTFOLIO.md`, `docs/FOLLOWUPS.md`
+
+| guidance | design response |
+|---|---|
+| Prefer existing tool/plugin capabilities over rebuilding | Document existing `wfctl update`, release assets, Homebrew formula automation, `wfctl plugin add/lock/install/ci/update/remove`, and global plugin flags instead of adding installer code. |
+| Update docs when behavior or commands change | Treat `README.md`, `docs/WFCTL.md`, and generated website inputs as canonical docs surfaces. |
+| Use real Workflow app/tool boundaries for scenario-like proof | Validate docs against actual release assets, current CLI help, Homebrew formula metadata, and local command behavior. |
+| Keep examples under documented repo layout | Add docs under `docs/`; no new examples or scratch roots. |
+
+Portfolio inventory: `docs/PORTFOLIO.md` lists `workflow`, `homebrew-tap`, and `gocodealone-website`; `docs/FOLLOWUPS.md` has no existing wfctl install-doc follow-up. Existing release automation and tap publication are reused.
+
+## Goal
+
+Make wfctl installation, update, and plugin lifecycle documentation accurate across Workflow, the GoCodeAlone Homebrew tap, and the website surfaces that advertise wfctl.
+
+## Current Evidence
+
+- Latest Workflow release checked on 2026-07-03: `v0.84.3`, with raw `wfctl-{darwin,linux}-{amd64,arm64}`, `wfctl-windows-amd64.exe`, and `checksums.txt` assets.
+- Workflow release workflow publishes checksums and dispatches `update-wfctl` to `GoCodeAlone/homebrew-tap` for stable tags.
+- `homebrew-tap` `origin/main` has `Formula/wfctl.rb` at `0.84.3`; local brew cache may lag until `brew update`.
+- `homebrew-tap` `main` has no branch protection as of 2026-07-03, so generated formula PRs are not blocked by required review settings. PR #59 (`automation/update-wfctl-v0.84.3`) merged after CodeQL checks with only a Copilot comment.
+- `wfctl` already supports `update`, `update --check`, project plugin manifest/lock commands, `plugin ci`, and `-g/--global` plugin installs.
+
+## Recommended Approach
+
+Use a documentation-first repair.
+
+1. Workflow owns canonical wfctl installation and plugin lifecycle docs.
+2. Homebrew tap owns concise tap/formula docs and update/troubleshooting instructions.
+3. Website hardcoded marketing copy points to the maintained install surfaces and stops pinning stale wfctl versions.
+4. Releases and generated docs flow through existing Workflow release and website sync-docs automation.
+
+Alternative considered: add a shell installer script. Rejected for now because current published assets, checksums, `wfctl update`, and Homebrew formula already cover install/update needs; a script would add another maintenance and trust surface.
+
+Alternative considered: make Homebrew the only recommended path. Rejected because Linux CI, Windows users, and browser/manual downloads need a documented non-Homebrew path.
+
+## Scope
+
+In scope:
+
+- Replace stale README install one-liners.
+- Add a dedicated wfctl installation/lifecycle doc covering Homebrew, terminal release download, browser/manual download, source install, self-update, PATH, and verification.
+- Expand plugin lifecycle docs: project manifest, lockfile, CI install, global install, update, remove, and compatibility/checksum notes.
+- Expand the tap README with tap setup, formulas, install/upgrade examples, and automation notes.
+- Verify that generated Homebrew formula PRs can merge without mandatory reviews; if required reviews are later enabled, remove that branch requirement or add an explicit generated-PR bypass before relying on auto-merge.
+- Update website hardcoded wfctl install snippets away from stale `v0.60.17`.
+- After PRs merge, release Workflow and the website as needed, then verify downstream repository dispatches ran: Homebrew tap formula update, workflow-registry sync, workflow-scenarios bump, workflow-editor notification, website docs sync, and multisite ingest.
+
+Out of scope:
+
+- New installer binaries or install scripts.
+- Changing release asset names.
+- Changing plugin installer behavior.
+- Automatically refreshing all generated website docs before Workflow docs are released.
+
+## Security Review
+
+The docs must not encourage unauthenticated blind execution. Non-Homebrew terminal installs include downloading `checksums.txt` and verifying SHA-256 before moving the binary into `PATH`. Homebrew uses formula SHA-256 verification. `go install` is documented as a source/developer path, not the preferred release path. Plugin docs call out checksum verification, lockfiles for CI, and the risk of `--skip-checksum`.
+
+## Infrastructure Impact
+
+No runtime infrastructure changes. Release impact is limited to normal Workflow and website release pipelines. Homebrew tap updates continue through existing repository dispatch. Generated PR auto-merge depends on repository settings not requiring human review for bot-created formula PRs.
+
+## Multi-Component Validation
+
+Validation must cover:
+
+- GitHub release asset existence and checksums for latest stable Workflow release.
+- Local CLI help for documented `wfctl update` and plugin lifecycle commands.
+- Homebrew tap formula version and formula syntax/test where available.
+- Website build or at least type/build validation after copy changes.
+- Post-merge release and downstream automation: GitHub Actions release jobs complete successfully; generated tap PR merges; website docs sync PR and release/deploy workflows complete.
+
+## Assumptions
+
+- Workflow `v0.84.3` is still the latest stable release at implementation time; if a newer stable release appears, docs use non-pinned `latest` commands where possible and cite the exact checked version only as evidence.
+- `gocodealone-website` generated docs consume Workflow docs after Workflow release/sync; hardcoded website copy must be fixed separately.
+- Homebrew users may need `brew update` before seeing a just-merged formula.
+
+## Rollback
+
+Docs-only rollback: revert the documentation PRs. Release rollback: cut a new Workflow/website patch release from the reverted state if bad install docs were published. Tap README rollback: revert tap docs PR; formulas are unchanged by this design. If a downstream dispatch fails after a release, rerun the failed workflow after fixing the blocker; do not edit generated formula checksums by hand.
+
+## Self-Challenge
+
+1. The laziest solution is only patching `README.md`; rejected because stale instructions also exist in `docs/WFCTL.md`, website copy, and tap docs.
+2. Fragile assumption: Homebrew freshness. Mitigation: document `brew update` and validate `origin/main` formula separately from local brew cache.
+3. Potential YAGNI: extensive plugin lifecycle prose. Kept because the user explicitly asked for global install, update/upgrade plugins, and lifecycle parity with plugin managers.
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
new file mode 100644
index 00000000..7299ba5f
--- /dev/null
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
@@ -0,0 +1,231 @@
+# wfctl Install Lifecycle Implementation Plan
+
+> **For the implementing agent:** REQUIRED SUB-SKILL: Use autodev:executing-plans to implement this plan task-by-task.
+
+**Goal:** Publish verified wfctl install, update, and plugin lifecycle documentation across Workflow, the Homebrew tap, and website surfaces.
+
+**Architecture:** Workflow is the canonical source for wfctl docs. Homebrew tap documents tap-specific setup and formula inventory. Website changes avoid stale pinned install commands and rely on generated Workflow docs after release.
+
+**Tech Stack:** Markdown docs, Go `wfctl` CLI help validation, Homebrew formula metadata, Vite/React website.
+
+**Base branch:** main
+
+---
+
+## Scope Manifest
+
+**PR Count:** 3
+**Tasks:** 4
+**Estimated Lines of Change:** ~500
+
+**Out of scope:**
+- New installer scripts or release asset names.
+- Plugin installer behavior changes.
+- Generated website docs refresh before Workflow docs release.
+
+**PR Grouping:**
+
+| PR # | Title | Tasks | Branch |
+|------|-------|-------|--------|
+| 1 | docs: clarify wfctl install and plugin lifecycle | Task 1 | docs/wfctl-install-lifecycle |
+| 2 | docs: document GoCodeAlone Homebrew tap usage | Task 2 | docs/tap-install-readme |
+| 3 | docs: remove stale wfctl install copy and release docs | Task 3, Task 4 | docs/wfctl-install-copy |
+
+**Status:** Draft
+
+## Task 1: Workflow Canonical wfctl Docs
+
+**Files:**
+- Create: `docs/WFCTL_INSTALLATION.md`
+- Modify: `README.md`
+- Modify: `docs/WFCTL.md`
+- Modify: `docs/PLUGIN_DEVELOPMENT_GUIDE.md`
+
+**Step 1: Write docs**
+
+Add a dedicated installation/lifecycle guide covering:
+
+- Homebrew: `brew tap gocodealone/tap`, `brew install wfctl`, `brew upgrade wfctl`, `brew update`.
+- Terminal release install without Homebrew: detect OS/arch, download latest raw binary and `checksums.txt`, verify SHA-256, `chmod +x`, move into `PATH`.
+- Browser/manual install: GitHub Releases page, choose matching asset, download `checksums.txt`, verify locally, make executable, move into `PATH`.
+- Windows manual install: download `wfctl-windows-amd64.exe`, verify via `certutil -hashfile`, add directory to `PATH`.
+- Source install: `go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest` for Go users/devs.
+- Self-update: `wfctl update --check`, `wfctl update`; Homebrew users should prefer `brew upgrade wfctl`.
+- Plugin lifecycle: `plugin search`, `add`, `lock`, `install`, `ci`, `install -g`, `update`, `update --all`, `update -g --all`, `remove`, `list`, lockfiles, default project/global plugin directories, checksum/compatibility behavior.
+
+Update `README.md` and `docs/WFCTL.md` to link the guide instead of duplicating stale one-liners. Add a short pointer from `docs/PLUGIN_DEVELOPMENT_GUIDE.md`.
+
+**Step 2: Verify command surfaces**
+
+Run:
+
+```bash
+GOWORK=off go run ./cmd/wfctl --help >/tmp/wfctl-help.txt
+GOWORK=off go run ./cmd/wfctl update --help >/tmp/wfctl-update-help.txt
+GOWORK=off go run ./cmd/wfctl plugin --help >/tmp/wfctl-plugin-help.txt
+```
+
+Expected: each exits `0`; update help includes `--check`; plugin help includes `install`, `ci`, `update`, `remove`, and `-g or -global`.
+
+Run:
+
+```bash
+gh release view --repo GoCodeAlone/workflow --json tagName,assets --jq '.tagName,([.assets[].name]|join("\n"))'
+```
+
+Expected: latest stable tag and assets include `checksums.txt`, `wfctl-darwin-amd64`, `wfctl-darwin-arm64`, `wfctl-linux-amd64`, `wfctl-linux-arm64`, and `wfctl-windows-amd64.exe`.
+
+**Step 3: Commit**
+
+```bash
+git add README.md docs/WFCTL.md docs/WFCTL_INSTALLATION.md docs/PLUGIN_DEVELOPMENT_GUIDE.md docs/plans/2026-07-03-wfctl-install-lifecycle*.md
+git commit -m "docs: clarify wfctl install lifecycle"
+```
+
+Rollback: revert commit; no runtime state changes.
+
+## Task 2: Homebrew Tap README And Auto-Merge Guard
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `.github/workflows/update-wfctl.yml`
+- External setting: `GoCodeAlone/homebrew-tap` `main` branch protection
+
+**Step 1: Write tap docs**
+
+Expand the tap README with:
+
+- `brew tap gocodealone/tap`.
+- Available formula table for `wfctl`, `ratchet-cli`, and `claude-skills`.
+- Install, upgrade, pin/unpin, uninstall, and inspect examples.
+- Formula-specific examples: `brew install gocodealone/tap/wfctl`, `brew upgrade wfctl`.
+- Troubleshooting for stale formula cache via `brew update` and `brew info gocodealone/tap/wfctl`.
+- Automation note: Workflow releases dispatch `update-wfctl`; generated wfctl formula PRs are expected to auto-merge or admin-merge after checks when no unresolved review threads remain.
+- Branch-protection note: required reviews must not be mandatory for generated formula PRs unless a generated-PR bypass exists.
+
+**Step 2: Verify tap state**
+
+Run:
+
+```bash
+ruby -c Formula/wfctl.rb
+ruby -c Formula/ratchet-cli.rb
+brew info gocodealone/tap/wfctl
+gh pr list --repo GoCodeAlone/homebrew-tap --state all --limit 5 --json number,title,state --jq '.[] | [.number,.state,.title] | @tsv'
+gh api repos/GoCodeAlone/homebrew-tap/branches/main/protection --jq '.required_pull_request_reviews' || true
+gh pr view 59 --repo GoCodeAlone/homebrew-tap --json state,mergedAt,reviewDecision,statusCheckRollup --jq '{state,mergedAt,reviewDecision,checks:[.statusCheckRollup[]? | {name,conclusion,status}]}'
+```
+
+Expected: Ruby syntax OK; `brew info` reports the tap formula; recent PR list shows automated formula updates; branch protection is absent or has no required-review gate for generated formula PRs; recent generated wfctl formula PR merged with green checks.
+
+If the branch-protection check reports required reviews and no generated-PR bypass exists, update the repository rule before relying on the automation. If workflow inspection shows generated formula PRs no longer merge after checks, patch `.github/workflows/update-wfctl.yml` to restore the current behavior: open/update the generated PR, request Copilot review as advisory, wait for checks, leave open on failed checks or unresolved review threads, and admin-merge after green checks.
+
+**Step 3: Commit**
+
+```bash
+git add README.md .github/workflows/update-wfctl.yml
+git commit -m "docs: document Homebrew tap usage"
+```
+
+Rollback: revert commit; formulas unchanged.
+
+## Task 3: Website Install Copy
+
+**Files:**
+- Modify: `src/pages/PlatformPage.tsx`
+- Optionally modify generated docs only after Workflow docs release/sync.
+
+**Step 1: Replace stale install snippets**
+
+Replace hardcoded `go install ...@v0.60.17` snippets with current lifecycle copy that avoids pin drift:
+
+- Primary snippet: `brew install gocodealone/tap/wfctl`.
+- Secondary source command: `go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest`.
+- Link users to Workflow releases/docs for binary downloads rather than duplicating versioned asset names in React copy.
+
+**Step 2: Verify website build**
+
+Run:
+
+```bash
+npm install
+npm run build
+```
+
+Expected: build exits `0`.
+
+**Step 3: Commit**
+
+```bash
+git add src/pages/PlatformPage.tsx
+git commit -m "docs: refresh wfctl install copy"
+```
+
+Rollback: revert commit; no runtime state changes until website release.
+
+## Task 4: Post-Merge Release And Downstream Verification
+
+**Files:**
+- Inspect: `.github/workflows/release.yml`
+- Inspect: `.github/workflows/sync-docs.yml`
+- External repos: `GoCodeAlone/workflow`, `GoCodeAlone/homebrew-tap`, `GoCodeAlone/workflow-registry`, `GoCodeAlone/workflow-scenarios`, `GoCodeAlone/workflow-editor`, `GoCodeAlone/gocodealone-website`, `GoCodeAlone/gocodealone-multisite`
+
+**Step 1: Merge PRs after checks and review threads**
+
+For each PR, wait for checks to complete and inspect unresolved review threads. Merge with admin privileges only after checks are green and actionable review threads are resolved or explicitly non-blocking.
+
+```bash
+gh pr checks <PR> --repo <owner/repo>
+gh pr merge <PR> --repo <owner/repo> --admin --squash --delete-branch
+```
+
+Expected: PR state becomes `MERGED`.
+
+**Step 2: Release Workflow if Workflow docs changed**
+
+After the Workflow PR merges, create a new patch tag from `main` using the repository's current release convention, push the tag, then monitor `release.yml`.
+
+```bash
+gh release view --repo GoCodeAlone/workflow --json tagName
+git fetch origin main --tags
+git checkout main
+git pull --ff-only origin main
+git tag <new-workflow-tag>
+git push origin <new-workflow-tag>
+gh run list -R GoCodeAlone/workflow --workflow release.yml --limit 3
+```
+
+Expected: release run exits `success`, assets include `wfctl-*` and `checksums.txt`, and stable-release dispatch jobs trigger Homebrew tap, workflow-registry, workflow-scenarios, and workflow-editor.
+
+**Step 3: Verify Homebrew generated PR freshness**
+
+```bash
+gh run list --repo GoCodeAlone/homebrew-tap --workflow update-wfctl.yml --limit 3
+gh pr list --repo GoCodeAlone/homebrew-tap --state all --limit 5 --json number,state,title,headRefName
+brew update
+brew info gocodealone/tap/wfctl
+```
+
+Expected: generated wfctl formula update run is `success`, generated PR is merged, and `brew info` shows the latest Workflow version after `brew update`.
+
+**Step 4: Refresh and release website docs**
+
+After the Workflow release is available, run the website docs sync, merge its generated PR after checks, then release the website per its README by bumping `package.json` and pushing a `v*` tag.
+
+```bash
+gh workflow run sync-docs.yml -R GoCodeAlone/gocodealone-website
+gh pr list -R GoCodeAlone/gocodealone-website --head chore/sync-docs-snapshot
+git fetch origin main --tags
+git checkout main
+git pull --ff-only origin main
+# edit package.json version to the next patch version
+git commit -am "chore: bump website release to <new-website-version>"
+git tag v<new-website-version>
+git push origin main --tags
+gh run list -R GoCodeAlone/gocodealone-website --workflow release.yml --limit 3
+gh run list -R GoCodeAlone/gocodealone-multisite --workflow content-ingest.yml --limit 3
+```
+
+Expected: docs sync PR includes regenerated Workflow docs, website release succeeds, and multisite ingest succeeds.
+
+Rollback: if a bad docs release ships, revert the relevant PR, cut a follow-up patch release, and rerun failed downstream workflows from the corrected tag. Do not hand-edit generated tap checksums.

From b04173c380e0f65b8ca6dd1ba563413e3b357631 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:38:05 -0400
Subject: [PATCH 02/16] docs: review wfctl install lifecycle plan

---
 ...3-wfctl-install-lifecycle-design-review.md | 43 ++++++++++++++
 ...-03-wfctl-install-lifecycle-plan-review.md | 56 +++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 docs/plans/2026-07-03-wfctl-install-lifecycle-design-review.md
 create mode 100644 docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md

diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle-design-review.md b/docs/plans/2026-07-03-wfctl-install-lifecycle-design-review.md
new file mode 100644
index 00000000..bbd10b7b
--- /dev/null
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle-design-review.md
@@ -0,0 +1,43 @@
+### Adversarial Review Report
+
+**Phase:** design
+**Artifact:** docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
+**Status:** PASS
+
+**Findings (Critical):**
+- None.
+
+**Findings (Important):**
+- None.
+
+**Findings (Minor):**
+- `D1` [Assumptions under attack] [lines 78-80]: Homebrew freshness can lag local users even when `origin/main` is correct. Recommendation: document `brew update` and verify formula freshness from both GitHub and local Homebrew. _Resolution: covered in design evidence and Task 2._
+- `D2` [User-intent drift] [lines 41-50]: Initial design covered docs but not the user's release/downstream instruction. Recommendation: add post-merge release and downstream verification scope. _Resolution: design and plan amended before lock._
+- `D3` [Simpler alternative] [lines 37-39]: A shell installer could reduce copy/paste but would add a trust surface. Recommendation: keep installer script out of scope until repeated user friction proves it is needed. _Resolution: explicitly rejected in design._
+
+**Bug-class scan transcript:**
+
+| Class | Result | Note |
+|---|---|---|
+| Project-guidance conflicts | Clean | Reuses existing release, tap, and plugin-manager surfaces per workspace guidance. |
+| Assumptions under attack | Finding | Homebrew cache freshness is called out and mitigated. |
+| Repo-precedent conflicts | Clean | Docs live under existing `docs/`; no root examples or new installer roots. |
+| Artifact-class precedent | Clean | Workflow docs, tap README, and website copy match sibling artifact shapes. |
+| YAGNI violations | Clean | No new installer or plugin behavior is introduced. |
+| Missing failure modes | Clean | Covers stale Homebrew cache, checksum verification, and downstream dispatch failure. |
+| Security / privacy | Clean | Design avoids blind shell execution and requires checksums for raw binaries. |
+| Infrastructure impact | Clean | No infra changes; release/downstream pipelines are normal repo operations. |
+| Multi-component validation | Clean | Requires CLI help, GitHub release assets, tap formula metadata, website build, and downstream workflow checks. |
+| Declared integration proof | Clean | Integrations are config-only docs surfaces plus release dispatches verified through GitHub Actions. |
+| Contributed UI rendering proof | Clean | No contributed UI routes. |
+| Rollback story | Clean | Revert docs PRs or cut follow-up patch release from reverted state. |
+| Simpler alternative not considered | Finding | Shell installer considered and rejected. |
+| User-intent drift | Finding | Release/downstream instruction was added before PASS. |
+| Existence / runtime-validity | Clean | Design cites observed release assets, tap formula, branch protection, generated PR, and CLI surfaces. |
+
+**Options the author may not have considered:**
+
+1. Add `install.sh`: easier UX, worse trust and maintenance surface than documented release assets plus checksums.
+2. Make Homebrew mandatory: simple docs, but excludes Windows/manual download and some Linux CI use cases.
+
+**Verdict reasoning:** PASS. The design now maps the user's install, update, plugin lifecycle, Homebrew auto-freshness, and downstream release requirements without adding new runtime behavior.
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md b/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
new file mode 100644
index 00000000..3747bf52
--- /dev/null
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
@@ -0,0 +1,56 @@
+### Adversarial Review Report
+
+**Phase:** plan
+**Artifact:** docs/plans/2026-07-03-wfctl-install-lifecycle.md
+**Status:** PASS
+
+**Findings (Critical):**
+- None.
+
+**Findings (Important):**
+- None.
+
+**Findings (Minor):**
+- `P1` [User-intent drift] [Task 4]: First draft omitted post-merge release and downstream execution. Recommendation: add an explicit operational task. _Resolution: Task 4 added._
+- `P2` [Existence / runtime-validity] [Task 4]: First draft used `gh workflow run release.yml` for tag-driven release workflows. Recommendation: use tag push and monitor workflow runs. _Resolution: Task 4 corrected after inspecting release workflows._
+- `P3` [Verification-class mismatch] [Task 2]: Tap auto-freshness needs settings and PR evidence, not only README syntax checks. Recommendation: verify branch protection and a recent generated wfctl PR. _Resolution: Task 2 includes both checks._
+
+**Bug-class scan transcript:**
+
+| Class | Result | Note |
+|---|---|---|
+| Project-guidance conflicts | Clean | Plan respects repo-local docs/layout guidance and uses clean worktrees. |
+| Assumptions under attack | Clean | Latest release, Homebrew cache, generated PR merge, and website generated-doc timing are verified. |
+| Repo-precedent conflicts | Clean | Uses existing docs files, release workflows, and website README release flow. |
+| Artifact-class precedent | Clean | Docs updates and tap README updates match existing artifact classes. |
+| YAGNI violations | Clean | No new installer or CLI behavior. |
+| Missing failure modes | Clean | Handles stale tap cache, failed generated PR, failed downstream workflows, and rollback. |
+| Security / privacy | Clean | Checksum verification is required for raw binary docs; no secret values in PR bodies. |
+| Infrastructure impact | Clean | Release and dispatch workflows are monitored; no cloud resource changes. |
+| Multi-component validation | Clean | Release assets, CLI help, tap formula, website build, and downstream workflows are checked. |
+| Declared integration proof | Clean | Release dispatches are enumerated and verified through real workflow runs. |
+| Contributed UI rendering proof | Clean | No UI plugin contribution. |
+| Rollback story | Clean | Every task has a rollback note. |
+| Simpler alternative not considered | Clean | Design rejects installer script and Homebrew-only approach. |
+| User-intent drift | Finding | Initial omission resolved by Task 4. |
+| Existence / runtime-validity | Finding | Release command shape corrected after workflow inspection. |
+| Over-decomposition / under-decomposition | Clean | Four tasks map to repo/workflow boundaries. |
+| Verification-class mismatch | Finding | Tap automation evidence added. |
+| Auth/authz chain composition | Clean | No auth chain changes. |
+| Hidden serial dependencies | Clean | Workflow release precedes website generated-doc sync; Task 4 states ordering. |
+| Missing rollback wiring | Clean | Rollback notes included. |
+| Missing integration proof | Clean | Downstream release dispatch proof included. |
+| Missing declared integration matrix | Clean | Downstream repos are listed in Task 4. |
+| Missing contributed UI route proof | Clean | Not applicable. |
+| Infrastructure verification mismatch | Clean | No infrastructure resources are changed. |
+| Plugin-loader runtime layout | Clean | No plugin process layout changes. |
+| Config-validation schema rules | Clean | No config files added. |
+| Identifier / naming-convention match | Clean | Commands and flags match inspected CLI surfaces. |
+| Planned-code compile-validity | Clean | No embedded compiled code. |
+
+**Options the author may not have considered:**
+
+1. Collapse all repos into one mega PR: impossible across repos and worse for rollback.
+2. Skip website copy and rely on generated docs: insufficient because website has hardcoded stale snippets.
+
+**Verdict reasoning:** PASS. Tangible issues from the first pass were corrected before implementation; remaining findings are documented as resolved.

From 04a4e74b65324b8c6b0c66395249b07fd568aaf1 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:38:48 -0400
Subject: [PATCH 03/16] docs: align wfctl install plan manifest

---
 .../2026-07-03-wfctl-install-lifecycle-plan-review.md     | 1 +
 docs/plans/2026-07-03-wfctl-install-lifecycle.md          | 8 ++++----
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md b/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
index 3747bf52..9a89626e 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
@@ -14,6 +14,7 @@
 - `P1` [User-intent drift] [Task 4]: First draft omitted post-merge release and downstream execution. Recommendation: add an explicit operational task. _Resolution: Task 4 added._
 - `P2` [Existence / runtime-validity] [Task 4]: First draft used `gh workflow run release.yml` for tag-driven release workflows. Recommendation: use tag push and monitor workflow runs. _Resolution: Task 4 corrected after inspecting release workflows._
 - `P3` [Verification-class mismatch] [Task 2]: Tap auto-freshness needs settings and PR evidence, not only README syntax checks. Recommendation: verify branch protection and a recent generated wfctl PR. _Resolution: Task 2 includes both checks._
+- `P4` [Manifest trace] [plan headings]: First checked plan used `## Task N` headings, which the scope-lock parser does not count as task headings. Recommendation: use `### Task N:` headings required by `writing-plans`. _Resolution: headings corrected and `plan-scope-check.sh` rerun._
 
 **Bug-class scan transcript:**
 
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
index 7299ba5f..2caa63b2 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
@@ -33,7 +33,7 @@
 
 **Status:** Draft
 
-## Task 1: Workflow Canonical wfctl Docs
+### Task 1: Workflow Canonical wfctl Docs
 
 **Files:**
 - Create: `docs/WFCTL_INSTALLATION.md`
@@ -84,7 +84,7 @@ git commit -m "docs: clarify wfctl install lifecycle"
 
 Rollback: revert commit; no runtime state changes.
 
-## Task 2: Homebrew Tap README And Auto-Merge Guard
+### Task 2: Homebrew Tap README And Auto-Merge Guard
 
 **Files:**
 - Modify: `README.md`
@@ -129,7 +129,7 @@ git commit -m "docs: document Homebrew tap usage"
 
 Rollback: revert commit; formulas unchanged.
 
-## Task 3: Website Install Copy
+### Task 3: Website Install Copy
 
 **Files:**
 - Modify: `src/pages/PlatformPage.tsx`
@@ -163,7 +163,7 @@ git commit -m "docs: refresh wfctl install copy"
 
 Rollback: revert commit; no runtime state changes until website release.
 
-## Task 4: Post-Merge Release And Downstream Verification
+### Task 4: Post-Merge Release And Downstream Verification
 
 **Files:**
 - Inspect: `.github/workflows/release.yml`

From 61070ad4270808de8a6e57b50554e5c96bedc6f1 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:39:07 -0400
Subject: [PATCH 04/16] chore: lock scope for wfctl install lifecycle

---
 docs/plans/2026-07-03-wfctl-install-lifecycle.md            | 2 +-
 docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock

diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
index 2caa63b2..5982683b 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
@@ -31,7 +31,7 @@
 | 2 | docs: document GoCodeAlone Homebrew tap usage | Task 2 | docs/tap-install-readme |
 | 3 | docs: remove stale wfctl install copy and release docs | Task 3, Task 4 | docs/wfctl-install-copy |
 
-**Status:** Draft
+**Status:** Locked 2026-07-03T23:38:53Z
 
 ### Task 1: Workflow Canonical wfctl Docs
 
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock b/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
new file mode 100644
index 00000000..483ffa12
--- /dev/null
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
@@ -0,0 +1 @@
+6c680e5d93bd392889bc2cb257803a044bd3846d09b18c19d3bcab4729df5011

From 3238b6019a6bb1ab021273fc4a787f84f79bec40 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:42:44 -0400
Subject: [PATCH 05/16] docs: clarify wfctl install lifecycle

---
 README.md                        |  12 +-
 docs/PLUGIN_DEVELOPMENT_GUIDE.md |   7 ++
 docs/WFCTL.md                    |  27 ++--
 docs/WFCTL_INSTALLATION.md       | 210 +++++++++++++++++++++++++++++++
 4 files changed, 245 insertions(+), 11 deletions(-)
 create mode 100644 docs/WFCTL_INSTALLATION.md

diff --git a/README.md b/README.md
index 0552dfac..b11619f1 100644
--- a/README.md
+++ b/README.md
@@ -179,9 +179,10 @@ docker compose up
 
 `wfctl` is a command-line tool for inspecting, validating, and generating workflow configurations.
 
-**Install from GitHub Releases:**
+**Install with Homebrew:**
 ```bash
-curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') -o wfctl && chmod +x wfctl
+brew tap gocodealone/tap
+brew install wfctl
 ```
 
 **Install from source:**
@@ -189,6 +190,13 @@ curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-
 go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest
 ```
 
+Direct binary downloads are published on
+[GitHub Releases](https://github.com/GoCodeAlone/workflow/releases/latest)
+with `checksums.txt` for verification. See
+[wfctl Installation And Plugin Lifecycle](docs/WFCTL_INSTALLATION.md) for
+Homebrew, terminal download, browser download, Windows, update, and plugin
+lifecycle instructions.
+
 **Commands:**
 - `wfctl inspect <config.yaml>` — summarize modules, workflows, triggers, and dependencies
 - `wfctl validate <config.yaml>` — deep validation against known module/step types
diff --git a/docs/PLUGIN_DEVELOPMENT_GUIDE.md b/docs/PLUGIN_DEVELOPMENT_GUIDE.md
index 4f289485..fa9fa08d 100644
--- a/docs/PLUGIN_DEVELOPMENT_GUIDE.md
+++ b/docs/PLUGIN_DEVELOPMENT_GUIDE.md
@@ -539,6 +539,13 @@ cp my-plugin data/plugins/my-plugin/
 cp plugin.json data/plugins/my-plugin/
 ```
 
+For installing published plugins as a `wfctl` user, prefer the plugin lifecycle
+commands documented in
+[wfctl Installation And Plugin Lifecycle](WFCTL_INSTALLATION.md): use
+`wfctl plugin add`, `wfctl plugin lock`, and `wfctl plugin ci` for project
+plugins, or `wfctl plugin install -g` and `wfctl plugin update -g --all` for
+operator-global plugins.
+
 ### Discovery and Loading
 
 The engine discovers external plugins through two mechanisms:
diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 75222adf..34c582d7 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -4,20 +4,27 @@
 
 ## Installation
 
-### GitHub Releases (recommended)
+For full install, update, checksum, browser-download, Windows, Homebrew, and
+plugin lifecycle instructions, see
+[wfctl Installation And Plugin Lifecycle](WFCTL_INSTALLATION.md).
+
+### Homebrew
 
 ```bash
-# macOS (Apple Silicon)
-curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-darwin-arm64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/
+brew tap gocodealone/tap
+brew install wfctl
+```
 
-# macOS (Intel)
-curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-darwin-amd64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/
+### GitHub Releases
 
-# Linux (x86_64)
-curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-linux-amd64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/
+Download raw binaries and `checksums.txt` from
+<https://github.com/GoCodeAlone/workflow/releases/latest>. Verify the checksum
+before moving `wfctl` into `PATH`.
 
-# Linux (ARM64)
-curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-linux-arm64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/
+```bash
+shasum -a 256 --ignore-missing -c checksums.txt
+chmod +x ./wfctl-*
+sudo install -m 0755 ./wfctl-darwin-arm64 /usr/local/bin/wfctl
 ```
 
 ### From Source
@@ -33,6 +40,8 @@ wfctl update          # install latest release
 wfctl update --check  # check for updates without installing
 ```
 
+Prefer `brew upgrade wfctl` for Homebrew-managed installs.
+
 ---
 
 ## Command Tree
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
new file mode 100644
index 00000000..8c20f95c
--- /dev/null
+++ b/docs/WFCTL_INSTALLATION.md
@@ -0,0 +1,210 @@
+# wfctl Installation And Plugin Lifecycle
+
+`wfctl` is published as raw release binaries, a GoCodeAlone Homebrew formula,
+and a Go source install. Use Homebrew when you want package-manager upgrades.
+Use the release binaries when you want a direct install without Homebrew.
+
+## Install wfctl
+
+### Homebrew
+
+```bash
+brew tap gocodealone/tap
+brew install wfctl
+wfctl --version
+```
+
+Upgrade with Homebrew:
+
+```bash
+brew update
+brew upgrade wfctl
+```
+
+If a Workflow release was just published and Homebrew still shows an older
+formula, run `brew update` before checking again:
+
+```bash
+brew info gocodealone/tap/wfctl
+```
+
+### Terminal Download Without Homebrew
+
+Workflow releases publish raw `wfctl` binaries plus `checksums.txt`.
+This installer downloads the latest binary for macOS or Linux, verifies the
+SHA-256 checksum, and installs it into `/usr/local/bin`.
+
+```bash
+set -euo pipefail
+
+os="$(uname -s | tr '[:upper:]' '[:lower:]')"
+arch="$(uname -m)"
+case "$arch" in
+  x86_64|amd64) arch="amd64" ;;
+  arm64|aarch64) arch="arm64" ;;
+  *) echo "unsupported architecture: $arch" >&2; exit 1 ;;
+esac
+case "$os" in
+  darwin|linux) ;;
+  *) echo "unsupported OS: $os" >&2; exit 1 ;;
+esac
+
+asset="wfctl-${os}-${arch}"
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+base="https://github.com/GoCodeAlone/workflow/releases/latest/download"
+curl -fL "$base/$asset" -o "$tmpdir/$asset"
+curl -fL "$base/checksums.txt" -o "$tmpdir/checksums.txt"
+
+(cd "$tmpdir" && grep "  $asset$" checksums.txt | shasum -a 256 -c -)
+chmod +x "$tmpdir/$asset"
+sudo install -m 0755 "$tmpdir/$asset" /usr/local/bin/wfctl
+
+wfctl --version
+```
+
+For a user-local install without `sudo`, replace the install command with:
+
+```bash
+mkdir -p "$HOME/.local/bin"
+install -m 0755 "$tmpdir/$asset" "$HOME/.local/bin/wfctl"
+```
+
+Then ensure `$HOME/.local/bin` is in `PATH`.
+
+### Browser Download
+
+1. Open <https://github.com/GoCodeAlone/workflow/releases/latest>.
+2. Download the asset for your platform:
+   - macOS Apple Silicon: `wfctl-darwin-arm64`
+   - macOS Intel: `wfctl-darwin-amd64`
+   - Linux x86_64: `wfctl-linux-amd64`
+   - Linux ARM64: `wfctl-linux-arm64`
+   - Windows x86_64: `wfctl-windows-amd64.exe`
+3. Download `checksums.txt` from the same release.
+4. Verify the checksum.
+
+macOS or Linux:
+
+```bash
+shasum -a 256 --ignore-missing -c checksums.txt
+chmod +x ./wfctl-*
+sudo install -m 0755 ./wfctl-darwin-arm64 /usr/local/bin/wfctl
+```
+
+Replace `wfctl-darwin-arm64` with the file you downloaded.
+
+Windows PowerShell:
+
+```powershell
+certutil -hashfile .\wfctl-windows-amd64.exe SHA256
+```
+
+Compare the printed hash to the `wfctl-windows-amd64.exe` row in
+`checksums.txt`, then place the executable in a directory on `%PATH%`.
+
+### From Source
+
+Use this path when you already have Go installed and want a source build:
+
+```bash
+go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest
+```
+
+This installs into `$(go env GOPATH)/bin` or `$(go env GOBIN)`. Ensure that
+directory is in `PATH`.
+
+## Update wfctl
+
+Homebrew installs should be updated by Homebrew:
+
+```bash
+brew update
+brew upgrade wfctl
+```
+
+Release-binary installs can self-update:
+
+```bash
+wfctl update --check
+wfctl update
+```
+
+`wfctl update` downloads the latest GitHub release for the current platform,
+verifies `checksums.txt` when available, and replaces the current executable.
+It is not recommended for Homebrew-managed binaries because it bypasses
+Homebrew's cellar and formula state.
+
+## Project Plugin Lifecycle
+
+Workflow projects should commit a human-edited `wfctl.yaml` manifest and the
+generated `.wfctl-lock.yaml` lockfile. The manifest states intent; the lockfile
+pins resolved versions and portable archive checksums for CI.
+
+```bash
+# Find a plugin.
+wfctl plugin search auth
+
+# Add a plugin to wfctl.yaml and regenerate .wfctl-lock.yaml.
+wfctl plugin add workflow-plugin-auth@v0.4.0
+
+# Refresh the lockfile after editing wfctl.yaml.
+wfctl plugin lock
+
+# Install all locked project plugins into ./data/plugins.
+wfctl plugin install
+
+# CI path: install exactly from the lockfile and do not write files.
+wfctl plugin ci
+```
+
+`wfctl plugin install` without a plugin argument checks `wfctl.yaml` and
+`.wfctl-lock.yaml`. If the lockfile is missing or stale, local installs
+regenerate it before installing. Use `wfctl plugin ci` or
+`wfctl plugin install --locked` in CI to fail on stale locks instead of
+modifying the checkout.
+
+By default, project plugins install to `data/plugins`. Override the directory
+with `--plugin-dir` or `WFCTL_PLUGIN_DIR`.
+
+## Global Plugin Lifecycle
+
+Global plugins are operator tools available outside a single project. They do
+not modify `wfctl.yaml` or `.wfctl-lock.yaml`.
+
+```bash
+wfctl plugin install -g workflow-plugin-portfolio
+wfctl plugin list -g
+wfctl plugin info -g workflow-plugin-portfolio
+wfctl plugin update -g workflow-plugin-portfolio
+wfctl plugin update -g --all
+wfctl plugin remove -g workflow-plugin-portfolio
+```
+
+The default global directory is
+`${XDG_DATA_HOME:-$HOME/.local/share}/wfctl/plugins`. Override it with
+`WFCTL_GLOBAL_PLUGIN_DIR`.
+
+Project-local plugin commands take precedence over global plugin commands, so a
+repository can pin the plugin version it expects while operators keep global
+tools installed for ad hoc use.
+
+## Plugin Integrity And Compatibility
+
+Registry installs fail closed when `wfctl` cannot verify plugin archive
+checksums. GitHub release downloads can auto-fetch `checksums.txt`; registry
+manifests can also carry SHA-256 values directly. Use `--skip-checksum` only
+for trusted internal URLs.
+
+Registry installs and locks also resolve compatibility evidence for the current
+Workflow engine version. Use `--compat-mode warn` to allow warnings during
+migration, or `--force` only when you intentionally accept known-failing or
+missing compatibility evidence while keeping checksum enforcement.
+
+## Useful References
+
+- Full CLI reference: [WFCTL.md](WFCTL.md)
+- Plugin authoring: [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md)
+- Registry: <https://github.com/GoCodeAlone/workflow-registry>
+- Releases: <https://github.com/GoCodeAlone/workflow/releases>

From 1ab78d6ce105419ce89ac4a8769f23f40857f03f Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:45:43 -0400
Subject: [PATCH 06/16] docs: amend wfctl install lifecycle scope

---
 ...51-homebrew-claude-skills-formula-layout.md | 18 ++++++++++++++++++
 ...026-07-03-wfctl-install-lifecycle-design.md |  3 ++-
 ...7-03-wfctl-install-lifecycle-plan-review.md |  1 +
 .../2026-07-03-wfctl-install-lifecycle.md      | 14 ++++++++++----
 ...07-03-wfctl-install-lifecycle.md.scope-lock |  2 +-
 5 files changed, 32 insertions(+), 6 deletions(-)
 create mode 100644 decisions/0051-homebrew-claude-skills-formula-layout.md

diff --git a/decisions/0051-homebrew-claude-skills-formula-layout.md b/decisions/0051-homebrew-claude-skills-formula-layout.md
new file mode 100644
index 00000000..4c0c01f4
--- /dev/null
+++ b/decisions/0051-homebrew-claude-skills-formula-layout.md
@@ -0,0 +1,18 @@
+# 0051. Restore claude-skills formula layout
+
+**Status:** Accepted
+**Date:** 2026-07-03
+**Decision-makers:** Codex
+**Related:** docs/plans/2026-07-03-wfctl-install-lifecycle-design.md, docs/plans/2026-07-03-wfctl-install-lifecycle.md
+
+## Context
+
+The tap README claimed `claude-skills` was installable, but `brew info gocodealone/tap/claude-skills` failed after `brew update`. The formula exists only as `claude-skills.rb` at the tap root, while current Homebrew resolves formulas from `Formula/`.
+
+## Decision
+
+Move `claude-skills.rb` to `Formula/claude-skills.rb` and document it as an available formula only after that layout is fixed. Rejected alternatives: removing it from README would hide a broken intended recipe; leaving the root file would keep the install path nonfunctional.
+
+## Consequences
+
+`brew install gocodealone/tap/claude-skills` should resolve after the tap PR merges and users run `brew update`. The change is a formula layout fix, not a new release of `claude-skills`. Rollback is moving the file back or reverting the tap PR, but that would make the README table false again.
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md b/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
index 2eb48e7a..f98ff7c9 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle-design.md
@@ -23,6 +23,7 @@ Make wfctl installation, update, and plugin lifecycle documentation accurate acr
 - Workflow release workflow publishes checksums and dispatches `update-wfctl` to `GoCodeAlone/homebrew-tap` for stable tags.
 - `homebrew-tap` `origin/main` has `Formula/wfctl.rb` at `0.84.3`; local brew cache may lag until `brew update`.
 - `homebrew-tap` `main` has no branch protection as of 2026-07-03, so generated formula PRs are not blocked by required review settings. PR #59 (`automation/update-wfctl-v0.84.3`) merged after CodeQL checks with only a Copilot comment.
+- `claude-skills` exists as a root-level legacy formula file but is not resolved by current Homebrew; see `decisions/0051-homebrew-claude-skills-formula-layout.md`.
 - `wfctl` already supports `update`, `update --check`, project plugin manifest/lock commands, `plugin ci`, and `-g/--global` plugin installs.
 
 ## Recommended Approach
@@ -45,7 +46,7 @@ In scope:
 - Replace stale README install one-liners.
 - Add a dedicated wfctl installation/lifecycle doc covering Homebrew, terminal release download, browser/manual download, source install, self-update, PATH, and verification.
 - Expand plugin lifecycle docs: project manifest, lockfile, CI install, global install, update, remove, and compatibility/checksum notes.
-- Expand the tap README with tap setup, formulas, install/upgrade examples, and automation notes.
+- Expand the tap README with tap setup, formulas, install/upgrade examples, and automation notes, and repair the `claude-skills` formula layout so every documented formula resolves.
 - Verify that generated Homebrew formula PRs can merge without mandatory reviews; if required reviews are later enabled, remove that branch requirement or add an explicit generated-PR bypass before relying on auto-merge.
 - Update website hardcoded wfctl install snippets away from stale `v0.60.17`.
 - After PRs merge, release Workflow and the website as needed, then verify downstream repository dispatches ran: Homebrew tap formula update, workflow-registry sync, workflow-scenarios bump, workflow-editor notification, website docs sync, and multisite ingest.
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md b/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
index 9a89626e..ed7fac92 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle-plan-review.md
@@ -15,6 +15,7 @@
 - `P2` [Existence / runtime-validity] [Task 4]: First draft used `gh workflow run release.yml` for tag-driven release workflows. Recommendation: use tag push and monitor workflow runs. _Resolution: Task 4 corrected after inspecting release workflows._
 - `P3` [Verification-class mismatch] [Task 2]: Tap auto-freshness needs settings and PR evidence, not only README syntax checks. Recommendation: verify branch protection and a recent generated wfctl PR. _Resolution: Task 2 includes both checks._
 - `P4` [Manifest trace] [plan headings]: First checked plan used `## Task N` headings, which the scope-lock parser does not count as task headings. Recommendation: use `### Task N:` headings required by `writing-plans`. _Resolution: headings corrected and `plan-scope-check.sh` rerun._
+- `P5` [Existence / runtime-validity] [Task 2 amendment]: `claude-skills` was documented as installable but current Homebrew did not resolve it from the tap root. Recommendation: amend Task 2 to move the formula into `Formula/` and verify local formula resolution. _Resolution: ADR 0051 recorded; Task 2 amended._
 
 **Bug-class scan transcript:**
 
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
index 5982683b..79ca073d 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
@@ -31,7 +31,7 @@
 | 2 | docs: document GoCodeAlone Homebrew tap usage | Task 2 | docs/tap-install-readme |
 | 3 | docs: remove stale wfctl install copy and release docs | Task 3, Task 4 | docs/wfctl-install-copy |
 
-**Status:** Locked 2026-07-03T23:38:53Z
+**Status:** Locked 2026-07-03T23:45:22Z
 
 ### Task 1: Workflow Canonical wfctl Docs
 
@@ -88,6 +88,7 @@ Rollback: revert commit; no runtime state changes.
 
 **Files:**
 - Modify: `README.md`
+- Move: `claude-skills.rb` to `Formula/claude-skills.rb`
 - Inspect: `.github/workflows/update-wfctl.yml`
 - External setting: `GoCodeAlone/homebrew-tap` `main` branch protection
 
@@ -96,12 +97,13 @@ Rollback: revert commit; no runtime state changes.
 Expand the tap README with:
 
 - `brew tap gocodealone/tap`.
-- Available formula table for `wfctl`, `ratchet-cli`, and `claude-skills`.
+- Available recipe table for `wfctl`, `ratchet-cli`, `ratchet-cli` cask, and `claude-skills`.
 - Install, upgrade, pin/unpin, uninstall, and inspect examples.
 - Formula-specific examples: `brew install gocodealone/tap/wfctl`, `brew upgrade wfctl`.
 - Troubleshooting for stale formula cache via `brew update` and `brew info gocodealone/tap/wfctl`.
 - Automation note: Workflow releases dispatch `update-wfctl`; generated wfctl formula PRs are expected to auto-merge or admin-merge after checks when no unresolved review threads remain.
 - Branch-protection note: required reviews must not be mandatory for generated formula PRs unless a generated-PR bypass exists.
+- Move the legacy root-level `claude-skills.rb` formula into `Formula/claude-skills.rb` so the documented `brew install gocodealone/tap/claude-skills` path resolves.
 
 **Step 2: Verify tap state**
 
@@ -110,20 +112,24 @@ Run:
 ```bash
 ruby -c Formula/wfctl.rb
 ruby -c Formula/ratchet-cli.rb
+ruby -c Formula/claude-skills.rb
 brew info gocodealone/tap/wfctl
+brew info gocodealone/tap/ratchet-cli
+brew info --cask gocodealone/tap/ratchet-cli
+brew info ./Formula/claude-skills.rb
 gh pr list --repo GoCodeAlone/homebrew-tap --state all --limit 5 --json number,title,state --jq '.[] | [.number,.state,.title] | @tsv'
 gh api repos/GoCodeAlone/homebrew-tap/branches/main/protection --jq '.required_pull_request_reviews' || true
 gh pr view 59 --repo GoCodeAlone/homebrew-tap --json state,mergedAt,reviewDecision,statusCheckRollup --jq '{state,mergedAt,reviewDecision,checks:[.statusCheckRollup[]? | {name,conclusion,status}]}'
 ```
 
-Expected: Ruby syntax OK; `brew info` reports the tap formula; recent PR list shows automated formula updates; branch protection is absent or has no required-review gate for generated formula PRs; recent generated wfctl formula PR merged with green checks.
+Expected: Ruby syntax OK; `brew info` reports the tap formulas/cask; local `Formula/claude-skills.rb` resolves as a formula; recent PR list shows automated formula updates; branch protection is absent or has no required-review gate for generated formula PRs; recent generated wfctl formula PR merged with green checks.
 
 If the branch-protection check reports required reviews and no generated-PR bypass exists, update the repository rule before relying on the automation. If workflow inspection shows generated formula PRs no longer merge after checks, patch `.github/workflows/update-wfctl.yml` to restore the current behavior: open/update the generated PR, request Copilot review as advisory, wait for checks, leave open on failed checks or unresolved review threads, and admin-merge after green checks.
 
 **Step 3: Commit**
 
 ```bash
-git add README.md .github/workflows/update-wfctl.yml
+git add README.md Formula/claude-skills.rb .github/workflows/update-wfctl.yml
 git commit -m "docs: document Homebrew tap usage"
 ```
 
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock b/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
index 483ffa12..7e4efea5 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
@@ -1 +1 @@
-6c680e5d93bd392889bc2cb257803a044bd3846d09b18c19d3bcab4729df5011
+5aac6f809612e8609dc3b20f5611e4200bf5450d95273ea1d73a08e223a5b949

From 87a1bc2e599f81da103030ed74343795dedf635d Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:48:10 -0400
Subject: [PATCH 07/16] docs: clarify tap formula verification

---
 docs/plans/2026-07-03-wfctl-install-lifecycle.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
index 79ca073d..e07c6ee3 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
@@ -116,13 +116,22 @@ ruby -c Formula/claude-skills.rb
 brew info gocodealone/tap/wfctl
 brew info gocodealone/tap/ratchet-cli
 brew info --cask gocodealone/tap/ratchet-cli
-brew info ./Formula/claude-skills.rb
 gh pr list --repo GoCodeAlone/homebrew-tap --state all --limit 5 --json number,title,state --jq '.[] | [.number,.state,.title] | @tsv'
 gh api repos/GoCodeAlone/homebrew-tap/branches/main/protection --jq '.required_pull_request_reviews' || true
 gh pr view 59 --repo GoCodeAlone/homebrew-tap --json state,mergedAt,reviewDecision,statusCheckRollup --jq '{state,mergedAt,reviewDecision,checks:[.statusCheckRollup[]? | {name,conclusion,status}]}'
 ```
 
-Expected: Ruby syntax OK; `brew info` reports the tap formulas/cask; local `Formula/claude-skills.rb` resolves as a formula; recent PR list shows automated formula updates; branch protection is absent or has no required-review gate for generated formula PRs; recent generated wfctl formula PR merged with green checks.
+Expected: Ruby syntax OK; `brew info` reports the tap formulas/cask; recent PR list shows automated formula updates; branch protection is absent or has no required-review gate for generated formula PRs; recent generated wfctl formula PR merged with green checks.
+
+After committing the tap branch, verify the moved `claude-skills` formula through a temporary tap clone:
+
+```bash
+brew tap gocodealone/wfctl-docs-test "$(pwd)"
+brew info gocodealone/wfctl-docs-test/claude-skills
+brew untap gocodealone/wfctl-docs-test
+```
+
+Expected: `brew info` resolves `claude-skills` from the temporary tap.
 
 If the branch-protection check reports required reviews and no generated-PR bypass exists, update the repository rule before relying on the automation. If workflow inspection shows generated formula PRs no longer merge after checks, patch `.github/workflows/update-wfctl.yml` to restore the current behavior: open/update the generated PR, request Copilot review as advisory, wait for checks, leave open on failed checks or unresolved review threads, and admin-merge after green checks.
 

From b1703f34523d1519e54c78b3b86da993f9c17452 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 19:53:57 -0400
Subject: [PATCH 08/16] docs: record website snapshot scope

---
 docs/plans/2026-07-03-wfctl-install-lifecycle.md    | 13 +++++++++----
 ...2026-07-03-wfctl-install-lifecycle.md.scope-lock |  2 +-
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
index e07c6ee3..0d718a25 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md
@@ -21,7 +21,7 @@
 **Out of scope:**
 - New installer scripts or release asset names.
 - Plugin installer behavior changes.
-- Generated website docs refresh before Workflow docs release.
+- Hand-editing generated website API reference output.
 
 **PR Grouping:**
 
@@ -148,7 +148,10 @@ Rollback: revert commit; formulas unchanged.
 
 **Files:**
 - Modify: `src/pages/PlatformPage.tsx`
-- Optionally modify generated docs only after Workflow docs release/sync.
+- Modify: `src/data/configs/README.md`
+- Modify: `docs/site/src/content/docs/workflow/WFCTL.md`
+- Modify: `docs/site/src/content/docs/workflow/index.md`
+- Create: `docs/site/src/content/docs/workflow/WFCTL_INSTALLATION.md`
 
 **Step 1: Replace stale install snippets**
 
@@ -157,6 +160,8 @@ Replace hardcoded `go install ...@v0.60.17` snippets with current lifecycle copy
 - Primary snippet: `brew install gocodealone/tap/wfctl`.
 - Secondary source command: `go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest`.
 - Link users to Workflow releases/docs for binary downloads rather than duplicating versioned asset names in React copy.
+- Remove stale `v0.60.17` validation text from the checked-in example config README.
+- Update the checked-in generated Workflow docs snapshot for the served wfctl docs pages so the website PR is correct before the next post-release sync. Do not hand-edit generated Go API reference output.
 
 **Step 2: Verify website build**
 
@@ -172,8 +177,8 @@ Expected: build exits `0`.
 **Step 3: Commit**
 
 ```bash
-git add src/pages/PlatformPage.tsx
-git commit -m "docs: refresh wfctl install copy"
+git add src/pages/PlatformPage.tsx src/data/configs/README.md docs/site/src/content/docs/workflow/WFCTL.md docs/site/src/content/docs/workflow/index.md docs/site/src/content/docs/workflow/WFCTL_INSTALLATION.md
+git commit -m "docs: update wfctl install copy"
 ```
 
 Rollback: revert commit; no runtime state changes until website release.
diff --git a/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock b/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
index 7e4efea5..505dbc22 100644
--- a/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
+++ b/docs/plans/2026-07-03-wfctl-install-lifecycle.md.scope-lock
@@ -1 +1 @@
-5aac6f809612e8609dc3b20f5611e4200bf5450d95273ea1d73a08e223a5b949
+694b0e545085fcf95c3116e82314569ff236ecebc4fbe28ccce753091acf97ff

From f48e3024ea4331492b1a4bc9b3b1b12e80d21c0b Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:00:54 -0400
Subject: [PATCH 09/16] docs: improve wfctl checksum examples

---
 docs/WFCTL.md              | 11 ++++++++---
 docs/WFCTL_INSTALLATION.md | 25 ++++++++++++++++++++-----
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 34c582d7..8f56a009 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -22,9 +22,14 @@ Download raw binaries and `checksums.txt` from
 before moving `wfctl` into `PATH`.
 
 ```bash
-shasum -a 256 --ignore-missing -c checksums.txt
-chmod +x ./wfctl-*
-sudo install -m 0755 ./wfctl-darwin-arm64 /usr/local/bin/wfctl
+asset=wfctl-darwin-arm64 # replace with the asset you downloaded
+if command -v shasum >/dev/null 2>&1; then
+  grep "  $asset$" checksums.txt | shasum -a 256 -c -
+else
+  grep "  $asset$" checksums.txt | sha256sum -c -
+fi
+chmod +x "./$asset"
+sudo install -m 0755 "./$asset" /usr/local/bin/wfctl
 ```
 
 ### From Source
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 8c20f95c..69acfef7 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -57,7 +57,16 @@ base="https://github.com/GoCodeAlone/workflow/releases/latest/download"
 curl -fL "$base/$asset" -o "$tmpdir/$asset"
 curl -fL "$base/checksums.txt" -o "$tmpdir/checksums.txt"
 
-(cd "$tmpdir" && grep "  $asset$" checksums.txt | shasum -a 256 -c -)
+if command -v shasum >/dev/null 2>&1; then
+  checksum_cmd=(shasum -a 256 -c -)
+elif command -v sha256sum >/dev/null 2>&1; then
+  checksum_cmd=(sha256sum -c -)
+else
+  echo "missing checksum tool: install shasum or sha256sum" >&2
+  exit 1
+fi
+
+(cd "$tmpdir" && grep "  $asset$" checksums.txt | "${checksum_cmd[@]}")
 chmod +x "$tmpdir/$asset"
 sudo install -m 0755 "$tmpdir/$asset" /usr/local/bin/wfctl
 
@@ -88,12 +97,18 @@ Then ensure `$HOME/.local/bin` is in `PATH`.
 macOS or Linux:
 
 ```bash
-shasum -a 256 --ignore-missing -c checksums.txt
-chmod +x ./wfctl-*
-sudo install -m 0755 ./wfctl-darwin-arm64 /usr/local/bin/wfctl
+asset=wfctl-darwin-arm64 # replace with the asset you downloaded
+if command -v shasum >/dev/null 2>&1; then
+  grep "  $asset$" checksums.txt | shasum -a 256 -c -
+else
+  grep "  $asset$" checksums.txt | sha256sum -c -
+fi
+chmod +x "./$asset"
+sudo install -m 0755 "./$asset" /usr/local/bin/wfctl
 ```
 
-Replace `wfctl-darwin-arm64` with the file you downloaded.
+Replace `wfctl-darwin-arm64` with the file you downloaded. On Linux, install
+`sha256sum` or `shasum` if neither command is available.
 
 Windows PowerShell:
 

From c6208538de5f8d5cfbdee893a176fe78a5b730e4 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:03:27 -0400
Subject: [PATCH 10/16] docs: clarify project plugin install dir

---
 docs/WFCTL_INSTALLATION.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 69acfef7..3f55e057 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -180,8 +180,10 @@ regenerate it before installing. Use `wfctl plugin ci` or
 `wfctl plugin install --locked` in CI to fail on stale locks instead of
 modifying the checkout.
 
-By default, project plugins install to `data/plugins`. Override the directory
-with `--plugin-dir` or `WFCTL_PLUGIN_DIR`.
+By default, project plugin install commands write to `data/plugins`. Override
+the install directory with `--plugin-dir`; commands that load installed
+project plugins may also honor `WFCTL_PLUGIN_DIR` as documented in their
+individual help.
 
 ## Global Plugin Lifecycle
 

From cfeaa65d4e24240f57a4f1e3484faba5a51f0ec6 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:12:25 -0400
Subject: [PATCH 11/16] docs: align wfctl quickstart examples

---
 docs/WFCTL.md              | 5 ++++-
 docs/WFCTL_INSTALLATION.md | 2 +-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 8f56a009..0377250f 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -25,8 +25,11 @@ before moving `wfctl` into `PATH`.
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
 if command -v shasum >/dev/null 2>&1; then
   grep "  $asset$" checksums.txt | shasum -a 256 -c -
-else
+elif command -v sha256sum >/dev/null 2>&1; then
   grep "  $asset$" checksums.txt | sha256sum -c -
+else
+  echo "missing checksum tool: install shasum or sha256sum" >&2
+  exit 1
 fi
 chmod +x "./$asset"
 sudo install -m 0755 "./$asset" /usr/local/bin/wfctl
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 3f55e057..68f73bb1 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -167,7 +167,7 @@ wfctl plugin add workflow-plugin-auth@v0.4.0
 # Refresh the lockfile after editing wfctl.yaml.
 wfctl plugin lock
 
-# Install all locked project plugins into ./data/plugins.
+# Install all locked project plugins into data/plugins.
 wfctl plugin install
 
 # CI path: install exactly from the lockfile and do not write files.

From 2b69f74b7d53932c0cd881346816052fa57daab0 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:19:50 -0400
Subject: [PATCH 12/16] docs: guard browser checksum example

---
 docs/WFCTL_INSTALLATION.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 68f73bb1..f2330067 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -100,8 +100,11 @@ macOS or Linux:
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
 if command -v shasum >/dev/null 2>&1; then
   grep "  $asset$" checksums.txt | shasum -a 256 -c -
-else
+elif command -v sha256sum >/dev/null 2>&1; then
   grep "  $asset$" checksums.txt | sha256sum -c -
+else
+  echo "missing checksum tool: install shasum or sha256sum" >&2
+  exit 1
 fi
 chmod +x "./$asset"
 sudo install -m 0755 "./$asset" /usr/local/bin/wfctl

From 4dae2a9a394258cd4e7f8b0780f5e19c55e4d786 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:33:41 -0400
Subject: [PATCH 13/16] docs: fail closed on missing checksum rows

---
 docs/WFCTL.md              |  9 +++++++--
 docs/WFCTL_INSTALLATION.md | 17 ++++++++++++++---
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 0377250f..2710ecbf 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -23,10 +23,15 @@ before moving `wfctl` into `PATH`.
 
 ```bash
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
+checksum_line="$(grep "  $asset$" checksums.txt || true)"
+if [ -z "$checksum_line" ]; then
+  echo "missing checksum entry for $asset" >&2
+  exit 1
+fi
 if command -v shasum >/dev/null 2>&1; then
-  grep "  $asset$" checksums.txt | shasum -a 256 -c -
+  printf '%s\n' "$checksum_line" | shasum -a 256 -c -
 elif command -v sha256sum >/dev/null 2>&1; then
-  grep "  $asset$" checksums.txt | sha256sum -c -
+  printf '%s\n' "$checksum_line" | sha256sum -c -
 else
   echo "missing checksum tool: install shasum or sha256sum" >&2
   exit 1
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index f2330067..33ae7194 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -57,6 +57,12 @@ base="https://github.com/GoCodeAlone/workflow/releases/latest/download"
 curl -fL "$base/$asset" -o "$tmpdir/$asset"
 curl -fL "$base/checksums.txt" -o "$tmpdir/checksums.txt"
 
+checksum_line="$(grep "  $asset$" "$tmpdir/checksums.txt" || true)"
+if [ -z "$checksum_line" ]; then
+  echo "missing checksum entry for $asset" >&2
+  exit 1
+fi
+
 if command -v shasum >/dev/null 2>&1; then
   checksum_cmd=(shasum -a 256 -c -)
 elif command -v sha256sum >/dev/null 2>&1; then
@@ -66,7 +72,7 @@ else
   exit 1
 fi
 
-(cd "$tmpdir" && grep "  $asset$" checksums.txt | "${checksum_cmd[@]}")
+(cd "$tmpdir" && printf '%s\n' "$checksum_line" | "${checksum_cmd[@]}")
 chmod +x "$tmpdir/$asset"
 sudo install -m 0755 "$tmpdir/$asset" /usr/local/bin/wfctl
 
@@ -98,10 +104,15 @@ macOS or Linux:
 
 ```bash
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
+checksum_line="$(grep "  $asset$" checksums.txt || true)"
+if [ -z "$checksum_line" ]; then
+  echo "missing checksum entry for $asset" >&2
+  exit 1
+fi
 if command -v shasum >/dev/null 2>&1; then
-  grep "  $asset$" checksums.txt | shasum -a 256 -c -
+  printf '%s\n' "$checksum_line" | shasum -a 256 -c -
 elif command -v sha256sum >/dev/null 2>&1; then
-  grep "  $asset$" checksums.txt | sha256sum -c -
+  printf '%s\n' "$checksum_line" | sha256sum -c -
 else
   echo "missing checksum tool: install shasum or sha256sum" >&2
   exit 1

From 7cfcaf5ec811f43d11ce97cb37ad6060051eecde Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:42:59 -0400
Subject: [PATCH 14/16] docs: match checksum assets exactly

---
 docs/WFCTL.md              | 2 +-
 docs/WFCTL_INSTALLATION.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 2710ecbf..1a6f6cba 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -23,7 +23,7 @@ before moving `wfctl` into `PATH`.
 
 ```bash
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
-checksum_line="$(grep "  $asset$" checksums.txt || true)"
+checksum_line="$(awk -v asset="$asset" '$2 == asset { print; found = 1; exit } END { if (!found) exit 1 }' checksums.txt || true)"
 if [ -z "$checksum_line" ]; then
   echo "missing checksum entry for $asset" >&2
   exit 1
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 33ae7194..462752e9 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -57,7 +57,7 @@ base="https://github.com/GoCodeAlone/workflow/releases/latest/download"
 curl -fL "$base/$asset" -o "$tmpdir/$asset"
 curl -fL "$base/checksums.txt" -o "$tmpdir/checksums.txt"
 
-checksum_line="$(grep "  $asset$" "$tmpdir/checksums.txt" || true)"
+checksum_line="$(awk -v asset="$asset" '$2 == asset { print; found = 1; exit } END { if (!found) exit 1 }' "$tmpdir/checksums.txt" || true)"
 if [ -z "$checksum_line" ]; then
   echo "missing checksum entry for $asset" >&2
   exit 1
@@ -104,7 +104,7 @@ macOS or Linux:
 
 ```bash
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
-checksum_line="$(grep "  $asset$" checksums.txt || true)"
+checksum_line="$(awk -v asset="$asset" '$2 == asset { print; found = 1; exit } END { if (!found) exit 1 }' checksums.txt || true)"
 if [ -z "$checksum_line" ]; then
   echo "missing checksum entry for $asset" >&2
   exit 1

From 3e218f59846823bcfb6c1961cbd84db54b63ee80 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:48:25 -0400
Subject: [PATCH 15/16] docs: ensure wfctl install target exists

---
 docs/WFCTL.md              | 1 +
 docs/WFCTL_INSTALLATION.md | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 1a6f6cba..3bada174 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -37,6 +37,7 @@ else
   exit 1
 fi
 chmod +x "./$asset"
+sudo install -d -m 0755 /usr/local/bin
 sudo install -m 0755 "./$asset" /usr/local/bin/wfctl
 ```
 
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 462752e9..2220a1dd 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -74,6 +74,7 @@ fi
 
 (cd "$tmpdir" && printf '%s\n' "$checksum_line" | "${checksum_cmd[@]}")
 chmod +x "$tmpdir/$asset"
+sudo install -d -m 0755 /usr/local/bin
 sudo install -m 0755 "$tmpdir/$asset" /usr/local/bin/wfctl
 
 wfctl --version
@@ -118,6 +119,7 @@ else
   exit 1
 fi
 chmod +x "./$asset"
+sudo install -d -m 0755 /usr/local/bin
 sudo install -m 0755 "./$asset" /usr/local/bin/wfctl
 ```
 

From e0fcc378ec55430cd8cc15bb722e0219b86f0392 Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Fri, 3 Jul 2026 20:54:42 -0400
Subject: [PATCH 16/16] docs: normalize checksum filenames

---
 docs/WFCTL.md              | 2 +-
 docs/WFCTL_INSTALLATION.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/WFCTL.md b/docs/WFCTL.md
index 3bada174..91445dcc 100644
--- a/docs/WFCTL.md
+++ b/docs/WFCTL.md
@@ -23,7 +23,7 @@ before moving `wfctl` into `PATH`.
 
 ```bash
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
-checksum_line="$(awk -v asset="$asset" '$2 == asset { print; found = 1; exit } END { if (!found) exit 1 }' checksums.txt || true)"
+checksum_line="$(awk -v asset="$asset" '{ file = $2; sub(/^\*/, "", file); sub(/^\.\//, "", file); if (file == asset) { print $1 "  " asset; found = 1; exit } } END { if (!found) exit 1 }' checksums.txt || true)"
 if [ -z "$checksum_line" ]; then
   echo "missing checksum entry for $asset" >&2
   exit 1
diff --git a/docs/WFCTL_INSTALLATION.md b/docs/WFCTL_INSTALLATION.md
index 2220a1dd..23ea63ef 100644
--- a/docs/WFCTL_INSTALLATION.md
+++ b/docs/WFCTL_INSTALLATION.md
@@ -57,7 +57,7 @@ base="https://github.com/GoCodeAlone/workflow/releases/latest/download"
 curl -fL "$base/$asset" -o "$tmpdir/$asset"
 curl -fL "$base/checksums.txt" -o "$tmpdir/checksums.txt"
 
-checksum_line="$(awk -v asset="$asset" '$2 == asset { print; found = 1; exit } END { if (!found) exit 1 }' "$tmpdir/checksums.txt" || true)"
+checksum_line="$(awk -v asset="$asset" '{ file = $2; sub(/^\*/, "", file); sub(/^\.\//, "", file); if (file == asset) { print $1 "  " asset; found = 1; exit } } END { if (!found) exit 1 }' "$tmpdir/checksums.txt" || true)"
 if [ -z "$checksum_line" ]; then
   echo "missing checksum entry for $asset" >&2
   exit 1
@@ -105,7 +105,7 @@ macOS or Linux:
 
 ```bash
 asset=wfctl-darwin-arm64 # replace with the asset you downloaded
-checksum_line="$(awk -v asset="$asset" '$2 == asset { print; found = 1; exit } END { if (!found) exit 1 }' checksums.txt || true)"
+checksum_line="$(awk -v asset="$asset" '{ file = $2; sub(/^\*/, "", file); sub(/^\.\//, "", file); if (file == asset) { print $1 "  " asset; found = 1; exit } } END { if (!found) exit 1 }' checksums.txt || true)"
 if [ -z "$checksum_line" ]; then
   echo "missing checksum entry for $asset" >&2
   exit 1