optbrew 0.1.2 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
-  "name": "optbrew-local",
-  "description": "Local optbrew plugin source",
-  "owner": { "name": "optbrew" },
-  "plugins": [{ "name": "optbrew", "source": "./", "version": "0.1.2" }]
+  "name": "optbrew",
+  "description": "optbrew: search, Naver and AI-answer readiness audit skill",
+  "owner": { "name": "nowwcastle-sudo", "url": "https://github.com/nowwcastle-sudo" },
+  "plugins": [{ "name": "optbrew", "source": "./skills", "description": "Audit a site, fix approved local files, re-check under the same conditions and write a scored report" }]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "optbrew",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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.1.2",
+  "version": "0.2.0",
   "description": "Pinned search audit and improvement skill bundle",
   "license": "MIT",
   "extensions": {
     "com.openai": {
       "skills": ["./skills/optbrew"],
-      "release_version": "0.1.2"
+      "release_version": "0.2.0"
     }
   }
 }

package/AGENT_INSTALL.md

@@ -0,0 +1,94 @@
+# Install optbrew — instructions for an AI agent
+
+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
+
+## Rules
+
+- Install only what the user asked for. Do not change other skills, settings or accounts.
+- Never delete `.optbrew/runs` or an `optbrew-audit` folder (the user's audit evidence) or a whole `.optbrew` folder (it also holds the user's Google key file). The only deletions in this guide are the paths that the reinstall check in [Update](#update) prints.
+- Do not call paid APIs, submit sites to search engines or publish anything. optbrew itself does none of these without the user's approval.
+- Show the user the planned changes (step 3) before you install.
+- On Windows in PowerShell, write `npx.cmd` wherever this guide says `npx`. Plain `npx` runs `npx.ps1`, which the default execution policy blocks with "running scripts is disabled".
+
+## 1. Ask the user two questions
+
+1. Which agents should get the skill? Valid IDs: `codex`, `claude-code`, `cursor`, `opencode`, `pi`. Default: the agent you are running in.
+2. Install for the user account (`user`, every project) or for one project folder (`project`)? Default: `user`.
+
+Write the answers as `AGENTS` (comma-separated, no spaces) and `SCOPE`. For `project`, also get the absolute folder path as `PROJECT`.
+
+## 2. Check Node.js
+
+```text
+node -p "process.versions.node"
+```
+
+Check: the major version is 22 or higher. If Node.js is missing or older, stop and tell the user to install Node.js 22 or later from https://nodejs.org.
+
+## 3. Show the planned changes
+
+User scope:
+
+```text
+npx --yes optbrew@0.2.0 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
+```
+
+Check: exit code 0 and `"status": "dry_run"`. Show the user `decision.targets[].path` from the output and ask for approval before step 4.
+
+If the output says `existing release differs; use optbrew update`, optbrew is already installed: go to [Update](#update) instead. If it says `unmanaged optbrew target exists`, stop: tell the user the path and ask them what to do with that folder. Do not delete it yourself.
+
+## 4. Install
+
+Run the command from step 3 without `--dry-run`.
+
+Check: exit code 0 and `"status": "installed"` (or `"unchanged"` when the same release was already in place).
+
+## 5. Verify
+
+```text
+npx --yes optbrew@0.2.0 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.
+
+## 6. Hand over
+
+Tell the user:
+
+- The skill is installed for AGENTS (SCOPE scope).
+- Start a new agent session. Then say "run optbrew" (or "optbrew 실행해") with the site URL and the goal, for example search traffic, Naver visibility, or AI answer citations.
+- optbrew asks for the URL first if it is missing. Then it checks the setup and sends all start questions in one message. The user can answer each number or reply "시작" (start) to accept the defaults.
+- The audit then runs in one go and writes `report.html`, `report.md` and `report.json` to `optbrew-audit/<site>-<date>` in the working folder. The user opens `report.html` first.
+- A Google API key is optional. It fills the real-visitor speed scores. The user saves it from their own terminal with `optbrew key set google` (or the `key.mjs` command that the key guide shows). Never ask the user to paste a key into the chat, and never read the key file.
+
+## 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`.
+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).
+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.
+
+## Troubleshooting
+
+| Message | What to do |
+|---|---|
+| `running scripts is disabled` (PowerShell) | Use `npx.cmd` instead of `npx`. |
+| `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. |

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 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.
+
+### What you see
+
+- **One call.** The agent checks your setup (`preflight.mjs`), sends the start questions in one message (one setup guide at most when something blocks the audit, plus up to three one-line offers), runs the audit with one command (`run.mjs`), judges the page text that code cannot judge, runs the same command again with `--judgments`, and hands you three reports: `report.html`, `report.md` and `report.json`. You answer once. The questions, guides and report are in Korean, and "시작" (start) takes every default.
+- **Which pages.** The audit takes pages from the sitemap and from links on the start page, up to the limit you choose: 50 pages by default, up to 200. The limit counts every request, including redirects and the robots and sitemap files. The same site gives the same pages every time. An address that redirects to its `www` or `https` twin is followed, and the report says so. A redirect to a different site stops the run with one sentence.
+- **Pages the site keeps out of the index.** A page with `noindex` that is not the home page and is missing from the site's own sitemap (a contact form, a thank-you page) is treated as meant that way: it gets no index, sitemap, crawler, title, canonical or Naver markup check and is no blocker. The run conditions list these pages. Without a sitemap that lists pages, a `noindex` stays a blocker.
+- **Which engines.** Google is always a target. Naver is a target when a goal names it, when you give a Naver export, or when the site is Korean (`lang="ko"` or an address ending in `.kr`).
+- **One fix per problem.** Pages with the same problem are one fix that lists how many pages it affects, instead of one finding per page. The fixes are sorted by what to do first.
+- **Fixes the model judged.** A missing date, an unnamed operator or a claim with no source is worded in Korean from the message catalog, one fix per page: the problem (an answer-clarity fail names its question), the page, the text it cites, where to look, what to do, how much work, and how to check. The model's own reason stays in `report.json` as evidence.
+- **Questions.** A page may answer several of your start questions, and a line every page repeats (a footer phone number) counts for a question when the model cites it for that question. A question with no answering page reads "not found within the pages read", never "the site lacks it".
+- **Korean report.** Every sentence in `report.md` and `report.html` is Korean: the fixes and the remaining work. A few ids in the run conditions stay English, and so do JSON keys and ids. The HTML report is one self-contained file with no script and no outside request. Runbook steps are a plain numbered list. A step shows a screen drawing only where a runbook names the position, and no runbook does yet.
+- **Speed scores.** Core Web Vitals of real visitors (LCP, INP, CLS) come from Google's Chrome UX Report and PageSpeed Insights when they have data. A free Google API key makes this work; without one those cells can stay blank, with the steps to get a key in the report. The lab values measured in your Chrome are shown as a run condition and are never scored.
+- **Google key command.** `optbrew key set google`, `optbrew key status` and `optbrew key remove google` (or `node <skill folder>/scripts/key.mjs ...`). You run it in your own terminal with hidden input. The key is saved in `.optbrew/credentials.json` in your home folder, outside every project; `OPTBREW_GOOGLE_API_KEY` takes priority. It is sent to Google only in a request header and is never written to a report, a log or the evidence. The agent never asks for it in the chat.
+- **Chrome.** The audit renders up to 10 pages, one of each kind, in a headless Chrome of its own, with a temporary profile that it removes at the end. Your running Chrome is never touched. The audit works through a proxy (`HTTPS_PROXY`); proxy credentials are never recorded. Without Chrome the render checks are blank, with the steps to install it.
+- **Owner exports.** A Search Console zip and a Naver Search Advisor text file are read when you give their paths. Their numbers appear as actual outcomes and do not enter the score.
+- **Setup guides (runbooks).** Step-by-step guides cover what needs your account or your machine: a Google API key and where to save it (your terminal, Codex, Claude Code cloud), Chrome, the two export files, network permission for Codex and Claude Code cloud, collecting visitor speed data inside your site, and the optional Anthropic and SE Ranking connections. The agent shows a full guide unasked only when something blocks the audit; every other guide appears when you ask for it, at the guidance level you picked.
+- **Old output folders.** A folder or evidence packet from a 0.1.x run is refused with one sentence: run the audit again in a new folder. A finished folder, or one that holds files the audit did not write, is refused too.
+
+### Versions
+
+Release 0.2.0, evaluation 0.4.0 (was 0.3.0), audit protocol 0.2.0 (was 0.1.0), contract schema 2.0.0. Scores of different evaluation versions are not comparable: `compare` reports `not_comparable` against a 0.1.x baseline.
+
+### Upgrading from 0.1.x
+
+- A managed install of any 0.1.x release (0.1.2 and 0.1.3 were tested) stops `optbrew update` with `migration_required` and changes nothing. Replace it with the blocks in `docs/platforms.md`, "Reinstall after a migration_required update". They run the read-only `optbrew reinstall-plan` first and never touch your evidence.
+- A plugin install from the marketplace follows `main`; the plugin update commands of your host are enough.
+- Run the baseline audit again with 0.2.0 before you compare.
+
+### Known limitations
+
+- The one-call audit refuses private and local addresses; a local target can no longer be declared from the start questions.
+- The fix step writes a change record for each edited file, but the 0.2.0 report does not read it, and a re-check after deploy does not update its `verification`; it stays `pending`. The re-check compares two audits (`cli.mjs compare`) and says what is resolved.
+- Core Web Vitals field data can stay unknown: a site with few visitors has no Google data, and the `cwv-site-collection` guide explains how to collect it in the site itself.
+- A runbook shows no screen drawing yet. A drawing appears only for a step that carries an explicit position tag.
+
+### Release checks that stay with the owner
+
+- The wording of the eli5 notice in `skills/optbrew/THIRD_PARTY_NOTICES.md`: its licence text was reconstructed because upstream has no licence file and no year. Decide the wording before the release is published. The caveman notice is copied from the installed 4.0.1 package.
+- After the merge: the claude.ai copy shows the merge commit (a check that waits for the sync). A directory review result does not block the release.
+- The steps in `docs/release.md`: CI on the merge commit, the tag, the GitHub Release and `npm publish` are run by the owner, not by an agent.
+
+### Carried over from the unreleased 0.1.4
+
+- The Claude marketplace now serves the `skills/` folder (new `skills/.claude-plugin/plugin.json`) instead of the repository root, because claude.ai, Claude Desktop and Cowork refuse a plugin with a top-level `bin/` folder and the marketplace sync failed. The marketplace entry and the served manifest pin no version, so every commit is picked up by marketplace sync. Claude Code installs keep the name `optbrew@optbrew` and the skill `/optbrew:optbrew`.
+- No `.gitattributes` at the repository root or inside `skills/`. The Claude plugin directory refuses one there whatever its lines say, `* -text` included, so the root file is gone. `tests/` and `docs/` keep their own `* -text`, because the test fixtures, evidence hashes and the documented shell blocks need exact bytes. A test rejects a `.gitattributes` at the root or inside `skills/`, and every file is still committed with LF.
+- Bundle hashes ignore the line endings a checkout adds. With `core.autocrlf=true` (the Git for Windows default) a Claude Code plugin install from the marketplace checks the skill out with CRLF. `bundle.mjs` and `score.mjs` now hash a file without a NUL byte as its LF form, so `doctor`, `install` and scoring accept that copy; LF files keep their old hashes and binary files hash as is. The ZIP and npm verifiers still compare exact bytes, so releases are built from a `core.autocrlf=false` clone (`docs/release.md`).
+- `docs/release.md` adds two steps: publish a GitHub Release for each tag and read it back, and confirm that the webhook got a push for `refs/heads/main` with the merge commit (a branch deletion is answered `ignored_delete` and does not sync).
+- The served `skills/` folder is a complete directory plugin: `skills/README.md` describes what the plugin runs, reads and sends, and `skills/.claude-plugin/plugin.json` adds `displayName`, `homepage`, `repository`, `license`, `keywords` and a 1024 px icon (`skills/.claude-plugin/icon.png`). Submit to the Claude directory with plugin path `skills`, so the scan reads only the plugin and not the repository's CLI, tests and npm files. A test checks the directory's README, license, icon, file-size and file-count rules.
+
+## 0.1.3
+
+Resolves the seven known limitations listed under 0.1.2.
+
+- Evaluation version 0.3.0 (was 0.2.0; protocol stays 0.1.0 because its source files are unchanged). The discovery and fact observations change, so 0.1.2 and 0.1.3 scores are not comparable: `compare()` returns `not_comparable` for a 0.1.2 baseline against 0.1.3 inputs. Run the baseline audit again with 0.1.3.
+- A managed install of 0.1.2 cannot be updated to 0.1.3. The updater guard is unchanged, so `optbrew update` stops with `migration_required` and changes nothing. Replace the install with the copy-paste blocks in `docs/platforms.md` ("Reinstall after a migration_required update"; the READMEs link there); they run the read-only `optbrew reinstall-plan` first. Audit evidence from 0.1.2 has no hashed failure records and is refused by 0.1.3 report replay with an "older optbrew release" error.
+- The request limit is a hard ceiling again. Every request, each redirect hop included, takes one budget slot immediately before it is sent, so the total never exceeds `max_urls` (the 0.1.2 overshoot of up to concurrency x min(10, `max_urls`) requests is gone). A redirect chain the limit stops leaves its URL as a `request_limit` unknown and keeps the hops it already received. A failed fetch now writes a hashed `<sha256>.failure.json` record (answered redirect hops plus whether one more attempt got no response; listed in `failures` in the audit index), and report replay checks the ledger entry against it. An honest run that reaches the limit inside a redirect chain therefore replays, and a limit claim is accepted only when the recorded requests use the whole limit.
+- Report replay rejects a URL that appears in more than one ledger entry, so duplicate failed-fetch entries for already fetched linked URLs can no longer prove a false request limit.
+- Orphan pages are decided in steps. An unlinked page is an orphan unless another collected page's own bytes (inline scripts included) name its path as a whole path, or a script-only page loads a same-origin script file that was not collected; a fetched sitemap that lists other pages and leaves the page out still proves the orphan. A script-only widget page that never mentions the orphan no longer hides it.
+- Phone extraction reads a national number written with spaces only (`02 555 0142`) and Korean nationwide representative numbers (15xx, 16xx and 18xx plus four digits) in labelled fields, `tel:` links and JSON-LD `telephone`. Prose, dates, fax numbers and a spaced number followed by more digits stay unread.
+- A page is a separate entity only on structural evidence: JSON-LD `branchOf`, `parentOrganization` or another `@id`, a branch-list URL path (`/branch/`, `/branches/`, `/locations/`, `/stores/`, `/지점/`), or the word branch, 지점 or 지사 in the title or first heading together with an address of its own. A title word alone no longer hides a wrong phone or address.
+- The Naver crawler token `Yeti` is confirmed against Naver's robots.txt guide, read again on 2026-10-15 (page text sha256 `ff8ddc85c5dd42e0d1133abae6928fb9b42f67f35d1b2c89b40378009571ed49`); `ai-crawlers.json` and `ai-crawlers.md` carry the source, the date and the hash.
+- Five install routes in the README: npm, npx, a pinned PowerShell installer (`install.ps1`, which reads `doctor` and stops on a failed check), Claude Code and Codex plugins (marketplace `optbrew`, so the plugin is `optbrew@optbrew`; Codex reads `.agents/plugins/marketplace.json`), and a prompt that hands an agent the new step-by-step `AGENT_INSTALL.md`. The READMEs were rewritten around why, how it works and installation; checkout commands and the reinstall blocks moved to `docs/platforms.md`. New `CONTRIBUTING.md`.
+- Seeded-defect detection on the frozen answer key: 29 of 61 detected (0.1.2: 28), 2 module-only, no new failure on a clean control page; the orphan page (SEO-12) is detected again. See `docs/validation/detection-0.1.3.md` (repository only).
+
+### Known limitations
+
+- An inline script that builds a URL from pieces can hide the link from the orphan check, so such a page is reported as an orphan although the script links it.
+- Report replay checks that evidence files agree with each other and with their hashes. Someone who rewrites the collection, the ledger, the hashed records and the audit index together can still make a coherent false run; the failure-record chain length is bounded (at most eleven answered hops per failed fetch), a URL can appear once, and every failed fetch or skipped URL needs provenance, which limits how far such an edit can pad the request total.
+- Phone extraction does not read numbers shorter than nine digits other than the 15xx, 16xx and 18xx representative numbers, nor national numbers separated by spaces outside a label.
+
 ## 0.1.2
 
 - The report headline no longer lets a measured score read as a complete one. Each headline score carries its coverage; below the 80% coverage rule the single number is withheld and the report shows `insufficient coverage` with the measured-subset value and the missing-data bounds (`report.json` `headline[]`).
@@ -20,7 +93,7 @@
 - `build-release` writes `bundle-manifest.json` through the same temporary file and rename as `build-bundle`, and the release tests build on a private copy of the tree.
 - Not scripted yet: the `robots.txt` Sitemap line, og:image size, hreflang, JavaScript-only navigation, answer structure, claim support, authorship and freshness.
 
-### Known limitations
+### Known limitations (all resolved in 0.1.3)
 
 - Report replay does not reject a URL that appears in more than one ledger entry, so adding failed-fetch duplicates of already fetched linked URLs to `collection.json`, `ledger.json` and the audit index can prove a false request limit and turn a discovery failure into `unknown`; this needs deliberate edits to local evidence files.
 - A run that reaches the request limit while a failed fetch was following redirects can record fewer requests than the limit, and report replay then refuses it as unprovable; run the audit again.

package/README.ko.md

@@ -1,149 +1,173 @@
 # 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)
+
 [English](README.md)
 
-Optbrew는 웹사이트의 검색 준비도를 확인하고, 승인된 로컬 파일을 고친 뒤, 전후 근거를 비교하는 스킬과 CLI입니다. 고정된 원본 묶음 5개(mblode SEO, Naver Search Advisor, Firecrawl SEO Audit, Magnus SEO, SE Ranking SEO)와 선택한 마케팅 가이드 7개를 포함합니다. 최상위 `SKILL.md` 한 파일이 내부 가이드를 안내합니다. 실행 중에 바뀌는 upstream 파일을 가져오지 않습니다.
+코딩 에이전트용 검색 준비도 감사 스킬입니다. optbrew는 구글·네이버·AI 답변 엔진 기준으로 사이트를 점검합니다. 승인한 로컬 파일만 고치고, 같은 조건으로 다시 확인한 뒤, 다시 계산할 수 있는 근거로 점수 보고서를 씁니다.
+
+- 스킬 하나로 다섯 가지를 봅니다: **SEO**, **NEO**(네이버), **AEO**, **GEO**, **LLMO**.
+- 초보자도 한 번에 끝냅니다. 시작 질문에 한 번 답하면 에이전트가 감사 전체를 돌리고 HTML 보고서를 건네 줍니다.
+- 고정된 감사 가이드 묶음 5개를 점검 항목 22개로 합쳤습니다. 여러 가이드가 같은 문제를 짚어도 한 번만 셉니다.
+- 보고서의 판정은 모두 수집한 원본 응답(해시 기록)에서 다시 계산할 수 있습니다.
+- 근거가 모자라면 대표 점수를 내지 않습니다. 측정 범위가 80% 미만이면 잰 부분과 그 범위만 보여 줍니다.
+- Codex, Claude Code, Cursor, OpenCode, Pi에서 씁니다. 점수 계산과 보고서에는 API 계정이 필요 없습니다.
+
+## 왜 optbrew인가
+
+이제 「검색에 잡힌다」는 말은 세 가지를 뜻합니다. 구글 순위, 네이버 노출, AI 답변 속 인용입니다. 셋 다 가이드가 따로 있고, 가이드끼리 겹치거나 서로 다른 말을 합니다. 에이전트에게 「SEO 개선해 줘」라고 하면 보통 체크리스트 하나를 골라 파일을 고치고, 근거 없이 끝났다고 보고합니다.
+
+optbrew는 다섯 기준 모두에 같은 작업 순서와 같은 채점 규칙을 씁니다. 잰 것만 점수에 넣고, 재지 못한 것은 통과가 아니라 「알 수 없음」으로 남깁니다. 로컬에서 고친 것과 실제 운영 결과도 따로 적습니다. 준비도 점수가 높아도 방문자나 인용이 는다는 보장은 없으며, 보고서에도 그렇게 적힙니다.
 
-저장된 JSON으로 점수를 계산하고 보고서를 만드는 데 API 계정은 필요하지 않습니다. 사이트 감사에는 대상과 허용 범위가 필요합니다. 공개 게시, 검색엔진 제출, 원격 사이트 수정, 유료 호출은 각각 별도 권한이 필요합니다. 설치 파일이 놓인 상태와 호스트가 실제로 스킬을 호출한 상태는 [플랫폼 안내](docs/platforms.md)에서 구분합니다.
+## 동작 방식
+
+1. **질문.** URL을 알려 주면 optbrew가 시작 쪽, 사이트맵, 사용자의 환경(크롬, 구글 키, 네트워크)을 읽습니다. 그다음 시작 질문을 한 메시지로 보냅니다. 안내 수준, 목표, 사람들이 찾을 질문, 사이트에서 읽은 사실, 쪽수 상한을 묻습니다. 번호마다 답하거나 「시작」만 답하면 기본값으로 갑니다. 네트워크가 막혀 있는 것처럼 감사를 막는 일이 하나 있으면 설정 안내를 먼저 보여 줍니다. 그 밖의 안내는 한 줄짜리 제안으로 최대 세 개까지 나오고, 그 단어로 답하면 열립니다.
+2. **감사.** 명령 한 번으로 수집, 페이지 종류마다 한 쪽씩 최대 10쪽을 전용 헤드리스 크롬으로 렌더링, 속도 측정, 코드 판정을 끝냅니다. 사이트맵과 시작 쪽의 링크에서 쪽을 골라 상한까지 감사합니다. 기본은 50쪽이고 올리면 최대 200쪽입니다. 상한은 모든 요청을 세므로 리다이렉트와 robots·사이트맵 파일도 한도를 씁니다. 주소가 `www`나 `https` 쌍둥이 주소로 넘어가면 따라가고, 보고서에 그렇게 적습니다. 응답마다 해시와 함께 저장합니다.
+3. **판정.** 코드가 판정할 수 없는 글 내용(주장, 답의 명확성, 최신성 등)은 에이전트가 읽고 판정합니다. 근거로 삼은 문장을 인용하고, 같은 명령을 한 번 더 실행하면 인용한 글이 증거 안에 실제로 있는지 확인한 뒤 점수를 냅니다.
+4. **보고.** 내용이 같은 파일 셋이 나옵니다. `report.html`(먼저 여십시오. 파일 하나로 완결됩니다), `report.md`, `report.json`입니다. 글은 한국어입니다. 문제마다 고칠 것이 하나이고 영향을 주는 쪽수가 붙습니다. 구글 키가 없을 때처럼 비어 있는 칸은 번호를 매긴 단계로 채우는 법을 알려 줍니다. 비어 있는 칸은 통과가 아니라 「알 수 없음」으로 보입니다.
+5. **수정과 재확인(선택).** 에이전트가 로컬 파일 수정안을 냅니다. 승인 없이 고치거나 배포하거나 검색엔진에 제출하지 않습니다. 배포한 뒤에는 같은 조건으로 다시 수집합니다. 그래서 수정 전후를 비교할 수 있습니다.
+
+스크립트가 직접 재는 것과 가이드·에이전트 판단에 맡기는 것은 이렇게 나뉩니다.
+
+| 기준 | 대상 | 스크립트가 재는 것 | 판단에 맡기는 것 |
+|---|---|---|---|
+| SEO | 구글과 웹 검색 | 응답 상태, meta와 `X-Robots-Tag`의 `noindex`, 제목, Googlebot용 robots.txt, canonical, 리다이렉트 단계, 링크·사이트맵으로 찾을 수 있는지, JSON-LD 문법 | 콘텐츠 품질, 검색 의도와 맞는지 |
+| NEO | 네이버 | Yeti용 robots.txt, Open Graph, description, canonical, viewport, 제목 반복, 막힌 CSS·JS | 네이버 콘텐츠 가이드 |
+| AEO, GEO | 답변 엔진과 AI 검색 | [ai-crawlers.md](skills/optbrew/references/ai-crawlers.md)에 적은 AI 검색 봇용 robots.txt(학습용 봇은 채점하지 않음) | 답변 구조, 주장, 작성자, 최신성 |
+| LLMO | AI가 우리를 설명하는 방식 | 상호·주소·전화·설립 연도가 페이지끼리 일치하는지, 페이지들이 한 업체를 설명하는지 | 그 사실이 맞는지 |
+| 전체 | 속도와 스크립트 | 자바스크립트가 돈 뒤에도 글이 보이는지(크롬). 구글 Chrome UX Report와 PageSpeed Insights의 방문자 실측 점수(LCP, INP, CLS) | 없음. 크롬으로 잰 실험실 값은 실행 조건으로만 보이고 채점하지 않습니다 |
+
+엔진별 검사는 대상으로 밝힌 엔진에만 적용됩니다. ChatGPT·Claude·Perplexity처럼 신경 쓰는 AI 답변 엔진을 알려 주십시오. 목표에 네이버가 들어 있거나, 네이버 내보내기 파일을 주었거나, 사이트가 한국어(`lang="ko"` 또는 `.kr`로 끝나는 주소)이면 네이버는 저절로 대상이 됩니다. 구글은 항상 대상입니다. 채점 규칙은 [scoring.md](skills/optbrew/references/scoring.md)에 있습니다. 측정 범위 80% 기준은 optbrew가 정한 규칙이며, 검색엔진 표준이 아닙니다.
 
 ## 설치
 
-Node.js 22 이상이 필요합니다. 내부 Python 감사 도구는 Python 3.10 이상이 필요합니다. Python이 없으면 그 도구는 미실행으로 남깁니다. 이 checkout에서 `site`라는 별도 프로젝트 폴더를 만든 뒤 실행합니다.
+[Node.js](https://nodejs.org) 22 이상이 필요합니다. Python 3.10 이상은 선택입니다. 없으면 내부 Python 감사 도구만 실행하지 않습니다. 아래 다섯 방법 중 하나를 고르십시오. 예시는 Codex와 Claude Code에 사용자 범위로 설치합니다. 에이전트 ID는 `codex`, `claude-code`, `cursor`, `opencode`, `pi`입니다.
 
-Bash와 PowerShell에서 같은 명령을 사용합니다.
+Windows PowerShell에서 `npx`나 `optbrew`가 「스크립트를 실행할 수 없습니다」라고 하면 `npx.cmd`, `optbrew.cmd`로 바꿔 입력하십시오.
 
-```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.2.0
+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
 ```
 
-저장소 루트에서 실행하십시오. 기본 전략은 `--strategy link`입니다. 링크를 쓸 수 없으면 `copy`를 선택할 수 있습니다. 관리 기록은 프로젝트의 `.optbrew/install`에 둡니다. 한 호스트만 설치하려면 목록 대신 `codex`, `claude-code`, `cursor`, `opencode`, `pi` 중 한 ID를 적습니다. 사용자 전체 범위에 설치할 때만 `--scope user`를 씁니다. 설치 명령은 번들 manifest를 확인하며 관리 대상이 아닌 기존 폴더를 덮어쓰지 않습니다.
+미리보기(`--dry-run`)는 쓸 폴더를 보여 줍니다. `doctor`는 파일과 해시를 확인합니다.
 
-checkout은 `https://github.com/nowwcastle-sudo/optbrew`를 clone해서 받고, 위 명령은 그 저장소 최상위에서 실행합니다. `npm install -g optbrew`로 설치하면 같은 CLI를 `optbrew` 명령으로 쓸 수 있습니다. 이때는 위 명령의 `node bin/optbrew.mjs`를 `optbrew`로 바꿉니다. 호스트 고유 설치와 ZIP은 [플랫폼 안내](docs/platforms.md)를 보십시오.
+### 2. npx
 
-## 첫 실행
+전역 설치 없이 같은 CLI를 실행합니다.
 
-호스트에 optbrew를 사용하라고 요청할 때 대상 URL, 목표, 사이트 소유 또는 접근 권한, 허용할 로컬 변경, 보유한 근거를 전달합니다. 로컬 감사 전에 URL 범위를 선언합니다. 기본 수집 상한은 URL 50개, 깊이 3, 동시성 2입니다. 새 요청은 한도 아래에서만 시작합니다. 이미 시작한 리다이렉트 체인은 끝까지 갑니다. 체인은 리다이렉트 min(10, `max_urls`)번까지라서 한도를 넘는 요청은 동시성 × min(10, `max_urls`)건 이하입니다(기본값은 20건). 사설 주소는 명시한 로컬 대상에서만 허용합니다. 작업은 원시 근거, 준비도 관찰, 로컬 변경, 후속 확인을 기록합니다. 로컬 검증 통과를 운영 성과로 해석하지 않습니다.
+```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
+```
 
-다음 명령은 포함된 합성 fixture를 재생하며 제공자 호출을 하지 않습니다. 저장소 루트에서 새 출력 경로를 골라 실행합니다.
+### 3. PowerShell (Windows)
 
-Bash와 PowerShell에서 같은 명령을 사용합니다.
+```powershell
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/install.ps1 | iex
+```
 
-```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
+이 스크립트는 이번 버전에 고정돼 있습니다. Node.js를 확인하고, 설치할 폴더를 보여 주고, Codex와 Claude Code에 설치합니다. `doctor`가 문제를 찾으면 오류로 멈춥니다. 먼저 읽어 보거나 에이전트·프로젝트 폴더를 고르려면 이렇게 실행합니다.
+
+```powershell
+irm https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/install.ps1 -OutFile install.ps1
+powershell -ExecutionPolicy Bypass -File .\install.ps1 -Agents codex,claude-code,cursor
 ```
 
-명령을 그대로 실행하려면 `tests/fixtures/scoring/before.json`, `after.json`을 현재 폴더로 복사합니다. `tests/fixtures/reports/remote-only.json`과 같은 폴더의 근거 파일도 함께 복사합니다. 실제 작업에서는 자신의 검증된 `ScoreInput` 또는 `ReportPacket` 경로를 넘깁니다. 계약은 [채점](skills/optbrew/references/scoring.md), [측정](skills/optbrew/references/measurement.md), [보고 근거](skills/optbrew/references/report.md)에 있습니다.
+한 프로젝트에만 설치하려면 `-Scope project -Project C:\path\to\site`를 붙입니다.
 
-## 점수와 보고서
+### 4. 플러그인
 
-자체 준비도 프로필은 SEO, 네이버가 대상일 때 NEO, AEO, GEO, LLMO입니다. 고유 검사군 22개는 여러 가이드가 같은 문제를 찾아도 한 번만 셉니다. 확인하지 못한 적용 검사는 분모에 남기고, 근거 있는 `not_applicable` 검사만 제외합니다. 결과에는 점수, 측정 범위, 미측정 구간의 상·하한, 차단 요소, 미확인 핵심 검사가 들어갑니다. 측정 범위 80% 기준은 optbrew 자체 규칙이며 검색엔진 기준이 아닙니다. 높은 준비도 점수는 색인, 유입, 인용, 사실 정확성, 전환, 매출을 증명하지 않습니다.
+Claude Code:
 
-감사 스크립트가 수집한 응답에서 스스로 관찰하는 항목은 다음과 같습니다. 응답 상태, meta 태그와 `X-Robots-Tag`의 색인 지시자(대상 엔진별), 제목 없음·중복, 선언한 엔진별 robots.txt 접근(Googlebot, Yeti, [`ai-crawlers.md`](skills/optbrew/references/ai-crawlers.md)의 AI 검색 봇. 학습 봇은 점수에 넣지 않음), canonical 대상과 리다이렉트 체인 길이, 링크 또는 선언한 사이트맵을 통한 발견성, JSON-LD 문법, 네이버 마크업(Open Graph, 설명, canonical, viewport, 제목 키워드 반복, 막힌 CSS·JS), 이름·주소·전화·설립연도의 페이지 간 일치입니다. 따라서 SEO와 NEO는 접근·색인·마크업 검사를 스크립트로 합니다. AEO와 GEO는 준비도 감사로 남습니다. 답변 구조, 주장 근거, 저자, 최신성은 가이드와 에이전트 판단이 필요합니다. LLMO는 페이지 간 불일치를 보여 주는 검사를 얻지만 사실이 맞다는 것을 증명하지는 않습니다. 심은 결함 시험과 한계는 저장소의 `docs/validation/detection-0.1.2.md`에 있습니다.
+```bash
+claude plugin marketplace add nowwcastle-sudo/optbrew
+claude plugin install optbrew@optbrew
+```
+
+Codex:
 
-측정 범위가 80% 미만이면 보고서는 하나의 대표 점수를 내지 않고 측정된 부분의 값과 상·하한을 보여 줍니다. 모든 대표 점수는 측정 범위와 함께 표시됩니다.
+```bash
+codex plugin marketplace add nowwcastle-sudo/optbrew
+codex plugin add optbrew@optbrew
+```
 
-보고서는 준비도, 해결 방안, 실제 성과, 남은 일을 별도 표로 보여 줍니다. 실제 성과에는 소유자 내보내기 자료 또는 고정된 AI 질문 패널이 필요합니다. 일반 성과 비교에는 정의와 필터가 같은 인접한 완결 28일 기간 두 개를 사용합니다. 로컬 수정은 배포와 운영 관찰의 근거가 생기기 전까지 로컬 수정입니다.
+claude.ai, Claude Desktop, Cowork: Customize > Plugins에서 Add > Add marketplace를 고르고 `nowwcastle-sudo/optbrew`를 입력한 뒤 `optbrew`를 추가합니다.
 
-## API와 비용
+플러그인은 이 저장소의 `main` 브랜치를 따르며, 업데이트는 각 호스트의 플러그인 명령이나 마켓플레이스 동기화로 합니다.
 
-API 사용은 선택 사항입니다. Claude 또는 Claude Code 구독에 Anthropic API 과금이 포함되는 것은 아닙니다. 직접 API 키는 [공식 발급 안내](https://platform.claude.com/docs/en/get-api-key)의 Console → Settings → API keys에서 만듭니다. 키는 자신의 셸 또는 비밀 관리 도구에서 `ANTHROPIC_API_KEY`로 설정합니다. 보고서에 실값을 넣지 마십시오. v0.1.0에서 도입한 직접 어댑터는 여러 Anthropic workspace에 걸친 키에 필요할 수 있는 `anthropic-workspace-id` 헤더를 여전히 설정하지 않습니다. 호환 키나 별도로 승인된 호스트 기능을 사용합니다.
+### 5. 에이전트에게 맡기기
 
-직접 어댑터는 텍스트 `{model,max_tokens,messages}` 요청과 정확한 모델 ID `claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`만 받습니다. `max_tokens` 상한은 128,000입니다. 매 시도에는 `1,000,000 + max_tokens` 이상의 토큰 예약 한 개, 맞는 장부 예산, 승인 참조가 필요합니다. 이 예약은 최악 경우의 용량 상한이며 예상 청구액이 아닙니다. 첫 유료 호출 전에 현재 단가의 출처와 날짜, 예상 지출, 승인된 중단 조건을 기록합니다. 추가 필드, 도구, 검색, 비텍스트 입력, 다른 모델, 통화만으로 설정한 상한은 직접 호출 전에 거부됩니다. 자세한 경계는 [API 안내](skills/optbrew/references/api.md)에 있습니다.
+Codex, Claude Code 같은 코딩 에이전트에 아래 글을 붙여 넣으십시오.
 
-SE Ranking은 별도의 [API](https://seranking.com/api.html), [MCP 안내](https://seranking.com/api/integrations/mcp), 계정 상품, 크레딧을 사용합니다. [HTTP MCP 주소](https://api.seranking.com/mcp)는 문서에 따른 OAuth 또는 직접 토큰 경로를 씁니다. `ANTHROPIC_API_KEY`와는 별개입니다. 사용 가능한 도구는 구독에 따라 달라집니다. 오프라인 채점에는 어느 연결도 필요하지 않습니다. 유료 기능을 결정할 때 실제 계정의 단가와 크레딧을 확인합니다.
+```text
+optbrew 스킬을 설치해 줘. https://raw.githubusercontent.com/nowwcastle-sudo/optbrew/v0.2.0/AGENT_INSTALL.md 를 읽고 단계대로 따라 해. 어느 에이전트에, 어느 범위로 설치할지 먼저 묻고, 설치 전에 바뀔 내용을 보여 줘.
+```
+
+[AGENT_INSTALL.md](AGENT_INSTALL.md)는 단계마다 실행할 명령과 통과 기준, 멈추고 사용자에게 물어야 할 경우를 적어 둔 에이전트용 안내서입니다.
 
-## 업데이트와 복원
+소스 checkout에서 설치하기, Agent Skills CLI, Pi 패키지, Claude 웹 업로드는 [플랫폼 안내](docs/platforms.md)에 있습니다.
 
-관리 설치를 갱신하려면 먼저 검증된 새 optbrew 번들을 빌드하거나 받습니다. 저장소 루트에서 다음 명령을 실행합니다.
+## 빠른 시작
 
-Bash와 PowerShell에서 같은 명령을 사용합니다.
+새 에이전트 세션을 열고 이렇게 요청합니다.
 
 ```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
+https://example.com 에 optbrew 돌려 줘. 목표: 네이버 노출, AI 답변 인용.
 ```
 
-`check-updates --package optbrew`는 npm 레지스트리에서 최신 버전을 읽습니다. `--package`를 빼면 `local_only`를 반환합니다. `update`는 현재 CLI 번들을 검증한 뒤 관리 기록의 모든 대상에 적용합니다. 로컬 편집은 자동으로 덮어쓰지 않습니다. `rollback`은 관리 기록에 해당 이전 버전이 남아 있어야 합니다. 새 0.1.2 설치에서는 위 복원 예시가 실패하며, 로컬 0.1.0을 보존한 관리 설치에 적용됩니다. 출시 후 `npm update -g optbrew`는 npm 패키지를 갱신하지만 이전에 agent 스킬 폴더로 복사한 파일까지 바꾸지는 않습니다. CLI를 갱신한 다음 관리 `update`를 다시 실행합니다. 관리 중인 0.1.1 설치는 0.1.2로 갱신할 수 없고 `update`가 `migration_required`로 멈춥니다(아래 재설치 절차). 호스트 고유 갱신은 [플랫폼 안내](docs/platforms.md)를 보십시오.
-
-### migration_required 뒤 재설치
-
-0.1.2는 평가 버전 0.2.0을 사용합니다(0.1.1은 0.1.0). 그래서 0.1.1로 만든 점수와 기준선은 0.1.2와 비교할 수 없고 `compare`는 `not_comparable`을 반환합니다. 기준선 감사는 0.1.2로 다시 실행하십시오. 같은 이유로 관리 중인 0.1.1 설치에서 `optbrew update`를 실행하면 `migration_required`로 멈추고 아무것도 바꾸지 않으며, 메시지에 경로와 명령이 나옵니다. `uninstall` 명령은 없습니다. 0.1.2 저장소 루트에서 아래 블록으로 교체합니다. 각 블록은 먼저 읽기 전용 `reinstall-plan`을 실행해 설치 기록을 검증하고(모든 대상이 정확히 해당 에이전트의 `skills/optbrew` 경로여야 합니다) 변조된 기록이면 아무것도 지우기 전에 거절합니다. 이후 셸은 그 명령이 출력한 경로만, 대상을 먼저 지우고 관리 루트를 마지막에 지우므로 실패한 뒤 같은 블록을 다시 실행할 수 있습니다. 이 명령은 `.optbrew/runs`(감사 증거)를 건드리지 않습니다. `.optbrew` 폴더 전체를 지우지 마십시오. 자세한 설명은 [플랫폼 안내](docs/platforms.md)를 보십시오.
-
-사용자 범위:
-
-```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 }
-}
-```
+optbrew는 환경을 점검한 뒤 시작 질문을 한 메시지로 보냅니다. 번호마다 답하거나 「시작」만 답하면 기본값으로 갑니다. 구글 키, 크롬, 내보내기 파일이 없어도 감사는 멈추지 않습니다. 빈 칸은 채우는 방법과 함께 보고서에 적힙니다.
 
-```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"
-```
+감사에는 몇 분이 걸립니다. 결과는 작업 폴더의 `optbrew-audit/<사이트>-<날짜>`에 쌓입니다. 원본 근거(응답마다 해시)와 보고서 셋이 들어 있습니다. `report.html`을 먼저 여십시오. 같은 이름의 폴더가 있으면 `-2`, `-3`을 붙입니다. 사설·내부·로컬 주소(`localhost`, `192.168.x.x` 등)는 감사하지 않습니다. 공개 주소로 감사하십시오.
 
-프로젝트 범위(`./site`를 프로젝트 폴더로 바꾸십시오. 한 곳에만 나옵니다):
-
-```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 }
-}
+### 구글 API 키(선택)
+
+무료 구글 API 키가 있으면 실제 방문자가 겪는 속도 점수(LCP, INP, CLS)가 안정적으로 채워집니다. optbrew가 권하면 「키」라고 답하십시오. 발급 방법이 나옵니다. 키는 대화창이 아니라 본인 터미널에서 저장하십시오. Codex나 Claude Code 클라우드에서는 키 안내가 저장할 곳을 대신 알려 줍니다.
+
+```bash
+optbrew key set google
+optbrew key status
+optbrew key remove google
 ```
 
