geneseed 3.16.0 → 3.18.0

package/js/build/stubs.mjs

@@ -12,7 +12,7 @@ import { writeText } from '../lib/fs.mjs';
 import { isDir } from '../lib/fs.mjs';
 import { jsonDumpsIndent } from '../lib/json.mjs';
 import { EXCLUDES_FILE } from '../hosts/hosts.mjs';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 
 // ---------------------------------------------------------------------------
 // Seeded stubs. Written once into the bundle and NEVER overwritten — each holds
@@ -34,7 +34,7 @@ const CONTEXT_STUB = {
 
 /** `_build_render.WIKI_STUB`. */
 const WIKI_STUB = `\
-// Geneseed wiki.jsonc — declare your machine-wide knowledge base(s) here, typically
+// geneseed-wiki.jsonc — declare your machine-wide knowledge base(s) here, typically
 // an Obsidian vault (AGENT.md: the Wiki section). Comments are allowed in this file
 // (JSONC). It is host-specific — never commit it. The build created it once, empty,
 // and will never overwrite it.
@@ -183,7 +183,8 @@ const BUNDLE_GITIGNORE = `\
 context.json
 
 # Knowledge-base manifest — holds private machine paths; never commit.
-# (wiki.json is the legacy name from earlier seeds.)
+# (wiki.jsonc and wiki.json are its legacy names from earlier seeds.)
+geneseed-wiki.jsonc
 wiki.jsonc
 wiki.json
 
@@ -220,9 +221,37 @@ export function ensureContextStub(out) {
   seed(path.join(out, 'context.json'), `${jsonDumpsIndent(CONTEXT_STUB, { ensureAscii: false })}\n`);
 }
 
-/** `_build_render.ensure_wiki_stub` — a legacy `wiki.json` counts as present. */
+/** The wiki manifest's name. `geneseed-` says who owns it in a shared `.claude/`/`.opencode/`. */
+export const WIKI_FILE = 'geneseed-wiki.jsonc';
+/** Its earlier names, newest first. Readers still fall back to them for one release. */
+const LEGACY_WIKI_FILES = ['wiki.jsonc', 'wiki.json'];
+
+/**
+ * `_build_render.ensure_wiki_stub`, plus the rename. A legacy manifest is the user's file: it is
+ * RENAMED to `WIKI_FILE` (bytes preserved by construction), never copied and never seeded beside.
+ * A rename that fails (the file held open on Windows) leaves it where it is and seeds nothing —
+ * a seed beside it would fork the user's declarations; the readers' fallback still finds it.
+ * The sibling `.gitignore` follows the rename, or the private paths become committable.
+ */
 export function ensureWikiStub(out) {
-  if (!existsSync(path.join(out, 'wiki.json'))) seed(path.join(out, 'wiki.jsonc'), WIKI_STUB);
+  const dest = path.join(out, WIKI_FILE);
+  if (existsSync(dest)) return;
+  const legacy = LEGACY_WIKI_FILES.find((n) => existsSync(path.join(out, n)));
+  if (!legacy) return seed(dest, WIKI_STUB);
+  try { renameSync(path.join(out, legacy), dest); } catch { return; }
+  ignoreRenamedWiki(path.join(out, '.gitignore'), legacy);
+}
+
+/** Add `WIKI_FILE` to a `.gitignore` that ignores the legacy name and not the new one, in the
+ * file's own line ending. Anything else — no file, no legacy line — is left alone. */
+function ignoreRenamedWiki(gi, legacy) {
+  let text;
+  try { text = readFileSync(gi, 'utf8'); } catch { return; }
+  const lines = text.split(/\r?\n/);
+  if (!lines.includes(legacy) || lines.includes(WIKI_FILE)) return;
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const sep = text.endsWith('\n') ? '' : eol;
+  writeFileSync(gi, `${text}${sep}${WIKI_FILE}${eol}`);
 }
 
 /** `_build_render.ensure_rules_stub`. */
@@ -264,7 +293,7 @@ export const ensureNotebookIndex = storeIndexWriter('NOTEBOOK.md', NOTEBOOK_INDE
  * the two copies must move with it.
  */
 export const SESSION_SEEDS = {
-  'user-rules.md': RULES_STUB, 'PROFILE.md': PROFILE_STUB, 'wiki.jsonc': WIKI_STUB,
+  'user-rules.md': RULES_STUB, 'PROFILE.md': PROFILE_STUB, [WIKI_FILE]: WIKI_STUB,
   'MEMORY.md': MEMORY_INDEX, 'NOTEBOOK.md': NOTEBOOK_INDEX,
 };
 

package/js/build/themes.mjs

@@ -144,9 +144,7 @@ export function syncThemes(themesDir = THEMES) {
   } catch {
     process.stdout.write(`[sync-themes] ${path.basename(tmplPath)} is missing or unreadable `
       + '— there is nothing to sync against.\n');
-    const e = new Error('template unreadable');
-    e.exitCode = 2;
-    throw e;
+    throw Object.assign(new Error('template unreadable'), { exitCode: 2 });
   }
   const tmplKeys = Object.keys(tmpl);
   let changed = 0;

package/js/cli-table.json

@@ -1079,6 +1079,59 @@
       ],
       "mutex": []
     },
