@a2f0/agent-tool 0.1.11 → 0.1.13

package/README.md

@@ -11,6 +11,9 @@ version management, and portable skills for Claude Code, Codex, and OpenCode.
   `bun.lock` in sync.
 - **Share skills**: install the same workflow instructions where each harness
   discovers them, and check them in CI.
+- **Render brand images**: build app icons, splash screens, favicons, and store
+  graphics from the SVGs in `assets/brand/`, with every size and destination
+  declared in `agent-tool.json`.
 - **Compact output**: run noisy commands with full private logs and bounded
   diagnostics, keeping routine output out of an agent's context.
 
@@ -109,6 +112,8 @@ agent-tool skills install --apply
 | `skills list` | List embedded portable skills |
 | `skills install [--harness all\|claude\|codex\|opencode] [--apply]` | Preview by default; install or update managed skills |
 | `skills check [--harness all\|claude\|codex\|opencode]` | Read-only CI check for current managed skills |
+| `images list [target...]` | List the files each image target writes, without rendering |
+| `images build [target...] [--out dir]` | Render image targets from `assets/brand/*.svg`; `--out` redirects one target |
 | `init` / `config show` | Create or inspect data-only project policy |
 | `doctor` | Inspect local versions and required CLI flags without running a model |
 
@@ -256,6 +261,38 @@ the commit restores the manifests, lockfile, and index, unless HEAD or other
 paths changed, in which case it leaves that state for inspection. Repeating
 against the same base creates no commit.
 
