@malloy-publisher/skills 0.1.33 → 0.1.35

package/README.md

@@ -5,6 +5,31 @@ SPDX-License-Identifier: MIT
 
 # @malloy-publisher/skills
 
+## Start here
+
+1. **Learn.** Read the getting-started skill. Nothing to install, no server:
+
+   <https://unpkg.com/@malloy-publisher/skills@latest/skills/malloy-getting-started/SKILL.md>
+
+   Every skill reads the same way. Put its name in place of `malloy-getting-started`.
+
+2. **Install.** If your agent has a shell, copy every skill to where it loads them:
+
+   ```bash
+   npx -y @malloy-publisher/skills@latest install           # into this project
+   npx -y @malloy-publisher/skills@latest install --global  # into your home directory
+   npx -y @malloy-publisher/skills@latest list              # every skill, with a description
+   ```
+
+   Keep the `@latest`. Without it, npx may reuse an old cached copy and install old skills.
+
+   `install` picks the agent from what it finds. A `CLAUDE.md` means `.claude/skills/`. An
+   `AGENTS.md` or `.cursor/` means `.agents/skills/`. With `--global` it looks for `~/.claude/`,
+   `~/.agents/`, or `~/.cursor/` instead. If it finds none, it stops and asks you to name one:
+   `install claude` or `install agents`.
+
+## What this package is
+
 The agent skills that ship with [Malloy Publisher](https://github.com/malloydata/publisher), as
 files you can install. They are task-specific guides for writing Malloy, building and reviewing
 models, exploring data, and authoring HTML data apps.
@@ -14,7 +39,7 @@ files. This package exists for the cases MCP does not cover: a host that reads s
 (Claude Code and the Publisher plugin), a scaffolder that installs them into a new project, or any
 tool that wants the files themselves rather than prompt text.
 
-## Install
+## Use the files from code
 
 ```bash
 npm install @malloy-publisher/skills

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Where each host looks for skills, relative to a project or to the home dir. */
+declare const TARGETS: Record<string, string>;
+/**
+ * What says a host is set up, per scope. The two differ because the hosts keep
+ * their user-level config in a directory rather than a top-level file: Claude
+ * Code reads `~/.claude/CLAUDE.md`, never `~/CLAUDE.md`, so the project markers
+ * would miss almost everyone who has Claude set up.
+ */
+declare const MARKERS: Record<"project" | "global", Record<string, string[]>>;
+/**
+ * Where a skill can be read with nothing installed. `@latest` rather than this
+ * package's own version, so a link copied from an old cached copy of this CLI
+ * still serves the current skill.
+ */
+declare function skillUrl(name: string): string;
+/**
+ * Which hosts this directory is set up for.
+ *
+ * Detection only ever chooses between hosts the user already has; it never
+ * decides *whether* to write. When it finds nothing, install asks rather than
+ * picking one, because a skills directory in the wrong place is invisible: the
+ * agent simply never loads them and nothing says why.
+ */
+declare function detectTargets(root: string, scope: keyof typeof MARKERS): string[];
+declare function main(argv: string[]): void;
+export { TARGETS, detectTargets, main, skillUrl };

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Copyright (c) Credible Data Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `malloy-skills` -- list the agent skills, and install them, with nothing
+ * running.
+ *
+ * This exists so an agent meeting Publisher for the first time can get the
+ * skills before it installs or starts anything. Every other route to them is
+ * gated: the MCP prompt channel needs the server up, and the server is a large
+ * install that clones its example packages over the network.
+ *
+ * Reading one skill needs no command at all: the package ships the files, so
+ * unpkg serves each SKILL.md at a stable URL (`skillUrl`). That works in a chat
+ * with no shell, which `npx` cannot. This CLI covers what a URL cannot: listing
+ * what ships, and copying the whole tree, `reference/` files included, onto
+ * disk through the hardened copy in install.ts.
+ *
+ * Which is why this lives in @malloy-publisher/skills and not in the server or a
+ * new package: this one already ships the skill files, has no runtime
+ * dependencies and no native code, so `npx` is fast and cannot fail on a build
+ * step or a platform binary. Adding a CLI framework here would cost that, for
+ * two commands, so the argument parsing below is by hand.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { listSkills } from "./index.js";
+import { installSkills } from "./install.js";
+import { skillsDir } from "./payload.js";
+/** Where each host looks for skills, relative to a project or to the home dir. */
+const TARGETS = {
+    claude: path.join(".claude", "skills"),
+    agents: path.join(".agents", "skills"),
+};
+/**
+ * What says a host is set up, per scope. The two differ because the hosts keep
+ * their user-level config in a directory rather than a top-level file: Claude
+ * Code reads `~/.claude/CLAUDE.md`, never `~/CLAUDE.md`, so the project markers
+ * would miss almost everyone who has Claude set up.
+ */
+const MARKERS = {
+    project: { claude: ["CLAUDE.md"], agents: ["AGENTS.md", ".cursor"] },
+    global: { claude: [".claude"], agents: [".agents", ".cursor"] },
+};
+/**
+ * Where a skill can be read with nothing installed. `@latest` rather than this
+ * package's own version, so a link copied from an old cached copy of this CLI
+ * still serves the current skill.
+ */
+function skillUrl(name) {
+    return `https://unpkg.com/@malloy-publisher/skills@latest/skills/${name}/SKILL.md`;
+}
+const USAGE = `malloy-skills - list and install the Malloy Publisher agent skills
+
+Usage:
+  npx -y @malloy-publisher/skills@latest [list]          List every skill.
+  npx -y @malloy-publisher/skills@latest install [host]  Copy the skills onto disk.
+
+Keep the @latest: without it npx may reuse an old cached copy.
+
+Install targets:
+  claude    .claude/skills/   (detected from a CLAUDE.md)
+  agents    .agents/skills/   (detected from an AGENTS.md or .cursor/)
+  --global  install into your home directory instead of this project
+            (detected from ~/.claude/, ~/.agents/, or ~/.cursor/)
+
+Read one skill without installing anything:
+  ${skillUrl("<name>")}
+
+Nothing here needs a running server or an account.`;
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+/** Print the name and description of every shipped skill. */
+function list() {
+    const skills = listSkills();
+    if (skills.length === 0) {
+        fail(`No skills found in ${skillsDir}. This install of ` +
+            `@malloy-publisher/skills is incomplete; reinstall and try again.`);
+    }
+    for (const skill of skills) {
+        console.log(skill.name);
+        console.log(`  ${skill.description}`);
+    }
+    console.log("");
+    console.log(`Read one: ${skillUrl("<name>")}`);
+    console.log("Install them all: npx -y @malloy-publisher/skills@latest install");
+}
+/**
+ * Which hosts this directory is set up for.
+ *
+ * Detection only ever chooses between hosts the user already has; it never
+ * decides *whether* to write. When it finds nothing, install asks rather than
+ * picking one, because a skills directory in the wrong place is invisible: the
+ * agent simply never loads them and nothing says why.
+ */
+function detectTargets(root, scope) {
+    return Object.entries(MARKERS[scope])
+        .filter(([, markers]) => markers.some((marker) => fs.existsSync(path.join(root, marker))))
+        .map(([host]) => host);
+}
+/** Say what an install did, including what it cost. */
+function report(target, dir, result) {
+    if (result.refused) {
+        fail(`Did not install into ${dir}: ${result.refused}.`);
+    }
+    console.log(`Installed ${result.installed} skills into ${dir}`);
+    if (result.skipped.length > 0) {
+        console.log(`  left alone (symlinked): ${result.skipped.join(", ")}`);
+    }
+    if (result.refreshed.length > 0) {
+        console.log(`  replaced: ${result.refreshed.join(", ")}`);
+    }
+    // Not a footnote: these are files the user put there that no copy puts back.
+    for (const gone of result.removed) {
+        console.log(`  removed (not in the shipped skill): ${target}/${gone}`);
+    }
+}
+function install(hosts, global) {
+    const root = global ? os.homedir() : process.cwd();
+    const scope = global ? "global" : "project";
+    let chosen = hosts;
+    if (chosen.length === 0) {
+        chosen = detectTargets(root, scope);
+        if (chosen.length === 0) {
+            const looked = Object.values(MARKERS[scope]).flat().join(", ");
+            const flag = global ? " --global" : "";
+            fail(`Could not tell which agent to install for: no ${looked} in ${root}.\n` +
+                `Name one: npx -y @malloy-publisher/skills@latest install claude${flag}   (or: install agents${flag})`);
+        }
+    }
+    for (const host of chosen) {
+        const dir = path.join(root, TARGETS[host]);
+        report(host, dir, installSkills(dir, root));
+    }
+}
+function main(argv) {
+    const global = argv.includes("--global");
+    const args = argv.filter((arg) => arg !== "--global");
+    const [command = "list", ...rest] = args;
+    if (command === "--help" || command === "-h" || command === "help") {
+        console.log(USAGE);
+        return;
+    }
+    if (command === "install") {
+        for (const host of rest) {
+            if (!(host in TARGETS)) {
+                fail(`Unknown install target '${host}'. ` +
+                    `Expected one of: ${Object.keys(TARGETS).join(", ")}.`);
+            }
+        }
+        return install(rest, global);
+    }
+    // Anything else is refused rather than skipped: a silently ignored argument
+    // is how a typo turns into a command that looks like it worked.
+    if (command !== "list") {
+        // A skill name is the likeliest mistake, from an agent that expects this
+        // to print one, so it gets the URL that does.
+        const skill = listSkills().find((s) => s.name === command);
+        fail(skill
+            ? `There is no command to print a skill. Read it at ${skillUrl(command)}`
+            : `Unknown command or option '${command}'.\n\n${USAGE}`);
+    }
+    if (rest.length > 0) {
+        fail(`'list' takes no arguments, got: ${rest.join(" ")}.`);
+    }
+    if (global)
+        fail("--global only applies to install.");
+    return list();
+}
+// Only when run as the command, so importing this module for a test does not
+// parse the test runner's own argv and exit the process.
+if (process.argv[1] &&
+    realpath(process.argv[1]) === realpath(fileURLToPath(import.meta.url))) {
+    main(process.argv.slice(2));
+}
+function realpath(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return target;
+    }
+}
+export { TARGETS, detectTargets, main, skillUrl };

