toolroll 0.5.0

package/dist/skills-ui.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const hidden = (data) => Object.entries(data)
+    .map(([k, v]) => `<input type="hidden" name="${e(k)}" value="${e(v)}">`)
+    .join("");
+export const SKILLS_CSS = `.skills{max-width:780px;min-width:0;overflow-wrap:anywhere}.skills h2{font-size:1.1rem}.skills .card{padding:18px;margin:14px 0;min-width:0}.skills form,.skills label{display:grid;gap:10px}.skills input,.skills textarea,.skills select{box-sizing:border-box;width:100%;max-width:100%;min-width:0}.skills textarea{resize:vertical;min-height:130px}.skills button{justify-self:start;white-space:nowrap;min-height:44px}.skills summary{cursor:pointer;min-height:44px;display:flex;align-items:center;gap:10px;flex-wrap:wrap}.skills pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:360px;overflow:auto;font-size:.9rem}.skills .skill-heading{display:flex;align-items:baseline;justify-content:space-between;gap:12px}.skills .skill-heading h2{margin:0}.skills .skill-state{font-size:.85rem;flex-shrink:0}.skills .skill-source{font-size:.85rem}.skills .skill-controls{display:flex;gap:12px;flex-wrap:wrap}.skills .skill-controls form{margin:0}.skills details details{margin-top:10px}.skills [hidden]{display:none!important}.skills .skill-files{max-height:200px;overflow:auto}.skills .problem{padding:12px}@media(max-width:600px){.skills input,.skills textarea,.skills select{font-size:16px}.skills .card{padding:14px}.skills .skill-heading{align-items:flex-start}}`;
+function source(skill) {
+    return `<p class="skill-source">${e(skill.source)} · ${skill.sha.slice(0, 10)}</p><p>${skill.files.length} files · ${Math.ceil(skill.files.reduce((n, f) => n + Buffer.from(f.base64, "base64").length, 0) / 1024)} KB</p><pre>${e(Buffer.from(skill.files.find((f) => f.path === "SKILL.md").base64, "base64").toString("utf8"))}</pre><details><summary>Package files</summary><ul class="skill-files">${skill.files.map((f) => `<li>${e(f.path)}</li>`).join("")}</ul></details>`;
+}
+export function skillsHtml(view, csrf, canManage, options = {}) {
+    const manage = canManage && !!csrf, base = {
+        csrf,
+        repo: view.repo,
+        identity: view.identity,
+        revision: view.revision,
+    };
+    const form = (action, contents, extra = {}) => `<form method="post" action="/settings/skills/change">${hidden({ ...base, action, ...extra })}${contents}</form>`;
+    const active = Object.values(view.selection).filter((c) => c.enabled).length;
+    const renderSkill = (skill) => {
+        const enabled = view.selection[skill.name]?.sha === skill.sha &&
+            view.selection[skill.name]?.enabled === true;
+        const replaced = view.selection[skill.name]?.enabled &&
+            view.selection[skill.name]?.sha !== skill.sha;
+        return `<article class="card" id="skill-${skill.sha}"><div class="skill-heading"><h2>${e(skill.name)}</h2><span class="skill-state">${enabled ? "Enabled" : "In library"}</span></div><p>${e(skill.description)}</p>${skill.requirements ? `<p><strong>Requires:</strong> ${e(skill.requirements)} <span class="meta">Availability is checked when the agent tests or uses it.</span></p>` : ""}${skill.warnings.map((w) => `<p class="meta">${e(w)}</p>`).join("")}<details${options.focus === skill.sha ? " open" : ""}><summary>Review skill</summary>${source(skill)}${manage ? form(enabled ? "disable" : "enable", `${replaced ? "<p>Replaces the enabled version of this skill for new tasks.</p>" : ""}<button>${enabled ? "Disable skill" : "Enable skill"}</button>`, { sha: skill.sha }) : ""}</details>${manage ? `<details${options.draft?.["sha"] === skill.sha ? " open" : ""}><summary>Test skill</summary>${form("test", `<p>${e(options.agent ?? "Uses this project’s configured report agent")}. Runs a read-only sample through the normal task and approval flow.</p><label>Sample request<textarea name="sample" required maxlength="800" placeholder="Review this project’s home page and suggest three clearer button labels.">${e(options.draft?.["sha"] === skill.sha ? (options.draft?.["sample"] ?? "") : "")}</textarea></label><p class="meta">The report shows what worked and what needs tools or permission. Enabled status alone does not prove use.</p><button>Create test</button>`, { sha: skill.sha, nonce: randomUUID() })}</details>` : ""}</article>`;
+    };
+    const names = [...new Set(view.library.map((s) => s.name))];
+    const cards = names
+        .map((name) => {
+        const versions = view.library.filter((s) => s.name === name), primary = versions.find((s) => s.sha === options.focus) ??
+            versions.find((s) => s.sha === view.selection[name]?.sha) ??
+            versions.at(-1);
+        const older = versions.filter((s) => s !== primary);
+        return `<div data-skill-group data-skill-query="${e(name + " " + primary.description)}">${renderSkill(primary)}${older.length ? `<details><summary>Other versions (${older.length})</summary>${older.map(renderSkill).join("")}</details>` : ""}</div>`;
+    })
+        .join("");
+    const search = names.length > 5
+        ? '<label>Search library<input type="search" data-skill-search placeholder="Name or description"></label><p data-skill-no-matches hidden>No matching skills.</p>'
+        : "";
+    const d = options.draft ?? {};
+    const add = manage
+        ? `<details class="card"${options.error && options.draft?.["method"] ? " open" : ""}><summary>Add skill</summary><form method="post" action="/settings/skills/import" data-skill-import>${hidden(base)}<label>Add from<select name="method" data-skill-method><option value="paste"${d["method"] === "paste" ? " selected" : ""}>Paste SKILL.md</option><option value="github"${d["method"] === "github" ? " selected" : ""}>GitHub folder</option><option value="folder"${d["method"] === "folder" ? " selected" : ""}>Local folder</option></select></label><div data-skill-input="paste"><label>SKILL.md<textarea name="content" rows="8" maxlength="24576" placeholder="---&#10;name: design-review&#10;description: Review interface copy and layout.&#10;---&#10;Write your instructions here.">${e(d["content"])}</textarea></label></div><div data-skill-input="github"><label>Public GitHub folder<input name="url" type="url" value="${e(d["url"])}" placeholder="https://github.com/owner/repo/tree/main/skills/review"></label></div><div data-skill-input="folder"><label>Skill folder<input type="file" webkitdirectory multiple data-skill-folder></label><input type="hidden" name="files" value=""><p class="meta">Choose the folder containing SKILL.md. Up to 64 files, 1 MB total.</p><noscript>Folder uploads require JavaScript. You can paste SKILL.md or use a GitHub folder.</noscript></div><p class="meta">Added to your library first. Review its source and requirements before enabling it.</p><p data-skill-error role="alert" hidden></p><button>Add to library</button></form></details>`
+        : "";
+    const history = view.history.length
+        ? `<details><summary>Change history</summary>${view.history.map((h) => `<div class="card"><p>Selection ${h.revision} · ${e(h.actor)} · ${e(h.at.slice(0, 16).replace("T", " "))} UTC</p><ul>${h.enabled.length ? h.enabled.map((s) => `<li>${e(s.name)} · ${e(s.version)}</li>`).join("") : "<li>No skills enabled</li>"}</ul>${manage && h.revision !== view.revision ? form("restore", "<button>Restore selection</button>", { restore: h.revision }) : '<span class="meta">Current selection</span>'}</div>`).join("")}</details>`
+        : "";
+    return `<section class="skills">${options.error ? `<p class="problem" role="alert">${e(options.error)}</p>` : ""}<p>${active ? `${active} skill${active === 1 ? "" : "s"} enabled for new tasks.` : "No skills enabled for this project."} Active tasks keep their saved versions.</p>${add}${search}${cards || "<p>Your library is empty. Add a skill to review and enable it here.</p>"}${history}</section>`;
+}
+export function skillsSnapshotHtml(snapshot) {
+    if (!snapshot || !snapshot.packages.length)
+        return "";
+    return `<details class="skills"><summary>Skills supplied (${snapshot.packages.length})</summary><p class="meta">Exact versions supplied to this run. This does not confirm the agent read or applied them.</p>${snapshot.packages.map((s) => `<details><summary>${e(s.name)} · ${s.sha.slice(0, 10)}</summary>${source(s)}</details>`).join("")}</details>`;
+}
+export function skillsScript() {
+    return `(()=>{const search=document.querySelector('[data-skill-search]');if(search)search.addEventListener('input',()=>{let found=0;document.querySelectorAll('[data-skill-group]').forEach(el=>{el.hidden=!el.dataset.skillQuery.toLowerCase().includes(search.value.trim().toLowerCase());if(!el.hidden)found++;});document.querySelector('[data-skill-no-matches]').hidden=found>0;});const form=document.querySelector('[data-skill-import]');if(!form)return;const method=form.querySelector('[data-skill-method]'),error=form.querySelector('[data-skill-error]');function sync(){form.querySelectorAll('[data-skill-input]').forEach(el=>{el.hidden=el.dataset.skillInput!==method.value;el.querySelectorAll('input,textarea').forEach(i=>i.disabled=el.hidden);});}method.addEventListener('change',sync);sync();form.addEventListener('submit',async event=>{if(method.value!=='folder')return;if(form.dataset.prepared==='yes'){delete form.dataset.prepared;return;}event.preventDefault();error.hidden=true;const button=form.querySelector('button');button.disabled=true;try{const files=Array.from(form.querySelector('[data-skill-folder]').files);if(!files.length||files.length>64||files.reduce((n,f)=>n+f.size,0)>1048576||files.some(f=>f.size>262144))throw Error('Choose one skill folder with up to 64 files and 1 MB total.');const packed=[];for(const file of files){const parts=file.webkitRelativePath.split('/');parts.shift();const data=new Uint8Array(await file.arrayBuffer());let binary='';for(const byte of data)binary+=String.fromCharCode(byte);packed.push({path:parts.join('/'),base64:btoa(binary)});}form.querySelector('[name=files]').value=JSON.stringify(packed);form.dataset.prepared='yes';button.disabled=false;form.requestSubmit();}catch(e){error.textContent=e.message||'The folder could not be read. Select it again.';error.hidden=false;button.disabled=false;}});})();`;
+}
+export function skillTestFeedbackHtml(test, csrf, canManage, error = "", draft = "") {
+    return `<section class="skills" id="skill-test-feedback"><h2>Improve this test</h2>${test.sourceRun ? `<p>Revises test run #${test.sourceRun}.</p>` : ""}${test.feedback ? `<details><summary>Feedback for this test</summary><p>${e(test.feedback)}</p></details>` : ""}${test.revisions.length ? `<p>${test.revisions.map((id, i) => `<a href="/t/${encodeURIComponent(id)}">Test revision ${i + 1}</a>`).join(" · ")}</p>` : ""}${error ? `<p role="alert">${e(error)}</p>` : ""}${canManage && csrf ? `<form method="post" action="/settings/skills/revise">${hidden({ csrf, repo: test.repo, run: test.run, nonce: randomUUID() })}<label>What should change?<textarea name="feedback" required maxlength="500" rows="3" placeholder="Try a clearer action label and explain why it fits the user’s goal.">${e(draft)}</textarea></label><p class="meta">Creates another report task with this skill version and your feedback. Review its scope before it runs.</p><button>Create revision</button></form>` : ""}</section>`;
+}

