optbrew 0.2.0 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "optbrew",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pinned search audit and improvement skill bundle",
   "author": { "name": "nowwcastle-sudo", "url": "https://github.com/nowwcastle-sudo" },
   "skills": ["./skills/optbrew"]

package/.codex-plugin/plugin.json

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

package/AGENT_INSTALL.md

@@ -2,7 +2,7 @@
 
 You are an AI coding agent installing the optbrew skill for a user. Follow the steps in order. Each step has a command and a check. Stop and ask the user when a step says so. Do not skip a check.
 
-Package: `optbrew@0.2.0` on npm. Source: https://github.com/nowwcastle-sudo/optbrew
+Package: `optbrew@0.2.1` on npm. Source: https://github.com/nowwcastle-sudo/optbrew
 
 ## Rules
 
@@ -32,13 +32,13 @@ Check: the major version is 22 or higher. If Node.js is missing or older, stop a
 User scope:
 
 ```text
-npx --yes optbrew@0.2.0 install --agents AGENTS --scope user --dry-run --json
+npx --yes optbrew@0.2.1 install --agents AGENTS --scope user --dry-run --json
 ```
 
 Project scope:
 
 ```text
-npx --yes optbrew@0.2.0 install --agents AGENTS --scope project --project PROJECT --dry-run --json
+npx --yes optbrew@0.2.1 install --agents AGENTS --scope project --project PROJECT --dry-run --json
 ```
 
 Check: exit code 0 and `"status": "dry_run"`. Show the user `decision.targets[].path` from the output and ask for approval before step 4.
