harnery 0.34.1 → 0.36.0

package/dist/lib/http/client.js

@@ -1,7 +1,8 @@
 /**
  * Fetch a URL with optional cookie-jar attach + persist.
  *
- * Returns the response body as a string (callers handle JSON parsing).
+ * Returns the response body as text by default (callers handle JSON parsing).
+ * Pass `responseType: "bytes"` when the caller must preserve the body exactly.
  * Streams aren't supported; this is a CLI helper, not a streaming HTTP
  * client. Use Bun's `fetch` directly for streaming workloads.
  */
@@ -21,13 +22,27 @@ export async function fetchWithJar(url, opts = {}) {
                 headers[k] = v;
         }
     }
-    const response = await fetch(url, {
+    // Byte mode is a download boundary, so keep the HTTP representation bytes
+    // aligned with the response headers. Bun otherwise decompresses the body
+    // while retaining Content-Encoding and the encoded Content-Length.
+    if (opts.responseType === "bytes" && !headers["Accept-Encoding"] && !headers["accept-encoding"]) {
+        headers["Accept-Encoding"] = "identity";
+    }
+    const fetchInit = {
         method: opts.method ?? "GET",
         body: opts.body,
         headers,
         redirect: opts.redirect ?? "follow",
         signal: opts.signal,
-    });
+    };
+    if (opts.responseType === "bytes")
+        fetchInit.decompress = false;
+    const response = await fetch(url, fetchInit);
+    if (opts.responseType === "bytes" &&
+        typeof Bun === "undefined" &&
+        response.headers.has("content-encoding")) {
+        throw new Error("cannot preserve a content-encoded response under the Node fallback; install Bun or request identity encoding");
+    }
     let cookiesSaved = 0;
     if (opts.jar) {
         const setCookieHeaders = collectSetCookie(response.headers);
@@ -46,12 +61,15 @@ export async function fetchWithJar(url, opts = {}) {
     response.headers.forEach((value, key) => {
         headerObj[key] = value;
     });
+    const body = opts.responseType === "bytes"
+        ? new Uint8Array(await response.arrayBuffer())
+        : await response.text();
     return {
         status: response.status,
         statusText: response.statusText,
         url: response.url,
         headers: headerObj,
-        body: await response.text(),
+        body: body,
         cookiesSaved,
     };
 }

package/dist/lib/http/index.d.ts

@@ -1,3 +1,3 @@
-export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+export { type FetchOptions, type FetchResponseType, type FetchResult, fetchWithJar, } from "./client.js";
 export * from "./request.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/http/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC"}

package/dist/lib/http/index.js

@@ -1,2 +1,2 @@
-export { fetchWithJar } from "./client.js";
+export { fetchWithJar, } from "./client.js";
 export * from "./request.js";

package/dist/lib/indexer-exclusions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Editor-indexer exclusions for the `.harnery/` coord root.
+ *
+ * `harn init` already writes `.harnery/.gitignore`, which keeps git-aware
+ * tools out of runtime state. Two high-traffic editor surfaces ignore
+ * gitignore, though: Cursor's codebase indexer (governed by a repo-root
+ * `.cursorindexingignore`) and the VS Code/Cursor file watcher (governed by
+ * `files.watcherExclude` in `.vscode/settings.json`). A busy coord root holds
+ * tens of thousands of ledger events plus working artifacts, so on
+ * session-heavy hosts the missing exclusions turn editor startup into an
+ * indexing storm over machine-local state no editor needs to see.
+ *
+ * `applyIndexerExclusions` is idempotent and non-destructive: it appends a
+ * managed entry to `.cursorindexingignore` (or creates the file) and merges a
+ * single key into `.vscode/settings.json` (or creates it). A settings file it
+ * cannot merge safely (comments, malformed JSON, or a non-object
+ * `files.watcherExclude`) is left byte-identical and reported as a manual
+ * step. `removeIndexerExclusions` reverses exactly what apply wrote: it never
+ * removes a `.harnery/` ignore entry the consumer added themselves (detected
+ * by the absence of the managed comment) and never edits a settings file it
+ * could not have written into.
+ */
+/** Ensure both editor exclusions exist. Returns init-style action lines. */
+export declare function applyIndexerExclusions(projectRoot: string, dryRun: boolean): string[];
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export declare function removeIndexerExclusions(projectRoot: string, dryRun: boolean): string[];
+//# sourceMappingURL=indexer-exclusions.d.ts.map

