@penguinharness/agent-development 0.2.9

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="m12 3 8 4.5v9L12 21l-8-4.5v-9z" />
+  <path d="m4 7.5 8 4.5 8-4.5" />
+  <path d="M12 12v9" />
+  <path d="m8 5.25 8 4.5" />
+</svg>

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@penguinharness/agent-development",
+  "version": "0.2.9",
+  "description": "Agent development on PenguinHarness: build on the SDK, call any model through one unified LLM API, manage models and secrets, and orchestrate agents, sessions, costs and schedules.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prism-Shadow/penguin-harness.git",
+    "directory": "plugins/agent-development"
+  },
+  "files": [
+    "plugin.json",
+    "icon.svg",
+    "skills",
+    "hooks",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.json

@@ -0,0 +1,8 @@
+{
+  "description": "Agent development on PenguinHarness: build on the SDK, call any model through one unified LLM API, manage models and secrets, and orchestrate agents, sessions, costs and schedules.",
+  "description_zh": "基于 PenguinHarness 的智能体开发：用 SDK 构建应用、经统一的 LLM API 调用任意模型、管理模型与密钥、编排智能体/会话/成本/定时任务。",
+  "short_description": "SDK, unified LLM API, config and orchestration.",
+  "short_description_zh": "SDK、统一 LLM API、配置与编排。",
+  "version": "2026-09-02.1",
+  "category": "ai-app-development"
+}

package/skills/penguin-config/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: penguin-config
+description: Manage model API keys, default models and per-agent vault secrets with the penguin CLI.
+---
+
+# Penguin Config (CLI)
+
+The `penguin` CLI manages model credentials, default models and per-agent vault secrets. Its primary job is model configuration: `penguin config model add` registers a model and `penguin config model list` shows the models currently available. Configuration goes through the CLI only — never read or hand-edit the underlying hidden files.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use penguin-cli skill") without a concrete request, ask the user what they want to configure. Do not run any command until the goal is clear.
+
+## Models
+
+Add or update a model (upsert by the `(provider, model_id)` pair; re-run with more options to amend an entry):
+
+```bash
+penguin config model add --provider <group> --model-id <upstream_id> [--api-key <key>] [--base-url <url>] \
+  [--client-type <type>] [--context-window <n>] [--max-tokens <n>] [--vision | --no-vision] \
+  [--price-cache-read <n>] [--price-cache-write <n>] [--price-output <n>] \
+  [--project-id <id>] [--root <dir>] [--set-default]
+```
+
+- A model is identified by the `(provider, model_id)` pair, so `--provider` and `--model-id` are **both required** — the group is never inferred from the model id, because gateways resell vendor models under their upstream ids and a wrong guess would send the key to another vendor's endpoint. `--model-id` takes the provider's upstream model id (what the API expects) and is persisted as the entry's request id, so it reaches the API unchanged; `--provider` names the group (`deepseek`, `openai`, `anthropic`, `google`, `openrouter`, `siliconflow`, … — `custom` for any other endpoint).
+- For any OpenAI chat-completion compatible endpoint use `--client-type openai --base-url <endpoint>`; omit `--client-type` to auto-route by model id.
+- Prices are USD per million tokens (cache read / cache write / output).
+- `--vision` / `--no-vision` mark whether the model accepts images; omitting both keeps the current value (default is vision-capable).
+- `--max-tokens <n>` pins a per-model output cap (positive integer), overriding the Agent's `model.max_tokens`; omit to inherit. Lower it for small-context models — the per-Agent default (32000) cannot fit into e.g. a 32k context window together with any prompt.
+- All `penguin config model ...` and `penguin config vault ...` commands accept `--root <dir>` to target another data root (default `PENGUIN_HOME`, then `~/.penguin/data`). Two configuration targets — treat the difference as a hard rule:
+  - **Penguin's own model** (self-configuration: the model Penguin itself runs on): the default root without `--root` is correct.
+  - **An AI app you are building**: `--root` **must** point at the app's own data directory inside the project (e.g. `--root ./penguin_data`, the same path the app gives `createAgent({ root })`) unless the user explicitly chose another location — never write an app's models or keys into the global `~/.penguin/data`, which belongs to the person running Penguin, not to the app.
+  - While developing an app, review regularly: `penguin config model list --root <app root>` should show the app's entries, and the global list (no `--root`) should stay clean.
+
+Other model commands:
+
+```bash
+penguin config model default --model-id <upstream_id> --provider <group> [--root <dir>]   # set the project default model
+penguin config model vision --model-id <upstream_id> --provider <group> [--root <dir>]    # set the project vision model (reads images for text-only sessions)
+penguin config model list [--root <dir>]                      # list models; api_key is shown masked
+```
+
+## Vault (per-agent secrets)
+
+The vault holds an agent's environment-variable secrets (third-party API keys etc.); values are injected into that agent's shell subprocesses:
+
+```bash
+penguin config vault set --key <NAME> --value <value> [--project-id <id>] [--agent-id <id>] [--root <dir>]
+penguin config vault list [--project-id <id>] [--agent-id <id>] [--root <dir>]      # values are shown masked
+penguin config vault remove --key <NAME> [--project-id <id>] [--agent-id <id>] [--root <dir>]
+```
+
+- `--project-id` defaults to `default_project`, `--agent-id` to `default_agent`.
+- Key names follow shell variable rules (letter or underscore first, then letters, digits and underscores); values are limited to 8192 characters.
+
+## Language
+
+```bash
+penguin config lang <en|zh>   # persist the CLI language via PENGUIN_LANG in your shell rc
+```
+
+## Running agents
+
+`penguin run -m "<task>" [--provider <group> --model-id <id>] [--agent-id <id>] [--workspace <path>] [--approve <mode>]` runs one task; `penguin chat [--resume [session_id]]` starts or resumes an interactive chat with the same options. The model reference stays a pair here too: pass `--provider` and `--model-id` together, or neither to run on the project's default model — one without the other is rejected.
+
+## Storage
+
+Paths use `<app_data_dir>`, the App Data Dir value from your Environment section.
+
+- `<app_data_dir>/.project_config.toml` — the project's single hidden config file: model list, settings and per-model credentials (`api_key` etc. inlined in each model entry). Configuration is CLI-only — never read, print or hand-edit this file.
+- `<app_data_dir>/agents/<agent_id>/agent_state/.vault.toml` — that agent's vault entries, hidden file; same rule, manage it with `penguin config vault`.

package/skills/penguin-orchestration/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: penguin-orchestration
+description: Drive PenguinHarness itself from a shell — list and create agents and sessions, send and steer messages mid-flight, and query costs and scheduled tasks via the penguin CLI over the local server.
+---
+
+# Penguin Orchestration
+
+The `penguin` CLI is a thin client of the PenguinHarness server. Inside a harness agent session it reaches the same server that is running you, so you can orchestrate the platform yourself: list and create agents, start conversations with them, steer those conversations while they run, and query costs and scheduled tasks.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use penguin-orchestration skill") without a concrete request, ask the user what they want to orchestrate. Read-only commands (`project ls`, `agent ls`, `ls`, `logs`, `cost`, `schedule ls`) are always safe; do not create agents, start sessions or send messages until the goal is clear.
+
+## How the connection works
+
+- **Inside a harness agent session** (you, now): every command subprocess has `PENGUIN_API_URL`, `PENGUIN_API_TOKEN`, `PENGUIN_PROJECT_ID`, `PENGUIN_AGENT_ID` and `PENGUIN_SESSION_ID` injected, so `penguin` commands automatically reach your own server with your project and agent as the defaults — no login step.
+- **Outside an agent** (a human shell): the CLI attaches to the running local server via its lock file, or auto-starts one; the local `<data-root>/api-token` file (0600) authenticates it.
+- You are operating the same server that runs you: sessions and agents you create appear live in the web UI, where the user sees and owns everything you spawn.
+- The injected token is admin-equivalent. Act accordingly: stick to what the task requires, and prefer read-only commands until a mutation is clearly needed.
+
+## Orient first
+
+Before mutating anything, see what exists:
+
+```bash
+penguin project ls        # projects on this server
+penguin agent ls          # agents in the current project
+penguin ls --json         # the project's sessions, with running state
+```
+
+`--json` on any listing gives machine-parseable output.
+
+## Command surface
+
+```
+penguin run -m <msg> [--project-id <id>] [--agent-id <id>] [--workspace <path>]
+            [--model-id <id> --provider <p>] [--approve <mode>] [--thinking <level>]
+            [--session <session_id>] [--background] [--timeout <duration>]
+            [--goal [budget]] [--json]
+penguin ls [--project-id <id>] [--agent-id <id>] [--days <n>] [-a|--all] [--json]
+penguin input [session_id] [-m <text>] [--timeout <duration>]
+              [--project-id <id>] [--agent-id <id>] [--json] [--server <url>]
+penguin logs [session_id] [--project-id <id>] [--agent-id <id>] [--tail <n>]
+             [-f|--follow] [--timeout <duration>] [--json]
+penguin agent ls [--project-id <id>] [--json]
+penguin agent create --agent-id <id> [--name <s>] [--description <s>] [--skills <a,b>]
+                     [--project-id <id>] [--json]
+penguin project ls [--json]
+penguin cost [--days <n>] [--from <d> --to <d>] [--by date|agent|model|session]
+             [--project-id <id>] [--agent-id <id>] [--json]
+penguin schedule ls [--project-id <id>] [--agent-id <id>] [--json]
+penguin schedule add <name> --prompt <s> --start-at <ISO|now> [--period <duration>]
+                    [--end-at <ISO>] [--session-id <id> | --workspace <path>
+                    [--model-id <id> --provider <p>]] [--disabled]
+                    [--project-id <id>] [--agent-id <id>]
+penguin schedule update <name> [<same field flags>] [--enable|--disable]
+                    [--project-id <id>] [--agent-id <id>]
+penguin schedule rm <name> [--project-id <id>] [--agent-id <id>]
+```
+
+- `run` starts a task and waits, rendering the conversation, unless `--background` — then it prints the new session id and exits while the server keeps running the task. `--session <session_id>` runs the task in an existing session instead of creating one; the model reference is the `--provider` + `--model-id` pair (both or neither); `--goal [budget]` runs in goal mode — the session loops until the agent declares the goal complete, with an optional spend budget.
+- **Caller-context defaults.** Inside a harness agent, a session-creating `run` fills every field you leave unspecified from your own live session, per field independently: `--workspace`, the `--model-id`/`--provider` pair, `--approve` and `--thinking` inherit the caller's values — the same convention as `run_subagent` parent inheritance. Precedence: explicit flag > caller value > plain fallback (cwd, the Project default model, `allow-all`, none — used wholesale if the caller lookup fails, with a dim stderr note). So inside an agent, `penguin run -m "..."` alone typically does the right thing; pass flags only to diverge.
+- `--timeout <duration>` (`30s`, `5m`, `2h`, or bare seconds) bounds the wait of a foreground `run`, an `input`, or a `logs -f`. Expiry is a soft yield, not an error: the command exits 0 while the task keeps running server-side, printing a still-running note that names the follow-up commands (`--json` prints `{sessionId, status: "running", text}` with the text so far). `--timeout 0` (also `0s`) returns immediately after delivery — the same note without collected text (`--json`: `{sessionId, status: "running"}`); on a bare poll it snapshots a running session instantly. `run --background` stays the idiomatic fire-and-forget for new tasks and rejects `--timeout`; `logs --timeout` requires `-f`.
+- `input` with `-m` steers a **running** session mid-turn (the agent absorbs it as a course correction within the current task) or starts a new turn on an idle one; it waits for the reply unless a `--timeout` bounds the wait (`--timeout 0` = deliver and return at once). Bare `input [session_id]` (no `-m`) **polls**: it prints the session's most recent complete assistant text — an idempotent snapshot that skips user/thinking/tool output and never touches approvals, mirroring `input_subagent`'s empty-prompt semantics. A running session is waited on first (bounded by `--timeout`, else indefinitely); a session with no reply yet prints `(no assistant reply yet)`. `--json` reports `{sessionId, status, text}` — `idle`/`running` when polling, `completed`/`aborted`/`running` with `-m`.
+- `ls` spans every agent of the project, newest first (by last active); archived sessions are left out unless `-a`/`--all` includes them, and `--days <n>` keeps only sessions last active since local midnight n−1 days ago — today counts as day 1, so `--days 2` is yesterday and today, `--days 7` this week. `logs` renders a session's transcript: `--tail <n>` for the last entries, `-f` to follow live.
+- Session ids embed their creation timestamp — `session-YYYY-MM-DD-HH-mm-ss-<8hex>`. Every `<session_id>` argument takes any unique substring of an id; the 8-hex tail is the recommended short form, and an ambiguous fragment errors listing the candidates. On `input` and `logs`, `--project-id` scopes that fragment search (unnecessary with a full id).
+- On `input` and `logs` the id is optional altogether: omitted, it is the agent's most recent session, off the same newest-first listing `chat --resume` uses, with `--agent-id` picking whose. The chosen id is announced as a dim `[latest]` line on stderr, so the target is never ambiguous and `--json` on stdout stays parseable. Bare `penguin logs` is therefore "what just happened" and bare `penguin input` is "what did my agent last say"; an agent with no session at all gets one line pointing at `penguin run` and a non-zero exit.
+
+## Recipes
+
+### Yesterday's or this week's sessions, with their latest replies
+
+```bash
+penguin ls --days 2 --json    # yesterday + today (today counts as day 1)
+penguin ls --days 7 --json    # this week; add -a to include archived sessions
+penguin input <session_id>    # one session's latest complete assistant reply
+```
+
+- `--days <n>` keeps sessions last active since local midnight n−1 days ago. For strictly-yesterday, take `--days 2` and drop today's entries client-side — ids embed the creation date and the JSON carries last-active.
+- Bare `input` prints the latest reply; add `--timeout 0` to snapshot a running session instantly instead of waiting for its turn to finish.
+
+### Summarize this week's history in a new session
+
+A fresh session gets a fresh context window for the summary; feed it through a file, not the prompt:
+
+```bash
+penguin ls --days 7 --json               # pick the sessions
+penguin logs <session_id> --tail 100     # gather each transcript (widen if cut short)
+# write what you gathered into a workspace file with your file tools, then:
+penguin run -m "Read ./weekly-material.md and write the weekly summary to ./weekly-summary.md"
+```
+
+- **Exchange big material through workspace files.** Caller-context defaults mean the new session shares your workspace — write the gathered transcripts to `./weekly-material.md` and have the new session read it there. Pages of transcript do not belong in `-m`.
+- Read the result from `./weekly-summary.md` (the foreground run also renders the reply).
+
+### Create an agent and say hello
+
+```bash
+penguin agent create --agent-id greeter --name "Greeter" --description "Welcomes people"
+penguin run --agent-id greeter -m "Hello! Introduce yourself."
+```
+
+- Agent ids must match `^[a-z][a-z0-9_]{1,63}$`: a lowercase letter first, then lowercase letters, digits and underscores — no hyphens.
+- A newly created agent starts with **no skills preinstalled**: seed it at creation with `--skills a,b` (library names) — include `penguin-orchestration` itself when the new agent must drive the harness too.
+- `--agent-id` switches only the agent: workspace, model, approval and thinking still inherit from your own session (caller-context defaults) — add those flags to change them too. Each `run` without `--session` opens a fresh session; reuse a session id to continue a conversation.
+
+### Summarize each agent's costs in a new session
+
+```bash
+penguin cost --days 7 --by agent --json    # who spent what this week
+penguin run -m "Summarize this per-agent cost report and flag anomalies: <the JSON>"
+```
+
+- The default `penguin cost` card already carries today / last 7 days / total; `--by date|model|session` and `--from <d> --to <d>` give the other cuts, `--project-id` / `--agent-id` narrow the scope.
+- A `--by agent` report is small enough to inline in `-m`; for long breakdowns (`--by session` over a busy week), use the file-exchange pattern from the weekly-summary recipe.
+
+### Set up a scheduled task for the current agent
+
+```bash
+penguin schedule add build-watch --prompt "Check the build results and report the failures" \
+  --start-at now --period 12h --session-id "$PENGUIN_SESSION_ID" \
+  --end-at <ISO instant>                             # only when the request has a horizon
+penguin schedule add daily-report --prompt "Summarize yesterday's conversations" \
+  --start-at now --period 1d                         # no target: a fresh session per firing
+penguin schedule ls                                  # verify
+penguin schedule update daily-report --period 12h    # adjust; --enable/--disable to toggle
+penguin schedule rm daily-report                     # remove — no confirmation prompt
+```
+
+- `--agent-id` defaults to yourself from the caller env, so this schedules the current agent. `--start-at` takes ISO 8601 or `now`; `--period` is at least 5m (`30m`/`12h`/`1d`/`7d`), omit it for a one-shot; `--end-at` bounds recurrence. Target the session you are in — `--session-id "$PENGUIN_SESSION_ID"` — unless the user asked for somewhere else: the prompt then arrives in this conversation, with its context. Leave the target off when the user wants a separate session, or when the task is better off starting clean (a nightly report that should not inherit this conversation); each firing then opens a new session, which `--workspace <path>` and the `--model-id` + `--provider` pair configure.
+- `add` creates the schedule **enabled** (`--disabled` stages it off) — deliberately diverging from the raw file, where `enabled` defaults to false. `update` is read-modify-write: unspecified fields keep their stored values, and switching the target form clears the other one.
+- In `schedule ls`, read: the AGENT column (without `--agent-id` the listing spans agents), `enabled` (a disabled entry never fires), `startAt` (first firing), `period` (absent means one-shot), the target — an existing session versus a new session per firing — and `lastFiredAt`.
+- The CLI writes through the schedules API, so mistakes are rejected synchronously. The TOML file stays the single source of truth — `<app_data_dir>/agents/<agent_id>/agent_state/schedule/<name>.toml`, fields mirroring the flags (`prompt`, `enabled` — false by default in the file, `start_at`, `period`, `end_at`, `session_id` / `workspace`+`provider`+`model_id`) — and remains editable with file tools; your system prompt's schedule roster lists yours. A hand edit is only validated by the periodic reconcile (roughly every 30s), with errors landing in error records rather than your terminal — prefer the CLI.
+
+### Run a conversation in the background and steer it mid-flight
+
+Two patterns; both leave you free while the conversation runs.
+
+**(a) Background CLI process — you get a completion report.** Run the CLI itself as a background command: `exec_command` with `run_in_background: true` and the command
+
+```bash
+penguin run --agent-id <agent_id> -m "<long task>"
+```
+
+- The harness delivers a `[background_task_done]` report when the CLI exits — no polling needed for completion.
+- Meanwhile, find the session with `penguin ls --json` (it shows as running, with the newest id) and steer it: `penguin input <session_id> -m "Focus on X; skip Y" --timeout 0` (deliver and return at once).
+- Poll the latest answer with bare `penguin input <session_id> --timeout 30s` — a bounded wait that exits 0 with a still-running note when the reply is not in yet — or read the raw transcript with `penguin logs <session_id> --tail 20`.
+
+**(b) Server-side background — survives you.** `penguin run --background --agent-id <agent_id> -m "<long task>"` prints the session id and exits; the server keeps running the task with no local process.
+
+- Poll the latest answer with bare `penguin input <session_id> --timeout 30s`, watch live with `penguin logs <session_id> -f`, and check running state with `penguin ls --json`; steer with `penguin input <session_id> -m ...` the same way.
+
+Prefer (a) when you stay around for the result — the completion report comes to you. Prefer (b) when the work must survive your own session ending, or when fanning out many tasks without holding a process per task. A bounded foreground run is the middle ground: `penguin run --timeout 5m -m "..."` renders up to the bound, then soft-yields with the task still running — pick up the answer later with a bare `penguin input <session_id>`.
+
+## Cautions
+
+- **One active task per session.** `penguin input` at a busy session steers the running task rather than starting a second one; a new task sent at a busy session waits its turn. For parallel work, start parallel sessions.
+- **Unattended sessions must not need a human.** A spawned session inherits your approval mode (`allow-all` when there is no caller to inherit from); if you yourself run under `always-ask`, pass `--approve allow-all` (trusted work) or `--approve read-only` explicitly — an unattended `always-ask` session hangs waiting for approval in the web UI.
+- **No runaway loops.** An agent that messages itself — directly, through a chain of agents, or through a schedule aimed back at its own session — keeps spending until someone stops it. Make every automated conversation terminate: a recurring schedule pointed at your own session takes an `--end-at` whenever the request has a natural horizon (or no `--period` at all, for a one-time reminder), and a prompt whose per-firing work stays small — that session's context grows with every firing. When the user wants it open-ended, leave `--end-at` off and tell them it runs until they remove it.
+- **Spawned work bills the project.** Everything you start lands in the same project's usage (`penguin cost` shows it); a fan-out of sessions multiplies spend.
+- **Configuration stays CLI-managed.** Never read or hand-edit `.project_config.toml` or `agent_state/.vault.toml` — models and secrets go through `penguin config` (see the penguin-cli skill).

package/skills/penguin-sdk/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: penguin-sdk
+description: Use whenever the user wants to build an agent application — their own program with an embedded agent, such as an AI app, an agentic app or a RAG app. This is writing application code on the Penguin Harness SDK, not configuring an Agent State inside PenguinHarness. Covers self-contained projects, the createSession/run streaming loop with thinking and image messages, wiring the user's existing tools in as CLI commands, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI.
+---
+
+# Penguin Harness SDK
+
+`@prismshadow/penguin-core` is the TypeScript SDK this agent itself runs on. Use it to build your own AI apps:
+
+- An **Agent** loads its state (prompts, tools, skills) from `<root>/<project_id>/agents/<agent_id>/`. Creating an Agent whose directory is empty initializes it with defaults.
+- A **Session** is one conversation of an Agent inside a **Workspace** directory.
+- `session.run()` executes one task and streams every step (thinking, text, tool calls) as OmniMessages.
+
+To have an agent perform a task, use the `run_subagent` tool — the SDK is for building applications, not for invoking agents.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use penguin-sdk skill") without a concrete app to build, ask the user what they want to build. But when the request names a concrete goal — even a single sentence like "build a RAG app that answers questions about these docs" — do **not** ask follow-up questions: build it end to end with the defaults in this skill (self-contained workspace project, project default model, BM25 retrieval, web UI styled per the web-design skill) and list the assumptions you made in your final reply.
+
+## Project location
+
+Create the app in the current workspace directory by default (the `CWD` value from your Environment section), as a self-contained project — do not place it under `<app_data_dir>` (PenguinHarness's app data root) or depend on any path outside the project folder. When creating the app's agent, the data root defaults **under the working directory (CWD)** too: point `createAgent({ root })` at a directory inside the project, resolved from the source file so it stays relative:
+
+```ts
+const agent = await createAgent({ root: path.join(import.meta.dirname, "penguin_data") });
+```
+
+With every reference relative to the project, the user can move or copy the folder anywhere and it still runs.
+
+## Keys and the data root — check before you build
+
+**The app's Penguin data root must live inside the CWD workspace — never `~/.penguin`.** Point `createAgent({ root })` and every `penguin config ... --root <dir>` at a directory under the current working directory (e.g. `./penguin_data`); the global `~/.penguin` belongs to the person running Penguin and must never hold — or lend — the app's config or keys.
+
+**Credential first, code second** — a finished app that cannot answer is a failed delivery discovered too late. Before writing any code:
+
+```bash
+env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI)_API_KEY" || echo none
+```
+
+**Only two sources count as a usable credential**: a vault-injected environment variable (the check above; vault keys also appear in your Vault Keys section), or a key already configured in the app's own data root (`penguin config model list --root <data_dir>`). Keys in the global `~/.penguin` or any other `.penguin` directory do **not** count — a bare `penguin config model list` (no `--root`) reads the global store, because the CLI defaults to the global root unless `--root` is given, so a key showing up there proves nothing for the app and must never be used or copied.
+
+If neither counted source yields a key, **stop immediately and ask the user to configure one — do not start building, and do not burn turns re-checking in a loop**: have them open this agent's settings via the **gear icon** on its card (left side, Agents page) and add a model API key (e.g. `DEEPSEEK_API_KEY`) in the **key vault** tab — vault values reach your shell environment on the next task. One clear check, then hand back to the user. Build only after a credential is confirmed, or after clearly agreeing with the user to build now and verify later. Model ids to offer the user come from the penguin CLI catalog (`penguin config model add --help`) and the agenthub-models skill's id table.
+
+## Setup
+
+```bash
+npm install @prismshadow/penguin-core tsx
+```
+
+If the package is not on your npm registry (it is developed in the PenguinHarness monorepo and may not be published), develop inside a checkout of the PenguinHarness repo instead: add your app as a workspace package under `packages/`, depend on `"@prismshadow/penguin-core": "workspace:*"`, then `pnpm install && pnpm build` at the repo root. Tell the user which route you took.
+
+Configure a model for the app's data root, in this order — stop at the first that works:
+
+1. `penguin config model add --root <data_dir> --provider <group> --model-id <id> --api-key <key> [--base-url <url>] [--client-type openai-chat] --set-default` — prefer `--client-type openai-chat --base-url <endpoint>` (works with any OpenAI Chat Completions compatible endpoint; exact ids in the agenthub-models skill). `--provider` is required: a model is always the `(provider, model_id)` pair and the group is never inferred from the id (`custom` for an endpoint outside the built-in groups).
+2. Environment variables cover the **credential only** (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) — model selection still comes from the project config, whose preset default is `deepseek-v4-flash-vision-exp`. Env-only setup therefore works out of the box only with `DEEPSEEK_API_KEY`; for another vendor either run the CLI command above or pass a configured `{ provider, modelId }` pair to `createSession`.
+
+Keep model API keys **project-local**: configure them with the penguin CLI into the app's own data root under the working directory, so the project stays self-contained and movable. When building an AI app, **always pass `--root <data_dir>` pointing at the app's data directory inside the current working directory** (the same path you give `createAgent({ root })`, e.g. `./penguin_data`) — never run `penguin config ...` without `--root`, or it writes to the global `~/.penguin/data` instead of the project. Never read, copy or fall back to model keys stored in the user's global `~/.penguin` directory — that config belongs to the person running Penguin, not to the app you are building.
+
+Model config lives in one hidden file under the data root's project directory: `.project_config.toml`. It is CLI-only — never read, print or edit it.
+
+If the user agreed to build before a credential exists, do not fake the verification: finish the build, report it as **unverified**, and point them at the key vault flow above — once a key is added, vault values reach your environment on the next task and you can run the self-test to completion.
+
+## Streaming loop
+
+The raw `run()` stream mixes model, event and session-meta payloads — always narrow with the exported guards (`isModelMessage`, `isCompleteModelMessage`, `isEventMessage`) before touching `payload.type`; accessing `msg.payload.type` directly does not typecheck.
+
+```ts
+import path from "node:path";
+import readline from "node:readline/promises";
+import { createAgent, isModelMessage, userText } from "@prismshadow/penguin-core";
+
+const agent = await createAgent({ root: path.join(import.meta.dirname, "penguin_data") });
+const session = await agent.createSession({ workspaceDir: process.cwd() });
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+for (;;) {
+  const line = await rl.question("> ");
+  if (!line.trim()) break;
+  // One run per user turn; the same Session keeps the conversation context.
+  for await (const msg of session.run([userText(line)], {
+    approve: async () => "allow", // demo only — a real app should ask its user ("deny" blocks the call)
+  })) {
+    if (isModelMessage(msg)) {
+      const p = msg.payload;
+      if (p.type === "partial_text" && p.event_type === "delta") process.stdout.write(p.text);
+      // CoT stream from reasoning models — show progress, but keep it out of the answer channel.
+      if (p.type === "partial_thinking" && p.event_type === "delta") process.stderr.write(p.thinking);
+    }
+  }
+  process.stdout.write("\n");
+}
+rl.close();
+session.dispose();
+```
+
+- `createSession({ workspaceDir, provider, modelId })` — `workspaceDir` must already exist (omit for a temporary workspace); the model reference is the `(provider, modelId)` pair, so pass both to pick a configured model or neither for the project default — passing one alone throws.
+- The `approve` callback gates every tool call; **omitting it denies everything**.
+- `opts.thinkingLevel` (`"none" | "low" | "medium" | "high" | "xhigh" | "max"`) overrides the agent's default (`model.thinking_level` in `system_config.yaml`) for this turn only — raise it for hard questions, drop it for latency-sensitive calls like titling or classification.
+- Session lifetime is the app's memory model: reuse one Session for a stateful chat (context accumulates, as above), create one per request for stateless QA (the RAG recipe below); either way call `session.dispose()` when done to release background processes.
+- An Agent's behavior is edited in its `agent_state/` files (system_config.yaml, AGENTS.md, skills/), not in code.
+
+## Thinking and image messages
+
+Modern models think before answering and accept images; the stream and the input protocol carry both — use them instead of flattening everything to text.
+
+**Thinking (CoT) out.** Reasoning models stream `partial_thinking` (field `thinking`) before any `partial_text`, and a complete `thinking` message follows. Show the stream — a silent 20-second wait reads as a hang — but keep it in its own channel: a collapsible muted block per the web-design skill, auto-collapsed once answer text starts. Never concatenate thinking into the answer, store it as the answer, or cite from it; ignore its `fidelity` field (core's replay bookkeeping). Non-reasoning models simply never emit it — don't reserve UI space.
+
+**Images in.** Build image input with `imageUrlMessage` (a web URL or a base64 data URL) beside `userText` in the same `run` input:
+
+```ts
+import { imageUrlMessage, userText } from "@prismshadow/penguin-core";
+session.run([userText(question), ...images.map(imageUrlMessage)], { ... });
+```
+
+Browser flow: `<input type="file" accept="image/*">` plus paste/drag-drop → `FileReader.readAsDataURL` → POST `{ question, images: [dataUrl] }` → the server maps each entry to `imageUrlMessage`. Reject non-image MIME types and cap size (a data URL rides the context window; a few MB is plenty). Whether the session model actually sees pixels is the model config's `vision` flag (`penguin config model list` prints `vision=Y/-`; set via `--vision/--no-vision` on `model add`, default supported): with `vision=false` the core folds the image into an `[attached image: <path>]` line and the built-in image tools read it through the project's configured `vision_model` (`penguin config model vision --provider <group> --model-id <id> --root <data_dir>`) — the app still works, through a description instead of direct sight.
+
+**Other payloads worth handling** (always narrow with the guards first): `partial_tool_call` / `partial_tool_call_output` — surface as an activity line ("running `search`…") in apps that grant tools; `request_end` (event) — a non-`completed` `status` is the error signal (`auth` → ask for a key; `message` carries the failure detail; `retry_in_ms` announces a planned in-run retry, renderable as a countdown); `token_usage` (event) — session-cumulative and last-request counts, if the app shows cost; `compaction_begin` / `compaction_end` (events) — long-lived chats only, show a brief "context being compacted" notice. Everything else is safe to ignore.
+
+## Wiring in the user's tools
+
+When the app's agent must call the user's existing tools (scripts, internal CLIs, anything with an entry point), integrate them as **CLI commands** first: wrap each one as a small executable inside the project (a script under `tools/`, or the user's own binary), and describe it in the embedded agent's persona / `AGENTS.md` — name, what it does, one usage line. The agent invokes it through the built-in `exec_command` tool, so there is nothing to register: no schema to declare, arguments are flags, stdout is the result, the `approve` callback still gates every invocation, and the same command stays testable by hand.
+
+Add an MCP server (`tools.mcpServers` in `system_config.yaml`) only when a CLI wrapper cannot express the integration — a long-lived authenticated connection, or tool schemas the model must see typed. Otherwise the CLI form is the cheaper default and keeps the project self-contained.
+
+## RAG knowledge app
+
+The default recipe when the user wants an app that answers questions over a document set ("docs QA", "knowledge base", "chat with our docs", "become an expert on X"). The core contributes the agent loop only — retrieval is app code. Default to **lexical BM25**: no extra dependencies, no embedding credential, works offline. (Semantic upgrade: embed chunks via `@prismshadow/agenthub` — see the agenthub-models skill — and rank by cosine; only when an embedding-capable key is configured.)
+
+```
+my-app/
+  package.json       # "type": "module"; scripts: ingest / start
+  persona.md         # the embedded agent's role — write it per the agent-initialization skill
+  ingest.ts          # corpus/ → data/index.json; initializes penguin_data/, installs persona
+  rag.ts             # BM25 retrieval over the chunk index
+  server.ts          # POST /api/ask streams SSE; serves public/
+  public/index.html  # chat UI — build it per the web-design skill
+  corpus/            # collected source documents
+  data/index.json    # generated chunk index
+  penguin_data/      # agent data root (generated; model config lives here)
+```
+
+**Collect** — clone or fetch the sources into `corpus/`, keeping only text formats:
+
+```bash
+git clone --depth 1 <repo_url> corpus/<name>   # or curl pages into corpus/
+find corpus -type f ! -regex '.*\.\(md\|mdx\|txt\|html?\)$' -delete && rm -rf corpus/*/.git
+```
+
+**Ingest** (`ingest.ts`) — split on markdown headings, cap chunk size, write one JSON index; also initialize `penguin_data/`, install the persona and strip the skills the embedded agent doesn't need:
+
+```ts
+import fs from "node:fs";
+import path from "node:path";
+import { createAgent } from "@prismshadow/penguin-core";
+
+const ROOT = import.meta.dirname;
+const walk = (d: string): string[] =>
+  fs.readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? walk(path.join(d, e.name)) : [path.join(d, e.name)]);
+
+const STATE = path.join(
+  ROOT, "penguin_data", "default_project", "agents", "default_agent", "agent_state");
+await createAgent({ root: path.join(ROOT, "penguin_data") });
+fs.copyFileSync(path.join(ROOT, "persona.md"), path.join(STATE, "AGENTS.md"));
+// A fresh default_agent is initialized with the whole built-in Skill library, and every installed
+// Skill's metadata is injected into the system prompt of every /api/ask. This app only answers
+// from retrieved context, so remove them: unrelated skill descriptions cost tokens on each
+// question and pull the answer off-topic when one happens to match the wording of a question.
+fs.rmSync(path.join(STATE, "skills"), { recursive: true, force: true });
+
+const chunks: { id: number; source: string; heading: string; text: string }[] = [];
+for (const f of walk(path.join(ROOT, "corpus")).filter((f) => /\.(md|mdx|txt|html?)$/i.test(f))) {
+  const raw = fs.readFileSync(f, "utf8");
+  const text = /\.html?$/i.test(f) ? raw.replace(/<[^>]+>/g, " ") : raw;
+  const source = path.relative(ROOT, f);
+  let heading = path.basename(f);
+  for (const block of text.split(/^(?=#{1,3} )/m)) {
+    heading = block.match(/^#{1,3} (.+)/)?.[1] ?? heading;
+    for (let i = 0; i < block.length; i += 1500) {
+      const piece = block.slice(i, i + 1500).trim();
+      if (piece.length > 40) chunks.push({ id: chunks.length, source, heading, text: piece });
+    }
+  }
+}
+fs.mkdirSync(path.join(ROOT, "data"), { recursive: true });
+fs.writeFileSync(path.join(ROOT, "data", "index.json"), JSON.stringify(chunks));
+console.log(`indexed ${chunks.length} chunks`);
+```
+
+**Retrieve** (`rag.ts`) — standard BM25 (k1 = 1.2, b = 0.75); the tokenizer treats each CJK character as a token so Chinese queries work. The corpus-wide statistics (per-chunk term frequencies, document frequencies, average length) never change once the corpus is indexed, so build them **once** in `loadIndex` — a per-query rescan would make every question O(corpus):
+
+```ts
+import fs from "node:fs";
+import path from "node:path";
+
+export interface Chunk { id: number; source: string; heading: string; text: string }
+export interface Index {
+  chunks: Chunk[];
+  tf: Map<string, number>[]; // per-chunk term → count
+  len: number[];             // per-chunk token length
+  df: Map<string, number>;   // term → number of chunks containing it
+  avg: number;               // mean chunk length (BM25 length normalization)
+}
+
+const tokenize = (s: string): string[] => s.toLowerCase().match(/[a-z0-9]+|[一-鿿]/g) ?? [];
+
+export function loadIndex(): Index {
+  const chunks: Chunk[] = JSON.parse(
+    fs.readFileSync(path.join(import.meta.dirname, "data", "index.json"), "utf8"));
+  const tf: Map<string, number>[] = [];
+  const len: number[] = [];
+  const df = new Map<string, number>();
+  for (const c of chunks) {
+    const toks = tokenize(`${c.heading} ${c.text}`);
+    const m = new Map<string, number>();
+    for (const t of toks) m.set(t, (m.get(t) ?? 0) + 1);
+    for (const t of m.keys()) df.set(t, (df.get(t) ?? 0) + 1);
+    tf.push(m);
+    len.push(toks.length);
+  }
+  const avg = len.reduce((n, l) => n + l, 0) / Math.max(len.length, 1);
+  return { chunks, tf, len, df, avg };
+}
+
+export function search(index: Index, query: string, k = 6): Chunk[] {
+  const { chunks, tf, len, df, avg } = index;
+  const q = [...new Set(tokenize(query))];
+  const score = (i: number): number => {
+    let s = 0;
+    for (const t of q) {
+      const f = tf[i]!.get(t) ?? 0;
+      if (f === 0) continue;
+      const n = df.get(t) ?? 0;
+      s += Math.log(1 + (chunks.length - n + 0.5) / (n + 0.5)) *
+        (f * 2.2) / (f + 1.2 * (0.25 + (0.75 * len[i]!) / avg));
+    }
+    return s;
+  };
+  return chunks.map((_, i) => [score(i), i] as const)
+    .filter(([s]) => s > 0).sort((a, b) => b[0] - a[0]).slice(0, k)
+    .map(([, i]) => chunks[i]!);
+}
+```
+
+**Answer & serve** (`server.ts`) — one Session per request (stateless QA), retrieved chunks numbered into the prompt, deltas streamed over SSE, sources sent as the final event. A pure QA session needs no tool calls — deny every approval; a denied or tool-less turn terminates normally. Do **not** clear the toolset with `tools: { builtin: [] }`: an empty tools array is sent to the provider verbatim and some OpenAI-compatible endpoints reject it with a 400, which surfaces as a silent empty answer. Guard the request boundary — a malformed body must return 400, never reject the async handler (an unhandled rejection takes the whole server down) — and abort the run if the client disconnects mid-answer so you stop generating (and paying) for a page nobody is reading.
+
+```ts
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { createAgent, isModelMessage, userText } from "@prismshadow/penguin-core";
+import { loadIndex, search } from "./rag.ts";
+
+const ROOT = import.meta.dirname;
+const PUB = path.join(ROOT, "public");
+const agent = await createAgent({ root: path.join(ROOT, "penguin_data") });
+const index = loadIndex();
+const MIME: Record<string, string> = { ".html": "text/html", ".css": "text/css", ".js": "text/javascript" };
+
+http.createServer(async (req, res) => {
+  res.on("error", () => {}); // a client that vanishes mid-write must not throw an uncaught EPIPE
+  if (req.method === "POST" && req.url === "/api/ask") {
+    let question: string;
+    try {
+      let body = "";
+      for await (const part of req) body += part; // a mid-body connection reset rejects here — caught below, never fatal
+      const parsed = JSON.parse(body) as { question?: unknown };
+      if (typeof parsed.question !== "string" || !parsed.question.trim()) throw new Error();
+      question = parsed.question;
+    } catch {
+      res.writeHead(400, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "expected a JSON body { question: string }" }));
+      return;
+    }
+    const hits = search(index, question);
+    const context = hits.map((c, i) => `[${i + 1}] ${c.source} — ${c.heading}\n${c.text}`).join("\n\n");
+    const ac = new AbortController();
+    res.on("close", () => ac.abort()); // client navigated away → cancel the in-flight generation
+    // Create the Session BEFORE committing headers: a model-config failure then returns a real
+    // HTTP error instead of an unhandled rejection with a 200 already on the wire.
+    let session;
+    try {
+      session = await agent.createSession({ workspaceDir: ROOT });
+    } catch {
+      res.writeHead(503, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "no model configured yet — see the setup steps" }));
+      return;
+    }
+    res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+    try {
+      const prompt = `Answer in plain text (no Markdown; short paragraphs) from the context below; cite blocks inline as [1][2]. If the context is not enough, say so.\n\n${context}\n\nQuestion: ${question}`;
+      for await (const msg of session.run([userText(prompt)], { approve: async () => "deny", signal: ac.signal })) {
+        if (isModelMessage(msg)) {
+          const p = msg.payload;
+          if (p.type === "partial_text" && p.event_type === "delta" && !res.writableEnded)
+            res.write(`data: ${JSON.stringify({ delta: p.text })}\n\n`);
+          // Reasoning models: forward CoT on its own SSE field so the UI can collapse it.
+          if (p.type === "partial_thinking" && p.event_type === "delta" && !res.writableEnded)
+            res.write(`data: ${JSON.stringify({ thinking: p.thinking })}\n\n`);
+        }
+      }
+      // Sources carry the matched chunk text verbatim: the UI must be able to show the exact
+      // block behind each [n], not just a file link.
+      if (!res.writableEnded)
+        res.write(`data: ${JSON.stringify({ sources: hits.map((c) => ({ source: c.source, heading: c.heading, url: `/${c.source}`, text: c.text })) })}\n\n`);
+    } catch {
+      // The run failed after headers were sent, or the client left: surface an error event (best effort), then clean up.
+      if (!res.writableEnded) res.write(`data: ${JSON.stringify({ error: "generation failed" })}\n\n`);
+    } finally {
+      session.dispose();
+      if (!res.writableEnded) res.end();
+    }
+    return;
+  }
+  const pathname = (req.url ?? "/").split("?")[0] ?? "/";
+  // /corpus/* serves the source documents read-only, so citation links resolve to real files.
+  const inCorpus = pathname.startsWith("/corpus/");
+  const base = inCorpus ? path.join(ROOT, "corpus") : PUB;
+  const rel = inCorpus
+    ? pathname.slice("/corpus/".length)
+    : pathname === "/"
+      ? "index.html"
+      : pathname.slice(1);
+  const file = path.normalize(path.join(base, rel));
+  if (file.startsWith(base + path.sep) && fs.existsSync(file) && fs.statSync(file).isFile()) {
+    res.writeHead(200, { "content-type": MIME[path.extname(file)] ?? "text/plain" });
+    res.end(fs.readFileSync(file));
+  } else {
+    res.writeHead(404);
+    res.end();
+  }
+}).listen(Number(process.env.PORT ?? 4630), () => console.log("http://localhost:4630"));
+```
+
+**UI** (`public/index.html`) — a chat interface built per the web-design skill: message list, streamed assistant text appended delta by delta (plain text under the output contract below: escape, split blank-line paragraphs, style the `[n]` markers), `thinking` events into the collapsible reasoning block (collapse it when the first answer delta arrives), the final `sources` event rendered as citations (pill chips or accordion source cards), an empty state inviting the first question with **3–4 example questions the corpus can actually answer** (clicking one submits it), and a visible error state when `/api/ask` fails. Citations must satisfy both of these, never bare text:
+
+- **Reveal the original chunk**: clicking a citation chip (or an inline `[n]`) opens a popover/panel showing the matched chunk's `text` from the sources event **verbatim** — the numbering maps 1:1 to the context blocks in the prompt, so `[n]` always reveals exactly the block the answer drew on.
+- **Link to the real document**: inside the popover, `<a href="<url>" target="_blank">` using the `url` field (`/corpus/<path>`, which this server serves) — clicking the chip itself opens the popover, the document link lives within it. When the corpus was cloned from a public repository, prefer mapping the path to the canonical upstream page instead (e.g. the GitHub blob URL derived from the clone URL).
+
+**Output format and language** — settle both up front, in the persona and the retriever, not in the UI:
+
+- **No Markdown pipeline — set the output format instead**: instruct the embedded agent (in `persona.md` and the per-request prompt) to answer in plain text — short paragraphs separated by blank lines, citations as bare `[n]`, no Markdown syntax. The UI then only escapes the text, splits paragraphs and styles the `[n]` markers; there is no renderer to build. When richer structure genuinely matters, have the model emit a small whitelisted HTML subset (`<p> <ul> <li> <strong> <code>`) and sanitize to exactly that whitelist before inserting — never inject unsanitized model output.
+- **Cross-language retrieval**: the corpus and the user often speak different languages (English docs, Chinese questions), and BM25 is purely lexical — a Chinese question scores zero against English chunks. At ingest time derive a small bilingual keyword map for the corpus's core vocabulary (10–20 domain terms, e.g. `权限 → permissions / allow / deny`, `钩子 → hooks`) and expand query tokens through it in `search()` before scoring; keep the per-character CJK tokenizer. The persona already pins the answer language to the question's language.
+
+**Persona** (`persona.md`) — the embedded agent's role, written per the agent-initialization skill. Shape: one role sentence ("You are an expert on X; you answer strictly from the provided context blocks"), citation and refusal rules, plain-text output (no Markdown — the output contract above), answer language follows the question.
+
+## Verify before you hand over
+
+Never declare the app done without running it:
+
+1. `npm install` succeeds (or the workspace route builds).
+2. Model configured for `penguin_data` (CLI or env var; no usable key → see Setup: ask the user to add one to this agent's key vault, and report the app as unverified for now).
+3. `npm run ingest` prints `indexed N chunks` with N > 0.
+4. Start `npm start` in the background, then ask a real question:
+   `curl -N -sS -X POST localhost:4630/api/ask -H 'content-type: application/json' -d '{"question":"<something the corpus answers>"}'` — expect streamed `data:` deltas ending in a `sources` event that carries `source`, `url` **and the matched chunk `text`** per hit. If nothing streams, the model call failed: re-check step 2 and the provider endpoint before touching the code.
+   Then `curl` one of the returned source `url`s — it must return the document, not a 404 (citation links have to resolve).
+5. Open the UI (or screenshot it) to confirm the layout renders.
+
+Fix any failure and re-verify; when the app accepts image input, one verification question must include a real image. Report with backtick-wrapped relative paths (`server.ts`, `public/index.html`, …), how to start the app, and the assumptions you made.

package/skills/unified-llm-api/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: unified-llm-api
+description: Call model APIs through @prismshadow/agenthub — streaming text generation, image generation, speech synthesis, embeddings and the supported-model registry with one client.
+---
+
+# Unified LLM API (AgentHub)
+
+`@prismshadow/agenthub` is a unified TypeScript client for model APIs: streaming text, image generation, speech synthesis and embeddings behind one entry point.
+
+```bash
+npm install @prismshadow/agenthub
+```
+
+The main entry point is `AutoLLMClient`:
+
+```ts
+import { AutoLLMClient } from "@prismshadow/agenthub";
+
+const client = new AutoLLMClient({ model: "<model_id>", apiKey: "<key>", baseUrl: "<url>", clientType: "<type>" });
+```
+
+`apiKey`, `baseUrl` and `clientType` are optional (see routing below). The package also exports `listSupportedModels` (the model registry) and the error classes `AgentHubError`, `UnsupportedParameterError`, `EmptyResponseError` and `ToolCallArgumentParseError`.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use agenthub-models skill") without a concrete task, ask the user what they want to build. Do not write code until the requirement is clear.
+
+**Important prerequisite — set the key up first, then develop.** When the script is an AI app you are building for the user, have them add the model API key in **this agent's key vault** (gear icon on its card, Agents page → settings → key vault tab) *before* you start, so the credential is in your shell environment. If the app stores its own model config, keep its Penguin data root **inside the CWD workspace** (`--root ./penguin_data`), never `~/.penguin`. Model ids can come from the penguin CLI catalog and the id table below.
+
+Check for a usable API key before writing code — the client needs one for whichever provider you target:
+
+```bash
+env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI|ZAI|MOONSHOT|MINIMAX)_API_KEY" || echo none
+```
+
+Vault keys also appear in your Vault Keys section. **Only two sources count as a usable key**: a vault-injected environment variable (the check above), or — when the app stores its own model config — a key already configured in the app's own data root (`penguin config model list --root <data_dir>`). Keys living in the global `~/.penguin` or any other `.penguin` directory do **not** count — a bare `penguin config model list` (no `--root`) reads the global store, because the CLI defaults to the global root unless `--root` is given, so a key showing up there proves nothing for your script and must never be used or copied.
+
+If neither counted source yields a usable key, **stop immediately and ask the user to configure one — do not write code, and do not keep calling tools to retry**: ask them to add one in the agent's **key vault** (gear icon on the agent's card, Agents page → settings → key vault tab); vault values reach your shell environment on the next task. Re-checking the environment or the vault in a loop just wastes turns — one clear check, then hand back to the user.
+
+Keep model API keys **project-local**: for an app that stores its own model config, write the key into the project under the working directory with the penguin CLI, **always passing `--root <data_dir>` for a directory inside the current working directory** (`penguin config model add --root ./penguin_data --provider <group> --model-id <id> --api-key <key>`) — without `--root` it writes to the global `~/.penguin/data` instead. `--provider` is required alongside `--model-id`: a model entry is the `(provider, model_id)` pair and the group is never inferred (use `custom` for an endpoint outside the built-in groups). Otherwise rely on vault-injected environment variables. Never read, copy or fall back to model keys stored in the user's global `~/.penguin` directory — that config belongs to the person running Penguin, not to your script.
+
+## Model IDs
+
+Use exact model ids. If an id is not in the table below and the user has not given one, ask the user to confirm the exact id before writing code.
+
+| Family           | Official IDs                                                          | Gateway variants                                                                                                                                |
+| ---------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gemini 3.7       | `gemini-3.7-flash`                                                    | OpenRouter `google/gemini-3.7-flash`                                                                                                            |
+| Gemini 3.6       | `gemini-3.6-flash`, `gemini-3.5-flash-lite`                           | —                                                                                                                                               |
+| Gemini 3         | `gemini-3.1-pro-preview`, `gemini-3.5-flash`, `gemini-3.1-flash-lite` | —                                                                                                                                               |
+| Gemini 3 image   | `gemini-3.1-flash-image`, `gemini-3-pro-image-preview`                | —                                                                                                                                               |
+| Gemini 3 TTS     | `gemini-3.1-flash-tts-preview`                                        | —                                                                                                                                               |
+| Gemini embedding | `gemini-embedding-2`                                                  | —                                                                                                                                               |
+| Claude 5         | `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`                  | OpenRouter `anthropic/claude-fable-5`, `anthropic/claude-opus-5`, `anthropic/claude-sonnet-5`                                                   |
+| Claude 4         | `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-opus-4-8`             | OpenRouter `anthropic/claude-opus-4.8`, `anthropic/claude-opus-4.7`                                                                             |
+| GPT-5.6          | `gpt-5.6` (routes to sol), `gpt-5.6-terra`, `gpt-5.6-luna`            | OpenRouter `openai/gpt-5.6-sol`, `openai/gpt-5.6-terra`, `openai/gpt-5.6-luna`                                                                  |
+| GPT-5.5 / 5.4    | `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`                  | OpenRouter `openai/gpt-5.5`, `openai/gpt-5.5-pro`, `openai/gpt-5.4`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-nano`, `openai/gpt-5.4-pro`         |
+| OpenAI embedding | `text-embedding-3-small`, `text-embedding-3-large`                    | —                                                                                                                                               |
+| MiniMax M3       | `MiniMax-M3`                                                          | OpenRouter `minimax/minimax-m3`                                                                                                                 |
+| Kimi K3          | `kimi-k3`                                                             | OpenRouter `moonshotai/kimi-k3`                                                                                                                 |
+| Kimi K2.7 Code   | —                                                                     | SiliconFlow `moonshotai/Kimi-K2.7-Code`; Fireworks AI `accounts/fireworks/models/kimi-k2p7-code`                                                |
+| Kimi K2.6        | `kimi-k2.6`                                                           | OpenRouter `moonshotai/kimi-k2.6`; SiliconFlow `Pro/moonshotai/Kimi-K2.6`                                                                       |
+| DeepSeek V4      | `deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp` | OpenRouter `deepseek/deepseek-v4-pro-0813`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-flash-0731`, `deepseek/deepseek-v4-flash-vision-exp`; Fireworks AI `accounts/fireworks/models/deepseek-v4-flash-0731`; SiliconFlow `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` |
+| GLM 5.3          | `glm-5.3`, `glm-5.3-flash`                                            | OpenRouter `z-ai/glm-5.3`, `z-ai/glm-5.3-flash`                                                                                                 |
+| GLM 5.2          | `glm-5.2`                                                             | OpenRouter `z-ai/glm-5.2`; SiliconFlow `zai-org/GLM-5.2`                                                                                        |
+| GLM 5.1          | `glm-5.1`                                                             | —                                                                                                                                               |
+| Qwen 3.8 Max     | —                                                                     | OpenRouter `qwen/qwen3.8-max`                                                                                                                   |
+| Qwen 3.8 Flash   | —                                                                     | Qwen DashScope `qwen3.8-flash`                                                                                                                  |
+| Qwen 3.6         | —                                                                     | OpenRouter `qwen/qwen3.6-35b-a3b`; SiliconFlow `Qwen/Qwen3.6-35B-A3B`                                                                           |
+| Inkling          | —                                                                     | OpenRouter `thinkingmachines/inkling`; Fireworks AI `accounts/fireworks/models/inkling`                                                         |
+
+The image endpoint dropped its preview suffix: `gemini-3.1-flash-image-preview` is deprecated, use `gemini-3.1-flash-image`.
+
+`glm-5.3-flash` is the one GLM model that reads images (`@prismshadow/agenthub` >= 0.4.8). The GLM client sends an `image_url` item as an `image_url` part, in a prompt and in a tool result alike, and both an HTTP(S) URL and a base64 data URL pass through unchanged. The version match is case-insensitive, so the gateway spellings `z-ai/glm-5.3-flash` and `zai-org/GLM-5.3-Flash` are recognised too. Every other GLM id refuses an image rather than dropping it — `GLM <id> does not support image inputs.` in a prompt, `GLM <id> does not support images in tool results.` in a tool result — and that includes `glm-5v-turbo`.
+
+Gateway model lists can be queried online:
+
+```bash
+curl https://openrouter.ai/api/v1/models
+curl --request GET --url https://api.siliconflow.cn/v1/models --header 'Authorization: Bearer <token>'
+```
+
+## Supported-model registry
+
+`listSupportedModels(currency?)` returns the models AgentHub itself knows how to route, so ids, endpoints, modalities, context windows and prices can be read from the package instead of being hardcoded:
+
+```ts
+import { listSupportedModels } from "@prismshadow/agenthub";
+
+for (const m of listSupportedModels()) {
+  console.log(m.model, m.base_url, m.client, m.context_window, m.pricing?.prompt_tokens);
+}
+```
+
+- Each `SupportedModel` is `{ model, base_url, client, input_modalities, output_modalities, context_window?, pricing? }`. The `(model, base_url, client)` triple maps straight onto the constructor: `new AutoLLMClient({ model, baseUrl: base_url, clientType: client })`.
+- Modalities are `"Text" | "Image" | "Video" | "Audio" | "Embed"`. Coverage includes the official vendor endpoints plus the OpenRouter and SiliconFlow gateways; `context_window` and `pricing` are omitted where the platform publishes no authoritative value (image and TTS models, for instance).
+- `pricing` is per million tokens, keyed by the same usage buckets as `usage_metadata`: `prompt_tokens` (non-cached input), `thoughts_tokens` / `response_tokens` (both the output price) and optional `cached_tokens` (cache-hit price). Values are stored in USD; pass `listSupportedModels("CNY")` to convert at 7 CNY/USD.
+
+The registry is the curated current line-up, so prefer it when picking a model or estimating cost. It is not the routing table, and it lags in both directions: older ids in the table above (`gpt-5.4`, `claude-opus-4-7`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite`) still route fine without appearing in it, and a newly launched id can route before the registry carries it. For an id the registry omits, take the context window and price from the vendor's own page.
+
+## Routing and credentials
+
+- Without `clientType`, the client auto-routes by model id substring, in this order: `minimax-m3` (exact), `gemini-3*` / `gemini-embedding`, `claude` 4-6/4-7/4-8/-5, `gpt-5.4`/`gpt-5.5`/`gpt-5.6`, `glm-5` (whole series, 5.3 included), `kimi-k3`/`kimi-k2.5`/`kimi-k2.6`, `deepseek-v4`, `ant-messages`, `openai-responses`, `openai`+`embedding` (embeddings), `openai` (chat). Ids matching none of these throw. Most gateway variants in the table above hit the same substrings, so they route to the right family — just set `baseUrl` to the gateway endpoint.
+- Three generic protocol clients cover everything else (all take `baseUrl` + `apiKey`):
+  - `clientType: "openai-chat"` — any OpenAI Chat Completions compatible endpoint (gateway models, Qwen via OpenRouter/SiliconFlow or DashScope `https://dashscope.aliyuncs.com/compatible-mode/v1`, local vLLM, …). Renamed from `openai` in AgentHub 0.4.2; the bare `openai` string still routes as a deprecated alias.
+  - `clientType: "openai-responses"` — OpenAI Responses-compatible endpoints (OpenAI, OpenRouter, DeepSeek, Z.AI, MiniMax all serve one).
+  - `clientType: "ant-messages"` — Anthropic Messages-compatible endpoints (Anthropic, OpenRouter `https://openrouter.ai/api`, DeepSeek `https://api.deepseek.com/anthropic`, Z.AI, MiniMax).
+- Exception: an id served by an OpenAI-compatible gateway that still matches a first-party substring (e.g. OpenRouter's `google/gemini-3.7-flash`, `anthropic/claude-sonnet-5` or `openai/gpt-5.6-sol` on the `/api/v1` endpoint) would auto-route to the vendor protocol client — and a dotted id like `anthropic/claude-opus-4.8` matches nothing and throws. Always pass an explicit `clientType` for gateway ids; never rely on the id. Routing reads `clientType` (or the model id) as a plain lowercased string and never looks at `baseUrl`, so the vendor prefix gives no protection.
+- OpenRouter serves both protocols at `https://openrouter.ai/api/v1`, so its `openai/*` ids work with `clientType: "openai-responses"` as well as `"openai-chat"`; use Responses when you want reasoning items round-tripped.
+- The first-party `deepseek-v4` client posts to `{baseUrl}/responses` (AgentHub 0.4.6 moved it off Chat Completions). A self-hosted endpoint serving a `deepseek-v4*` id over Chat Completions must therefore pass `clientType: "openai-chat"` explicitly rather than rely on id routing.
+- API key: constructor parameter first, then the provider environment variable — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY` (also for `ant-messages`), `OPENAI_API_KEY` (also for `openai-chat`/`openai-responses`), `GEMINI_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_API_KEY`. Base URLs read the same names with `_BASE_URL`.
+
+## Streaming text
+
+```ts
+for await (const event of client.streamingResponseStateful({
+  message: { role: "user", content_items: [{ type: "text", text: "Hello" }] },
+  config: {},
+})) {
+  for (const item of event.content_items) {
+    if (item.type === "text") process.stdout.write(item.text);
+  }
+}
+```
+
+- Each `event` is a `UniEvent`: `event_type` is `start` | `delta` | `stop`, and `content_items` carry the increments.
+- `config` accepts `max_tokens`, `temperature`, `system_prompt`, `thinking_level` (the `ThinkingLevel` enum, `NONE` to `MAX`), `tool_choice`, `prompt_caching`, `fast_mode` and `tools`.
+- `streamingResponseStateful` keeps conversation history inside the client; manage it with `getHistory()` / `setHistory(history)` / `clearHistory()`. The stateless variant is `streamingResponse({ messages, config })`.
+
+## Config parameters the model may reject
+
+A config value the target client cannot honour throws `UnsupportedParameterError` (an `AgentHubError` carrying `client` and `parameter`) while building the request, before anything reaches the network:
+
+```ts
+import { UnsupportedParameterError } from "@prismshadow/agenthub";
+
+try {
+  // ...
+} catch (err) {
+  if (err instanceof UnsupportedParameterError) console.error(err.parameter, err.message);
+}
+```
+
+- `thinking_level` never throws: every client maps each level onto the closest one the model supports, and `MAX` (the tier above `XHIGH`, added in AgentHub 0.4.4) degrades silently wherever the vendor has no such tier — Gemini and MiniMax M3 stop at `high`. Kimi K3 reasons unconditionally, so `NONE` degrades to its lowest effort rather than disabling thinking; GLM-5.2 sends `reasoning_effort` alongside its `thinking` block and only `NONE` disables it. GLM-5.3 thinks unconditionally (`NONE` degrades to the light `low` effort) and clamps `reasoning_effort` to `low`/`high`/`max`; `gemini-3.7-*` clamps to `low`/`medium`/`high` (`NONE` degrades to `low`). DeepSeek V4 accepts `low`/`high`/`max` and maps `medium` and `xhigh` onto `high` server-side, so since 0.4.4 `LOW` sends `low` (it sent `high`) and `XHIGH` sends `high` (it sent `max`).
+- `temperature` is rejected outright by Gemini 3.6/3.7 — those generations deprecated the sampling parameters, so the client refuses them instead of sending a value the API ignores. GPT-5.5/5.6, the whole Claude 4.6+ family (4.6 included since AgentHub 0.4.2), DeepSeek V4, Kimi K2.6 and Kimi K3 accept only the protocol default `1.0` and reject any other value. Gemini 3, GLM and the generic protocol clients (`openai-chat` / `openai-responses` / `ant-messages`) pass it through.
+- `tool_choice`: `"auto"` is safe everywhere. Claude accepts a single forced tool name; DeepSeek V4 and Kimi K2.6 allow `"auto"` / `"none"`; Kimi K3 adds `"required"` but refuses a specific tool (K2.x also rejects `"required"`); GLM only accepts `"auto"`.
+- `prompt_caching`: every client accepts `PromptCaching.ENABLE` and rejects the other values — caching is on by default and Kimi K3 caches context automatically.
+- `fast_mode` (`UniConfig`, AgentHub 0.4.2): fast processing at premium pricing. OpenAI-protocol clients (`openai-chat`, `openai-responses`, `gpt-5.6`, `minimax-m3`) map it to `service_tier: "priority"`; Anthropic-protocol clients (`ant-messages`, `claude-5`) map it to `speed: "fast"` with a beta header (an Anthropic research preview limited to Claude Opus 5 / Opus 4.8 — organizations without access get a 429). Clients without a fast tier (Gemini, GLM, Kimi, DeepSeek, embeddings, Claude 4.6 models) raise `UnsupportedParameterError`; DeepSeek and Z.AI's OpenAI-compatible endpoints simply ignore the tier.
+
+Leave a parameter unset and the protocol default applies, which is the portable choice when a script must run against several families.
+
+## Image generation
+
+Use a Gemini image model (see Model IDs) and set `config.image_config` (optional `aspect_ratio`, and `image_size` of `"1K"` | `"2K"`):
+
+```ts
+import fs from "node:fs";
+
+const client = new AutoLLMClient({ model: "gemini-3.1-flash-image" });
+for await (const event of client.streamingResponseStateful({
+  message: { role: "user", content_items: [{ type: "text", text: "A penguin on a glacier" }] },
+  config: { image_config: { aspect_ratio: "16:9", image_size: "2K" } },
+})) {
+  for (const item of event.content_items) {
+    if (item.type === "inline_data") fs.writeFileSync("image.png", item.data);
+  }
+}
+```
+
+Images arrive as `inline_data` content items (`data` is a Buffer, with `mime_type`).
+
+## Speech synthesis
+
+Use a Gemini TTS model (`gemini-3.1-flash-tts-preview`) and set `config.tts_config`:
+
+```ts
+config: { tts_config: [{ voice: "Kore" }] }
+```
+
+- One entry → single voice; two entries → multi-speaker, and each entry must also set `speaker`.
+- The `inline_data` output is raw PCM (24kHz 16-bit mono) — wrap it in a WAV header yourself before saving as `.wav`.
+
+## Embeddings
+
+Two routes:
+
+- Gemini: a model whose id contains `gemini-embedding` auto-routes (`gemini-embedding-2`).
+- Any OpenAI-compatible embeddings endpoint: pass `clientType: "openai-embedding"` (plus `baseUrl` and `apiKey` as needed) — ids like `text-embedding-3-small` / `text-embedding-3-large` match no auto-route substring and would throw without it.
+
+Optional `config.embedding_config`:
+
+```ts
+config: { embedding_config: { dimensions: 768 } }
+```
+
+The output arrives as `embedding` content items (`embedding` is a number array).