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.shnew file mode 100755index 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.mdindex 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 changedNode 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:```shpnpm --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 `` 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.mdnew file mode 100644index 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+`` 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.