Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

The dev skill loads progressively, and states when tests move off this machine (#647)

Yaowei Zheng7739d94ac8f3
diff --git a/.agents/scripts/remote-test.sh b/.agents/scripts/remote-test.sh
new file mode 100755
index 00000000..995c9783
--- /dev/null
+++ b/.agents/scripts/remote-test.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Run a package's tests on another machine, when the user has asked for that.
+#
+# PENGUIN_TEST_HOST=<ssh-destination> \
+# .agents/scripts/remote-test.sh <worktree> [--build "<pkg> <pkg>"] -- <pnpm args...>
+#
+# PENGUIN_TEST_HOST=box .agents/scripts/remote-test.sh . -- --filter @prismshadow/penguin-web test
+# PENGUIN_TEST_HOST=box .agents/scripts/remote-test.sh ~/dev/penguin-harness-wt/foo \
+# --build "@prismshadow/penguin-core @prismshadow/penguin-server" -- \
+# --filter @prismshadow/penguin-cli exec vitest run test/agent-porting.test.ts
+#
+# Tests run on the developer's own machine by default; this script exists for the times the user
+# asks for a different one, and it is never the automatic choice. The destination comes from the
+# environment — an ssh alias or user@host that the caller's ssh config already resolves — because
+# the address belongs to whoever runs this, not to the repository.
+#
+# It syncs sources only (node_modules, dist and .git stay behind and the remote rebuilds its own),
+# installs with the frozen lockfile, optionally builds the packages whose dist the suite reads,
+# then runs pnpm there. A remote result describes the remote environment: when it disagrees with a
+# local run, that disagreement is the finding.
+set -euo pipefail
+
+usage() { sed -n '2,18p' "$0"; exit 2; }
+
+HOST="${PENGUIN_TEST_HOST:-}"
+[ -n "$HOST" ] || { echo "PENGUIN_TEST_HOST is unset: pass the ssh destination to use." >&2; exit 2; }
+
+[ $# -ge 1 ] || usage
+WORKTREE=$(cd "$1" && pwd) || usage
+shift
+BUILD_FILTERS=""
+if [ "${1:-}" = "--build" ]; then
+ BUILD_FILTERS="$2"
+ shift 2
+fi
+[ "${1:-}" = "--" ] || usage
+shift
+[ $# -ge 1 ] || usage
+
+NAME=$(basename "$WORKTREE")
+# Resolved once, then used absolute everywhere: rsync does not expand `$HOME` in a remote
+# destination, and a `~` inside double quotes is not expanded by the remote shell either — either
+# spelling silently creates a directory literally named after the variable.
+REMOTE_HOME=$(ssh "$HOST" 'printf %s "$HOME"')
+REMOTE="$REMOTE_HOME/penguin-remote-test/$NAME"
+
+echo "== sync $NAME -> $HOST:$REMOTE =="
+ssh "$HOST" "mkdir -p '$REMOTE'"
+# --delete keeps a file left by an earlier run out of the suite; the excludes are what the remote
+# rebuilds for itself, and shipping them would be both slower and wrong.
+rsync -az --delete \
+ --exclude 'node_modules' --exclude 'dist' --exclude '.git' \
+ --exclude 'test-results' --exclude '.turbo' --exclude 'out' \
+ -e ssh "$WORKTREE/" "$HOST:$REMOTE/"
+
+# A non-login ssh shell sources no profile, so a version manager's Node and a corepack-installed
+# pnpm are both off PATH — `node -v` there can report a version below this repo's >=24 engine while
+# the intended one sits unloaded. Load them explicitly; both blocks are no-ops when absent.
+REMOTE_ENV='
+ if [ -s "$HOME/.nvm/nvm.sh" ]; then export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh" >/dev/null; fi
+ [ -d "$HOME/.local/bin" ] && export PATH="$HOME/.local/bin:$PATH";
+'
+
+# One core test resolves the checkout root beside pnpm-workspace.yaml. A worktree's .git is a
+# pointer file, so it is excluded above; an empty repository is cleaner than a dangling gitdir.
+ssh "$HOST" "$REMOTE_ENV cd '$REMOTE' && [ -e .git ] || git init -q"
+
+echo "== install =="
+ssh "$HOST" "$REMOTE_ENV cd '$REMOTE' && pnpm install --frozen-lockfile --reporter=silent"
+
+if [ -n "$BUILD_FILTERS" ]; then
+ echo "== build $BUILD_FILTERS =="
+ FILTER_ARGS=""
+ for f in $BUILD_FILTERS; do FILTER_ARGS="$FILTER_ARGS --filter $f"; done
+ # The flag goes BEFORE the command; after it, pnpm forwards it to the build script itself.
+ ssh "$HOST" "$REMOTE_ENV cd '$REMOTE' && pnpm --config.verify-deps-before-run=false $FILTER_ARGS build"
+fi
+
+echo "== pnpm $* =="
+ssh "$HOST" "$REMOTE_ENV cd '$REMOTE' && pnpm $*"
diff --git a/.agents/skills/penguin-harness-dev/SKILL.md b/.agents/skills/penguin-harness-dev/SKILL.md
index 1ef8bce9..bbb76040 100644
--- a/.agents/skills/penguin-harness-dev/SKILL.md
+++ b/.agents/skills/penguin-harness-dev/SKILL.md
@@ -1,33 +1,60 @@
---
name: penguin-harness-dev
-description: Use when developing PenguinHarness itself — changing packages/{core,server,web,cli,desktop,landing,docs,skills}, the built-in model catalog, the installers or the release workflow; writing or auditing changelog entries; writing a blog post or capturing release screenshots; deciding what to do about data already on disk; or auditing prose that reads like a leaked authoring session. Covers the two-repo symlink layout, the CI-parity verification chain, the record-and-ship contract, where blog media is hosted, and the seams that are intentional.
+description: Use when developing PenguinHarness itself — changing packages/{core,server,web,cli,desktop,landing,docs,skills}, the built-in model catalog, the installers or the release workflow; writing or auditing changelog entries; writing a blog post or capturing release screenshots; running the test suite here or, when asked, on another machine; deciding what to do about data already on disk; or auditing prose that reads like a leaked authoring session. Covers the two-repo symlink layout, the CI-parity verification chain, the record-and-ship contract, where blog media is hosted, and the seams that are intentional.
---
# Developing PenguinHarness
-PenguinHarness is a TypeScript monorepo: an Agent SDK (`packages/core`), an HTTP server (`packages/server`), a Web App (`packages/web`), a CLI (`packages/cli`), an Electron shell (`packages/desktop`), the landing and docs sites, and the shipped plugin library — one npm package per plugin under the repo root's `plugins/`, with `packages/plugins` as the loader that depends on them all. It **consumes** LLM providers through `@prismshadow/agenthub` and implements no provider clients of its own.
+PenguinHarness is a TypeScript monorepo: an Agent SDK (`packages/core`), an HTTP server
+(`packages/server`), a Web App (`packages/web`), a CLI (`packages/cli`), an Electron shell
+(`packages/desktop`), the landing and docs sites, and the shipped plugin library — one npm package
+per plugin under the repo root's `plugins/`, with `packages/plugins` as the loader that depends on
+them all. It **consumes** LLM providers through `@prismshadow/agenthub` and implements no provider
+clients of its own.
+
+This page is the part that applies to every change. Four reference files carry the detail, read
+them when the task reaches them:
+
+| Read | When |
+| --- | --- |
+| `reference/verification.md` | A test fails oddly, CI reads green when it should not, or the user asks you to run the suite on another machine |
+| `reference/changelog.md` | Writing or auditing a changelog entry |
+| `reference/model-catalog.md` | Touching `model-catalog.ts`, pricing, provider groups or glyphs |
+| `reference/authoring.md` | Writing a blog post, auditing prose, or proposing a simplification |
## Repo shape — read before your first edit
-Two repositories sit side by side: the implementation repo (`penguin-harness`) and the design repo (`penguin-harness-design`). Three paths inside the implementation repo are symlinks into the design repo and are gitignored here:
+Two repositories sit side by side: the implementation repo (`penguin-harness`) and the design repo
+(`penguin-harness-design`). Three paths inside the implementation repo are symlinks into the design
+repo and are gitignored here:
- `design/` → the design repo, so specs are reachable as `design/specs/…`
- `AGENTS.md` → `design/AGENTS.md`
- `CLAUDE.md` → `AGENTS.md`
-Editing `AGENTS.md`, `CLAUDE.md` or anything under `specs/` edits **the design repo's files**. Commit them there, on their own branch, in their own PR. They can never appear in an implementation-repo PR. A fresh clone has none of the three links; recreate them by hand.
+Editing `AGENTS.md`, `CLAUDE.md` or anything under `specs/` edits **the design repo's files**.
+Commit them there, on their own branch, in their own PR. They can never appear in an
+implementation-repo PR. A fresh clone has none of the three links; recreate them by hand.
-Both repos take changes through branch + PR against `main`, squash-merged. Do not push to `main`.
+Both repos take changes through branch + PR against `main`, squash-merged. Do not push to `main`,
+and `gh pr create --base main` — not `dev`, whatever a sibling repo does.
-Branches are `feat/<topic>`, `fix/<topic>`, `docs/<topic>` in both repos. Some older branches here read `docs-<topic>` instead: a remote branch literally named `docs` once held that ref namespace and made the slashed form unpushable. It is gone — if a push is ever rejected as a directory/file conflict again, `git ls-remote --heads origin` names the branch responsible.
+Branches are `feat/<topic>`, `fix/<topic>`, `docs/<topic>` in both repos. Some older branches here
+read `docs-<topic>` instead: a remote branch literally named `docs` once held that ref namespace and
+made the slashed form unpushable. It is gone — if a push is ever rejected as a directory/file
+conflict again, `git ls-remote --heads origin` names the branch responsible.
-Independent changes each get their own git worktree under `../penguin-harness-wt/<topic>/` so several can run in parallel.
+Independent changes each get their own git worktree under `../penguin-harness-wt/<topic>/` so
+several can run in parallel.
## Verify what you changed
Node must be >= 24. In each worktree, `pnpm install --frozen-lockfile` first.
-The full chain CI runs is `pnpm build`, `pnpm format:check`, `pnpm typecheck`, `pnpm test`, `sh scripts/test-installer.sh`. **Do not reach for `pnpm test` by reflex** — it is nine packages and ~2500 tests, minutes per run, and for a docs-only diff it proves nothing the narrow run does not. Pick the narrowest evidence that would actually fail for this change's regression:
+The full chain CI runs is `pnpm build`, `pnpm format:check`, `pnpm typecheck`, `pnpm test`,
+`sh scripts/test-installer.sh`. **Do not reach for `pnpm test` by reflex** — it is nine packages and
+~2500 tests, minutes per run, and for a docs-only diff it proves nothing the narrow run does not.
+Pick the narrowest evidence that would actually fail for this change's regression:
```sh
pnpm --filter @prismshadow/penguin-core exec vitest run test/model-catalog.test.ts # one file, ~1s
@@ -45,118 +72,45 @@ pnpm --filter @prismshadow/penguin-web test
| `package.json`, the lockfile, `pnpm-workspace.yaml` | `pnpm install --frozen-lockfile` + `pnpm build` |
| Installers, `release.yml` | `sh scripts/test-installer.sh` |
-Always cheap, always worth it: `git diff --check`, and `pnpm format` + `format:check` on any diff at all.
-
-Run the whole chain in exactly three cases: the change spans the repo widely enough that nothing narrower is credible, you are diagnosing a CI failure, or you are asked to. There are no coverage thresholds in this repo, so nothing forces a wider run than the behavior needs.
-
-`ci-windows` runs the same minus `format:check`, plus `scripts/test-installer.ps1`. Two failures there are known and are not your diff: a bare `Failed` worker crash, and an `environment.test.ts` truncation-timing assertion — rerun before debugging. An `EBUSY` on removing a directory that is some child process's cwd is real, not a flake.
+Always cheap, always worth it: `git diff --check`, and `pnpm format` + `format:check` on any diff at
+all.
-**A fake that is kinder than the real thing hides the bug it was written for.** Transports are faked at a seam here — `createSocket`, `createClient`, a stubbed `globalThis.fetch` — and the half that drifts is the failure contract, not the happy path. A fake that hands back a fresh cursor where the adapter returns the one it was given, or that resolves where production parks, passes a test whose subject is exactly that path. Write the fake's failure branches from the adapter's, not from what the assertions need.
+Run the whole chain in exactly three cases: the change spans the repo widely enough that nothing
+narrower is credible, you are diagnosing a CI failure, or you are asked to. There are no coverage
+thresholds in this repo, so nothing forces a wider run than the behavior needs.
-**A structural assertion that was already true at the base commit is not a test.** Reading source text in a test is house style here (20 web test files do it), which makes it easy to assert a shape the file already had. Replay each new assertion against `git show <base>:<path>` and keep the ones that fail there.
+**Tests run on this machine unless the user asks otherwise.** Moving a suite to another host is
+something they request in so many words, not an optimisation to take on your own — see
+`reference/verification.md` for how, and for why a difference between two machines is a finding
+rather than something to paper over.
-The local server suite drops a few tests under full parallel load — they time out and pass on their own. Rerun the file alone before blaming the diff.
+Once the evidence you chose passes, commit and push to the current branch without asking.
+Force-pushes and reverting someone else's commits still need confirmation.
-Once the evidence you chose passes, commit and push to the current branch without asking. Force-pushes and reverting someone else's commits still need confirmation.
-
-**On a conflicting PR, waiting for CI is waiting for nothing.** The workflows run against the merge commit GitHub builds from the branch and `main`, and it does not build one while the two conflict — the checks never start, so polling `statusCheckRollup` returns the same pending or empty list forever. Read the state before the checks: `gh pr view <n> --json mergeable,mergeStateStatus` answers `CONFLICTING` / `DIRTY`. Merge `origin/main` into the branch, resolve, push, and only then expect checks. Two more things that pass silently and are worth checking in the same pass: an auto-merged file is not a correct file, so read the merged result where two PRs touched one region; and a test constant pinned to a count the other PR changed fails for a reason that has nothing to do with either change — derive the count instead of re-pinning it.
+When a test fails in a way that does not match your diff, when CI reads green too easily, or when a
+fake or an assertion looks like it proves nothing, read `reference/verification.md` before spending
+a second round on it.
## Record and ship
-Every change ships a changelog entry, in both languages, in `changelog/unreleased/`:
-
-- `YYYY-MM-DD-<slug>.md` and `YYYY-MM-DD-<slug>.zh.md`, mirroring section for section. One without the other is unfinished.
-- H1, then the metadata block in fixed order — `Date` / `Type` / `Scope` / `PR` / `Issue` / `Breaking` — then the counterpart link, then a lead paragraph and bespoke sections. Field names and values stay English in both files so one `grep` covers the tree.
-- Omit an inapplicable field entirely. Placeholders are what stop `grep -rl 'Breaking:' changelog/` from being an exact query.
-- `Breaking` present ⇒ a `## Compatibility` / `## 兼容性` section stating what breaks and the migration step.
-- Section headings are translated, not carried across: `## Details` → `## 细节`, `## Compatibility` → `## 兼容性`, bespoke ones naturally, in the same order and count. An English heading in the `.zh.md` is the most common way the pair stops mirroring.
-
-`changelog/README.md` is the full spec. Read it rather than pattern-matching a neighbouring entry.
-
-**There is no index file.** Do not add one, and do not port the index step from agenthub's own workflow: the index was a single file every PR had to touch, which is precisely why it was deleted.
-
-**Reasoning does not go on disk.** No `## Why`, `## Problem`, `## Decision`, `## Alternatives considered`, `## Verification`, `## Risks`, and no claims about what the codebase currently *is*. The thinking is still required — report it in the conversation and write it into the PR description, which stays attached to its diff.
-
-**Numbers are links, and half of them are issues.** A bare `#N` does not render as a link in Markdown. Worse, this repository's bug reports and its PRs share one numbering space: `#83`, `#85`, `#102`, `#136`–`#140`, `#150`, `#170`, `#215`, `#218`, `#229`, `#239` are issues. Classify before writing — `gh api repos/Prism-Shadow/penguin-harness/issues/N --jq 'if .pull_request then "PR" else "ISSUE" end'` — and route them to `Issue`, not `PR`. A cross-repo reference names its repo: `agenthub [#162](https://github.com/Prism-Shadow/agenthub/pull/162)`.
-
-The PR number exists only once the PR is open: open it, then add the links in a follow-up commit on the same branch. `PR` is the field that actually gets forgotten — `grep -L 'PR:' changelog/unreleased/*.md` before asking for review.
-
-An entry ships **inside the PR that makes the change** — there is no separate aggregate PR. Released version folders are frozen. `RELEASE.md` is written at release preparation and must be committed **before** the tag — the workflow reads it from the tag's own checkout.
-
-## Blog posts, and where their images live
-
-A post is a pair under `packages/landing/content/blog/`: `<slug>.en.md` and `<slug>.zh.md`, each with `title` / `date` / `category` / `excerpt` frontmatter. Same rule as changelog entries — one without the other is unfinished.
-
-**The images are not in this repo.** Screenshots and demo videos live in the sibling `Prism-Shadow/penguin-harness-community` repo, under `blog-assets/` and `videos/`. A published post's screenshots are never deleted, so that asset class grows without bound in the number of posts written; keeping it out of this history keeps everyone's clone small.
-
-**Posts still write a repo-local path.** Reference an image as `/blog-assets/<name>` — both `![alt](…)` and the raw `<img src="…">` some posts use — and let the renderer resolve it: `blogAssetUrl` in `packages/landing/src/lib/links.ts`, applied by the `img` adapter in `src/pages/blog-post.tsx`. Never paste the raw `raw.githubusercontent` URL into a post. One source of truth for the host, Markdown that stays readable and diffable, and moving the host again is a one-line change instead of a sweep over every post.
-
-Release screenshots are captured, not mocked up: drive the app through the Playwright e2e harness in `packages/web/e2e/` with its mock LLM, against a scratch `PENGUIN_HOME` — never `~/.penguin`, which is the developer's real data. Shoot at `deviceScaleFactor: 2`, crop to the feature rather than the whole window, and check the frame for what must not ship publicly: absolute paths carrying a home directory, API keys, and mock-model filler text.
+Every change ships a changelog entry, in both languages, in `changelog/unreleased/`: a
+`YYYY-MM-DD-<slug>.md` and `YYYY-MM-DD-<slug>.zh.md` pair mirroring section for section, inside the
+PR that makes the change. One without the other is unfinished, **there is no index file**, and
+reasoning belongs in the PR description rather than on disk.
-## Changing the built-in model catalog
-
-`packages/core/src/state/model-catalog.ts` is the single source of truth for presets, shared by core's defaults, the server's initial config, and web/CLI display. It is a *catalog*, not a routing table — AgentHub owns routing.
-
-- Pricing is three buckets in USD per million tokens: `cache_read` (the vendor's cache-hit price), `cache_write` (the vendor's cache-write price, or the standard input price where the vendor charges no write premium), `output`. `cny(...)` converts official CNY list prices at the 7:1 display convention.
-- A vendor with **tiered** pricing gets its base tier recorded, and the tier boundary noted in the section comment — OpenAI above 272K input, Gemini 3.1 Pro above 200K, MiniMax M3 above 512K. Long-context use is then knowingly under-costed; that is the convention, not an oversight.
-- A **promotion** is a `discount` fraction beside the list `pricing`, never a discounted number written into `pricing`: `effectivePricing()` derives the billed rate, and a lapsed promotion is one field to delete with the rate to return to still on the row. `presetModelEntries()` writes the effective rate, so what a Project stores is what the gateway charges.
-- A **time-based** tier is an `offPeakDiscount` schedule instead, and it is never baked into a Project. The row stores its peak price, and the cost center decides the tier from each usage record's own `ts` — the aggregation splits by tier before pricing. Deciding it at read time instead would move a finished week's cost every time the boundary passed.
-- Uniqueness is the `(provider, model_id)` pair, never the bare id — gateways resell vendor models under their upstream ids.
-- Set `client_type` only when the id cannot be auto-routed or a protocol must be pinned, and inline `baseUrl` with it. Everything else is auto-routed by AgentHub.
-- A provider group is split only when the vendor genuinely has separate endpoints or billing paths (Qwen Token Plan vs Pay-As-You-Go). One endpoint serving several key types is one group.
-- `resolveModelEnv` mirrors AgentHub's exact routing; a lookalike id must stay unroutable.
-- Adding a model touches the catalog test's exact-order assertions, `packages/web/src/features/models/protocol-path.ts` when the client's request path is not `/chat/completions`, the provider glyph map, and the bilingual `models` / `configuration` docs.
-- **Moving the default reaches further than adding a model.** `defaultProjectConfig()` in `packages/core/src/state/project-config.ts` holds it, and six documented first-run commands pin it by hand — `README.md`, `README.zh.md`, and `quickstart-cli` / `quickstart-sdk` in both languages — each ending `--set-default`, which writes `default_model`. Leave them on the old id and the documented first run silently undoes the change on every fresh install. The `models` and `configuration` samples carry it in two places that must move together, the `default_model` line and the `[[models]]` row it names (a default naming no entry is rejected on load), and `plugins/agent-development/skills/penguin-sdk/SKILL.md` states it in prose.
-
-Existing Projects never migrate automatically: presets are copied into `.project_config.toml` at creation and nothing rewrites them. Users pick changes up through the models page's explicit "sync presets", which appends and updates catalog-owned fields but never deletes and never touches the stored default. Say so in the entry.
+`changelog/README.md` is the full spec and `reference/changelog.md` has the shape plus the traps
+(the metadata block's fixed order, translated headings, `#N` numbers that are often issues rather
+than PRs, and the `PR:` field everyone forgets). Read one of them before writing an entry rather
+than pattern-matching a neighbouring one.
## Backward compatibility is the user's call, not yours
-When a change touches data or configuration already on disk — Traces, `system_config.yaml`, `.project_config.toml`, installed skills, `web.db`, localStorage keys — do not pick a strategy. State plainly what breaks if nothing is done, offer the options (permanent dual-format tolerance / one-time migration / a documented reset path / accept the break and say so), and let the user decide.
-
-Whatever is decided, compatibility code is a standing cost: name **how long it stays, who removes it, and what has to be true first**, at the code site and in a dedicated `changelog/unreleased/YYYY-MM-DD-backward-compatibility.md`. Other entries in that batch reference that file instead of re-telling it. A batch with no compatibility handling has no such file.
-
-## Prose that survives the session
-
-Comments, JSDoc, docs and changelog entries are read by people who have no access to the session that produced them. Apply one test to any suspect passage:
-
-> Could a reader at HEAD, with no session transcript and no uncommitted draft, resolve every reference and verify every claim?
-
-If not, keep the surviving facts and delete the rest. What to hunt:
-
-- **Dead citations** — design-session decision numbers, `§N` of an uncommitted draft, audit item codes. This repo already swept design-doc citations out of code comments once; do not reintroduce them.
-- **Stack and review vantage** — "a later PR in this stack", "rejected in review", "the reviewer confirmed". State the shipped mechanism; drop the choreography.
-- **Change narration** — "used to", "no longer", "this cut". A comment describes what the code does now. A changelog entry describes what the change did, in past tense — that is the one place narration is correct.
-- **Reviewer-addressed justification** — defensive paragraphs arguing a choice was fine. State the invariant, or delete.
-- **Hedged planning residue** — "probably fine for now". Promote to a real `TODO` with a name, or replace with the actual bound.
-- **Authoring-language slips** — untranslated fragments. Non-i18n code and developer docs are English-only; Chinese belongs in i18n catalogs, `*.zh.md` documents, and tests asserting CJK behavior.
-
-Keep, deliberately: issue and merged-PR links, suppression justifications, counterfactual-present statements ("without this, X happens"), measured bounds and the numbers behind them, and lifecycle descriptions of runtime behavior.
-
-## Proposing simplifications
-
-A simplification needs evidence, not taste. Strong cases: a public method, event, config knob, helper or package with **no production consumer** (`packages/*/src`, `examples`, `scripts` — tests and docs do not count); two representations mirroring one fact; hand-rolled code a maintained dependency or Node builtin already covers; defensive machinery guarding an unused API.
-
-Do not propose it when a production caller exists (that is a feature decision), when the removal forces unrelated churn without shrinking any public surface, or when the defensive pattern protects a load-bearing invariant. Correct but tiny belongs in a named `TODO(<smell>)`, not a proposal.
-
-Seams that are intentional here — collapsing one is a product decision, not cleanup:
-
-- the AgentHub boundary: PenguinHarness pins protocols and env fallback, AgentHub owns clients and routing;
-- `packages/core/src/internal/` versus what the package barrel exports — the public SDK surface is a contract;
-- the Trace on-disk format and its tolerant readers;
-- the bilingual documentation pairs and the i18n catalogs;
-- `desktop` running the *unchanged* server and Web App.
-
-Prove consumers with `rg` over exact symbols, event names and wire strings, and read the call sites. There is no `knip` here, and no Agent Note tree — a proposal lives in the PR description or an issue.
-
-## What this repo is not
-
-Imported wholesale from a sibling repo's workflow, these are wrong here:
+When a change touches data or configuration already on disk — Traces, `system_config.yaml`,
+`.project_config.toml`, installed skills, `web.db`, localStorage keys — do not pick a strategy.
+State plainly what breaks if nothing is done, offer the options (permanent dual-format tolerance /
+one-time migration / a documented reset path / accept the break and say so), and let the user decide.
-- **Provider-client development.** No vendor doc syncing, no live API captures, no paired Python/TypeScript clients, no `AVAILABLE_MODELS`. That is agenthub's work; PenguinHarness only records presets in its catalog.
-- **Changelog index files.** Deleted on purpose. See above.
-- **`gh pr create --base dev`.** The base branch is `main`.
-- **Agent Notes** (`.agents/notes/<lifecycle>/<class>/…`) and their supersession lifecycle. No such convention.
-- **`knip`, `pnpm run doc-sync`, `pnpm run lint`.** None exist; the real chain is the one above.
-- **Coverage-scoped verification** (`--coverage.include`, per-file thresholds). No coverage gate is configured here, so narrowing means choosing test files, not proving coverage over a source scope.
-- **Adding a skill to the repo root's `plugins/`** because it is "a skill". Those packages are the shipped, user-facing plugin library — a docs-sync test requires every plugin to appear in the bilingual skills pages, the README tables are test-checked, and everything there installs into users' agents. Repo development skills live in `.agents/skills/`.
+Whatever is decided, compatibility code is a standing cost: name **how long it stays, who removes
+it, and what has to be true first**, at the code site and in a dedicated
+`changelog/unreleased/YYYY-MM-DD-backward-compatibility.md`. Other entries in that batch reference
+that file instead of re-telling it. A batch with no compatibility handling has no such file.
diff --git a/.agents/skills/penguin-harness-dev/reference/authoring.md b/.agents/skills/penguin-harness-dev/reference/authoring.md
new file mode 100644
index 00000000..a7b8c712
--- /dev/null
+++ b/.agents/skills/penguin-harness-dev/reference/authoring.md
@@ -0,0 +1,105 @@
+# Authoring: blog posts, prose hygiene, and proposing simplifications
+
+Loaded on demand from `SKILL.md`. Three things that come up when you are writing rather than
+changing behavior.
+
+## Blog posts, and where their images live
+
+A post is a pair under `packages/landing/content/blog/`: `<slug>.en.md` and `<slug>.zh.md`, each
+with `title` / `date` / `category` / `excerpt` frontmatter. Same rule as changelog entries — one
+without the other is unfinished.
+
+**The images are not in this repo.** Screenshots and demo videos live in the sibling
+`Prism-Shadow/penguin-harness-community` repo, under `blog-assets/` and `videos/`. A published
+post's screenshots are never deleted, so that asset class grows without bound in the number of
+posts written; keeping it out of this history keeps everyone's clone small.
+
+**Posts still write a repo-local path.** Reference an image as `/blog-assets/<name>` — both
+`![alt](…)` and the raw `<img src="…">` some posts use — and let the renderer resolve it:
+`blogAssetUrl` in `packages/landing/src/lib/links.ts`, applied by the `img` adapter in
+`src/pages/blog-post.tsx`. Never paste the raw `raw.githubusercontent` URL into a post. One source
+of truth for the host, Markdown that stays readable and diffable, and moving the host again is a
+one-line change instead of a sweep over every post.
+
+Release screenshots are captured, not mocked up: drive the app through the Playwright e2e harness
+in `packages/web/e2e/` with its mock LLM, against a scratch `PENGUIN_HOME` — never `~/.penguin`,
+which is the developer's real data. Shoot at `deviceScaleFactor: 2`, crop to the feature rather
+than the whole window, and check the frame for what must not ship publicly: absolute paths carrying
+a home directory, API keys, and mock-model filler text.
+
+## Prose that survives the session
+
+Comments, JSDoc, docs and changelog entries are read by people who have no access to the session
+that produced them. Apply one test to any suspect passage:
+
+> Could a reader at HEAD, with no session transcript and no uncommitted draft, resolve every
+> reference and verify every claim?
+
+If not, keep the surviving facts and delete the rest. What to hunt:
+
+- **Dead citations** — design-session decision numbers, `§N` of an uncommitted draft, audit item
+ codes. This repo already swept design-doc citations out of code comments once; do not reintroduce
+ them.
+- **Stack and review vantage** — "a later PR in this stack", "rejected in review", "the reviewer
+ confirmed". State the shipped mechanism; drop the choreography.
+- **Change narration** — "used to", "no longer", "this cut". A comment describes what the code does
+ now. A changelog entry describes what the change did, in past tense — that is the one place
+ narration is correct.
+- **Reviewer-addressed justification** — defensive paragraphs arguing a choice was fine. State the
+ invariant, or delete.
+- **Hedged planning residue** — "probably fine for now". Promote to a real `TODO` with a name, or
+ replace with the actual bound.
+- **Authoring-language slips** — untranslated fragments. Non-i18n code and developer docs are
+ English-only; Chinese belongs in i18n catalogs, `*.zh.md` documents, and tests asserting CJK
+ behavior.
+
+Keep, deliberately: issue and merged-PR links, suppression justifications, counterfactual-present
+statements ("without this, X happens"), measured bounds and the numbers behind them, and lifecycle
+descriptions of runtime behavior.
+
+**A comment that contradicts the code is worse than no comment.** When a change reverses a decision
+the surrounding prose argues for, rewrite that prose in the same commit — the next reader trusts
+whichever of the two they happen to read first.
+
+## Proposing simplifications
+
+A simplification needs evidence, not taste. Strong cases: a public method, event, config knob,
+helper or package with **no production consumer** (`packages/*/src`, `examples`, `scripts` — tests
+and docs do not count); two representations mirroring one fact; hand-rolled code a maintained
+dependency or Node builtin already covers; defensive machinery guarding an unused API.
+
+Do not propose it when a production caller exists (that is a feature decision), when the removal
+forces unrelated churn without shrinking any public surface, or when the defensive pattern protects
+a load-bearing invariant. Correct but tiny belongs in a named `TODO(<smell>)`, not a proposal.
+
+Seams that are intentional here — collapsing one is a product decision, not cleanup:
+
+- the AgentHub boundary: PenguinHarness pins protocols and env fallback, AgentHub owns clients and
+ routing;
+- `packages/core/src/internal/` versus what the package barrel exports — the public SDK surface is
+ a contract;
+- the Trace on-disk format and its tolerant readers;
+- the bilingual documentation pairs and the i18n catalogs;
+- `desktop` running the *unchanged* server and Web App;
+- `message-window.ts` mirroring `stream-model.ts` — the file's own job is to reproduce that
+ accumulation for the pre-window prefix, and its tests pin the shared cases on both sides.
+
+Prove consumers with `rg` over exact symbols, event names and wire strings, and read the call sites.
+There is no `knip` here, and no Agent Note tree — a proposal lives in the PR description or an issue.
+
+## What this repo is not
+
+Imported wholesale from a sibling repo's workflow, these are wrong here:
+
+- **Provider-client development.** No vendor doc syncing, no live API captures, no paired
+ Python/TypeScript clients, no `AVAILABLE_MODELS`. That is agenthub's work; PenguinHarness only
+ records presets in its catalog.
+- **Agent Notes** (`.agents/notes/<lifecycle>/<class>/…`) and their supersession lifecycle. No such
+ convention.
+- **`knip`, `pnpm run doc-sync`, `pnpm run lint`.** None exist.
+- **Coverage-scoped verification** (`--coverage.include`, per-file thresholds). No coverage gate is
+ configured here, so narrowing means choosing test files, not proving coverage over a source scope.
+- **Adding a skill to the repo root's `plugins/`** because it is "a skill". Those packages are the
+ shipped, user-facing plugin library — a docs-sync test requires every plugin to appear in the
+ bilingual skills pages, the README tables are test-checked, and everything there installs into
+ users' agents. Repo development skills live in `.agents/skills/`.
diff --git a/.agents/skills/penguin-harness-dev/reference/changelog.md b/.agents/skills/penguin-harness-dev/reference/changelog.md
new file mode 100644
index 00000000..242dfe28
--- /dev/null
+++ b/.agents/skills/penguin-harness-dev/reference/changelog.md
@@ -0,0 +1,49 @@
+# The changelog contract
+
+Loaded on demand from `SKILL.md`, which states the rule: every change ships a bilingual entry in
+`changelog/unreleased/`, inside the PR that makes the change. This file is the shape of that
+entry and the traps around it. `changelog/README.md` is the full spec — read it rather than
+pattern-matching a neighbouring entry.
+
+## The pair
+
+- `YYYY-MM-DD-<slug>.md` and `YYYY-MM-DD-<slug>.zh.md`, mirroring section for section. One
+ without the other is unfinished.
+- H1, then the metadata block in fixed order — `Date` / `Type` / `Scope` / `PR` / `Issue` /
+ `Breaking` — then the counterpart link, then a lead paragraph and bespoke sections. Field names
+ and values stay English in both files so one `grep` covers the tree.
+- Omit an inapplicable field entirely. Placeholders are what stop `grep -rl 'Breaking:'
+ changelog/` from being an exact query.
+- `Breaking` present ⇒ a `## Compatibility` / `## 兼容性` section stating what breaks and the
+ migration step.
+- Section headings are translated, not carried across: `## Details` → `## 细节`, `## Compatibility`
+ → `## 兼容性`, bespoke ones naturally, in the same order and count. An English heading in the
+ `.zh.md` is the most common way the pair stops mirroring.
+
+## Rules that are easy to break
+
+**There is no index file.** Do not add one, and do not port the index step from agenthub's own
+workflow: the index was a single file every PR had to touch, which is precisely why it was deleted.
+
+**Reasoning does not go on disk.** No `## Why`, `## Problem`, `## Decision`, `## Alternatives
+considered`, `## Verification`, `## Risks`, and no claims about what the codebase currently *is*.
+The thinking is still required — report it in the conversation and write it into the PR
+description, which stays attached to its diff.
+
+**Numbers are links, and half of them are issues.** A bare `#N` does not render as a link in
+Markdown. Worse, this repository's bug reports and its PRs share one numbering space: `#83`, `#85`,
+`#102`, `#136`–`#140`, `#150`, `#170`, `#215`, `#218`, `#229`, `#239` are issues. Classify before
+writing — `gh api repos/Prism-Shadow/penguin-harness/issues/N --jq 'if .pull_request then "PR" else
+"ISSUE" end'` — and route them to `Issue`, not `PR`. A cross-repo reference names its repo:
+`agenthub [#162](https://github.com/Prism-Shadow/agenthub/pull/162)`.
+
+The PR number exists only once the PR is open: open it, then add the links in a follow-up commit on
+the same branch. `PR` is the field that actually gets forgotten — `grep -L 'PR:'
+changelog/unreleased/*.md` before asking for review.
+
+## Release mechanics
+
+An entry ships **inside the PR that makes the change** — there is no separate aggregate PR.
+Released version folders are frozen. `RELEASE.md` is written at release preparation and must be
+committed **before** the tag: the workflow reads it from the tag's own checkout, so a file added
+afterwards never reaches the Release page.
diff --git a/.agents/skills/penguin-harness-dev/reference/model-catalog.md b/.agents/skills/penguin-harness-dev/reference/model-catalog.md
new file mode 100644
index 00000000..e9f88e3b
--- /dev/null
+++ b/.agents/skills/penguin-harness-dev/reference/model-catalog.md
@@ -0,0 +1,61 @@
+# Changing the built-in model catalog
+
+Loaded on demand from `SKILL.md`. `packages/core/src/state/model-catalog.ts` is the single source
+of truth for presets, shared by core's defaults, the server's initial config, and web/CLI display.
+It is a *catalog*, not a routing table — AgentHub owns routing.
+
+## Pricing
+
+- Three buckets in USD per million tokens: `cache_read` (the vendor's cache-hit price),
+ `cache_write` (the vendor's cache-write price, or the standard input price where the vendor
+ charges no write premium), `output`. `cny(...)` converts official CNY list prices at the 7:1
+ display convention.
+- A vendor with **tiered** pricing gets its base tier recorded, and the tier boundary noted in the
+ section comment — OpenAI above 272K input, Gemini 3.1 Pro above 200K, MiniMax M3 above 512K.
+ Long-context use is then knowingly under-costed; that is the convention, not an oversight.
+- A **promotion** is a `discount` fraction beside the list `pricing`, never a discounted number
+ written into `pricing`: `effectivePricing()` derives the billed rate, and a lapsed promotion is
+ one field to delete with the rate to return to still on the row. `presetModelEntries()` writes
+ the effective rate, so what a Project stores is what the gateway charges.
+- A **time-based** tier is an `offPeakDiscount` schedule instead, and it is never baked into a
+ Project. The row stores its peak price, and the cost center decides the tier from each usage
+ record's own `ts` — the aggregation splits by tier before pricing. Deciding it at read time
+ instead would move a finished week's cost every time the boundary passed.
+- **Zero is a rate, absence is not.** Three zero buckets are a genuine $0 tier: the row shows the
+ free badge and contributes 0 to the cost center. Omitting `pricing` instead means "unknown", and
+ the cost center marks it uncosted. Self-hosted and free-tier rows take the zero; a row whose
+ price nobody has looked up takes the absence.
+
+## Identity and routing
+
+- Uniqueness is the `(provider, model_id)` pair, never the bare id — gateways resell vendor models
+ under their upstream ids.
+- Set `client_type` only when the id cannot be auto-routed or a protocol must be pinned, and inline
+ `baseUrl` with it. Everything else is auto-routed by AgentHub.
+- A provider group is split only when the vendor genuinely has separate endpoints or billing paths
+ (Qwen Token Plan vs Pay-As-You-Go). One endpoint serving several key types is one group.
+- `resolveModelEnv` mirrors AgentHub's exact routing; a lookalike id must stay unroutable.
+
+## What a change touches
+
+Adding a model touches the catalog test's exact-order assertions,
+`packages/web/src/features/models/protocol-path.ts` when the client's request path is not
+`/chat/completions`, the provider glyph map, and the bilingual `models` / `configuration` docs.
+
+Provider glyphs are one monochrome family: 24×24, `currentColor`, pure paths, no external assets.
+A vendor's own mark goes in with its colours flattened, the way Qwen's gradient wordmark already
+is — a single coloured glyph in that row reads as a mistake.
+
+**Moving the default reaches further than adding a model.** `defaultProjectConfig()` in
+`packages/core/src/state/project-config.ts` holds it, and six documented first-run commands pin it
+by hand — `README.md`, `README.zh.md`, and `quickstart-cli` / `quickstart-sdk` in both languages —
+each ending `--set-default`, which writes `default_model`. Leave them on the old id and the
+documented first run silently undoes the change on every fresh install. The `models` and
+`configuration` samples carry it in two places that must move together, the `default_model` line
+and the `[[models]]` row it names (a default naming no entry is rejected on load), and
+`plugins/agent-development/skills/penguin-sdk/SKILL.md` states it in prose.
+
+Existing Projects never migrate automatically: presets are copied into `.project_config.toml` at
+creation and nothing rewrites them. Users pick changes up through the models page's explicit "sync
+presets", which appends and updates catalog-owned fields but never deletes and never touches the
+stored default. Say so in the entry.
diff --git a/.agents/skills/penguin-harness-dev/reference/verification.md b/.agents/skills/penguin-harness-dev/reference/verification.md
new file mode 100644
index 00000000..53b508a8
--- /dev/null
+++ b/.agents/skills/penguin-harness-dev/reference/verification.md
@@ -0,0 +1,89 @@
+# Verification detail
+
+Loaded on demand from `SKILL.md`, which carries the decision itself — the table of what to run
+for what you changed. This file is what that decision leans on when something goes sideways:
+the known flakes, the two ways a test proves nothing, the CI-polling traps, and how to run a
+suite on another machine when the user asks for that.
+
+## Known platform failures that are not your diff
+
+`ci-windows` runs the same chain minus `format:check`, plus `scripts/test-installer.ps1`. Two
+failures there are known: a bare `Failed` worker crash, and an `environment.test.ts`
+truncation-timing assertion — rerun before debugging. An `EBUSY` on removing a directory that is
+some child process's cwd is real, not a flake.
+
+The local server suite drops a few tests under full parallel load — they time out and pass on
+their own. Rerun the file alone before blaming the diff.
+
+## Two ways a test proves nothing
+
+**A fake that is kinder than the real thing hides the bug it was written for.** Transports are
+faked at a seam here — `createSocket`, `createClient`, a stubbed `globalThis.fetch` — and the
+half that drifts is the failure contract, not the happy path. A fake that hands back a fresh
+cursor where the adapter returns the one it was given, or that resolves where production parks,
+passes a test whose subject is exactly that path. Write the fake's failure branches from the
+adapter's, not from what the assertions need.
+
+**A structural assertion that was already true at the base commit is not a test.** Reading source
+text in a test is house style here (20 web test files do it), which makes it easy to assert a
+shape the file already had. Replay each new assertion against `git show <base>:<path>` and keep
+the ones that fail there.
+
+## Reading CI without fooling yourself
+
+**On a conflicting PR, waiting for CI is waiting for nothing.** The workflows run against the
+merge commit GitHub builds from the branch and `main`, and it does not build one while the two
+conflict — the checks never start, so polling `statusCheckRollup` returns the same pending or
+empty list forever. Read the state before the checks: `gh pr view <n> --json
+mergeable,mergeStateStatus` answers `CONFLICTING` / `DIRTY`. Merge `origin/main` into the branch,
+resolve, push, and only then expect checks.
+
+**A queued run registers no checks at all**, so "every check is non-pending" is trivially true in
+the seconds after a PR opens, and a rollup holding two unrelated fast checks reads as a green
+matrix. Poll the run, not the checks — `gh run list --branch <branch> --workflow CI --limit 1
+--json status,conclusion,databaseId` — and treat `queued` / `in_progress` as not done. Sanity-check
+the check count against a sibling PR before calling anything green.
+
+Two more things that pass silently and are worth checking in the same pass: an auto-merged file is
+not a correct file, so read the merged result where two PRs touched one region; and a test constant
+pinned to a count the other PR changed fails for a reason that has nothing to do with either change
+— derive the count instead of re-pinning it.
+
+**A piped command reports the pipe's exit code.** `pnpm … | tail` succeeds when the build fails.
+Check a real artifact, or set `pipefail`, before believing a piped run.
+
+## Running the suite somewhere other than this machine
+
+**Default: run tests here.** Move them to another machine only when the user asks for that in so
+many words. A remote run is not a silent optimisation — it changes which environment the result
+describes, and a green run elsewhere is not evidence about here unless that was the point.
+
+When asked, `.agents/scripts/remote-test.sh` does the round trip:
+
+```sh
+.agents/scripts/remote-test.sh <worktree> [--build "<pkg> <pkg>"] -- <pnpm args>
+```
+
+It reads the destination from `PENGUIN_TEST_HOST` — an ssh alias or `user@host`, whatever the
+caller's ssh config already resolves — and hard-codes none: the address belongs to the person
+running it, not to this repo. It rsyncs sources (`node_modules`, `dist` and `.git` stay behind),
+installs with the frozen lockfile, optionally builds, then runs pnpm there.
+
+Four things that each cost a round trip if you assume them away:
+
+- **A non-login ssh shell loads neither a version manager nor corepack.** `ssh <host> node -v` can
+ report a Node below this repo's `>=24` engine while the intended one sits under a version
+ manager. Source the environment inside the remote command rather than trusting PATH.
+- **Resolve the remote home; never spell it.** rsync does not expand `$HOME` in a remote
+ destination, and a `~` inside double quotes is not expanded by the remote shell either — both
+ silently create a directory named after the variable.
+- **Build what the suite reads a `dist` of**, not just core. `SKILL.md`'s table says which; a
+ suite importing another package's subpath exports fails to resolve them otherwise.
+- **The synced tree may need `git init`.** One core test resolves the checkout root beside
+ `pnpm-workspace.yaml`, and a worktree's `.git` is a pointer file, so syncing it verbatim leaves
+ a dangling gitdir.
+
+**A difference between the two machines is a finding, not noise.** A suite that passes here and
+fails there has usually caught a real environment assumption — a locale-dependent sort, a
+filesystem or Node-version difference. Report it and fix the assumption. Pinning the remote
+environment to make it green is the same mistake as a fake kinder than the real thing.