+    {
+      "name": "scorecard",
+      "help": "grade a repo with the AI Harness Scorecard (31 checks, five pillars) — scores the repo itself (CI, tests, docs), not the harness files; a reading, never a gate",
+      "description": "",
+      "positionals": [
+        {
+          "names": [],
+          "dest": "path",
+          "metavar": null,
+          "help": "the repo to score (default: the current directory)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": "?",
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "options": [
+        {
+          "names": [
+            "--json"
+          ],
+          "dest": "json",
+          "metavar": null,
+          "help": "print the full assessment as JSON — every check with its score, evidence and fix",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": [
+            "--svg"
+          ],
+          "dest": "svg",
+          "metavar": "PATH",
+          "help": "write the scorecard as an SVG card (grade + one bar per pillar) to PATH instead of printing — the README card is docs/assets/scorecard.svg",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "mutex": []
+    },
     {
       "name": "setup",
       "help": "interactive install wizard (dependency-free, all OSes)",

package/js/hosts/hooks-context.mjs

@@ -32,7 +32,8 @@ const _ERRNO = {
 function asOsError(e, filename) {
   const hit = _ERRNO[e && e.code];
   if (!hit) return String((e && e.message) || e);
-  // Python reprs the filename, so a Windows path comes out with its backslashes doubled.
+  // The `[Errno N] text: 'file'` shape this hook has always printed: the filename is quoted,
+  // so a Windows path comes out with its backslashes doubled.
   return `[Errno ${hit[0]}] ${hit[1]}: ${JSON.stringify(filename).replace(/^"|"$/g, "'")
     .replace(/\\"/g, '"')}`;
 }
@@ -57,7 +58,7 @@ function fnTranslate(pat) {
       if (pat[j] === '!') j += 1;
       if (pat[j] === ']') j += 1;
       while (j < pat.length && pat[j] !== ']') j += 1;
-      // An unterminated `[` is a LITERAL bracket in Python's translate, not an error.
+      // An unterminated `[` is a LITERAL bracket (fnmatch semantics), not an error.
       if (j >= pat.length) { out += '\\['; continue; }
       let body = pat.slice(i + 1, j).replaceAll('\\', '\\\\');
       if (body.startsWith('!')) body = `^${body.slice(1)}`;
@@ -77,9 +78,14 @@ function fnTranslate(pat) {
  */
 let HOST = 'claude';
 
-// Kept in step with adapters/opencode/plugins/geneseed-context.js, same as the Python.
+// Kept in step with adapters/opencode/plugins/geneseed-context.js.
 const EAGER_ROOT = ['AGENTS.md', 'AGENT.md', 'CLAUDE.md', '.cursorrules',
-  'README.md', 'CONTRIBUTING.md', 'user-rules.md', 'PROFILE.md'];
+  'README.md', 'README.adoc', 'CONTRIBUTING.md', 'CONTRIBUTING.adoc', 'user-rules.md', 'PROFILE.md'];
+// Project docs are Markdown or AsciiDoc: the document-project skill writes AsciiDoc when the
+// user asks for it or the docs already are, so a loader blind to `.adoc` would hide those docs.
+// Agent-runtime files (AGENTS.md, CLAUDE.md, specs) stay Markdown whatever the project uses.
+const DOC_EXT = new Set(['.md', '.adoc']);
+const isDoc = (name) => DOC_EXT.has(path.extname(name).toLowerCase());
 const LAZY_DIRS = ['docs', 'doc', 'documentation', 'architecture', 'adr', 'ADR'];
 const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', '.next',
   'target', '.venv', '__pycache__', '.opencode', '.harness']);
@@ -120,7 +126,10 @@ const cost = (s) => s.length + (s.match(/\n/g) || []).length + 2;
 // honoured by `resolveContextSets` (the harness dir is its last candidate). The OpenCode
 // context plugin carries the same list.
 const SESSION_FILES = ['user-rules.md', 'PROFILE.md', 'memory/MEMORY.md', 'anamnesis/MEMORY.md',
-  'notebook/NOTEBOOK.md', 'wiki.jsonc'];
+  'notebook/NOTEBOOK.md', 'geneseed-wiki.jsonc'];
+// The wiki manifest's earlier name, read when the new one is absent (an install not yet re-emitted,
+// or a rename that failed). One release; `wiki.json`, older still, is the build's to rename.
+const LEGACY_WIKI = 'wiki.jsonc';
 // SHA-256 of each seed body in `js/build/stubs.mjs` (`SESSION_SEEDS`), CRLF folded. A file still
 // byte-identical to its seed says nothing, so it is skipped rather than injected as noise.
 // Hashes, not an import: stubs.mjs pulls in the build's writers, and this module loads on every
@@ -128,7 +137,9 @@ const SESSION_FILES = ['user-rules.md', 'PROFILE.md', 'memory/MEMORY.md', 'anamn
 const SEED_SHA256 = new Set([
   '5c2e92fb1acde041e02d9ebf158460d8ff7a07cbc2b447859631604610130721', // user-rules.md
   '29e012c3c4349ea62a9082cbd04bb25599a0ec280d62c33f6e10742809471816', // PROFILE.md
-  'cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8', // wiki.jsonc
+  '3a82c78ccc5d745033c16c354f5eda9d79350c704e9da8d605d380fb1e108d7a', // geneseed-wiki.jsonc
+  // The wiki seed before the rename: the build renames an untouched one byte for byte.
+  'cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8', // wiki.jsonc (legacy)
   '99c786049c260f6baf7aec68a5c0f59907861afe9b867da009440613bdddb907', // MEMORY.md
   '9acb5c9d9cb5dac572104480f05b48cc144e676869bd60e86d8a15b1f6308184', // NOTEBOOK.md
 ]);
@@ -144,8 +155,9 @@ export function sessionFiles(hookRoot) {
   const found = [];
   for (const rel of SESSION_FILES) {
     let abs = path.join(hookRoot, rel);
-    if (rel === 'wiki.jsonc' && process.env.GENESEED_WIKI && isFile(process.env.GENESEED_WIKI)) {
-      abs = process.env.GENESEED_WIKI;
+    if (rel === 'geneseed-wiki.jsonc') {
+      if (process.env.GENESEED_WIKI && isFile(process.env.GENESEED_WIKI)) abs = process.env.GENESEED_WIKI;
+      else if (!isFile(abs)) abs = path.join(hookRoot, LEGACY_WIKI);
     }
     if (!isFile(abs)) continue;
     let text;
@@ -182,9 +194,8 @@ export function globalHookStandingDown(hookRoot, cwd) {
 
 /** `_disp` — relative to the repo root when it sits under it, else verbatim. */
 function disp(pathStr, root) {
-  // `os.path.relpath` raises ValueError across drives and the Python falls back to the
-  // path as given; `path.relative` silently returns an absolute path instead, which would
-  // print a DIFFERENT string rather than the same one.
+  // A path on another drive has no relative form, so it is printed as given. `path.relative`
+  // would silently return an absolute path instead — a different string, not the same one.
   if (path.parse(path.resolve(pathStr)).root.toLowerCase()
       !== path.parse(path.resolve(root)).root.toLowerCase()) {
     return pathStr;
@@ -193,18 +204,18 @@ function disp(pathStr, root) {
 }
 
 
-function rglobMd(dir, acc = []) {
+function rglobDocs(dir, acc = []) {
   for (const name of listDir(dir)) {
     const full = path.join(dir, name);
-    if (isDir(full)) rglobMd(full, acc);
-    else if (isFile(full) && path.extname(name).toLowerCase() === '.md') acc.push(full);
+    if (isDir(full)) rglobDocs(full, acc);
+    else if (isFile(full) && isDoc(name)) acc.push(full);
   }
   return acc;
 }
 
 /**
  * `_discover_context` — the no-manifest path, mirroring the OpenCode context plugin.
- * Root entry docs are eager; other root markdown, the doc trees and monorepo package
+ * Root entry docs are eager; other root docs (.md or .adoc), the doc trees and monorepo package
  * READMEs are lazy.
  */
 export function discoverContext(root, host = HOST) {
@@ -217,12 +228,12 @@ export function discoverContext(root, host = HOST) {
     const name = path.basename(full);
     if (native.includes(name)) continue;
     if (EAGER_ROOT.includes(name)) eager.set(full, null);
-    else if (path.extname(name).toLowerCase() === '.md') lazy.set(full, null);
+    else if (isDoc(name)) lazy.set(full, null);
   }
   for (const d of LAZY_DIRS) {
     const sub = path.join(root, d);
     if (!isDir(sub)) continue;
-    for (const md of sortPaths(rglobMd(sub))) {
+    for (const md of sortPaths(rglobDocs(sub))) {
       const parts = path.relative(root, md).split(/[\\/]/);
       if (parts.some((part) => EXCLUDE_DIRS.has(part))) continue;
       if (!eager.has(md) && !lazy.has(md)) lazy.set(md, null);
@@ -233,8 +244,10 @@ export function discoverContext(root, host = HOST) {
     if (!isDir(base)) continue;
     for (const pkg of sortPaths(listDir(base).map((n) => path.join(base, n)))) {
       if (!isDir(pkg) || EXCLUDE_DIRS.has(path.basename(pkg))) continue;
-      const readme = path.join(pkg, 'README.md');
-      if (isFile(readme) && !eager.has(readme) && !lazy.has(readme)) lazy.set(readme, null);
+      for (const name of ['README.md', 'README.adoc']) {
+        const readme = path.join(pkg, name);
+        if (isFile(readme) && !eager.has(readme) && !lazy.has(readme)) lazy.set(readme, null);
+      }
     }
   }
   return [
@@ -249,6 +262,7 @@ export function discoverContext(root, host = HOST) {
  *
  * `recs` is a Map, not an object: JS reorders integer-like keys on a plain object, and
  * these keys are absolute paths whose iteration order becomes the printed order.
+ * @returns {[Array<{path: string, description: string}>, Array<{path: string, description: string}>, string]}
  */
 export function resolveContextSets(root, hookRoot = null) {
   let manifest = null;
@@ -281,19 +295,18 @@ export function resolveContextSets(root, hookRoot = null) {
   let extend;
   try {
     let data = JSON.parse(raw);
-    // Valid JSON of the wrong SHAPE, guarded on both sides — see the Python original. JS
-    // would not have thrown here (`[].context` is merely undefined), which is exactly why
-    // the guard is written out rather than left to fall out of the language: without it,
-    // the two CLIs disagree about a file a user really does hand-edit.
+    // Valid JSON of the wrong SHAPE (null, a number, an array) is an empty manifest, not a
+    // syntax error. The guard is written out rather than left to fall out of the language:
+    // without it, `null.context` throws into the catch below and a file a user really does
+    // hand-edit is reported as invalid JSON when it is not.
     data = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
     entries = data.context || [];
     if (!Array.isArray(entries)) entries = [];
     extend = Boolean(data.extend);
   } catch {
-    // See the Python original for why the decoder's own message is not quoted: the two
-    // engines disagree on the wording and on the offset, and V8 supplies no offset at all
-    // for the commonest shapes. Reporting the file is what the user needs; reporting
-    // WHICH decoder found it is what makes two implementations impossible.
+    // The decoder's own message is not quoted: its wording and offset are engine details,
+    // and V8 supplies no offset at all for the commonest shapes. Reporting the file is what
+    // the user needs.
     err(`[context] ${manifest} is not valid JSON — no context was loaded `
       + '(fix the syntax, then re-run).\n');
     return [[], [], String(manifest)];

package/js/hosts/hooks.mjs

@@ -201,7 +201,7 @@ const BOB_DENY_EXIT = 2;
  * logs. `gate-error` is a warning too: a crashed gate that blocked every tool call would be
  * a lockout, not a safeguard, and there is no prompt through which the user could clear it.
  */
-const BLOCK_RULES = new Set(['law-1', 'law-4']);
+const BLOCK_RULES = new Set(['law-1', 'law-4', 'rigor-5']);
 
 /**
  * THE GATE LEDGER — one JSON line per ask, nothing per defer.
@@ -358,6 +358,33 @@ const SECRET_RE =
   /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9_-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
 const DOTENV_RE = /(^|[\\/])\.env(\.[^\\/]*)?$/;
 
+/**
+ * External Gate's boundary half: the checks an agent is judged by must sit outside what it can
+ * edit, or a failing check is one edit away from a passing one. A project opts in by listing
+ * them, one repo-relative path per line (`#` comments), in `.geneseed/protected-checks.txt` at
+ * its git root — found by walking up from the WRITE TARGET, not the cwd, so a session in one repo
+ * writing into another reads that other repo's list. The list protects itself. Returns the entry
+ * the path falls under, or null. ponytail: a write tool only — a shell `sed -i` or redirect is
+ * not seen here; CI running the checks is the boundary that holds against that.
+ */
+export const SENSOR_LIST = '.geneseed/protected-checks.txt';
+function protectedCheck(p) {
+  try {
+    const target = resolvePath(p);
+    const root = gitRootOf(path.dirname(target));
+    if (!root) return null;
+    const text = readFileSync(path.join(root, SENSOR_LIST), 'utf8');
+    // `normcase` folds case AND slashes on Windows, so both sides go through it, the trailing
+    // separator of the prefix included.
+    const rel = normcase(path.relative(root, target));
+    const entries = [SENSOR_LIST, ...text.split(/\r?\n/).map((l) => l.trim().replace(/[\\/]+$/, ''))
+      .filter((l) => l && !l.startsWith('#'))];
+    return entries.find((e) => rel === normcase(e) || rel.startsWith(normcase(`${e}/`))) ?? null;
+  } catch {
+    return null;   // no list (the common case) or an unreadable one: nothing is protected
+  }
+}
+
 function ruleGate(args) {
   if (sovereignBypass(args.root)) return 0;
   return ruleDecide(args, readPayload());
@@ -378,6 +405,12 @@ function ruleDecide(args, payload) {
       + 'credential-shaped string. Secrets live in .env or a secret manager, never in a '
       + 'tracked file.');
   }
+  const sensor = protectedCheck(p);
+  if (sensor) {
+    return ask(args, 'rule-gate', 'rigor-5', `Geneseed (External Gate) — ${p} is a protected `
+      + `check (${sensor}, listed in ${SENSOR_LIST}). A check the agent can edit is not a `
+      + 'check: fix the code, not the check, unless the user asks for this edit.');
+  }
   const target = ruleGateTarget(p, args.root);
   if (!target) return 0;
   return ask(args, 'rule-gate', 'process-1', `Geneseed (Persist Insight) \u2014 writing to `

package/js/hosts/hosts.mjs

@@ -128,9 +128,7 @@ export function expanduser(p) {
       + "ntpath/posixpath would guess a home directory for 'user' — this port does not); "
       + 'pass an absolute path, or "~" / "~/…" for your own home directory';
     printErr(`${msg}\n`);
-    const e = new Error(msg);
-    e.exitCode = 1;
-    throw e;
+    throw Object.assign(new Error(msg), { exitCode: 1 });
   }
   return p;
 }

package/js/hosts/installs.mjs

@@ -35,7 +35,7 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 
-import { CONFIG, PACK_ORDER, THEMES, discoverNames, knownSkillIds } from '../build/source.mjs';
+import { CONFIG, PACK_ORDER, THEMES, discoverNames, resolveSkillNames } from '../build/source.mjs';
 import { CLAUDE_STYLE, GLOBAL_MANIFEST, HOSTS, resolvePath } from './hosts.mjs';
 import { registryRoots } from '../inspect/registry.mjs';
 import { printErr, readText, isFile, isDir } from '../lib/fs.mjs';
@@ -408,7 +408,7 @@ export function excludedRulesOfDir(d) {
   }, []);
 }
 
-/** `Excluded skills: bruno-test-writer, daydream` — written only when something is excluded. */
+/** `Excluded skills: bruno, daydream` — written only when something is excluded. */
 const EXCLUDED_SKILLS_RE = /^Excluded skills:[ \t]*(.+?)[ \t]*$/m;
 
 /**
@@ -416,17 +416,23 @@ const EXCLUDED_SKILLS_RE = /^Excluded skills:[ \t]*(.+?)[ \t]*$/m;
  * re-render the same set. Same semantics as `excludedRulesOfDir`: a missing line is `[]`
  * (nothing excluded), and a name this checkout does not ship condemns the whole line to `[]`
  * — re-admitting a skill is the safe direction, and the flag would refuse the name anyway.
+ *
+ * A name that only got OLDER is not unknown: an alias reads back as its target and a retired
+ * name drops out (`resolveSkillNames`), so a skill merge does not quietly re-admit everything
+ * else the install left out. Silent unless the caller passes `notify` — status, diff and the
+ * console call this on every read; the replays that rebuild an install (`rebuild-all`,
+ * `upgrade`, `migrate`) pass it.
  */
-export function excludedSkillsOfDir(d) {
+export function excludedSkillsOfDir(d, notify = null) {
   return firstCarrier(d, (carrierPath) => {
     const text = readMaybe(carrierPath);
     if (text === null) return undefined;
     const m = EXCLUDED_SKILLS_RE.exec(text);
     if (!m) return undefined;
-    const names = m[1].split(',').map((s) => s.trim()).filter(Boolean);
-    const known = knownSkillIds();
-    if (!names.every((n) => known.includes(n))) return [];
-    return [...new Set(names)].sort();
+    const { ids, notices, unknown } = resolveSkillNames(m[1].split(',').map((s) => s.trim()).filter(Boolean));
+    if (unknown.length) return [];
+    if (notify) for (const n of notices) notify(n);
+    return ids;
   }, []);
 }
 

package/js/hosts/mcp.mjs

@@ -5,7 +5,7 @@
  * at "~90 new, already in js/: `_mcp_load`/`readJsonc` (P6c), `settings.mjs`'s atomic write".
  * Measured against `js/`: `readJsonc` had crossed and NOTHING ELSE HAD. `js/web/api.mjs`
  * carries a five-line `mcpLoad` that is the no-host, comment-tolerant reader P6c needed for
- * `wiki.jsonc`, which is one arm of one of these thirteen functions. `_MCP_PRESETS`,
+ * `geneseed-wiki.jsonc`, which is one arm of one of these thirteen functions. `_MCP_PRESETS`,
  * `_mcp_servers_key`, `_mcp_preset_block`, `_mcp_apply`, `_mcp_state`, `_mcp_set_enabled`,
  * `_mcp_load`'s host fork, `_mcp_commented`, `_mcp_save`, `_mcp_config_for`,
  * `_mcp_install_targets`, `_mcp_known_names` and `_mcp_meta` are 168 lines of Python, all

package/js/hosts/native.mjs

@@ -32,6 +32,7 @@ import path from 'node:path';
 import { writeText, copyFile, readText } from '../lib/fs.mjs';
 import { jsonDumps, parseJson, formatValue, formatRepr, isTruthy, isDict } from '../lib/json.mjs';
 import { relPosix } from '../lib/text.mjs';
+import { aliasesOf } from '../build/source.mjs';
 
 /** What a folder skill writes where it needs its own directory — see `writeNativeLayer`. */
 const SKILL_DIR_PLACEHOLDER = '<this-skill-directory>';
@@ -253,6 +254,25 @@ export function stripSkillBodyLinks(body) {
   return body.replace(SKILL_BODY_LINK_RE, '$1');
 }
 
+/**
+ * A first-party skill's SIDE FILES (`src/skills/<stem>/<file>`, beside the flat spec) are
+ * linked from the spec as `[…](<stem>/<file>)` — the path that resolves in `src/` and in the
+ * flat bundle, where doctor's dead-link scan proves it. A native skill sits one level deeper
+ * (`skills/<stem>/SKILL.md`), and an alias or a command copies the body somewhere else again,
+ * so there the link becomes a code-span path under `dir`: the placeholder a host that
+ * announces the skill's base directory resolves, or the answer for one that does not.
+ *
+ * A link with an `#anchor` (which `sideFileProblems` accepts) gets the same pointer with the
+ * anchor DROPPED: the pointer is a path the agent hands to a file-read tool, and
+ * `deep.md#two` names no file. Left unmatched, `stripSkillBodyLinks` would reduce the link to
+ * its label and the agent would never learn where the file is.
+ */
+export function pointSideFiles(body, stem, dir) {
+  // A function, not a `$1` string: `dir` is a real path and may itself hold a `$`.
+  return body.replace(new RegExp(`\\[[^\\]]+\\]\\(${stem}/([^)\\s#]+)(?:#[^)\\s]*)?\\)`, 'g'),
+    (_m, f) => `\`${dir}/${f}\``);
+}
+
 /** `_build_emit._agent_color_map` — validated, always a valid OpenCode slot. */
 function agentColorMap(theme) {
   let raw = null;
@@ -479,8 +499,8 @@ export function claimer(oldOwned, cfg, manifestExisted = true) {
  * `<this-skill-directory>/…`; Claude Code resolves that because it announces each skill's
  * base directory on load, while on Bob the model got the text with a hole in it and went
  * hunting through the filesystem. With the option, every rendered `.md` of a vendored folder
- * has the placeholder replaced by the answer. Only vendored folders carry the placeholder — a
- * flat skill has no siblings to point at.
+ * has the placeholder replaced by the answer. A flat skill with side files points at them
+ * through the same option (`pointSideFiles`), placeholder when it is absent.
  *
  * `opts.claim` — a `claimer` closure the caller shares with its other writers; built from
  * `oldOwned`/`cfg`/`manifestExisted` when absent.
@@ -498,13 +518,15 @@ export function claimer(oldOwned, cfg, manifestExisted = true) {
  */
 export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null, {
   host = 'opencode', oldOwned = null, cfg = null, manifestExisted = true,
-  theme = null, src, skillDirOf = null, claim = claimer(oldOwned, cfg, manifestExisted),
+  theme = null, src = undefined, skillDirOf = null, claim = claimer(oldOwned, cfg, manifestExisted),
 } = {}) {
   const ov = overrides || {};
   if (host === 'claude') warnClaudeIgnored(ov);
   let nAgents = 0;
   let nSkills = 0;
   const written = [];
+  const sideFiles = [];            // [stem, dest, text], written after the loop
+  const claimedSkills = new Set(); // stems whose own SKILL.md claim held
 
   const write = (dest, text) => {
     mkdirSync(path.dirname(dest), { recursive: true });
@@ -534,6 +556,15 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
       continue;
     }
     if (text === null) continue;
+    // A first-party side file rides next to its skill's SKILL.md, read only when the body
+    // points the agent at it; not a skill, so not counted. `sideFileProblems` holds the
+    // layout (a flat spec beside it, one level, `.md`, linked from the body). Held until the
+    // loop ends: written only once its skill's own SKILL.md claim held (the alias rule), so a
+    // user's file at the target never gets a geneseed side file dropped beside it.
+    if (sparts.length === 3 && sparts[0] === 'skills') {
+      sideFiles.push([sparts[1], path.join(skillsDir, sparts[1], sparts[2]), text]);
+      continue;
+    }
     if (sparts.length !== 2 || !sparts[1].endsWith('.md')) continue;
     const [folder, fname] = sparts;
     const targetDir = { agents: agentsDir, skills: skillsDir }[folder];
@@ -567,18 +598,42 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
     } else {
       // Skills are BYTE-IDENTICAL across hosts: name + description, body link-stripped.
       // The user-only key is emitted for every host too — Claude Code and Bob honour it,
-      // OpenCode ignores an unknown key — so the identity holds.
+      // OpenCode ignores an unknown key — so the identity holds. ALIASES are the one
+      // exception: OpenCode has no user-only skill, so an alias skill there would land in the
+      // model's catalogue as a duplicate; it gets a command instead (`writeAliasCommands`).
       fm = [`name: ${stem}`, `description: ${jsonDumps(skillDescription(text))}`];
       if (isUserInvokedOnly(text)) fm.push('disable-model-invocation: true');
-      body = stripSkillBodyLinks(body);
+      body = stripSkillBodyLinks(pointSideFiles(body, stem, skillDirOf ? skillDirOf(stem)
+        : SKILL_DIR_PLACEHOLDER));
       dest = path.join(skillsDir, stem, 'SKILL.md');
       kind = 'skill';
     }
     if (!claim(dest)) continue;
     write(dest, `---\n${fm.join('\n')}\n---\n\n${body}`);
+    if (kind === 'skill') claimedSkills.add(stem);
+    // An old name keeps answering `/name`: user-only, so the model's catalogue lists the
+    // skill once. Read off the already-filtered items, so excluding the target drops its
+    // aliases; through `claim`, so manifest, prune and uninstall own them; not counted.
+    // Only once the target's own claim held: a user's file at the target gets no alias
+    // pointing at a skill this install never wrote.
+    if (kind === 'skill' && host === 'claude') {
+      // The host announces the ALIAS's folder as the base directory, so a side-file pointer
+      // climbs back to the target's.
+      const aliasBody = skillDirOf ? body : stripSkillBodyLinks(
+        pointSideFiles(lstripNewlines(text), stem, `${SKILL_DIR_PLACEHOLDER}/../${stem}`));
+      for (const alias of aliasesOf(text)) {
+        const aliasDest = path.join(skillsDir, alias, 'SKILL.md');
+        if (!claim(aliasDest)) continue;
+        write(aliasDest, `---\nname: ${alias}\ndescription: ${jsonDumps(`Alias of ${stem}.`)}\n`
+          + `disable-model-invocation: true\n---\n\n${aliasBody}`);
+      }
+    }
     if (kind === 'agent') nAgents += 1;
     else nSkills += 1;
   }
+  for (const [stem, dest, text] of sideFiles) {
+    if (claimedSkills.has(stem) && claim(dest)) write(dest, stripSkillBodyLinks(text));
+  }
   return { nAgents, nSkills, written };
 }