optbrew 0.1.1 → 0.1.3

package/README.md

@@ -1,73 +1,148 @@
 # optbrew
 
+[![npm](https://img.shields.io/npm/v/optbrew.svg)](https://www.npmjs.com/package/optbrew)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 [한국어](README.ko.md)
 
-Optbrew is a local skill and CLI for checking a site's search readiness, making approved local changes, and comparing evidence before and after. It combines five pinned source bundles—mblode SEO, Naver Search Advisor, Firecrawl SEO Audit, Magnus SEO, and SE Ranking SEO—with seven selected marketing guides. One top-level `SKILL.md` routes to the included guides. The bundle works from its pinned files; it does not fetch a moving upstream revision during a run.
+A search-readiness audit skill for coding agents. optbrew checks a site for Google, Naver and AI answer engines, fixes the local files you approve, checks again under the same conditions, and writes a scored report built from replayable evidence.
+
+- One skill for five profiles: **SEO**, **NEO** (Naver), **AEO**, **GEO** and **LLMO**.
+- Five pinned audit guide bundles merged into 22 check families. An issue that several guides report is counted once.
+- Every verdict in the report can be recomputed from the raw responses that were collected and hashed.
+- No headline score when the evidence is thin: below 80% coverage the report shows the measured part and its bounds.
+- Works with Codex, Claude Code, Cursor, OpenCode and Pi. Scoring and reports need no API account.
+
+## Why optbrew
+
+Being found now means three different things: ranking in Google, showing in Naver, and being cited in AI answers. Each has its own guides, and the guides overlap and disagree. An agent asked to "improve SEO" usually picks one checklist, edits files, and reports success without proof.
+
+optbrew gives the agent one workflow and one scoring rule for all five profiles. It counts what it measured, marks what it could not measure as unknown instead of passing it, and keeps a local fix separate from a production result. A high readiness score is not a promise of traffic or citations, and the report says so.
+
+## How it works
+
+1. **Audit.** You give the URL, the goal and the scope. A collector makes at most 50 requests (pages, redirects and robots or sitemap files together; depth 3, two at a time) and stores every response with its hash.
+2. **Fix.** The agent proposes changes to local files. Nothing is edited, deployed or submitted without your approval.
+3. **Re-check.** The same collection runs again under the same conditions, so the before and after are comparable.
+4. **Report.** A score per profile with its coverage, blockers, open core checks, and separate tables for readiness, fixes, real outcomes and remaining work.
+
+What the script measures by itself, and what still needs the guides and the agent's judgment:
+
+| Profile | Target | Measured by the script | Left to judgment |
+|---|---|---|---|
+| SEO | Google and web search | Fetch status, `noindex` in meta and `X-Robots-Tag`, titles, robots.txt for Googlebot, canonical, redirect chains, discovery through links and sitemap, JSON-LD syntax | Content quality and intent fit |
+| NEO | Naver | robots.txt for Yeti, Open Graph, description, canonical, viewport, title repetition, blocked CSS or JS | Naver-specific content guidance |
+| AEO, GEO | Answer engines and AI search | robots.txt for the AI search bots in [ai-crawlers.md](skills/optbrew/references/ai-crawlers.md) (training bots are never scored) | Answer structure, claims, authorship, freshness |
+| LLMO | How models describe you | Whether name, address, phone and founding year agree across pages, and whether the pages describe one business | Whether those facts are true |
 
-The CLI can calculate a score and write a report from stored JSON without an API account. A site audit needs a declared target and scope. Publication, search engine submission, remote site changes, and paid calls require separate authority. Read [platform support](docs/platforms.md) for the difference between installing a file and confirming that a host invoked it.
+Engine-specific checks run for the engines you name as targets. Say that Naver matters, or name the AI answer engines you care about, such as ChatGPT, Claude or Perplexity. The scoring rule is in [scoring.md](skills/optbrew/references/scoring.md). The 80% coverage threshold is optbrew's own rule, not a search engine standard.
 
 ## Install
 
-Requires Node.js 22 or later. The internal Python audit utilities need Python 3.10 or later; missing Python leaves those utilities unrun. From this checkout, first inspect the targets in an isolated project directory named `site`:
+Requires [Node.js](https://nodejs.org) 22 or later. Python 3.10 or later is optional; without it, the internal Python audit utilities stay unrun. Pick one of the five methods. The examples install for Codex and Claude Code at user level; the agent IDs are `codex`, `claude-code`, `cursor`, `opencode` and `pi`.
 
-Bash and PowerShell use the same commands:
+In Windows PowerShell, if `npx` or `optbrew` reports that running scripts is disabled, type `npx.cmd` or `optbrew.cmd` instead.
 
-```text
-node bin/optbrew.mjs install --agents codex,claude-code,cursor,opencode,pi --scope project --project ./site --strategy copy --dry-run --json
-node bin/optbrew.mjs install --agents codex,claude-code,cursor,opencode,pi --scope project --project ./site --strategy copy --json
-node bin/optbrew.mjs doctor --agents codex,claude-code,cursor,opencode,pi --scope project --project ./site --json
+### 1. npm
+
+```bash
+npm install -g optbrew@0.1.3
+optbrew install --agents codex,claude-code --scope user --dry-run
+optbrew install --agents codex,claude-code --scope user
+optbrew doctor --agents codex,claude-code --scope user
 ```
 
-Create `site` first and run these commands from the repository root. `--strategy link` is the default; `copy` also works when links are unavailable. The managed record lives under that project's `.optbrew/install`. For one host, replace the comma-separated list with its exact ID: `codex`, `claude-code`, `cursor`, `opencode`, or `pi`. Use `--scope user` only when you intend to install into user-level host directories. The install command checks the bundle manifest and refuses to replace an unmanaged target.
+The dry run prints the folders it will write. `doctor` checks the files and their hashes.
 
-To get the checkout, clone `https://github.com/nowwcastle-sudo/optbrew` and run the commands above from its root. `npm install -g optbrew` installs the same CLI as an `optbrew` command; replace `node bin/optbrew.mjs` with `optbrew` in the commands above. Native host distribution and the ZIP path are described in [platform support](docs/platforms.md).
+### 2. npx
 
-## First use
+Runs the same CLI without a global install:
+
+```bash
+npx optbrew@0.1.3 install --agents codex,claude-code --scope user
+npx optbrew@0.1.3 doctor --agents codex,claude-code --scope user
+```
 
-Ask the host to use optbrew with the target URL, goal, site ownership or access, allowed local changes, and available evidence. For a local audit, declare the URL scope before collection. The default collection ceilings are 50 URLs, depth 3, and concurrency 2; private addresses need an explicit local target. The workflow records raw evidence, readiness observations, local changes, and follow-up checks. It does not infer a site's production result from a passing local test.
+### 3. PowerShell (Windows)
 
-The examples below replay bundled synthetic fixtures. They make no provider call. Run them from the checkout root and choose fresh output paths:
+```powershell
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.1.3/install.ps1 | iex
+```
 
-Bash and PowerShell use the same commands:
+The script is pinned to this release. It checks Node.js, shows the target folders, installs for Codex and Claude Code, and stops with an error if `doctor` finds a problem. To read it first, or to choose agents or a project folder:
 
-```text
-node bin/optbrew.mjs score --input ./before.json --output ./score.json
-node bin/optbrew.mjs compare --before ./before.json --after ./after.json --output ./comparison.json
-node bin/optbrew.mjs report --input ./remote-only.json --output-dir ./report-output
+```powershell
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.1.3/install.ps1 -OutFile install.ps1
+powershell -ExecutionPolicy Bypass -File .\install.ps1 -Agents codex,claude-code,cursor
 ```
 
-For those literal commands, copy `tests/fixtures/scoring/before.json` and `after.json` into the current directory, and copy `tests/fixtures/reports/remote-only.json` plus its sibling evidence files into the current directory. For real work, pass your own validated `ScoreInput` or `ReportPacket` paths. See [scoring](skills/optbrew/references/scoring.md), [measurement](skills/optbrew/references/measurement.md), and [report evidence](skills/optbrew/references/report.md) for the contracts.
+Add `-Scope project -Project C:\path\to\site` to install into one project.
 
-## Score and report
+### 4. Plugin
 
-The five optbrew readiness profiles are SEO, NEO when Naver is a target, AEO, GEO, and LLMO. The 22 unique check families are counted once even when several guides find the same issue. An unknown applicable check remains in the denominator; an evidenced `not_applicable` check is excluded. The result includes score, measured coverage, missing-data bounds, blockers, and unresolved core checks. The 80% coverage threshold is an optbrew rule, not a search engine standard. A high readiness score does not prove indexing, traffic, citations, accuracy, conversions, or revenue.
+Claude Code:
 
-The report keeps readiness, remedies, actual outcomes, and remaining work in separate tables. Actual outcomes need owner exports or a fixed AI question panel. A normal outcome comparison uses two complete, adjacent 28-day windows with matching definitions and filters. A local edit remains local until deployment and a production observation have their own evidence.
+```bash
+claude plugin marketplace add nowwcastle-sudo/optbrew
+claude plugin install optbrew@optbrew
+```
 
-## APIs and cost
+Codex:
 
-API access is optional. A Claude or Claude Code subscription does not supply Anthropic API billing. To use a direct API key, follow the [official key guide](https://platform.claude.com/docs/en/get-api-key): Console → Settings → API keys. Put the key in the `ANTHROPIC_API_KEY` environment variable in your own shell or secret manager; never put a real value in a report. A key spanning multiple Anthropic workspaces may require an `anthropic-workspace-id` header. The direct adapter introduced in v0.1.0 still does not set that header, so use a compatible key or a separately approved host capability.
+```bash
+codex plugin marketplace add nowwcastle-sudo/optbrew
+codex plugin add optbrew@optbrew
+```
+
+Plugins follow this repository's `main` branch and update through the host's plugin commands.
+
+### 5. Ask your agent
 
-The direct adapter accepts only text `{model,max_tokens,messages}` requests for the exact model IDs `claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5`, and `claude-haiku-5-5`. `max_tokens` cannot exceed 128,000. Each attempt needs one token reservation of at least `1,000,000 + max_tokens`, a matching ledger budget, and an approval reference. This is a worst-case capacity bound, not a bill estimate. Record the current price source, estimated spend, and approved stop condition before the first paid call. Extra fields, tools, search, non-text input, unknown models, or currency-only bounds make zero direct calls. See [API boundaries](skills/optbrew/references/api.md).
+Paste this into Codex, Claude Code or another coding agent:
 
-SE Ranking has its own [API](https://seranking.com/api.html), [MCP instructions](https://seranking.com/api/integrations/mcp), account plan, and credits. Its [HTTP MCP endpoint](https://api.seranking.com/mcp) uses its documented OAuth or direct-token path, independently of `ANTHROPIC_API_KEY`. Available tools depend on the subscription. Neither connection is required for offline scoring. Use actual account prices and credits when deciding whether to run a paid capability; no price is built into this README.
+```text
+Install the optbrew skill for me. Read https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.1.3/AGENT_INSTALL.md and follow it step by step. Ask me which agents and which scope to use, and show me the planned changes before you install.
+```
 
-## Update and rollback
+[AGENT_INSTALL.md](AGENT_INSTALL.md) gives the agent a command and a pass check for each step, and the cases where it must stop and ask you.
 
-For a managed project installation, rebuild or obtain a verified newer optbrew bundle before updating. From the checkout root:
+Installing from a source checkout, the Agent Skills CLI, Pi packages and Claude web uploads are covered in [platform support](docs/platforms.md).
 
-Bash and PowerShell use the same commands:
+## Quick start
+
+Start a new agent session and ask, for example:
 
 ```text
-node bin/optbrew.mjs check-updates --json
-node bin/optbrew.mjs update --scope project --project ./site --json
-node bin/optbrew.mjs rollback --scope project --project ./site --release-version 0.1.0 --json
+Run optbrew on https://example.com. Goal: show up in Naver and get cited in AI answers.
 ```
 
-Without a confirmed registry package, `check-updates` reports `local_only`. `update` uses the current CLI bundle, verifies it, and updates all targets in that install record; it does not silently replace local edits. `rollback` needs that version in the record's retained prior releases. The shown rollback will therefore fail on a fresh 0.1.1 install and applies to a managed installation that retains local 0.1.0. `npm update -g optbrew` updates npm's package files after release; it does not rewrite a copy already placed in an agent skills directory. Run the managed `update` command again after updating the CLI. Native plugin and Pi package update paths are in [platform support](docs/platforms.md).
+optbrew asks for anything it is missing: site ownership or access, which local changes are allowed, and which evidence you already have. Raw evidence goes to `.optbrew/runs`. Private network addresses are fetched only when you declare a local target.
+
+## Update
+
+```bash
+npm install -g optbrew@latest
+optbrew update --scope user
+```
+
+With npx, run `npx optbrew@latest update --scope user`. `optbrew check-updates --package optbrew` tells you, without changing anything, whether npm has a newer release than the CLI you are running; `optbrew doctor --json` shows the `release_version` installed in your agent folders. `npm update` alone does not touch copies already placed in agent folders; the `update` command does.
+
+An install from 0.1.2 or earlier stops with `migration_required`, because 0.1.3 scores with a new evaluation version. Scores from different evaluation versions are not comparable. Follow [Reinstall after a migration_required update](docs/platforms.md#reinstall-after-a-migration_required-update); the steps delete only paths that a read-only check printed and never touch your audit evidence.
+
+## APIs and cost
+
+Nothing here requires a paid account. A direct Anthropic API call or an [SE Ranking](https://seranking.com/api.html) call needs your approval, a recorded budget and a stop condition first; a Claude subscription does not include API billing. Keys stay in your environment variables and never go into a report. Details: [API boundaries](skills/optbrew/references/api.md).
+
+## Documentation
+
+- [Platform support](docs/platforms.md): install paths per agent, checkout commands, reinstall steps
+- [Scoring](skills/optbrew/references/scoring.md), [measurement](skills/optbrew/references/measurement.md) and [report evidence](skills/optbrew/references/report.md)
+- [Changelog](CHANGELOG.md) and [release process](docs/release.md)
+
+## Contributing
 
-## Support and license
+Contributions are welcome: bug reports, false positives from a real site, guide updates, translations and code. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Managed install, doctor, update, and rollback cover Codex, Claude Code, Cursor, OpenCode, and Pi at the documented default paths. Custom host directories, project trust, and session reload rules can change discovery. Ordinary ChatGPT chat uses attached files and instructions; it is not the same installation path as Codex or a Work/desktop plugin. Claude web requires manual ZIP upload and re-upload for updates. Host discovery and a successful real invocation require separate checks.
+## License
 
-The Naver bundle retains an index of official [Search Advisor guides](https://searchadvisor.naver.com/guide). It excludes the 55 original Naver article bodies, so full offline article lookup is unavailable. Follow the official links while online. Included source licenses and changes are listed in [third-party notices](skills/optbrew/THIRD_PARTY_NOTICES.md); optbrew's own code is [MIT licensed](LICENSE). Service access and API data rights are separate from those code licenses. Release packaging and verification are in [release instructions](docs/release.md).
+optbrew's own code is [MIT licensed](LICENSE). The bundled guides keep their own licenses, listed in [third-party notices](skills/optbrew/THIRD_PARTY_NOTICES.md). The Naver bundle keeps an index of the official [Search Advisor guides](https://searchadvisor.naver.com/guide) but not the 55 article bodies; follow the official links while online.

package/docs/platforms.md

@@ -1,6 +1,6 @@
 # Platform installation and update paths
 
-Optbrew v0.1.1 contains one skill source at `skills/optbrew`. The managed CLI can place it at five hosts' documented default paths. A file in a host path proves placement, not that the host discovered, loaded, or invoked the skill. Confirm those three steps in a fresh host session before reporting host support as exercised.
+Optbrew v0.1.3 contains one skill source at `skills/optbrew`. The managed CLI can place it at five hosts' documented default paths. A file in a host path proves placement, not that the host discovered, loaded, or invoked the skill. Confirm those three steps in a fresh host session before reporting host support as exercised.
 
 | Host | Managed project target | Managed user target | Discovery and invocation boundary |
 |---|---|---|---|
@@ -14,17 +14,130 @@ The CLI maps only these default targets. Custom roots, host policies, remote age
 
 ## Managed checkout and npm paths
 
-The [README](../README.md) shows parser-checked checkout commands for install, doctor, update, and rollback. The CLI validates bundle hashes before an install or update. `update` replaces every target in one managed record as a unit. An edited target makes the default update stop; the explicit `--local-changes backup-and-replace` policy retains a readable backup. `rollback --release-version VERSION` works only when that version is in the record's retained prior releases. A fresh installation has no older release.
+The [README](../README.md) shows the npm, npx, PowerShell, plugin and agent install routes. This section holds the parser-checked commands for a source checkout. Clone `https://github.com/nowwcastle-sudo/optbrew`, create an empty `site` folder, and run them from the repository root. With the npm package installed, replace `node bin/optbrew.mjs` with `optbrew`.
 
-After a public npm release, `npm install -g optbrew` and `npm update -g optbrew` manage the package in npm. Neither command rewrites an old copied skill target. Run the installed CLI's managed `update` after the package update, then `doctor` and a new-session invocation check. `check-updates --json` is read-only; without a confirmed registry name it returns `local_only`. The package is not public merely because `package.json` names it.
+Install into an isolated project folder, after a dry run:
+
+Bash and PowerShell use the same commands:
+
+```text
+node bin/optbrew.mjs install --agents codex,claude-code,cursor,opencode,pi --scope project --project ./site --strategy copy --dry-run --json
+node bin/optbrew.mjs install --agents codex,claude-code,cursor,opencode,pi --scope project --project ./site --strategy copy --json
+node bin/optbrew.mjs doctor --agents codex,claude-code,cursor,opencode,pi --scope project --project ./site --json
+```
+
+`--strategy link` is the default; `copy` also works when links are unavailable. The managed record lives under that project's `.optbrew/install`. For one host, replace the comma-separated list with its exact ID. Use `--scope user` only when you intend to install into user-level host directories. The install command checks the bundle manifest and refuses to replace an unmanaged target.
+
+Replay the bundled synthetic fixtures without any provider call. Copy `tests/fixtures/scoring/before.json` and `after.json`, and `tests/fixtures/reports/remote-only.json` with its sibling evidence files, into the current directory first:
+
+Bash and PowerShell use the same commands:
+
+```text
+node bin/optbrew.mjs score --input ./before.json --output ./score.json
+node bin/optbrew.mjs compare --before ./before.json --after ./after.json --output ./comparison.json
+node bin/optbrew.mjs report --input ./remote-only.json --output-dir ./report-output
+```
+
+Check for updates, update, and roll back a managed project install:
+
+Bash and PowerShell use the same commands:
+
+```text
+node bin/optbrew.mjs check-updates --json
+node bin/optbrew.mjs update --scope project --project ./site --json
+node bin/optbrew.mjs rollback --scope project --project ./site --release-version 0.1.0 --json
+```
+
+The shown rollback fails on a fresh 0.1.3 install, because no earlier release is retained; it applies to a managed install that retains local 0.1.0.
+
+The CLI validates bundle hashes before an install or update. `update` replaces every target in one managed record as a unit. An edited target makes the default update stop; the explicit `--local-changes backup-and-replace` policy retains a readable backup. `rollback --release-version VERSION` works only when that version is in the record's retained prior releases. A fresh installation has no older release.
+
+After a public npm release, `npm install -g optbrew` and `npm update -g optbrew` manage the package in npm. Neither command rewrites an old copied skill target. Run the installed CLI's managed `update` after the package update, then `doctor` and a new-session invocation check. `check-updates --package optbrew --json` is read-only and compares the installed release with the npm registry; without `--package` it returns `local_only`.
+
+## Reinstall after a migration_required update
+
+Release 0.1.3 uses evaluation version 0.3.0; 0.1.2 used 0.2.0. The managed updater refuses a change of evaluation version, so `optbrew update` on a managed 0.1.2 install stops with `migration_required` and changes nothing. There is no `uninstall` command. Replace the install by hand: the blocks below delete the install's targets and then its managed root, and run `install` again from the 0.1.3 checkout. Scores and baselines made with 0.1.2 are not comparable with 0.1.3; `compare` returns `not_comparable` (`evaluation_version_changed`). Run the baseline audit again with 0.1.3.
+
+The blocks do not trust the install record. Each one first runs the read-only `node bin/optbrew.mjs reinstall-plan`, which resolves the home directory the way the CLI does (`HOME`, else the operating system's home directory), checks that the record belongs to this scope, that every recorded target is exactly the agent's `skills/optbrew` path (absolute, no `..`, no linked folder on the way, inside the scope or project), and that an existing target is a link to the managed bundle or a real folder holding a bundle manifest. If any check fails it prints the reason, exits with a nonzero code, and the block deletes nothing. Otherwise the shell deletes only the paths it printed: the targets first, then `<scope root>/.optbrew/installs/user` (user scope) or `<project>/.optbrew/install` (project scope), which holds the install record. Because the record goes last, you can run the same block again after a failure. The commands never touch `<scope root>/.optbrew/runs`, where your audit evidence lives; do not delete the whole `.optbrew` folder. Each agent is installed again with the strategy (`link` or `copy`) the record had, then `doctor` runs. Run the blocks from the 0.1.3 checkout root. If `reinstall-plan` refuses the record, fix or remove the named path by hand and look at it first; the CLI also refuses to overwrite a target it does not own.
+
+User scope:
+
+```powershell user
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+$plan = @(node bin/optbrew.mjs reinstall-plan --scope user)
+if ($LASTEXITCODE) { exit $LASTEXITCODE }
+foreach ($line in $plan) {
+  $f = $line -split "`t"
+  if ($f[0] -eq 'delete-link') { [IO.Directory]::Delete($f[1]) }
+  elseif ($f[0] -eq 'delete-dir') { Remove-Item -Recurse -Force -LiteralPath $f[1] }
+}
+foreach ($line in $plan) {
+  $f = $line -split "`t"
+  if ($f[0] -eq 'install') { node bin/optbrew.mjs install --agents $f[1] --scope user --strategy $f[2]; if ($LASTEXITCODE) { exit $LASTEXITCODE } }
+  elseif ($f[0] -eq 'agents') { node bin/optbrew.mjs doctor --agents $f[1] --scope user; exit $LASTEXITCODE }
+}
+```
+
+```bash user
+set -e
+plan=$(node bin/optbrew.mjs reinstall-plan --scope user)
+while IFS=$'\t' read -r kind a b; do
+  case "$kind" in delete-link | delete-dir) rm -r -- "$a" ;; esac
+done <<< "$plan"
+while IFS=$'\t' read -r kind a b; do
+  case "$kind" in
+    install) node bin/optbrew.mjs install --agents "$a" --scope user --strategy "$b" ;;
+    agents) node bin/optbrew.mjs doctor --agents "$a" --scope user ;;
+  esac
+done <<< "$plan"
+```
+
+Project scope (replace `./site` with your project folder; it appears once):
+
+```powershell project
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+$project = './site'
+$plan = @(node bin/optbrew.mjs reinstall-plan --scope project --project $project)
+if ($LASTEXITCODE) { exit $LASTEXITCODE }
+foreach ($line in $plan) {
+  $f = $line -split "`t"
+  if ($f[0] -eq 'delete-link') { [IO.Directory]::Delete($f[1]) }
+  elseif ($f[0] -eq 'delete-dir') { Remove-Item -Recurse -Force -LiteralPath $f[1] }
+}
+foreach ($line in $plan) {
+  $f = $line -split "`t"
+  if ($f[0] -eq 'install') { node bin/optbrew.mjs install --agents $f[1] --scope project --project $project --strategy $f[2]; if ($LASTEXITCODE) { exit $LASTEXITCODE } }
+  elseif ($f[0] -eq 'agents') { node bin/optbrew.mjs doctor --agents $f[1] --scope project --project $project; exit $LASTEXITCODE }
+}
+```
+
+```bash project
+set -e
+project='./site'
+plan=$(node bin/optbrew.mjs reinstall-plan --scope project --project "$project")
+while IFS=$'\t' read -r kind a b; do
+  case "$kind" in delete-link | delete-dir) rm -r -- "$a" ;; esac
+done <<< "$plan"
+while IFS=$'\t' read -r kind a b; do
+  case "$kind" in
+    install) node bin/optbrew.mjs install --agents "$a" --scope project --project "$project" --strategy "$b" ;;
+    agents) node bin/optbrew.mjs doctor --agents "$a" --scope project --project "$project" ;;
+  esac
+done <<< "$plan"
+```
+
+Inside 0.1.3 and later releases that keep evaluation version 0.3.0, `update` and `rollback` work as before. The same refusal and steps apply to any future release that changes the evaluation version.
 
 ## Native host routes
 
 These are alternatives to the managed CLI. Do not mix their ownership records for the same target path.
 
 - **Agent Skills tool:** Current [Vercel Skills CLI](https://github.com/vercel-labs/skills) documents `npx skills add ./` for a local source and `npx skills update optbrew` for an installation it owns. Run from a checkout containing the skill. Confirm its host selection and destination before writing. The public repository is `https://github.com/nowwcastle-sudo/optbrew`.
