@rosenfan/matrix 0.1.2 → 0.1.3

package/assets/skills-zh-CN/matrix-claude/SKILL.md

@@ -1,31 +1,33 @@
----
-name: matrix-claude
-description: 将已批准的 Matrix Contract 导出为受边界约束的 Claude Code 任务包，不改变 Matrix 工作流状态。
----
-
+---
+name: matrix-claude
+description: 将已批准的 Matrix Contract 导出为受边界约束的 Claude Code 任务包，不改变 Matrix 工作流状态。
+---
+
 # Matrix Claude Handoff
 
-这是可选旁路，不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml` 或 `events.jsonl`。
-
-仅当变更已进入 Build、`design -> build` 已批准精确 Contract，并且用户明确选择 Claude Code 实现时使用。先检查：
-
-```powershell
-matrix workflow guard build
-```
-
-若结果为 `CONTRACT_CHANGED`、`CONTRACT_UNAPPROVED` 或 `CONTRACT_READ_FAILED`，回到 `$matrix-design`，修订后重新进入 Build 取得新批准。导出只读取批准快照中的 `proposal.md`、`design.md` 与 `plan.md`。
-
-```powershell
-# 通用项目：只导出 Matrix 产物
-matrix workflow export --task-id <ID> --target generic
-
-# FnSec：仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
-matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
-```
-
-任务包包含批准的 Contract hash 与 revision，以及同一快照的 proposal、design、plan。导出本身不改变 Build 阶段；Claude 完成后，补齐 `## Build evidence`，然后继续：
-
-```powershell
-matrix workflow guard build
-matrix workflow transition verify
-```
+这是可选旁路，不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml` 或 `events.jsonl`。它只支持匹配的 full 或 legacy-full 三产物 Contract；新的 lightweight hotfix/tweak 不支持导出。
+
+人类可读 handoff 内容使用 inspect 的 `artifact_language`；稳定的机器可读标题和 metadata key 保持不变。
+
+仅当变更已进入 Build、`design -> build` 已批准精确 Contract，并且用户明确选择 Claude Code 实现时使用。先检查：
+
+```powershell
+matrix workflow guard build
+```
+
+若结果为 `CONTRACT_CHANGED`、`CONTRACT_UNAPPROVED` 或 `CONTRACT_READ_FAILED`，回到 `$matrix-design`，修订后重新进入 Build 取得新批准。导出只读取批准快照中的 `proposal.md`、`design.md` 与 `plan.md`。
+
+```powershell
+# 通用项目：只导出 Matrix 产物
+matrix workflow export --task-id <ID> --target generic
+
+# FnSec：仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
+matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+任务包包含批准的 Contract hash 与 revision，以及同一快照的 proposal、design、plan。导出本身不改变 Build 阶段；Claude 完成后，补齐 `## Build evidence`，然后继续：
+
+```powershell
+matrix workflow guard build
+matrix workflow transition verify
+```

package/assets/skills-zh-CN/matrix-design/SKILL.md

@@ -3,14 +3,18 @@ name: matrix-design
 description: 在实现前设计并冻结活动 Matrix 变更。
 ---
 
-# Matrix Design
-
-读取 `matrix workflow inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
+# Matrix Design
+
+Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
 
-- **Prim**：使用 Matrix 自身能力调查并设计。
-- **Arch**：仅按事实触发 `domain-modeling`、`research`、`wayfinder`、`prototype`、`codebase-design`，不得机械执行固定序列。每次调用前说明能力与原因。
+design 和 plan 正文使用 `matrix workflow inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
 
