@nanonets/graft 0.24.0 → 0.25.0

package/dist/skills/skillmd.js

@@ -0,0 +1,219 @@
+/**
+ * A learned skill's SKILL.md (design 2.1, spec 6), written and read.
+ *
+ * Only `name` and `description` sit at the top level; everything of Trail's
+ * is under `metadata` as flat quoted strings, and `metadata.trail` is the one
+ * mark that makes a file Trail's. Sections are always Run, Check it worked,
+ * If it fails, Don't use for.
+ *
+ * Every value is written on one line: text a person or an agent wrote (a
+ * repo name, an error line) can't open a line of its own, so it can't start
+ * a `[trail]` line, a heading or a step. Reading goes through phase 0's
+ * guarded front-matter reader (no anchors, aliases or code fences), and a
+ * file without `metadata.trail` is never read for steps: Trail never reads
+ * or edits another skill's steps.
+ */
+import { createHash } from 'node:crypto';
+import { flatLine } from '../notes/flatten.js';
+import { matter } from '../util/front-matter.js';
+import { gatedKind } from './risk.js';
+import { metaToParams } from './params.js';
+export const GATED_PREFIX = "Can't be undone (Claude Code asks the person first): ";
+export const WAIT_NOTE = '(a wait: run it in the background if it may take over 2 minutes)';
+export const BG_NOTE = '(in the background)';
+export const NO_CHECK = 'No check ran in the run this came from.';
+export const NOTHING_FAILED = 'Nothing failed in the run this came from.';
+/** D59b: a check read with a deploy status tool (`check-tool`), not run as a command. */
+export const TOOL_CHECK = 'Check the deployment the same way the run did: ';
+const META_ORDER = [
+    'trail', 'scope', 'applies', 'job', 'asks', 'status-asks', 'params', 'needs', 'ready', 'check-first', 'before-you-start', 'confirm-before', 'check', 'check-shows', 'check-tool', 'version',
+];
+/** Values that are commands or command lists: kept as typed, only made one line. */
+const COMMAND_KEYS = new Set(['params', 'needs', 'ready', 'check-first', 'confirm-before', 'check']);
+const BREAKS = /\r\n|[\n\r\u000b\u000c\u0085\u2028\u2029]/g;
+const HIDDEN = /[\p{Cf}\ufe00-\ufe0f\u{e0100}-\u{e01ef}\u0000-\u0008\u000e-\u001f\u007f-\u0084\u0086-\u009f]/gu;
+const MARKER = /^\s*(?:\[(?:trail|graft|trail-code)\]\s*)+/i;
+/** A command on one line: breaks become spaces, hidden characters go; spaces inside it are kept. */
+export function oneLine(text) {
+    return String(text ?? '').replace(HIDDEN, '').replace(BREAKS, ' ').replace(/\t/g, ' ').replace(MARKER, '').trim();
+}
+/** Prose on one line; three dashes in a row would end the front matter for some readers. */
+const prose = (text, max = 1024) => flatLine(text, max).replace(/-{3,}/g, '--');
+/**
+ * A command as a double-quoted YAML string. Three dashes in a row end the front matter for some readers,
+ * so a dash inside such a run is written `\u002d`, which YAML reads back as `-`: the command stays as typed.
+ */
+const quoted = (cmd) => JSON.stringify(cmd).replace(/-{3,}/g, (m) => `-${'\\u002d'.repeat(m.length - 2)}-`);
+/** The step in a code span whose fence is longer than any backtick run inside it. */
+function codeSpan(cmd) {
+    const longest = Math.max(0, ...[...cmd.matchAll(/`+/g)].map((m) => m[0].length));
+    if (!longest)
+        return `\`${cmd}\``;
+    const fence = '`'.repeat(longest + 1);
+    return `${fence} ${cmd} ${fence}`;
+}
+export function renderSkillMd(c) {
+    const meta = c.meta;
+    const keys = [...META_ORDER, ...Object.keys(meta).filter((k) => !META_ORDER.includes(k))];
+    const front = ['---', `name: ${c.name}`, `description: ${JSON.stringify(prose(c.description))}`, 'metadata:'];
+    for (const k of keys) {
+        const v = meta[k];
+        if (v === undefined || v === null || String(v) === '')
+            continue;
+        front.push(`  ${k}: ${COMMAND_KEYS.has(k) ? quoted(oneLine(String(v))) : JSON.stringify(prose(v))}`);
+    }
+    front.push('---');
+    const run = c.steps.map((s) => {
+        const note = s.wait ? ` ${WAIT_NOTE}` : s.bg ? ` ${BG_NOTE}` : '';
+        return `${s.n}. ${s.gated ? GATED_PREFIX : ''}${codeSpan(oneLine(s.cmd))}${note}`;
+    });
+    let check;
+    const shows = c.checkShows ? prose(c.checkShows, 200) : '';
+    const phrase = /\s/.test(shows);
+    if (!c.check)
+        check = NO_CHECK;
+    else if (c.meta['check-tool'])
+        check = `${TOOL_CHECK}${prose(c.check, 300)}${shows ? `; it shows ${shows}` : ''}.`;
+    else if (c.checkIsStep) {
+        const n = [...c.steps].reverse().find((s) => s.cmd === c.check)?.n;
+        const lead = n ? `Step ${n}, ${codeSpan(oneLine(c.check))}, is the check` : `${codeSpan(oneLine(c.check))} is the check`;
+        check = shows ? `${lead}: ${shows}.` : `${lead}.`;
+    }
+    else if (!shows)
+        check = `${codeSpan(oneLine(c.check))} works.`;
+    else
+        check = `${codeSpan(oneLine(c.check))} shows ${phrase ? shows : codeSpan(shows)}.`;
+    const fails = c.ifFails.map((l) => prose(l, 200)).filter(Boolean);
+    const before = beforeYouStart(c.meta);
+    return [
+        ...front,
+        `# ${prose(c.title, 160)}`,
+        '',
+        ...(before.length ? ['## Before you start', ...before.map((l) => `- ${l}`), ''] : []),
+        '## Run',
+        ...run,
+        '',
+        '## Check it worked',
+        check,
+        '',
+        '## If it fails',
+        ...(fails.length ? fails.map((l) => `- ${l}`) : [NOTHING_FAILED]),
+        '',
+        "## Don't use for",
+        prose(c.dontUse, 300),
+        '',
+    ].join('\n');
+}
+/** D116 item 5: the lines of `metadata.before-you-start`, each one flat line. */
+export function beforeYouStart(meta) {
+    return String(meta['before-you-start'] ?? '').split(' | ').map((l) => prose(l, 200)).filter(Boolean).slice(0, 3);
+}
+export function skillHash(text) {
+    return `sha256:${createHash('sha256').update(String(text ?? '')).digest('hex')}`;
+}
+/** The command in a Run line's first code span, and what follows it (CommonMark code spans). */
+function readSpan(rest) {
+    const open = /`+/.exec(rest);
+    if (!open)
+        return null;
+    const len = open[0].length;
+    const from = open.index + len;
+    const close = new RegExp(`(?<!\`)\`{${len}}(?!\`)`, 'g');
+    close.lastIndex = from;
+    const m = close.exec(rest);
+    if (!m)
+        return null;
+    let cmd = rest.slice(from, m.index);
+    if (cmd.length > 1 && cmd.startsWith(' ') && cmd.endsWith(' ') && cmd.trim())
+        cmd = cmd.slice(1, -1);
+    return { cmd, after: rest.slice(m.index + len) };
+}
+const isMap = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date);
+const SCOPES = new Set(['personal', 'repo', 'team']);
+const JOBS = new Set(['release', 'ship', 'pr-green', 'sweep', 'run-local', 'report', 'tests']);
+const section = (heading) => heading.toLowerCase().replace(/[\u2019']/g, "'").replace(/\s+/g, ' ').trim();
+/** Through phase 0's matter(): null on `refused` (anchors, aliases, non-scalars) or when there is no `metadata.trail` key. */
+export function parseSkillMd(text, folderName) {
+    const src = String(text ?? '');
+    let fm;
+    try {
+        fm = matter(src, { scalars: ['name', 'description'] });
+    }
+    catch {
+        return null;
+    }
+    if (fm.refused)
+        return null;
+    const data = fm.data;
+    const raw = data.metadata;
+    if (!isMap(raw))
+        return null;
+    const strings = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (v === null || v === undefined)
+            continue;
+        if (typeof v === 'object' && !(v instanceof Date))
+            return null;
+        strings[k] = v instanceof Date ? v.toISOString().slice(0, 10) : String(v);
+    }
+    if (!strings.trail?.trim())
+        return null;
+    const meta = {};
+    for (const k of [...META_ORDER, ...Object.keys(strings)])
+        if (strings[k] !== undefined && meta[k] === undefined)
+            meta[k] = strings[k];
+    if (!SCOPES.has(meta.scope))
+        meta.scope = 'personal';
+    if (meta.job !== undefined && !JOBS.has(meta.job))
+        delete meta.job;
+    meta.asks ??= '';
+    meta.version ??= '1';
+    const confirm = new Set((meta['confirm-before'] ?? '').split(' ; ').map((s) => s.trim()).filter(Boolean));
+    const steps = [];
+    const ifFails = [];
+    const dontUse = [];
+    let where = '';
+    for (const line of String(fm.content ?? '').split(/\r?\n/)) {
+        const h = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+        if (h) {
+            where = section(h[1]);
+            continue;
+        }
+        if (where === 'run') {
+            const m = /^\s*\d+\.\s+(.*)$/.exec(line);
+            if (!m)
+                continue;
+            let rest = m[1];
+            const prefixed = /^can[\u2019']t be undone\b[^`]*?:\s*/i.exec(rest);
+            if (prefixed)
+                rest = rest.slice(prefixed[0].length);
+            const span = readSpan(rest);
+            if (!span || !span.cmd.trim())
+                continue;
+            const cmd = span.cmd;
+            const kind = gatedKind(cmd);
+            const gated = kind ?? (prefixed || confirm.has(cmd) ? 'deploy' : null);
+            steps.push({ n: steps.length + 1, cmd, gated, bg: /\(in the background\)/i.test(span.after), wait: /\(a wait\b/i.test(span.after) });
+        }
+        else if (where === 'if it fails') {
+            const m = /^\s*[-*]\s+(.+)$/.exec(line);
+            if (m)
+                ifFails.push(m[1].trim());
+        }
+        else if (where === "don't use for" && line.trim())
+            dontUse.push(line.trim());
+    }
+    return {
+        name: typeof data.name === 'string' && data.name.trim() ? data.name : folderName,
+        description: typeof data.description === 'string' ? data.description : '',
+        meta: meta,
+        steps,
+        check: meta.check?.trim() ? meta.check : null,
+        checkShows: meta['check-shows']?.trim() ? meta['check-shows'] : null,
+        ifFails,
+        dontUse: dontUse.join(' '),
+        params: metaToParams(meta.params),
+        hash: skillHash(src),
+    };
+}
+//# sourceMappingURL=skillmd.js.map

package/dist/skills/skillmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillmd.js","sourceRoot":"","sources":["../../src/skills/skillmd.ts"],"names":[],"mappings":"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"}

package/dist/skills/skills.d.ts

@@ -1,8 +1,18 @@
-/** Where a repo's skills are: the team's in the repo, and this machine's in ~/.trail. */
-export declare function skillDirs(dir: string): {
+/** Trail's and graft's own skills, rewritten by every `init`: never a place for takeaways. */
+export declare const OWN_SKILLS: Set<string>;
+/**
+ * Where a repo's skills are: the repo's in its `.claude/skills/`, and this
+ * machine's in ~/.trail. A link in either is followed only while it stays
+ * inside its root (`repoRoot`, the checkout; `homeRoot`, ~/.trail), so no
+ * skill file outside the repo or ~/.trail is ever read or written.
+ */
+export declare function skillDirs(dir: string): SkillDirs;
+export interface SkillDirs {
     repo: string;
     home: string;
-};
+    repoRoot: string;
+    homeRoot: string;
+}
 export interface Takeaway {
     /** Absolute path of its file. */
     path: string;
@@ -28,9 +38,11 @@ export interface Skill {
     where: "repo" | "home";
     /** Absolute path of its SKILL.md. */
     file: string;
+    /** Trail may rewrite its SKILL.md (skill-file.ts): never when someone wrote it by hand. */
+    trailOwned: boolean;
     takeaways: Takeaway[];
 }
-/** A skill name as a folder: `PDF coords` → `pdf-coords`. */
+/** A skill name as a folder: `PDF coords` → `pdf-coords`. At most 64 characters, cut at a word. */
 export declare function skillName(raw: string): string;
 export declare function parseTakeaway(text: string, path: string, skill: string): Takeaway | null;
 export declare function renderTakeaway(t: Omit<Takeaway, "path">): string;
@@ -77,6 +89,12 @@ export interface FoldResult {
     stillWaiting: number;
     /** The SKILL.md headings that gained lines. */
     sections: string[];
+    /**
+     * Why SKILL.md was left as it is, with takeaways ready: `hand-written`, not
+     * Trail's to rewrite (skill-file.ts); `unreadable`, its front matter isn't
+     * between two `---` lines. The takeaways stay waiting, and still reach the agent.
+     */
+    left?: "hand-written" | "unreadable";
 }
 /**
  * Write a skill's waiting takeaways into its SKILL.md, under the heading each
@@ -87,12 +105,13 @@ export interface FoldResult {
 export declare function fold(dir: string, name: string, opts?: {
     confirmed?: boolean;
 }): FoldResult | null;
+/** `link`: the repo's `.claude/skills/<name>` leads out of the repo, so nothing is written through it. */
 export type PublishResult = {
     ok: true;
     file: string;
 } | {
     ok: false;
-    reason: "unknown" | "in-repo";
+    reason: "unknown" | "in-repo" | "link";
 };
 /**
  * Move a skill kept on this machine into the repo's `.claude/skills/`, where
@@ -111,8 +130,9 @@ export declare function skillForAgent(s: Skill): string;
 /**
  * The line a session starts with about skills an agent can't see by itself:
  * ones kept only on this machine (Claude Code loads `.claude/skills/`, not
- * ~/.trail), and the team's ones with corrections waiting. Empty when there
- * are none, so the directive is unchanged everywhere else.
+ * ~/.trail), and the team's ones with corrections waiting. It names the files
+ * to read: `trail skills show` is the learned skills' command now and can't
+ * print these. Empty when there are none.
  */
-export declare function skillsDirective(dir: string, show: string): string;
+export declare function skillsDirective(dir: string): string;
 //# sourceMappingURL=skills.d.ts.map

package/dist/skills/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/skills/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/skills/skills.ts"],"names":[],"mappings":"AA6BA,8FAA8F;AAC9F,eAAO,MAAM,UAAU,aAA8B,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAGhD;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB;AAKD,mGAAmG;AACnG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7C;AAcD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqBxF;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,CAOhE;AA2FD,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,EAAE,CAI/C;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAEhE;AAED,qCAAqC;AACrC,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,QAAQ,EAAE,CAE5C;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAEhD;AAiBD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,WAAW,CA8BjE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CAazF;AASD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,cAAc,GAAG,YAAY,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,GAAG,IAAI,CAmCrG;AAED,0GAA0G;AAC1G,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC;AAE/G;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAiBhE;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAU5C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAQ9C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYnD"}

package/dist/skills/skills.js

@@ -8,30 +8,46 @@
  * skill stays one readable page instead of a pile of corrections.
  *
  * The SKILL.md lives in one of two places. A skill the repo already has, in
- * `.claude/skills/<name>/`, is the team's: takeaways attach to it and fold
- * into it, and the diff goes through review like any change. A skill started
- * by `trail learn` lives next to its takeaways in `~/.trail` until someone
+ * `.claude/skills/<name>/`, is the repo's: takeaways attach to it, and fold
+ * into it only when it is Trail's (skill-file.ts), never into one someone
+ * wrote by hand; the diff goes through review like any change. A skill started
+ * by `learn()` lives next to its takeaways in `~/.trail` until someone
  * chooses to share it: `trail skills publish` moves it into the repo's
  * `.claude/skills/`, where Claude Code loads it for everyone who pulls.
+ * (No command calls `learn()` any more: the hidden `trail learn` is gone.)
  *
  * Takeaways are never deleted: a folded one keeps its file, with `folded_in`
  * saying which version took it, so why a rule exists stays findable.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { matter } from "../util/front-matter.js";
 import { shortDate, slug } from "../notes/notes.js";
-import { ensureRepoHome, repoPlace } from "../notes/home.js";
+import { ensureRepoHome, repoPlace, trailHome } from "../notes/home.js";
+import { versionOf } from "./front-version.js";
+import { nearestThere, rewriteSkill, skillMark, trailOwned, within } from "./skill-file.js";
 /** Trail's and graft's own skills, rewritten by every `init`: never a place for takeaways. */
-const OWN_SKILLS = new Set(["trail", "graft"]);
-/** Where a repo's skills are: the team's in the repo, and this machine's in ~/.trail. */
+export const OWN_SKILLS = new Set(["trail", "graft"]);
+/**
+ * Where a repo's skills are: the repo's in its `.claude/skills/`, and this
+ * machine's in ~/.trail. A link in either is followed only while it stays
+ * inside its root (`repoRoot`, the checkout; `homeRoot`, ~/.trail), so no
+ * skill file outside the repo or ~/.trail is ever read or written.
+ */
 export function skillDirs(dir) {
     const place = repoPlace(dir);
-    return { repo: join(place.checkout, ".claude", "skills"), home: join(place.dir, "skills") };
+    return { repo: join(place.checkout, ".claude", "skills"), home: join(place.dir, "skills"), repoRoot: place.checkout, homeRoot: trailHome() };
 }
-/** A skill name as a folder: `PDF coords` → `pdf-coords`. */
+/** The longest skill name the Agent Skills spec allows (validate.ts). */
+const NAME_MAX = 64;
+/** A skill name as a folder: `PDF coords` → `pdf-coords`. At most 64 characters, cut at a word. */
 export function skillName(raw) {
-    return slug(raw, 8);
+    const name = slug(raw, 8);
+    if (name.length <= NAME_MAX)
+        return name;
+    const cut = name.slice(0, NAME_MAX + 1);
+    const at = cut.lastIndexOf("-");
+    return at > 0 ? cut.slice(0, at) : name.slice(0, NAME_MAX);
 }
 function yamlScalar(s) {
     return /^[A-Za-z0-9][^:#\n"'{}[\],&*!|>%@`]*$/.test(s) && s.trim() === s ? s : JSON.stringify(s);
@@ -76,10 +92,12 @@ export function renderTakeaway(t) {
     fm.push("---");
     return `${fm.join("\n")}\n${t.text.trim()}\n`;
 }
-function readTakeaways(homeSkills, name) {
-    const tdir = join(homeSkills, name, "takeaways");
+function readTakeaways(dirs, name) {
+    const tdir = join(dirs.home, name, "takeaways");
     let files = [];
     try {
+        if (!within(tdir, dirs.homeRoot))
+            return [];
         files = readdirSync(tdir).filter((f) => f.endsWith(".md")).sort();
     }
     catch {
@@ -87,6 +105,8 @@ function readTakeaways(homeSkills, name) {
     }
     const out = [];
     for (const f of files) {
+        if (!within(join(tdir, f), dirs.homeRoot))
+            continue;
         try {
             const t = parseTakeaway(readFileSync(join(tdir, f), "utf8"), join(tdir, f), name);
             if (t)
@@ -98,25 +118,27 @@ function readTakeaways(homeSkills, name) {
     }
     return out;
 }
-/** The skill's SKILL.md: the repo's when it has one, else this machine's. */
+/** The skill's SKILL.md: the repo's when it has one, else this machine's. Never one a link leads to outside the repo or ~/.trail. */
 function skillFile(dirs, name) {
     const repo = join(dirs.repo, name, "SKILL.md");
-    if (existsSync(repo))
+    if (existsSync(repo) && within(repo, dirs.repoRoot))
         return { file: repo, where: "repo" };
     const home = join(dirs.home, name, "SKILL.md");
-    if (existsSync(home))
+    if (existsSync(home) && within(home, dirs.homeRoot))
         return { file: home, where: "home" };
     return null;
 }
 function readSkill(dirs, name) {
-    if (OWN_SKILLS.has(name))
+    if (!name || OWN_SKILLS.has(name))
         return null;
     const at = skillFile(dirs, name);
     if (!at)
         return null;
+    let text;
     let parsed;
     try {
-        parsed = matter(readFileSync(at.file, "utf8"));
+        text = readFileSync(at.file, "utf8");
+        parsed = matter(text);
     }
     catch {
         return null;
@@ -125,27 +147,56 @@ function readSkill(dirs, name) {
     return {
         name,
         description: typeof d.description === "string" ? d.description.trim() : "",
-        version: typeof d.version === "number" ? d.version : 1,
+        version: versionOf(d),
         body: parsed.content.trim(),
         where: at.where,
         file: at.file,
-        takeaways: readTakeaways(dirs.home, name),
+        trailOwned: trailOwned(text, d, at.where),
+        takeaways: readTakeaways(dirs, name),
     };
 }
-function subdirs(dir) {
+/**
+ * The folders in `dir`, by name, following links: a repo's skill can sit in
+ * `.agents/skills/<name>/` with `.claude/skills/<name>` linking to it. A link
+ * that loops, dangles, reaches a file or leads out of `root` is skipped, and
+ * two names for one folder count once, the first by name.
+ */
+function subdirs(dir, root) {
+    let entries;
     try {
-        return readdirSync(dir, { withFileTypes: true })
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name);
+        entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
     }
     catch {
         return [];
     }
+    const out = [];
+    const seen = new Set();
+    for (const e of entries) {
+        const path = join(dir, e.name);
+        let real;
+        try {
+            if (e.isSymbolicLink() && !statSync(path).isDirectory())
+                continue;
+            if (!e.isSymbolicLink() && !e.isDirectory())
+                continue;
+            if (!within(path, root))
+                continue;
+            real = realpathSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        out.push(e.name);
+    }
+    return out;
 }
 /** Every skill for the repo `dir` is in: the team's in the repo, then this machine's, by name. */
 export function listSkills(dir) {
     const dirs = skillDirs(dir);
-    const names = [...new Set([...subdirs(dirs.repo), ...subdirs(dirs.home)])].sort();
+    const names = [...new Set([...subdirs(dirs.repo, dirs.repoRoot), ...subdirs(dirs.home, dirs.homeRoot)])].sort();
     return names.map((n) => readSkill(dirs, n)).filter((s) => s !== null);
 }
 export function getSkill(dir, name) {
@@ -162,25 +213,15 @@ export function isConfirmed(t) {
 /* -------------------------------------------------------------------------- */
 /* writing                                                                    */
 /* -------------------------------------------------------------------------- */
-function renderNewSkill(name, description) {
-    const fm = ["---", `name: ${name}`, `description: ${yamlScalar(description)}`, "version: 1", "---"];
-    return `${fm.join("\n")}\n\n# ${name}\n\n${description}.\n`;
-}
 /**
- * SKILL.md at a new version with a new body. The frontmatter is edited as
- * text, only its `version:` line, so a team's own skill keeps every other key
- * (`allowed-tools`, `license`, …) exactly as they wrote it.
+ * A new SKILL.md as the Agent Skills spec has it: name and description on
+ * top; Trail's mark and the version under metadata. The description never
+ * holds `---`, which ends the front matter early for the reference validator.
  */
-function rewriteSkill(file, version, body) {
-    const lines = readFileSync(file, "utf8").split(/\r?\n/);
-    const close = lines[0] === "---" ? lines.indexOf("---", 1) : -1;
-    const fm = close === -1 ? [] : lines.slice(1, close);
-    const at = fm.findIndex((l) => l.startsWith("version:"));
-    if (at === -1)
-        fm.push(`version: ${version}`);
-    else
-        fm[at] = `version: ${version}`;
-    writeFileSync(file, `---\n${fm.join("\n")}\n---\n\n${body.trim()}\n`);
+function renderNewSkill(name, description) {
+    const said = description.replace(/-{3,}/g, "--");
+    const fm = ["---", `name: ${name}`, `description: ${JSON.stringify(said)}`, "metadata:", `  trail: ${JSON.stringify(skillMark(name))}`, '  version: "1"', "---"];
+    return `${fm.join("\n")}\n\n# ${name}\n\n${description}.\n`;
 }
 /**
  * Save one takeaway, on this machine. A skill the repo has gets it as is; a
@@ -192,7 +233,7 @@ export function learn(dir, input) {
     if (!name)
         throw new Error("a skill needs a name, like pdf-coords");
     if (OWN_SKILLS.has(name))
-        throw new Error(`${name} is the code map's own skill, rewritten by every init — pick a name for what you're teaching, like pdf-coords`);
+        throw new Error(`${name} is the code map's own skill, rewritten by every init: pick a name for what you're teaching, like pdf-coords`);
     ensureRepoHome(dir);
     const dirs = skillDirs(dir);
     let created = false;
@@ -265,6 +306,9 @@ export function fold(dir, name, opts = {}) {
     const base = { skill: s.name, where: s.where, file: s.file, from: s.version, stillWaiting: still };
     if (ready.length === 0)
         return { ...base, to: s.version, folded: [], sections: [] };
+    const leave = (left) => ({ ...base, stillWaiting: waiting(s).length, to: s.version, folded: [], sections: [], left });
+    if (!s.trailOwned)
+        return leave("hand-written");
     const lines = s.body.split(/\r?\n/);
     const sections = [];
     for (const t of ready) {
@@ -288,7 +332,8 @@ export function fold(dir, name, opts = {}) {
             sections.push(heading);
     }
     const to = s.version + 1;
-    rewriteSkill(s.file, to, lines.join("\n"));
+    if (!rewriteSkill(s.file, to, lines.join("\n"), skillMark(s.name)))
+        return leave("unreadable");
     for (const t of ready) {
         t.foldedIn = to;
         writeFileSync(t.path, renderTakeaway(t));
@@ -306,8 +351,12 @@ export function publish(dir, name) {
         return { ok: false, reason: "unknown" };
     if (s.where === "repo")
         return { ok: false, reason: "in-repo" };
-    const target = join(skillDirs(dir).repo, s.name, "SKILL.md");
-    mkdirSync(join(target, ".."), { recursive: true });
+    const dirs = skillDirs(dir);
+    const target = join(dirs.repo, s.name, "SKILL.md");
+    // The nearest folder already there must be the repo's own, or the new ones would be made through a link.
+    if (!within(nearestThere(dirname(target)), dirs.repoRoot))
+        return { ok: false, reason: "link" };
+    mkdirSync(dirname(target), { recursive: true });
     try {
         renameSync(s.file, target);
     }
@@ -340,7 +389,7 @@ export function skillStatus(s) {
  */
 export function skillForAgent(s) {
     const open = waiting(s).sort((a, b) => b.date.localeCompare(a.date) || b.path.localeCompare(a.path));
-    const out = [`# ${s.name} (v${s.version}, ${s.where === "repo" ? "the team's" : "kept on this machine"})`, "", s.body.trim()];
+    const out = [`# ${s.name} (v${s.version}, ${s.where === "repo" ? "in this repo" : "kept on this machine"})`, "", s.body.trim()];
     if (open.length) {
         out.push("", `## Corrections since v${s.version} (newest first; these win where they disagree with the above)`);
         for (const t of open)
@@ -351,20 +400,24 @@ export function skillForAgent(s) {
 /**
  * The line a session starts with about skills an agent can't see by itself:
  * ones kept only on this machine (Claude Code loads `.claude/skills/`, not
- * ~/.trail), and the team's ones with corrections waiting. Empty when there
- * are none, so the directive is unchanged everywhere else.
+ * ~/.trail), and the team's ones with corrections waiting. It names the files
+ * to read: `trail skills show` is the learned skills' command now and can't
+ * print these. Empty when there are none.
  */
-export function skillsDirective(dir, show) {
+export function skillsDirective(dir) {
     const parts = [];
+    const dirs = skillDirs(dir);
     for (const s of listSkills(dir)) {
         const open = waiting(s).length;
+        const fixes = `${open} correction${open === 1 ? "" : "s"}`;
+        const tdir = join(dirs.home, s.name, "takeaways");
         if (s.where === "home")
-            parts.push(`${s.name} (on this machine${open ? `, ${open} correction${open === 1 ? "" : "s"}` : ""})`);
+            parts.push(`${s.name} (on this machine: ${s.file}${open ? `, then ${fixes} in ${tdir}` : ""})`);
         else if (open)
-            parts.push(`${s.name} (${open} correction${open === 1 ? "" : "s"} newer than its SKILL.md)`);
+            parts.push(`${s.name} (${fixes} newer than its SKILL.md, in ${tdir})`);
     }
     if (parts.length === 0)
         return "";
-    return `Skills with more than Claude Code loads by itself: ${parts.join(", ")}. Before working in one's area, run \`${show} <name>\`: it prints the skill with every correction, newest first.\n`;
+    return `Skills with more than Claude Code loads by itself: ${parts.join(", ")}. Read them before working in one's area, the corrections newest first; they win where they disagree.\n`;
 }
 //# sourceMappingURL=skills.js.map