@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/claude-plugin/hooks/companion-instructions.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Thin shim for src/hooks/companion-instructions.ts, loaded through ts-loader.mjs: the
+ * installed plugin sits inside node_modules, where node's native type stripping is off.
+ */
+import "./ts-loader.mjs";
+
+const { run } = await import("../../src/hooks/companion-instructions.ts");
+process.exitCode = await run();

package/claude-plugin/hooks/hooks.json

@@ -1,9 +1,9 @@
 {
-  "description": "Mate hooks \u2014 PreToolUse artifact-path guardrail, SessionStart banner, companion guidance and session prepare",
+  "description": "Mate hooks \u2014 PreToolUse artifact-path and secret guardrail, SessionStart banner, companion guidance, session prepare then companion instructions, SubagentStart companion instructions",
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|MultiEdit|Bash",
+        "matcher": "Read|Grep|Write|Edit|MultiEdit|NotebookEdit|Bash",
         "hooks": [
           {
             "type": "command",
@@ -38,6 +38,16 @@
           }
         ]
       }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/companion-instructions.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/opencode-plugin/src/add-dir.ts

@@ -1,8 +1,15 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 
 import type { Context } from "@opencode/plugin/promise/plugin";
 
-import { loadSkillInfos } from "../../src/runtime/opencode-audience-layer";
+type CompanionSkill = {
+  id: string;
+  name: string;
+  description?: string;
+  path: string;
+  content: string;
+};
 
 function companionSkillPaths(companionPath: string): string[] {
   return [
@@ -16,28 +23,87 @@ function isWithin(root: string, candidate: string): boolean {
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
+function parseFrontmatter(content: string): { name?: string; description?: string } {
+  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return {};
+
+  const scalar = (key: string) => {
+    const value = match[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim();
+    return value?.replace(
+      /^(?:"([\s\S]*)"|'([\s\S]*)')$/,
+      (_all, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted,
+    );
+  };
+
+  return { name: scalar("name"), description: scalar("description") };
+}
+
+async function findSkillFiles(directory: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    const files: string[] = [];
+    const subdirectories: Promise<string[]>[] = [];
+    for (const entry of entries) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isFile() && entry.name === "SKILL.md") files.push(entryPath);
+      else if (entry.isDirectory()) subdirectories.push(findSkillFiles(entryPath));
+    }
+    const nested = await Promise.all(subdirectories);
+    return [...files, ...nested.flat()];
+  } catch {
+    return [];
+  }
+}
+
+function skillID(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "mate-skill"
+  );
+}
+
+async function loadCompanionSkills(companionPath: string): Promise<CompanionSkill[]> {
+  const files = (await Promise.all(companionSkillPaths(companionPath).map(findSkillFiles))).flat();
+  const skills = await Promise.all(
+    files.map(async (filePath): Promise<CompanionSkill | null> => {
+      try {
+        const content = await fs.readFile(filePath, "utf8");
+        const metadata = parseFrontmatter(content);
+        const name = metadata.name || path.basename(path.dirname(filePath));
+        return {
+          id: skillID(name),
+          name,
+          ...(metadata.description ? { description: metadata.description } : {}),
+          path: filePath,
+          content,
+        };
+      } catch {
+        /** An unreadable companion skill must not prevent the session from loading. */
+        return null;
+      }
+    }),
+  );
+  return skills.filter((skill) => skill !== null);
+}
+
 /**
  * Grants the session access to the companion and registers its skills. The
  * permission hook only widens access for companion resources; every other
  * evaluation keeps OpenCode's own verdict.
  */
-export async function registerCompanionAccess(
-  api: Context,
-  companionPath: string,
-  extraRoots: readonly string[] = [],
-): Promise<void> {
+export async function registerCompanionAccess(api: Context, companionPath: string): Promise<void> {
   const permissionRoot = path.resolve(companionPath);
-  /** An audience layer's files are as readable as the companion's, for this launch only. */
-  const allowedRoots = [permissionRoot, ...extraRoots.map((root) => path.resolve(root))];
 
   await api.permission.hook("evaluate", (event) => {
-    if (event.resources.some((resource) => allowedRoots.some((root) => isWithin(root, resource)))) {
+    if (event.resources.some((resource) => isWithin(permissionRoot, resource))) {
       event.effect = "allow";
       delete event.message;
     }
   });
 
-  const skills = await loadSkillInfos(companionSkillPaths(permissionRoot));
+  const skills = await loadCompanionSkills(permissionRoot);
   if (skills.length === 0) return;
 
   await api.skill.transform((editor) => {

package/opencode-plugin/src/companion.ts

@@ -77,7 +77,6 @@ function buildSystemPrompt(
   context: CompanionContext,
   guidance: MateGuidanceFile,
   wrapperBinPath: string,
-  layerGuidance: string,
 ): string[] {
   const lines = [materializeCompanionGuidance(guidance.companionGuidance, context, wrapperBinPath)];
 
@@ -89,11 +88,6 @@ function buildSystemPrompt(
     lines.push("", `<agents.md>${context.agentsMd.trim()}</agents.md>`);
   }
 
-  /** The audience's guidance follows the companion's, never replaces it. */
-  if (layerGuidance.trim()) {
-    lines.push("", layerGuidance.trim());
-  }
-
   return lines;
 }
 
@@ -188,7 +182,6 @@ export async function registerCompanion(
   api: Context,
   context: CompanionContext,
   env: LaunchEnvironment = process.env,
-  layerGuidance = "",
 ): Promise<void> {
   const guidance = loadGuidance(env, api.location.directory);
   if (!guidance) return;
@@ -199,7 +192,7 @@ export async function registerCompanion(
     return;
   }
 
-  const companion = buildSystemPrompt(context, guidance, wrapperBinPath, layerGuidance).join("\n");
+  const companion = buildSystemPrompt(context, guidance, wrapperBinPath).join("\n");
 
   await api.session.hook("context", (event) => {
     const merged = mergeCompanionSystem(event.system, companion);

package/opencode-plugin/src/server.ts

@@ -11,11 +11,6 @@ import { spawnPrepareRunner } from "../../src/runtime/session-prepare-runner";
 import { readWrapStateSync } from "../../src/runtime/wrap-state";
 
 import { registerCompanionAccess } from "./add-dir";
-import {
-  readTrustedAudienceLayer,
-  readWrappedAudienceLayer,
-  registerAudienceLayer,
-} from "./audience-layer";
 import { missingRuntimeDirectoryMessage, registerCompanion, resolveMateBin } from "./companion";
 import { pluginLaunchEnvironment, type LaunchEnvironment } from "./launch-environment";
 
@@ -56,17 +51,9 @@ export const MateOpenCodePlugin = Plugin.define({
     const context = readContext(env, api.location.directory);
     if (!context.companionPath) return;
 
-    /**
-     * A layer comes from a payload this launch trusts, else from the wrap of
-     * the session's checkout; an inherited environment never names one.
-     */
-    const layer =
-      (await readTrustedAudienceLayer(env)) ??
-      (await readWrappedAudienceLayer(api.location.directory, context.companionPath));
-    await registerCompanionAccess(api, context.companionPath, layer ? [layer.root] : []);
+    await registerCompanionAccess(api, context.companionPath);
     await registerCompanionHooks(api, context, env);
-    await registerCompanion(api, context, env, layer?.contents.guidance);
-    if (layer) await registerAudienceLayer(api, layer.contents);
+    await registerCompanion(api, context, env);
     /** Last: the guardrails above are live while the local phase holds `setup`. */
     const prepareCleanup = await registerPrepare(api, context.companionPath, env);
     return async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.4",
+  "version": "1.0.0-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,8 @@
     "./runtime": "./src/runtime/index.ts",
     "./opencode": "./src/opencode/index.ts",
     "./opencode/tui": "./src/opencode/tui.tsx",
-    "./tui": "./src/tui.ts"
+    "./tui": "./src/tui.ts",
+    "./brand": "./src/brand/index.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -32,6 +33,8 @@
   },
   "scripts": {
     "test": "CI=1 bun ../../test/run-isolated.ts",
+    "test:unit": "CI=1 bun ../../test/run-isolated.ts --suite=unit",
+    "test:integration": "CI=1 bun ../../test/run-isolated.ts --suite=integration",
     "typecheck": "bunx tsc --noEmit -p ../../tsconfig.json",
     "lint": "oxlint src/ opencode-plugin/",
     "lint:fix": "oxlint src/ opencode-plugin/ --fix",
@@ -39,10 +42,14 @@
     "format:check": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" --check"
   },
   "dependencies": {
+    "@fission-ai/openspec": "1.15.0",
     "@opencode/plugin": "^2.0.23",
     "@opentui/core": "^0.5.14",
     "@opentui/keymap": "^0.5.14",
     "@opentui/solid": "^0.5.14",
+    "@secretlint/core": "13.0.7",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.7",
+    "@secretlint/types": "13.0.7",
     "@tanstack/highlight": "0.0.10",
     "@xterm/addon-clipboard": "^0.2.0",
     "@xterm/addon-fit": "^0.11.0",
@@ -51,6 +58,7 @@
     "@xterm/xterm": "^6.0.0",
     "hono": "^4.13.5",
     "ink": "^7.1.0",
+    "marked": "^18.1.1",
     "react": "^19.2.7",
     "react-doctor": "0.9.13",
     "semver": "^7.8.5",

package/src/brand/art.generated.ts

@@ -0,0 +1,69 @@
+// Generated by scripts/brand/generate.ts from assets/logo-kit. Do not edit.
+import type { LogoArt, LogoForm } from "./types";
+
+export const LOGO_ART: Record<LogoForm, LogoArt> = {
+  lockup: {
+    block: [
+      [{"kind":"pane","text":"▄███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"},{"kind":"space","text":"                          "},{"kind":"word","text":"▄▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▄▄▄▄▄"},{"kind":"space","text":"                          "},{"kind":"word","text":"██"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"},{"kind":"space","text":"    "},{"kind":"word","text":"▄█▀▀██▀▀█▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀██"},{"kind":"space","text":"   "},{"kind":"word","text":"▀██▀▀"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀█▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▀▀▀▀▀"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██▄▄██"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"}],
+      [{"kind":"pane","text":"▀███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▀"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄██▄"},{"kind":"space","text":"   "},{"kind":"word","text":"▀█▄▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄▄▄"}],
+    ],
+    ascii: [
+      " ####### ####",
+      "######## #####                          ##",
+      "########                                ##",
+      "######## #####     ########    #####   #####   #####",
+      "######## #####    ##  ##  ##  ##  ##    ##    ##   ##",
+      "########          ##  ##  ##  ##  ##    ##    #######",
+      "######## #####    ##  ##  ##  ##  ##    ##    ##",
+      " ####### ####     ##  ##  ##   ######    ###   ######",
+    ],
+    columns: 52,
+  },
+  symbol: {
+    block: [
+      [{"kind":"pane","text":"▄███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▄▄▄▄▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▀▀▀▀▀"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"}],
+      [{"kind":"pane","text":"▀███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▀"}],
+    ],
+    ascii: [
+      " ####### ####",
+      "######## #####",
+      "########",
+      "######## #####",
+      "######## #####",
+      "########",
+      "######## #####",
+      " ####### ####",
+    ],
+    columns: 14,
+  },
+  wordmark: {
+    block: [
+      [{"kind":"space","text":"                      "},{"kind":"word","text":"▄▄"}],
+      [{"kind":"space","text":"                      "},{"kind":"word","text":"██"}],
+      [{"kind":"word","text":"▄█▀▀██▀▀█▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀██"},{"kind":"space","text":"   "},{"kind":"word","text":"▀██▀▀"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀█▄"}],
+      [{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██▄▄██"}],
+      [{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"}],
+      [{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄██▄"},{"kind":"space","text":"   "},{"kind":"word","text":"▀█▄▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄▄▄"}],
+    ],
+    ascii: [
+      "                      ##",
+      "                      ##",
+      " ########    #####   #####   #####",
+      "##  ##  ##  ##  ##    ##    ##   ##",
+      "##  ##  ##  ##  ##    ##    #######",
+      "##  ##  ##  ##  ##    ##    ##",
+      "##  ##  ##   ######    ###   ######",
+    ],
+    columns: 34,
+  },
+};

package/src/brand/index.ts

@@ -0,0 +1,12 @@
+export { LOGO_ART } from "./art.generated";
+export { BRAND_ACCENT, BRAND_COLORS, type BrandColor, type BrandColorName } from "./palette";
+export { BRAND_SVGS } from "./svg.generated";
+export {
+  LOGO_WORD,
+  chooseLogo,
+  colorEnabled,
+  renderLogo,
+  type LogoChoice,
+  type LogoOptions,
+} from "./terminal";
+export type { BrandSvgs, LogoArt, LogoForm, LogoRow, LogoSegment, LogoSegmentKind } from "./types";

package/src/brand/palette.ts

@@ -0,0 +1,19 @@
+/** A brand colour as a 24-bit hex value plus its nearest xterm 256-colour index. */
+export interface BrandColor {
+  hex: string;
+  ansi256: number;
+}
+
+/** The five colours of the Mate identity, as defined in `assets/logo-kit/BRAND.md`. */
+export const BRAND_COLORS = {
+  ink: { hex: "#1F2421", ansi256: 235 },
+  mateGreen: { hex: "#2E7D5B", ansi256: 29 },
+  cream: { hex: "#F4F0E8", ansi256: 255 },
+  lightGreen: { hex: "#7FD0A6", ansi256: 115 },
+  night: { hex: "#15191A", ansi256: 234 },
+} as const satisfies Record<string, BrandColor>;
+
+export type BrandColorName = keyof typeof BRAND_COLORS;
+
+/** The accent used on surfaces whose background is unknown; it reads on both light and dark. */
+export const BRAND_ACCENT = BRAND_COLORS.mateGreen.hex;

package/src/brand/svg.generated.ts

@@ -0,0 +1,8 @@
+// Generated by scripts/brand/generate.ts from assets/logo-kit. Do not edit.
+import type { BrandSvgs } from "./types";
+
+export const BRAND_SVGS: BrandSvgs = {
+  symbolColor: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" width=\"256\" height=\"256\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">mate logo</title><g id=\"symbol\"><path fill=\"#1F2421\" d=\"M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z\"/><path fill=\"#2E7D5B\" d=\"M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z\"/></g></svg>",
+  symbolOnDark: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" width=\"256\" height=\"256\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">mate logo</title><g id=\"symbol\"><path fill=\"#F4F0E8\" d=\"M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z\"/><path fill=\"#7FD0A6\" d=\"M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z\"/></g></svg>",
+  favicon: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" width=\"256\" height=\"256\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">mate logo</title><rect width=\"256\" height=\"256\" rx=\"48\" fill=\"#1F2421\"/><g id=\"symbol\" transform=\"translate(32 32) scale(0.75)\"><path fill=\"#F4F0E8\" d=\"M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z\"/><path fill=\"#7FD0A6\" d=\"M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z\"/></g></svg>",
+};

package/src/brand/terminal.ts

@@ -0,0 +1,83 @@
+import { LOGO_ART } from "./art.generated";
+import { BRAND_COLORS } from "./palette";
+import type { LogoForm, LogoRow } from "./types";
+
+export interface LogoOptions {
+  /** The largest form wanted; it falls back to smaller forms when it does not fit. */
+  form: LogoForm;
+  /** Columns available on the target stream. */
+  columns: number;
+  isTTY: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export type LogoChoice =
+  | { kind: "block"; form: LogoForm; rows: readonly LogoRow[]; color: boolean }
+  | { kind: "ascii"; form: LogoForm; rows: readonly string[] }
+  | { kind: "word" };
+
+/** The word that stands in for the logo when no art fits. */
+export const LOGO_WORD = "mate";
+
+const FALLBACKS: Record<LogoForm, readonly LogoForm[]> = {
+  lockup: ["lockup", "symbol"],
+  symbol: ["symbol"],
+  wordmark: ["wordmark"],
+};
+
+function asciiWidth(rows: readonly string[]): number {
+  return Math.max(...rows.map((row) => row.length));
+}
+
+/** Whether colour is allowed, following https://no-color.org: any non-empty NO_COLOR disables it. */
+export function colorEnabled(
+  isTTY: boolean,
+  env: Record<string, string | undefined> = {},
+): boolean {
+  return isTTY && !env.NO_COLOR;
+}
+
+/**
+ * Picks the logo encoding for a stream: block art on a TTY (coloured unless NO_COLOR is set),
+ * ASCII otherwise, falling back from the lockup to the symbol to the word `mate` as width runs
+ * out.
+ */
+export function chooseLogo({ form, columns, isTTY, env = {} }: LogoOptions): LogoChoice {
+  for (const candidate of FALLBACKS[form]) {
+    const art = LOGO_ART[candidate];
+    if (!isTTY) {
+      if (asciiWidth(art.ascii) <= columns)
+        return { kind: "ascii", form: candidate, rows: art.ascii };
+    } else if (art.columns <= columns) {
+      return { kind: "block", form: candidate, rows: art.block, color: colorEnabled(isTTY, env) };
+    }
+  }
+  return { kind: "word" };
+}
+
+function hexToRgb(hex: string): string {
+  const value = Number.parseInt(hex.slice(1), 16);
+  return `${(value >> 16) & 255};${(value >> 8) & 255};${value & 255}`;
+}
+
+const NOTE_ON = `\x1b[38;2;${hexToRgb(BRAND_COLORS.mateGreen.hex)}m`;
+const NOTE_OFF = "\x1b[39m";
+
+/** Renders the logo as a string ready to write to a stream, rows separated by newlines. */
+export function renderLogo(options: LogoOptions): string {
+  const choice = chooseLogo(options);
+  if (choice.kind === "word") return LOGO_WORD;
+  if (choice.kind === "ascii") return choice.rows.join("\n");
+
+  return choice.rows
+    .map((row) =>
+      row
+        .map((segment) =>
+          choice.color && segment.kind === "note"
+            ? `${NOTE_ON}${segment.text}${NOTE_OFF}`
+            : segment.text,
+        )
+        .join(""),
+    )
+    .join("\n");
+}

package/src/brand/types.ts

@@ -0,0 +1,33 @@
+/**
+ * What a run of logo cells belongs to. Notes are the three bars of the right pane and the
+ * only cells coloured on an unknown background; panes and the wordmark keep the default
+ * foreground.
+ */
+export type LogoSegmentKind = "pane" | "note" | "word";
+
+/** A run of adjacent cells that share a kind. Spaces between runs are their own segments. */
+export interface LogoSegment {
+  kind: LogoSegmentKind | "space";
+  text: string;
+}
+
+export type LogoRow = readonly LogoSegment[];
+
+/** One logo form in every terminal encoding the kit provides. */
+export interface LogoArt {
+  /** Unicode half-block art, one entry per row. */
+  readonly block: readonly LogoRow[];
+  /** 7-bit ASCII art for streams that are not a TTY. */
+  readonly ascii: readonly string[];
+  /** Width in columns of the block art. */
+  readonly columns: number;
+}
+
+export type LogoForm = "lockup" | "symbol" | "wordmark";
+
+/** The SVG markup a web surface embeds, generated verbatim from the kit. */
+export interface BrandSvgs {
+  readonly symbolColor: string;
+  readonly symbolOnDark: string;
+  readonly favicon: string;
+}

package/src/cli/commands/artifact/artifact.ts

@@ -1,4 +1,6 @@
 import { usage } from "../../usage";
+import { runArtifactArchiveCommand } from "./delivery/archive";
+import { runArtifactLinkCommand } from "./delivery/link";
 import { runArtifactPublishCommand } from "./finish";
 import { runArtifactPendingCommand } from "./pending";
 
@@ -30,6 +32,12 @@ export async function runArtifactCommand(
     case "pending":
       await runArtifactPendingCommand(argv);
       return;
+    case "link":
+      await runArtifactLinkCommand(argv);
+      return;
+    case "archive":
+      await runArtifactArchiveCommand(argv);
+      return;
     default:
       console.error(`Unknown artifact command: ${subcommand ?? ""}`);
       console.error(usage());

package/src/cli/commands/artifact/delivery/archive.ts

@@ -0,0 +1,117 @@
+import {
+  archiveChange,
+  type ArchiveChangeDeps,
+  type ArchiveResult,
+} from "../../../../lib/delivery/archive-change";
+import type { DeliveryRefusal } from "../../../../lib/delivery/record-delivery";
+import { type BooleanFlagSet, parseFlags, positionalArgs } from "../../../parse-flags";
+import {
+  branchFlagsFrom,
+  canonicalRepository,
+  deliveryEditFrom,
+  DIRECT_NEEDS_BRANCH,
+  repositoryFlag,
+  valueFlagError,
+} from "./branch-flags";
+import { resolveDeliveryEnvironment, type DeliveryEnvironmentDeps } from "./environment";
+import {
+  commandOutput,
+  renderDelivery,
+  sharedRefusalMessage,
+  unscopedDeliveryWarning,
+} from "./output";
+
+export interface ArchiveCommandDeps
+  extends DeliveryEnvironmentDeps, Omit<ArchiveChangeDeps, "onWarnings"> {
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+const BOOLEAN_FLAGS: BooleanFlagSet = new Set(["json", "direct", "skip-branch"]);
+
+function refusalMessage(refusal: DeliveryRefusal): string {
+  if (refusal.reason === "unknown-change") {
+    return `mate: no active change named "${refusal.change}" to archive.`;
+  }
+  return sharedRefusalMessage(refusal);
+}
+
+/** Warnings are not repeated here: they go to stderr before anything is archived. */
+function renderHuman(result: ArchiveResult): string[] {
+  return [
+    result.message,
+    ...result.record.deliveries.map(renderDelivery),
+    `  delivery: ${result.settlement.status}`,
+  ];
+}
+
+/**
+ * @command mate artifact archive <change>
+ * @description Archives an active change whether or not its delivery is merged, so a
+ * feature's later changes build on its canonical specs. Writes overlap, dependency, and
+ * incomplete-planning warnings to stderr before archiving, refreshes merge state from the forge when a token
+ * is available, always leaves a `delivery.yaml` (unlinked when none was recorded), then
+ * runs `openspec archive` with the bundled CLI. Merge state is reported, never a refusal.
+ * @flags
+ * - `--repository <org/repo>` — the delivery `--branch` or `--not-applicable` records; defaults
+ *   to the Working Repository.
+ * - `--branch <branch>` / `--direct` — record the delivery branch first, as `artifact link`.
+ * - `--not-applicable <reason>` — record that no branch delivers this change.
+ * - `--skip-branch` — archive with an unlinked record when the user skips the question.
+ * - `--json` — emit an {@link ArchiveResult}.
+ * @remarks Without a recorded delivery and none of the branch flags, nothing is archived:
+ * the result is `needs-branch`, a question rather than a refusal (exit 0), with
+ * `change/<change-name>` suggested when that branch exists, so the caller can ask the user.
+ */
+export async function runArtifactArchiveCommand(
+  argv: string[],
+  deps: ArchiveCommandDeps = {},
+): Promise<void> {
+  const { emitOut, emitErr, refuse } = commandOutput(deps);
+  const flags = parseFlags(argv, BOOLEAN_FLAGS);
+  const flagError = valueFlagError(flags, ["repository", "branch", "not-applicable"]);
+  if (flagError) return refuse(flagError);
+  const json = flags.json === true;
+  const [change] = positionalArgs(argv, BOOLEAN_FLAGS);
+  const branchFlags = branchFlagsFrom(flags);
+  const { branch, notApplicable } = branchFlags;
+  const skip = flags["skip-branch"] === true;
+
+  if (!change) return refuse("mate: artifact archive requires a change name.");
+  if ([branch !== undefined, notApplicable !== undefined, skip].filter(Boolean).length > 1) {
+    return refuse("mate: pass only one of --branch, --not-applicable, or --skip-branch.");
+  }
+  if (branchFlags.direct && branch === undefined) return refuse(DIRECT_NEEDS_BRANCH);
+  const requested = repositoryFlag(flags);
+  if ("error" in requested) return refuse(requested.error);
+  if (requested.repository !== undefined && branch === undefined && notApplicable === undefined) {
+    return refuse("mate: --repository names the delivery --branch or --not-applicable records.");
+  }
+
+  const environment = await resolveDeliveryEnvironment(deps);
+  if ("error" in environment) return refuse(environment.error);
+  const repository = canonicalRepository(environment, requested.repository);
+  const delivery = deliveryEditFrom(branchFlags);
+  const outcome = await archiveChange(
+    environment,
+    {
+      change,
+      ...(repository ? { repository } : {}),
+      ...(delivery ? { delivery } : {}),
+      skipBranch: skip,
+    },
+    {
+      ...deps,
+      onWarnings: (warnings, unscoped) => {
+        for (const warning of warnings) emitErr(`warning: ${warning.message}`);
+        for (const entry of unscoped) emitErr(unscopedDeliveryWarning(change, entry));
+      },
+    },
+  );
+  if ("refusal" in outcome) return refuse(refusalMessage(outcome.refusal));
+
+  const { result } = outcome;
+  if (result.status === "failed") process.exitCode = 1;
+  if (json) emitOut(JSON.stringify(result));
+  else for (const line of renderHuman(result)) emitOut(line);
+}