-长期有效的领域、ADR 或研究产物遵循仓库约定，关键结论必须同步进入 Matrix design/plan。prototype 默认写入系统临时目录。companion 不得拥有 Matrix 状态或创建竞争计划。重大范围或架构决策须先由用户确认。
+读取 `matrix workflow inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
+
+- **Prim**：使用 Matrix 自身能力调查并设计。
+- **Arch**：仅按事实触发 `domain-modeling`、`research`、`wayfinder`、`prototype`、`codebase-design`，不得机械执行固定序列。每次调用前说明能力与原因。
+
+长期有效的领域、ADR 或研究产物遵循仓库约定，关键结论必须同步进入 Matrix design/plan。prototype 默认写入系统临时目录。companion 不得拥有 Matrix 状态或创建竞争计划。重大范围或架构决策须先由用户确认。
 
 ```powershell
 matrix workflow guard design

package/assets/skills-zh-CN/matrix-hotfix/SKILL.md

@@ -5,4 +5,4 @@ description: 为可复现的小型缺陷运行受约束的 Matrix 工作流。
 
 # Matrix Hotfix
 
-从 `$matrix` 以 `hotfix` 工作流启动并保持冻结的 Prim/Arch 编排。Prim 自行诊断；Arch 仅在真实失败存在且根因未知时调用 `diagnosing-bugs`。companion 输出必须回到 Matrix 产物与状态。若问题影响架构、公开 API、数据模式或多模块协调，受控 Return 后升级为完整工作流。
+从 `$matrix` 以 `hotfix` 启动，共用 `open → build → verify → archive` lightweight 生命周期，不维护独立 hotfix 状态机。Build 前记录预期/实际行为和可复现失败信号，展示紧凑 Contract 并等待确认；Build 记录复现与根因，Verify 记录回归证据。若影响架构、公开 API、数据模式或多模块协调，受控 Return 后升级为 full。

package/assets/skills-zh-CN/matrix-open/SKILL.md

@@ -3,16 +3,26 @@ name: matrix-open
 description: 将开发请求澄清为有证据的 Matrix 提案。
 ---
 
-# Matrix Open
-
-读取 `matrix workflow inspect` 的活动变更与冻结 `orchestration`；写入 `artifacts/proposal.md`，必须包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`。
+# Matrix Open
+
+读取 `matrix workflow inspect` 返回的 `profile` 与 `evidence_policy`。
 
-- **Prim**：使用 Matrix 自身能力澄清并编写提案。
-- **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
+proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
 
-companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
+- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
+- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
+- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
+- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
+
+- **Prim**：使用 Matrix 自身能力澄清并编写提案。
+- **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
+
+companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
 
 ```powershell
-matrix workflow guard open
-matrix workflow transition design
-```
+matrix workflow guard open
+# full
+matrix workflow transition design
+# hotfix/tweak，仅在用户明确确认后
+matrix workflow transition build --confirmed
+```

package/assets/skills-zh-CN/matrix-status/SKILL.md