+### Images
+
+`images` declares named targets of brand images rendered from SVG sources in
+`assets/brand/`. Each output names its file, pixel size or variants (such as
+Android densities or `@2x`/`@3x`), and the layers composed into it:
+
+```json
+{
+  "schemaVersion": 1,
+  "images": {
+    "targets": {
+      "ios": {
+        "dir": "ios/App/Assets.xcassets",
+        "outputs": [
+          {
+            "path": "AppIcon.appiconset/AppIcon.png",
+            "size": 1024,
+            "opaque": true,
+            "layers": [{ "source": "background", "fit": "cover" }, { "source": "logo", "scale": 0.7 }]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+`agent-tool images build ios` writes PNG, ICO, SVG, and Android color resource
+outputs with a bundled WebAssembly renderer, so builds need no ImageMagick or
+librsvg and render identically on every machine. See the
+[image reference](docs/images.md) for every setting.
+
 ## Portable skills
 
 Canonical skills live in `skills/`. The build embeds them, and the installer
@@ -294,52 +331,10 @@ anything. Use the same `--harness` for install and check.
 
 ### Dependency upgrades
 
-Invoke `update-dependencies` in Claude Code, Codex, or OpenCode to inventory and
-upgrade package dependencies, runtimes, mise tools, Actions, native toolchains,
-Ansible, Terraform providers/modules, and other repository-owned pins. It reads
-official migration guides, upgrades coupled dependencies together, resolves
-deprecations, and records validated, constrained, and skipped upgrades. It follows
-the repository's existing upgrade skills and support policy.
-
-Read-only advisory checks cover baseline and candidate lockfiles, including
-resolved transitive and native dependencies. The skill traces findings to their
-owning dependency and prefers an upstream-supported fix. A scoped security patch
-override requires compatibility evidence, a regression check of the affected
-integration, and a documented removal condition; blind audit fixes and blanket
-compatibility overrides are excluded. Remaining advisories and audit limits are
-reported explicitly. For published packages, the skill also checks tarballs and
-consumer installs with their documented supported managers, including override
-syntax and runtime requirements.
-
-The skill requires a dry run before any infrastructure mutation, including ones
-triggered by hooks or CI on push/merge. Resource destruction or replacement, and
-previews that cannot establish safety, skip the affected upgrade group. A Wrangler
-bundle dry run alone does not prove remote resource safety. The skill does not
-itself authorize deployment or shipping; use `ship-pr` when requested.
-For Wrangler, the skill treats remote D1 migration listing as potentially
-mutating and holds deployment when a migration is pending or the upload cannot
-be proven to match the validated preview artifacts.
-
-For a full refreshed Terraform saved plan, export its private JSON and screen it:
-
-```sh
-terraform show -json /private/path/upgrade.tfplan > /private/path/upgrade.json
-agent-tool dependencies check-terraform-plan /private/path/upgrade.json
-```
-
-The check returns JSON with `ok`, `issues`, and `resourceActions`, and exits 1 for
-unsafe or unsupported plans. It rejects delete and replacement actions, unknown
-actions, destructive drift, incomplete/deferred plans, unpassed checks, and opaque
-provider action invocations. It requires JSON format 1.x and `complete: true`
-(available from Terraform 1.8); older plans without completeness evidence fail.
-OpenTofu's current JSON format omits `complete` and is not accepted; report that
-limitation rather than fabricating the field.
-Missing `resource_changes` is valid for a complete empty or output-only plan;
-removing an output is not a resource deletion. Invalid JSON fails without echoing
-the input. The command never applies or contacts a backend and prints no attribute
-values. It cannot establish plan freshness, environment/identity, provider or
-provisioner side effects, or authorization; inspect those before deploying and
-apply the exact approved saved plan. Keep state and plans out of Git.
+Invoke `update-dependencies` to upgrade repository-owned dependencies, runtimes,
+and tool pins with compatibility checks and safe infrastructure previews.
+See the [dependency upgrade guide](docs/dependency-upgrades.md) for advisory
+checks, preview limits, the Terraform plan guard, and maintaining upgrade records.
 
 ## Review guarantees and limits
 
@@ -435,6 +430,7 @@ yet.
 ## Further reading
 
 - [Design](docs/design.md): component boundaries and implementation choices.
+- [Images](docs/images.md): brand image sources, targets, and output settings.
 - [Validation record](docs/validation.md): observed test results and their
   limits.
 - [Extraction record](docs/extraction.md): the projects this tool was extracted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
   "license": "UNLICENSED",
@@ -33,5 +33,8 @@
   "devDependencies": {
     "@types/bun": "1.4.2",
     "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "@resvg/resvg-wasm": "2.6.2"
   }
 }

package/skills/update-dependencies/SKILL.md

@@ -6,8 +6,9 @@ description: Update a repository's dependency manifests, lockfiles, runtimes, to
 # Update Dependencies
 
 Use the repository's package managers and installed `agent-tool`. Read `AGENTS.md`,
-README, linked setup/release documents, and repository-owned upgrade skills before
-editing. Follow their hooks, version policy, checks, and requested stopping point.
+README, existing dependency-maintenance notes, linked setup/release documents,
+and repository-owned upgrade skills before editing. Follow their hooks, version
+policy, checks, and requested stopping point.
 Update applicable dependencies throughout the repository, including workspaces
 and examples. This skill does not authorize deploying, merging, publishing, or
 changing global tools; use existing user authorization and `ship-pr` when shipping
@@ -139,7 +140,8 @@ Source: [Ansible check mode limits](https://docs.ansible.com/projects/ansible/la
 ## Inventory and choose compatible targets
 
 Record each dependency source, current resolved version, latest stable candidate,
-selected target, compatibility constraints, upstream migration links, and checks.
+selected target, compatibility constraints, upstream migration links, and checks
+in the run ledger described under Report.
 Query authoritative registries, official releases, support matrices, and migration
 guides at execution time; do not treat remembered versions or prereleases as
 latest stable. Inspect runtime requirements, peer dependencies, ABI/API changes,
@@ -246,11 +248,33 @@ changed HEAD. Check deployment safety again before its push/open/merge operation
 
 ## Report
 
-Keep a compact ledger of old/selected versions, completed migrations, validation
-and warning results, preview environment/commit/tool versions and safe action
-summary, and every skipped/constrained dependency with the reason. Include baseline
-and final audit results, security overrides with their rationale and removal
-condition, unresolved advisories, and audit coverage limits. For shipping,
-include branch, reviewed commit/verdict, PR, merge, publish/deploy result, and final
-checkout state. For a repository sweep, keep one entry per repository, including
-unready or unchanged checkouts. Do not publish credentials, state, or plan contents.
+Keep run-specific evidence in the upgrade PR body or a linked PR comment: the
+inventory and old/selected versions, completed migrations, validation and warnings,
+baseline/final audits and coverage limits, preview environment/commit/tool versions
+and safe action summary, and skipped/constrained dependencies with reasons. Include
+security overrides, their rationale and removal condition, and unresolved advisories.
+If no PR is requested, provide this ledger in the task report; reporting does not
+authorize opening a PR or issue. For a sweep, keep one entry per repository,
+including unready and unchanged checkouts, and use an existing tracking issue only
+when explicitly requested. Never create an issue merely to store upgrade evidence.
+
+Keep durable repository guidance focused on what the next upgrade needs: current
+compatibility constraints, intentional pins/overrides, unresolved advisories, and
+reusable repository-specific procedures. Prefer the existing maintenance document;
+otherwise create `docs/dependency-upgrades.md` (or the repository's equivalent)
+only when there is substantive guidance to preserve. For each constraint, record
+its rationale, upstream advisory/migration/issue link or originating PR, and the
+condition and check for removing or revisiting it. Do not copy version inventories,
+audit output, validation/preview receipts, or dated run journals into that document.
+
+On every upgrade, reconcile the existing maintenance document against the final
+dependency graph and checks: update constraints in place, remove resolved entries,
+and link the PR for historical evidence. Keep the root README focused on purpose,
+setup, supported requirements, and normal usage, with a concise maintenance link
+when needed. Keep dependency-maintenance guidance in `AGENTS.md` to a short
+routing rule and link; do not accumulate upgrade reports in either entrypoint
+or duplicate the maintenance document.
+
+For shipping, report the branch, reviewed commit/verdict, PR, merge, publish/deploy
+result, and final checkout state. Keep full logs private; never publish credentials,
+state, or plan contents in any of these locations.

package/src/cli.ts

@@ -32,6 +32,8 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
   skills list
   skills install [--harness <all|claude|codex|opencode>] [--apply]
   skills check [--harness <all|claude|codex|opencode>]
+  images list [target...]               JSON files each image target writes
+  images build [target...] [--out <dir>]  Render assets/brand/*.svg per agent-tool.json
   init                                  Create agent-tool.json without overwriting
   config show
   doctor                                JSON versions and supported review flags
@@ -85,6 +87,22 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
     const result = doctor(process.cwd()); output(result);
     return result.tools.find(item => item.name === "git")?.compatible && result.tools.some(item => ["claude", "codex", "opencode"].includes(item.name) && item.compatible) ? 0 : 1;
   }
+  if (command === "images") {
+    const action = args.shift();
+    usage(action === "list" || action === "build", "Usage: agent-tool images <list|build> [target...] [--out <dir>]");
+    const names: string[] = [];
+    let out: string | undefined;
+    while (args.length) {
+      const value = args.shift()!;
+      if (value === "--out") { usage(action === "build" && out === undefined && !!args[0] && !args[0].startsWith("--"), "--out requires one directory and applies to build."); out = args.shift(); }
+      else { usage(!value.startsWith("-"), `Unknown images argument '${value}'.`); names.push(value); }
+    }
+    const { images } = loadConfig();
+    // Loaded on demand so other commands never initialize the renderer.
+    return import("./images/build").then(async ({ buildImages, listImages }) => {
+      output(action === "list" ? listImages(images, names) : await buildImages(process.cwd(), images, names, out)); return 0;
+    });
+  }
   if (command === "skills") {
     const action = args.shift();
     if (action === "list") { usage(args.length === 0, "Usage: agent-tool skills list"); output(Object.keys(BUNDLED_SKILLS)); return 0; }

package/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { parseImages, type ImagesConfig } from "./images/config";
 
 export interface RequiredCheck {
   name: string;
@@ -13,6 +14,7 @@ export interface AgentToolConfig {
   review: { claudeModel: string | null; codexModel: string | null; opencodeModel: string; opencodeVariants: Record<string, string>; timeoutMs: number };
   versions: { packages: string[] | null; bundles: string[]; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
   pr: { rejectClaudeBranding: boolean };
+  images: ImagesConfig;
 }
 
 export const DEFAULT_CONFIG: AgentToolConfig = {
@@ -26,6 +28,7 @@ export const DEFAULT_CONFIG: AgentToolConfig = {
   review: { claudeModel: null, codexModel: null, opencodeModel: "deepseek/deepseek-v4-pro", opencodeVariants: { low: "low", medium: "medium", high: "high", xhigh: "max", max: "max" }, timeoutMs: 600_000 },
   versions: { packages: null, bundles: [], lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
   pr: { rejectClaudeBranding: false },
+  images: { targets: {} },
 };
 
 function object(value: unknown, name: string): Record<string, unknown> {
@@ -57,6 +60,7 @@ export function parseConfig(source: string): AgentToolConfig {
     keys(settings, Object.keys(result[section]), section);
     Object.assign(result[section], settings);
   }
+  if (input.images !== undefined) result.images = parseImages(input.images);
   const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };
   if (typeof result.subject.conventional !== "boolean") invalid("subject.conventional");
   if (!Number.isSafeInteger(result.subject.maxLength) || result.subject.maxLength < 1) invalid("subject.maxLength");

package/src/images/build.ts

@@ -0,0 +1,160 @@
+import { initWasm, Resvg } from "@resvg/resvg-wasm";
+import wasm from "@resvg/resvg-wasm/index_bg.wasm" with { type: "file" };
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { composeSvg, type Canvas } from "./compose";
+import { expand, format, SOURCE_DIRECTORY, verbatim, type ImageOutput, type ImagesConfig, type ImageTarget } from "./config";
+import { encodeIco, encodePng, fromPremultiplied, type Pixels } from "./png";
+import { parseSvg, type SvgSource } from "./svg";
+
+let ready: Promise<void> | undefined;
+
+async function rasterize(svg: string, width: number, height: number, opaque: boolean): Promise<Pixels> {
+  await (ready ??= initWasm(readFileSync(wasm)));
+  // No system fonts: sources may not contain text, so nothing depends on the machine.
+  const renderer = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } });
+  const image = renderer.render();
+  try {
+    if (image.width !== width || image.height !== height) throw new Error(`Rendered ${image.width}x${image.height} instead of ${width}x${height}.`);
+    return fromPremultiplied(width, height, image.pixels, opaque);
+  } finally { image.free(); renderer.free(); }
+}
+
+class Sources {
+  private readonly loaded = new Map<string, { text: string; svg?: SvgSource }>();
+  constructor(private readonly root: string) {}
+  private entry(name: string) {
+    let entry = this.loaded.get(name);
+    if (!entry) {
+      const file = path.join(this.root, SOURCE_DIRECTORY, `${name}.svg`);
+      if (!existsSync(file)) throw new Error(`Image source '${name}' does not exist at ${SOURCE_DIRECTORY}/${name}.svg.`);
+      entry = { text: readFileSync(file, "utf8") };
+      this.loaded.set(name, entry);
+    }
+    return entry;
+  }
+  text(name: string): string { return this.entry(name).text; }
+  parsed(names: Iterable<string>): Map<string, SvgSource> {
+    return new Map([...names].map(name => { const entry = this.entry(name); return [name, entry.svg ??= parseSvg(name, entry.text)]; }));
+  }
+}
+
+function layerSources(output: Pick<ImageOutput, "layers">): string[] {
+  return output.layers.flatMap(layer => "source" in layer ? [layer.source] : []);
+}
+
+async function render(output: ImageOutput, canvas: Canvas, sources: Sources): Promise<Uint8Array | string> {
+  const kind = format(output.path);
+  if (kind === "xml") {
+    let colors = "";
+    for (const [name, color] of Object.entries(output.colors!)) {
+      let hex = typeof color === "string" ? color : "";
+      if (typeof color !== "string") {
+        // The source's mean color over white, on a canvas of its own proportions, for settings that take a color.
+        const parsed = sources.parsed([color.average]), [, , viewWidth, viewHeight] = parsed.get(color.average)!.viewBox;
+        const width = Math.max(1, Math.round(64 * Math.min(1, viewWidth / viewHeight))), height = Math.max(1, Math.round(64 * Math.min(1, viewHeight / viewWidth)));
+        const average = { layers: [{ source: color.average, fit: "cover" as const, scale: null, size: null, hide: [], tint: null, bleed: [], pixelSnap: false }], mask: null, opaque: true };
+        const { data } = await rasterize(composeSvg(average, { width, height, factor: 1 }, parsed), width, height, true);
+        const sums = [0, 0, 0];
+        for (let index = 0; index < data.length; index += 1) sums[index % 3]! += data[index]!;
+        hex = `#${sums.map(sum => Math.round(sum / (width * height)).toString(16).padStart(2, "0")).join("")}`;
+      }
+      if (hex.length === 4) hex = `#${[...hex.slice(1)].map(digit => digit + digit).join("")}`;
+      colors += `    <color name="${name}">${hex.toUpperCase()}</color>\n`;
+    }
+    return `<?xml version="1.0" encoding="utf-8"?>\n<!-- Generated by agent-tool images from agent-tool.json. Do not edit. -->\n<resources>\n${colors}</resources>\n`;
+  }
+  const copy = verbatim(output);
+  // Copies pass the same checks as composed sources: no scripts, handlers, or external references.
+  if (copy !== null) { sources.parsed([copy]); return sources.text(copy); }
+  const parsed = sources.parsed(layerSources(output));
+  if (kind === "svg") return composeSvg(output, canvas, parsed, true);
+  const pixels = async (width: number, height: number) => rasterize(composeSvg(output, { width, height, factor: canvas.factor }, parsed), width, height, output.opaque);
+  if (kind === "ico") return encodeIco(await Promise.all(output.sizes!.map(size => pixels(size, size))));
+  return encodePng(await pixels(canvas.width, canvas.height));
+}
+
+function select(config: ImagesConfig, names: string[], writable: boolean): [string, ImageTarget][] {
+  const available = Object.keys(config.targets);
+  if (!available.length) throw new Error("agent-tool.json defines no images.targets.");
+  for (const name of names) if (!config.targets[name]) throw new Error(`Unknown image target '${name}'; expected one of: ${available.join(", ")}.`);
+  // Without names, build leaves targets that need --out for an explicit request.
+  const selected = names.length ? [...new Set(names)] : available.filter(name => !writable || config.targets[name]!.dir !== null);
+  if (!selected.length) throw new Error("No image target has a dir; name one and pass --out <directory>.");
+  return selected.map(name => [name, config.targets[name]!]);
+}
+
+/** Refuses symbolic links below the base, so a committed link cannot redirect a write outside it. */
+function assertNoLinks(base: string, destination: string): void {
+  let current = base;
+  for (const part of path.relative(base, destination).split(path.sep)) {
+    current = path.join(current, part);
+    let link: boolean;
+    try { link = lstatSync(current).isSymbolicLink(); } catch { return; }
+    if (link) throw new Error(`Refusing to write through symbolic link ${path.relative(base, current)}.`);
+  }
+}
+
+function directory(name: string, target: ImageTarget, out: string | undefined): string {
+  const dir = out ?? target.dir;
+  if (dir === null) throw new Error(`Image target '${name}' has no dir; pass --out <directory>.`);
+  return dir;
+}
+
+/** Every file each selected target writes, without rendering anything. */
+export function listImages(config: ImagesConfig, names: string[]) {
+  return {
+    sources: SOURCE_DIRECTORY,
+    targets: select(config, names, false).map(([name, target]) => ({
+      name, dir: target.dir, files: target.outputs.flatMap(output => expand(output).map(file => file.path)),
+    })),
+  };
+}
+
+/**
+ * Renders the selected targets under the repository root. Files whose bytes
+ * already match are left alone, so native builds see no spurious changes, and
+ * the rest are replaced atomically.
+ */
+export async function buildImages(root: string, config: ImagesConfig, names: string[], out?: string) {
+  if (out !== undefined && names.length !== 1) throw new Error("--out needs exactly one image target.");
+  const sources = new Sources(root);
+  // Render everything first, so a bad source or setting leaves no partial set behind.
+  const rendered: { name: string; dir: string; files: { relative: string; destination: string; bytes: Uint8Array }[] }[] = [];
+  const owners = new Map<string, string>();
+  for (const [name, target] of select(config, names, true)) {
+    const dir = directory(name, target, out);
+    const files = [];
+    for (const output of target.outputs) {
+      for (const file of expand(output)) {
+        const content = await render(output, { width: file.width, height: file.height, factor: file.factor }, sources);
+        const destination = path.resolve(root, dir, file.path);
+        // An explicit --out is the caller's choice; configured directories are checked from the repository root.
+        assertNoLinks(out === undefined ? root : path.resolve(root, out), destination);
+        // Compared without case, as macOS and Windows file systems do.
+        const owner = owners.get(destination.toLowerCase());
+        if (owner !== undefined) throw new Error(`Image targets '${owner}' and '${name}' both write ${path.relative(root, destination)}.`);
+        owners.set(destination.toLowerCase(), name);
+        files.push({ relative: path.join(dir, file.path), destination, bytes: typeof content === "string" ? Buffer.from(content) : content });
+      }
+    }
+    rendered.push({ name, dir, files });
+  }
+  const targets = rendered.map(({ name, dir, files }) => {
+    const written: string[] = [], unchanged: string[] = [];
+    for (const { relative, destination, bytes } of files) {
+      if (existsSync(destination) && Buffer.compare(readFileSync(destination), bytes) === 0) { unchanged.push(relative); continue; }
+      mkdirSync(path.dirname(destination), { recursive: true });
+      // An unpredictable name created exclusively, so no committed link can stand in for it.
+      const temporary = `${destination}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(temporary, bytes, { flag: "wx" });
+        renameSync(temporary, destination);
+      } catch (error) { rmSync(temporary, { force: true }); throw error; }
+      written.push(relative);
+    }
+    return { name, dir, written, unchanged };
+  });
+  return { targets };
+}

package/src/images/compose.ts

@@ -0,0 +1,78 @@
+import { pair, type ImageOutput, type SourceLayer } from "./config";
+import { attribute, inlineSvg, renameReferences, type SvgSource } from "./svg";
+
+export interface Canvas { width: number; height: number; factor: number | null }
+
+/** Coordinates rounded so documents stay readable and byte-stable. */
+function n(value: number): string { return String(Number(value.toFixed(6))); }
+
+function nested(source: SvgSource, prefix: string, hide: Set<string>, box: [number, number, number, number], viewBox: number[], aspect: string): string {
+  const content = inlineSvg(source, prefix, hide);
+  // The source root's presentation attributes go on a group, so none can collide with or loosen the viewport's.
+  const presentation = source.attributes.map(([key, value]) => attribute(key, renameReferences(value, prefix))).join("");
+  return `<svg x="${n(box[0])}" y="${n(box[1])}" width="${n(box[2])}" height="${n(box[3])}" viewBox="${viewBox.map(n).join(" ")}" preserveAspectRatio="${aspect}" overflow="hidden">${presentation ? `<g${presentation}>${content}</g>` : content}</svg>`;
+}
+
+function placeSource(layer: SourceLayer, index: number, canvas: Canvas, source: SvgSource): string {
+  const { width, height } = canvas;
+  for (const id of layer.hide) if (!source.ids.has(id)) throw new Error(`Image source '${source.name}' has no element with id '${id}' to hide.`);
+  const hide = new Set(layer.hide);
+  const [vx, vy, vw, vh] = source.viewBox;
+  const [boxWidth, boxHeight] = layer.size === null ? [width * (layer.scale ?? 1), height * (layer.scale ?? 1)] : pair(layer.size).map(side => side * canvas.factor!);
+  const boxX = (width - boxWidth!) / 2, boxY = (height - boxHeight!) / 2;
+  const tint = (parts: string[]) => layer.tint === null ? parts.join("") : `<g filter="url(#agent-tool-tint-${index})">${parts.join("")}</g>`;
+  if (layer.fit === "cover") return tint([nested(source, `l${index}-`, hide, [boxX, boxY, boxWidth!, boxHeight!], source.viewBox, "xMidYMid slice")]);
+  let scale = Math.min(boxWidth! / vw, boxHeight! / vh);
+  if (layer.pixelSnap) {
+    if (!Number.isInteger(vw) || !Number.isInteger(vh)) throw new Error(`Image source '${source.name}' needs a whole-unit viewBox to snap to pixels.`);
+    scale = Math.floor(scale + 1e-9);
+    if (scale < 1) throw new Error(`Image source '${source.name}' (${vw}x${vh}) cannot snap to pixels within ${n(boxWidth!)}x${n(boxHeight!)}.`);
+  }
+  const drawnWidth = vw * scale, drawnHeight = vh * scale;
+  let x = (width - drawnWidth) / 2, y = (height - drawnHeight) / 2;
+  if (layer.pixelSnap) { x = Math.floor(x); y = Math.floor(y); }
+  const parts = [nested(source, `l${index}-`, hide, [x, y, drawnWidth, drawnHeight], source.viewBox, "none")];
+  // Bleeding repeats the source's outermost rendered pixel row or column out to the canvas edge.
+  const row = vh / drawnHeight, column = vw / drawnWidth;
+  const strips: Record<string, [[number, number, number, number], number[]]> = {
+    top: [[x, 0, drawnWidth, y], [vx, vy, vw, row]],
+    bottom: [[x, y + drawnHeight, drawnWidth, height - y - drawnHeight], [vx, vy + vh - row, vw, row]],
+    left: [[0, y, x, drawnHeight], [vx, vy, column, vh]],
+    right: [[x + drawnWidth, y, width - x - drawnWidth, drawnHeight], [vx + vw - column, vy, column, vh]],
+  };
+  for (const edge of layer.bleed) {
+    const [box, viewBox] = strips[edge]!;
+    if (box[2] > 0 && box[3] > 0) parts.push(nested(source, `l${index}${edge}-`, hide, box, viewBox, "none"));
+  }
+  return tint(parts);
+}
+
+/**
+ * One SVG document for an output at its pixel size. Each layer inlines its
+ * source in a nested viewport, so raster and SVG outputs share one geometry.
+ */
+export function composeSvg(output: Pick<ImageOutput, "layers" | "mask" | "opaque">, canvas: Canvas, sources: ReadonlyMap<string, SvgSource>, standalone = false): string {
+  const { width, height } = canvas;
+  const namespaces: Record<string, string> = { xlink: "http://www.w3.org/1999/xlink" };
+  const defs: string[] = [], layers: string[] = [];
+  for (const [index, layer] of output.layers.entries()) {
+    if ("fill" in layer) { layers.push(`<rect width="${width}" height="${height}" fill="${layer.fill}"/>`); continue; }
+    const source = sources.get(layer.source)!;
+    for (const [prefix, uri] of Object.entries(source.namespaces)) {
+      if (namespaces[prefix] !== undefined && namespaces[prefix] !== uri) throw new Error(`Image sources bind xmlns:${prefix} to different namespaces.`);
+      namespaces[prefix] = uri;
+    }
+    if (layer.tint !== null) {
+      // User-space bounds: resvg measures nested viewports incorrectly for bounding-box filter regions.
+      defs.push(`<filter id="agent-tool-tint-${index}" filterUnits="userSpaceOnUse" x="0" y="0" width="${width}" height="${height}" color-interpolation-filters="sRGB"><feFlood flood-color="${layer.tint}"/><feComposite in2="SourceAlpha" operator="in"/></filter>`);
+    }
+    layers.push(placeSource(layer, index, canvas, source));
+  }
+  const shortest = Math.min(width, height);
+  if (output.mask === "circle") defs.push(`<clipPath id="agent-tool-mask"><circle cx="${n(width / 2)}" cy="${n(height / 2)}" r="${n(shortest / 2)}"/></clipPath>`);
+  else if (output.mask) defs.push(`<clipPath id="agent-tool-mask"><rect width="${width}" height="${height}" rx="${n(shortest * output.mask.cornerRadius)}"/></clipPath>`);
+  const size = standalone ? "" : ` width="${width}" height="${height}"`;
+  const declarations = Object.entries(namespaces).map(([prefix, uri]) => attribute(`xmlns:${prefix}`, uri)).join("");
+  const body = output.mask ? `<g clip-path="url(#agent-tool-mask)">${layers.join("")}</g>` : layers.join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg"${declarations}${size} viewBox="0 0 ${width} ${height}">${defs.length ? `<defs>${defs.join("")}</defs>` : ""}${output.opaque ? `<rect width="${width}" height="${height}" fill="#ffffff"/>` : ""}${body}</svg>\n`;
+}

package/src/images/config.ts

@@ -0,0 +1,205 @@
+/** The data-only `images` section of agent-tool.json: named targets of rendered brand images. */
+
+export type Size = number | [number, number];
+export type Edge = "top" | "right" | "bottom" | "left";
+export interface FillLayer { fill: string }
+export interface SourceLayer {
+  source: string;
+  fit: "contain" | "cover";
+  scale: number | null;
+  size: Size | null;
+  hide: string[];
+  tint: string | null;
+  bleed: Edge[];
+  pixelSnap: boolean;
+}
+export type ImageLayer = FillLayer | SourceLayer;
+export type ColorValue = string | { average: string };
+export interface ImageOutput {
+  path: string;
+  size: Size | null;
+  variants: Record<string, number> | Record<string, [number, number]> | null;
+  sizes: number[] | null;
+  opaque: boolean;
+  mask: "circle" | { cornerRadius: number } | null;
+  layers: ImageLayer[];
+  colors: Record<string, ColorValue> | null;
+}
+export interface ImageTarget { dir: string | null; outputs: ImageOutput[] }
+export interface ImagesConfig { targets: Record<string, ImageTarget> }
+
+/** Sources live at assets/brand/<name>.svg in every repository. */
+export const SOURCE_DIRECTORY = "assets/brand";
+export const ANDROID_DENSITIES = { mdpi: 1, hdpi: 1.5, xhdpi: 2, xxhdpi: 3, xxxhdpi: 4 };
+export const MAX_PIXELS = 8192;
+const NAME = /^[a-z][a-z0-9-]*$/;
+const COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const ID = /^[A-Za-z_][\w.:-]*$/;
+const EDGES: Edge[] = ["top", "right", "bottom", "left"];
+const FORMATS = ["png", "ico", "svg", "xml"] as const;
+export type ImageFormat = typeof FORMATS[number];
+
+type Json = Record<string, unknown>;
+function fail(setting: string): never { throw new Error(`Invalid config setting '${setting}'.`); }
+function object(value: unknown, setting: string, allowed: string[]): Json {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${setting} setting '${key}'.`);
+  return value as Json;
+}
+/** An object whose keys are names chosen by the project. */
+function record(value: unknown, setting: string): Json {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  return value as Json;
+}
+function positive(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value > 0; }
+function size(value: unknown, setting: string): Size {
+  if (positive(value)) return value;
+  if (Array.isArray(value) && value.length === 2 && value.every(positive)) return [value[0], value[1]];
+  fail(setting);
+}
+export function pair(value: Size): [number, number] { return typeof value === "number" ? [value, value] : value; }
+/** Repository-relative and inside it: no absolute paths, backslashes, or dot segments. */
+export function relativePath(value: unknown): value is string {
+  return typeof value === "string" && !value.startsWith("/") && !value.includes("\\") && value.split("/").every(part => part && part !== "." && part !== "..");
+}
+export function format(path: string): ImageFormat {
+  return path.slice(path.lastIndexOf(".") + 1) as ImageFormat;
+}
+
+function parseLayer(value: unknown, setting: string): ImageLayer {
+  if (value && typeof value === "object" && "fill" in value) {
+    const layer = object(value, setting, ["fill"]);
+    if (typeof layer.fill !== "string" || !COLOR.test(layer.fill)) fail(`${setting}.fill`);
+    return { fill: layer.fill };
+  }
+  const layer = object(value, setting, ["source", "fit", "scale", "size", "hide", "tint", "bleed", "pixelSnap"]);
+  if (typeof layer.source !== "string" || !NAME.test(layer.source)) fail(`${setting}.source`);
+  const fit = layer.fit ?? "contain";
+  if (fit !== "contain" && fit !== "cover") fail(`${setting}.fit`);
+  if (layer.scale !== undefined && (!positive(layer.scale) || layer.scale > 4)) fail(`${setting}.scale`);
+  if (layer.scale !== undefined && layer.size !== undefined) throw new Error(`${setting} sets both scale and size; choose one.`);
+  const hide = layer.hide ?? [];
+  if (!Array.isArray(hide) || hide.some(id => typeof id !== "string" || !ID.test(id)) || new Set(hide).size !== hide.length) fail(`${setting}.hide`);
+  if (layer.tint !== undefined && (typeof layer.tint !== "string" || !COLOR.test(layer.tint))) fail(`${setting}.tint`);
+  const bleed = layer.bleed ?? [];
+  if (!Array.isArray(bleed) || bleed.some(edge => !EDGES.includes(edge)) || new Set(bleed).size !== bleed.length) fail(`${setting}.bleed`);
+  if (layer.pixelSnap !== undefined && typeof layer.pixelSnap !== "boolean") fail(`${setting}.pixelSnap`);
+  const result: SourceLayer = {
+    source: layer.source, fit, scale: layer.scale ?? null, size: layer.size === undefined ? null : size(layer.size, `${setting}.size`),
+    hide, tint: layer.tint ?? null, bleed, pixelSnap: layer.pixelSnap ?? false,
+  };
+  if (fit === "cover" && (result.bleed.length || result.pixelSnap)) throw new Error(`${setting} can only bleed or snap to pixels with fit "contain".`);
+  return result;
+}
+
+function parseOutput(value: unknown, setting: string): ImageOutput {
+  const input = object(value, setting, ["path", "size", "variants", "sizes", "opaque", "mask", "layers", "colors"]);
+  if (!relativePath(input.path) || !FORMATS.includes(format(input.path))) fail(`${setting}.path`);
+  const path = input.path, kind = format(path);
+  const allowed: Record<ImageFormat, string[]> = {
+    png: ["size", "variants", "opaque", "mask", "layers"],
+    svg: ["size", "variants", "opaque", "mask", "layers"],
+    ico: ["sizes", "opaque", "mask", "layers"],
+    xml: ["colors"],
+  };
+  for (const key of Object.keys(input)) if (key !== "path" && !allowed[kind].includes(key)) throw new Error(`${setting} is ${kind} output and cannot set '${key}'.`);
+
+  let variants: ImageOutput["variants"] = null;
+  if (input.variants !== undefined) {
+    const entries = Object.entries(input.variants === "android" ? ANDROID_DENSITIES : record(input.variants, `${setting}.variants`));
+    const factors = entries.every(([, factor]) => positive(factor)), pairs = entries.every(([, dimensions]) => Array.isArray(dimensions));
+    if (!entries.length || (!factors && !pairs) || entries.some(([key]) => !/^[\w@.-]*$/.test(key))) fail(`${setting}.variants`);
+    variants = Object.fromEntries(entries.map(([key, entry]) => [key, factors ? entry : pair(size(entry, `${setting}.variants.${key}`))])) as ImageOutput["variants"];
+    if (!path.includes("{variant}")) throw new Error(`${setting}.path needs {variant} to name each variant's file.`);
+  } else if (path.includes("{variant}")) throw new Error(`${setting}.path uses {variant} without variants.`);
+  const explicit = variants !== null && Object.values(variants).every(Array.isArray);
+  const base = input.size === undefined ? null : size(input.size, `${setting}.size`);
+  if (explicit && base !== null) throw new Error(`${setting} gives each variant its pixels; remove size.`);
+
+  let sizes: number[] | null = null;
+  if (kind === "ico") {
+    if (!Array.isArray(input.sizes) || !input.sizes.length || input.sizes.some(item => !Number.isInteger(item) || item < 1 || item > 256) || new Set(input.sizes).size !== input.sizes.length) fail(`${setting}.sizes`);
+    sizes = input.sizes as number[];
+  }
+  let colors: ImageOutput["colors"] = null;
+  if (kind === "xml") {
+    const entries = Object.entries(record(input.colors, `${setting}.colors`));
+    if (!entries.length) fail(`${setting}.colors`);
+    colors = {};
+    for (const [name, color] of entries) {
+      if (!/^[a-z_][a-z0-9_]*$/.test(name)) fail(`${setting}.colors.${name}`);
+      if (typeof color === "string" && COLOR.test(color)) colors[name] = color;
+      else {
+        const average = object(color, `${setting}.colors.${name}`, ["average"]).average;
+        if (typeof average !== "string" || !NAME.test(average)) fail(`${setting}.colors.${name}`);
+        colors[name] = { average };
+      }
+    }
+    return { path, size: null, variants: null, sizes: null, opaque: false, mask: null, layers: [], colors };
+  }
+
+  if (input.opaque !== undefined && typeof input.opaque !== "boolean") fail(`${setting}.opaque`);
+  let mask: ImageOutput["mask"] = null;
+  if (input.mask === "circle") mask = "circle";
+  else if (input.mask !== undefined) {
+    const radius = object(input.mask, `${setting}.mask`, ["cornerRadius"]).cornerRadius;
+    if (!positive(radius) || radius > 0.5) fail(`${setting}.mask.cornerRadius`);
+    mask = { cornerRadius: radius };
+  }
+  if (!Array.isArray(input.layers) || !input.layers.length) fail(`${setting}.layers`);
+  const layers = input.layers.map((layer, index) => parseLayer(layer, `${setting}.layers[${index}]`));
+  if ((explicit || kind === "ico") && layers.some(layer => "source" in layer && layer.size !== null)) throw new Error(`${setting} has no base size for a layer size; use scale.`);
+  const output: ImageOutput = { path, size: base, variants, sizes, opaque: input.opaque ?? false, mask, layers, colors };
+  if (kind === "png" && base === null && !explicit) throw new Error(`${setting} needs a size or sized variants.`);
+  if (kind === "svg" && base === null && !explicit && !verbatim(output)) throw new Error(`${setting} needs a size unless it copies one source unchanged.`);
+  for (const { width, height } of base === null && !explicit ? [] : expand(output)) {
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width > MAX_PIXELS || height > MAX_PIXELS) throw new Error(`${setting} renders ${width}x${height}; sizes must be whole pixels up to ${MAX_PIXELS}.`);
+  }
+  return output;
+}
+
+/** An SVG output that is one unmodified source is copied byte for byte. */
+export function verbatim(output: ImageOutput): string | null {
+  const [layer] = output.layers;
+  if (format(output.path) !== "svg" || output.layers.length !== 1 || output.size !== null || output.variants !== null || output.opaque || output.mask || !layer || !("source" in layer)) return null;
+  return layer.fit === "contain" && layer.scale === null && layer.size === null && !layer.hide.length && layer.tint === null && !layer.bleed.length && !layer.pixelSnap ? layer.source : null;
+}
+
+export function parseImages(value: unknown): ImagesConfig {
+  const input = object(value, "images", ["targets"]);
+  const targets = record(input.targets ?? {}, "images.targets");
+  const result: ImagesConfig = { targets: {} };
+  for (const [name, entry] of Object.entries(targets)) {
+    const setting = `images.targets.${name}`;
+    if (!NAME.test(name)) fail(setting);
+    const target = object(entry, setting, ["dir", "outputs"]);
+    if (target.dir !== undefined && !relativePath(target.dir)) fail(`${setting}.dir`);
+    if (!Array.isArray(target.outputs) || !target.outputs.length) fail(`${setting}.outputs`);
+    const outputs = target.outputs.map((output, index) => parseOutput(output, `${setting}.outputs[${index}]`));
+    const paths = outputs.flatMap(output => expand(output).map(file => file.path));
+    const escaping = paths.find(path => !relativePath(path));
+    if (escaping !== undefined) throw new Error(`${setting} writes '${escaping}', which is not a path inside its directory.`);
+    // Compared without case, as macOS and Windows file systems do.
+    const folded = paths.map(path => path.toLowerCase());
+    const repeated = paths.find((_, index) => folded.indexOf(folded[index]!) !== index);
+    if (repeated) throw new Error(`${setting} writes ${repeated} more than once.`);
+    result.targets[name] = { dir: target.dir ?? null, outputs };
+  }
+  return result;
+}
+
+export interface ImageFile { path: string; width: number; height: number; factor: number | null }
+
+/** One file per variant, with its pixel size and the factor that scales layer sizes. */
+export function expand(output: ImageOutput): ImageFile[] {
+  if (output.variants === null) {
+    const [width, height] = output.size === null ? [0, 0] : pair(output.size);
+    return [{ path: output.path, width, height, factor: 1 }];
+  }
+  return Object.entries(output.variants).map(([key, value]) => {
+    const path = output.path.replaceAll("{variant}", key);
+    if (Array.isArray(value)) return { path, width: value[0], height: value[1], factor: null };
+    const [width, height] = pair(output.size!).map(side => side * value) as [number, number];
+    return { path, width, height, factor: value };
+  });
+}

package/src/images/png.ts

@@ -0,0 +1,110 @@
+import { deflateSync } from "node:zlib";
+
+export interface Pixels { width: number; height: number; channels: 3 | 4; data: Uint8Array }
+
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, index) => {
+  let value = index;
+  for (let bit = 0; bit < 8; bit += 1) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+  return value >>> 0;
+});
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = CRC_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(data.length + 12);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, data.length);
+  bytes.set(new TextEncoder().encode(type), 4);
+  bytes.set(data, 8);
+  view.setUint32(data.length + 8, crc32(bytes.subarray(4, data.length + 8)));
+  return bytes;
+}
+
+function paeth(left: number, up: number, upLeft: number): number {
+  const estimate = left + up - upLeft;
+  const toLeft = Math.abs(estimate - left), toUp = Math.abs(estimate - up), toUpLeft = Math.abs(estimate - upLeft);
+  return toLeft <= toUp && toLeft <= toUpLeft ? left : toUp <= toUpLeft ? up : upLeft;
+}
+
+/**
+ * Premultiplied RGBA from the renderer to straight-alpha RGBA, or to RGB when
+ * the image is opaque: app stores reject icons that carry an alpha channel.
+ */
+export function fromPremultiplied(width: number, height: number, rgba: Uint8Array, opaque: boolean): Pixels {
+  const channels = opaque ? 3 : 4;
+  const data = new Uint8Array(width * height * channels);
+  for (let pixel = 0; pixel < width * height; pixel += 1) {
+    const alpha = rgba[pixel * 4 + 3]!;
+    if (opaque && alpha !== 255) throw new Error("An opaque image rendered a transparent pixel.");
+    for (let channel = 0; channel < 3; channel += 1) {
+      const value = rgba[pixel * 4 + channel]!;
+      data[pixel * channels + channel] = alpha === 0 ? 0 : alpha === 255 ? value : Math.min(255, Math.round(value * 255 / alpha));
+    }
+    if (!opaque) data[pixel * 4 + 3] = alpha;
+  }
+  return { width, height, channels, data };
+}
+
+/** A deterministic PNG: no timestamps or text, and each row's filter chosen by the usual minimum-sum heuristic. */
+export function encodePng({ width, height, channels, data }: Pixels): Uint8Array {
+  const stride = width * channels;
+  const filtered = new Uint8Array((stride + 1) * height);
+  const candidates = Array.from({ length: 5 }, () => new Uint8Array(stride));
+  const empty = new Uint8Array(stride);
+  for (let row = 0; row < height; row += 1) {
+    const current = data.subarray(row * stride, (row + 1) * stride);
+    const previous = row ? data.subarray((row - 1) * stride, row * stride) : empty;
+    let best = 0, bestScore = Infinity;
+    for (let type = 0; type < 5; type += 1) {
+      const output = candidates[type]!;
+      let score = 0;
+      for (let index = 0; index < stride; index += 1) {
+        const left = index >= channels ? current[index - channels]! : 0;
+        const up = previous[index]!, upLeft = index >= channels ? previous[index - channels]! : 0;
+        const predictor = type === 0 ? 0 : type === 1 ? left : type === 2 ? up : type === 3 ? (left + up) >> 1 : paeth(left, up, upLeft);
+        const value = (current[index]! - predictor) & 0xff;
+        output[index] = value;
+        score += value < 128 ? value : 256 - value;
+        if (score >= bestScore) break;
+      }
+      if (score < bestScore) { best = type; bestScore = score; }
+    }
+    filtered[row * (stride + 1)] = best;
+    filtered.set(candidates[best]!, row * (stride + 1) + 1);
+  }
+  const header = new DataView(new ArrayBuffer(13));
+  header.setUint32(0, width);
+  header.setUint32(4, height);
+  header.setUint8(8, 8);
+  header.setUint8(9, channels === 3 ? 2 : 6);
+  return Buffer.concat([
+    Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10),
+    chunk("IHDR", new Uint8Array(header.buffer)),
+    chunk("IDAT", deflateSync(filtered, { level: 9 })),
+    chunk("IEND", new Uint8Array()),
+  ]);
+}
+
+/** A Windows icon that stores one PNG per size, which every current browser reads. */
+export function encodeIco(images: readonly Pixels[]): Uint8Array {
+  const pngs = images.map(encodePng);
+  const directory = new DataView(new ArrayBuffer(6 + images.length * 16));
+  directory.setUint16(2, 1, true);
+  directory.setUint16(4, images.length, true);
+  let offset = directory.byteLength;
+  for (const [index, image] of images.entries()) {
+    const entry = 6 + index * 16;
+    // A stored dimension of 0 means 256 pixels.
+    directory.setUint8(entry, image.width % 256);
+    directory.setUint8(entry + 1, image.height % 256);
+    directory.setUint16(entry + 4, 1, true);
+    directory.setUint16(entry + 6, 32, true);
+    directory.setUint32(entry + 8, pngs[index]!.length, true);
+    directory.setUint32(entry + 12, offset, true);
+    offset += pngs[index]!.length;
+  }
+  return Buffer.concat([new Uint8Array(directory.buffer), ...pngs]);
+}