@@ -54,7 +54,7 @@ Check: exit code 0 and `"status": "installed"` (or `"unchanged"` when the same r
 ## 5. Verify
 
 ```text
-npx --yes optbrew@0.2.0 doctor --agents AGENTS --scope SCOPE --json
+npx --yes optbrew@0.2.1 doctor --agents AGENTS --scope SCOPE --json
 ```
 
 Add `--project PROJECT` for project scope. Check: every entry in `targets` has `file_present: true`, `hash_ok: true` and `registered: true`. `session_discovery` and `invocation_verified` are always `not_verified`: doctor checks files, not whether the agent loaded them. A new agent session in step 6 confirms that.
@@ -71,15 +71,15 @@ Tell the user:
 
 ## Update
 
-1. Find the installed release: run `npx --yes optbrew@0.2.0 doctor --agents AGENTS --scope SCOPE --json` (add `--project PROJECT` for project scope) and read `release_version`.
+1. Find the installed release: run `npx --yes optbrew@0.2.1 doctor --agents AGENTS --scope SCOPE --json` (add `--project PROJECT` for project scope) and read `release_version`.
 2. Find the latest release: `npm view optbrew version`.
 3. If they are equal, stop: nothing to update.
 4. Otherwise run `npx --yes optbrew@latest update --scope SCOPE --json` (add `--project PROJECT` for project scope). Check: `"status": "updated"`. Then repeat step 5 with `optbrew@latest`.
 
 If `update` stops with `migration_required`, the installed release scores with an older evaluation version and cannot be updated in place. Its scores are not comparable with the new release. Every managed 0.1.x install ends here when it is updated to 0.2.0. Tell the user that an output folder from a 0.1.x audit cannot be reused: the new release refuses it with one sentence, and the audit has to run again in a new folder. Reinstall it:
 
-1. `git clone --depth 1 --branch v0.2.0 https://github.com/nowwcastle-sudo/optbrew optbrew-src` (needs git; use the tag of the release you install).
-2. In `optbrew-src`, run the read-only check from https://github.com/nowwcastle-sudo/optbrew/blob/v0.2.0/docs/platforms.md#reinstall-after-a-migration_required-update: `node bin/optbrew.mjs reinstall-plan --scope SCOPE` (add `--project PROJECT` for project scope).
+1. `git clone --depth 1 --branch v0.2.1 https://github.com/nowwcastle-sudo/optbrew optbrew-src` (needs git; use the tag of the release you install).
+2. In `optbrew-src`, run the read-only check from https://github.com/nowwcastle-sudo/optbrew/blob/v0.2.1/docs/platforms.md#reinstall-after-a-migration_required-update: `node bin/optbrew.mjs reinstall-plan --scope SCOPE` (add `--project PROJECT` for project scope).
 3. Show the user the printed `delete-link` and `delete-dir` paths and ask for approval. If the check refuses the install record, stop and show the user the message.
 4. After approval, run the block from that section that matches the user's shell (PowerShell or Bash) and scope, from `optbrew-src`. It deletes only the printed paths, installs again and runs doctor.
 
@@ -91,4 +91,4 @@ If `update` stops with `migration_required`, the installed release scores with a
 | `npx` cannot find `optbrew` | Check network access to the npm registry, then retry once. |
 | `unmanaged optbrew target exists` | Stop. Show the path to the user and ask. |
 | `bundle integrity failed` | Stop. Report the full message to the user. |
-| `doctor` shows `hash_ok: false` | Read the doctor `warnings`. If one says `migration_required`, the install is an older release: follow [Update](#update). Otherwise someone edited the installed files: ask the user before you run `npx --yes optbrew@0.2.0 update --scope SCOPE --local-changes backup-and-replace --json`, which keeps a backup of the edited files. |
+| `doctor` shows `hash_ok: false` | Read the doctor `warnings`. If one says `migration_required`, the install is an older release: follow [Update](#update). Otherwise someone edited the installed files: ask the user before you run `npx --yes optbrew@0.2.1 update --scope SCOPE --local-changes backup-and-replace --json`, which keeps a backup of the edited files. |

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.1
+
+Answers the Claude plugin directory review of 0.2.0. The audit itself is unchanged; evaluation 0.4.0, audit protocol 0.2.0 and contract schema 2.0.0 stay.
+
+### What you see
+
+- **Google key in the Claude plugin settings.** With the Claude Code plugin you can enter the Google API key in `/plugin`, **Installed**, optbrew, **Configure options** instead of running `key set google` in a terminal. Claude Code keeps it in the system credential store. A new session picks it up. The key is optional, as before. The order optbrew reads the key in is now: the plugin setting, then `OPTBREW_GOOGLE_API_KEY`, then `.optbrew/credentials.json`. npm, Codex and the other hosts keep the variable and the key file.
+- **Key guides.** `key-set-local` and `google-api-key` name the plugin setting. `key remove google` now says a key is still set outside the key file when the variable or the plugin setting holds one.
+
+### Directory review answers
+
+- `MANIFEST_VERSION_MISSING`: the served `skills/.claude-plugin/plugin.json` now carries the release version. Before, it carried none so that every commit reached marketplace sync; now installed copies move only when a release changes the version. The marketplace entry still carries none (the manifest's version overrides it). The version-consistency test and `verify-release.mjs` check the served manifest.
+- `MCP_FORWARDS_CREDENTIAL_ENV`: the served manifest declares `userConfig.google_api_key` (`sensitive: true`). Claude Code gives a sensitive value only to hooks, so a new SessionStart hook (`skills/hooks/hooks.json`, exec form, `node` with `plugin-key-env.mjs`) appends it to `CLAUDE_ENV_FILE` as one single-quoted `CLAUDE_PLUGIN_OPTION_GOOGLE_API_KEY` line, and only when the value is letters, digits, `_` and `-`. The hook prints nothing and never echoes the value. Trade-off: the value then sits in the session's env file and in every shell command of the session, like the variable did. The flagged module guides (`seranking-seo` `seo-api` references, `seo-google/GUIDE.md`, `references/api.md`) are documentation only, and each sends a key to its own vendor (SE Ranking, Google, Anthropic); they are unchanged.
+- `UNREAD_ASSET_REFERENCED` on `modules/seranking-seo/skills/seo-api/references/api-surface-map.md`: the file names no image or font, and nothing runs it (only `seo-api/GUIDE.md` links it as a reference). Unchanged; it is a pinned vendored file (`source-lock.json`).
+- `RUNTIME_FETCH_EXEC` on `modules/magnus-seo/references/ghost-metadata.md`: its three `curl -s … | grep` lines read a page and filter it; nothing is run. Documentation only and pinned; unchanged.
+
+### Versions
+
+Release 0.2.1, evaluation 0.4.0, audit protocol 0.2.0, contract schema 2.0.0. Scores from 0.2.0 and 0.2.1 are comparable.
+
+### Not checked here
+
+- The hook was tested with a fake key and a temporary env file, not in a live Claude Code session with the plugin installed. Check after the merge: set the key in **Configure options**, start a new session, and `node "<skill folder>/scripts/key.mjs" status` shows `"present":true`. Check it on Windows too.
+- The Claude Code desktop app's plugin screen for **Configure options** was not seen.
+
 ## 0.2.0
 
 The beginner audit in one call. You answer one set of start questions, the agent runs the whole audit, and you get an HTML report in Korean with the fixes in order and the blanks explained.

package/README.ko.md

@@ -49,7 +49,7 @@ Windows PowerShell에서 `npx`나 `optbrew`가 「스크립트를 실행할 수
 ### 1. npm
 
 ```bash
-npm install -g optbrew@0.2.0
+npm install -g optbrew@0.2.1
 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
@@ -62,20 +62,20 @@ optbrew doctor --agents codex,claude-code --scope user
 전역 설치 없이 같은 CLI를 실행합니다.
 
 ```bash
-npx optbrew@0.2.0 install --agents codex,claude-code --scope user
-npx optbrew@0.2.0 doctor --agents codex,claude-code --scope user
+npx optbrew@0.2.1 install --agents codex,claude-code --scope user
+npx optbrew@0.2.1 doctor --agents codex,claude-code --scope user
 ```
 
 ### 3. PowerShell (Windows)
 
 ```powershell
-irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/install.ps1 | iex
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.1/install.ps1 | iex
 ```
 
 이 스크립트는 이번 버전에 고정돼 있습니다. Node.js를 확인하고, 설치할 폴더를 보여 주고, Codex와 Claude Code에 설치합니다. `doctor`가 문제를 찾으면 오류로 멈춥니다. 먼저 읽어 보거나 에이전트·프로젝트 폴더를 고르려면 이렇게 실행합니다.
 
 ```powershell
-irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/install.ps1 -OutFile install.ps1
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.1/install.ps1 -OutFile install.ps1
 powershell -ExecutionPolicy Bypass -File .\install.ps1 -Agents codex,claude-code,cursor
 ```
 
@@ -106,7 +106,7 @@ claude.ai, Claude Desktop, Cowork: Customize > Plugins에서 Add > Add marketpla
 Codex, Claude Code 같은 코딩 에이전트에 아래 글을 붙여 넣으십시오.
 
 ```text
-optbrew 스킬을 설치해 줘. https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/AGENT_INSTALL.md 를 읽고 단계대로 따라 해. 어느 에이전트에, 어느 범위로 설치할지 먼저 묻고, 설치 전에 바뀔 내용을 보여 줘.
+optbrew 스킬을 설치해 줘. https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.1/AGENT_INSTALL.md 를 읽고 단계대로 따라 해. 어느 에이전트에, 어느 범위로 설치할지 먼저 묻고, 설치 전에 바뀔 내용을 보여 줘.
 ```
 
 [AGENT_INSTALL.md](AGENT_INSTALL.md)는 단계마다 실행할 명령과 통과 기준, 멈추고 사용자에게 물어야 할 경우를 적어 둔 에이전트용 안내서입니다.
@@ -135,7 +135,7 @@ optbrew key status
 optbrew key remove google
 ```
 
-`set`은 숨겨진 입력 창으로 키를 받습니다. `status`는 키가 있는지와 해시 앞 8자만 보여 줍니다. `remove`는 키를 지웁니다. npm으로 설치하지 않았다면 `npx optbrew@0.2.0 key set google`을 쓰거나, 「키」라고 답해 안내에 나온 명령을 그대로 복사하십시오. 스킬 폴더에도 같은 명령이 있습니다: `node <스킬 폴더>/scripts/key.mjs set google`. 키는 홈 폴더의 `.optbrew/credentials.json`에 저장되며 어느 프로젝트 안에도 들어가지 않습니다. 환경 변수 `OPTBREW_GOOGLE_API_KEY`가 있으면 그것이 먼저입니다. optbrew는 키를 요청 헤더로만 구글에 보내고, 보고서·로그·근거에는 쓰지 않습니다.
+`set`은 숨겨진 입력 창으로 키를 받습니다. `status`는 키가 있는지와 해시 앞 8자만 보여 줍니다. `remove`는 키를 지웁니다. npm으로 설치하지 않았다면 `npx optbrew@0.2.1 key set google`을 쓰거나, 「키」라고 답해 안내에 나온 명령을 그대로 복사하십시오. 스킬 폴더에도 같은 명령이 있습니다: `node <스킬 폴더>/scripts/key.mjs set google`. 키는 홈 폴더의 `.optbrew/credentials.json`에 저장되며 어느 프로젝트 안에도 들어가지 않습니다. 환경 변수 `OPTBREW_GOOGLE_API_KEY`가 있으면 그것이 먼저입니다. Claude Code 플러그인으로 설치했다면 `/plugin` → **Installed** → optbrew → **Configure options**에 키를 넣어도 됩니다. Claude Code가 운영체제의 자격 증명 저장소에 보관하고, 이 값이 둘보다 먼저 쓰이며, 새 세션부터 적용됩니다. optbrew는 키를 요청 헤더로만 구글에 보내고, 보고서·로그·근거에는 쓰지 않습니다.
 
 ## 업데이트
 

package/README.md

@@ -49,7 +49,7 @@ In Windows PowerShell, if `npx` or `optbrew` reports that running scripts is dis
 ### 1. npm
 
 ```bash
-npm install -g optbrew@0.2.0
+npm install -g optbrew@0.2.1
 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
@@ -62,20 +62,20 @@ The dry run prints the folders it will write. `doctor` checks the files and thei
 Runs the same CLI without a global install:
 
 ```bash
-npx optbrew@0.2.0 install --agents codex,claude-code --scope user
-npx optbrew@0.2.0 doctor --agents codex,claude-code --scope user
+npx optbrew@0.2.1 install --agents codex,claude-code --scope user
+npx optbrew@0.2.1 doctor --agents codex,claude-code --scope user
 ```
 
 ### 3. PowerShell (Windows)
 
 ```powershell
-irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/install.ps1 | iex
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.1/install.ps1 | iex
 ```
 
 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:
 
 ```powershell
-irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/install.ps1 -OutFile install.ps1
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.1/install.ps1 -OutFile install.ps1
 powershell -ExecutionPolicy Bypass -File .\install.ps1 -Agents codex,claude-code,cursor
 ```
 
@@ -106,7 +106,7 @@ Plugins follow this repository's `main` branch and update through the host's plu
 Paste this into Codex, Claude Code or another coding agent:
 
 ```text
-Install the optbrew skill for me. Read https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/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.
+Install the optbrew skill for me. Read https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.1/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.
 ```
 
 [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.
@@ -135,7 +135,7 @@ optbrew key status
 optbrew key remove google
 ```
 
-`set` asks for the key with hidden input. `status` shows only whether a key exists and the first 8 characters of its hash. `remove` deletes it. If you did not install with npm, use `npx optbrew@0.2.0 key set google`, or answer "키" and copy the exact command from the guide. The skill folder has the same command too: `node <skill folder>/scripts/key.mjs set google`. The key is saved in `.optbrew/credentials.json` in your home folder, outside every project, and the environment variable `OPTBREW_GOOGLE_API_KEY` takes priority if it is set. optbrew sends the key to Google only in a request header, and never writes it to a report, a log or the evidence.
+`set` asks for the key with hidden input. `status` shows only whether a key exists and the first 8 characters of its hash. `remove` deletes it. If you did not install with npm, use `npx optbrew@0.2.1 key set google`, or answer "키" and copy the exact command from the guide. The skill folder has the same command too: `node <skill folder>/scripts/key.mjs set google`. The key is saved in `.optbrew/credentials.json` in your home folder, outside every project, and the environment variable `OPTBREW_GOOGLE_API_KEY` takes priority if it is set. With the Claude Code plugin you can instead enter the key in `/plugin`, **Installed**, optbrew, **Configure options**: Claude Code keeps it in your system credential store, it comes before both, and a new session picks it up. optbrew sends the key to Google only in a request header, and never writes it to a report, a log or the evidence.
 
 ## Update
 

package/docs/platforms.md

@@ -1,6 +1,6 @@
 # Platform installation and update paths
 
-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.
+Optbrew v0.2.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.
 
 | 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.2.0 --json
+node bin/optbrew.mjs rollback --scope project --project ./site --release-version 0.2.1 --json
 ```
 
-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.
+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.1 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.
 
@@ -135,9 +135,9 @@ Inside 0.2.0 and later releases that keep evaluation version 0.4.0 and the scori
 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` 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.
+- **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`. The served `plugin.json` carries the release version, so installed copies move only when a release changes it; the marketplace entry pins none. The served `plugin.json` also declares one optional setting, `google_api_key` (sensitive): Claude Code keeps it in the system credential store, and the plugin's SessionStart hook (`skills/hooks/`) hands it to the session's shell commands as `CLAUDE_PLUGIN_OPTION_GOOGLE_API_KEY`, which optbrew reads before `OPTBREW_GOOGLE_API_KEY` and the key file. Set it in `/plugin`, **Installed**, optbrew, **Configure options**; a new session picks it up. 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.1) 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.
+- **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.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 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.
 

package/docs/release.md

@@ -1,10 +1,10 @@
 # Release procedure
 
-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.
+This checkout is version 0.2.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.
 
 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. 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.
+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.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.
 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. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "optbrew",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Pinned search audit and improvement skill bundle",
   "license": "MIT",

package/plugin.json

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

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

@@ -1,6 +1,7 @@
 {
   "name": "optbrew",
   "displayName": "optbrew",
+  "version": "0.2.1",
   "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",
@@ -19,5 +20,13 @@
   ],
   "skills": [
     "./optbrew"
-  ]
+  ],
+  "userConfig": {
+    "google_api_key": {
+      "type": "string",
+      "title": "Google API key (optional)",
+      "description": "Fills the real-visitor speed scores (LCP, INP, CLS) from Google's Chrome UX Report and PageSpeed Insights. Kept in your system credential store and sent only to Google. Leave it empty to audit without them.",
+      "sensitive": true
+    }
+  }
 }

package/skills/README.md

@@ -15,7 +15,7 @@ The audit then runs in one go. It writes `report.html`, `report.md` and `report.
 - **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.
+- **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. In the Claude Code plugin, the optional `google_api_key` setting (`/plugin`, **Installed**, optbrew, **Configure options**) comes before both; Claude Code keeps it in the system credential store and the plugin's SessionStart hook hands it to the session. 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.

package/skills/optbrew/bundle-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0.0",
-  "release_version": "0.2.0",
+  "release_version": "0.2.1",
   "evaluation_version": "0.4.0",
   "protocol_version": "0.2.0",
   "evaluation_sources": [
@@ -724,7 +724,7 @@
     },
     {
       "path": "references/runbooks/google-api-key.md",
-      "sha256": "8c752ee46300fdd57e3a87efa4d3addc38c7a69ee2f409ddfba188c79cdf3d7d"
+      "sha256": "ca75745cceea090cb1f31926be3fdab5ceb0e27bf5e95fd83c74762ce6c4cfb7"
     },
     {
       "path": "references/runbooks/gsc-export.md",
@@ -744,7 +744,7 @@
     },
     {
       "path": "references/runbooks/key-set-local.md",
-      "sha256": "9f2a59e4e5e45fe2f2dfcc3651364d9549b26296ed4191c577cf8f57bd328c00"
+      "sha256": "43424c1b72766c3866e210c3a666ccca50a2fc6244a29c11d8519a36fff770fd"
     },
     {
       "path": "references/runbooks/naver-searchadvisor-export.md",
@@ -780,7 +780,7 @@
     },
     {
       "path": "references/versions.json",
-      "sha256": "105378f9955712e900290078224d0f21895f6fb9274323ebce69e536576acbb0"
+      "sha256": "838675b611fcc6fb243b253575f17af8536fa30d912e0e654be4a819ece3e908"
     },
     {
       "path": "scripts/adapters/anthropic.mjs",
@@ -948,7 +948,7 @@
     },
     {
       "path": "scripts/core/keys.mjs",
-      "sha256": "2796757270929679abe3fdb3b13f7f0a60a4f6cb6da395a9bb6af8e87c0b3a04"
+      "sha256": "ef7e5d7106628da61da448b170accdf834244c10035165cc96f6110101d2c9f0"
     },
     {
       "path": "scripts/core/link-graph.mjs",
@@ -1028,7 +1028,7 @@
     },
     {
       "path": "scripts/key.mjs",
-      "sha256": "b800a478d601bddf461c6237295fd54279fcd1a14459261e938f0b5a342c6467"
+      "sha256": "047fc58f97b978c33334375cb9ee824c9fe0d0d93d3b6ecddb7e1691afb48cb0"
     },
     {
       "path": "scripts/preflight.mjs",
@@ -1043,5 +1043,5 @@
       "sha256": "dca0bbd03fbf591c4aca6a568be76615eb48d69f7df0c634886f652b54f3f46d"
     }
   ],
-  "bundle_hash": "4f9cf4134069bf43e1243d9a1a925bf6712cc7fb858841161c26361d7b3a9e70"
+  "bundle_hash": "5b7087588e8fc817a3a5704e9b6418955bf5f615594ac9cbedf149bc5a3e707d"
 }

package/skills/optbrew/references/runbooks/google-api-key.md

@@ -39,7 +39,7 @@ harness: any
 27. **만들기**(Create)를 누릅니다.
 28. **API 키 생성 완료**(API key created) 창에 키 문자열이 나옵니다. 키 옆 복사 아이콘을 눌러 복사합니다. 창을 닫기 전에 복사를 마칩니다.
 29. 키를 채팅창, 메모, 문서, 화면 공유에 붙여 넣지 않습니다.
-30. 키를 optbrew에 넣는 방법은 사용 중인 환경에 맞는 런북을 따릅니다. 내 컴퓨터의 터미널은 `key-set-local`, Claude Code 클라우드는 `key-set-claude-cloud`, Codex는 `key-set-codex`입니다.
+30. 키를 optbrew에 넣는 방법은 사용 중인 환경에 맞는 런북을 따릅니다. 내 컴퓨터의 터미널과 Claude Code 플러그인 설정은 `key-set-local`, Claude Code 클라우드는 `key-set-claude-cloud`, Codex는 `key-set-codex`입니다.
 
 키가 유출됐다고 의심되면 **사용자 인증 정보** 목록에서 그 키를 삭제하고 새로 만듭니다.
 

package/skills/optbrew/references/runbooks/key-set-local.md

@@ -1,6 +1,6 @@
 ---
-checked: 2026-10-17
-source: https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell
+checked: 2026-10-18
+source: https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell https://code.claude.com/docs/en/plugins/install https://code.claude.com/docs/en/plugins-reference
 harness: local
 ---
 
@@ -32,9 +32,22 @@ node "{{skill_root}}/scripts/key.mjs" status
 
 npm으로 optbrew를 설치했다면 같은 일을 `optbrew key set google`, `optbrew key status`로 할 수 있습니다. 저장한 키를 지울 때는 같은 방법으로 `key remove google` 명령을 씁니다. 지우면 `google key removed`가 나옵니다.
 
+**Claude Code에 optbrew를 플러그인으로 설치했다면** 위 명령 대신 플러그인 설정에 키를 넣을 수 있습니다. 이 값은 Claude Code가 운영체제의 자격 증명 저장소에 보관하고, 키 파일과 `OPTBREW_GOOGLE_API_KEY`보다 먼저 쓰입니다.
+
+1. Claude Code 입력창에 `/plugin`을 입력하고 Enter를 누릅니다.
+2. Tab 키로 **Installed** 탭으로 갑니다.
+3. 목록에서 `optbrew`를 골라 Enter를 누릅니다.
+4. **Configure options**를 고릅니다.
+5. **Google API key (optional)** 칸에 키를 붙여 넣고 저장합니다. 입력한 글자는 가려져 보이는 것이 정상입니다.
+6. 새 세션을 시작합니다. 키는 새 세션부터 쓰입니다. (화면 확인 필요: 데스크톱 앱)
+7. 에이전트에게 "키 넣었어"라고만 말합니다. 에이전트가 위 `status` 명령으로 `"present":true`를 확인합니다.
+
+플러그인 설정의 키를 지우려면 같은 칸을 비우고 저장한 뒤 새 세션을 시작합니다.
+
 ## brief
 
 - 내 터미널에서 `node "{{skill_root}}/scripts/key.mjs" set google`(npm 설치는 `optbrew key set google`)을 실행하고, 숨겨진 입력 창에 키를 붙여 넣습니다.
 - 키는 `~/.optbrew/credentials.json`에 저장됩니다. `OPTBREW_GOOGLE_API_KEY` 환경 변수가 있으면 그것이 먼저입니다.
+- Claude Code 플러그인 설치는 `/plugin` → **Installed** → optbrew → **Configure options**의 **Google API key**에 넣어도 됩니다. 이 값이 가장 먼저 쓰이고, 새 세션부터 적용됩니다.
 - `key status`로 존재와 해시 앞 8자만 확인하고, 지우려면 `key remove`입니다.
 - 키를 대화창에 붙이지 않습니다.

package/skills/optbrew/references/versions.json

@@ -1,5 +1,5 @@
 {
-  "release": "0.2.0",
+  "release": "0.2.1",
   "evaluation": "0.4.0",
   "protocol": "0.2.0",
   "contract_schema": "2.0.0",

package/skills/optbrew/scripts/core/keys.mjs

@@ -5,6 +5,8 @@ import os from 'node:os';
 import path from 'node:path';
 
 const ENV_NAME = 'OPTBREW_GOOGLE_API_KEY';
+// The Claude plugin's `google_api_key` setting (userConfig, sensitive), handed to the session's shell commands by the plugin's SessionStart hook.
+const PLUGIN_ENV_NAME = 'CLAUDE_PLUGIN_OPTION_GOOGLE_API_KEY';
 const HASH_CHARS = 8;
 const OWNER_ONLY_FILE = 0o600;
 const OWNER_ONLY_DIR = 0o700;
@@ -37,9 +39,12 @@ function readCredentials(file) {
   try { return loadCredentials(file); } catch { return {}; }
 }
 
-/** Environment variable first, then the key file. An empty variable, a missing file or a corrupt file all mean "no key". */
+/**
+ * The Claude plugin setting first, then the environment variable, then the key file. An empty value, a missing file or a
+ * corrupt file all mean "no key".
+ */
 export function readGoogleKey({ env = process.env, home = keyHome(env) } = {}) {
-  return clean(env?.[ENV_NAME]) ?? clean(readCredentials(credentialsPath(home)).google);
+  return clean(env?.[PLUGIN_ENV_NAME]) ?? clean(env?.[ENV_NAME]) ?? clean(readCredentials(credentialsPath(home)).google);
 }
 
 /**

package/skills/optbrew/scripts/key.mjs

@@ -71,7 +71,7 @@ export async function runKeyCommand(argv, { stdin = process.stdin, stdout = proc
       stdout.write(`${JSON.stringify(googleKeyStatus({ env, home }))}\n`);
     } else if (action === 'remove') {
       stdout.write(await removeGoogleKey({ home }) ? 'google key removed\n' : 'no google key in the key file; nothing to remove\n');
-      if (googleKeyStatus({ env, home }).google.present) stderr.write('OPTBREW_GOOGLE_API_KEY is still set in the environment\n');
+      if (googleKeyStatus({ env, home }).google.present) stderr.write('a google key is still set outside the key file: OPTBREW_GOOGLE_API_KEY or the Claude plugin setting\n');
     } else {
       const key = (stdin.isTTY ? await readHidden(stdin, stdout) : await readLine(stdin)).trim();
       if (!key) { stderr.write('no key entered; nothing saved\n'); return 2; }