-```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"
+`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는 키를 요청 헤더로만 구글에 보내고, 보고서·로그·근거에는 쓰지 않습니다.
+
+## 업데이트
+
+```bash
+npm install -g optbrew@latest
+optbrew update --scope user
 ```
 
-## 지원 범위와 라이선스
+npx를 쓴다면 `npx optbrew@latest update --scope user`를 실행합니다. `optbrew check-updates --package optbrew`는 아무것도 바꾸지 않고, 지금 실행한 CLI보다 새 버전이 npm에 있는지 알려 줍니다. 에이전트 폴더에 설치된 버전은 `optbrew doctor --json`의 `release_version`에 나옵니다. `npm update`만으로는 에이전트 폴더에 이미 놓인 사본이 바뀌지 않습니다. 사본은 `update` 명령이 바꿉니다.
+
+### 0.1.x에서 올리기
+
+0.2.0은 평가 버전(0.4.0), 감사 프로토콜(0.2.0), 계약 스키마(2.0.0)를 바꿨습니다. 그래서 이렇습니다.
+
+- 0.1.x 설치본(managed install)은 `migration_required`로 멈추며, `optbrew update`는 아무것도 바꾸지 않습니다. [migration_required 뒤 재설치](docs/platforms.md#reinstall-after-a-migration_required-update) 절차를 따르십시오. 이 절차는 읽기 전용 검사가 출력한 경로만 지우며, 감사 근거는 건드리지 않습니다.
+- 플러그인 설치(Claude Code, Codex, claude.ai)는 `main`을 따라가므로, 쓰는 도구의 플러그인 업데이트 명령이 그대로 됩니다.
+- 0.1.x 실행이 남긴 결과 폴더와 근거 묶음은 한 문장으로 거부됩니다. 새 폴더에서 감사를 다시 실행하십시오. 평가 버전이 다른 점수끼리는 비교할 수 없어서, 0.1.x 기준선과 `compare`하면 `not_comparable`이 나옵니다. 기준선 감사를 0.2.0으로 다시 돌리십시오.
+
+## API와 비용
+
+유료 계정 없이 쓸 수 있습니다. Anthropic API나 [SE Ranking](https://seranking.com/api.html)을 직접 호출하려면 먼저 사용자 승인, 예산 기록, 중단 조건이 있어야 합니다. Claude 구독에는 API 요금이 포함되지 않습니다. 위의 구글 키는 본인 키이고, 그 키로 부르는 구글 속도 서비스는 무료입니다. 키는 환경 변수나 키 파일에만 두며 보고서에는 넣지 않습니다. 자세한 내용은 [API 경계](skills/optbrew/references/api.md)를 보십시오.
+
+## 문서
+
+- [플랫폼 안내](docs/platforms.md): 에이전트별 설치 경로, checkout 명령, 재설치 절차
+- [채점](skills/optbrew/references/scoring.md), [측정](skills/optbrew/references/measurement.md), [보고서 근거](skills/optbrew/references/report.md)
+- [변경 기록](CHANGELOG.md), [출시 절차](docs/release.md)
+
+## 기여
+
+기여를 환영합니다. 버그 제보, 실제 사이트에서 나온 오판, 가이드 갱신, 번역, 코드 모두 좋습니다. [CONTRIBUTING.md](CONTRIBUTING.md)를 보십시오.
 
-관리 설치·검사·갱신·복원은 문서화된 기본 경로의 Codex, Claude Code, Cursor, OpenCode, Pi를 대상으로 합니다. 호스트의 사용자 지정 경로, 프로젝트 신뢰 설정, 세션 재시작 조건은 탐색 결과를 바꿀 수 있습니다. 일반 ChatGPT 채팅에서는 파일을 첨부해 안내형으로 사용합니다. 이는 Codex나 Work/desktop 플러그인 설치와 다릅니다. Claude 웹에서는 ZIP을 직접 올리고 갱신 때 다시 올립니다. 호스트 탐색과 실제 호출 성공은 따로 확인해야 합니다.
+## 라이선스
 
-네이버 묶음은 [Search Advisor 공식 안내](https://searchadvisor.naver.com/guide)의 색인을 포함합니다. 네이버 원문 55개는 제외했으므로 전문을 오프라인에서 읽을 수 없습니다. 온라인에서 공식 링크를 여십시오. 포함한 원본의 라이선스와 변경 내역은 [제삼자 고지](skills/optbrew/THIRD_PARTY_NOTICES.md)에 있습니다. optbrew 자체 코드는 [MIT 라이선스](LICENSE)입니다. 서비스 접근권과 API 자료 이용권은 코드 라이선스와 별개입니다. 묶음 생성·검증 절차는 [릴리스 안내](docs/release.md)에 있습니다.
+optbrew 자체 코드는 [MIT 라이선스](LICENSE)입니다. 포함된 가이드는 각자의 라이선스를 따르며, [제3자 고지](skills/optbrew/THIRD_PARTY_NOTICES.md)에 정리돼 있습니다. 네이버 묶음에는 공식 [서치어드바이저 가이드](https://searchadvisor.naver.com/guide) 색인만 있고, 원문 55편은 없습니다. 온라인에서 공식 링크를 따라가십시오.