-- **Claude Code plugin:** The local `.claude-plugin/marketplace.json` and `plugin.json` name `optbrew@optbrew-local` at version 0.1.1. The installed Claude CLI help accepts `claude plugin marketplace add --scope project .`, then `claude plugin install --scope project optbrew@optbrew-local` from this checkout. Later, `claude plugin update --scope project optbrew@optbrew-local` applies the marketplace's newer version and requires a restart. These commands change Claude settings, so documentation checks inspect `--help` without registering a marketplace. [Claude Code plugin instructions](https://code.claude.com/docs/en/plugins) also describe the interactive `/plugin` path. Marketplace auto-update is a user setting; the marketplace file does not enable it. Verify the selected release version and a fresh-session invocation after a native update.
-- **Pi package:** Current [Pi package instructions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) document `pi install ./local-package`, `pi install npm:package-name@version`, `pi list`, and `pi update --extensions`. `pi install ./` installs from a local checkout when Pi is installed; `pi install npm:optbrew@0.1.1` installs the published npm package. The package's `pi.skills` entry points to `./skills/optbrew`. A project-local package declaration uses Pi's `--local` option and is subject to project trust. Check the installed Pi version's help and package list before updating.
+- **Claude Code plugin:** `.claude-plugin/marketplace.json` and `plugin.json` name the plugin `optbrew@optbrew` at version 0.1.3. Run `claude plugin marketplace add nowwcastle-sudo/optbrew`, then `claude plugin install optbrew@optbrew` (add `--scope project` to keep it in one project). Later, `claude plugin update optbrew@optbrew` applies the marketplace's newer version and requires a restart. `claude plugin validate .` checks both files from a checkout.
+- **Codex plugin:** `.agents/plugins/marketplace.json` lists the same `optbrew` plugin. Run `codex plugin marketplace add nowwcastle-sudo/optbrew`, then `codex plugin add optbrew@optbrew`, or choose it in `/plugins`. Start a new Codex task afterwards. [Claude Code plugin instructions](https://code.claude.com/docs/en/plugins) also describe the interactive `/plugin` path. Marketplace auto-update is a user setting; the marketplace file does not enable it. Verify the selected release version and a fresh-session invocation after a native update.
+- **Pi package:** Current [Pi package instructions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) document `pi install ./local-package`, `pi install npm:package-name@version`, `pi list`, and `pi update --extensions`. `pi install ./` installs from a local checkout when Pi is installed; `pi install npm:optbrew@0.1.3` installs the published npm package. The package's `pi.skills` entry points to `./skills/optbrew`. A project-local package declaration uses Pi's `--local` option and is subject to project trust. Check the installed Pi version's help and package list before updating.
 - **Claude web:** Upload the built skill ZIP manually in the supported web interface. Upload a new ZIP again for each update. There is no verified automatic update of that upload.
 - **Ordinary ChatGPT chat:** Attach the relevant skill files or ZIP and give the assistant the target and scope. This is attachment-guided use. It is not the Codex installation path and does not establish Work/desktop plugin discovery.
 

package/docs/release.md

@@ -1,13 +1,14 @@
 # Release procedure
 
-This checkout is version 0.1.1. A package name, local manifest, or generated ZIP does not establish a public release. Publication, a Git tag, a push, and account changes require their own authorization. This page describes the reviewable local release artifacts and the checks to run before that decision.
+This checkout is version 0.1.3. A package name, local manifest, or generated ZIP does not establish a public release. Publication, a Git tag, a push, and account changes require their own authorization. This page describes the reviewable local release artifacts and the checks to run before that decision.
 
 1. Confirm the source commit and clean intended diff. Match `package.json`, the portable plugin, Codex plugin, Claude plugin, marketplace entry, and ZIP name to one release version. Keep `evaluation_version` and `protocol_version` separate from the release version.
 2. Run `npm test` and `python -m unittest discover -s tests/python` on Python 3.10 or later. Run the focused `node --test tests/docs-commands.test.mjs` check when changing examples. The command check runs optbrew against isolated local fixtures; it makes no provider call.
-3. Run `npm run build-bundle`, `node scripts/build-release.mjs --version 0.1.1 --output-dir dist`, `npm pack --pack-destination dist`, `node scripts/verify-release.mjs --dist dist`, and `npm pack --dry-run --json` from the repository root. Rebuild after changing the README or packaged files. Do not treat an older tarball as containing a later documentation edit.
+3. Run `npm run build-bundle`, `node scripts/build-release.mjs --version 0.1.3 --output-dir dist`, `npm pack --pack-destination dist`, `node scripts/verify-release.mjs --dist dist`, and `npm pack --dry-run --json` from the repository root. Rebuild after changing the README or packaged files. Do not treat an older tarball as containing a later documentation edit.
 4. Inspect the npm file list, the ZIP file list, `bundle-manifest.json`, `source-lock.json`, licenses, and secret scan output. The same skill bytes and version must be traceable across the npm package and ZIP. Source notices belong in both. User run evidence, account configuration, keys, private cards, and authoring materials must stay outside both.
 5. Test a fresh isolated managed install, `doctor`, update from a retained earlier release, rollback, and fresh host discovery or invocation where a host is available. A dry run or manifest check does not prove invocation. Record the untested hosts and capabilities.
 6. Only after a reviewed release decision, publish or upload the approved artifacts and verify the public npm and repository readback. Do not infer publication from successful local builds.
+7. `main` is protected by a repository ruleset: no force push, no deletion, changes only through a pull request, linear history. Tags matching `v*` cannot be moved or deleted. Merge the release branch through a pull request, then tag the merge commit `vX.Y.Z`. The README's PowerShell installer and agent prompt load `install.ps1` and `AGENT_INSTALL.md` from that tag, so test both raw URLs after the tag is pushed.
 
 The bundle includes five pinned source bundles plus seven selected marketing guides. The Naver source articles under `references/guide/` (55 original bodies) remain excluded; the index links to official pages and full offline article lookup is unavailable. The published notice must retain upstream MIT/ISC permission texts and modifications. Optbrew's own code uses MIT. These code licenses do not grant service subscriptions or API data rights.
 

package/lib/cli.mjs

@@ -8,10 +8,11 @@ import { checkUpdates, update, rollback } from './update.mjs';
 import { readFile } from 'node:fs/promises';
 import { readInstallRecord } from './records.mjs';
 import { runCli } from '../skills/optbrew/scripts/cli.mjs';
+import { reinstallPlan } from './reinstall.mjs';
 
 const defaultBundle = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../skills/optbrew');
 class UsageError extends Error {}
-const usage = 'usage: optbrew <install|doctor|check-updates|update|rollback|score|compare|report> [options]';
+const usage = 'usage: optbrew <install|doctor|check-updates|update|rollback|reinstall-plan|score|compare|report> [options]';
 
 function parseOptions(argv, allowed) {
   const options = {};
@@ -61,7 +62,19 @@ export async function main(argv, { stdout = process.stdout, stderr = process.std
       stdout.write(`${command} complete\n`);
       return 0;
     }
-    if (!['install', 'doctor', 'check-updates', 'update', 'rollback'].includes(command)) throw new UsageError(usage);
+    if (!['install', 'doctor', 'check-updates', 'update', 'rollback', 'reinstall-plan'].includes(command)) throw new UsageError(usage);
+    if (command === 'reinstall-plan') {
+      // Read-only: validates the install record and prints what the documented manual reinstall may delete.
+      const parsed = parseOptions(rest, ['--scope', '--home', '--project']);
+      const scope = parsed['--scope'] ?? 'user';
+      if (!['user', 'project'].includes(scope)) throw new UsageError('--scope must be user or project');
+      if (scope === 'project' && !parsed['--project']) throw new UsageError('project scope requires --project');
+      if (scope === 'user' && parsed['--project']) throw new UsageError('--project requires project scope');
+      const rows = await reinstallPlan({ scope, home: parsed['--home'] ? path.resolve(cwd, parsed['--home']) : env?.HOME ?? os.homedir(),
+        projectRoot: parsed['--project'] ? path.resolve(cwd, parsed['--project']) : undefined });
+      stdout.write(`${rows.map(row => row.join('\t')).join('\n')}\n`);
+      return 0;
+    }
     if (command === 'check-updates') {
       const parsed = parseOptions(rest, ['--package', '--json']);
       const manifest = JSON.parse(await readFile(path.join(bundleRoot, 'bundle-manifest.json'), 'utf8'));

package/lib/doctor.mjs

@@ -30,6 +30,7 @@ export async function doctor({ agents, scope, home, projectRoot }) {
         if (saved.strategy === 'copy' && (await lstat(target.path)).isSymbolicLink()) throw new Error('copy replaced by link');
         const manifest = JSON.parse(await readFile(path.join(target.path, 'bundle-manifest.json'), 'utf8'));
         const check = await verifyBundle({ bundleRoot: target.path, manifest });
+        if (check.errors.some(e => e.code === 'migration_required')) warnings.push(`${target.agent}: installed release ${manifest.release_version} was built for another evaluation version; update is refused (migration_required). See docs/platforms.md, "Reinstall after a migration_required update".`);
         hashOk = !recoveryPending && record.transaction.state === 'committed' && check.status === 'valid' && check.bundle_hash === record.bundle_hash && manifest.release_version === record.release_version;
       } catch (error) { warnings.push(`${target.agent}: ${error.message}`); }
     }

package/lib/reinstall.mjs

@@ -0,0 +1,92 @@
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { readInstallRecord } from './records.mjs';
+import { scopePaths } from './paths.mjs';
+import { validateScope, statOrNull } from './transaction.mjs';
+
+const powershell = value => `'${String(value).replaceAll("'", "''")}'`;
+const posix = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+/**
+ * Read-only plan for the manual reinstall of a managed scope. It validates the install record before anything is
+ * deleted: the record belongs to this scope, every recorded target is exactly the expected skills/optbrew path of its
+ * agent (absolute, no "..", no linked ancestor, inside the scope), and every target that exists is what the installer
+ * created (a link to the managed bundle, or a real directory holding a bundle manifest). Any failed check throws, so a
+ * caller that deletes only what this returns never deletes anything for a tampered record.
+ *
+ * Rows: `delete-link|delete-dir <path>` (recorded targets first, the managed root last), then `install <agent> <strategy>`
+ * per recorded agent in record order, then `agents <csv>` for the final doctor call.
+ */
+export async function reinstallPlan({ scope, home, projectRoot }) {
+  const refuse = message => { throw new Error(`reinstall plan refused: ${message}`); };
+  // One output line per path: a line break, tab or other control character would split a row or inject another one.
+  const plain = value => typeof value === 'string' && [...value].every(ch => { const c = ch.codePointAt(0); return c > 31 && (c < 127 || c > 159) && c !== 8232 && c !== 8233; });
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  if (!plain(scopeRoot) || !plain(managedRoot)) refuse('the scope path contains a control character (a line break, tab or similar)');
+  const record = await readInstallRecord(managedRoot).catch(error => refuse(`install record unreadable (${error.message})`));
+  if (!record) refuse(`no install record in ${managedRoot}`);
+  if (record.scope_id !== `${scope}:${scopeRoot}` || record.managed_root !== managedRoot) refuse('the install record belongs to another scope');
+  if (!record.targets.length) refuse('the install record lists no target');
+  for (const target of record.targets) {
+    if (!plain(target.path) && typeof target.path === 'string') refuse('a recorded target path contains a control character (a line break, tab or similar)');
+    if (typeof target.path !== 'string' || !path.isAbsolute(target.path) || target.path.split(/[\\/]/).includes('..'))
+      refuse(`recorded target is not a plain absolute path: ${JSON.stringify(target.path)}`);
+  }
+  try { await validateScope(managedRoot, record); }
+  catch (error) { refuse(`${error.message} (expected exactly the agent's skills/optbrew path inside ${scopeRoot})`); }
+  const managedBundle = path.join(managedRoot, 'bundle');
+  const rows = [];
+  for (const target of record.targets) {
+    const found = await statOrNull(target.path);
+    if (!found) continue;
+    if (found.isSymbolicLink()) {
+      if (target.strategy !== 'link' || await realpath(target.path) !== await realpath(managedBundle))
+        refuse(`${target.path} is a link that does not lead to the managed bundle`);
+      rows.push(['delete-link', target.path]);
+    } else if (found.isDirectory()) {
+      if (target.strategy !== 'copy') refuse(`${target.path} was recorded as a link but is a directory`);
+      try { await lstat(path.join(target.path, 'bundle-manifest.json')); }
+      catch { refuse(`${target.path} holds no optbrew bundle manifest`); }
+      rows.push(['delete-dir', target.path]);
+    } else refuse(`${target.path} is neither a link nor a directory`);
+  }
+  rows.push(['delete-dir', managedRoot]);
+  for (const target of record.targets) rows.push(['install', target.agent, target.strategy]);
+  rows.push(['agents', record.targets.map(target => target.agent).join(',')]);
+  if (!rows.every(row => row.every(plain))) refuse('a path or name in the plan contains a control character (a line break, tab or similar)');
+  return rows;
+}
+
+/**
+ * Exact manual reinstall steps for a managed scope whose update was refused with migration_required.
+ * Targets are deleted first and the managed root (which holds the install record) last, so the steps can be repeated
+ * after a partial failure. `.optbrew/runs` is never deleted.
+ */
+export function reinstallGuidance({ record, recordRoot, from, to }) {
+  const separator = record.scope_id.indexOf(':');
+  const scope = record.scope_id.slice(0, separator), scopeRoot = record.scope_id.slice(separator + 1);
+  const agents = record.targets.map(target => target.agent).join(',');
+  const place = quote => scope === 'user' ? `--scope user --home ${quote(scopeRoot)}` : `--scope project --project ${quote(scopeRoot)}`;
+  const removePowershell = record.targets.map(target => target.strategy === 'link' ?
+    `[IO.Directory]::Delete(${powershell(target.path)})` : `Remove-Item -Recurse -Force -LiteralPath ${powershell(target.path)}`);
+  removePowershell.push(`Remove-Item -Recurse -Force -LiteralPath ${powershell(recordRoot)}`);
+  const removePosix = `rm -r -- ${[...record.targets.map(target => target.path), recordRoot].map(posix).join(' ')}`;
+  const install = quote => record.targets.map(target =>
+    `optbrew install --agents ${target.agent} ${place(quote)} --strategy ${target.strategy}`);
+  const doctor = quote => `optbrew doctor --agents ${agents} ${place(quote)}`;
+  return [
+    `Release ${to} uses a new evaluation contract, so a managed update from ${from} cannot carry this install over, and scores from the two releases are not comparable. Reinstall instead; your runs folder (${scopeRoot}/.optbrew/runs) is not touched, so never delete it.`,
+    '1. Check the install record first. This read-only command refuses a tampered record and prints exactly what will be deleted:',
+    `   optbrew reinstall-plan ${place(posix)}`,
+    '2. Delete only those paths, the targets first and the managed root last (repeat the same steps if one fails):',
+    '   PowerShell:',
+    ...removePowershell.map(line => `     ${line}`),
+    `   POSIX shell: ${removePosix}`,
+    '3. Install again, one command per recorded agent, from the checkout of the new release:',
+    ...['PowerShell', 'POSIX shell'].flatMap((label, i) => [`   ${label}:`, ...install(i ? posix : powershell).map(line => `     ${line}`)]),
+    '4. Verify:',
+    `   PowerShell: ${doctor(powershell)}`,
+    `   POSIX shell: ${doctor(posix)}`,
+    'The same steps as copy-paste blocks that do these checks for you: docs/platforms.md, "Reinstall after a migration_required update".',
+  ].join('\n');
+}

package/lib/update.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { createBundleManifest } from '../skills/optbrew/scripts/core/bundle.mjs';
 import { readInstallRecord, writeDurableJson, writeInstallRecord } from './records.mjs';
+import { reinstallGuidance } from './reinstall.mjs';
 import { assertManagedPath, copyBundle, fingerprint, finishJournal, managedRename, operationPaths,
   readJournal, recoverTransaction, statOrNull, validateScope, verifiedBundle, withScopeLock } from './transaction.mjs';
 
@@ -110,9 +111,16 @@ async function applyRelease({ bundleRoot, recordRoot, localChanges, faultHook, k
     const managed = path.join(recordRoot, 'bundle');
     let previousRoot = managed;
     if (conflicts.some(c => c.path === managed)) previousRoot = before.source;
-    const previous = await verifiedBundle(previousRoot);
+    // The guard stays as is. A refusal for another evaluation version carries the exact manual reinstall steps.
+    const refuse = error => {
+      if (!/migration_required/.test(error.message)) throw error;
+      const reason = error.message.startsWith('migration_required') ? error.message
+        : 'migration_required: evaluation_version changed (the installed bundle was built for another evaluation version)';
+      throw new Error(`${reason}\n${reinstallGuidance({ record: before, recordRoot, from: before.release_version, to: source.manifest.release_version })}`);
+    };
+    const previous = await verifiedBundle(previousRoot).catch(refuse);
     if (!matchesRecord(previous.manifest, before)) throw new Error('previous verified bundle unavailable; preserve edits and recover original release first');
-    await compatible(previous.manifest, source.manifest);
+    await compatible(previous.manifest, source.manifest).catch(refuse);
     const id = randomUUID();
     const snapshotRoot = path.join(recordRoot, 'releases', id, 'bundle');
     await assertManagedPath(scopeRoot, snapshotRoot);

package/package.json

@@ -1,16 +1,33 @@
 {
   "name": "optbrew",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Pinned search audit and improvement skill bundle",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/nowwcastle-sudo/optbrew.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nowwcastle-sudo/optbrew.git"
+  },
   "homepage": "https://github.com/nowwcastle-sudo/optbrew#readme",
-  "bugs": { "url": "https://github.com/nowwcastle-sudo/optbrew/issues" },
-  "keywords": ["pi-package", "seo", "agent-skill"],
-  "pi": { "skills": ["./skills/optbrew"] },
-  "engines": { "node": ">=22" },
-  "bin": { "optbrew": "bin/optbrew.mjs" },
+  "bugs": {
+    "url": "https://github.com/nowwcastle-sudo/optbrew/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "seo",
+    "agent-skill"
+  ],
+  "pi": {
+    "skills": [
+      "./skills/optbrew"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "optbrew": "bin/optbrew.mjs"
+  },
   "files": [
     "bin/",
     "lib/",
@@ -20,6 +37,7 @@
     ".claude-plugin/",
     "README.md",
     "README.ko.md",
+    "AGENT_INSTALL.md",
     "CHANGELOG.md",
     "docs/platforms.md",
     "docs/release.md",
@@ -34,7 +52,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "build-bundle": "node scripts/build-bundle.mjs --bundle skills/optbrew --version 0.1.1",
+    "build-bundle": "node scripts/build-bundle.mjs --bundle skills/optbrew --version 0.1.3",
     "vendor": "node scripts/vendor.mjs",
     "scan-secrets": "node scripts/scan-secrets.mjs --tracked-and-staged"
   }