package/dist/skills.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `toolroll skills install` (M7.13) — how a repository tells its
+ * agents this queue exists.
+ *
+ * Two artifacts, both operator-invoked, previewed by default, and marked
+ * as managed so nothing here ever overwrites a file it does not own:
+ *
+ *   - `.claude/skills/toolroll/SKILL.md` — the Agent Skills entry
+ *     (the cross-vendor layout Claude Code, Codex, Gemini CLI, and
+ *     opencode all read). Router-style: the description says when to
+ *     reach for the CLI; the body carries the operating contract and
+ *     defers to live `--help` for everything else, because a skill that
+ *     duplicates the manual drifts from it.
+ *   - a managed AGENTS.md block (CLAUDE.md-compatible), written only
+ *     with --write-context, replaced only between its own markers.
+ *
+ * DESIGN's "nothing is ever installed for you" holds: this command runs
+ * when the operator runs it, shows exactly what it would write, and
+ * touches nothing without --yes.
+ */
+export declare const SKILL_DIR: string;
+/** Where installs before the rename to Toolroll put the skill: still found, and replaced by the new one. */
+export declare const LEGACY_SKILL_DIR: string;
+export declare const SKILL_FILE = "SKILL.md";
+export declare const MANAGED_MARK = "managed by toolroll \u2014 edits outside the markers survive reinstalls";
+export declare const CONTEXT_BEGIN = "<!-- standing-orders:begin -->";
+export declare const CONTEXT_END = "<!-- standing-orders:end -->";
+/** The skill, complete. The description is the routing contract. The body
+ * is the binary-served `operating` guide (guides.ts) — ONE source, so the
+ * installed snapshot and `skills get operating` cannot drift apart within
+ * a version. The frontmatter prefix and the managed mark are the ownership
+ * signature planInstall checks — do not reword them. */
+export declare function skillContent(): string;
+/** The AGENTS.md block, marker-fenced so reinstalls replace only themselves. */
+export declare function contextBlock(): string;
+export type InstallPlan = {
+    skillPath: string;
+    skillAction: "create" | "replace" | "refuse-foreign";
+    /** A skill of ours under the old folder name, removed once the new one is written. */
+    legacySkillPath: string | null;
+    contextPath: string | null;
+    contextAction: "create" | "insert" | "replace" | "skip";
+};
+export type InstallResult = {
+    ok: true;
+    plan: InstallPlan;
+    wrote: string[];
+} | {
+    ok: false;
+    reason: "foreign-skill" | "broken-markers";
+    message: string;
+};
+/** What install would do, computed without writing anything. */
+export declare function planInstall(repo: string, writeContext: boolean): InstallPlan;
+/** Apply the plan. Refuses a foreign skill file rather than eating it. */
+export declare function applyInstall(repo: string, writeContext: boolean): InstallResult;
+/**
+ * The user-level Claude Code skill is separate from the repository-local
+ * skill above. The former teaches one Claude Code installation how to use
+ * this exact Toolroll binary; the latter remains part of the shared
+ * project setup flow.
+ */
+export declare const CLAUDE_CODE_MANAGED_MARK = "<!-- standing-orders:claude-code-skill:v1 -->";
+export declare const CLAUDE_CODE_GUIDES: readonly ["console", "operating", "runner"];
+export type ClaudeCodeSkillFile = {
+    name: string;
+    path: string;
+    action: "create" | "replace" | "refuse-foreign";
+};
+export type ClaudeCodeInstallPlan = {
+    directory: string;
+    directoryAction: "create" | "use" | "refuse-foreign";
+    files: ClaudeCodeSkillFile[];
+    /** Managed files left under the old folder name, removed once the new ones are written. */
+    legacyFiles: string[];
+};
+export type ClaudeCodeInstallResult = {
+    ok: true;
+    plan: ClaudeCodeInstallPlan;
+    wrote: string[];
+} | {
+    ok: false;
+    reason: "foreign-file";
+    message: string;
+    plan: ClaudeCodeInstallPlan;
+};
+export declare function defaultClaudeCodeSkillDir(home?: string): string;
+/** Where installs before the rename put the Claude Code skill. */
+export declare function legacyClaudeCodeSkillDir(home?: string): string;
+/** SKILL.md links to the full guides instead of copying their detail. */
+export declare function claudeCodeSkillContent(): string;
+/** One linked file, generated from the guide embedded in this binary. */
+export declare function claudeCodeGuideContent(name: typeof CLAUDE_CODE_GUIDES[number]): string;
+/** Compute the complete write set without changing the filesystem. */
+export declare function planClaudeCodeInstall(directory?: string, legacyDirectory?: string | null): ClaudeCodeInstallPlan;
+/** Refresh every managed file, after validating the whole set first. */
+export declare function applyClaudeCodeInstall(directory?: string, legacyDirectory?: string | null): ClaudeCodeInstallResult;

