@topmindspace/topmind-skills 4.13.0

package/integrations/opencode/tests/opencode-config-shape.test.mjs

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const integrationRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(integrationRoot, "..", "..");
+
+test("OpenCode example config keeps a thin adapter shape", async () => {
+  const raw = await fs.readFile(path.join(integrationRoot, "opencode.example.json"), "utf8");
+  const config = JSON.parse(raw);
+
+  assert.ok(Array.isArray(config.skills.paths));
+  assert.ok(config.skills.paths.includes("${topmind_ENGINE_ROOT}/skills"));
+  assert.equal(config.mcp.topmind.type, "local");
+  assert.deepEqual(config.mcp.topmind.command, [
+    "node",
+    "${topmind_ENGINE_ROOT}/utr/server/topmind-mcp.mjs",
+  ]);
+  assert.deepEqual(config.plugin, [
+    "${topmind_ENGINE_ROOT}/integrations/opencode/plugins/topmind-plugin.ts",
+  ]);
+  assert.doesNotMatch(raw, /\/Users\/|\/home\/|~\//u);
+});
+
+test("OpenCode command templates exist for capture and doctor", async () => {
+  const capture = await fs.readFile(path.join(integrationRoot, "commands", "topmind-capture.md"), "utf8");
+  const doctor = await fs.readFile(path.join(integrationRoot, "commands", "topmind-doctor.md"), "utf8");
+
+  assert.match(capture, /capture -> auto route/u);
+  assert.match(capture, /workspace-write\.capture-note/u);
+  assert.match(doctor, /topmind-cli\.mjs doctor --json --mcp/u);
+});
+
+test("OpenCode plugin skeleton exports a topmind plugin", async () => {
+  const source = await fs.readFile(path.join(repoRoot, "integrations", "opencode", "plugins", "topmind-plugin.ts"), "utf8");
+
+  assert.match(source, /export default async function topmindPlugin/u);
+  assert.match(source, /name: "topmind"/u);
+});
+
+test("OpenCode adapter follows the portable skill-pack contract", async () => {
+  const [pack, target, readme, pluginSource] = await Promise.all([
+    fs.readFile(path.join(repoRoot, "topmind-pack.json"), "utf8").then(JSON.parse),
+    fs.readFile(path.join(repoRoot, "install-targets", "opencode.json"), "utf8").then(JSON.parse),
+    fs.readFile(path.join(integrationRoot, "README.md"), "utf8"),
+    fs.readFile(path.join(repoRoot, "integrations", "opencode", "plugins", "topmind-plugin.ts"), "utf8"),
+  ]);
+
+  assert.equal(pack.portable_contract.requires_desktop, false);
+  assert.equal(target.content_truth, pack.portable_contract.content_truth);
+  assert.ok(target.capabilities.includes("skills"));
+  assert.ok(target.capabilities.includes("mcp"));
+  assert.ok(target.capabilities.includes("plugin"));
+  assert.match(readme, /content truth/u);
+  assert.match(readme, /Expose only `topmind`|only daily.*`topmind`/iu);
+
+  assert.match(pluginSource, /contentTruth:\s*"topmind-workspace\/categories-and-topics"/u);
+  assert.match(pluginSource, /writesContent:\s*false/u);
+  assert.doesNotMatch(readme + "\n" + pluginSource, /should fork OpenCode|write topmind content directly:\s*true|writesContent:\s*true/u);
+});

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@topmindspace/topmind-skills",
+  "version": "4.13.0",
+  "description": "topmind Agent Skills pack — portable markdown skills for capture, organize, write, memory, maintain, loop.",
+  "type": "module",
+  "license": "MIT",
+  "author": "TopMindSpace",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topmindspace/topmind-skills.git"
+  },
+  "homepage": "https://github.com/topmindspace/topmind-skills#readme",
+  "bugs": {
+    "url": "https://github.com/topmindspace/topmind-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "shared/",
+    "install-targets/",
+    "integrations/",
+    "evals/",
+    "topmind/",
+    "topmind-capture/",
+    "topmind-ledger/",
+    "topmind-loop/",
+    "topmind-maintain/",
+    "topmind-memory/",
+    "topmind-organize/",
+    "topmind-wechat/",
+    "topmind-weread/",
+    "topmind-write/",
+    "topmind-x/",
+    "topmind-pack.json",
+    "skills.md",
+    "INSTALL.md",
+    "README.md",
+    "README.zh-CN.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "bin": {
+    "topmind-skills": "bin/install-skills.mjs"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs integrations/opencode/tests/*.test.mjs",
+    "pack": "node scripts/build-pack.mjs",
+    "prepublishOnly": "npm test",
+    "versions": "node -e \"console.log('skills', require('./topmind-pack.json').version)\"",
+    "add": "node bin/install-skills.mjs add",
+    "update": "node bin/install-skills.mjs update",
+    "list": "node bin/install-skills.mjs list"
+  },
+  "keywords": [
+    "agent-skills",
+    "skill-pack",
+    "topmind",
+    "personal-knowledge",
+    "claude-code",
+    "codex",
+    "opencode"
+  ]
+}

package/scripts/build-pack.mjs

@@ -0,0 +1,463 @@
+#!/usr/bin/env node
+/**
+ * topmind Skill Pack — Build & Pack (v4.3+)
+ *
+ * Reads `skills/topmind-pack.json` (single source of truth) and assembles
+ * a portable distributable bundle under `dist/`.
+ *
+ * Outputs (per build) — surface prefix "skills" so users never confuse with Desktop:
+ *   - dist/topmind-skills-<version>.tar.gz
+ *   - dist/topmind-skills-<version>.zip
+ *   - dist/topmind-skills-<version>-manifest.json
+ *   - dist/topmind-skills-<version>.SHA256SUMS
+ *
+ * Bundle layout (top-level prefix is the bundle root):
+ *
+ *   topmind-skills-<version>/
+ *   ├── SKILL.md                            (router entry — Agent Skills root convention)
+ *   ├── skills.md · LICENSE · README.md · topmind-pack.json
+ *   ├── topmind/SKILL.md + references/      (router — daily entry, full copy)
+ *   ├── topmind-capture|organize|…/SKILL.md (actions + optional connectors)
+ *   ├── topmind-loop/DESIGN.md + references/ (when present)
+ *   ├── install-targets/*.json
+ *   ├── evals/evals.json
+ *   └── shared/*.md                         (degradation, receipts, disambiguation, …)
+ *
+ * Why root SKILL.md? Many hosts unzip a pack and look for `SKILL.md` at the
+ * archive root (Agent Skills single-skill convention). topmind is multi-skill;
+ * root SKILL.md is the **router** (same as topmind/SKILL.md) so zip-as-one-skill
+ * loaders work. Full multi-skill install still uses subdirs + shared/.
+ *
+ * Excluded (dev-only): tests/
+ *
+ * Cross-platform: tar.gz uses `tar -czf` (GNU tar + bsdtar). zip tries `zip`
+ * first, then falls back to `tar -a -cf` (bsdtar on Windows 10+/macOS) so the
+ * build works on macOS / Linux / Windows without extra toolchain.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "..");
+// After the topmind-skills split the pack root IS the repo root.
+const skillsRoot = repoRoot;
+const distRoot = path.join(repoRoot, "dist");
+
+// ---- helpers --------------------------------------------------------------
+
+function log(msg) {
+  process.stdout.write(`[build-pack] ${msg}\n`);
+}
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+function sha256File(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+function run(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(" ")} exited ${code}\n${stderr}`));
+    });
+  });
+}
+
+/**
+ * Like `run` but resolves to {ok} instead of rejecting. Used to probe
+ * whether an external command exists before falling back to alternatives
+ * (cross-platform: `zip` is absent on stock Windows, but `tar -a` works there).
+ */
+function tryRun(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.on("error", () => resolve({ ok: false, error: `ENOENT: ${cmd}` }));
+    child.on("exit", (code) =>
+      resolve({ ok: code === 0, error: code === 0 ? null : `${cmd} exited ${code}\n${stderr}` }),
+    );
+  });
+}
+
+// ---- pack.json loader -----------------------------------------------------
+
+async function loadPack() {
+  const raw = await fs.readFile(path.join(skillsRoot, "topmind-pack.json"), "utf8");
+  return JSON.parse(raw);
+}
+
+// ---- file enumeration -----------------------------------------------------
+
+/**
+ * Walk `skills/` and return the relative paths to include in the bundle.
+ *
+ * Include:
+ *   - skills/topmind-pack.json
+ *   - skills/README.md
+ *   - skills/LICENSE
+ *   - skills/<skill>/SKILL.md
+ *   - skills/<skill>/DESIGN.md  (only if present — topmind-loop has one)
+ *   - skills/<skill>/references/ tree (all .md; progressive disclosure resources)
+ *   - skills/install-targets/*.json
+ *   - skills/evals/evals.json
+ *   - skills/shared/*.md
+ *
+ * Exclude:
+ *   - skills/tests/**
+ *   - any dotfile
+ */
+async function collectBundleFiles() {
+  const include = new Set();
+
+  include.add("topmind-pack.json");
+  include.add("README.md");
+  include.add("LICENSE");
+  include.add("INSTALL.md");
+  // Package landing page (canonical lowercase — many agent platforms look for this)
+  include.add("skills.md");
+
+  for (const entry of await fs.readdir(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+    if (["tests", "dist"].includes(entry.name)) continue;
+    if (["install-targets", "evals", "shared"].includes(entry.name)) continue;
+
+    const skillMd = path.join(skillsRoot, entry.name, "SKILL.md");
+    if (await fileExists(skillMd)) include.add(path.join(entry.name, "SKILL.md"));
+    const designMd = path.join(skillsRoot, entry.name, "DESIGN.md");
+    if (await fileExists(designMd)) include.add(path.join(entry.name, "DESIGN.md"));
+    // Progressive disclosure: skill-local references/
+    const refsDir = path.join(skillsRoot, entry.name, "references");
+    for (const rel of await listMarkdownFiles(refsDir, path.join(entry.name, "references"))) {
+      include.add(rel);
+    }
+  }
+
+  for (const f of await fs.readdir(path.join(skillsRoot, "install-targets"))) {
+    if (f.endsWith(".json")) include.add(path.join("install-targets", f));
+  }
+
+  include.add(path.join("evals", "evals.json"));
+
+  for (const f of await fs.readdir(path.join(skillsRoot, "shared"))) {
+    if (f.endsWith(".md")) include.add(path.join("shared", f));
+  }
+
+  return [...include].sort();
+}
+
+/** Recursively list *.md under dir as paths relative to skillsRoot. */
+async function listMarkdownFiles(absDir, relPrefix) {
+  const out = [];
+  let entries;
+  try {
+    entries = await fs.readdir(absDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    const abs = path.join(absDir, e.name);
+    const rel = path.join(relPrefix, e.name);
+    if (e.isDirectory()) {
+      out.push(...(await listMarkdownFiles(abs, rel)));
+    } else if (e.isFile() && e.name.endsWith(".md")) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+async function fileExists(p) {
+  try {
+    const stat = await fs.stat(p);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+// ---- staging --------------------------------------------------------------
+
+/**
+ * Copy the selected files into a staging directory with a top-level prefix
+ * (`topmind-<version>/`). The system tar/zip will archive this directory
+ * verbatim to get the bundle layout.
+ *
+ * mtime is normalized to epoch (1970-01-01) so the resulting tar archive
+ * is byte-stable across rebuilds. zip includes file mtimes in its own
+ * structure, so we set them on the staged files via utimes() too.
+ */
+async function stage(bundleRoot) {
+  await ensureDir(bundleRoot);
+  const files = await collectBundleFiles();
+  const epoch = new Date(0);
+  for (const rel of files) {
+    const src = path.join(skillsRoot, rel);
+    const dest = path.join(bundleRoot, rel);
+    await ensureDir(path.dirname(dest));
+    await fs.copyFile(src, dest);
+    await fs.utimes(dest, epoch, epoch);
+  }
+
+  // Emit an uppercase `SKILLS.md` mirror at the bundle root, but only on
+  // case-sensitive filesystems. On case-insensitive macOS / Windows the
+  // lowercase `skills.md` and uppercase `SKILLS.md` are the same file —
+  // creating both is impossible.
+  try {
+    const lower = path.join(bundleRoot, "skills.md");
+    const upper = path.join(bundleRoot, "SKILLS.md");
+    const lowerContent = await fs.readFile(lower, "utf8");
+    // Probe: write a unique sentinel to `SKILLS.md`. If the FS is
+    // case-insensitive, this overwrites `skills.md` too. We detect that by
+    // reading `skills.md` and seeing whether it now contains the sentinel.
+    const sentinel = `__probe_${Date.now()}__`;
+    await fs.writeFile(upper, sentinel);
+    const reread = await fs.readFile(lower, "utf8");
+    if (reread.trim() === sentinel) {
+      // Case-insensitive: cannot have both. Restore the canonical file.
+      await fs.writeFile(lower, lowerContent);
+      await fs.utimes(lower, epoch, epoch);
+    } else {
+      // Case-sensitive: write the real content as SKILLS.md.
+      await fs.writeFile(upper, lowerContent);
+      await fs.utimes(upper, epoch, epoch);
+    }
+  } catch {
+    // Probe failed — bundle has lowercase only, which is the canonical form.
+  }
+
+  // Root SKILL.md = router (Agent Skills zip-root convention).
+  // Many hosts fail with "SKILL.md not found" when loading multi-skill zips
+  // that only nest topmind/SKILL.md. Stage router at pack root as the entry.
+  const routerSrc = path.join(skillsRoot, "topmind", "SKILL.md");
+  const rootSkill = path.join(bundleRoot, "SKILL.md");
+  if (await fileExists(routerSrc)) {
+    let body = await fs.readFile(routerSrc, "utf8");
+    // Rewrite relative shared links: from topmind/ they are ../shared/;
+    // from pack root they must be shared/. Skill-local references/ → topmind/references/.
+    body = body.replace(/\(\.\.\/shared\//g, "(shared/");
+    body = body.replace(/degradation:\s*\.\.\/shared\//g, "degradation: shared/");
+    body = body.replace(/\((?:\.\.\/)?references\//g, "(topmind/references/");
+    body = body.replace(/\]\((?:\.\.\/)?references\//g, "](topmind/references/");
+    // Prefix a one-line note so hosts know this is a multi-skill pack entry.
+    if (!body.includes("<!-- topmind-pack-root-entry -->")) {
+      const note =
+        "<!-- topmind-pack-root-entry -->\n" +
+        "> **Pack root entry**: this `SKILL.md` is the topmind **router** " +
+        "(same as `topmind/SKILL.md`). Multi-skill install: load sibling " +
+        "`topmind-*/` dirs + `shared/`. See `skills.md` + `INSTALL.md`.\n\n";
+      // Insert after frontmatter if present
+      if (body.startsWith("---")) {
+        const end = body.indexOf("\n---", 3);
+        if (end !== -1) {
+          const after = end + 4; // past \n---
+          body = body.slice(0, after) + "\n" + note + body.slice(after).replace(/^\n*/, "");
+        } else {
+          body = note + body;
+        }
+      } else {
+        body = note + body;
+      }
+    }
+    await fs.writeFile(rootSkill, body);
+    await fs.utimes(rootSkill, epoch, epoch);
+    // Staged-only: not in skills/ source tree; archive includes it via bundleRoot walk.
+    // Manifest file list stays source-based (collectBundleFiles); SKILL.md is pack-entry glue.
+  }
+
+  return files;
+}
+
+// ---- archive builders -----------------------------------------------------
+
+async function writeTarGz(tarPath, bundleRoot) {
+  // BSD tar on macOS, GNU tar on Linux: both support `tar -czf <out> -C <parent> <name>`.
+  // Use the parent dir as cwd so the archive contains exactly the top-level dir.
+  // Files have been mtime-normalized to epoch in stage(), so the archive is
+  // byte-stable across rebuilds.
+  const parent = path.dirname(bundleRoot);
+  const name = path.basename(bundleRoot);
+  await run("tar", ["-czf", tarPath, "-C", parent, name], parent);
+}
+
+async function writeZip(zipPath, bundleRoot) {
+  // Cross-platform zip generation.
+  //   1. `zip -r -q -X`  — works on macOS / Linux (where `zip` is commonly installed)
+  //   2. `tar -a -cf`    — bsdtar auto-format fallback (ships with Windows 10+ and macOS;
+  //                        the `-a` flag infers zip from the `.zip` extension)
+  // GNU tar on Linux does not create zip archives, so strategy 1 is tried first there.
+  const parent = path.dirname(bundleRoot);
+  const name = path.basename(bundleRoot);
+
+  const primary = await tryRun("zip", ["-r", "-q", "-X", zipPath, name], parent);
+  if (primary.ok) return;
+
+  const fallback = await tryRun("tar", ["-a", "-cf", zipPath, "-C", parent, name], parent);
+  if (fallback.ok) return;
+
+  throw new Error(
+    `zip generation failed on this platform.\n` +
+      `  tried: zip -r -q -X → ${primary.error}\n` +
+      `  tried: tar -a -cf   → ${fallback.error}\n` +
+      `Install \`zip\` or ensure bsdtar (Windows 10+/macOS) is available on PATH.`,
+  );
+}
+
+// ---- manifest & checksums -------------------------------------------------
+
+async function writeManifestAndSums(pack, tarPath, zipPath, files) {
+  const fileEntries = [];
+  for (const rel of files) {
+    const data = await fs.readFile(path.join(skillsRoot, rel));
+    fileEntries.push({
+      path: rel,
+      size: data.length,
+      sha256: sha256File(data),
+    });
+  }
+
+  const tarStat = await fs.stat(tarPath);
+  const zipStat = await fs.stat(zipPath);
+  const tarSha = sha256File(await fs.readFile(tarPath));
+  const zipSha = sha256File(await fs.readFile(zipPath));
+
+  const manifest = {
+    schema_version: 1,
+    name: pack.name,
+    label: pack.label,
+    version: pack.version,
+    updated: pack.updated,
+    daily_entry: pack.daily_entry,
+    metadata: pack.metadata,
+    skills: pack.skills.map((s) => ({ id: s.id, role: s.role, human_facing: s.human_facing })),
+    entry_files: pack.entry_files,
+    install_targets: pack.install_targets,
+    archive: {
+      tar_gz: {
+        path: path.basename(tarPath),
+        size: tarStat.size,
+        sha256: tarSha,
+      },
+      zip: {
+        path: path.basename(zipPath),
+        size: zipStat.size,
+        sha256: zipSha,
+      },
+    },
+    files: fileEntries,
+    total_size: fileEntries.reduce((acc, f) => acc + f.size, 0),
+    built_at: new Date().toISOString(),
+    built_by: "scripts/build-pack.mjs",
+  };
+
+  const manifestPath = path.join(distRoot, `topmind-skills-${pack.version}-manifest.json`);
+  await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  const sumsPath = path.join(distRoot, `topmind-skills-${pack.version}.SHA256SUMS`);
+  const sumsText =
+    `${tarSha}  ${path.basename(tarPath)}\n` +
+    `${zipSha}  ${path.basename(zipPath)}\n`;
+  await fs.writeFile(sumsPath, sumsText);
+
+  return { manifestPath, sumsPath, manifest };
+}
+
+// ---- stale artifact cleanup -----------------------------------------------
+
+/**
+ * Remove skills-pack artifacts that belong to a different version (or the
+ * legacy `topmind-<ver>.*` name without the "skills" surface prefix).
+ * Never touch extension (`topmind-clip-extension-*`) or other surfaces.
+ */
+async function cleanStaleArtifacts(currentVersion) {
+  const skillsPrefix = "topmind-skills-";
+  const currentPrefix = `${skillsPrefix}${currentVersion}`;
+  // Legacy ambiguous name (pre surface-prefix rename)
+  const legacyRe = /^topmind-\d+\.\d+\.\d+/u;
+  let cleaned = 0;
+
+  try {
+    const entries = await fs.readdir(distRoot);
+    for (const entry of entries) {
+      const isCurrentSkills = entry.startsWith(currentPrefix);
+      const isOtherSkills =
+        entry.startsWith(skillsPrefix) && !isCurrentSkills;
+      const isLegacyAmbiguous =
+        legacyRe.test(entry) && !entry.startsWith("topmind-clip-extension-");
+      if (!isOtherSkills && !isLegacyAmbiguous) continue;
+      if (isCurrentSkills) continue;
+      await fs.rm(path.join(distRoot, entry), { force: true, recursive: true });
+      cleaned += 1;
+    }
+  } catch {
+    // dist/ might not exist yet — harmless
+  }
+
+  if (cleaned > 0) {
+    log(`cleaned ${cleaned} stale skills artifact(s) from previous versions`);
+  }
+}
+
+// ---- main -----------------------------------------------------------------
+
+async function main() {
+  const pack = await loadPack();
+  const version = pack.version;
+  // Surface-prefixed name: never "topmind-<ver>" alone (looks like the whole product)
+  const bundleTop = `topmind-skills-${version}`;
+
+  await ensureDir(distRoot);
+  const stagingDir = path.join(distRoot, bundleTop);
+  // Idempotent rebuild — clean current version artifacts
+  await fs.rm(stagingDir, { recursive: true, force: true });
+  for (const ext of [".tar.gz", ".zip", "-manifest.json", ".SHA256SUMS"]) {
+    await fs.rm(path.join(distRoot, `${bundleTop}${ext}`), { force: true });
+  }
+
+  // Clean stale artifacts from previous versions to prevent accumulation
+  await cleanStaleArtifacts(version);
+
+  log(`version: ${version}`);
+  log(`staging files into ${bundleTop}/ ...`);
+  const files = await stage(stagingDir);
+
+  const tarPath = path.join(distRoot, `${bundleTop}.tar.gz`);
+  const zipPath = path.join(distRoot, `${bundleTop}.zip`);
+
+  log(`writing tar.gz ...`);
+  await writeTarGz(tarPath, stagingDir);
+  log(`writing zip ...`);
+  await writeZip(zipPath, stagingDir);
+
+  log(`writing manifest + SHA256SUMS ...`);
+  const { manifestPath, sumsPath, manifest } = await writeManifestAndSums(pack, tarPath, zipPath, files);
+
+  // Clean up staging
+  await fs.rm(stagingDir, { recursive: true, force: true });
+
+  const tarStat = await fs.stat(tarPath);
+  const zipStat = await fs.stat(zipPath);
+  log(`done.`);
+  log(`  ${path.basename(tarPath)}  (${tarStat.size} bytes)`);
+  log(`  ${path.basename(zipPath)}  (${zipStat.size} bytes)`);
+  log(`  ${path.basename(manifestPath)}  (${manifest.files.length} files, ${manifest.total_size} bytes uncompressed)`);
+  log(`  ${path.basename(sumsPath)}`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[build-pack] error: ${err.stack || err.message || err}\n`);
+  process.exit(1);
+});

package/shared/capability-degradation.md

@@ -0,0 +1,82 @@
+# topmind Skills — Capability Degradation
+
+> **共享降级表（唯一真源）**。各 SKILL.md frontmatter `degradation` 指向本文件。  
+> Skill 是纯 Markdown 指令集，**不依赖特定运行时**。主路径 = Host 文件工具 + `PROJECT-MODEL`；UTR 为可选加速。边界见 `PRODUCT-BOUNDARIES.md`。  
+> Host 如何三级加载 / 安装 `shared/`：见 [`host-loading.md`](./host-loading.md)。
+
+## 三级能力（主 → 次）
+
+```text
+Level 1（主）: Host 文件工具
+  → 直接读写工作区 Markdown / 目录
+  → 遵守 PROJECT-MODEL 路径与 frontmatter
+  → 写入返回路径回执
+
+Level 2（可选）: UTR CLI / MCP
+  → workspace-read.* / workspace-write.* 等确定性命令
+  → 适合批量、脚本、强校验
+
+Level 3（最低）: 仅对话
+  → 给出路径与步骤；不静默假装已写入
+```
+
+**不要**把「先装 UTR」写成用户前提。
+
+## Level 1 — Host 文件工具
+
+| 意图 | 操作要点 |
+|------|----------|
+| 看类别 | 扫描 `{NN}[- ]{Name}/` + 读 `topmind.yaml` v4（含 categories.extensions / overrides）；跳过 hidden |
+| 看专题 | 列出类别下专题目录 + 根层单篇 `.md` |
+| 检视专题 | 读 `topic.md`（若有）+ 专题根 `.md` |
+| 捕获 | 写带 frontmatter 的 `.md` 到专题根 / 大类根 / role:buffer |
+| 交付 | 写到 role:delivery（常为 `88-交付/`） |
+| 追加记忆 | 默认 `memory/profile.md`（主）或 `memory/periodic/{YYYY}/`（周期反思）；**开专题**写内容大类 `{YYYY-主题}/`；仅用户明说才写 `memory/topics/{slug}.md` |
+| 健康检查 | 遍历结构、报告缺失 / 垃圾；自定义类合法 |
+| 归档 / 恢复 | 移动并写入 role:system（常为 `99-归档/`） |
+
+写回：`auto | confirm`（见 `TOOLS.md`）。
+
+## Level 2 — UTR（可选）
+
+| 需要 | 命令 |
+|------|------|
+| 类别 / 专题 | `list-categories`（WorkspaceModel Descriptor）· `list-topics` · `inspect-topic` · `list-topic-files` · `list-inbox` |
+| 捕获 / 创建 | `create-topic` · `capture-note` · `save-output` |
+| 记忆 | `memory.append-profile` · `memory.append-topic` · `memory.promote` · `memory.digest` |
+| Inbox 路由 | `plan-inbox-routing`（primary；整理 inbox 前规划） |
+| 检查 / 维护 | `doctor-workspace` · `archive-topic` · `archive-stream-year` · `restore-safety-receipt` · `contract.reseed` |
+
+扩展面见 `TOOLS.md` §Current Command Surface。输入用独立字段 `category` + `topic`。
+
+## Level 3 — 对话 only
+
+- 给出明确路径：`{workspace}/{类别}/{专题}/xxx.md`  
+- 描述可手动执行的步骤  
+- 可提示安装 UTR 获得脚本化能力（**非强制**）  
+
+## 回执格式
+
+```text
+已收进/已更新：大类 → 专题（或单篇 / Inbox）
+位置：relative/path.md
+操作：create | update | delete | archive | restore
+保存模式：auto | confirm
+判断：信心与理由（如有）
+下一步：继续写 / 整理（活动窗口）/ 更新我的情况 / 建议开专题（内容大类）/ 手动移动
+```
+
+完整 write evidence 见 `TOOLS.md`。
+
+## Save Settings
+
+```yaml
+writeback_mode: auto | confirm
+```
+
+## 与 Desktop
+
+- Desktop **不是** Skills 运行时，也不是 UTR 的 GUI  
+- Desktop 内捕获 / 编辑 / AI 走 **WorkspaceService**  
+- 同一套 Skills 文案在任意 agent host 独立生效  
+- 四者只共享内容约定，不共享进程