package/dist/index.d.ts

@@ -5,14 +5,6 @@ export interface Skill {
     /** Absolute path to the skill's directory: SKILL.md and any reference/. */
     dir: string;
 }
-/**
- * Absolute path to the directory holding the skill directories.
- *
- * Resolved from this module's own URL, which works both from dist/ once
- * installed and from src/ in the repo, since both sit one level under the
- * package root.
- */
-export declare const skillsDir: string;
 /**
  * Read every skill's frontmatter from the shipped files.
  *
@@ -20,3 +12,10 @@ export declare const skillsDir: string;
  * second copy of this metadata to regenerate or to drift.
  */
 export declare function listSkills(): Skill[];
+/**
+ * The installer is re-exported here so `@malloy-publisher/skills` has one entry
+ * point: consumers get `skillsDir` to read from and `installSkills` to write
+ * with, without reaching into a subpath.
+ */
+export { skillsDir } from "./payload.js";
+export { countSkills, installSkills, isWithinDirectory, type SkillInstall, } from "./install.js";

package/dist/index.js

@@ -6,15 +6,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-/**
- * Absolute path to the directory holding the skill directories.
- *
- * Resolved from this module's own URL, which works both from dist/ once
- * installed and from src/ in the repo, since both sit one level under the
- * package root.
- */
-export const skillsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
+import { skillsDir } from "./payload.js";
 function unquote(value) {
     return value.trim().replace(/^["']|["']$/g, "");
 }
@@ -47,3 +39,10 @@ export function listSkills() {
     // platforms and must not depend on the runtime's locale.
     return skills.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 }
+/**
+ * The installer is re-exported here so `@malloy-publisher/skills` has one entry
+ * point: consumers get `skillsDir` to read from and `installSkills` to write
+ * with, without reaching into a subpath.
+ */
+export { skillsDir } from "./payload.js";
+export { countSkills, installSkills, isWithinDirectory, } from "./install.js";

package/dist/install.d.ts

@@ -0,0 +1,68 @@
+export interface SkillInstall {
+    /** How many skills were copied in. */
+    installed: number;
+    /** Skill names left alone because the target is a symlink. */
+    skipped: string[];
+    /** Skill names whose existing files the bundled copies replaced. */
+    refreshed: string[];
+    /**
+     * Paths that were inside a skill directory, are not in the bundled copy of
+     * that skill, and so were removed and not written back. Relative to the
+     * skills directory (`malloy-review/NOTES.md`), directories with a trailing
+     * separator.
+     *
+     * Reported separately from `refreshed` because they are a different loss.
+     * "Refreshed" is read as "my edits to the skill files were reverted", which
+     * is recoverable knowledge; a file the user put in the directory themselves
+     * is simply gone, and nothing named it.
+     */
+    removed: string[];
+    /** Why nothing at all was installed, when nothing was. */
+    refused?: string;
+}
+/**
+ * Copy every agent skill into targetDir as real files. The generated project is
+ * standalone and the user may move or commit it, so this is a recursive copy, not
+ * a symlink: a symlink into node_modules would dangle the moment the project is
+ * moved or its dependencies pruned. skillsDir already excludes non-shipping skills
+ * and the internal README, so a straight copy is clean.
+ *
+ * A skill directory in the target that is itself a symlink is left alone. That is
+ * how this repo's own contributors wire skills into their agent (skills/README.md
+ * tells them to), and copying through the link would overwrite the source of truth
+ * rather than the workspace.
+ *
+ * targetDir has to resolve inside workspaceRoot. A `.claude` that is itself a
+ * symlink elsewhere is not caught by the per-skill check above, and used to write
+ * every skill outside the workspace while reporting them installed.
+ *
+ * An existing skill directory is removed before the copy rather than copied over.
+ * fs.cpSync follows a symlink it finds at the destination, so checking only the
+ * skill directory itself left every path inside it writable through a link: a
+ * `.claude/skills/malloy-review/SKILL.md` linked elsewhere had the file it points
+ * at replaced, and a linked `reference/` (four shipped skills have one) had files
+ * written into whatever directory it named, all under a green
+ * "Installed N Malloy skills". `.claude/skills/` is shared agent territory where
+ * links are an expected state, so the check has to cover the whole subtree, and
+ * removing first is the only form of that which cannot be one level short.
+ *
+ * The copy is unconditional, so an edited skill is replaced on every run. That is
+ * deliberate (an existing workspace picks up skill updates), but it is reported:
+ * `refreshed` names what was overwritten. Because the directory is removed and
+ * not merged, that goes further than reverting an edit: a file the user added
+ * inside a skill directory is gone, and no bundled copy puts it back. Those paths
+ * are collected into `removed` so the caller can name them, rather than leaving
+ * them under a word ("refreshed") that reads as "your edits were reverted". Note
+ * the copy never prunes whole skills, so one dropped from a later release stays in
+ * the workspace until deleted by hand.
+ */
+export declare function installSkills(targetDir: string, workspaceRoot: string): SkillInstall;
+/** Count directories under dir that contain a SKILL.md, i.e. real skills. */
+export declare function countSkills(dir: string): number;
+/**
+ * Whether target, which need not exist yet, names a path inside root once every
+ * symlink on the way has been followed. A path utility rather than a skills
+ * concept, but it lives beside the only call that needs it, and exporting it
+ * keeps the scaffolder's own path checks on the same implementation.
+ */
+export declare function isWithinDirectory(target: string, root: string): boolean;

package/dist/install.js

@@ -0,0 +1,182 @@
+// Copyright (c) Credible Data Inc.
+// SPDX-License-Identifier: MIT
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { skillsDir } from "./payload.js";
+/**
+ * Copy every agent skill into targetDir as real files. The generated project is
+ * standalone and the user may move or commit it, so this is a recursive copy, not
+ * a symlink: a symlink into node_modules would dangle the moment the project is
+ * moved or its dependencies pruned. skillsDir already excludes non-shipping skills
+ * and the internal README, so a straight copy is clean.
+ *
+ * A skill directory in the target that is itself a symlink is left alone. That is
+ * how this repo's own contributors wire skills into their agent (skills/README.md
+ * tells them to), and copying through the link would overwrite the source of truth
+ * rather than the workspace.
+ *
+ * targetDir has to resolve inside workspaceRoot. A `.claude` that is itself a
+ * symlink elsewhere is not caught by the per-skill check above, and used to write
+ * every skill outside the workspace while reporting them installed.
+ *
+ * An existing skill directory is removed before the copy rather than copied over.
+ * fs.cpSync follows a symlink it finds at the destination, so checking only the
+ * skill directory itself left every path inside it writable through a link: a
+ * `.claude/skills/malloy-review/SKILL.md` linked elsewhere had the file it points
+ * at replaced, and a linked `reference/` (four shipped skills have one) had files
+ * written into whatever directory it named, all under a green
+ * "Installed N Malloy skills". `.claude/skills/` is shared agent territory where
+ * links are an expected state, so the check has to cover the whole subtree, and
+ * removing first is the only form of that which cannot be one level short.
+ *
+ * The copy is unconditional, so an edited skill is replaced on every run. That is
+ * deliberate (an existing workspace picks up skill updates), but it is reported:
+ * `refreshed` names what was overwritten. Because the directory is removed and
+ * not merged, that goes further than reverting an edit: a file the user added
+ * inside a skill directory is gone, and no bundled copy puts it back. Those paths
+ * are collected into `removed` so the caller can name them, rather than leaving
+ * them under a word ("refreshed") that reads as "your edits were reverted". Note
+ * the copy never prunes whole skills, so one dropped from a later release stays in
+ * the workspace until deleted by hand.
+ */
+export function installSkills(targetDir, workspaceRoot) {
+    const empty = { installed: 0, skipped: [], refreshed: [], removed: [] };
+    if (isSymlink(targetDir)) {
+        return {
+            ...empty,
+            refused: "it is a symlink, so writing into it would edit whatever it points at",
+        };
+    }
+    if (!isWithinDirectory(targetDir, workspaceRoot)) {
+        return {
+            ...empty,
+            refused: "it resolves outside the workspace, so writing into it would put " +
+                "files somewhere else on this machine",
+        };
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    const skipped = [];
+    const refreshed = [];
+    const removed = [];
+    let installed = 0;
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const source = path.join(skillsDir, entry.name);
+        if (!fs.existsSync(path.join(source, "SKILL.md"))) {
+            continue;
+        }
+        const target = path.join(targetDir, entry.name);
+        if (isSymlink(target)) {
+            skipped.push(entry.name);
+            continue;
+        }
+        if (fs.existsSync(target)) {
+            refreshed.push(entry.name);
+            // Read before the removal, because after it there is nothing to read:
+            // these are the paths the copy below does not put back.
+            for (const relative of pathsNotIn(target, source)) {
+                removed.push(path.join(entry.name, relative));
+            }
+        }
+        // target is not a symlink (checked above) and sits directly under a
+        // targetDir that resolves inside the workspace, so this removes files in
+        // the workspace and, for any symlink further down, the link itself rather
+        // than what it points at.
+        fs.rmSync(target, { recursive: true, force: true });
+        fs.cpSync(source, target, { recursive: true });
+        installed += 1;
+    }
+    return { installed, skipped, refreshed, removed };
+}
+/**
+ * Every path under target that source does not also hold, relative to target.
+ *
+ * A directory that source does not hold is named once and not walked: what the
+ * user has to look for is the directory, and walking it would turn one dropped
+ * folder into a hundred lines. Nothing here follows a link out of target either,
+ * because a symlink is compared by its own path, never by what it points at.
+ */
+function pathsNotIn(target, source, prefix = "") {
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(target, prefix), {
+            withFileTypes: true,
+        });
+    }
+    catch {
+        // Unreadable: nothing can be said about what is in it.
+        return [];
+    }
+    const missing = [];
+    for (const entry of entries) {
+        const relative = path.join(prefix, entry.name);
+        if (!fs.existsSync(path.join(source, relative))) {
+            missing.push(entry.isDirectory() ? relative + path.sep : relative);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            missing.push(...pathsNotIn(target, source, relative));
+        }
+    }
+    return missing;
+}
+/** Count directories under dir that contain a SKILL.md, i.e. real skills. */
+export function countSkills(dir) {
+    if (!fs.existsSync(dir)) {
+        return 0;
+    }
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        fs.existsSync(path.join(dir, entry.name, "SKILL.md"))).length;
+}
+/**
+ * Whether target, which need not exist yet, names a path inside root once every
+ * symlink on the way has been followed. A path utility rather than a skills
+ * concept, but it lives beside the only call that needs it, and exporting it
+ * keeps the scaffolder's own path checks on the same implementation.
+ */
+export function isWithinDirectory(target, root) {
+    const realRoot = realPathOf(root);
+    const realTarget = realPathOf(target);
+    return realTarget === realRoot || realTarget.startsWith(realRoot + path.sep);
+}
+/**
+ * The path target really names. fs.realpathSync cannot be used: it throws on a
+ * path that does not exist yet (every file we are about to create) and on a
+ * dangling symlink, which is precisely the case that matters, because
+ * fs.writeFileSync follows a dangling link and creates the file wherever it
+ * points. So resolve the parent first, then follow one link at a time.
+ */
+function realPathOf(target, hops = 0) {
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    if (parent === resolved) {
+        return resolved;
+    }
+    const here = path.join(realPathOf(parent, hops), path.basename(resolved));
+    if (hops >= 40) {
+        // A symlink cycle. Stop following and judge the path as it stands.
+        return here;
+    }
+    try {
+        if (!fs.lstatSync(here).isSymbolicLink()) {
+            return here;
+        }
+        return realPathOf(path.resolve(path.dirname(here), fs.readlinkSync(here)), hops + 1);
+    }
+    catch {
+        // Does not exist yet, or is unreadable: it is the path it looks like.
+        return here;
+    }
+}
+function isSymlink(target) {
+    try {
+        return fs.lstatSync(target).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/payload.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Absolute path to the directory holding the skill directories.
+ *
+ * Resolved from this module's own URL, which works both from dist/ once
+ * installed and from src/ in the repo, since both sit one level under the
+ * package root.
+ */
+export declare const skillsDir: string;

package/dist/payload.js

@@ -0,0 +1,19 @@
+// Copyright (c) Credible Data Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Where the shipped skill files are.
+ *
+ * Its own module, rather than a constant in index.ts, because both the reader
+ * (`listSkills`) and the writer (`installSkills`) need it and index.ts re-exports
+ * the writer: importing it from there would make the two modules a cycle.
+ */
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Absolute path to the directory holding the skill directories.
+ *
+ * Resolved from this module's own URL, which works both from dist/ once
+ * installed and from src/ in the repo, since both sit one level under the
+ * package root.
+ */
+export const skillsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");

package/package.json

@@ -1,11 +1,14 @@
 {
    "name": "@malloy-publisher/skills",
    "description": "Agent skills for Malloy and the Malloy Publisher",
-   "version": "0.1.33",
+   "version": "0.1.35",
    "license": "MIT",
    "type": "module",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
+   "bin": {
+      "malloy-skills": "dist/cli.js"
+   },
    "exports": {
       ".": {
          "types": "./dist/index.d.ts",

package/skills/eval-answer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-answer
 description: 'Score one analytical answer against a verified golden, and score which of the entities the golden depends on retrieval delivered to the answerer. Run the contamination checklist, re-execute the submitted query yourself, then spawn a judge subagent per skill:eval-judge. Append attempt, tool_call, score, and retrieval_score events to the file ledger (reference/ledger-schema.md). Never explain the failure (eval-diagnose) or edit the model (eval-improve). Use when asked whether an answer was correct, to score a run, or to baseline a model.'
-version: 0.1.33
+version: 0.1.35
 ---
 
 # Evaluate One Answer

package/skills/eval-answer/reference/ledger-schema.md

@@ -140,9 +140,9 @@ on that axis.
 | `evalConfig` | The set's `eval.toml` (or `eval.json`) the run read, as `{path, values}`; `path` is null when the set has none. |
 | `predictionsReExecuted` | Whether re-execution was POSSIBLE: the server was serving the bytes this run is pinned to. It is one bool for the whole run and says nothing about any given query, so it reads stronger than it is; `reExecution` below is what actually happened. |
 | `reExecution` | `{attempted, ok, failed, noQuery, notReExecuted, notJudged, missing}` over the run's predictions. `failed` means the query ran and the server returned an error, which is a different thing from an answer with no query at all. `notJudged` is a case the judge was never handed: a golden refused before judging (`provisional`, `invalid`, `ambiguous`, `verified_wrong`, missing), an attempt that submitted nothing, or every case under `--no-judge`. Those used to land in `missing` and read as corrupt artifacts on a freshly imported set. `ok`, `failed`, `noQuery`, `notReExecuted`, `notJudged` and `missing` partition the cases, so they sum to the case count; `attempted` is `ok + failed` and sits outside that sum. |
-| `retrievalMode` | Which retriever answered: `semantic`, `lexical`, `mixed` (it changed mid-run, so nothing can be averaged across it) or `unreported` (nothing ranked, which on a configured server means no embedding provider). Only a RANKING call names a retriever, so a call that enumerates a type or looks a name up is `unreported` on a fully semantic server and must not make the run read as `mixed`. Local retrieval degrades to lexical SILENTLY without an embedding key, and a pair compared across that reads as a model change, so `flip_table.py` refuses the pair unless both sides match. |
-| `retrievalCalls` | `{semantic, lexical, unreported}` call counts behind `retrievalMode`. `unreported` counts the calls that did not rank, which is a different thing from calls that fell back. |
-| `retrievalGate` | What the pre-arm retrieval gate found, or why it did not run. A run is held until `get_context` answers semantic twice in a row, because the first calls after a restart are lexical by design and an arm started immediately measures two retrievers. `not run (no answering phase)` under `--rebuild`/`--rejudge`, and `skipped by --no-retrieval-gate` when the operator opted out -- which is a different fact from a gate that passed, and the field is what tells them apart. |
+| `retrievalMode` | Which retriever answered: `semantic`, `lexical`, `mixed` (it changed mid-run, so nothing can be averaged across it), `unavailable` (at least one search was answered `indexing` or `error`, so it returned nothing to score and reads as a miss) or `unreported` (nothing ranked, which on a configured server means no embedding provider). Only a RANKING call names a retriever, so a call that enumerates a type or looks a name up is `unreported` on a fully semantic server and must not make the run read as `mixed`. Local retrieval degrades to lexical SILENTLY without an embedding key, and a pair compared across that reads as a model change, so `flip_table.py` refuses the pair unless both sides match. |
+| `retrievalCalls` | `{semantic, lexical, indexing, error, unreported}` call counts behind `retrievalMode`. `unreported` counts the calls that did not rank, which is a different thing from calls that fell back. |
+| `retrievalGate` | What the pre-arm retrieval gate found, or why it did not run. A run is held until `get_context` answers semantic twice in a row, because the first calls after a restart return `retrieval: "indexing"` with no sources and an arm started immediately measures empty results as well as real ones. A `retrieval: "error"` result stops the gate with its `retrieval_reason` instead of waiting. `not run (no answering phase)` under `--rebuild`/`--rejudge`, and `skipped by --no-retrieval-gate` when the operator opted out -- which is a different fact from a gate that passed, and the field is what tells them apart. |
 | `coverageReport` | The `check_coverage.py --out` report this run read, when `--coverage` named one: its path, the model version it was stamped with, its `agentModel`, and `decided` of `cases`. Coverage is a read of the MODEL, so it is measured separately and costs a judge call per case; the run does not run it, it consumes it. Its per-case verdict then beats the authored `coverage` label in retrieval attribution, and each `score_retrieval` row records `coverage_source` (`measured`, `authored`, `none`) so nobody has to guess which one charged the failure. Absent when no report was given, which is a different fact from a report that found everything covered. |
 | `label` | `<set>-<phase>-<nn>`, assigned by `run_baseline.py` from the set name, the run's phase and the next free number beside it (`ecommerce-baseline-01`, `ecommerce-baseline-02`, `ecommerce-blind_gate-01`). The A/A pair is two runs of the same phase; the post-edit arms are two runs of `blind_gate`. Hand-typed names do not survive one afternoon of runs -- `base`, `rejudged2`, `r3`, `post1` sort wrongly, group not at all, and cannot be matched to an arm. `--label` overrides for a run that genuinely needs a human name. |
 | `effort` | |