package/dist/skills.js

@@ -0,0 +1,276 @@
+/**
+ * `toolroll skills install` (M7.13) — how a repository tells its
+ * agents this queue exists.
+ *
+ * Two artifacts, both operator-invoked, previewed by default, and marked
+ * as managed so nothing here ever overwrites a file it does not own:
+ *
+ *   - `.claude/skills/toolroll/SKILL.md` — the Agent Skills entry
+ *     (the cross-vendor layout Claude Code, Codex, Gemini CLI, and
+ *     opencode all read). Router-style: the description says when to
+ *     reach for the CLI; the body carries the operating contract and
+ *     defers to live `--help` for everything else, because a skill that
+ *     duplicates the manual drifts from it.
+ *   - a managed AGENTS.md block (CLAUDE.md-compatible), written only
+ *     with --write-context, replaced only between its own markers.
+ *
+ * DESIGN's "nothing is ever installed for you" holds: this command runs
+ * when the operator runs it, shows exactly what it would write, and
+ * touches nothing without --yes.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { guideNamed } from "./guides.js";
+export const SKILL_DIR = join(".claude", "skills", "toolroll");
+/** Where installs before the rename to Toolroll put the skill: still found, and replaced by the new one. */
+export const LEGACY_SKILL_DIR = join(".claude", "skills", "standing-orders");
+export const SKILL_FILE = "SKILL.md";
+export const MANAGED_MARK = "managed by toolroll — edits outside the markers survive reinstalls";
+const LEGACY_MANAGED_MARK = "managed by standing-orders — edits outside the markers survive reinstalls";
+/** Frontmatter a skill of ours starts with, under either name. */
+const OWN_HEADERS = ["---\nname: toolroll\n", "---\nname: standing-orders\n"];
+const ownHeader = (content) => OWN_HEADERS.some(header => content.startsWith(header));
+export const CONTEXT_BEGIN = "<!-- standing-orders:begin -->";
+export const CONTEXT_END = "<!-- standing-orders:end -->";
+/** The skill, complete. The description is the routing contract. The body
+ * is the binary-served `operating` guide (guides.ts) — ONE source, so the
+ * installed snapshot and `skills get operating` cannot drift apart within
+ * a version. The frontmatter prefix and the managed mark are the ownership
+ * signature planInstall checks — do not reword them. */
+export function skillContent() {
+    const operating = guideNamed("operating");
+    if (operating === null)
+        throw new Error("the operating guide is missing from the build");
+    return `---
+name: toolroll
+description: Operate this repository's unattended work queue via the toolroll CLI, and explain its console. Use when asked to file or inspect tasks (including scout tasks that deliver a report), check what is ready or blocked, peek at live agents, read run results and briefs, see what awaits a human decision, or tell the operator which screen or command does what. Not for pushing, merging, or approving anything — approvals are the operator's, always.
+---
+
+<!-- ${MANAGED_MARK} -->
+
+${operating.content}
+<!-- end ${MANAGED_MARK} -->
+`;
+}
+/** The AGENTS.md block, marker-fenced so reinstalls replace only themselves. */
+export function contextBlock() {
+    return `${CONTEXT_BEGIN}
+This repository's unattended work runs through the \`toolroll\` CLI
+(work queue, decisions, runs). Machine answers: add \`--json\` — one
+envelope per command, stable \`reason\` tokens, exit 3 means "no" not
+"broken", every mutation takes an idempotency \`--key\`. Refusals like
+\`held\`, \`fenced\`, \`reserved\`, \`unapproved\`, and \`external\` are
+answers to branch on, not errors to retry. Details:
+\`.claude/skills/toolroll/SKILL.md\`, or \`toolroll --help\`,
+which is authoritative — and \`toolroll skills get <name>\` serves
+version-matched guides straight from the binary (\`skills list\` names
+them). Project memory (instructions, references, lessons, decisions) lives
+in the plane: read \`skills get knowledge\`, search it with
+\`toolroll memory search\`, and record settled choices with
+\`memory decide\` instead of editing this file. Never approve, push, or
+merge anything yourself.
+${CONTEXT_END}`;
+}
+/** What install would do, computed without writing anything. */
+export function planInstall(repo, writeContext) {
+    const skillPath = join(repo, SKILL_DIR, SKILL_FILE);
+    let skillAction = "create";
+    if (existsSync(skillPath)) {
+        const current = readFileSync(skillPath, "utf8");
+        // Ownership is the exact header AND the managed mark — a foreign file
+        // that merely quotes the mark somewhere is not ours (audit C-10).
+        const ours = ownHeader(current) && (current.includes(MANAGED_MARK) || current.includes(LEGACY_MANAGED_MARK));
+        skillAction = ours ? "replace" : "refuse-foreign";
+    }
+    const legacy = join(repo, LEGACY_SKILL_DIR, SKILL_FILE);
+    const legacySkillPath = realFolder(join(repo, ".claude")) && realFolder(join(repo, ".claude", "skills")) && realFolder(join(repo, LEGACY_SKILL_DIR)) && isOwnFile(legacy, current => ownHeader(current) && (current.includes(MANAGED_MARK) || current.includes(LEGACY_MANAGED_MARK))) ? legacy : null;
+    const contextPath = writeContext ? join(repo, "AGENTS.md") : null;
+    let contextAction = "skip";
+    if (contextPath !== null) {
+        if (!existsSync(contextPath))
+            contextAction = "create";
+        else {
+            const current = readFileSync(contextPath, "utf8");
+            contextAction = current.includes(CONTEXT_BEGIN) ? "replace" : "insert";
+        }
+    }
+    return { skillPath, skillAction, legacySkillPath, contextPath, contextAction };
+}
+/** Apply the plan. Refuses a foreign skill file rather than eating it. */
+export function applyInstall(repo, writeContext) {
+    const plan = planInstall(repo, writeContext);
+    if (plan.skillAction === "refuse-foreign") {
+        return {
+            ok: false,
+            reason: "foreign-skill",
+            message: `${plan.skillPath} exists and was not written by this installer — refusing to overwrite a file that is not mine`,
+        };
+    }
+    // EVERY validation happens before EITHER file is touched — "nothing was
+    // written" must be true when it is said (arc-5 review, finding 6; the
+    // old order wrote the skill first and then refused on damaged markers).
+    let contextNext = null;
+    if (plan.contextPath !== null && plan.contextAction !== "create") {
+        const current = readFileSync(plan.contextPath, "utf8");
+        if (plan.contextAction === "replace") {
+            // Exactly one well-ordered pair, or a typed refusal — a half block
+            // must never produce a silent false success (audit C-10).
+            const begins = current.split(CONTEXT_BEGIN).length - 1;
+            const ends = current.split(CONTEXT_END).length - 1;
+            const begin = current.indexOf(CONTEXT_BEGIN);
+            const end = current.indexOf(CONTEXT_END);
+            if (begins !== 1 || ends !== 1 || end <= begin) {
+                return {
+                    ok: false,
+                    reason: "broken-markers",
+                    message: `${plan.contextPath} carries a damaged managed block (${begins} begin, ${ends} end marker(s)) — repair or remove it by hand; nothing was written`,
+                };
+            }
+            contextNext = current.slice(0, begin) + contextBlock() + current.slice(end + CONTEXT_END.length);
+        }
+        else {
+            // insert: append after existing content, never rewriting a word of it.
+            contextNext = `${current.replace(/\n*$/, "\n\n")}${contextBlock()}\n`;
+        }
+    }
+    const wrote = [];
+    mkdirSync(dirname(plan.skillPath), { recursive: true });
+    writeFileSync(plan.skillPath, skillContent());
+    wrote.push(plan.skillPath);
+    if (plan.legacySkillPath !== null)
+        removeOwn([plan.legacySkillPath]);
+    if (plan.contextPath !== null) {
+        writeFileSync(plan.contextPath, contextNext ?? `${contextBlock()}\n`);
+        wrote.push(plan.contextPath);
+    }
+    return { ok: true, plan, wrote };
+}
+/**
+ * The user-level Claude Code skill is separate from the repository-local
+ * skill above. The former teaches one Claude Code installation how to use
+ * this exact Toolroll binary; the latter remains part of the shared
+ * project setup flow.
+ */
+export const CLAUDE_CODE_MANAGED_MARK = "<!-- standing-orders:claude-code-skill:v1 -->";
+export const CLAUDE_CODE_GUIDES = ["console", "operating", "runner"];
+export function defaultClaudeCodeSkillDir(home = homedir()) {
+    return join(home, ".claude", "skills", "toolroll");
+}
+/** Where installs before the rename put the Claude Code skill. */
+export function legacyClaudeCodeSkillDir(home = homedir()) {
+    return join(home, ".claude", "skills", "standing-orders");
+}
+/** A regular file (not a link) whose text says it is ours. */
+function isOwnFile(path, ours) {
+    if (!existsSync(path))
+        return false;
+    const entry = lstatSync(path);
+    return !entry.isSymbolicLink() && entry.isFile() && entry.size <= 2_000_000 && ours(readFileSync(path, "utf8"));
+}
+/** A folder that is itself, not a link to somewhere else. */
+function realFolder(path) {
+    try {
+        const entry = lstatSync(path);
+        return entry.isDirectory() && !entry.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove files of ours, then their folder only if nothing else is left in it. */
+function removeOwn(paths) {
+    for (const path of paths)
+        unlinkSync(path);
+    const folders = new Set(paths.map(path => dirname(path)));
+    for (const folder of folders)
+        if (readdirSync(folder).length === 0)
+            rmdirSync(folder);
+}
+/** SKILL.md links to the full guides instead of copying their detail. */
+export function claudeCodeSkillContent() {
+    return `---
+name: toolroll
+description: Use this machine's Toolroll installation from Claude Code. Use when the user asks about its console, tasks, approvals, results, or runner workflow.
+---
+
+${CLAUDE_CODE_MANAGED_MARK}
+
+# Toolroll
+
+Use the installed \`toolroll\` command. Its live help is authoritative.
+
+- [Console guide](console.md) — where a person can review and act.
+- [Operating guide](operating.md) — the command contract and safe workflow.
+- [Runner guide](runner.md) — claims, leases, heartbeats, and fencing.
+`;
+}
+/** One linked file, generated from the guide embedded in this binary. */
+export function claudeCodeGuideContent(name) {
+    const guide = guideNamed(name);
+    if (guide === null)
+        throw new Error(`the ${name} guide is missing from the build`);
+    return `${CLAUDE_CODE_MANAGED_MARK}\n\n${guide.content.replace(/\n*$/, "\n")}`;
+}
+function claudeCodeFiles(directory) {
+    return [
+        { name: "SKILL.md", path: join(directory, "SKILL.md"), content: claudeCodeSkillContent() },
+        ...CLAUDE_CODE_GUIDES.map(name => ({
+            name: `${name}.md`,
+            path: join(directory, `${name}.md`),
+            content: claudeCodeGuideContent(name),
+        })),
+    ];
+}
+function isClaudeCodeManaged(name, content) {
+    if (name === "SKILL.md") {
+        return ownHeader(content) && content.includes(`\n${CLAUDE_CODE_MANAGED_MARK}\n`);
+    }
+    return content.startsWith(`${CLAUDE_CODE_MANAGED_MARK}\n\n`);
+}
+/** Compute the complete write set without changing the filesystem. */
+export function planClaudeCodeInstall(directory = defaultClaudeCodeSkillDir(), legacyDirectory = directory === defaultClaudeCodeSkillDir() ? legacyClaudeCodeSkillDir() : null) {
+    let directoryAction = "create";
+    if (existsSync(directory)) {
+        const entry = lstatSync(directory);
+        directoryAction = entry.isDirectory() && !entry.isSymbolicLink() ? "use" : "refuse-foreign";
+    }
+    const files = claudeCodeFiles(directory).map(({ name, path }) => {
+        if (directoryAction === "refuse-foreign" || !existsSync(path))
+            return {
+                name,
+                path,
+                action: directoryAction === "refuse-foreign" ? "refuse-foreign" : "create",
+            };
+        const entry = lstatSync(path);
+        if (entry.isSymbolicLink() || !entry.isFile() || entry.size > 2_000_000) {
+            return { name, path, action: "refuse-foreign" };
+        }
+        const current = readFileSync(path, "utf8");
+        return { name, path, action: isClaudeCodeManaged(name, current) ? "replace" : "refuse-foreign" };
+    });
+    const legacyFiles = legacyDirectory === null || legacyDirectory === directory || !realFolder(legacyDirectory)
+        ? []
+        : claudeCodeFiles(legacyDirectory).filter(({ name, path }) => isOwnFile(path, content => isClaudeCodeManaged(name, content))).map(({ path }) => path);
+    return { directory, directoryAction, files, legacyFiles };
+}
+/** Refresh every managed file, after validating the whole set first. */
+export function applyClaudeCodeInstall(directory = defaultClaudeCodeSkillDir(), legacyDirectory = directory === defaultClaudeCodeSkillDir() ? legacyClaudeCodeSkillDir() : null) {
+    const plan = planClaudeCodeInstall(directory, legacyDirectory);
+    const refused = plan.files.find(file => file.action === "refuse-foreign");
+    if (refused !== undefined) {
+        const message = plan.directoryAction === "refuse-foreign"
+            ? `${plan.directory} is not a regular directory — refusing to replace it`
+            : `${refused.path} exists and was not written by this installer — refusing to overwrite it`;
+        return { ok: false, reason: "foreign-file", message, plan };
+    }
+    mkdirSync(directory, { recursive: true });
+    const wrote = [];
+    for (const file of claudeCodeFiles(directory)) {
+        writeFileSync(file.path, file.content);
+        wrote.push(file.path);
+    }
+    if (plan.legacyFiles.length > 0)
+        removeOwn(plan.legacyFiles);
+    return { ok: true, plan, wrote };
+}

package/dist/slack-api.d.ts

@@ -0,0 +1,55 @@
+import { ChatDeliveryError } from "./chat-delivery-state.js";
+import { type SlackIdentity } from "./slack-state.js";
+export type SlackCredentials = SlackIdentity & {
+    appToken: string;
+    botToken: string;
+};
+export type SlackApi = (method: string, args?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export declare class SlackError extends ChatDeliveryError {
+    constructor(code: string, retryMs?: number, uncertain?: boolean);
+}
+export declare function slackApi(token: string, fetcher?: typeof fetch): SlackApi;
+export declare const slackCredentialFile: (dir: string) => string;
+export declare function loadSlackCredentials(dir: string): SlackCredentials | null;
+export declare function saveSlackCredentials(dir: string, value: SlackCredentials): void;
+export declare function clearSlackCredentials(dir: string): void;
+export declare function checkSlackCredentials(appToken: string, botToken: string, fetcher?: typeof fetch): Promise<SlackCredentials>;
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function slackId(value: unknown, prefix: string): value is string;
+export declare function slackTs(value: unknown): value is string;
+export declare function slackMember(api: SlackApi, identity: SlackIdentity, member: string, channel: string): Promise<boolean>;
+export declare function uploadSlackBytes(url: string, bytes: Uint8Array, fetcher?: typeof fetch): Promise<void>;
+/** DM scopes plus channel history for rooms that follow a team conversation. */
+export declare const SLACK_MANIFEST: {
+    display_information: {
+        name: string;
+        description: string;
+        background_color: string;
+    };
+    features: {
+        bot_user: {
+            display_name: string;
+            always_online: boolean;
+        };
+        app_home: {
+            home_tab_enabled: boolean;
+            messages_tab_enabled: boolean;
+            messages_tab_read_only_enabled: boolean;
+        };
+    };
+    oauth_config: {
+        scopes: {
+            bot: string[];
+        };
+    };
+    settings: {
+        event_subscriptions: {
+            bot_events: string[];
+        };
+        interactivity: {
+            is_enabled: boolean;
+        };
+        socket_mode_enabled: boolean;
+        token_rotation_enabled: boolean;
+    };
+};