@@ -8,8 +8,8 @@ description: 检查活动 Matrix 工作流的磁盘状态、守卫与恢复命
 执行：
 
 ```powershell
-matrix workflow inspect
-matrix workflow doctor
-```
-
-报告变更 ID、工作流、冻结 `orchestration`、阶段、守卫结果、`next_skill`、Workflow health、未完成 transaction、可用策略和精确恢复命令。Arch 完整性失败时列出平台/Skill 事实并报告 `matrix init --with-mattpocock`，不得把 change 解释为 Prim。两条命令都只读；不得推断恢复策略、运行 `--repair` 或修改状态。
+matrix workflow inspect
+matrix workflow doctor
+```
+
+报告变更 ID、工作流、`profile`、`evidence_policy`、冻结 `orchestration`、阶段、守卫结果、`next_skill`、Workflow health、未完成 transaction、可用策略和精确恢复命令。Arch 完整性失败时列出平台/Skill 事实并报告 `matrix init --with-mattpocock`，不得把 change 解释为 Prim。两条命令都只读；不得推断恢复策略、运行 `--repair` 或修改状态。

package/assets/skills-zh-CN/matrix-tweak/SKILL.md

@@ -5,4 +5,4 @@ description: 为边界清晰的小改动运行轻量 Matrix 工作流。
 
 # Matrix Tweak
 
-从 `$matrix` 以 `tweak` 工作流启动并保持冻结的 Prim/Arch 编排。保持提案和设计简洁，但仍定义验收条件与测试边界。Arch 只调用满足正常事实触发条件的能力，轻量流程不会获得固定 companion 序列或更弱的证据要求。若涉及 API、模式、架构或跨模块协调，受控 Return 后升级为完整工作流。
+从 `$matrix` 以 `tweak` 启动，共用 `open → build → verify → archive` lightweight 生命周期，不维护独立 tweak 状态机或 Design 阶段。修改实现前，在紧凑 proposal 中定义当前/保留行为、diff 边界、验收与验证，展示后等待确认；Build 与 Verify 必须证明范围和 diff 一致。若涉及 API、模式、架构或跨模块协调，受控 Return 后升级为 full。

package/assets/skills-zh-CN/matrix-verify/SKILL.md

@@ -3,23 +3,25 @@ name: matrix-verify
 description: 依据计划验证 Matrix 变更并审查差异。
 ---
 
-# Matrix Verify
-
-运行计划的验证命令，在 `verification.md` 写入 `## Test evidence`。读取冻结 `orchestration`：
-
-- **Prim**：Matrix 自行完成 Standards 与 Spec 双轴审查。
-- **Arch**：调用 `code-review` 产生双轴证据，并说明调用原因。
-
-审查结果只是 Matrix Verify 的输入；companion 不得决定阶段结果、扩大已批准架构、推进或归档。不得调用事后架构改进 wrapper。正确安装的审查能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须停止。
+# Matrix Verify
 
-失败时使用受控 Return：
+运行已批准 Contract 的验证命令，在 `verification.md` 写入 `## Test evidence`。hotfix 另写 `## Regression evidence`；tweak 另写 `## Scope review evidence`。读取冻结 `orchestration`：
 