package/src/images/svg.ts

@@ -0,0 +1,197 @@
+/**
+ * Just enough XML to inline brand sources in a composed document: one copy per
+ * layer with prefixed ids, named elements dropped, and features refused when
+ * they would render differently between machines, leak between layers, or
+ * script or fetch when an output is opened.
+ */
+
+export interface SvgSource {
+  name: string;
+  viewBox: [number, number, number, number];
+  /** Root presentation attributes, such as fill or shape-rendering, that the inlined copy keeps. */
+  attributes: [string, string][];
+  namespaces: Record<string, string>;
+  ids: Set<string>;
+  tokens: Token[];
+}
+
+type Token =
+  | { kind: "raw"; text: string }
+  | { kind: "start"; name: string; attributes: [string, string][]; selfClosing: boolean }
+  | { kind: "end"; name: string };
+
+const TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<!DOCTYPE[^>[]*(\[[\s\S]*?\])?\s*>|<\/([A-Za-z_][\w.:-]*)\s*>|<([A-Za-z_][\w.:-]*)((?:\s+[^\s=/>]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>|[^<]+/y;
+const ATTRIBUTE = /\s+([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+// Static SVG only: shapes, paint servers, clipping, masking, and filters. Animation, links, and markup
+// from other namespaces could script or fetch when an output is opened, so they are refused, not trusted.
+const ELEMENTS = new Set([
+  "circle", "clipPath", "defs", "desc", "ellipse", "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite",
+  "feConvolveMatrix", "feDiffuseLighting", "feDisplacementMap", "feDistantLight", "feDropShadow", "feFlood", "feFuncA",
+  "feFuncB", "feFuncG", "feFuncR", "feGaussianBlur", "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset",
+  "fePointLight", "feSpecularLighting", "feSpotLight", "feTile", "feTurbulence", "filter", "g", "image", "line",
+  "linearGradient", "marker", "mask", "metadata", "path", "pattern", "polygon", "polyline", "radialGradient", "rect",
+  "stop", "svg", "switch", "symbol", "title", "use",
+]);
+const REASONS: Record<string, string> = {
+  style: "a <style> element; use presentation attributes",
+  text: "text, which depends on installed fonts; convert it to paths",
+};
+const ROOT_GEOMETRY = new Set(["xmlns", "version", "baseProfile", "width", "height", "x", "y", "viewBox", "preserveAspectRatio", "overflow", "id"]);
+
+const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+/** Attribute values as an XML parser sees them, so checks cannot be bypassed by encoding. */
+function decode(name: string, value: string): string {
+  if (/&(?!(?:#x[0-9a-fA-F]{1,6}|#[0-9]{1,7}|amp|lt|gt|quot|apos);)/.test(value)) throw new Error(`Image source '${name}' uses an undefined entity in '${value.slice(0, 40)}'.`);
+  const decoded = value.replace(/&(?:#x([0-9a-fA-F]+)|#([0-9]+)|(amp|lt|gt|quot|apos));/g, (reference, hex?: string, decimal?: string, entity?: string) => {
+    if (entity) return ENTITIES[entity]!;
+    const code = hex ? Number.parseInt(hex, 16) : Number(decimal);
+    if (code < 1 || code > 0x10ffff) throw new Error(`Image source '${name}' has an invalid character reference '${reference}'.`);
+    return String.fromCodePoint(code);
+  });
+  // CSS escapes could spell url( in a way the reference check cannot see; SVG values never need them.
+  if (decoded.includes("\\")) throw new Error(`Image source '${name}' uses a CSS escape in '${value.slice(0, 40)}'.`);
+  return decoded;
+}
+
+function tokenize(name: string, text: string): Token[] {
+  const tokens: Token[] = [];
+  TOKEN.lastIndex = 0;
+  while (TOKEN.lastIndex < text.length) {
+    const match = TOKEN.exec(text);
+    if (!match) throw new Error(`Image source '${name}' is not well-formed SVG near offset ${TOKEN.lastIndex}.`);
+    if (match[1] !== undefined) throw new Error(`Image source '${name}' declares a DOCTYPE subset; remove it.`);
+    if (match[0].startsWith("<!DOCTYPE") && /["']/.test(match[0]) && !/^<!DOCTYPE\s+svg\s+PUBLIC\s+"[^"]*"\s+"http:\/\/www\.w3\.org\/[^"]*"\s*>$/.test(match[0])) {
+      throw new Error(`Image source '${name}' names a DOCTYPE other than the W3C SVG DTD; remove it.`);
+    }
+    if (match[2] !== undefined) tokens.push({ kind: "end", name: match[2] });
+    else if (match[3] !== undefined) {
+      const attributes: [string, string][] = [];
+      for (const attribute of match[4]!.matchAll(ATTRIBUTE)) {
+        if (attributes.some(([key]) => key === attribute[1])) throw new Error(`Image source '${name}' repeats attribute '${attribute[1]}'.`);
+        attributes.push([attribute[1]!, decode(name, attribute[2] ?? attribute[3]!)]);
+      }
+      tokens.push({ kind: "start", name: match[3], attributes, selfClosing: match[5] === "/" });
+    } else tokens.push({ kind: "raw", text: match[0] });
+  }
+  return tokens;
+}
+
+/** The name without its namespace prefix: any prefix may be bound to the SVG or XLink namespace. */
+function local(name: string): string { return name.slice(name.indexOf(":") + 1); }
+
+/** Event handlers, stylesheets, and references to anything outside the file except embedded images, are refused. */
+function checkAttributes(name: string, element: string, attributes: [string, string][]): void {
+  for (const [key, value] of attributes) {
+    if (/^on/i.test(local(key))) throw new Error(`Image source '${name}' has a '${key}' event handler.`);
+    if (local(key) === "style") throw new Error(`Image source '${name}' has a style attribute; use presentation attributes.`);
+    if (local(key) === "base") throw new Error(`Image source '${name}' sets '${key}', which could resolve references elsewhere.`);
+    // CSS image functions can fetch without url(), for example through a mask presentation attribute.
+    if (key !== "id" && /(?:image-set|image|cross-fade|element|src)\s*\(/i.test(value)) throw new Error(`Image source '${name}' uses a CSS image function in '${value.slice(0, 40)}'.`);
+    const external = local(key) === "href"
+      ? !value.startsWith("#") && !(["image", "feImage"].includes(local(element)) && value.startsWith("data:"))
+      : value.split(/url\(/i).slice(1).some(target => !target.trimStart().replace(/^['"]/, "").startsWith("#"));
+    if (external) throw new Error(`Image source '${name}' references '${value.slice(0, 40)}'; embed it or reference an element in the file.`);
+  }
+}
+
+interface Scope { default: string | undefined; prefixes: Record<string, string> }
+function declare(parent: Scope, attributes: [string, string][]): Scope {
+  const declarations = attributes.filter(([key]) => key === "xmlns" || key.startsWith("xmlns:"));
+  if (!declarations.length) return parent;
+  const scope: Scope = { default: parent.default, prefixes: { ...parent.prefixes } };
+  for (const [key, value] of declarations) if (key === "xmlns") scope.default = value; else scope.prefixes[key.slice(6)] = value;
+  return scope;
+}
+
+function number(value: string | undefined): number | undefined {
+  const parsed = value === undefined ? NaN : Number(value.trim().replace(/px$/, ""));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function parseSvg(name: string, text: string): SvgSource {
+  const all = tokenize(name, text);
+  const start = all.findIndex(token => token.kind !== "raw");
+  const root = all[start];
+  const prologue = all.slice(0, Math.max(start, 0));
+  if (!root || root.kind !== "start" || root.name !== "svg" || prologue.some(token => token.kind === "raw" && !/^(?:\s+|<!--[\s\S]*-->|<\?xml\s[\s\S]*\?>|<!DOCTYPE[\s\S]*>)$/.test(token.text))) {
+    throw new Error(`Image source '${name}' must have an <svg> root element.`);
+  }
+  const rootAttributes = new Map(root.attributes);
+  checkAttributes(name, root.name, root.attributes);
+  if (rootAttributes.get("xmlns") !== SVG_NAMESPACE) throw new Error(`Image source '${name}' must declare xmlns="${SVG_NAMESPACE}".`);
+  const box = rootAttributes.get("viewBox")?.trim().split(/[\s,]+/).map(Number);
+  const width = number(rootAttributes.get("width")), height = number(rootAttributes.get("height"));
+  let viewBox: [number, number, number, number];
+  if (box) {
+    if (box.length !== 4 || box.some(value => !Number.isFinite(value)) || box[2]! <= 0 || box[3]! <= 0) throw new Error(`Image source '${name}' has an invalid viewBox.`);
+    viewBox = box as [number, number, number, number];
+  } else if (width && height) viewBox = [0, 0, width, height];
+  else throw new Error(`Image source '${name}' needs a viewBox or numeric width and height.`);
+
+  const tokens: Token[] = [], ids = new Set<string>(), stack: string[] = [], scopes = [declare({ default: undefined, prefixes: {} }, root.attributes)];
+  // Ends on the root's closing tag, or on the root itself when it is self-closing.
+  let index = start;
+  if (!root.selfClosing) {
+    for (index = start + 1; index < all.length; index += 1) {
+      const token = all[index]!;
+      if (token.kind === "end") {
+        if (stack.length === 0) { if (token.name !== "svg") throw new Error(`Image source '${name}' closes </${token.name}> without opening it.`); break; }
+        if (stack.pop() !== token.name) throw new Error(`Image source '${name}' closes </${token.name}> out of order.`);
+        scopes.pop();
+      } else if (token.kind === "start") {
+        const scope = declare(scopes.at(-1)!, token.attributes);
+        const prefix = token.name.includes(":") ? token.name.slice(0, token.name.indexOf(":")) : undefined;
+        if ((prefix === undefined ? scope.default : scope.prefixes[prefix]) !== SVG_NAMESPACE || !ELEMENTS.has(local(token.name))) {
+          throw new Error(`Image source '${name}' contains ${REASONS[local(token.name)] ?? `an unsupported <${token.name}> element; keep only static SVG shapes, paint, clipping, masking, and filters`}.`);
+        }
+        checkAttributes(name, token.name, token.attributes);
+        for (const [key, value] of token.attributes) if (key === "id") { if (ids.has(value)) throw new Error(`Image source '${name}' repeats id '${value}'.`); ids.add(value); }
+        if (!token.selfClosing) { stack.push(token.name); scopes.push(scope); }
+      } else if (token.text.startsWith("<?")) throw new Error(`Image source '${name}' contains a processing instruction.`);
+      tokens.push(token);
+    }
+    if (index === all.length) throw new Error(`Image source '${name}' never closes its <svg> root.`);
+  }
+  if (all.slice(index + 1).some(token => token.kind !== "raw" || !/^(?:\s+|<!--[\s\S]*-->)$/.test(token.text))) throw new Error(`Image source '${name}' has content after its <svg> root.`);
+
+  const namespaces: Record<string, string> = {};
+  const attributes: [string, string][] = [];
+  for (const [key, value] of root.attributes) {
+    if (key.startsWith("xmlns:")) namespaces[key.slice(6)] = value;
+    else if (!ROOT_GEOMETRY.has(key)) attributes.push([key, value]);
+  }
+  return { name, viewBox, attributes, namespaces, ids, tokens };
+}
+
+export function attribute(key: string, value: string): string {
+  return ` ${key}="${value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll('"', "&quot;")}"`;
+}
+
+/** Points `url(#id)` references at a copy whose ids carry the prefix. */
+export function renameReferences(value: string, prefix: string): string {
+  return value.replace(/url\(\s*(['"]?)#([^'")\s]+)\1\s*\)/gi, (_, _quote, id: string) => `url(#${prefix}${id})`);
+}
+
+/** The source's children with every id prefixed, internal references rewritten, and hidden elements removed. */
+export function inlineSvg(source: SvgSource, prefix: string, hide: ReadonlySet<string>): string {
+  const rename = (value: string) => renameReferences(value, prefix);
+  let markup = "", skipped = 0;
+  for (const token of source.tokens) {
+    if (token.kind === "start") {
+      if (skipped > 0 || token.attributes.some(([key, value]) => key === "id" && hide.has(value))) { if (!token.selfClosing) skipped += 1; continue; }
+      markup += `<${token.name}`;
+      for (const [key, value] of token.attributes) {
+        if (key === "id") markup += attribute(key, `${prefix}${value}`);
+        else if (local(key) === "href" && value.startsWith("#")) markup += attribute(key, `#${prefix}${value.slice(1)}`);
+        else markup += attribute(key, rename(value));
+      }
+      markup += token.selfClosing ? "/>" : ">";
+    } else if (token.kind === "end") {
+      if (skipped > 0) skipped -= 1;
+      else markup += `</${token.name}>`;
+    } else if (skipped === 0) markup += token.text;
+  }
+  return markup;
+}

package/src/images/wasm.d.ts

@@ -0,0 +1,5 @@
+// Bun embeds the file in compiled executables and resolves it from node_modules otherwise.
+declare module "@resvg/resvg-wasm/index_bg.wasm" {
+  const path: string;
+  export default path;
+}

package/src/skills/bundled.ts

@@ -5,5 +5,5 @@ export const BUNDLED_SKILLS: Readonly<Record<string, string>> = {
   "reset": "---\nname: reset\ndescription: Return a clean checkout to its updated default branch after confirmed shipping or an explicit checkout cleanup request.\n---\n\n# Reset\n\nThis is checkout cleanup, not a destructive Git reset. Read repository guidance\nfor setup and hooks. Determine the default branch through the repository's\nremote metadata rather than assuming main.\n\nCheck worktree and index first. Preserve user edits; if they prevent switching,\nreport the condition instead of discarding or automatically stashing them. For\npost-merge cleanup, confirm the PR is MERGED before removing a feature branch.\n\nFetch the default branch, switch to it, and update by fast-forward only. A\ndiverged default branch requires inspection rather than forced replacement.\nDelete a merged feature branch only within the requested cleanup scope and\nafter verifying its exact commit is the shipped commit; squash merging does not\nmake Git ancestry-based branch deletion proof of shipping. Honor keep-branch.\n\nRun only the hook installer or dependency setup documented by this repository\nwhen the updated checkout requires it. Do not assume a package manager or copy\nsetup commands from another project. Report final branch, commit, and any\nunfinished cleanup.\n",
   "ship-pr": "---\nname: ship-pr\ndescription: Complete an authorized commit, independent review, repair, PR, CI, and squash-merge workflow for a GitHub repository.\n---\n\n# Ship PR\n\nUse the installed `agent-tool`. Read repository guidance and policy first;\nvalidation, versioning, package management, and hook installation remain project\nconcerns. Shipping authorizes this workflow within the user's stated scope.\nPreserve unrelated edits and honor requested stopping points such as open-PR\nonly, report-only review, or keeping the feature branch.\n\nUse `agent-tool run --label <check> -- <command> [args...]` for noisy setup,\nvalidation, builds, and hook-running Git commands. It preserves exit status and\ncomplete private logs, prints one success receipt, and shows a bounded failure\ntail. Inspect more with `agent-tool logs <log> --max-bytes 8192 --tail-lines 80`\nor a targeted search; never dump an entire suite log or pipe checks into `tail`.\nThe receipt proves process completion, not absence of warnings: inspect required\nwarning, coverage, timing, or artifact evidence before accepting a check. Keep\nmachine-readable receipts and review findings visible by running `versions\nprepare`, `review`, and other commands whose output drives a decision directly.\nPrefer documented compact test reporters when they preserve required evidence;\ndo not reduce test scope, skip checks, silence warnings, or mask failures.\n\n1. Finish the requested change on a feature branch. Create it with\n   `git switch --no-track -c <branch>`; settings such as\n   `branch.autosetupmerge=always` otherwise make it track a local branch.\n   Validate it with appropriate project checks and commit only the intended\n   files.\n2. Determine the current PR's base repository and branch, or the repository's\n   default branch when no PR exists. Fetch and pin its exact base. Integrate it\n   using the repository's normal workflow, resolving conflicts without losing\n   user work. If project policy versions packages, prepare versions against the\n   pinned base after every integration or repair and before each review, using\n   the project's commands or `agent-tool versions prepare <base-oid>`, which\n   commits bumped manifests and the refreshed lockfile.\n   `agent-tool versions resolve-conflicts` resolves conflicts confined to\n   version fields. Review the resulting committed HEAD with an independent\n   reviewer using the bundled cross-agent-review skill. Repair blocking findings\n   and review every changed HEAD again. Review failure blocks shipping.\n3. Push the reviewed HEAD through normal hooks, then verify the pushed SHA still\n   equals the reviewed SHA. If a hook changed content or HEAD, review that result.\n   Open the PR using the open-pr skill, or update the existing PR as needed.\n4. Allow any configured review bots time to respond, then fetch unresolved PR\n   review threads. Follow repository policy for feedback: fix valid findings,\n   reply in the original threads, and resolve only fully addressed comments.\n   Validate, commit, push, and independently review every feedback or CI repair.\n   Wait for CI, recheck the live base, PR base branch, and local and remote heads.\n   A changed base requires integration, validation, and another review. When\n   versions are managed, `agent-tool versions check <base-oid>` must pass for the\n   live base. Use the squash-merge skill to merge the exact reviewed HEAD.\n5. After confirmed MERGED, honor keep-branch; otherwise use the reset skill to\n   return to the updated default branch and apply any documented project setup.\n6. When the project deploys the merged branch, verify the deployment for the\n   merge commit and run its documented live checks. Report deployment failures\n   separately from a successful merge; follow project policy for repairs.\n\nNever infer a clean review from process success alone or carry a review across\ncontent changes. Do not weaken configured CI policy to get a merge through.\nIf a step fails, preserve useful intermediate work and report the concrete\nremaining issue. Report PR link, merged commit, review verdict, validation, and\nfinal checkout state.\n",
   "squash-merge": "---\nname: squash-merge\ndescription: Squash-merge a reviewed GitHub pull request while binding the mutation to the reviewed commit and checking CI.\n---\n\n# Squash Merge\n\nUse the installed `agent-tool` and repository merge policy. Merge only within\nthe user's authorized scope. Have the exact reviewed HEAD, base commit, and base\nbranch available, and read the verdict and unresolved findings. BLOCKER or MAJOR\nfindings require repair and a new review before merging.\nFollow the repository's review-bot policy and require all actionable blocking\nreview feedback to be addressed before merging.\n\nWait for required checks using `gh pr checks --watch --fail-fast`. Refresh the\nPR and live base from the repository that owns the PR. Confirm local HEAD and PR\nHEAD both equal the reviewed commit, the base branch is unchanged, the live base\nstill equals the reviewed base, and that base is an ancestor of reviewed HEAD.\nIf any identity changed, refresh, validate, and review again.\n\nUse a title that satisfies `agent-tool.json` and pass both reviewed HEAD and\nbase branch:\n\n```sh\nagent-tool pr merge 'feat: describe the change' <reviewed-head-oid> <base-branch>\n```\n\nThe helper enforces HEAD atomically through GitHub's `expectedHeadOid`, checks\nCI, rejects queued or automatic merges, and creates a subject-only squash with\nthe PR reference. GitHub has no atomic expected-base argument in this mutation;\nrepository branch protection must enforce any required base freshness. With\n`merge.requireStrictBaseFreshness`, the helper refuses to merge unless an\nactive strict status ruleset that the actor cannot bypass protects the base. Do\nnot retarget the PR concurrently with merging.\n\nConfirm GitHub reports MERGED before any cleanup. A failed or uncertain mutation\nis not evidence of a merge. Preserve the branch on failure. After a confirmed\nmerge, perform checkout cleanup only when requested or as part of an authorized\nshipping workflow. Report the PR and merge result.\n",
-  "update-dependencies": "---\nname: update-dependencies\ndescription: Update a repository's dependency manifests, lockfiles, runtimes, tools, and CI pins with upstream migrations, compatibility checks, and non-destructive infrastructure previews.\n---\n\n# Update Dependencies\n\nUse the repository's package managers and installed `agent-tool`. Read `AGENTS.md`,\nREADME, linked setup/release documents, and repository-owned upgrade skills before\nediting. Follow their hooks, version policy, checks, and requested stopping point.\nUpdate applicable dependencies throughout the repository, including workspaces\nand examples. This skill does not authorize deploying, merging, publishing, or\nchanging global tools; use existing user authorization and `ship-pr` when shipping\nis requested. Default dependency-update merge subject: `chore: update dependencies`,\nsubject to repository title policy and any explicit user subject.\n\nRun noisy installs, checks, tests, and builds with\n`agent-tool run --label <check> -- <command> [args...]` to retain full private\nlogs and return the original status with compact output. Inspect bounded excerpts\nusing `agent-tool logs <log>` and targeted searches for warnings and evidence;\na successful receipt does not establish a warning-free upgrade. Keep structured\naudit/plan results, deployment previews, and review findings directly visible\nwhen they drive a safety decision. Do not dump full suite logs into context,\nsilence warnings at their source, or change check scope to reduce output.\n\n## Safety before execution\n\n**Always dry-run before any infrastructure apply or deployment. Never destroy,\nreplace, or recreate a resource during an upgrade.** This includes Terraform,\nOpenTofu, Wrangler, Ansible, other infrastructure tools, and effects triggered by\ninstallation, tests, hooks, Git push, opening a PR, CI, or merging. Greenfield\nprojects and approval to ship do not waive this rule.\n\nBefore running project commands or pushing, trace their scripts, hooks, workflow\ntriggers, reusable workflows, and deployment commands. A dry-run flag alone is\ninsufficient: inspect tasks, provisioners, plugins, external programs, and actions\nthat can mutate despite preview mode. Avoid such a preview unless its effects\nare proven read-only. Do not run destroy/delete, taint/replace, state removal,\nbackend migration, forced database reset, or an automatic \"repair\" that bypasses\nthe rule. Do not hide destruction with targeting, disabled refresh, ignored\nchanges, new resource identities, or weakened policy.\n\nPreview with the proposed versions and complete configuration for each affected\nenvironment, using its real backend/workspace/account, variables, inventory, and\nresource identities. An empty local state, mocked credentials, validate-only run,\nor bundle build cannot establish safety for production. Check the current baseline\nas well when needed to distinguish existing drift from the upgrade. Keep state,\nbinary plans, JSON plans, and secret-bearing diffs out of Git and public reports.\n\nIf a preview proposes deletion or replacement, fails, is incomplete, omits\naffected resources, or cannot establish safety, skip that dependency and its\ncoupled migrations. Restore only this task's edits to the affected compatibility\ngroup, retain independent safe upgrades, and record the reason and affected\nresources. Never apply to find out. A preview is not deployment authorization.\n\nBefore an authorized apply/deploy, verify the exact validated commit, toolchain,\nconfiguration, environment, and current state still match the preview. Re-preview\nafter relevant changes or drift. CI must enforce the same order and stop on an\nunsafe preview before mutation; a successful local preview does not excuse an\nunguarded push- or merge-triggered deployment. Establish a narrowly scoped guard\nwhen authorized and reviewable, or hold the affected upgrade before triggering\nthat workflow. Do not disable protections to ship. A plan must be inspected before\nthe operation; inspecting deployment logs afterward is too late.\nAn unsafe workflow triggered on every branch push also blocks pushing otherwise\nindependent upgrades until that trigger has a proven safe guard.\n\n### Terraform and OpenTofu\n\nRead core, provider, and module upgrade guides, including intermediate major\nmigrations. Regenerate provider locks with the pinned CLI, preserving supported\nplatform hashes. Backend initialization/migration is also subject to the safety\ngate. Inspect external data programs and provisioners before planning.\n\nUse a full refreshed saved plan with locking and the real variables, for example\n`terraform plan -input=false -out=<private-plan>`; if using `-detailed-exitcode`,\n0 and 2 are success, 1 is failure. Inspect `terraform show -json <private-plan>`.\nRun `agent-tool dependencies check-terraform-plan <private-plan.json>` to check\nsupported JSON resource actions. It fails for every action containing `delete`,\nincluding both replacement orders, unknown actions, incomplete/deferred plans,\nfailed checks, or opaque provider action invocations. It prints actions and\ndiagnostics without resource attribute values; it does not prove that a plan is\nfresh, comprehensive, authentic, or that provider code has no hidden effects.\nOlder/unsupported plan formats that cannot establish completeness are skipped.\nOpenTofu currently omits `complete` in its JSON format and is rejected by this\nhelper; report that limitation rather than adding a synthetic completeness flag.\nAlso inspect resource identity, drift, warnings, provider semantics, and any\neffects outside resource actions. For an authorized apply, consume the exact\napproved saved plan, not an uninspected newly generated plan.\n\nSource: [Terraform JSON plan format](https://developer.hashicorp.com/terraform/internals/json-format).\n\n### Wrangler and other deployment tools\n\nUse the proposed pinned Wrangler for `wrangler deploy --dry-run` with the same\nbuild/configuration/environment used by deployment. This checks bundling, not a\ncomplete remote resource plan. Separately verify account, worker name, routes,\nbindings and resource IDs against the existing deployment and read migration\nsemantics. Review Durable Object deleted/renamed classes, D1 schema/data\nmigrations, storage resources, queues, containers, and deployment integrations.\nNever infer \"no destruction\" from a successful bundle. Resource removals,\nreplacement, or unprovable remote effects skip the affected group. Apply the\nequivalent preview and identity checks to other tools rather than assuming they\nshare Terraform's guarantees.\n\nDo not assume `wrangler d1 migrations list --remote` is read-only. The\nimplementation inspected for this skill initializes migration tracking with\n`CREATE TABLE IF NOT EXISTS`; verify the pinned Wrangler version before using\nthe command. Verify database identity and compare migration files with the\ndatabase's configured migration tracking table through audited read-only\nqueries. A missing table, pending migration, or unverifiable schema/data\neffects hold the affected upgrade/deployment group. Never initialize schema\nmerely to establish preview safety.\n\nWrangler runs a custom `build.command` again during deployment. Use supported\nconfiguration referencing the same validated artifacts for both preview and\ndeployment, preventing another unvalidated build before upload. Bind the\nartifacts, configuration, and pinned tool to the authorized commit, and recheck\ntheir identities before upload and after relevant changes. Hold the affected\ngroup if the pinned Wrangler cannot upload the validated output without\nrebuilding it, or if the upload cannot be proven to match the preview.\n\nSources: [Wrangler command documentation](https://developers.cloudflare.com/workers/wrangler/commands/),\n[D1 migration listing implementation](https://github.com/cloudflare/workers-sdk/blob/e3d186776fcc2e4b5cc4cfd7155591778a375957/packages/wrangler/src/d1/migrations/list.ts),\n[migration table initialization](https://github.com/cloudflare/workers-sdk/blob/e3d186776fcc2e4b5cc4cfd7155591778a375957/packages/wrangler/src/d1/migrations/helpers.ts),\nand [Wrangler custom builds](https://developers.cloudflare.com/workers/wrangler/custom-builds/).\n\n### Ansible\n\nCheck controller Python, ansible-core, collections/roles, and target Python support\ntogether; read porting guides. Inspect all tasks and invoked scripts before\n`ansible-playbook --check --diff` with the real inventory and variables.\n`check_mode: false` forces mutation even with `--check`; unsupported modules and\nconditions based on registered results can omit effects. Inspect deletion,\nrecreation, service/data reset, and package removal semantics beyond the diff.\nSkipped or opaque tasks are a safety gap, not a clean preview. Redact diffs.\n\nSource: [Ansible check mode limits](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html).\n\n## Inventory and choose compatible targets\n\nRecord each dependency source, current resolved version, latest stable candidate,\nselected target, compatibility constraints, upstream migration links, and checks.\nQuery authoritative registries, official releases, support matrices, and migration\nguides at execution time; do not treat remembered versions or prereleases as\nlatest stable. Inspect runtime requirements, peer dependencies, ABI/API changes,\nplatform availability, maintained release lines, and changed defaults, including\nsecurity, privacy/telemetry, data retention, and postinstall/native behavior.\nCheck transitive dependencies' peer/runtime constraints as well as direct ones. Unsupported\nor unpublished targets stay pinned with an explanation.\n\nInventory manifests, locks, tool configuration, CI/reusable actions, containers,\nscripts, deployment files, and executable documentation. Search duplicate version\npins and aliases, not just filenames; exclude vendored/generated snapshots unless\nthe repository owns their update process. Examples of sources to inspect:\n\n| Ecosystem | Sources and compatibility group |\n| --- | --- |\n| JavaScript/TypeScript | All package.json dependency fields, overrides/resolutions, workspace catalogs, packageManager/engines, npm/Bun/pnpm/Yarn locks, Node/Bun pins, compiler and lint/build/test plugins |\n| Toolchains | mise.toml/.mise.toml, mise.lock, .tool-versions, runtime version files, tool URLs/checksums, CI pins and container images; include every tool declared by mise, not just mise itself |\n| Python/Ansible | pyproject/requirements, uv/Poetry/pip locks, Python pins, ansible-core, collection/role requirements, lint plugins and managed host constraints |\n| Ruby/iOS | .ruby-version, Gemfile/lock, Bundler, CocoaPods, Podfile/lock, podspecs, Swift packages and Xcode/iOS deployment requirements |\n| Infrastructure | Terraform/OpenTofu CLI constraints, provider locks/constraints, module versions/Git refs, Wrangler and Cloudflare integration dependencies |\n| CI/system/native | Actions/reusable workflow refs, Docker tags/digests, OS images/packages, Rust/Cargo toolchain and locks, Go modules, Gradle/AGP/Kotlin/JDK and other repository-specific manifests |\n\nBuild connected compatibility groups before editing. Select the newest supported\ncombination, which can be older than an individual package's latest. Upgrade the\nframework first or keep its compatible toolchain pinned; do not force peer\nresolution, drop compatibility checks, or add blanket overrides to make installs\npass. Preserve source pin policy (exact version, digest, full Git SHA) and resolve\nimmutable pins from verified upstream releases. Preserve intentional runtime\nminimums unless migration requires changing the support contract.\n\nFor React Native, use its version-specific upgrade guide/template diffs and\nrepository upgrade skills. Couple React and its renderer, native modules,\nMetro/Babel, CLI, codegen, Hermes/New Architecture, CocoaPods/Bundler/Ruby,\nXcode/iOS deployment targets, and Android Gradle/AGP/Kotlin/JDK/SDK/NDK. For Expo,\nuse the chosen SDK's supported React Native/dependency matrix and its dependency\nchecks. Do not independently update framework-managed pods or generated native\nfiles; use the framework's regeneration workflow and prove iOS/Android builds.\nPermissive peer ranges alone do not prove native renderer or toolchain compatibility;\ncheck the framework's actual supported versions and native implementation.\nAn unavailable native toolchain is a reported validation limit; do not claim the\ngroup verified. See [React Native upgrading](https://reactnative.dev/docs/upgrading).\n\nCheck developer tools' own dependencies too: a compiler release without its old\nprogrammatic API may break test/lint runners that import it even when `tsc` passes.\nAction runtime upgrades can require newer self-hosted runners; preserve workflow\npermissions, action inputs/outputs, caching, artifact semantics, and job names.\n\nCheck current advisories with read-only ecosystem audits against the baseline and\nproposed lockfiles, using the repository's configured registry/advisory sources.\nDo not send private dependency metadata to an unconfigured or unauthorized service;\nreport the resulting coverage limit. Cover direct and resolved transitive dependencies,\nincluding native/platform-specific binaries. Latest direct packages can still\npin vulnerable transitive versions. Trace each finding to its owning dependency,\nverify affected versions, runtime conditions, and remediation in the maintainer's\nadvisory and fixed release. When the owner's range permits a fixed version, use a\ntargeted refresh with the lockfile's owning manager and preserve unrelated\nresolutions; otherwise prefer a supported owner upgrade.\nIf the owner still pins a vulnerable version, a narrowly scoped security patch\noverride may be used only with API/ABI/runtime compatibility evidence and focused\nregression checks of the actual affected integration. Document its rationale and\nremoval condition; a passing install or bundle alone is insufficient. Do not run\nblind audit fixes or use blanket overrides to bypass compatibility constraints.\nReport unresolved advisories and unavailable audit coverage accurately; current\ndirect pins or a partial clean audit do not\nestablish that the whole dependency graph is safe.\n\n## Migrate and validate\n\nCapture relevant baseline checks and warnings first, after screening their side\neffects. Update one compatibility group at a time. Read the upstream instructions\nfor every breaking step; implement required source/config/schema migrations and\nremoved API replacements. Use the manager that owns each lockfile, on the selected\nruntime, and inspect the resulting diff. Refresh transitive dependencies through\ntheir owning direct dependency; do not hand-edit integrity hashes or lock entries.\nReview intentional patches, overrides, and pins before removal; retain them until\nupstream fixes and regression checks demonstrate they are unnecessary.\nAvoid unrelated global installations or environment changes. Use task-local or\nrepository-scoped tools for testing changed runtime pins.\nFor published packages, also validate tarballs and consumer installs with their\ndocumented supported package managers, including manifest/override syntax and\nruntime requirements. A successful owning-manager install does not prove that\npublished metadata works for those consumers.\n\nRun the repository's setup/hooks, frozen installs, lint, typechecks, tests, builds,\npackage/platform smoke checks, and relevant safe integration previews. Resolve\nupgrade-related deprecation warnings at their source. Do not suppress warnings,\nweaken tests, or disable checks; report remaining upstream/pre-existing warnings\nwith evidence and keep a target pinned when migration cannot be completed.\nAdd focused regression coverage when a migration changes behavior; avoid tests\nthat merely assert version strings. Re-run checks after repairs. Report checks\nblocked by missing credentials, platforms, or external services accurately.\nRe-audit the final resolved graph after migrations and repairs.\n\nConfirm every inventory row is upgraded, already current, intentionally constrained,\nor skipped with a concrete reason. Do not present an unresolved group as complete.\nWhen upgrading agent-tool itself, install its managed skills with the same harness\nscope and commit the ownership manifest; never edit generated managed skill copies.\n\nWhen changes depend on another repository's release, ship the producer first and\nconfirm publishing and registry availability before pinning the consumer; include\nits exact version/commit and API migration notes. Independent groups may proceed.\nUse the installed `ship-pr` for authorized shipping and independently review every\nchanged HEAD. Check deployment safety again before its push/open/merge operations.\n\n## Report\n\nKeep a compact ledger of old/selected versions, completed migrations, validation\nand warning results, preview environment/commit/tool versions and safe action\nsummary, and every skipped/constrained dependency with the reason. Include baseline\nand final audit results, security overrides with their rationale and removal\ncondition, unresolved advisories, and audit coverage limits. For shipping,\ninclude branch, reviewed commit/verdict, PR, merge, publish/deploy result, and final\ncheckout state. For a repository sweep, keep one entry per repository, including\nunready or unchanged checkouts. Do not publish credentials, state, or plan contents.\n"
+  "update-dependencies": "---\nname: update-dependencies\ndescription: Update a repository's dependency manifests, lockfiles, runtimes, tools, and CI pins with upstream migrations, compatibility checks, and non-destructive infrastructure previews.\n---\n\n# Update Dependencies\n\nUse the repository's package managers and installed `agent-tool`. Read `AGENTS.md`,\nREADME, existing dependency-maintenance notes, linked setup/release documents,\nand repository-owned upgrade skills before editing. Follow their hooks, version\npolicy, checks, and requested stopping point.\nUpdate applicable dependencies throughout the repository, including workspaces\nand examples. This skill does not authorize deploying, merging, publishing, or\nchanging global tools; use existing user authorization and `ship-pr` when shipping\nis requested. Default dependency-update merge subject: `chore: update dependencies`,\nsubject to repository title policy and any explicit user subject.\n\nRun noisy installs, checks, tests, and builds with\n`agent-tool run --label <check> -- <command> [args...]` to retain full private\nlogs and return the original status with compact output. Inspect bounded excerpts\nusing `agent-tool logs <log>` and targeted searches for warnings and evidence;\na successful receipt does not establish a warning-free upgrade. Keep structured\naudit/plan results, deployment previews, and review findings directly visible\nwhen they drive a safety decision. Do not dump full suite logs into context,\nsilence warnings at their source, or change check scope to reduce output.\n\n## Safety before execution\n\n**Always dry-run before any infrastructure apply or deployment. Never destroy,\nreplace, or recreate a resource during an upgrade.** This includes Terraform,\nOpenTofu, Wrangler, Ansible, other infrastructure tools, and effects triggered by\ninstallation, tests, hooks, Git push, opening a PR, CI, or merging. Greenfield\nprojects and approval to ship do not waive this rule.\n\nBefore running project commands or pushing, trace their scripts, hooks, workflow\ntriggers, reusable workflows, and deployment commands. A dry-run flag alone is\ninsufficient: inspect tasks, provisioners, plugins, external programs, and actions\nthat can mutate despite preview mode. Avoid such a preview unless its effects\nare proven read-only. Do not run destroy/delete, taint/replace, state removal,\nbackend migration, forced database reset, or an automatic \"repair\" that bypasses\nthe rule. Do not hide destruction with targeting, disabled refresh, ignored\nchanges, new resource identities, or weakened policy.\n\nPreview with the proposed versions and complete configuration for each affected\nenvironment, using its real backend/workspace/account, variables, inventory, and\nresource identities. An empty local state, mocked credentials, validate-only run,\nor bundle build cannot establish safety for production. Check the current baseline\nas well when needed to distinguish existing drift from the upgrade. Keep state,\nbinary plans, JSON plans, and secret-bearing diffs out of Git and public reports.\n\nIf a preview proposes deletion or replacement, fails, is incomplete, omits\naffected resources, or cannot establish safety, skip that dependency and its\ncoupled migrations. Restore only this task's edits to the affected compatibility\ngroup, retain independent safe upgrades, and record the reason and affected\nresources. Never apply to find out. A preview is not deployment authorization.\n\nBefore an authorized apply/deploy, verify the exact validated commit, toolchain,\nconfiguration, environment, and current state still match the preview. Re-preview\nafter relevant changes or drift. CI must enforce the same order and stop on an\nunsafe preview before mutation; a successful local preview does not excuse an\nunguarded push- or merge-triggered deployment. Establish a narrowly scoped guard\nwhen authorized and reviewable, or hold the affected upgrade before triggering\nthat workflow. Do not disable protections to ship. A plan must be inspected before\nthe operation; inspecting deployment logs afterward is too late.\nAn unsafe workflow triggered on every branch push also blocks pushing otherwise\nindependent upgrades until that trigger has a proven safe guard.\n\n### Terraform and OpenTofu\n\nRead core, provider, and module upgrade guides, including intermediate major\nmigrations. Regenerate provider locks with the pinned CLI, preserving supported\nplatform hashes. Backend initialization/migration is also subject to the safety\ngate. Inspect external data programs and provisioners before planning.\n\nUse a full refreshed saved plan with locking and the real variables, for example\n`terraform plan -input=false -out=<private-plan>`; if using `-detailed-exitcode`,\n0 and 2 are success, 1 is failure. Inspect `terraform show -json <private-plan>`.\nRun `agent-tool dependencies check-terraform-plan <private-plan.json>` to check\nsupported JSON resource actions. It fails for every action containing `delete`,\nincluding both replacement orders, unknown actions, incomplete/deferred plans,\nfailed checks, or opaque provider action invocations. It prints actions and\ndiagnostics without resource attribute values; it does not prove that a plan is\nfresh, comprehensive, authentic, or that provider code has no hidden effects.\nOlder/unsupported plan formats that cannot establish completeness are skipped.\nOpenTofu currently omits `complete` in its JSON format and is rejected by this\nhelper; report that limitation rather than adding a synthetic completeness flag.\nAlso inspect resource identity, drift, warnings, provider semantics, and any\neffects outside resource actions. For an authorized apply, consume the exact\napproved saved plan, not an uninspected newly generated plan.\n\nSource: [Terraform JSON plan format](https://developer.hashicorp.com/terraform/internals/json-format).\n\n### Wrangler and other deployment tools\n\nUse the proposed pinned Wrangler for `wrangler deploy --dry-run` with the same\nbuild/configuration/environment used by deployment. This checks bundling, not a\ncomplete remote resource plan. Separately verify account, worker name, routes,\nbindings and resource IDs against the existing deployment and read migration\nsemantics. Review Durable Object deleted/renamed classes, D1 schema/data\nmigrations, storage resources, queues, containers, and deployment integrations.\nNever infer \"no destruction\" from a successful bundle. Resource removals,\nreplacement, or unprovable remote effects skip the affected group. Apply the\nequivalent preview and identity checks to other tools rather than assuming they\nshare Terraform's guarantees.\n\nDo not assume `wrangler d1 migrations list --remote` is read-only. The\nimplementation inspected for this skill initializes migration tracking with\n`CREATE TABLE IF NOT EXISTS`; verify the pinned Wrangler version before using\nthe command. Verify database identity and compare migration files with the\ndatabase's configured migration tracking table through audited read-only\nqueries. A missing table, pending migration, or unverifiable schema/data\neffects hold the affected upgrade/deployment group. Never initialize schema\nmerely to establish preview safety.\n\nWrangler runs a custom `build.command` again during deployment. Use supported\nconfiguration referencing the same validated artifacts for both preview and\ndeployment, preventing another unvalidated build before upload. Bind the\nartifacts, configuration, and pinned tool to the authorized commit, and recheck\ntheir identities before upload and after relevant changes. Hold the affected\ngroup if the pinned Wrangler cannot upload the validated output without\nrebuilding it, or if the upload cannot be proven to match the preview.\n\nSources: [Wrangler command documentation](https://developers.cloudflare.com/workers/wrangler/commands/),\n[D1 migration listing implementation](https://github.com/cloudflare/workers-sdk/blob/e3d186776fcc2e4b5cc4cfd7155591778a375957/packages/wrangler/src/d1/migrations/list.ts),\n[migration table initialization](https://github.com/cloudflare/workers-sdk/blob/e3d186776fcc2e4b5cc4cfd7155591778a375957/packages/wrangler/src/d1/migrations/helpers.ts),\nand [Wrangler custom builds](https://developers.cloudflare.com/workers/wrangler/custom-builds/).\n\n### Ansible\n\nCheck controller Python, ansible-core, collections/roles, and target Python support\ntogether; read porting guides. Inspect all tasks and invoked scripts before\n`ansible-playbook --check --diff` with the real inventory and variables.\n`check_mode: false` forces mutation even with `--check`; unsupported modules and\nconditions based on registered results can omit effects. Inspect deletion,\nrecreation, service/data reset, and package removal semantics beyond the diff.\nSkipped or opaque tasks are a safety gap, not a clean preview. Redact diffs.\n\nSource: [Ansible check mode limits](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html).\n\n## Inventory and choose compatible targets\n\nRecord each dependency source, current resolved version, latest stable candidate,\nselected target, compatibility constraints, upstream migration links, and checks\nin the run ledger described under Report.\nQuery authoritative registries, official releases, support matrices, and migration\nguides at execution time; do not treat remembered versions or prereleases as\nlatest stable. Inspect runtime requirements, peer dependencies, ABI/API changes,\nplatform availability, maintained release lines, and changed defaults, including\nsecurity, privacy/telemetry, data retention, and postinstall/native behavior.\nCheck transitive dependencies' peer/runtime constraints as well as direct ones. Unsupported\nor unpublished targets stay pinned with an explanation.\n\nInventory manifests, locks, tool configuration, CI/reusable actions, containers,\nscripts, deployment files, and executable documentation. Search duplicate version\npins and aliases, not just filenames; exclude vendored/generated snapshots unless\nthe repository owns their update process. Examples of sources to inspect:\n\n| Ecosystem | Sources and compatibility group |\n| --- | --- |\n| JavaScript/TypeScript | All package.json dependency fields, overrides/resolutions, workspace catalogs, packageManager/engines, npm/Bun/pnpm/Yarn locks, Node/Bun pins, compiler and lint/build/test plugins |\n| Toolchains | mise.toml/.mise.toml, mise.lock, .tool-versions, runtime version files, tool URLs/checksums, CI pins and container images; include every tool declared by mise, not just mise itself |\n| Python/Ansible | pyproject/requirements, uv/Poetry/pip locks, Python pins, ansible-core, collection/role requirements, lint plugins and managed host constraints |\n| Ruby/iOS | .ruby-version, Gemfile/lock, Bundler, CocoaPods, Podfile/lock, podspecs, Swift packages and Xcode/iOS deployment requirements |\n| Infrastructure | Terraform/OpenTofu CLI constraints, provider locks/constraints, module versions/Git refs, Wrangler and Cloudflare integration dependencies |\n| CI/system/native | Actions/reusable workflow refs, Docker tags/digests, OS images/packages, Rust/Cargo toolchain and locks, Go modules, Gradle/AGP/Kotlin/JDK and other repository-specific manifests |\n\nBuild connected compatibility groups before editing. Select the newest supported\ncombination, which can be older than an individual package's latest. Upgrade the\nframework first or keep its compatible toolchain pinned; do not force peer\nresolution, drop compatibility checks, or add blanket overrides to make installs\npass. Preserve source pin policy (exact version, digest, full Git SHA) and resolve\nimmutable pins from verified upstream releases. Preserve intentional runtime\nminimums unless migration requires changing the support contract.\n\nFor React Native, use its version-specific upgrade guide/template diffs and\nrepository upgrade skills. Couple React and its renderer, native modules,\nMetro/Babel, CLI, codegen, Hermes/New Architecture, CocoaPods/Bundler/Ruby,\nXcode/iOS deployment targets, and Android Gradle/AGP/Kotlin/JDK/SDK/NDK. For Expo,\nuse the chosen SDK's supported React Native/dependency matrix and its dependency\nchecks. Do not independently update framework-managed pods or generated native\nfiles; use the framework's regeneration workflow and prove iOS/Android builds.\nPermissive peer ranges alone do not prove native renderer or toolchain compatibility;\ncheck the framework's actual supported versions and native implementation.\nAn unavailable native toolchain is a reported validation limit; do not claim the\ngroup verified. See [React Native upgrading](https://reactnative.dev/docs/upgrading).\n\nCheck developer tools' own dependencies too: a compiler release without its old\nprogrammatic API may break test/lint runners that import it even when `tsc` passes.\nAction runtime upgrades can require newer self-hosted runners; preserve workflow\npermissions, action inputs/outputs, caching, artifact semantics, and job names.\n\nCheck current advisories with read-only ecosystem audits against the baseline and\nproposed lockfiles, using the repository's configured registry/advisory sources.\nDo not send private dependency metadata to an unconfigured or unauthorized service;\nreport the resulting coverage limit. Cover direct and resolved transitive dependencies,\nincluding native/platform-specific binaries. Latest direct packages can still\npin vulnerable transitive versions. Trace each finding to its owning dependency,\nverify affected versions, runtime conditions, and remediation in the maintainer's\nadvisory and fixed release. When the owner's range permits a fixed version, use a\ntargeted refresh with the lockfile's owning manager and preserve unrelated\nresolutions; otherwise prefer a supported owner upgrade.\nIf the owner still pins a vulnerable version, a narrowly scoped security patch\noverride may be used only with API/ABI/runtime compatibility evidence and focused\nregression checks of the actual affected integration. Document its rationale and\nremoval condition; a passing install or bundle alone is insufficient. Do not run\nblind audit fixes or use blanket overrides to bypass compatibility constraints.\nReport unresolved advisories and unavailable audit coverage accurately; current\ndirect pins or a partial clean audit do not\nestablish that the whole dependency graph is safe.\n\n## Migrate and validate\n\nCapture relevant baseline checks and warnings first, after screening their side\neffects. Update one compatibility group at a time. Read the upstream instructions\nfor every breaking step; implement required source/config/schema migrations and\nremoved API replacements. Use the manager that owns each lockfile, on the selected\nruntime, and inspect the resulting diff. Refresh transitive dependencies through\ntheir owning direct dependency; do not hand-edit integrity hashes or lock entries.\nReview intentional patches, overrides, and pins before removal; retain them until\nupstream fixes and regression checks demonstrate they are unnecessary.\nAvoid unrelated global installations or environment changes. Use task-local or\nrepository-scoped tools for testing changed runtime pins.\nFor published packages, also validate tarballs and consumer installs with their\ndocumented supported package managers, including manifest/override syntax and\nruntime requirements. A successful owning-manager install does not prove that\npublished metadata works for those consumers.\n\nRun the repository's setup/hooks, frozen installs, lint, typechecks, tests, builds,\npackage/platform smoke checks, and relevant safe integration previews. Resolve\nupgrade-related deprecation warnings at their source. Do not suppress warnings,\nweaken tests, or disable checks; report remaining upstream/pre-existing warnings\nwith evidence and keep a target pinned when migration cannot be completed.\nAdd focused regression coverage when a migration changes behavior; avoid tests\nthat merely assert version strings. Re-run checks after repairs. Report checks\nblocked by missing credentials, platforms, or external services accurately.\nRe-audit the final resolved graph after migrations and repairs.\n\nConfirm every inventory row is upgraded, already current, intentionally constrained,\nor skipped with a concrete reason. Do not present an unresolved group as complete.\nWhen upgrading agent-tool itself, install its managed skills with the same harness\nscope and commit the ownership manifest; never edit generated managed skill copies.\n\nWhen changes depend on another repository's release, ship the producer first and\nconfirm publishing and registry availability before pinning the consumer; include\nits exact version/commit and API migration notes. Independent groups may proceed.\nUse the installed `ship-pr` for authorized shipping and independently review every\nchanged HEAD. Check deployment safety again before its push/open/merge operations.\n\n## Report\n\nKeep run-specific evidence in the upgrade PR body or a linked PR comment: the\ninventory and old/selected versions, completed migrations, validation and warnings,\nbaseline/final audits and coverage limits, preview environment/commit/tool versions\nand safe action summary, and skipped/constrained dependencies with reasons. Include\nsecurity overrides, their rationale and removal condition, and unresolved advisories.\nIf no PR is requested, provide this ledger in the task report; reporting does not\nauthorize opening a PR or issue. For a sweep, keep one entry per repository,\nincluding unready and unchanged checkouts, and use an existing tracking issue only\nwhen explicitly requested. Never create an issue merely to store upgrade evidence.\n\nKeep durable repository guidance focused on what the next upgrade needs: current\ncompatibility constraints, intentional pins/overrides, unresolved advisories, and\nreusable repository-specific procedures. Prefer the existing maintenance document;\notherwise create `docs/dependency-upgrades.md` (or the repository's equivalent)\nonly when there is substantive guidance to preserve. For each constraint, record\nits rationale, upstream advisory/migration/issue link or originating PR, and the\ncondition and check for removing or revisiting it. Do not copy version inventories,\naudit output, validation/preview receipts, or dated run journals into that document.\n\nOn every upgrade, reconcile the existing maintenance document against the final\ndependency graph and checks: update constraints in place, remove resolved entries,\nand link the PR for historical evidence. Keep the root README focused on purpose,\nsetup, supported requirements, and normal usage, with a concise maintenance link\nwhen needed. Keep dependency-maintenance guidance in `AGENTS.md` to a short\nrouting rule and link; do not accumulate upgrade reports in either entrypoint\nor duplicate the maintenance document.\n\nFor shipping, report the branch, reviewed commit/verdict, PR, merge, publish/deploy\nresult, and final checkout state. Keep full logs private; never publish credentials,\nstate, or plan contents in any of these locations.\n"
 };