@hardfin/cli 0.1.0-dev.35 → 0.1.0-dev.36

package/README.md

@@ -307,6 +307,32 @@ show a description beside each.
 The script calls `hardfin` by name, so it needs `hardfin` on your `PATH`. Running
 `node dist/cli.js` from a checkout leaves nothing for it to call, and `npm link` fixes that.
 
+## Setting up a project for agents
+
+```sh
+hardfin init            # the working directory
+hardfin init --dry-run  # what it would write, writing nothing
+```
+
+`hardfin init` gets a project ready for a coding agent to use Hardfin, the way EmDash's starter
+projects come ready. Running it again updates only what it wrote.
+
+| File                                  | What init writes                                                    |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| `.agents/skills/hardfin-cli/SKILL.md` | The `hardfin-cli` skill, which Codex and most agents read           |
+| `.claude/skills/hardfin-cli/SKILL.md` | The same skill, where Claude Code reads it                          |
+| `AGENTS.md`                           | A Hardfin section between `hardfin:start` and `hardfin:end` markers |
+| `.mcp.json`                           | The `hardfin` server, for Claude Code                               |
+| `.cursor/mcp.json`                    | The `hardfin` server, for Cursor                                    |
+| `.vscode/mcp.json`                    | The `hardfin` server, for VS Code                                   |
+
+The server is the hosted one at the authorization server's host, `https://api.hardfin.com/mcp`
+by default. Every other server in an MCP config, and everything in `AGENTS.md` outside the
+markers, is left as it was. A config that does not hold JSON is skipped, never overwritten.
+
+The skill lives in `skills/` and the section in `templates/AGENTS.md`. Both ship in the npm
+package, so `init` writes the copy that matches the installed CLI.
+
 ## Serving an agent
 
 ```sh

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e0ebce65-52b6-5732-b4b2-1becfe72bdef")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fa6bfe29-9ee3-5a91-aaa1-4b75576d7943")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,7 +14,7 @@ process.on("unhandledRejection", (error) => void toCrash(error));
 try {
 	const answer = await toQuickAnswer(process.argv.slice(2));
 	if (answer === void 0) {
-		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-BdRDIa3u.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-DtqGeehp.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
 	try {
-		const { toReported } = await import("./program-BdRDIa3u.js");
+		const { toReported } = await import("./program-DtqGeehp.js");
 		await toReported(error, false, void 0, "fatal");
 	} finally {
 		process.exit(1);
@@ -51,4 +51,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=e0ebce65-52b6-5732-b4b2-1becfe72bdef
+//# debugId=fa6bfe29-9ee3-5a91-aaa1-4b75576d7943

package/dist/completion-tree.json

@@ -73,6 +73,25 @@
       "arguments": [],
       "subcommands": []
     },
+    {
+      "name": "init",
+      "summary": "Set up a project so coding agents can use Hardfin",
+      "runs": true,
+      "flags": [
+        {
+          "name": "dry-run",
+          "description": "Say what would be written, and write nothing"
+        },
+        {
+          "name": "json",
+          "description": "Print machine-readable output, which is the default when stdout is not a terminal"
+        }
+      ],
+      "arguments": [
+        {}
+      ],
+      "subcommands": []
+    },
     {
       "name": "asset",
       "summary": "Asset commands",

package/dist/{program-BdRDIa3u.js → program-DtqGeehp.js}

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6057a656-73c2-55b1-9f09-873e3b83b368")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03b49867-f2d5-5a64-af87-e45e530711a1")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BN3gyBpR.js";
 import { n as toCompletion, t as toAnswer$1 } from "./completion-tree-rR_Rmeij.js";
 import { createRequire } from "node:module";
 import { Command, CommanderError, Option } from "commander";
 import { z } from "zod";
-import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
-import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { basename, delimiter, dirname, join, relative, resolve } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
 import { createInterface as createInterface$1 } from "node:readline";
-import { fileURLToPath } from "node:url";
 //#region src/report/expected.ts
 /**
 * ExpectedFailure is a failure the CLI anticipated: the person's input, their network, their
@@ -1486,7 +1486,7 @@ const uninstallCommand = defineCommand({
 * directory by itself, and every other shell is told to load the script from its startup
 * file, because not every bash has bash-completion to load it lazily.
 */
-function toPlan(shell, place) {
+function toPlan$1(shell, place) {
 	const content = `${toScript(shell)}\n`;
 	if (shell === "fish") {
 		const config = place.env["XDG_CONFIG_HOME"] || join(place.home, ".config");
@@ -1569,7 +1569,7 @@ function toShell(place) {
 }
 /** isInstalled answers whether install has written a script for any shell. */
 function isInstalled(place = toPlace()) {
-	return SHELLS.some((shell) => existsSync(toPlan(shell, {
+	return SHELLS.some((shell) => existsSync(toPlan$1(shell, {
 		...place,
 		toProfile: () => void 0
 	}).script.path));
@@ -1602,7 +1602,7 @@ async function runChange(input, change) {
 		writeFailure("invalid_arguments", `name the shell to ${change} for: ${SHELLS.join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const plan = toPlan(shell, place);
+	const plan = toPlan$1(shell, place);
 	if (change === "install" && shell === "powershell" && !plan.startup) {
 		writeFailure("shell_unavailable", "PowerShell did not report its profile, so there is nowhere to load the script from", input.isJSON);
 		return ExitCode.ERROR;
@@ -1841,6 +1841,164 @@ const crashCommand = defineCommand({
 	run: () => Promise.reject(/* @__PURE__ */ new TypeError("hardfin __crash failed on purpose, to check that defects are reported"))
 });
 //#endregion
+//#region src/command/init.ts
+/** The markers around the section init owns in AGENTS.md, so a second run replaces only that. */
+const SECTION_START = "<!-- hardfin:start -->";
+const SECTION_END = "<!-- hardfin:end -->";
+/** Where agents look for skills: Codex and most others, then Claude Code. */
+const SKILL_DIRECTORIES = [".agents/skills", ".claude/skills"];
+const initCommand = defineCommand({
+	name: "init",
+	summary: "Set up a project so coding agents can use Hardfin",
+	description: "Writes the hardfin-cli skill, a Hardfin section in AGENTS.md, and the Hardfin MCP server for Claude Code, Cursor and VS Code. Running it again updates what it wrote and leaves everything else alone.",
+	arguments: [{
+		name: "directory",
+		description: "The project to set up, which is the working directory when omitted",
+		required: false
+	}],
+	flags: [{
+		name: "dry-run",
+		description: "Say what would be written, and write nothing",
+		schema: z.boolean()
+	}, {
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Set up the project you are in",
+		command: "hardfin init"
+	}, {
+		description: "See what it would write first",
+		command: "hardfin init --dry-run"
+	}],
+	run: runInit
+});
+async function runInit(input) {
+	const target = resolve(input.args[0] ?? ".");
+	if (!existsSync(target) || !statSync(target).isDirectory()) {
+		writeFailure("invalid_arguments", `${target} is not a folder, so there is nothing to set up`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const mcpUrl = `${input.resolved.settings.issuerUrl.replace(/\/+$/, "")}/mcp`;
+	const planned = toPlan(target, toPackageDirectory(), mcpUrl);
+	const isDryRun = input.flags["dryRun"] === true;
+	if (!isDryRun) for (const entry of planned) entry.write?.();
+	const changes = planned.map((entry) => entry.change);
+	if (input.isJSON) {
+		writeData({
+			directory: target,
+			dryRun: isDryRun,
+			mcpUrl,
+			changes
+		});
+		return ExitCode.OK;
+	}
+	const lines = changes.map((change) => `${change.action.padEnd(10)} ${change.path}${change.reason ? `  (${change.reason})` : ""}`);
+	const closing = isDryRun ? "Nothing was written, because this was a dry run." : "Start an agent here and ask it to use Hardfin.";
+	writeData([
+		...lines,
+		"",
+		closing
+	].join("\n"));
+	return ExitCode.OK;
+}
+/** toPlan works out every file init writes, without writing any of them. */
+function toPlan(target, packageDirectory, mcpUrl) {
+	const planned = [];
+	const skills = join(packageDirectory, "skills");
+	for (const skill of readdirSync(skills)) for (const file of toFiles(join(skills, skill))) {
+		const content = readFileSync(file, "utf8");
+		for (const place of SKILL_DIRECTORIES) planned.push(toFilePlan(target, join(place, skill, relative(join(skills, skill), file)), content));
+	}
+	const section = readFileSync(join(packageDirectory, "templates", "AGENTS.md"), "utf8").replaceAll("{{MCP_URL}}", mcpUrl);
+	planned.push(toFilePlan(target, "AGENTS.md", toAgentsFile(join(target, "AGENTS.md"), section)));
+	planned.push(toJSONPlan(target, ".mcp.json", (config) => toWithServer(config, "mcpServers", {
+		type: "http",
+		url: mcpUrl
+	})), toJSONPlan(target, ".cursor/mcp.json", (config) => toWithServer(config, "mcpServers", { url: mcpUrl })), toJSONPlan(target, ".vscode/mcp.json", (config) => toWithServer(config, "servers", {
+		type: "http",
+		url: mcpUrl
+	})));
+	return planned;
+}
+/** toAgentsFile puts the Hardfin section into AGENTS.md, replacing the one an earlier run wrote. */
+function toAgentsFile(path, section) {
+	const block = `${SECTION_START}\n${section.trimEnd()}\n${SECTION_END}\n`;
+	if (!existsSync(path)) return `# Agent instructions\n\n${block}`;
+	const current = readFileSync(path, "utf8");
+	const start = current.indexOf(SECTION_START);
+	const end = current.indexOf(SECTION_END);
+	if (start >= 0 && end > start) return `${current.slice(0, start)}${block}${current.slice(end + 20).replace(/^\n/, "")}`;
+	return `${current.trimEnd()}\n\n${block}`;
+}
+/** toWithServer adds the hardfin server to an MCP config, leaving every other server as it was. */
+function toWithServer(config, key, server) {
+	const servers = typeof config[key] === "object" && config[key] !== null ? config[key] : {};
+	return {
+		...config,
+		[key]: {
+			...servers,
+			hardfin: server
+		}
+	};
+}
+/** toFilePlan compares what a file holds with what init would write there. */
+function toFilePlan(target, path, content) {
+	const full = join(target, path);
+	const current = existsSync(full) ? readFileSync(full, "utf8") : void 0;
+	if (current === content) return { change: {
+		path,
+		action: "unchanged"
+	} };
+	return {
+		change: {
+			path,
+			action: current === void 0 ? "created" : "updated"
+		},
+		write: () => {
+			mkdirSync(dirname(full), { recursive: true });
+			writeFileSync(full, content);
+		}
+	};
+}
+/** toJSONPlan changes a JSON config, and leaves alone one it cannot read rather than overwrite it. */
+function toJSONPlan(target, path, change) {
+	const full = join(target, path);
+	let config = {};
+	if (existsSync(full)) try {
+		const parsed = JSON.parse(readFileSync(full, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { change: {
+			path,
+			action: "skipped",
+			reason: "it does not hold a JSON object, so it was left alone"
+		} };
+		config = parsed;
+	} catch {
+		return { change: {
+			path,
+			action: "skipped",
+			reason: "it does not hold JSON, so it was left alone"
+		} };
+	}
+	return toFilePlan(target, path, `${JSON.stringify(change(config), null, 2)}\n`);
+}
+/** toFiles lists every file under a folder. */
+function toFiles(directory) {
+	return readdirSync(directory).flatMap((name) => {
+		const path = join(directory, name);
+		return statSync(path).isDirectory() ? toFiles(path) : [path];
+	});
+}
+/** toPackageDirectory finds this package's own folder, which holds the skills and templates it ships. */
+function toPackageDirectory(from = dirname(fileURLToPath(import.meta.url))) {
+	for (let directory = from;; directory = dirname(directory)) {
+		const manifest = join(directory, "package.json");
+		if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@hardfin/cli") return directory;
+		if (dirname(directory) === directory) throw new Error("the @hardfin/cli package folder could not be found, so its skills cannot be copied");
+	}
+}
+//#endregion
 //#region src/auth/device.ts
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 /** The interval a server gives is in seconds, and five more are added on a slow_down. */
@@ -2742,7 +2900,7 @@ async function report(error, occasion, resolved) {
 		const settings = resolved ?? toResolved();
 		const status = settings ? await toStatus(settings) : void 0;
 		const secrets = [settings?.settings.apiKey, settings ? toCredential(settings.settings.issuerUrl)?.refreshToken : void 0];
-		return await (await import("./sentry-CLaeAWNa.js")).send({
+		return await (await import("./sentry-BM9Rvhhy.js")).send({
 			error,
 			occasion,
 			telemetry,
@@ -3528,6 +3686,7 @@ const commands = [
 	loginCommand,
 	logoutCommand,
 	statusCommand,
+	initCommand,
 	...[
 		{
 			name: "asset",
@@ -6330,5 +6489,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted };
 
-//# sourceMappingURL=program-BdRDIa3u.js.map
-//# debugId=6057a656-73c2-55b1-9f09-873e3b83b368
+//# sourceMappingURL=program-DtqGeehp.js.map
+//# debugId=03b49867-f2d5-5a64-af87-e45e530711a1

package/dist/{sentry-CLaeAWNa.js → sentry-BM9Rvhhy.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="853940c3-9e72-566b-ad70-9f043e6aba8d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="35c80804-dcd8-5662-9f00-9c8ff04f286a")}catch(e){}}();
 import { n as toScrubbed } from "./scrub-BN3gyBpR.js";
 import { dirname } from "node:path";
-import { request } from "node:http";
 import { fileURLToPath } from "node:url";
+import { request } from "node:http";
 import { request as request$1 } from "node:https";
 //#region node_modules/@sentry/core/build/esm/debug-build.js
 const DEBUG_BUILD = typeof __SENTRY_DEBUG__ === "undefined" || __SENTRY_DEBUG__;
@@ -3925,7 +3925,7 @@ function trim(arr) {
 	if (start > end) return [];
 	return arr.slice(start, end - start + 1);
 }
-function relative(from, to) {
+function relative$1(from, to) {
 	from = resolve$1(from).slice(1);
 	to = resolve$1(to).slice(1);
 	const fromParts = trim(from.split("/"));
@@ -4001,7 +4001,7 @@ function generateIteratee({ isBrowser, root, prefix }) {
 			}
 		} else if (isWindowsFrame || startsWithSlash) {
 			const filename = isWindowsFrame ? frame.filename.replace(/^[a-zA-Z]:/, "").replace(/\\/g, "/") : frame.filename;
-			frame.filename = `${prefix}${root ? relative(root, filename) : basename$1(filename)}`;
+			frame.filename = `${prefix}${root ? relative$1(root, filename) : basename$1(filename)}`;
 		}
 		return frame;
 	};
@@ -4385,5 +4385,5 @@ function toTags(delivery) {
 //#endregion
 export { send };
 
-//# sourceMappingURL=sentry-CLaeAWNa.js.map
-//# debugId=853940c3-9e72-566b-ad70-9f043e6aba8d
+//# sourceMappingURL=sentry-BM9Rvhhy.js.map
+//# debugId=35c80804-dcd8-5662-9f00-9c8ff04f286a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.0-dev.35",
+    "version": "0.1.0-dev.36",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -24,7 +24,9 @@
     },
     "files": [
         "dist",
-        "!dist/**/*.map"
+        "!dist/**/*.map",
+        "skills",
+        "templates"
     ],
     "engines": {
         "node": ">=20"

package/skills/hardfin-cli/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: hardfin-cli
+description: Read and change records in a Hardfin organization with the Hardfin CLI (`hardfin`) - assets, customers, items, locations, files, ownership and moves. Use when the person asks to look up, import, create, update, move, scrap or archive Hardfin data, to sign in to Hardfin, or to check what the CLI is connected to. Not for writing application code that calls the Hardfin API over HTTP; read https://docs.hardfin.com for that.
+---
+
+# Hardfin CLI
+
+The `hardfin` command reads and changes the records in one Hardfin organization through the
+Hardfin API. Every API operation is a command, named `hardfin <noun> <verb>`.
+
+This skill gives the patterns. The installed CLI is the authority on exact commands and
+flags, so check `--help` before relying on a flag this skill does not show.
+
+## 1. Make sure the CLI is installed
+
+```sh
+hardfin --version || npm install -g @hardfin/cli
+```
+
+It needs Node 20 or later. If `npm install -g` is refused, run commands as
+`npx -y @hardfin/cli <command>` instead.
+
+## 2. Make sure it is signed in
+
+```sh
+hardfin status --offline --json
+```
+
+`credential.kind` is `none` when nobody is signed in. Then sign in one of three ways.
+
+| Situation                                                  | Do this                                          |
+| ---------------------------------------------------------- | ------------------------------------------------ |
+| You run on the person's own machine                        | Run `hardfin login` in the foreground            |
+| You run in a cloud sandbox, away from the person's browser | Run `hardfin login --device`                     |
+| The person gave you an API key                             | Pass `--api-key <key>`, or set `HARDFIN_API_KEY` |
+
+`hardfin login` writes one JSON line on stderr before it waits:
+
+- `{"event": "sign_in_url", "url": …, "browserOpened": …}`: show the person `url`, and say
+  whether a browser tab opened
+- `{"event": "device_code", "userCode": …, "verificationUri": …}`: show the person the code
+  and where to enter it
+
+It then waits up to `waitSeconds` (300) for the person to approve. Give the command that
+long to finish. Do not run it in the background and move on.
+
+Never write an API key into a file in the repository, and never echo it back.
+
+## 3. Find the command
+
+```sh
+hardfin --help                    # the nouns
+hardfin asset --help              # what you can do with assets
+hardfin asset create --help       # every flag that command takes
+hardfin agent-guide               # every command, flag, exit code and error code, as Markdown
+```
+
+| Noun               | Holds                                                                              |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| `asset`            | Physical assets, with their accounting, events, files, moves, ownership and status |
+| `customer`         | The customers assets are sold or leased to                                         |
+| `item`             | The catalogue of item types an asset is an instance of                             |
+| `location`         | Warehouses, sites and their zones                                                  |
+| `file`, `url-link` | Attachments, and links to records elsewhere                                        |
+| `token`            | What the current credential is                                                     |
+| `api`              | Any endpoint directly, when no command fits                                        |
+
+## 4. Keys and IDs
+
+A record has both, and they are not interchangeable.
+
+|     | Looks like                                      | Used for                                                                             |
+| --- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Key | `ast_4f9xk2mq7plr8stz`, `item_V1StGXR8Z5jdHi6B` | The positional argument of `get`, `update` and nested commands                       |
+| ID  | `0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d70`          | A field that points at another record, such as `--customer-id` or `--move assetId=…` |
+
+A list or get answers with both. Take the one the next command asks for.
+
+## 5. Read
+
+```sh
+hardfin asset list --limit 20 --search-query "RX-200"
+hardfin asset get ast_4f9xk2mq7plr8stz
+hardfin customer list --page 2 --limit 100
+```
+
+Output is JSON on stdout whenever stdout is not a terminal, so pipe it to `jq` or parse it.
+A list holds at most 100 records a page. Fetch every page before saying how many there are.
+
+## 6. Change
+
+Before any change:
+
+1. Read the record you are about to change, and work from what it says now
+2. For more than a few records, or anything that deletes, scraps or archives, tell the person
+   what will change and wait for them to agree
+3. Make the change
+4. Read the record back to confirm it
+
+Set fields with one flag each, or send the whole body as JSON with `--input`:
+
+```sh
+hardfin customer create --name "Acme"
+echo '{"name": "Dock 4, north side"}' | hardfin location create --input -
+hardfin asset accounting update ast_4f9xk2mq7plr8stz --unset useful-life
+```
+
+A flag given with `--input` replaces that field of the body. A value with a comma in it
+must go through `--input`, because a `key=value` flag cannot carry one.
+
+## 7. When a command fails
+
+The exit code says what kind of failure it was.
+
+| Exit code | Means                             | Do this                                        |
+| --------- | --------------------------------- | ---------------------------------------------- |
+| 0         | It worked                         |                                                |
+| 1         | The API or the network refused it | Read the error's `code`                        |
+| 2         | The command was called wrongly    | Run the command with `--help` and fix the call |
+| 4         | No usable credential              | Sign in, as in step 2                          |
+
+The error is JSON on stderr. Branch on its `code`, never on the message.
+
+| `code`                                              | Do this                                                          |
+| --------------------------------------------------- | ---------------------------------------------------------------- |
+| `not_signed_in`, `unauthorized`                     | Sign in again                                                    |
+| `invalid_flag`, `missing_flag`, `invalid_arguments` | Read `--help` for that command                                   |
+| `not_found`                                         | Check you passed a key, not an ID, where the command wants a key |
+| `bad_request`, `invalid_request`, `conflict`        | Read `errors`, which names the field                             |
+| `rate_limited`                                      | Wait a minute, then retry once                                   |
+| `unreachable`, `server_error`                       | Tell the person, and include `requestId` if there is one         |
+
+`hardfin agent-guide` lists every code.

package/templates/AGENTS.md

@@ -0,0 +1,25 @@
+## Hardfin
+
+This project works with Hardfin data through the Hardfin CLI, `hardfin`.
+
+| Task                               | Command                                                                      |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| Install                            | `npm install -g @hardfin/cli`, with Node 20 or later                         |
+| Sign in                            | `hardfin login`, or `--device` away from a browser, or set `HARDFIN_API_KEY` |
+| Check what it is connected to      | `hardfin status`                                                             |
+| Find a command                     | `hardfin --help`, then `hardfin <noun> --help`                               |
+| Every command, flag and error code | `hardfin agent-guide`                                                        |
+| The API reference                  | https://docs.hardfin.com                                                     |
+
+Start with the `hardfin-cli` skill in `.agents/skills/hardfin-cli/SKILL.md`.
+
+The Hardfin MCP server, `{{MCP_URL}}`, is configured for Claude Code in `.mcp.json`, for
+Cursor in `.cursor/mcp.json`, and for VS Code in `.vscode/mcp.json`. For Codex, add
+`[mcp_servers.hardfin]` with `url = "{{MCP_URL}}"` to `~/.codex/config.toml`.
+
+Rules:
+
+- Read a record before changing it, and read it back afterwards
+- Ask the person before a bulk change, or anything that deletes, scraps or archives
+- Never write an API key into a file in this repository
+- Branch on an error's `code`, never on its message