Changelog, dev startup, README, AgentHub 0.4.0, model catalog, and landing site (#7)

Branch-length batch covering tooling, the model layer, the Web App and the public
surfaces. Highlights:

- Changelog: a per-release `changelog/<version>/` tree, grouped by the surface each
  change touches, with a root CHANGELOG.md holding one line per release.
- Dev startup: `scripts/dev-prebuild.mjs` serializes the skills+core prebuild behind a
  lock and keeps `pnpm install` current; `pnpm dev` runs server+web together.
- AgentHub 0.3.3 -> 0.4.0: OmniMessage complete payloads carry one opaque `fidelity`
  object in place of item-level `signature`/`phase`, threaded verbatim through Trace,
  replay and resume; malformed classification adapted to the new error types.
- Model layer: a model is always referenced by an explicit `(provider, model_id)` pair.
  The provider is never inferred, guessed or defaulted -- both the catalog inference and
  the unique-match config resolution are gone, and CLI, SDK, server routes and
  run_subagent all require the complete pair. Catalog gains the Qwen Token Plan, Qwen
  Pay-As-You-Go and Fireworks AI gateways, plus an expanded OpenRouter group.
- Web App: catalog preset sync and per-group speed test on the Models page, positional
  slash commands, a markdown renderer, skill-library update reminders, and a vertically
  centred draft page whose upward menus size themselves to the room available.
- Public surfaces: restructured READMEs, the penguin.ooo landing site and blog, refreshed
  benchmark results for both suites, and the demo videos playing on the landing page.

Includes the fixes from a full review of the branch: 23 confirmed findings, among them a
provider-inference bug that could send one vendor's API key to another vendor's endpoint,
and an Escape handler that destroyed the composer's contents unrecoverably.

Verified on the branch head: pnpm test (1127 passing, 7 packages), pnpm typecheck and
pnpm format:check clean, Playwright e2e 14/14.

packages/cli/src/commands/chat.ts

@@ -1,12 +1,14 @@
 /**
  * `penguin chat` — interactive REPL.
  *
- *   penguin chat [--model-id <id>] [--provider <group>] [--project-id <id>] [--agent-id <id>]
+ *   penguin chat [--model-id <id> --provider <group>] [--project-id <id>] [--agent-id <id>]
  *                [--workspace <path>] [--approve <allow-all|deny-all|read-only|always-ask>]
  *
  * Each line of input starts one conversation turn; `/compact` proactively compacts the
  * context (reason=manual); `/exit` or `/quit` exits.
- * Uses the current directory when no Workspace is specified.
+ * Uses the current directory when no Workspace is specified. A model reference is always an
+ * explicit `(provider, model_id)` pair, so `--model-id` and `--provider` must be given
+ * together; giving neither uses the Project's default model.
  *
  * Multi-line input: trailing `\` continues the line; when the terminal supports bracketed
  * paste, a multi-line paste is treated as a single message (sent on Enter).
@@ -65,6 +67,17 @@ export function registerChatCommand(program: Command, t: Messages): void {
     .option("--approve <mode>", t.common.approve)
     .option("--resume [sessionId]", t.chat.resume)
     .action(async (opts) => {
+      // The model reference is a pair: commander can only require each option on its own,
+      // so the "both or neither" rule is enforced here. Giving neither is the normal case
+      // and falls back to the Project's default model. Skipped under --resume, which
+      // rejects both options outright further down with a more specific message.
+      // Usage errors go to stderr (as in `run` and `config model add`), unlike this file's
+      // informational messages, which the REPL writes to stdout.
+      if (opts.resume === undefined && Boolean(opts.modelId) !== Boolean(opts.provider)) {
+        process.stderr.write(`${t.error(t.modelRefIncomplete())}\n`);
+        process.exitCode = 1;
+        return;
+      }
       const mode = resolveApprovalMode(opts.approve, t);
       const out = process.stdout;
 

packages/cli/src/commands/config.ts

@@ -2,7 +2,7 @@
  * `penguin config` — manages a Project's model credentials, default model, model list,
  * Agent-level vault environment variables, and UI language.
  *
- *   penguin config model add --model-id <upstream id> [--provider <group>] [--api-key <key>] [--context-window <n>] [--set-default] [--root <dir>]
+ *   penguin config model add --model-id <upstream id> --provider <group> [--api-key <key>] [--context-window <n>] [--set-default] [--root <dir>]
  *   penguin config model default --model-id <upstream id> --provider <group> [--root <dir>]
  *   penguin config model vision --model-id <upstream id> --provider <group> [--root <dir>]
  *   penguin config model list [--root <dir>]
@@ -13,12 +13,12 @@
  *
  * `--model-id` always takes the **upstream id** (the request id sent to AgentHub verbatim),
  * which together with `--provider` forms a `(provider, model_id)` paired reference —
- * **no string concatenation is ever performed**. For `model add`, --provider defaults to
- * an inference from the built-in catalog (falling back to custom when inference fails);
- * a new entry's client_type defaults according to the group's semantics (not set for
- * first-party vendors; openai for custom / self-hosted groups / gateways, with the
- * gateway's endpoint base URL pre-filled). For `model default` / `model vision`,
- * --provider is **required**; core validation raises an error when the reference is not
+ * **no string concatenation is ever performed**. `--provider` is **required** on all three
+ * model subcommands: the group is never guessed, so `--api-key` can never land on a vendor
+ * the user did not name. For `model add`, a new entry's client_type defaults according to
+ * the group's semantics (not set for first-party vendors; openai for custom / self-hosted
+ * groups / gateways, with the gateway's endpoint base URL pre-filled). For `model default`
+ * / `model vision`, core validation raises an error when the reference is not
  * found in models. `--root` specifies the data root directory (priority: option >
  * PENGUIN_HOME > ~/.penguin/data). The UI language is controlled by the PENGUIN_LANG
  * environment variable; `config lang` writes it into the shell startup file and restarts
@@ -39,7 +39,6 @@ import {
   catalogEntryFor,
   formatModelRef,
   getModel,
-  inferProviderForUpstream,
   loadAgentVault,
   loadProjectConfig,
   providerInfo,
@@ -117,7 +116,7 @@ export function registerConfigCommand(program: Command, t: Messages): void {
     .command("add")
     .description(t.config.addDesc)
     .requiredOption("--model-id <id>", t.config.addModelId)
-    .option("--provider <group>", t.config.addProvider)
+    .requiredOption("--provider <group>", t.config.addProvider)
     .option("--api-key <key>", t.config.addApiKey)
     .option("--base-url <url>", t.config.addBaseUrl)
     .option("--context-window <n>", t.config.addContextWindow, parseIntArg)
@@ -133,11 +132,11 @@ export function registerConfigCommand(program: Command, t: Messages): void {
     .option("--root <dir>", t.common.root)
     .action(async (opts) => {
       const root = resolveRootOption(opts.root);
-      // --model-id takes the upstream id, paired with --provider as a reference
-      // (--provider defaults to catalog-based inference, falling back to custom); no
-      // concatenation is performed.
+      // --model-id takes the upstream id, paired with the required --provider as a
+      // reference; the group is never guessed, so --api-key can only ever land on the
+      // vendor the user named. No concatenation is performed.
       const modelId: string = opts.modelId;
-      const provider: string = opts.provider ?? inferProviderForUpstream(modelId);
+      const provider: string = opts.provider;
       const ref: ModelRef = { provider, model_id: modelId };
       const before = await loadProjectConfig(root, opts.projectId);
       const existed = getModel(before, ref) !== undefined;

packages/cli/src/commands/run.ts

@@ -1,14 +1,14 @@
 /**
  * `penguin run` — send a single Task in one shot.
  *
- *   penguin run -m <msg> [--model-id <id>] [--provider <group>] [--workspace <path>]
+ *   penguin run -m <msg> [--model-id <id> --provider <group>] [--workspace <path>]
  *               [--project-id <id>] [--agent-id <id>]
  *               [--approve <allow-all|deny-all|read-only|always-ask>]
  *
  * Uses the current directory when Workspace is unspecified; uses the Project's default model
- * when model is unspecified. `--provider` is optional: when omitted, `--model-id` is resolved
- * via resolveModelRef semantics (only matches when the exact value is globally unique in the
- * config; ambiguity is an error). Defaults to interactive per-call approval; `--approve`
+ * when model is unspecified. A model reference is always an explicit `(provider, model_id)`
+ * pair, so `--model-id` and `--provider` must be given together — giving only one of them is
+ * an error, never a lookup. Defaults to interactive per-call approval; `--approve`
  * selects the permission mode.
  * Docs: /docs/cli § "penguin run".
  */
@@ -31,6 +31,14 @@ export function registerRunCommand(program: Command, t: Messages): void {
     .option("--workspace <path>", t.common.workspace)
     .option("--approve <mode>", t.common.approve)
     .action(async (opts) => {
+      // The model reference is a pair: commander can only require each option on its own,
+      // so the "both or neither" rule is enforced here. Giving neither is the normal case
+      // and falls back to the Project's default model.
+      if (Boolean(opts.modelId) !== Boolean(opts.provider)) {
+        process.stderr.write(`${t.error(t.modelRefIncomplete())}\n`);
+        process.exitCode = 1;
+        return;
+      }
       const mode = resolveApprovalMode(opts.approve, t);
 
       const agent = await createAgent({