package/dist/lib/indexer-exclusions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer-exclusions.d.ts","sourceRoot":"","sources":["../../src/lib/indexer-exclusions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4IH,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAErF;AAED,2FAA2F;AAC3F,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAKtF"}

package/dist/lib/indexer-exclusions.js

@@ -0,0 +1,176 @@
+/**
+ * Editor-indexer exclusions for the `.harnery/` coord root.
+ *
+ * `harn init` already writes `.harnery/.gitignore`, which keeps git-aware
+ * tools out of runtime state. Two high-traffic editor surfaces ignore
+ * gitignore, though: Cursor's codebase indexer (governed by a repo-root
+ * `.cursorindexingignore`) and the VS Code/Cursor file watcher (governed by
+ * `files.watcherExclude` in `.vscode/settings.json`). A busy coord root holds
+ * tens of thousands of ledger events plus working artifacts, so on
+ * session-heavy hosts the missing exclusions turn editor startup into an
+ * indexing storm over machine-local state no editor needs to see.
+ *
+ * `applyIndexerExclusions` is idempotent and non-destructive: it appends a
+ * managed entry to `.cursorindexingignore` (or creates the file) and merges a
+ * single key into `.vscode/settings.json` (or creates it). A settings file it
+ * cannot merge safely (comments, malformed JSON, or a non-object
+ * `files.watcherExclude`) is left byte-identical and reported as a manual
+ * step. `removeIndexerExclusions` reverses exactly what apply wrote: it never
+ * removes a `.harnery/` ignore entry the consumer added themselves (detected
+ * by the absence of the managed comment) and never edits a settings file it
+ * could not have written into.
+ */
+import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const CURSOR_IGNORE = ".cursorindexingignore";
+const MANAGED_COMMENT = "# .harnery/ is machine-local harnery runtime state (entry managed by init)";
+const MANAGED_ENTRY = ".harnery/";
+const VSCODE_DIR = ".vscode";
+const VSCODE_SETTINGS = ".vscode/settings.json";
+const WATCHER_KEY = "files.watcherExclude";
+const WATCHER_GLOB = "**/.harnery/**";
+/** True when a `.cursorindexingignore` line already excludes the coord root. */
+function coversCoordRoot(line) {
+    const t = line.trim();
+    return (t === ".harnery" ||
+        t === ".harnery/" ||
+        t === "/.harnery" ||
+        t === "/.harnery/" ||
+        t === ".harnery/**" ||
+        t === "/.harnery/**");
+}
+function applyCursorIgnore(projectRoot, dryRun) {
+    const path = resolve(projectRoot, CURSOR_IGNORE);
+    if (existsSync(path)) {
+        const raw = readFileSync(path, "utf8");
+        if (raw.split("\n").some(coversCoordRoot)) {
+            return `· ${CURSOR_IGNORE} already excludes .harnery/`;
+        }
+        if (dryRun)
+            return `+ would append .harnery/ to ${CURSOR_IGNORE}`;
+        const sep = raw === "" || raw.endsWith("\n") ? "" : "\n";
+        writeFileSync(path, `${raw}${sep}${MANAGED_COMMENT}\n${MANAGED_ENTRY}\n`);
+        return `+ appended .harnery/ to ${CURSOR_IGNORE}`;
+    }
+    if (dryRun)
+        return `+ would create ${CURSOR_IGNORE} (excludes .harnery/ from Cursor indexing)`;
+    writeFileSync(path, `${MANAGED_COMMENT}\n${MANAGED_ENTRY}\n`);
+    return `+ created ${CURSOR_IGNORE} (excludes .harnery/ from Cursor indexing)`;
+}
+function applyVscodeWatcherExclude(projectRoot, dryRun) {
+    const path = resolve(projectRoot, VSCODE_SETTINGS);
+    if (!existsSync(path)) {
+        if (dryRun)
+            return `+ would create ${VSCODE_SETTINGS} (file watcher excludes .harnery/)`;
+        mkdirSync(resolve(projectRoot, VSCODE_DIR), { recursive: true });
+        const body = JSON.stringify({ [WATCHER_KEY]: { [WATCHER_GLOB]: true } }, null, 2);
+        writeFileSync(path, `${body}\n`);
+        return `+ created ${VSCODE_SETTINGS} (file watcher excludes .harnery/)`;
+    }
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // JSONC (comments, trailing commas) or malformed. A rewrite would drop the
+        // consumer's comments, so leave the file alone and name the one-key merge.
+        return `! ${VSCODE_SETTINGS} is not plain JSON; add "${WATCHER_KEY}": {"${WATCHER_GLOB}": true} manually`;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return `! ${VSCODE_SETTINGS} is not a settings object; add "${WATCHER_KEY}": {"${WATCHER_GLOB}": true} manually`;
+    }
+    const settings = parsed;
+    const watcher = settings[WATCHER_KEY];
+    if (watcher !== undefined &&
+        (typeof watcher !== "object" || watcher === null || Array.isArray(watcher))) {
+        return `! ${VSCODE_SETTINGS} has a non-object "${WATCHER_KEY}"; add "${WATCHER_GLOB}": true manually`;
+    }
+    const map = watcher ?? {};
+    if (map[WATCHER_GLOB] === true) {
+        return `· ${VSCODE_SETTINGS} file watcher already excludes .harnery/`;
+    }
+    if (dryRun)
+        return `+ would add ${WATCHER_GLOB} to ${WATCHER_KEY} in ${VSCODE_SETTINGS}`;
+    map[WATCHER_GLOB] = true;
+    settings[WATCHER_KEY] = map;
+    writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+    return `+ added ${WATCHER_GLOB} to ${WATCHER_KEY} in ${VSCODE_SETTINGS}`;
+}
+function removeCursorIgnore(projectRoot, dryRun) {
+    const path = resolve(projectRoot, CURSOR_IGNORE);
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, "utf8");
+    const lines = raw.split("\n");
+    // Only the managed pair is ours. A bare `.harnery/` line without the managed
+    // comment is a consumer's own entry and stays.
+    if (!lines.some((line) => line.trim() === MANAGED_COMMENT))
+        return null;
+    if (dryRun)
+        return `+ would remove the managed .harnery/ entry from ${CURSOR_IGNORE}`;
+    const kept = lines.filter((line) => {
+        const t = line.trim();
+        return t !== MANAGED_COMMENT && t !== MANAGED_ENTRY;
+    });
+    if (kept.every((line) => line.trim() === "")) {
+        rmSync(path);
+        return `+ removed ${CURSOR_IGNORE} (was harnery-only)`;
+    }
+    let out = kept.join("\n");
+    if (!out.endsWith("\n"))
+        out += "\n";
+    writeFileSync(path, out);
+    return `+ removed the managed .harnery/ entry from ${CURSOR_IGNORE}`;
+}
+function removeVscodeWatcherExclude(projectRoot, dryRun) {
+    const path = resolve(projectRoot, VSCODE_SETTINGS);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // Not plain JSON, so apply never wrote into it.
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const settings = parsed;
+    const watcher = settings[WATCHER_KEY];
+    if (typeof watcher !== "object" || watcher === null || Array.isArray(watcher))
+        return null;
+    const map = watcher;
+    if (!(WATCHER_GLOB in map))
+        return null;
+    if (dryRun)
+        return `+ would remove ${WATCHER_GLOB} from ${VSCODE_SETTINGS}`;
+    delete map[WATCHER_GLOB];
+    if (Object.keys(map).length === 0)
+        delete settings[WATCHER_KEY];
+    if (Object.keys(settings).length === 0) {
+        rmSync(path);
+        try {
+            // Drop the .vscode/ directory too when the settings file was all it held.
+            rmdirSync(resolve(projectRoot, VSCODE_DIR));
+        }
+        catch {
+            // Non-empty or shared; leave it.
+        }
+        return `+ removed ${VSCODE_SETTINGS} (was harnery-only)`;
+    }
+    writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+    return `+ removed ${WATCHER_GLOB} from ${VSCODE_SETTINGS}`;
+}
+/** Ensure both editor exclusions exist. Returns init-style action lines. */
+export function applyIndexerExclusions(projectRoot, dryRun) {
+    return [applyCursorIgnore(projectRoot, dryRun), applyVscodeWatcherExclude(projectRoot, dryRun)];
+}
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export function removeIndexerExclusions(projectRoot, dryRun) {
+    return [
+        removeCursorIgnore(projectRoot, dryRun),
+        removeVscodeWatcherExclude(projectRoot, dryRun),
+    ].filter((line) => line !== null);
+}

