{ "markdown": "# PirateBao\n\n[![CI](https://github.com/d4551/piratebao/actions/workflows/ci.yml/badge.svg)](https://github.com/d4551/piratebao/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/piratebao?logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/piratebao)\n[![Bun](https://img.shields.io/badge/bun-1.3.14-14151a?logo=bun&logoColor=white)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/typescript-7.0.2-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)\n[![Node](https://img.shields.io/badge/node-%3E%3D24.11.0-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)\n[![Biome](https://img.shields.io/badge/biome-2.5.4-60a5fa?logo=biome&logoColor=white)](https://biomejs.dev)\n[![Vitest](https://img.shields.io/badge/vitest-4.1.10-6e9f18?logo=vitest&logoColor=white)](https://vitest.dev)\n[![Tokens saved](https://img.shields.io/badge/tokens_saved-77%25_avg_%7C_68%25_worst-0ea5e9)](evals/README.md)\n[![License](https://img.shields.io/badge/license-MIT-eab308)](LICENSE)\n\nPirateBao be a Bun-first, TypeScript-first pirate rig for terse AI coding replies. Commands, code, paths, versions, risk notes, stack traces, and test results stay nailed to the mast. Greeting foam, hedge fog, and apology barnacles get keelhauled on sight. Kraken eats boilerplate; cargo stays lashed. Parrot squawks; token bill shrinks.\n\nDefault sail: `kraken`. Main flags: `/piratebao`, `$piratebao`, `/piratebao:compress`. Goal: fewer tokens, same technical cargo, less polite sea-tax.\n\n## Explain Like I'm 5\n\nAI answers spend doubloons on hello, read the map thrice, then polish the plank until the plank demands equity. PirateBao heaves chatter overboard and lashes treasure to the mast: command, file, bug, fix.\n\n| Before | After |\n|---|---|\n| \"Sure, I would be happy to help. The issue is likely caused by a new object reference on each render.\" | \"New object ref each render. Use `useMemo`.\" |\n\nSame treasure map. Smaller scroll. Faster ship. Fewer invoices dressed as parrots. No \"hope this helps\" barnacle unless it actually fixes the failing test. Politeness is ballast; the kraken knows what to eat.\n\n```mermaid\nflowchart LR\n A[\"Long answer\"] --> B[\"PirateBao removes ceremony\"]\n B --> C[\"Short technical answer\"]\n C --> D[\"Fewer tokens\"]\n D --> E[\"Lower cost + faster replies\"]\n```\n\nThree questions a five-year-old pirate would ask:\n\n| Question | Answer |\n|---|---|\n| What is it? | A skill plus hooks that make an AI coding agent answer short without dropping technical cargo. |\n| What does it cost me? | Nothing at runtime. It removes words, not facts. Committed eval gate: 77% average saved, 68% worst saved. |\n| What can it break? | Nothing in your code. It shapes replies. Security, publish, and data-loss warnings stay long on purpose. |\n\n## Quick Start\n\n```bash\nbun install --frozen-lockfile\nbun run build\nbash hooks/install.sh\n```\n\nThen say `/piratebao` in Claude Code. Say `stop PirateBao` when the parrot needs a nap.\n\n## What It Ships\n\n| Area | Contract |\n|---|---|\n| Runtime | Claude Code hooks compile to `dist/hooks/*.js`; session start hauls no `tsx` anchor. |\n| Skills | Canonical behavior lives in `skills/piratebao/SKILL.md`; copies synced and verified — drift walks the plank. |\n| Compression | `/piratebao:compress ` uses Anthropic SDK, preserves code/URLs/paths/headings, writes `.original.md` backup. |\n| OpenCode | Native `.opencode/skills//SKILL.md` and `.opencode/commands/*.md`; no plugin dependency in this pass. |\n| Docs site | `docs/` is a static GitHub Pages surface with its own headless-browser test. |\n| npmjs | `package.json` exports compiled TypeScript cargo and gates the payload with `npm pack --dry-run --json`. No imaginary barrels aboard. |\n| `.bao` | `bao/piratebao.manifest.json` is a cargo ledger, not an archive format. The quartermaster checks it. |\n| CI | `.github/workflows/ci.yml` runs the gate on every push and pull request to `main`. |\n\n## What It Does Not Ship\n\n| Not aboard | Reason |\n|---|---|\n| Retired aliases | Break rename is intentional. Old names are barnacles — scrape them. |\n| CLI substitute for compression | Missing `ANTHROPIC_API_KEY` fails directly. Ghost oars cost maintenance and sometimes row toward prod. |\n| `.bao` archive builder | This pass counts barrels and checks labels only. No archive builder lurks below deck. |\n| Runtime TypeScript loader for hooks | Hooks run compiled JS. Ship does not stop to compile at dawn. |\n| Registry gate inside CI | `checkNpmRegistry` fails once a version exists in the registry. That is publish-time truth, not pull-request truth, so CI leaves it on the dock. |\n\n
\n日本語 README\n\n# PirateBao\n\nPirateBao は Bun-first / TypeScript-first の海賊リグです。AI コーディング返答から挨拶の泡、遠慮の霧、謝罪のフジツボを斬り捨てます。コード、コマンド、パス、バージョン、危険、スタックトレース、テスト結果はマストに釘打ちます。クラーケンは boilerplate を食べ、`TypeError` は残します。オウムは騒ぐ。token は金貨。礼儀に銀貨を払う船長はおらぬ。\n\n## 5歳向け説明\n\nAI は宝箱の前で長々と挨拶し、地図を三度読み直し、甲板を磨いて磨いて磨きがちです。PirateBao は泡を海に捨て、宝だけマストに残します: コマンド、ファイル、バグ、修正。金貨で霧を買わぬ。海賊は礼儀に銀を払わぬ。\n\n```mermaid\nflowchart LR\n A[\"長い返答\"] --> B[\"前置きを捨てる\"]\n B --> C[\"短い技術返答\"]\n C --> D[\"token削減\"]\n D --> E[\"速い航海\"]\n```\n\n## 技術メモ\n\n| 項目 | 内容 |\n|---|---|\n| 既定の帆 | `kraken` |\n| 主要コマンド | `/piratebao`, `/piratebao:compress `, `/piratebao-help` |\n| 日本語モード | `nihon-skiff`, `nihon-brig`, `nihon-kraken` |\n| 検証 | `bun run check` が TypeScript、Vitest、`.bao`、OpenCode、npmjs dry-run を通す |\n| CI | `.github/workflows/ci.yml` が `main` への push と pull request で門を開く |\n| 積荷台帳 | `bao/piratebao.manifest.json` に README と OpenCode 積荷を載せる |\n\n```bash\nbun install --frozen-lockfile\nbun run check\n```\n\n船長向け結論: これは翻訳された飾りではなく、日本語の短縮モードと検証対象の README です。`nihon-kraken` は短く切る。`rm -rf` と `npm publish` の危険は切りすぎない。髑髏は少なめ、検証は多め。\n\n
\n\n
\nSchwiizerdütsch README\n\n# PirateBao\n\nPirateBao isch es Bun-first, TypeScript-first Pirat-Rigg für churzi AI-Coding-Antworte. Code, Befehle, Pfäd, Versione, Risiko, Stacktraces und Testresultat bliibe am Mascht feschtgnaglet. Begrüessigs-Schaum, Hättegli-Nebel und Entschuldigungsmuschele gönd über Bord — kielholt ohni Gnade. De Chrottekrake frisst Boilerplate, nöd Fehlermeldige. De Papagei chiflet; d token-Rechnig schrumpft. Höflichkeit isch Ballascht.\n\n## Für Chind erklärt\n\nAI redt mängisch hoi, list d Charte drüümal und poliert s Brett bis es nach Büro riecht. PirateBao seit: Ladig bhalte, Blabla ab is Wasser. Tokens sind Münze; mir zahled nöd für Nebel mit Schnauz. De Hafemeister nickt; de Papagei chrächzt.\n\n```mermaid\nflowchart LR\n A[\"Langi Antwort\"] --> B[\"Blabla usem Logbuech streiche\"]\n B --> C[\"Kurzi Technik-Antwort\"]\n C --> D[\"weniger Tokens\"]\n D --> E[\"schnäller Hafe\"]\n```\n\n## Technik\n\n| Teil | Sinn |\n|---|---|\n| Standard-Segel | `kraken` |\n| Befehle | `/piratebao`, `/piratebao:compress `, `/piratebao-help` |\n| Schwiizerdütsch-Modi | `swiss-skiff`, `swiss-brig`, `swiss-kraken` |\n| Gate | `bun run check` prüeft TypeScript, Vitest, `.bao`, OpenCode und npmjs dry-run |\n| CI | `.github/workflows/ci.yml` lauft bi jedem push und pull request uf `main` |\n| Ladigslischte | `bao/piratebao.manifest.json` listet README und OpenCode-Fracht |\n\n```bash\nbun install --frozen-lockfile\nbun run check\n```\n\nKurz: kei lackierts Fass. Es isch e technischi README-Kopie mit eigenem Pirateton, Sprachmodi und Gate. `swiss-kraken` schneidet hart; bi Security, Publish und Dateverlust blibt er nüchtern. De Chäpten unterschriibt mit trockene Stiefel und em Schwert am Gurt.\n\n
\n\n## Install\n\nBun is the package manager of record. npm is used only where npmjs itself is the thing being tested, because even pirates respect the harbor office and its tiny clipboard of pain.\n\n| Harbor | Command | Checks |\n|---|---|---|\n| Install deps | `bun install --frozen-lockfile` | Uses `bun.lock`; fails if `package.json` drifted. |\n| Typecheck | `bun run typecheck` | `tsconfig.json` and `tsconfig.tests.json`, both `--noEmit`. |\n| Lint | `bun run biome` | Biome check over `src` and `tests`. |\n| Build | `bun run build` | Emits `dist/` JS, declarations, and source maps. |\n| Test | `bun run test` | Builds, packs `piratebao.skill`, runs Vitest. |\n| Verify all | `bun run verify` | Sync, `.bao`, OpenCode, stale-name scan, npm registry, npm pack dry-run. |\n| Complete gate | `bun run check` | Typecheck, lint, build, tests, verify, registry, pack dry-run. |\n| Post-publish bunx smoke | `bunx -p piratebao piratebao-verify` | Runs the npmjs binary from Bun's package runner after the crate exists in the registry. |\n\nAgent installs:\n\n| Agent | Install |\n|---|---|\n| Claude Code | `claude plugin marketplace add d4551/piratebao && claude plugin install piratebao@piratebao` |\n| Codex | Clone repo, open Codex, install local `plugins/piratebao` |\n| OpenCode | Clone repo; OpenCode reads `.opencode/skills/*/SKILL.md` and `.opencode/commands/*.md` |\n| Gemini CLI | `gemini extensions install https://github.com/d4551/piratebao` |\n| Cursor/Windsurf/Cline/Copilot | `npx skills add d4551/piratebao` |\n\nStandalone Claude Code hooks:\n\n```bash\nbun install --frozen-lockfile\nbun run build\nbash hooks/install.sh\n```\n\nUninstall:\n\n```bash\nbash hooks/uninstall.sh\n```\n\nWindows uses `hooks/install.ps1` and `hooks/uninstall.ps1` with the same contract.\n\n## Commands\n\n| Command | Loot |\n|---|---|\n| `/piratebao` | default `kraken` mode |\n| `/piratebao skiff` | light terse prose |\n| `/piratebao brig` | strong terse prose |\n| `/piratebao kraken` | maximum terse prose |\n| `/piratebao jade-skiff` | light classical Chinese terse mode |\n| `/piratebao jade-brig` | strong classical Chinese terse mode |\n| `/piratebao jade-kraken` | maximum classical Chinese terse mode |\n| `/piratebao nihon-skiff` | light Japanese terse mode |\n| `/piratebao nihon-brig` | strong Japanese terse mode |\n| `/piratebao nihon-kraken` | maximum Japanese terse mode |\n| `/piratebao swiss-skiff` | light Swiss German terse mode |\n| `/piratebao swiss-brig` | strong Swiss German terse mode |\n| `/piratebao swiss-kraken` | maximum Swiss German terse mode |\n| `/piratebao-commit` | terse Conventional Commit message |\n| `/piratebao-review` | one-line review findings |\n| `/piratebao:compress ` | compress natural-language memory file |\n| `/piratebao-help` | command card |\n| `$piratebao` | Codex skill trigger |\n\nDeactivate with `stop PirateBao` or `normal mode`.\n\nThe six command strings the `.bao` ledger tracks live in `src/config/pirateBaoCommands.ts`. Manifest drift against that file fails `verifyVersionSsot`, so the ledger cannot invent a command the code never answers.\n\n## Mode Matrix\n\n| Family | Modes | Output contract |\n|---|---|---|\n| English | `skiff`, `brig`, `kraken` | shorter prose, same technical payload, stricter ceiling as sail gets heavier |\n| Classical Chinese | `jade-skiff`, `jade-brig`, `jade-kraken` | terse classical Chinese phrasing, examples gated by token monotonicity |\n| Japanese | `nihon-skiff`, `nihon-brig`, `nihon-kraken` | Japanese terse mode with the same no-filler/no-self-reference rules |\n| Swiss German | `swiss-skiff`, `swiss-brig`, `swiss-kraken` | Swiss German terse mode with the same compression ceilings |\n\nWord ceilings from `skills/piratebao/SKILL.md`: `skiff` ≤45, `brig` ≤30, `kraken` ≤20. The jade/nihon/swiss families use sentence ceilings instead: skiff ≤2 short sentences, brig ≤1, kraken ≤1 fragment. `tests/evals.test.ts` re-counts every family's example with `js-tiktoken` and fails if a heavier sail somehow grows.\n\nConfig precedence for the default sail:\n\n```mermaid\nflowchart LR\n Env[\"PIRATEBAO_DEFAULT_MODE\"] --> Pick[\"chartDefaultSail\"]\n Cfg[\"~/.config/piratebao/config.json\"] --> Pick\n Fallback[\"built-in default\"] --> Pick\n Pick --> Mode[\"kraken unless overridden\"]\n```\n\nAll families forbid self-announcements like mode banners unless the user explicitly asks. PirateBao steers the ship; it does not give a speech from the crow's nest. The best compression is the sentence never emitted. The second best is the sentence that lost its adjectives at sea.\n\n## Repo Map\n\n```mermaid\nflowchart TD\n subgraph Canonical[\"Canonical sources — edit these\"]\n Skill[\"skills/*/SKILL.md\"]\n Rule[\"rules/piratebao-activate.md\"]\n Manifest[\"bao/piratebao.manifest.json\"]\n end\n subgraph Code[\"TypeScript — src/\"]\n Hooks[\"hooks/ — session + prompt + statusline\"]\n Dumpling[\"dumpling/ — compressor + seal\"]\n Shipyard[\"shipyard/ — sync, pack, verify\"]\n Evals[\"evals/ — token accounting\"]\n Cfg[\"config/ + constants/ + runtime/\"]\n end\n subgraph Generated[\"Generated — do not hand-edit\"]\n Copies[\".opencode/ .cursor/ .windsurf/ .clinerules/ plugins/\"]\n Dist[\"dist/\"]\n Zip[\"piratebao.skill\"]\n end\n Skill --> Copies\n Rule --> Copies\n Manifest --> Copies\n Code --> Dist\n Skill --> Zip\n Dist --> Gate[\"verifyHarbor\"]\n Copies --> Gate\n Zip --> Gate\n Manifest --> Gate\n```\n\n`dist/` is committed on purpose. `hooks/install.sh` can install without a clone by pulling compiled files straight from raw GitHub, so deleting compiled cargo from version control would strand every remote installer. `.github/workflows/sync-skill.yml` keeps it in step on `main`.\n\n## Runtime Flow\n\n```mermaid\nflowchart TD\n Prompt[\"agent prompt\"] --> Hook[\"readCaptainOrder\"]\n Hook --> Flag[\"~/.claude/.piratebao-active\"]\n Session[\"session start\"] --> Raise[\"raiseJollyRoger\"]\n Raise --> Skill[\"skills/piratebao/SKILL.md\"]\n Skill --> Filter[\"mode-specific rule filter\"]\n Filter --> Agent[\"agent context\"]\n Flag --> Status[\"paintStatusFlag\"]\n Status --> Badge[\"statusline badge PIRATEBAO:KRAKEN\"]\n```\n\n`SessionStart` loads the compiled hook and canonical skill once per invocation. `UserPromptSubmit` updates the mode flag. Statusline reads the flag and prints a small badge. This keeps startup work bounded; the ship does not inspect every barrel on each wave or bill you for barnacle inventory.\n\n## Shipyard Flow\n\n```mermaid\nflowchart TD\n Skill[\"skills/piratebao/SKILL.md\"] --> Sync[\"syncTreasureMap\"]\n Sync --> Copies[\"OpenCode/Cursor/Windsurf/Copilot/plugin copies\"]\n Skill --> Pack[\"packSkillCargo\"]\n Pack --> Zip[\"piratebao.skill\"]\n Schema[\"schemas/piratebao-bao-manifest.schema.json\"] --> Gate[\"verifyHarbor\"]\n Manifest[\"bao/piratebao.manifest.json\"] --> Gate\n Copies --> Gate\n Zip --> Gate\n Gate --> Release[\"npmjs-ready package\"]\n```\n\nCanonical files are edited once, then synced. `verifyHarbor` rejects copy drift, stale brand tokens, missing OpenCode cargo, malformed plugin manifests, missing compiled artifacts, wrong zip contents, and README drift. The quartermaster is boring on purpose; comedy belongs in prose, not package invariants. The gate has no sense of humor and no parrot.\n\nRun `bun run sync` after editing any canonical skill or rule file. `bun run verify` runs the same walk with `--check` and fails instead of writing.\n\n## End-to-End Gate\n\nUse this before publishing or after touching docs, skills, hooks, manifests, or compression logic:\n\n```bash\nbun install --frozen-lockfile\nbun run typecheck\nbun run build\nbun run test\nbun run verify\nbun run pack:dry\n```\n\nOr one rope for the whole rig:\n\n```bash\nbun run check\n```\n\n```mermaid\nflowchart LR\n TC[\"typecheck\"] --> LN[\"biome\"]\n LN --> BD[\"build\"]\n BD --> PK[\"packSkillCargo\"]\n PK --> VT[\"vitest\"]\n VT --> SY[\"sync --check\"]\n SY --> VH[\"verifyHarbor\"]\n VH --> RG[\"checkNpmRegistry\"]\n RG --> DR[\"npm pack --dry-run\"]\n```\n\nCI runs every step of that chain except `checkNpmRegistry`. That gate fails by design once a version already exists on npmjs, which is correct at publish time and wrong on a pull request, so it sails only in `bun run check` and `.github/workflows/publish.yml`.\n\n| Workflow | Trigger | Job |\n|---|---|---|\n| `.github/workflows/ci.yml` | push + pull request on `main` | typecheck, lint, build, Chromium, tests, sync check, harbor verify, pack dry-run |\n| `.github/workflows/sync-skill.yml` | push on `main` touching canonical files | rebuilds, syncs copies, commits drift back |\n| `.github/workflows/publish.yml` | tag `v*` | full verify chain plus `npm publish --access public` |\n\nRuntime smoke for standalone Claude Code hooks:\n\n```bash\ntmp_home=\"$(mktemp -d)\"\nHOME=\"$tmp_home\" bash hooks/install.sh --force\nHOME=\"$tmp_home\" node \"$tmp_home/.claude/hooks/piratebao-dist/hooks/raiseJollyRoger.js\"\nprintf '{\"prompt\":\"/piratebao swiss-kraken\"}' | HOME=\"$tmp_home\" node \"$tmp_home/.claude/hooks/piratebao-dist/hooks/readCaptainOrder.js\"\ncat \"$tmp_home/.claude/.piratebao-active\"\nHOME=\"$tmp_home\" bash hooks/uninstall.sh\nrm -rf \"$tmp_home\"\n```\n\nExpected smoke result: install succeeds, session hook emits PirateBao rules, prompt hook writes `swiss-kraken`, uninstall removes hook cargo. No bottle note required.\n\n## Tests\n\nEight Vitest files, forty tests, no live model calls. The only shell-out is the npm publish dry-run inside `verifyHarbor`, which `tests/publicSurface.test.ts` exercises for real.\n\n| File | Cargo checked |\n|---|---|\n| `tests/decodeJson.test.ts` | typed JSON decoding boundary; no raw parse in shipping code |\n| `tests/docs.browser.test.ts` | real headless Chromium against `docs/`: hero, stylesheet, clipboard, toggles, clean console |\n| `tests/dumpling.test.ts` | prose-vs-code detection, fence stripping, and every committed compressor scroll in `tests/piratebao-compress/` |\n| `tests/evals.test.ts` | locks the 77%/68% snapshot gate and mode-example token monotonicity |\n| `tests/hooks.test.ts` | session/prompt hooks, mode flag writes, statusline badge |\n| `tests/publicSurface.test.ts` | exported config surface plus a live `verifyHarbor()` run |\n| `tests/shipyard.test.ts` | `.bao` shape, deterministic zip, OpenCode cargo, sync targets |\n| `tests/wireClaudeSettings.test.ts` | Claude settings wiring without `JSON.parse` in shell |\n\n`tests/piratebao-compress/` holds real compressor output: each `.original.md` and its compressed `.md`. The suite feeds every pair to `sealBaoScroll` and fails on any lost code block, URL, or heading, then checks the pair still saves at least 20% of its tokens. Fixtures that stop compressing, or start eating cargo, get caught.\n\nThe browser test needs a Chromium build. Provision one with `bunx playwright install chromium`, or point `PIRATEBAO_CHROMIUM_PATH` at an existing binary. With no Chromium anywhere the suite skips instead of failing, so a clone without browsers still runs the rest of the gate — CI installs Chromium so the docs surface is genuinely exercised there.\n\n## OpenCode Native Support\n\nOpenCode support is project-native:\n\n| File | Purpose |\n|---|---|\n| `opencode.json` | Points OpenCode at `AGENTS.md` and allows `piratebao*` skills. |\n| `.opencode/skills/piratebao/SKILL.md` | Synced main skill. |\n| `.opencode/skills/piratebao-commit/SKILL.md` | Synced commit skill. |\n| `.opencode/skills/piratebao-review/SKILL.md` | Synced review skill. |\n| `.opencode/skills/piratebao-help/SKILL.md` | Synced help skill. |\n| `.opencode/skills/piratebao-compress/SKILL.md` | Synced compressor skill. |\n| `.opencode/commands/piratebao.md` | `/piratebao` command template. |\n| `.opencode/commands/piratebao-commit.md` | Platform-safe `/piratebao-commit`; uses `$ARGUMENTS`. |\n| `.opencode/commands/piratebao-review.md` | Platform-safe `/piratebao-review`; uses `$ARGUMENTS`. |\n| `.opencode/commands/piratebao-help.md` | Platform-safe `/piratebao-help`. |\n| `.opencode/commands/piratebao-compress.md` | Platform-safe compress command; uses `$ARGUMENTS`. |\n\nCommand filenames avoid `:` for cross-platform safety. Frontmatter descriptions are verified. This is not a TypeScript OpenCode plugin; no extra runtime hook hides in the bilge wearing a false moustache.\n\n## TypeScript Rig\n\nPinned current stack, verified on 2026-08-04:\n\n| Tool | Version | Role |\n|---|---|---|\n| Bun | `1.3.14` | install/scripts; lockfile authority |\n| TypeScript | `7.0.2` | strict compile for `src/` and tests |\n| Node | `>=24.11.0` | runtime target for compiled hooks/CLIs |\n| Biome | `2.5.4` | lint/format gate |\n| Vitest | `4.1.10` | behavior tests |\n| Playwright | `1.61.1` | docs browser contract |\n| AJV | `8.20.0` | `.bao` schema validation |\n| Anthropic SDK | `0.112.1` | compressor API client |\n| js-tiktoken | `1.0.21` | token evals |\n\nCompiler flags are strict on purpose: `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, and `skipLibCheck: false`. Biome bans `any`, `@ts-ignore`, and non-null assertions.\n\nNo direct env reads outside config modules. No `any` in implementation/tests. No TypeScript suppressions. If the mast cracks, the compiler gets first complaint, not a postmortem parrot. Types are the rigging; if they fray, the sail falls before the wind arrives.\n\n## `.bao` Contract\n\nPirateBao validates manifest contract. `.bao` is cargo ledger, not archive chest. The verifier counts barrels, then complains like a sober quartermaster.\n\n| Item | Path |\n|---|---|\n| schema | `schemas/piratebao-bao-manifest.schema.json` |\n| manifest | `bao/piratebao.manifest.json` |\n| validator | `src/shipyard/validateBaoChest.ts` |\n| full gate | `src/shipyard/verifyHarbor.ts` |\n| OpenCode cargo | `.opencode/skills/*/SKILL.md` + `.opencode/commands/*.md` |\n| spec | `BAO-MANIFEST-SPEC.md` |\n\nGate checks manifest schema, key order, referenced files, README inclusion, synced skill copies, OpenCode files, plugin metadata, stale brand tokens, compiled artifacts, shell scripts, npmjs package files, and `piratebao.skill` contents.\n\n```mermaid\nflowchart LR\n M[\"manifest\"] --> S[\"schema validate\"]\n S --> F[\"referenced files exist\"]\n F --> O[\"OpenCode cargo present\"]\n O --> Z[\"zip contains piratebao/SKILL.md\"]\n Z --> P[\"package files checked\"]\n P --> OK[\"ship\"]\n```\n\nThe ledger is also the sync map. `syncedCopies` names each canonical source and every copy it owns, with optional frontmatter prefixes for Cursor and Windsurf. Add a copy there and `bun run sync` starts maintaining it; forget to list it and `verifyHarbor` says so.\n\n## npmjs Package\n\nPackage name: `piratebao`. Registry gate checks availability before publish. npm dry-run checks payload, not vibes. The harbor rejects imaginary treasure; the verifier checks labels before the crate reaches the dock. Painted barrels without rum get thrown back.\n\nRequired npmjs fields are set: named `exports` only (no `main`/`types`/`\".\"`), plus `bin`, `files`, `license`, `repository`, `bugs`, `publishConfig`, `packageManager`.\n\n| Export | Compiled entry |\n|---|---|\n| `piratebao/hooks` | `dist/hooks/raiseJollyRoger.js` |\n| `piratebao/dumpling` | `dist/dumpling/stuffDumpling.js` |\n| `piratebao/shipyard` | `dist/shipyard/verifyHarbor.js` |\n| `piratebao/config` | `dist/config/captainConfig.js` |\n| `piratebao/decode-json` | `dist/runtime/decodeJson.js` |\n\n| Binary | Job |\n|---|---|\n| `piratebao-compress` | compress a natural-language memory file |\n| `piratebao-pack` | rebuild `piratebao.skill` |\n| `piratebao-registry` | check npmjs name/version availability |\n| `piratebao-sync` | refresh synced skill/rule copies |\n| `piratebao-verify` | run the harbor gate |\n\nDry-run before publish:\n\n```bash\nbun run check\n```\n\nPost-publish binary smoke:\n\n```bash\nbunx -p piratebao piratebao-verify\nnpx -p piratebao piratebao-verify\n```\n\nUse `-p piratebao` because the npm package is `piratebao` while the binary names are specific tools like `piratebao-verify` and `piratebao-compress`. That is not a riddle; it is just npm making the plank longer.\n\n`package.json` `files` includes README, `.bao` manifest/schema cargo, OpenCode files, agent plugin files, compiled `dist/`, shell hooks, and `piratebao.skill`. Painted barrels without files fail verification. CLI `bin` entries use npm-normalized paths and shebang-bearing JS so npm does not quietly saw the rudder off during publish dry-run.\n\n## Compressor\n\n`/piratebao:compress ` is for natural-language memory files: agent notes, project instructions, todos, and preference docs. It preserves code blocks, inline code, URLs, paths, headings, commands, versions, and proper nouns. It removes prose barnacles, not your mast. If a paragraph is mostly velvet rope, it becomes rope.\n\nSet:\n\n```bash\nexport ANTHROPIC_API_KEY=...\nexport PIRATEBAO_MODEL=claude-sonnet-4-5-20250929\n```\n\nNo CLI substitute. Missing key fails with direct error. No ghost oar under the floorboards, no mystery subprocess paddling toward a rate limit.\n\n```mermaid\nflowchart TD\n File[\"memory file\"] --> Detect[\"inspectFilling\"]\n Detect -->|prose| Call[\"Anthropic Messages API\"]\n Detect -->|code/config| Skip[\"skip\"]\n Call --> Backup[\"write .original.md\"]\n Backup --> Validate[\"sealBaoScroll\"]\n Validate -->|ok| Done[\"compressed file\"]\n Validate -->|bad| Fix[\"targeted fix prompt\"]\n Fix --> Validate\n```\n\n`sealBaoScroll` is the honest part. Heading-count drift and any changed code block or lost URL are errors. Changed path sets and large bullet swings are warnings. A compressor that quietly eats a stack trace is not a compressor; it is a leak with a hat.\n\n## Docs Site\n\n`docs/` is a dependency-free static page for GitHub Pages: `index.html`, `piratebao.css`, `favicon.svg`, and `.nojekyll`. Inline `