optbrew 0.1.3 → 0.2.0

package/docs/platforms.md

@@ -1,6 +1,6 @@
 # Platform installation and update paths
 
-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.
+Optbrew v0.2.0 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 |
 |---|---|---|---|
@@ -45,10 +45,10 @@ 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
+node bin/optbrew.mjs rollback --scope project --project ./site --release-version 0.2.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.
+Rollback works only between releases that share the evaluation version, so no release before 0.2.0 can be rolled back to. The shown command reports that no earlier release is retained on a fresh 0.2.0 install; it applies once a later release that shares evaluation version 0.4.0 has updated the install.
 
 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.
 
@@ -56,9 +56,9 @@ After a public npm release, `npm install -g optbrew` and `npm update -g optbrew`
 
 ## 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.
+Release 0.2.0 uses evaluation version 0.4.0, audit protocol 0.2.0 and contract schema 2.0.0. Release 0.1.3 used evaluation version 0.3.0 and 0.1.2 used 0.2.0. The managed updater refuses a change of evaluation version or of a scoring contract file, so `optbrew update` stops with `migration_required` and changes nothing on a managed install of any 0.1.x release. 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.2.0 checkout. Scores and baselines made with a 0.1.x release are not comparable with 0.2.0; `compare` returns `not_comparable`, so run the baseline audit again. An output folder or evidence packet from a 0.1.x run is refused with one sentence that tells you to run the audit again in a new folder. A plugin install from a marketplace is not a managed install: it follows the repository and needs no reinstall.
 
-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.
+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 the audit evidence of 0.1.x lives, and never touch an `optbrew-audit` folder; do not delete the whole `.optbrew` folder, which also holds the Google key file. Each agent is installed again with the strategy (`link` or `copy`) the record had, then `doctor` runs. Run the blocks from the 0.2.0 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:
 
@@ -128,17 +128,17 @@ while IFS=$'\t' read -r kind a b; do
 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.
+Inside 0.2.0 and later releases that keep evaluation version 0.4.0 and the scoring contract files, `update` and `rollback` work as before. The same refusal and steps apply to any future release that changes the evaluation version or a scoring contract file.
 
 ## 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:** `.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.