-```powershell
-matrix workflow return build --reason verification-failed
-matrix workflow return design --reason acceptance-or-design-gap
-```
-
-Return 会轮换旧 `verification.md`；不得把旧结论直接复制为新的当前证据。
+验证正文使用 `artifact_language`；上述 Runtime 所需英文证据标题保持不变。
+
+- **Prim**：Matrix 自行完成 Standards 与 Spec 双轴审查。
+- **Arch**：调用 `code-review` 产生双轴证据，并说明调用原因。
+
+审查结果只是 Matrix Verify 的输入；companion 不得决定阶段结果、扩大已批准架构、推进或归档。不得调用事后架构改进 wrapper。正确安装的审查能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须停止。
+
+失败时使用受控 Return：
+
+```powershell
+matrix workflow return build --reason verification-failed
+matrix workflow return design --reason acceptance-or-design-gap
+```
+
+Return 会轮换旧 `verification.md`；不得把旧结论直接复制为新的当前证据。
 
 ```powershell
 matrix workflow guard verify

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rosenfan/matrix",
-  "version": "0.1.2",
-  "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
+  "version": "0.1.3",
+  "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
   "license": "MIT",
   "type": "module",
   "bin": {

package/src/catalog.js

@@ -10,11 +10,11 @@ export const MATRIX_SKILLS = [
   "matrix", "matrix-open", "matrix-design", "matrix-build", "matrix-verify",
   "matrix-archive", "matrix-hotfix", "matrix-tweak", "matrix-status", "matrix-claude"
 ];
-export const MATT_SKILLS = [
-  "grilling", "domain-modeling", "research", "wayfinder", "prototype",
-  "codebase-design", "tdd", "diagnosing-bugs", "resolving-merge-conflicts", "code-review"
-];
-export const UNMANAGED_MATT_SKILLS = ["grill-with-docs", "implement", "improve-codebase-architecture"];
+export const MATT_SKILLS = [
+  "grilling", "domain-modeling", "research", "wayfinder", "prototype",
+  "codebase-design", "tdd", "diagnosing-bugs", "resolving-merge-conflicts", "code-review"
+];
+export const UNMANAGED_MATT_SKILLS = ["grill-with-docs", "implement", "improve-codebase-architecture"];
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageManifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
@@ -74,19 +74,19 @@ export function hashDirectory(directory, extraFiles = []) {
   return hash.digest("hex");
 }
 
-export function workflowRuntimeSource() { return path.join(packageRoot, "src", "workflow.js"); }
-export function workflowTransactionSource() { return path.join(packageRoot, "src", "workflow-transaction.js"); }
+export function workflowRuntimeSource() { return path.join(packageRoot, "src", "workflow.js"); }
+export function workflowTransactionSource() { return path.join(packageRoot, "src", "workflow-transaction.js"); }
 
 export function releaseCatalog(language = "en") {
   if (!LANGUAGE_IDS.includes(language)) throw new Error(`Unsupported language: ${language}`);
-  const root = sourceSkillsRoot(language);
-  const missing = MATRIX_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")));
-  if (missing.length) throw new Error(`Matrix package is incomplete. Missing: ${missing.join(", ")}`);
-  const runtime = fs.readFileSync(workflowRuntimeSource());
-  const transaction = fs.readFileSync(workflowTransactionSource());
-  const skills = Object.fromEntries(MATRIX_SKILLS.map((skill) => [skill, hashDirectory(path.join(root, skill), [
-    { path: "scripts/matrix-runtime.mjs", contents: runtime },
-    { path: "scripts/workflow-transaction.js", contents: transaction }
-  ])]));
+  const root = sourceSkillsRoot(language);
+  const missing = MATRIX_SKILLS.filter((skill) => !fs.existsSync(path.join(root, skill, "SKILL.md")));
+  if (missing.length) throw new Error(`Matrix package is incomplete. Missing: ${missing.join(", ")}`);
+  const runtime = fs.readFileSync(workflowRuntimeSource());
+  const transaction = fs.readFileSync(workflowTransactionSource());
+  const skills = Object.fromEntries(MATRIX_SKILLS.map((skill) => [skill, hashDirectory(path.join(root, skill), [
+    { path: "scripts/matrix-runtime.mjs", contents: runtime },
+    { path: "scripts/workflow-transaction.js", contents: transaction }
+  ])]));
   return { language, root, version: packageManifest.version, skills, digest: crypto.createHash("sha256").update(JSON.stringify(skills)).digest("hex") };
 }

package/src/cli.js

@@ -1,18 +1,20 @@
 import fs from "node:fs";
-import path from "node:path";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { PLATFORMS } from "./catalog.js";
-import { createDistribution } from "./distribution.js";
-import { text } from "./messages.js";
-import { createUi } from "./ui.js";
-import { invoke } from "./workflow.js";
+import { createDistribution, installedIntent } from "./distribution.js";
+import { text } from "./messages.js";
+import { createUi } from "./ui.js";
+import { invoke } from "./workflow.js";
+import { compareVersions, globalBinPath, latestVersion, selfUpdate } from "./self-update.js";
 
 const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
 const version = JSON.parse(fs.readFileSync(packagePath, "utf8")).version;
-const HELP = `Matrix ${version}\n\nUsage: matrix init [directory] [options]\n       matrix doctor [directory] [options]\n\nOptions:\n  --language <en|zh-CN>\n  --scope <project|global>\n  --platform <claude-code|codex>  (repeatable)\n  --mode <copy|symlink>\n  --with-mattpocock | --without-mattpocock\n  --default-orchestration <prim|arch>\n  --force  --yes, -y  --dry-run  --json  --no-color`;
+const HELP = `Matrix ${version}\n\nUsage: matrix init [directory] [options]\n       matrix update [directory] [options]\n       matrix doctor [directory] [options]\n\nOptions:\n  --language <en|zh-CN>\n  --scope <project|global>\n  --platform <claude-code|codex>  (repeatable)\n  --mode <copy|symlink>\n  --with-mattpocock | --without-mattpocock\n  --default-orchestration <prim|arch>\n  --skip-self-update  --force  --yes, -y  --dry-run  --json  --no-color`;
 
 function parse(argv) {
-  const result = { command: null, directory: null, scope: null, language: null, platforms: [], mode: "copy", matt: null, defaultOrchestration: null, matrixPolicy: "safe", yes: false, dryRun: false, json: false, color: true };
+  const result = { command: null, directory: null, scope: null, language: null, platforms: [], mode: "copy", matt: null, defaultOrchestration: null, matrixPolicy: "safe", yes: false, dryRun: false, json: false, color: true, skipSelfUpdate: false, reexec: false };
   const values = [...argv];
   if (values[0] && !values[0].startsWith("-")) result.command = values.shift();
   while (values.length) {
@@ -22,12 +24,14 @@ function parse(argv) {
     else if (token === "--language") result.language = values.shift();
     else if (token === "--platform") result.platforms.push(values.shift());
     else if (token === "--mode") result.mode = values.shift();
-    else if (token === "--with-mattpocock") result.matt = "missing";
-    else if (token === "--without-mattpocock") result.matt = "none";
-    else if (token === "--default-orchestration") result.defaultOrchestration = values.shift();
+    else if (token === "--with-mattpocock") result.matt = "missing";
+    else if (token === "--without-mattpocock") result.matt = "none";
+    else if (token === "--default-orchestration") result.defaultOrchestration = values.shift();
     else if (token === "--force") result.matrixPolicy = "replace";
     else if (["--yes", "-y"].includes(token)) result.yes = true;
-    else if (token === "--dry-run") result.dryRun = true;
+    else if (token === "--dry-run") result.dryRun = true;
+    else if (token === "--skip-self-update") result.skipSelfUpdate = true;
+    else if (token === "--_reexec") result.reexec = true;
     else if (token === "--json") result.json = true;
     else if (token === "--no-color") result.color = false;
     else if (["--help", "-h"].includes(token)) result.help = true;
@@ -58,29 +62,33 @@ async function intentFrom(options, ui) {
   const language = options.language ?? (options.yes ? "en" : await ui.select("Language / 语言", [{ label: "English", value: "en" }, { label: "中文", value: "zh-CN" }]));
   const scope = options.scope ?? (options.yes ? "project" : await ui.select(text(language, "scopeQuestion"), [{ label: text(language, "project"), value: "project" }, { label: text(language, "global"), value: "global" }]));
   let platforms = options.platforms;
-  if (!platforms.length && interactive && !options.yes) platforms = await ui.selectMany(text(language, "platformsQuestion"), [{ label: "Claude Code", value: "claude-code" }, { label: "Codex", value: "codex" }]);
-  const matt = options.matt ?? (interactive && !options.yes ? (await ui.confirm(text(language, "mattQuestion"), true, labelsFor(language)) ? "missing" : "none") : "missing");
-  const defaultOrchestration = options.defaultOrchestration ?? (interactive && !options.yes && matt === "missing"
-    ? await ui.select(text(language, "orchestrationQuestion"), [{ label: "Arch", value: "arch" }, { label: "Prim", value: "prim" }])
-    : null);
-  return { projectRoot: projectRoot(options.directory), language, scope, platforms, mode: options.mode, matt, defaultOrchestration, nonInteractive: options.yes || !interactive, matrixPolicy: options.matrixPolicy, dryRun: options.dryRun };
+  if (!platforms.length && interactive && !options.yes) platforms = await ui.selectMany(text(language, "platformsQuestion"), [{ label: "Claude Code", value: "claude-code" }, { label: "Codex", value: "codex" }]);
+  const matt = options.matt ?? (interactive && !options.yes ? (await ui.confirm(text(language, "mattQuestion"), true, labelsFor(language)) ? "missing" : "none") : "missing");
+  const defaultOrchestration = options.defaultOrchestration ?? (interactive && !options.yes && matt === "missing"
+    ? await ui.select(text(language, "orchestrationQuestion"), [{ label: "Arch", value: "arch" }, { label: "Prim", value: "prim" }])
+    : null);
+  return { projectRoot: projectRoot(options.directory), language, scope, platforms, mode: options.mode, matt, defaultOrchestration, nonInteractive: options.yes || !interactive, matrixPolicy: options.matrixPolicy, dryRun: options.dryRun };
 }
 
 function render(ui, evaluation) {
   const language = evaluation.intent?.language ?? "en";
-  const actions = (evaluation.actions ?? []).map((item) => `${item.platform}: ${localizedAction(language, item.matrix)}`).join(", ");
-  ui.info(actions ? `${text(language, "preview")}: ${actions}` : evaluation.code);
-  if (evaluation.intent?.defaultOrchestration) ui.muted(`Default orchestration: ${evaluation.intent.defaultOrchestration}`);
+  const actions = (evaluation.actions ?? []).map((item) => `${item.platform}: ${localizedAction(language, item.matrix)}`).join(", ");
+  ui.info(actions ? `${text(language, "preview")}: ${actions}` : evaluation.code);
+  if (evaluation.intent?.defaultOrchestration) ui.muted(`Default orchestration: ${evaluation.intent.defaultOrchestration}`);
   for (const item of evaluation.observations ?? []) ui.muted(`${item.name}: ${text(language, "matrix")} ${localizedState(language, item.matrix)}；${text(language, "matt")} ${localizedState(language, item.matt.state)}${item.matt.inherited ? ` (${text(language, "global")})` : ""}`);
   for (const item of evaluation.diagnostics ?? []) ui.warn(item.code === "USER_MODIFIED_BLOCKED" ? text(language, "replaceQuestion") : item.message ?? item.code);
   for (const item of evaluation.diagnosis ?? []) (item.code === "MATT_INHERITED" ? ui.muted : ui.warn)(item.message ?? item.code);
 }
 
-async function init(options) {
-  const ui = createUi({ color: options.color && !options.json });
-  if (!options.json) await ui.banner();
-  const intent = await intentFrom(options, ui);
-  const distribution = createDistribution();
+async function init(options) {
+  const ui = createUi({ color: options.color && !options.json });
+  if (!options.json) await ui.banner();
+  const intent = await intentFrom(options, ui);
+  return refresh(intent, options, ui);
+}
+
+async function refresh(intent, options, ui) {
+  const distribution = createDistribution();
   let evaluation = distribution.evaluate(intent);
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
   if (!evaluation.ok && evaluation.code === "USER_MODIFIED_BLOCKED" && interactive && !options.yes && await ui.confirm(text(intent.language, "replaceQuestion"), false, labelsFor(intent.language))) evaluation = distribution.evaluate({ ...intent, matrixPolicy: "replace" });
@@ -93,8 +101,52 @@ async function init(options) {
   if (result.code === "PARTIAL") { ui.warn(result.recovery); return 1; }
   ui.success(options.dryRun ? text(intent.language, "dryRunComplete") : text(intent.language, "ready"));
   ui.muted(evaluation.intent.platforms.map((id) => `${PLATFORMS[id].name}: $matrix <request>`).join("\n"));
-  return 0;
-}
+  return 0;
+}
+
+async function update(options) {
+  const ui = createUi({ color: options.color && !options.json });
+  const root = projectRoot(options.directory);
+  const installed = installedIntent({ projectRoot: root });
+  if (!installed.ok) {
+    const result = { ok: false, code: installed.code, message: "No trusted Matrix installation manifest was found. Run matrix init first." };
+    if (options.json) console.log(JSON.stringify(result)); else ui.warn(result.message);
+    return 2;
+  }
+  const forbidden = options.language || options.scope || options.platforms.length || options.matt || options.defaultOrchestration || options.mode !== "copy";
+  if (forbidden) throw new Error("matrix update inherits installation settings. Use matrix init to change language, scope, platform, mode, Matt skills, or orchestration.");
+  const intent = { ...installed.intent, dryRun: options.dryRun };
+  let npm = { status: "skipped", current: version, target: version, reason: options.skipSelfUpdate ? "disabled by --skip-self-update" : null };
+  if (!options.skipSelfUpdate && !options.reexec) {
+    try {
+      const target = await latestVersion(); const comparison = compareVersions(target, version);
+      if (comparison === null) throw new Error("unable to compare registry version");
+      npm = comparison > 0 ? { status: "available", current: version, target } : { status: "skipped", current: version, target, reason: comparison === 0 ? "already latest" : "registry version is older" };
+    } catch (error) {
+      const result = { ok: false, code: "SELF_UPDATE_CHECK_FAILED", npm: { status: "failed", current: version, reason: error.message }, recovery_command: "matrix update --skip-self-update" };
+      if (options.json) console.log(JSON.stringify(result)); else ui.warn(`${result.code}: ${error.message}\nRun ${result.recovery_command} to refresh assets without npm.`);
+      return 2;
+    }
+  }
+  if (options.json && options.dryRun) { console.log(JSON.stringify({ ok: true, code: "DRY_RUN", npm, intent })); return 0; }
+  if (!options.json) {
+    await ui.banner(); ui.info(`Matrix update: CLI ${npm.current}${npm.status === "available" ? ` → ${npm.target}` : ""}`);
+    ui.muted(`Assets: ${intent.scope}, ${intent.language}, ${intent.platforms.join(", ")}`);
+  }
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
+  if (npm.status === "available") {
+    if (!options.yes && interactive && !await ui.confirm(`Upgrade Matrix CLI ${npm.current} → ${npm.target} and then refresh these assets?`, true, labelsFor(intent.language))) return 0;
+    if (options.dryRun) { if (options.json) console.log(JSON.stringify({ ok: true, code: "DRY_RUN", npm, intent })); else ui.success(text(intent.language, "dryRunComplete")); return 0; }
+    const updated = selfUpdate(version, npm.target);
+    if (!updated.ok) { const result = { ok: false, code: "SELF_UPDATE_FAILED", npm: { ...npm, status: "failed", reason: updated.reason }, recovery_command: "matrix update --skip-self-update" }; if (options.json) console.log(JSON.stringify(result)); else ui.warn(`${result.code}: ${updated.reason}`); return 2; }
+    const args = [globalBinPath(), "update", root, "--skip-self-update", "--_reexec", "--yes"];
+    if (options.matrixPolicy === "replace") args.push("--force"); if (options.json) args.push("--json"); if (!options.color) args.push("--no-color");
+    const rerun = spawnSync(process.execPath, args, { stdio: "inherit" });
+    return Number.isInteger(rerun.status) ? rerun.status : 2;
+  }
+  if (options.json) return refresh(intent, { ...options, yes: true }, ui);
+  return refresh(intent, options, ui);
+}
 
 async function doctor(options) {
   const ui = createUi({ color: options.color && !options.json });
@@ -116,7 +168,8 @@ export async function main(argv) {
   const options = parse(argv);
   if (options.version) { console.log(version); return 0; }
   if (options.help || !options.command) { console.log(HELP); return 0; }
-  if (options.command === "init") return init(options);
+  if (options.command === "init") return init(options);
+  if (options.command === "update") return update(options);
   if (options.command === "doctor") return doctor(options);
   throw new Error(`Unknown command: ${options.command}. Run matrix --help.`);
 }