package/dist/lib/instructions/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAkBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAmBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}

package/dist/lib/instructions/apply.js

@@ -70,6 +70,7 @@ function blockSkills(projectRoot, adapter) {
         decide: supported && !exclude.has("harn-decide"),
         council: supported && !exclude.has("harn-council"),
         end: supported && !exclude.has("harn-end"),
+        team: supported && !exclude.has("harn-team"),
     };
 }
 /**

package/dist/lib/instructions/templates.d.ts

@@ -29,6 +29,8 @@ export interface BlockSkills {
     council: boolean;
     /** the `harn-end` skill file is present */
     end: boolean;
+    /** the `harn-team` skill file is present */
+    team: boolean;
 }
 /**
  * The always-on orientation spliced into `AGENTS.md`. Target ≤ 80 rendered

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAwD,GAC/D,MAAM,CA+FR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsND,eAAO,MAAM,MAAM,EAAE,aAAa,EAqCjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CA0GR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -35,12 +35,13 @@ export const HOST_ADDENDUM_REGION = "host-addendum";
  * excludes one via `skills.exclude` gets a CLI pointer instead of a dangling
  * reference to a skill it doesn't have.
  */
-export function renderInstructionsBlock(binName, skills = { decide: true, council: true, end: true }) {
+export function renderInstructionsBlock(binName, skills = { decide: true, council: true, end: true, team: true }) {
     const b = binName;
     const named = [
         skills.decide && "`harn-decide`",
         skills.council && "`harn-council`",
         skills.end && "`harn-end`",
+        skills.team && "`harn-team`",
     ].filter(Boolean);
     const deeper = named.length > 0
         ? `Procedures for the deeper flows live in the ${named.join(" and ")} skill${named.length > 1 ? "s" : ""}.`
@@ -54,6 +55,9 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     const endPointer = skills.end
         ? "When the whole session is genuinely finished, use the `harn-end` skill as the final workflow."
         : `When the whole session is genuinely finished, run \`${b} agents status --end-turn --end-session\` as the final tool action.`;
+    const teamPointer = skills.team
+        ? "The `harn-team` skill owns the tier choice, the governor artifacts, and the drive loop."
+        : `See \`${b} governor --help\` for the tier choice and the drive loop.`;
     // Render the journal categories from the canonical enum so this prose can
     // never drift from what `journal add` actually accepts (the "note, plan…" list
     // silently lagged the tool by two categories before this).
@@ -95,6 +99,7 @@ first when one pass will do, the second when the objective must outlive the
 attempt, and the third when a human would otherwise have to babysit the loop. A
 run that needs authorization parks durably instead of failing, so check
 \`${b} approval list\` when one appears to be waiting rather than stuck.
+${teamPointer}
 
 **Durable role handoff.** When you are replacing a prior session in the same
 named role, run \`${b} agents identity assume <name>\` before declaring your task.
@@ -103,9 +108,10 @@ live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
 **Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger. Lead a shell command with a \`# intent: <why>\` comment (or set
-the tool's description) so the recorded event carries a reason instead of
-\`(no intent)\`.
+coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+\`# intent: <why>\` comment (or set the tool's description) so the recorded event
+carries a reason instead of \`(no intent)\`; the [tool-intent
+guide](https://harnery.com/guides/tool-intent/) owns the details.
 
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
@@ -119,6 +125,11 @@ returned path, then run \`${b} artifacts release <id>\` when active work is done
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 
+**Local file links.** When the operator should open a local repo file, mint the
+URL with \`${b} files url <repo-relative-path>\` instead of guessing it. HTML opens
+as a real page with working scripts and relative assets; other files open in the
+dashboard viewer. Use localhost links only when the operator shares this machine.
+
 **Decision docket.** When you would otherwise stop to ask a human a decision you
 can't resolve from the repo, file it instead. \`${b} decision file "<question>"\`
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`
@@ -336,6 +347,130 @@ explicitly identifies it. Use the web control or \`${b} agents end --instance-id
 <id>\` for that operator action; it records immediately for an idle session or
 durably queues the end for its current turn.`;
 }
+function teamBody(b) {
+    return `Harnery gives you three ways to put more than one agent on a job. They differ
+by how long the objective outlives a single execution, and picking the wrong one
+is the usual reason a team spins. This skill owns that choice, the files a
+governed team needs, and the drive loop.
+
+## Step 0: do not build a second team
+
+Run this before anything else, every time:
+
+\`\`\`bash
+${b} governor list
+\`\`\`
+
+If a goal already covers the objective, **you are done building** — drive the
+existing one (Step 3). A second team pointed at the same tree fights the first:
+both hold the same files and their frozen missions contradict each other. It is
+the most expensive mistake available here, and it looks like progress while you
+make it. Listings are tolerant: an unreadable record prints a warning row with
+its id, which is evidence the goal *exists* — inspect it before creating a
+replacement. Treat stale or suffixed experiment goals as shared runtime state;
+archiving them is an operator call, not yours.
+
+## Step 1: pick the tier
+
+Match the tier to how long the objective must survive, not to how big it feels.
+
+| Surface | Use when | Dies when |
+|---|---|---|
+| \`${b} run <script>\` | One bounded pass: deterministic JS stages fan out to headless subagents. | The pass ends. Nothing remembers it. |
+| \`${b} work create <title> <workflow>\` | The objective must outlive the attempt: retries, failures, review rounds. | You accept or cancel it. |
+| \`${b} governor create\` | A graph of interdependent work with distinct roles, where a human would otherwise babysit the loop. | You accept the root or it exhausts its bounds. |
+
+When unsure, start with \`${b} run\`: it is the only tier you can throw away for
+free, and iterating a script there before freezing it is how you avoid
+invalidating a durable work item later. And check the sizing first: a single
+agent often matches a team on a task that does not truly decompose — reliability
+is multiplicative across steps, and the metric that decides is cost per
+completed task, not agent count.
+
+## Step 2: build the governor team
+
+Four artifacts, kept in a managed workspace
+(\`${b} artifacts create <slug> --purpose "<why>"\`), then frozen:
+
+**team.json** maps specialist id to profile: \`instructions\` (the role's whole
+charter) plus optional \`adapter\`, \`effort\`, \`maxAttempts\`. Two role rules
+carry most of the value: **split producing evidence from judging it** (a
+verifier that runs gates, a separate reviewer that accepts or refuses — no agent
+grades its own homework), and **add a standing scope-auditor** that reports at
+each milestone whether the finish line moved, since no one else is positioned to
+notice a rising bar. Write each role's hard boundaries explicitly, in the
+negative: name every act that is somebody else's. Write every brief as a
+four-part contract — objective, output (the named artifact that proves it),
+tools, boundaries — and pass references, not pasted content. \`timeoutMs\` and
+\`maxTurns\` are workflow-script options, never specialist-profile keys; the
+create command rejects unsupported keys with the offending key and the allowed
+set.
+
+**mission.json** carries \`objective\`, \`acceptance\` (criteria), and
+\`max_milestones\`. Write acceptance so **refusing is a representable outcome**
+("X exists, or the blocker is stated with its citation") — a criterion an agent
+cannot satisfy by correctly refusing gets reissued forever. Every criterion
+names the artifact that satisfies it (a path, a passing command, a review
+record); a criterion satisfiable by prose will eventually be satisfied exactly
+that way.
+
+**replanning.json** freezes the planner policy: \`planner_specialist\`,
+\`auto_apply\`, \`max_replans\`, \`max_work_items_per_plan\`,
+\`max_total_work_items\`, a \`templates\` catalog, and \`review\` with
+\`reviewer_specialists\` and \`max_revision_rounds\`. Keep \`auto_apply: false\`
+and proof auto-acceptance off for anything that can touch public state.
+
+**Workflow templates** are the plain-JS scripts the planner may choose from;
+route product decisions to a decision-brief template, never an implement one.
+Authoring traps (frozen script hashes, the five-minute \`timeoutMs\` default,
+schema caps, child sandboxes) live in the
+[workflow-authoring guide](https://harnery.com/guides/workflow-authoring/).
+
+\`\`\`bash
+${b} governor create --id <goal-id> --title "<title>" \\
+  --team <ws>/team.json --mission <ws>/mission.json \\
+  --replanning <ws>/replanning.json --max-parallel-work 2 --json
+\`\`\`
+
+## Step 3: drive it
+
+\`${b} governor show <goal-id> --json\` — the \`projection\` object is the whole
+dashboard: read \`state\`, \`reason\`, and \`next_action\`, then do exactly that
+action. Useful fields: \`ready_work\` / \`retryable_work\` / \`attention_work\`,
+\`decision_blocked_work\` (parked on a docket entry, not broken),
+\`replans_used\` / \`replans_remaining\`, and the milestone counters.
+
+\`\`\`bash
+${b} governor tick <goal-id>   # at most one scheduling cycle
+${b} governor run <goal-id>    # cycles until success, attention, or budget
+${b} approval list             # a run needing authorization parks, not fails
+\`\`\`
+
+Rules that prevent stranded work:
+
+- **Never drive a governed item with \`${b} work retry\` or \`${b} work run\`.**
+  Only the governor supplies the frozen specialist map; a bare retry starts a
+  run with no team, dies at the first specialist stage, and still burns the
+  attempt. \`${b} work retry\` is for standalone work only.
+- **A blocked item cannot be accepted.** When its objective was met out of band,
+  the door back is \`${b} work reopen\` plus a fresh governor cycle, not accept.
+- **Read the spin signals before retrying.** Zero milestones with climbing
+  \`replans_used\` and repeated reviewer rejections means the mission prose or
+  acceptance criteria are wrong, not the agents. Replans are capped; diagnose
+  first.
+- **A frozen mission cannot be edited** — deliberately. Pass corrections as
+  retry context on individual items, or create a new goal and cancel the old
+  one. Do not keep re-planning against prose you know is stale.
+- **"ended without terminal evidence"** means the child died before writing its
+  proof, not that the work failed. Check whether the outcome landed before
+  redoing it.
+
+## Reporting back
+
+Tell the operator which tier you chose and why, the goal id, the roles, and the
+single next action. If you declined to build a team because one already existed,
+say that first; it is the most useful sentence in the reply.`;
+}
 export const SKILLS = [
     {
         id: "harn-decide",
@@ -367,4 +502,14 @@ export const SKILLS = [
             body: endBody(binName),
         }),
     },
+    {
+        id: "harn-team",
+        relPath: "harn-team/SKILL.md",
+        render: (binName) => buildOwnedSkill({
+            name: "harn-team",
+            description: "Stand up and drive a multi-agent team on an objective: pick between a bounded run, durable work, and a governed role team; build the governor artifacts; drive off projection.next_action. Use when asked to put a team of agents on a job, orchestrate agents, or check on a goal already running. Refuses to build a second team when one already covers the objective.",
+            binName,
+            body: teamBody(binName),
+        }),
+    },
 ];