+- **Claude Code plugin:** `.claude-plugin/marketplace.json` names the plugin `optbrew@optbrew` and serves the `skills/` folder, whose `skills/.claude-plugin/plugin.json` lists `./optbrew`. Neither file pins a version, so each commit to `main` is a new plugin version. 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 the marketplace and the served plugin from a checkout. The root `.claude-plugin/plugin.json` (version 0.2.0) still loads the whole checkout with `claude --plugin-dir .`. [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 a fresh-session invocation after a native update.
+- **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.
+- **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.2.0` 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 (claude.ai, Claude Desktop, Cowork):** In Customize > Plugins, choose Add > Add marketplace and enter `nowwcastle-sudo/optbrew`, then add `optbrew`. The plugin is saved to your account, so cloud Claude Code sessions receive it too. Turn on Sync automatically for the marketplace, or select Check for updates, to pick up new commits. The marketplace serves `skills/` because claude.ai refuses a plugin with a top-level `bin/` folder. Uploading a ZIP of `skills/` (Add > Upload plugin) also works, but each update needs a new 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.
 
 The native syntax above comes from host documentation checked on 2026-10-14. It is documentation evidence, not proof that an installed host accepted the package or called the skill. No host registration, OAuth, account setting, or user-level install is performed by the documentation checks.

package/docs/release.md

@@ -1,15 +1,47 @@
 # Release procedure
 
-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.
+This checkout is version 0.2.0. 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.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.
+3. Build from a checkout made with `git clone -c core.autocrlf=false`. The root and `skills/` carry no `.gitattributes` (the Claude plugin directory refuses one there), so with `core.autocrlf=true` the skill files are CRLF in the working tree; the bundle hashes still match, but the ZIP and npm verifiers compare exact bytes and refuse them. Run `npm run build-bundle`, `node scripts/build-release.mjs --version 0.2.0 --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.
+6. Confirm CI on the exact commit that will be tagged. That commit exists only after the merge: `main` takes changes through a pull request with linear history, so the merge makes a commit that no earlier run has seen, and runs on the release branch or the pull request do not count. Do this after the merge of step 8 and before its tag. The `test` workflow (`.github/workflows/test.yml`) runs `npm test` on `ubuntu-latest` and on `windows-latest` with `core.autocrlf=true`, Chrome integration tests included, and its last step (`scripts/check-skips.mjs`) fails when a Chrome test was skipped or another test was skipped for a reason that is not listed there. The push to `main` starts the first run. Start two more on the same commit, one after the other, each when the previous one has finished (the workflow keeps one run per commit at a time): `gh workflow run test.yml --ref main`. Then `gh run list --workflow test.yml --branch main --commit <merge commit sha> --json event,conclusion,headSha,url` must list three runs (the `push` run and two `workflow_dispatch` runs) with `conclusion` `success`, each green on both systems. Do not rerun a red run until it turns green: one failed Chrome test (a leftover `gpu-process` of its own Chrome was seen once under load) is a flake to investigate. Read the two `Point optbrew at the runner's Chrome` steps of the newest run and add the Chrome version and path each runner printed to [Chrome locations and DevTools names](#chrome-locations-and-devtools-names-2026-10-16) with the date; also record whether the first Ubuntu run needed any sandbox workaround.
+7. Only after a reviewed release decision, and only after step 6 is green on the merge commit, publish or upload the approved artifacts and verify the public npm and repository readback. Do not infer publication from successful local builds. The owner runs these actions, not an agent: `git push`, the merge, the tag and its push, `gh release create`, and `npm publish dist/optbrew-X.Y.Z.tgz`. An agent prepares the artifacts and reads the results back.
+8. `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. Do not push the tag before step 6 is green for that merge commit.
+9. A tag alone is not a GitHub Release. Publish one for the tag, with the CHANGELOG section as notes and the reviewed ZIP attached: `gh release create vX.Y.Z dist/<zip> --title vX.Y.Z --notes-file <notes.md>`. Read it back: `gh api repos/nowwcastle-sudo/optbrew/releases --jq '.[].tag_name'` must list the tag, and `npm view optbrew dist-tags` must show the same version as `latest`.
+10. The Claude marketplace and directory sync on a push to `main`, sent by the repository webhook. After the merge, confirm that the webhook got a push for `refs/heads/main` with the merge commit: `gh api repos/nowwcastle-sudo/optbrew/hooks/<id>/deliveries` lists the delivery, and `.../deliveries/<delivery id>` shows `request.payload.ref` and `request.payload.after`. A branch deletion is answered `ignored_delete` and does not sync. Then check that the claude.ai copy shows the merge commit.
+11. The Codex marketplace file is `.agents/plugins/marketplace.json`. After the merge, in a Codex that has the marketplace (`codex plugin marketplace add nowwcastle-sudo/optbrew` adds it), run `codex plugin marketplace upgrade`, then `codex plugin list --marketplace optbrew` and check that `optbrew` is listed as available (`--json` gives a machine-readable form). A listing shows that the marketplace file is readable. It does not show that a Codex task discovers the skill: start a new Codex task, invoke the skill, and record the Codex version used (`codex --version`).
 
 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.
 
-The direct Anthropic adapter retains its v0.1.0 text-only scope and four model IDs in [API boundaries](../skills/optbrew/references/api.md). No live paid result, search indexing, traffic change, or customer adoption is established by a passing package check. See [platform paths](platforms.md) for update mechanisms after release.
+The direct Anthropic adapter keeps its text-only scope and four model IDs in [API boundaries](../skills/optbrew/references/api.md). No live paid result, search indexing, traffic change, or customer adoption is established by a passing package check. See [platform paths](platforms.md) for update mechanisms after release.
+
+## Confirmation records
+
+Values the code relies on that were confirmed from a primary source, with the date of confirmation. Re-confirm before changing the matching file.
+
+### Chrome locations and DevTools names (2026-10-16)
+
+Confirmed for `skills/optbrew/references/chrome-paths.json` and `skills/optbrew/scripts/core/chrome.mjs`:
+
+- Windows `\Google\Chrome\Application\chrome.exe` and `\Microsoft\Edge\Application\msedge.exe`, tried under `%ProgramFiles%`, `%ProgramFiles(x86)%` and `%LocalAppData%`; macOS `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` and `/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge`; Linux `/opt/google/chrome/chrome` and `/opt/microsoft/msedge/msedge`. Source: Playwright's channel table and Windows prefix list, https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/registry/index.ts (read 2026-10-16). The Windows prefixes (`LOCALAPPDATA`, `PROGRAMFILES`, `PROGRAMFILES(X86)`) also match Google's `chrome-launcher`, https://github.com/GoogleChrome/chrome-launcher/blob/main/src/chrome-finder.ts.
+- Names searched on `PATH`: `google-chrome-stable`, `google-chrome`, `chromium-browser`, `chromium` (Google's `chrome-launcher`, same file); `microsoft-edge-stable` (Playwright's Edge install script, https://github.com/microsoft/playwright/blob/main/packages/playwright-core/bin/reinstall_msedge_stable_linux.sh); `chrome` and `msedge` (the executable names above).
+- Playwright's Chromium: `<PLAYWRIGHT_BROWSERS_PATH>/chromium-<revision>/chrome-win64/chrome.exe`, `chrome-linux64/chrome`, `chrome-linux-arm64/chrome`, `chrome-mac-{arm64,x64}/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing`; the value `0` means a package-local directory and is ignored (same Playwright file). A Chromium path on macOS (`/Applications/Chromium.app`) was not confirmed and is not listed.
+- `--remote-debugging-pipe`: messages are JSON texts ended by a NUL byte, Chrome reads fd 3 and writes fd 4, so the parent writes `stdio[3]` and reads `stdio[4]`. Sources: Puppeteer's `PipeTransport.ts` and `BrowserLauncher.ts` (https://github.com/puppeteer/puppeteer/tree/main/packages/puppeteer-core/src/node), and Chromium's `content/browser/devtools/devtools_pipe_handler.cc`.
+- DevTools Protocol names (`json/browser_protocol.json` of https://github.com/ChromeDevTools/devtools-protocol, master, read 2026-10-16): `Network.ErrorReason` includes `BlockedByClient`; `Network.ResourceType` values `Document`, `Stylesheet`, `Image`, `Font`, `Script`, `XHR`, `Fetch`; `Fetch.enable` takes `patterns` and `handleAuthRequests`; `Fetch.requestPaused` carries `requestId`, `request`, `frameId`, `resourceType`, `redirectedRequestId`; `Fetch.failRequest` takes `errorReason`; `Fetch.authRequired` carries `authChallenge.source` (`Server` or `Proxy`); `Fetch.continueWithAuth` takes `authChallengeResponse.response` (`Default`, `CancelAuth`, `ProvideCredentials`) with `username` and `password`; `Target.createBrowserContext`, `createTarget`, `attachToTarget` (`flatten`), `closeTarget`, `disposeBrowserContext`; `Browser.close`; `Page.setLifecycleEventsEnabled` and the `networkIdle` lifecycle event.
+- Auto-attach (same protocol JSON, 2026-10-16): `Target.setAutoAttach` takes `autoAttach`, `waitForDebuggerOnStart`, `flatten` and an experimental `filter` (`TargetFilter`: entries are matched in order, the first match wins, a last `{ exclude: true }` drops every other type); `Target.attachedToTarget` carries `sessionId`, `targetInfo` (`targetId`, `type`, `openerId`, `browserContextId`) and `waitingForDebugger`; a paused target runs after `Runtime.runIfWaitingForDebugger`. Observed with Chrome on 2026-10-16: a page-session auto-attach delivers iframes (cross-site ones run in their own process), dedicated workers and service workers, but not popups, which only a browser-level auto-attach delivers (so the render page claims them by `browserContextId`). A dedicated worker session answers `Fetch.enable` with "'Fetch.enable' wasn't found"; its requests are paused on the session of the frame that owns it.
+- Unix socket path limit (Chromium `chrome/browser/process_singleton_posix.cc`, main, read 2026-10-18): the single-instance socket path must be shorter than `sizeof(sun_path)` (108 bytes on Linux; 104 on macOS) or Chrome aborts at start (`LOG(FATAL) << "Socket path too long"`); the socket sits in `<temp folder>/<org.chromium.Chromium.XXXXXX>/SingletonSocket`. `chrome-temp.mjs` therefore redirects Chrome's temp folder into the profile only while that folder path is at most 48 bytes, and otherwise leaves the user's own. First Ubuntu run (CI run 39049765483): every launch from a Hangul profile path and every render test exited at start; the cause was not read from Chrome itself, so the next failing launch prints Chrome's last stderr words in its error message.
+
+### Host resolver rules (2026-10-16)
+
+Confirmed for `skills/optbrew/scripts/core/render.mjs`: Chromium `net/base/host_mapping_rules.h` (chromium/chromium main, read 2026-10-16) defines the rules as a comma separated list of `MAP <hostname_pattern> <replacement_host>[:<port>]` and `EXCLUDE <hostname_pattern>`; the replacement is a hostname or an IP address literal, and a rule that maps to `^NOTFOUND` yields an invalid URL, so the request fails. Observed with the installed Chrome: a host mapped to `^NOTFOUND` fails to load with `net::ERR_NAME_NOT_RESOLVED`. The header does not say how a bracketed IPv6 replacement is parsed, so IPv6 pinning is not covered by a test.
+
+### Harness signals (2026-10-17)
+
+Confirmed for `skills/optbrew/references/harness-signals.json` and `skills/optbrew/scripts/core/probe.mjs`:
+
+- Claude Code: `CLAUDECODE` is set to `1` in subprocesses Claude Code spawns (Bash and PowerShell tools, hooks, status line, stdio MCP servers; IDE extensions set it in their integrated terminals). `CLAUDE_CODE_REMOTE` is set automatically to `true` when Claude Code runs as a cloud session. Both rows are in https://code.claude.com/docs/en/env-vars (read 2026-10-17); the cloud session page, https://code.claude.com/docs/en/claude-code-on-the-web, is the cross-reference. A cloud session also has `CLAUDECODE`, so `CLAUDE_CODE_REMOTE` is tested first.
+- Codex: `CODEX_SANDBOX_NETWORK_DISABLED` is set to `1` for a process spawned by a shell tool call when the network sandbox policy is restricted; `CODEX_SANDBOX` is set when the process runs under a sandbox (`seatbelt` on macOS, "may change" for other mechanisms). Source: openai/codex `codex-rs/core/src/spawn.rs`, https://github.com/openai/codex/blob/main/codex-rs/core/src/spawn.rs (read 2026-10-17, constants `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR` and `CODEX_SANDBOX_ENV_VAR`; the file defines `CODEX_SANDBOX` but does not set it). The variable is marked experimental in that comment. The Codex docs page `docs/sandbox.md` names neither variable.
+- Limits: a Codex run with full network access sets neither variable, so it is detected as `other` and gets the general runbooks. Only `CODEX_SANDBOX_NETWORK_DISABLED` makes a failed DNS lookup a `codex_sandbox` block; with only `CODEX_SANDBOX` set the same failure is `site_down`. No variable separates a Claude Code cloud network level from a down site, so a failed lookup or a refused proxy tunnel in a cloud session is `cloud_network_level`.

package/lib/cli.mjs

@@ -9,10 +9,12 @@ import { readFile } from 'node:fs/promises';
 import { readInstallRecord } from './records.mjs';
 import { runCli } from '../skills/optbrew/scripts/cli.mjs';
 import { reinstallPlan } from './reinstall.mjs';
+import { runKeyCommand } from '../skills/optbrew/scripts/key.mjs';
+import { keyHome } from '../skills/optbrew/scripts/core/keys.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|reinstall-plan|score|compare|report> [options]';
+const usage = 'usage: optbrew <install|doctor|check-updates|update|rollback|reinstall-plan|score|compare|report|key> [options]';
 
 function parseOptions(argv, allowed) {
   const options = {};
@@ -54,9 +56,10 @@ function computeArgs(argv, command, cwd) {
 }
 
 /** Return CLI process code: 0 success, 2 argument error, 1 environment or file failure. */
-export async function main(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd(), bundleRoot = defaultBundle, registryTransport } = {}) {
+export async function main(argv, { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd(), bundleRoot = defaultBundle, registryTransport } = {}) {
   try {
     const [command, ...rest] = argv;
+    if (command === 'key') return await runKeyCommand(rest, { stdin, stdout, stderr, env, home: keyHome(env) });
     if (['score', 'compare', 'report'].includes(command)) {
       await runCli(computeArgs(rest, command, cwd));
       stdout.write(`${command} complete\n`);

package/lib/install.mjs

@@ -1,6 +1,7 @@
 import { cp, lstat, mkdir, open, readFile, realpath, rename, rm, symlink } from 'node:fs/promises';
 import path from 'node:path';
 import { isDistributedBundlePath, verifyBundle } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { versions } from '../skills/optbrew/scripts/core/config.mjs';
 import { readInstallRecord, writeInstallRecord } from './records.mjs';
 import { resolveTargets, scopePaths } from './paths.mjs';
 
@@ -104,7 +105,7 @@ export async function install({ bundleRoot, agents, scope, home, projectRoot, dr
         changed.push(managedBundle);
       } finally { await rm(staging, { recursive: true, force: true }); }
       next = {
-        schema_version: '1.0.0', scope_id: `${scope}:${scopeRoot}`, release_version: source.manifest.release_version,
+        schema_version: versions().install_record_schema, scope_id: `${scope}:${scopeRoot}`, release_version: source.manifest.release_version,
         bundle_hash: source.manifest.bundle_hash, source: path.resolve(bundleRoot), managed_root: managedRoot,
         targets: [], file_hashes: Object.fromEntries(source.manifest.files.map(f => [f.path, f.sha256])),
         previous_releases: [], transaction: { state: 'pending' }, source_ref: 'bundle-manifest.json',

package/lib/records.mjs

@@ -1,9 +1,10 @@
 import { mkdir, readFile, open, rename, rm, lstat } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { versions } from '../skills/optbrew/scripts/core/config.mjs';
 
 export function validateInstallRecord(record) {
-  if (record?.schema_version !== '1.0.0') throw new Error('migration_required: unsupported install record schema; use a compatible optbrew release');
+  if (record?.schema_version !== versions().install_record_schema) throw new Error('migration_required: unsupported install record schema; use a compatible optbrew release');
   if (!Array.isArray(record.targets) || !/^[a-f0-9]{64}$/.test(record.bundle_hash) ||
       typeof record.managed_root !== 'string' || typeof record.scope_id !== 'string' ||
       typeof record.release_version !== 'string' || !record.file_hashes || typeof record.file_hashes !== 'object' ||

package/lib/transaction.mjs

@@ -2,6 +2,7 @@ import { cp, lstat, mkdir, open, readFile, readlink, realpath, rename, rm } from
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { createBundleManifest, isDistributedBundlePath, verifyBundle } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { versions } from '../skills/optbrew/scripts/core/config.mjs';
 import { readInstallRecord, validateInstallRecord, writeDurableJson, writeInstallRecord } from './records.mjs';
 import { resolveTargets, scopePaths } from './paths.mjs';
 
@@ -16,12 +17,18 @@ export async function assertManagedPath(scopeRoot, destination) {
   const relative = path.relative(scopeRoot, destination);
   if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`outside managed scope: ${destination}`);
   let current = path.parse(scopeRoot).root;
+  // Folders above the scope root are the user's own choice of location, and Windows may spell them in the 8.3 short form
+  // (C:\Users\RUNNER~1 for C:\Users\runneradmin, as a TEMP variable often does). Links among them are still refused; the
+  // resolved-path comparison applies below the root, measured from the root's real path.
+  const realRoot = (await statOrNull(scopeRoot)) ? path.resolve(await realpath(scopeRoot)) : scopeRoot;
   for (const part of path.relative(current, path.dirname(destination)).split(path.sep)) {
     current = path.join(current, part);
     const stat = await statOrNull(current);
     if (stat?.isSymbolicLink()) throw new Error(`linked ancestor: ${current}`);
     if (stat && !stat.isDirectory()) throw new Error(`invalid ancestor: ${current}`);
-    if (stat && path.resolve(await realpath(current)).toLowerCase() !== current.toLowerCase()) throw new Error(`resolved path changed: ${current}`);
+    const below = path.relative(scopeRoot, current);
+    if (!stat || !below || below === '..' || below.startsWith(`..${path.sep}`) || path.isAbsolute(below)) continue;
+    if (path.resolve(await realpath(current)).toLowerCase() !== path.join(realRoot, below).toLowerCase()) throw new Error(`resolved path changed: ${current}`);
   }
 }
 
@@ -47,11 +54,11 @@ export async function verifiedBundle(bundleRoot) {
   if (!(await lstat(bundleRoot)).isDirectory() || (await lstat(bundleRoot)).isSymbolicLink()) throw new Error('bundle ownership: expected real directory');
   if ((await lstat(path.join(bundleRoot, 'bundle-manifest.json'))).isSymbolicLink()) throw new Error('manifest is a link');
   const manifest = JSON.parse(await readFile(path.join(bundleRoot, 'bundle-manifest.json'), 'utf8'));
-  if (manifest.schema_version !== '1.0.0') throw new Error('migration_required: unsupported bundle manifest schema');
+  if (manifest.schema_version !== versions().bundle_manifest_schema) throw new Error('migration_required: unsupported bundle manifest schema');
   const verification = await verifyBundle({ bundleRoot, manifest });
   if (verification.status !== 'valid') throw new Error(`bundle integrity failed: ${JSON.stringify(verification.errors)}`);
   const lock = JSON.parse(await readFile(path.join(bundleRoot, 'source-lock.json'), 'utf8'));
-  if (lock.schema_version !== '1.0.0' || !Array.isArray(lock.files) || !Array.isArray(lock.modules)) throw new Error('invalid source-lock');
+  if (lock.schema_version !== versions().bundle_manifest_schema || !Array.isArray(lock.files) || !Array.isArray(lock.modules)) throw new Error('invalid source-lock');
   const hashes = new Map(manifest.files.map(f => [f.path, f.sha256]));
   const seen = new Set();
   for (const file of lock.files) {
@@ -75,7 +82,7 @@ export async function fingerprint(file) {
   if (!stat) return null;
   if (stat.isSymbolicLink()) return `link:${await readlink(file)}`;
   if (!stat.isDirectory()) throw new Error(`unexpected managed path type: ${file}`);
-  const manifest = await createBundleManifest({ bundleRoot: file, releaseVersion: '0.0.0' });
+  const manifest = await createBundleManifest({ bundleRoot: file, releaseVersion: versions().release });
   const meta = await readFile(path.join(file, 'bundle-manifest.json'));
   return createHash('sha256').update(manifest.bundle_hash).update(meta).digest('hex');
 }
@@ -142,7 +149,7 @@ async function recoverLocked(recordRoot) {
   if (!journal) return { status: 'clean', restored_version: null, unresolved_paths: [], evidence_ref: null };
   const evidence_ref = path.join(recordRoot, 'transaction.json');
   try {
-    if (journal.schema_version !== '1.0.0' || !/^[a-f0-9-]{36}$/.test(journal.id) || !Array.isArray(journal.operations)) throw new Error('invalid journal');
+    if (journal.schema_version !== versions().install_record_schema || !/^[a-f0-9-]{36}$/.test(journal.id) || !Array.isArray(journal.operations)) throw new Error('invalid journal');
     const scopeRoot = await validateScope(recordRoot, journal.before);
     await validateScope(recordRoot, journal.after);
     const expected = [path.join(recordRoot, 'bundle'), ...journal.before.targets.filter(t => t.strategy === 'copy').map(t => t.path)];

package/lib/update.mjs

@@ -2,6 +2,7 @@ import { lstat, mkdir, readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { createBundleManifest } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { endpoints, versions } from '../skills/optbrew/scripts/core/config.mjs';
 import { readInstallRecord, writeDurableJson, writeInstallRecord } from './records.mjs';
 import { reinstallGuidance } from './reinstall.mjs';
 import { assertManagedPath, copyBundle, fingerprint, finishJournal, managedRename, operationPaths,
@@ -31,7 +32,7 @@ export async function checkUpdates({ packageName, currentVersion, registryTransp
   if (!versionPattern.test(currentVersion)) throw new TypeError('invalid current version');
   if (!packageName) return { current_version: currentVersion, latest_version: null, status: 'local_only', source_ref: 'bundled release; registry package unconfirmed' };
   if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(packageName)) throw new TypeError('invalid registry package name');
-  const source_ref = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+  const source_ref = `${endpoints().npm_registry}${encodeURIComponent(packageName)}`;
   const transport = registryTransport ?? (async () => {
     const response = await fetch(source_ref, { signal: AbortSignal.timeout(10000), redirect: 'error', headers: { accept: 'application/json' } });
     if (!response.ok) throw new Error(`registry HTTP ${response.status}`);
@@ -141,7 +142,7 @@ async function applyRelease({ bundleRoot, recordRoot, localChanges, faultHook, k
       source: path.resolve(bundleRoot), file_hashes: Object.fromEntries(source.manifest.files.map(f => [f.path, f.sha256])),
       previous_releases: [...before.previous_releases, { release_version: before.release_version, bundle_hash: before.bundle_hash, bundle_root: snapshotRoot }],
       transaction: { state: 'committed', id, kind, conflicts, backups: decision.backups } };
-    const journal = { schema_version: '1.0.0', id, state: 'prepared', before, after, operations };
+    const journal = { schema_version: versions().install_record_schema, id, state: 'prepared', before, after, operations };
     await writeDurableJson(path.join(recordRoot, 'transaction.json'), journal);
     try {
       await faultHook?.('after_staging');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "optbrew",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pinned search audit and improvement skill bundle",
   "license": "MIT",
@@ -23,7 +23,7 @@
     ]
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.4"
   },
   "bin": {
     "optbrew": "bin/optbrew.mjs"
@@ -32,6 +32,8 @@
     "bin/",
     "lib/",
     "skills/optbrew/",
+    "skills/.claude-plugin/",
+    "skills/README.md",
     "plugin.json",
     ".codex-plugin/",
     ".claude-plugin/",
@@ -51,8 +53,8 @@
     "!**/test_*.py"
   ],
   "scripts": {
-    "test": "node --test",
-    "build-bundle": "node scripts/build-bundle.mjs --bundle skills/optbrew --version 0.1.3",
+    "test": "node scripts/test.mjs",
+    "build-bundle": "node scripts/build-bundle.mjs --bundle skills/optbrew",
     "vendor": "node scripts/vendor.mjs",
     "scan-secrets": "node scripts/scan-secrets.mjs --tracked-and-staged"
   }

package/plugin.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "optbrew",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Pinned search audit and improvement skill bundle",
   "license": "MIT",
   "extensions": {
     "com.openai": {
       "skills": ["./skills/optbrew"],
-      "release_version": "0.1.3"
+      "release_version": "0.2.0"
     }
   }
 }

package/skills/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "optbrew",
+  "displayName": "optbrew",
+  "description": "Audit a site for Google, Naver and AI answer engines, fix the local files you approve, re-check under the same conditions and write a scored report",
+  "author": {
+    "name": "nowwcastle-sudo",
+    "url": "https://github.com/nowwcastle-sudo"
+  },
+  "homepage": "https://github.com/nowwcastle-sudo/optbrew",
+  "repository": "https://github.com/nowwcastle-sudo/optbrew",
+  "license": "MIT",
+  "keywords": [
+    "seo",
+    "naver",
+    "aeo",
+    "geo",
+    "llmo",
+    "audit"
+  ],
+  "skills": [
+    "./optbrew"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,27 @@
+# optbrew
+
+A search-readiness audit skill. optbrew checks a website for Google, Naver and AI answer engines, fixes only the local files you approve, checks again under the same conditions, and writes a scored report built from evidence you can replay.
+
+It covers five profiles: SEO, NEO (Naver), AEO, GEO and LLMO. Five pinned audit guide bundles are merged into 22 check families, so an issue that several guides report is counted once. When less than 80% of the applicable checks could be measured, the report shows the measured part and its bounds instead of one headline score.
+
+## How to use it
+
+Start a session and ask, for example: "Run optbrew on https://example.com. Goal: show up in Naver and get cited in AI answers." optbrew reads the site and your setup, then sends all its start questions in one message: guidance level, goal, search questions, site facts, page limit and optional extras. The questions, guides and report are in Korean. Answer by number, or reply "시작" (start) to take the defaults.
+
+The audit then runs in one go. It writes `report.html`, `report.md` and `report.json` to an `optbrew-audit` folder in your working folder. Open `report.html` first. The report text is in Korean. Each problem has one fix with the number of pages it affects, and each blank has a numbered list of steps that fill it. Missing extras, such as a Google key or Chrome, never stop the audit.
+
+## What it runs, reads and sends
+
+- **Site collection.** It fetches only URLs on your site's own address and its `www` or `https` twin: pages from the sitemap and from links on the start page, up to a limit of 50 requests by default (up to 200 if you raise it), counting pages, redirects and robots or sitemap files together, two at a time. It follows a redirect to the `www` or `https` twin of your address and says so in the report. Private, internal and local addresses (such as `localhost`) are refused, so audit the public address of the site. Every response is stored with its hash in the `optbrew-audit` folder.
+- **Chrome.** To see text that scripts draw, it renders up to 10 pages, one of each kind, in a headless Chrome of its own with a temporary profile, and closes it when the audit ends. Your own Chrome is never reused. The pages it renders may load files from other public hosts, such as fonts and scripts; optbrew fetches those only from public addresses. Without Chrome the audit still runs and the render checks stay blank.
+- **Speed data.** To get the Core Web Vitals of real visitors, it asks Google's Chrome UX Report and PageSpeed Insights about your site's address. If you saved a Google API key, it is sent to Google only in a request header. The key is never written to a report, a log or the evidence. Without a key, those cells can stay blank.
+- **Google key file.** `optbrew key set google` (or `node <skill folder>/scripts/key.mjs set google`), run by you in your own terminal, saves the key in `.optbrew/credentials.json` in your home folder. The environment variable `OPTBREW_GOOGLE_API_KEY` takes priority. The skill never asks for the key in the chat.
+- **Your export files.** If you give the path of a Search Console zip or a Naver Search Advisor text file, the audit reads that file from disk. It sends nothing from it.
+- **Local scripts.** The skill tells Claude to run the Node.js and Python scripts bundled in this folder for collection, scoring, comparison and reports. They need Node.js 22 or later; Python 3.10 or later is optional.
+- **Local changes.** It edits only local files you approve, after keeping a backup copy. It does not deploy, publish, or submit a site to a search engine.
+- **Optional paid APIs.** Nothing requires an account. If you choose to use the Anthropic API, the bundled adapter reads your `ANTHROPIC_API_KEY` environment variable and sends it only to `api.anthropic.com`, and only after you approve a budget and a stop condition. The SE Ranking guides describe SE Ranking's own API and MCP with your own SE Ranking key, sent only to SE Ranking. Keys never go into a report.
+- **No other network use.** The plugin has no hooks, MCP servers or background tasks, and it does not download or run code at install time.
+
+## License
+
+MIT for optbrew's own code. The bundled guides keep their own licenses, listed in `optbrew/THIRD_PARTY_NOTICES.md`. Source and documentation: https://github.com/nowwcastle-sudo/optbrew