package/dist/lib/local-file-url.d.ts

@@ -0,0 +1,9 @@
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export declare const DEFAULT_WEB_PORT = 4276;
+/** Cookie-isolated host for navigable repo files. */
+export declare const FILES_ORIGIN_HOST = "harnery-files.localhost";
+/** Encode each repo-path segment while preserving slash-based URL resolution. */
+export declare function encodedRepoPath(relPath: string): string;
+export declare function localFilesOriginUrl(relPath: string, port?: number | string, protocol?: string): string;
+export declare function localFileViewerUrl(relPath: string, port?: number | string): string;
+//# sourceMappingURL=local-file-url.d.ts.map

package/dist/lib/local-file-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-url.d.ts","sourceRoot":"","sources":["../../src/lib/local-file-url.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,MAAyB,EACxC,QAAQ,SAAU,GACjB,MAAM,CAGR;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,MAAyB,GACvC,MAAM,CAER"}

package/dist/lib/local-file-url.js

@@ -0,0 +1,20 @@
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export const DEFAULT_WEB_PORT = 4276;
+/** Cookie-isolated host for navigable repo files. */
+export const FILES_ORIGIN_HOST = "harnery-files.localhost";
+/** Encode each repo-path segment while preserving slash-based URL resolution. */
+export function encodedRepoPath(relPath) {
+    return relPath
+        .replace(/^\/+/, "")
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+export function localFilesOriginUrl(relPath, port = DEFAULT_WEB_PORT, protocol = "http:") {
+    const portPart = String(port) === "" ? "" : `:${port}`;
+    return `${protocol}//${FILES_ORIGIN_HOST}${portPart}/${encodedRepoPath(relPath)}`;
+}
+export function localFileViewerUrl(relPath, port = DEFAULT_WEB_PORT) {
+    return `http://localhost:${port}/files?path=${encodeURIComponent(relPath)}`;
+}