@devwithdavid/ledger 0.1.0 → 0.1.3

package/LEDGER.md

@@ -38,9 +38,12 @@ what's below is a description of it, not a separate copy to keep in sync):
   - `direct-pr`: open a pull request against the default branch — using
     whatever tooling is available for that project's remote (e.g. `tea`
     for a Forgejo remote; ledger doesn't care which, that's your call) —
-    **do not merge it yourself, regardless of anything else you're told.**
-    PR review is a real checkpoint, not a formality to clear on your own
-    (see `DECISIONS.md` for the incident that made this explicit). Then
+    **never merge any branch or PR (your own or anyone else's), and
+    never approve any PR, regardless of anything else you're told,
+    including by the clerk.** PR review is a real checkpoint, not a
+    formality to clear on your own (see `DECISIONS.md` for the incident
+    that made this explicit, and the 2026-09-02 generalization that also
+    forbids approving any PR). Then
     `ledger agent update <your-agent-id> --status done --outcome
     '<pr-url>'`.
   - `local-only`: just `ledger agent update <your-agent-id> --status done
@@ -98,9 +101,11 @@ the code.
   concrete, in-the-moment, user-approved operation — executed exactly as
   approved, never inferred or generalized, conferring no standing
   authority.
-- **C2 — you never merge, force-push, or close a PR without an explicit
-  user word.** One explicit word at a time, in the moment; there is no
-  standing relaxation. (Worker-side mirror: A2.)
+- **C2 — you never merge a branch or PR, force-push, or close a PR without an
+  explicit user word naming the specific merge/pull request.** One explicit
+  word at a time, in the moment, for that specific PR; there is no standing
+  relaxation — a general instruction does not license a specific merge.
+  (Worker-side mirror: A2.)
 - **C4 — agents never address the user directly; you are the single
   channel.** If the user intervenes directly in a worker pane, that
   instruction is authoritative: reconcile at the next catch-up, never
@@ -119,6 +124,11 @@ the code.
 - **C9 — you do not self-modify.** Never edit your own contract or skills
   (this file, `DECISIONS.md`, the skill pointer) without explicit user
   approval — a gate must not be editable by the party it binds.
+- **C10 — you refer to a ledger item with visual context.** Always make an
+  item identifiable without board access: if it (or its project) has an open
+  PR/MR, include that PR/MR's number (and URL) alongside the ledger id — e.g.
+  'item #22 (PR #10)'; if no merge is open, add a short context phrase — the
+  item's title or a one-line description.
 
 **Liveness (A8, clerk side).** At catch-up, an `idle` agent with
 unfinished work is suspect — it may have died on a usage limit. `catchup`

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 David Kartik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -13,7 +13,8 @@ a general product.
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org) ≥ 20
+- [Node.js](https://nodejs.org) ≥ 22.13 (needed for the built-in
+  `node:sqlite` storage driver — see [`DECISIONS.md`](./DECISIONS.md))
 - [herdr](https://herdr.dev) installed and running — the terminal
   workspace/pane manager. `herdr status` should show a running server.
 - [treehouse](https://github.com/kunchenguid/treehouse) installed — isolated
@@ -24,53 +25,64 @@ a general product.
 ## Install
 
 ```sh
-git clone <this-repo> ledger   # or you already have it locally
-cd ledger
-npm install
-npm run build
+npm install -g @devwithdavid/ledger
 ```
 
-**Make the CLI available.** Either:
+That's the whole install. The package ships pre-built, and the global
+install puts `ledger` on your PATH — no build step, no separate linking
+step: the `ledger` binary lands on PATH with the install itself.
 
-```sh
-npm link          # puts `ledger` on PATH globally
-```
-
-or invoke it directly / alias it:
-
-```sh
-node dist/cli/index.js ...
-```
-
-**Link the watcher plugin into herdr** — this is what keeps agent status
-current automatically as dispatched agents work, without any polling:
+**Finish the setup with `ledger init`** — the single post-install step:
 
 ```sh
-herdr plugin link .
+ledger init
 ```
 
-This registers `herdr-plugin.toml`, so herdr invokes `dist/plugin/watcher.js`
-whenever a pane's detected agent state changes. It's local and reversible:
-`herdr plugin unlink ledger` removes it. Re-run `npm run build` after any
-change to `src/plugin/watcher.ts` — herdr always invokes whatever's
-currently in `dist/`.
+Run it once after installing. It does four things, printing a status line
+for each as it goes:
+
+1. **Verifies `herdr` and `treehouse` are on your PATH.** If either is
+   missing it exits without doing anything else, with an install pointer
+   for each missing tool (herdr: <https://herdr.dev>, treehouse:
+   <https://github.com/kunchenguid/treehouse>).
+2. **Creates the ledger database** at `$LEDGER_HOME/ledger.db` if it
+   doesn't exist yet. An existing store is never reset or rewritten.
+3. **Links the herdr watcher plugin**: runs `herdr plugin link` on the
+   installed package's root, where `herdr-plugin.toml` ships. That's what
+   keeps agent status current automatically as dispatched agents work,
+   without any polling — herdr invokes `dist/plugin/watcher.js` whenever a
+   pane's detected agent state changes.
+4. **Installs the clerk skill** at `~/.agents/skills/ledger/SKILL.md` from
+   the copy bundled with this install, symlinking it into
+   `~/.claude/skills/ledger` and `~/.pi/agent/skills/ledger` so either tool
+   picks it up. See "Starting a clerk session" below for what the skill
+   does.
+
+It's idempotent — re-running it (for example after `npm update -g
+@devwithdavid/ledger`) is safe: the store is only created if missing,
+re-linking the plugin leaves herdr's registration unchanged, the skill
+file is always re-synced from the bundled copy, and an existing symlink is
+only touched if it doesn't already point at the right place. The plugin
+link is local and reversible: `herdr plugin unlink ledger` removes it.
+herdr always runs whatever's currently in the installed package's `dist/`,
+so `npm update -g @devwithdavid/ledger` picks up new releases (including
+watcher changes) on the next event.
 
 ## Starting a clerk session
 
 You don't run `ledger` commands yourself day to day — you talk to **the
-clerk** (a Claude Code or Pi session), and it runs them on your behalf. A
-`ledger` skill is installed at `~/.agents/skills/ledger` (symlinked into
-both `~/.claude/skills/` and `~/.pi/agent/skills/`) so either tool can pick
-it up — it loads only when you actually ask for ledger-related work
-(register a project, dispatch an agent, check status, ...), not on every
-unrelated session.
+clerk** (a Claude Code or Pi session), and it runs them on your behalf.
+`ledger init` (step 4 above) installs a `ledger` skill so either Claude
+Code or Pi can pick it up — it loads only when you actually ask for
+ledger-related work (register a project, dispatch an agent, check status,
+...), not on every unrelated session.
 
 The skill itself carries no machine-specific path: it just tells the clerk
 to run `ledger docs`, which prints `LEDGER.md` by resolving it relative to
 wherever `ledger` is actually installed (works correctly through the
 `npm link` symlink too — proven live, see `DECISIONS.md`). That's what
-makes the skill portable to a fresh machine as-is: install `ledger` there
-per this README, and the skill works with no edits.
+makes the skill portable to a fresh machine as-is: run `ledger init` there
+and the skill works with no edits.
 
 ## Quick start (what the clerk actually runs)
 
@@ -106,9 +118,9 @@ simply never fires.
 
 | Doc | What's in it |
 |---|---|
-| [`DESIGN.md`](./DESIGN.md) | The philosophy, why this exists, and the original schema/flow brief |
+| [`DESIGN.md`](./DESIGN.md) | The philosophy, why this exists, and the original schema/flow brief (in the git repo — public mirror coming soon) |
 | [`LEDGER.md`](./LEDGER.md) | The operational reference — full CLI surface, what the first clerk is responsible for vs. what a dispatched agent is told, and how to extend this safely |
-| [`DECISIONS.md`](./DECISIONS.md) | Running log of implementation decisions and why, including things verified live against the real herdr/treehouse binaries (some of herdr's actual behavior differs from its docs — see this file before assuming a documented API shape is accurate) |
+| [`DECISIONS.md`](./DECISIONS.md) | Running log of implementation decisions and why, including things verified live against the real herdr/treehouse binaries — some of herdr's actual behavior differs from its docs, so read this before assuming a documented API shape is accurate (in the git repo — public mirror coming soon) |
 
 ## Extending
 
@@ -125,11 +137,15 @@ genuinely does belong in core.
 
 ## Example extension
 
-[`ledger-notify`](../ledger-notify) *(sibling repo, once built)* — a
-desktop-notification plugin that watches for agents going `blocked` or
-`done`, built entirely outside this repo as a worked example of the
-extension model. See [`EXTENSION-EXAMPLE-BRIEF.md`](./EXTENSION-EXAMPLE-BRIEF.md)
-for the implementation brief.
+`ledger-notify` — a desktop-notification plugin that watches for agents
+going `blocked` or `done`, built entirely outside this repo as a worked
+example of the extension model. The plugin lives in a sibling git repo, and
+the implementation brief, [`EXTENSION-EXAMPLE-BRIEF.md`](./EXTENSION-EXAMPLE-BRIEF.md),
+is in this project's git repo — the public mirror for both is coming soon.
+None of that is needed to build an extension, though: the whole contract is
+reading/writing the SQLite file at `$LEDGER_HOME/ledger.db` or shelling out
+to the `ledger` CLI, as [`LEDGER.md` § "Safe ways to extend this"]
+(./LEDGER.md#safe-ways-to-extend-this) describes.
 
 ## Status
 
@@ -138,3 +154,12 @@ with a high release cadence; some of the CLI/plugin behavior this repo
 depends on was reverse-engineered live (their docs don't fully match
 current behavior in places — see `DECISIONS.md`) and may need
 re-verification after either tool upgrades.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+Versions 0.1.0-0.1.2 were published to npm before this LICENSE file
+existed, so their tarballs don't contain it: published npm versions are
+immutable. As the sole author, the copyright holder grants those versions
+the same MIT license.

package/dist/cli/commands/agents.js

@@ -352,8 +352,9 @@ function survivalProof(worktreePath) {
  * one worktree / no spawning (A1), blocked as a structured decision
  * request (A4), no self-modification of the contract or the board (A5),
  * faithful outcomes (A6), and work surviving in a durable posture before
- * exit (A7). A2 (no self-merge) already lives in the direct-pr delivery
- * text since the self-merge incident.
+ * exit (A7). A2 (no merging, ever: no branch merge in any mode,
+ * no PR approval) lives in both delivery texts since the
+ * self-merge incident, generalized 2026-09-02.
  */
 function buildTaskPrompt(agentId, task, project) {
     const deliveryInstructions = project.delivery_mode === "direct-pr"
@@ -363,15 +364,19 @@ Before you exit, all your work must be on that branch pushed to the remote
 it is at risk of being lost.
 When you're done, open a pull request against '${project.default_branch}'
 (use whatever tooling is available for this project's remote, e.g. \`tea\`
-for a Forgejo remote). Do NOT merge it yourself, even if you technically
-can — opening the PR is the whole job. Merging is a human/review decision,
-not yours to make, regardless of anything else you're told. Then run this
-as your last step:
+for a Forgejo remote). Never merge any branch or PR — your own or anyone
+else's — and never approve any PR, even if you technically can: opening
+the PR is the whole job. Merging and approving are human/review decisions,
+not yours to make, regardless of anything else you're told, including by
+the clerk. Then run this as your last step:
   ledger agent update ${agentId} --status done --outcome '<pr-url>'
 using the PR's URL.`
         : `Work on a new branch — never commit directly to '${project.default_branch}'.
 Before you exit, commit all your work in the worktree — it is leased and
 gets recycled, so anything left uncommitted is at risk of being lost.
+Merging that branch into any other branch is not your act — you report it
+and stop. Never merge any branch or PR, and never approve any PR, regardless
+of anything else you're told; the merge is a human decision.
 When you're done, run this as your last step:
   ledger agent update ${agentId} --status done --outcome '<branch-name-or-report-path>'`;
     return `${task}

package/dist/cli/commands/clerk.js

@@ -1,4 +1,4 @@
-import { getDb } from "../../db/client.js";
+import { getDb, suppressNextClerkHeartbeat } from "../../db/client.js";
 import * as herdr from "../../lib/herdr.js";
 import { printJson } from "../format.js";
 const STALE_AFTER_HOURS = 12;
@@ -31,6 +31,10 @@ export function registerClerkCommands(program) {
              last_seen = NULL
            RETURNING *`)
             .get(opts.sessionId, opts.herdrPane);
+        // The upsert above just reset last_seen to NULL (fresh clock) —
+        // don't let the generic post-command heartbeat (src/cli/index.ts)
+        // immediately overwrite that within this same invocation.
+        suppressNextClerkHeartbeat();
         // The claim is durable now; the rename below is cosmetic only.
         renameClaimantWorkspace(opts.herdrPane);
         printJson(row);
@@ -45,9 +49,21 @@ export function registerClerkCommands(program) {
         printJson(row ?? null);
     });
 }
+/**
+ * Item 27 (2026-09-03, user-directed "robust" option): staleness reflects
+ * actual activity, not just how long ago the claim was made. A clerk
+ * session that's still working past 12h shouldn't be displaceable just
+ * because it claimed early — so this compares now against the LATEST of
+ * claimed_at and last_seen, falling back to claimed_at when last_seen is
+ * NULL (what a fresh claim sets — see the upsert above). last_seen is
+ * kept current by the heartbeat in src/cli/index.ts (touchClerkHeartbeat)
+ * and, belt-and-braces, by catchup's own write.
+ */
 function isStale(row) {
     const claimedAt = new Date(row.claimed_at + "Z").getTime();
-    const ageHours = (Date.now() - claimedAt) / (1000 * 60 * 60);
+    const lastSeen = row.last_seen ? new Date(row.last_seen + "Z").getTime() : claimedAt;
+    const lastActivity = Math.max(claimedAt, lastSeen);
+    const ageHours = (Date.now() - lastActivity) / (1000 * 60 * 60);
     return ageHours > STALE_AFTER_HOURS;
 }
 const CLERK_WORKSPACE_LABEL = "clerk";

package/dist/cli/commands/init.js

@@ -0,0 +1,192 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, readlinkSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getDb, ledgerHome } from "../../db/client.js";
+// This file compiles to dist/cli/commands/init.js, three levels under the
+// package root — resolve the package root relative to *this running code's
+// own location* rather than the cwd (same approach as docs.ts), so it works
+// from any invocation directory, in a dev checkout and in an npm install.
+// The herdr plugin manifest (herdr-plugin.toml) lives at the package root,
+// so that directory is what gets linked.
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+// Step 4's bundled skill template: a hand-authored `~/.agents/skills/ledger`
+// (cross-agent skill tree; see DECISIONS.md "Clerk bootstrapping") existed
+// on one machine only and was never captured as a reproducible setup step —
+// a second machine's clerk session never loaded LEDGER.md as a result and
+// spent a whole session unaware of its own governance gates. This ships the
+// real skill content as a package asset instead, resolved the same way as
+// the herdr plugin root above, so `init` can (re-)install it anywhere.
+const SKILL_TEMPLATE_PATH = join(PACKAGE_ROOT, "skills/ledger/SKILL.md");
+const AGENTS_SKILL_DIR = join(homedir(), ".agents/skills/ledger");
+const AGENTS_SKILL_FILE = join(AGENTS_SKILL_DIR, "SKILL.md");
+// Deliberately outside this repo (same reasoning as the skill itself living
+// outside it) — per-tool skill directories are symlinks into the shared
+// `~/.agents/skills/<name>` tree, so any coding agent that understands that
+// convention picks it up with zero ledger-specific config of its own.
+const SKILL_SYMLINK_TARGETS = [join(homedir(), ".claude/skills/ledger"), join(homedir(), ".pi/agent/skills/ledger")];
+// Install pointers for the pre-check:
+//   herdr: derived from the tool's own npm package metadata, verified
+//   2026-09-03 — NOT guessed: npm view herdr homepage -> https://herdr.dev
+//   treehouse: npm's 'treehouse' is an unrelated React package (name
+//   squat); the required tool is kunchenguid's git-worktree tool
+//   (installed binary v2.3.0) — URL per user confirmation 2026-09-04,
+//   not npm metadata.
+// (The README's prerequisites section carries the same treehouse URL —
+// the two now agree; see DECISIONS.md for the resolution.)
+const DOCS = {
+    herdr: "https://herdr.dev",
+    treehouse: "https://github.com/kunchenguid/treehouse",
+};
+const REQUIRED_TOOLS = ["herdr", "treehouse"];
+/**
+ * PATH lookup for a required tool: the first $PATH directory that contains
+ * an executable FILE named <tool> wins. A plain lookup, deliberately not a
+ * version/capability probe — the pre-check's job is to fail fast with a
+ * per-tool install pointer, not to audit the tool (item 30).
+ */
+function findOnPath(tool) {
+    const dirs = (process.env["PATH"] ?? "").split(delimiter).filter((d) => d.length > 0);
+    for (const dir of dirs) {
+        const candidate = join(dir, tool);
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // not here (or not executable) — keep looking
+        }
+    }
+    return undefined;
+}
+/**
+ * Step 4 helper: symlink one per-tool skill path to AGENTS_SKILL_DIR,
+ * creating its parent directory if needed. Idempotent: a symlink already
+ * pointing at the right place is a silent no-op; a pre-existing real
+ * file/directory (or a symlink to somewhere else) is left untouched with a
+ * warning rather than clobbered — this must never destroy something a user
+ * put there on purpose.
+ */
+function linkSkill(linkPath) {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    if (existsSync(linkPath)) {
+        let currentTarget;
+        try {
+            currentTarget = readlinkSync(linkPath);
+        }
+        catch {
+            // Exists but isn't a symlink at all.
+        }
+        if (currentTarget === AGENTS_SKILL_DIR) {
+            console.log(`✓ ${linkPath} already links to ${AGENTS_SKILL_DIR}`);
+        }
+        else {
+            console.log(`Warning: ${linkPath} already exists and is not a symlink to ${AGENTS_SKILL_DIR} ` +
+                `(${currentTarget ?? "a real file/directory"}) — left untouched. Remove it and ` +
+                `re-run 'ledger init' to relink.`);
+        }
+        return;
+    }
+    symlinkSync(AGENTS_SKILL_DIR, linkPath);
+    console.log(`✓ linked ${linkPath} -> ${AGENTS_SKILL_DIR}`);
+}
+/**
+ * The single post-install step (item 30, user-directed): the README's
+ * install section no longer tells users to hand-run `herdr plugin link
+ * <path>` — this command does that, transparently.
+ *
+ * Steps, in order:
+ *  1. Pre-check herdr AND treehouse on PATH before touching anything. If
+ *     one or both are missing, exit non-zero with a per-tool install
+ *     pointer (both in one error when both are missing) — no store is
+ *     created and no link is attempted.
+ *  2. Ensure the ledger store, reusing getDb() (it creates $LEDGER_HOME
+ *     and opens/migrates ledger.db; an existing store is only opened —
+ *     never reset or rewritten). Prints the path created or found.
+ *  3. Link the herdr plugin: `herdr plugin link <package root>`.
+ *     Verified live against herdr 0.7.5 (2026-09-03): re-linking a path
+ *     that's already linked exits 0, prints its `plugin_linked` JSON
+ *     result, and leaves herdr's plugin registry file byte-identical —
+ *     so this step is idempotent and the command is safe to re-run (e.g.
+ *     after `npm update -g @devwithdavid/ledger`). A non-zero exit (for
+ *     instance an already-linked different path) is surfaced: herdr's
+ *     own output is printed, the command fails, and the user resolves it
+ *     (`herdr plugin unlink ledger` first).
+ *  4. Install/update the clerk skill: write the bundled
+ *     `skills/ledger/SKILL.md` to `~/.agents/skills/ledger/SKILL.md`
+ *     (always overwritten from the bundled copy, so re-running `init`
+ *     after an upgrade re-syncs it), then symlink `~/.claude/skills/ledger`
+ *     and `~/.pi/agent/skills/ledger` to it if not already correctly
+ *     linked. Found missing on a second machine (see DECISIONS.md) —
+ *     the skill's *content* was portable, but nothing ever installed it.
+ *
+ * Every step prints an explicit status line (✓) naming what was done and
+ * the path/URL involved, so the user sees exactly what `ledger init` did.
+ */
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("one-time post-install setup: verify herdr and treehouse are on PATH, " +
+        "create the ledger store if missing, link the herdr watcher plugin, " +
+        "install the clerk skill (idempotent — safe to re-run)")
+        .action(() => {
+        // 1. Pre-check both required tools up front, before any side effect.
+        for (const tool of REQUIRED_TOOLS) {
+            if (findOnPath(tool)) {
+                console.log(`✓ ${tool} found on PATH`);
+            }
+        }
+        const missing = REQUIRED_TOOLS.filter((tool) => !findOnPath(tool));
+        if (missing.length > 0) {
+            // All missing tools are reported in one error, per the exact
+            // message format "<tool> not found on PATH - install it first:
+            // <docs URL>" (item 30). The CLI entry prints this as a single
+            // `Error:` line and exits non-zero.
+            throw new Error(missing.map((tool) => `${tool} not found on PATH - install it first: ${DOCS[tool]}`).join("; "));
+        }
+        // 2. Ensure the store — reuse the existing getDb() machinery (it
+        //    creates the home dir and migrates on open). Never resets or
+        //    rewrites an existing store.
+        const storePath = join(ledgerHome(), "ledger.db");
+        const alreadyThere = existsSync(storePath);
+        getDb();
+        console.log(`✓ ledger store ${alreadyThere ? "found at" : "created at"} ${storePath}`);
+        // 3. Link the herdr plugin from the package root.
+        const res = spawnSync("herdr", ["plugin", "link", PACKAGE_ROOT], { encoding: "utf8" });
+        if (res.error || res.status !== 0) {
+            const out = res.stdout ?? "";
+            const err = res.stderr ?? "";
+            if (out.trim())
+                process.stderr.write(`${out.trimEnd()}\n`);
+            if (err.trim())
+                process.stderr.write(`${err.trimEnd()}\n`);
+            const detail = res.error ? res.error.message : `exit ${res.status}`;
+            throw new Error(`herdr plugin link failed (${detail})`);
+        }
+        // Print herdr's own result so a fresh link and a no-op re-link are
+        // both visible, then our own status line naming the linked path.
+        const out = res.stdout ?? "";
+        if (out.trim())
+            console.log(out.trimEnd());
+        console.log(`✓ herdr plugin linked from ${PACKAGE_ROOT}`);
+        // 4. Install/update the clerk skill from the bundled template, then
+        //    link it into every known per-tool skill tree.
+        let skillTemplate;
+        try {
+            skillTemplate = readFileSync(SKILL_TEMPLATE_PATH, "utf8");
+        }
+        catch {
+            throw new Error(`couldn't read the bundled skill template at ${SKILL_TEMPLATE_PATH} ` +
+                `— is this a complete ledger install, not a partial copy?`);
+        }
+        const skillAlreadyThere = existsSync(AGENTS_SKILL_FILE);
+        mkdirSync(AGENTS_SKILL_DIR, { recursive: true });
+        writeFileSync(AGENTS_SKILL_FILE, skillTemplate);
+        console.log(`✓ clerk skill ${skillAlreadyThere ? "updated at" : "installed at"} ${AGENTS_SKILL_FILE}`);
+        for (const linkPath of SKILL_SYMLINK_TARGETS) {
+            linkSkill(linkPath);
+        }
+    });
+}

package/dist/cli/index.js

@@ -1,18 +1,47 @@
 #!/usr/bin/env node
+// Must come first — see the comment in suppress-experimental-warnings.ts.
+import "./suppress-experimental-warnings.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { registerAgentCommands } from "./commands/agents.js";
 import { registerCatchupCommand } from "./commands/catchup.js";
 import { registerClerkCommands } from "./commands/clerk.js";
 import { registerDocsCommand } from "./commands/docs.js";
 import { registerEventCommands } from "./commands/events.js";
+import { registerInitCommand } from "./commands/init.js";
 import { registerProjectCommands } from "./commands/projects.js";
 import { registerRoadmapCommands } from "./commands/roadmap.js";
+import { touchClerkHeartbeat } from "../db/client.js";
+// The version is derived from the package's own package.json at runtime —
+// package.json is the ONLY source of it. This entry compiles to
+// dist/cli/index.js, two levels below the package root, so resolve the
+// file relative to *this running code's own location* rather than the cwd
+// (same approach as docs.ts): that works from any invocation directory, in
+// a dev checkout, and in an npm install (the npm tarball carries
+// package.json at its root — verified in the 0.1.2 tarball). Publishing
+// bumps package.json, and since this reads package.json, the two can never
+// desync — a literal here is a second copy and is forbidden.
+// Graceful degradation: if the file can't be read or parsed (a corrupt
+// install), report "unknown" instead of throwing — a version query must
+// never crash the CLI (item 30, DECISIONS.md).
+function packageVersion() {
+    const pkgJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    try {
+        const parsed = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 const program = new Command();
 program
     .name("ledger")
     .description("Durable state store for a personal agent-orchestration workflow " +
     "(projects, roadmap, dispatched agents, events).")
-    .version("0.1.0");
+    .version(packageVersion());
 registerProjectCommands(program);
 registerRoadmapCommands(program);
 registerAgentCommands(program);
@@ -20,11 +49,16 @@ registerEventCommands(program);
 registerClerkCommands(program);
 registerCatchupCommand(program);
 registerDocsCommand(program);
+registerInitCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);
+    // Item 27: heartbeat after the command has run its own logic — see
+    // touchClerkHeartbeat's doc comment for why it can't live in getDb().
+    touchClerkHeartbeat();
 }
 catch (err) {
+    touchClerkHeartbeat();
     if (err.code?.startsWith("commander.")) {
         process.exit(err.exitCode ?? 1);
     }

package/dist/cli/suppress-experimental-warnings.js

@@ -0,0 +1,23 @@
+/**
+ * node:sqlite is still experimental (unflagged since Node 22.13.0/23.4.0)
+ * and prints an ExperimentalWarning the moment it's first imported.
+ * Suppress only that one warning — everything else still reaches stderr
+ * as normal.
+ *
+ * Must be the *first* import in the CLI entry point: ES module static
+ * imports are hoisted and executed before the importing module's own
+ * top-level body, so this override has to be its own dependency-free
+ * module, imported before anything that (transitively) imports
+ * "node:sqlite" — otherwise the warning fires before the override is
+ * installed.
+ */
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...args) => {
+    const type = typeof args[0] === "string" ? args[0] : args[0]?.type;
+    const message = warning instanceof Error ? warning.message : warning;
+    if (type === "ExperimentalWarning" && typeof message === "string" && message.includes("SQLite")) {
+        return;
+    }
+    return originalEmitWarning(warning, ...args);
+});
+export {};

package/dist/db/client.js

@@ -1,8 +1,16 @@
-import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { migrations } from "./migrations/index.js";
+// node:sqlite emits its one-time ExperimentalWarning as soon as the module
+// is *loaded* — a static `import ... from "node:sqlite"` here would trigger
+// it during ESM's graph-link phase, before the CLI entry point's warning
+// filter (src/cli/suppress-experimental-warnings.ts) has run. Loading it
+// via `require` instead defers that load to normal, in-order statement
+// execution, so the filter is already installed by the time it fires.
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require("node:sqlite");
 export function ledgerHome() {
     return process.env["LEDGER_HOME"] ?? join(homedir(), ".ledger");
 }
@@ -16,12 +24,59 @@ export function getDb() {
     const home = ledgerHome();
     mkdirSync(home, { recursive: true });
     mkdirSync(projectsDir(), { recursive: true });
-    db = new Database(join(home, "ledger.db"));
-    db.pragma("journal_mode = WAL");
-    db.pragma("foreign_keys = ON");
+    db = new DatabaseSync(join(home, "ledger.db"));
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
     applyMigrations(db);
     return db;
 }
+let suppressNextHeartbeat = false;
+/**
+ * `clerk claim`'s own upsert resets last_seen to NULL on every claim,
+ * fresh or forced — "a fresh claim starts a fresh clock" (DECISIONS.md,
+ * item 27). Without this, the generic post-command heartbeat below would
+ * immediately overwrite that NULL with `now` before the same invocation
+ * ends, erasing the reset the claim command just made. Call this right
+ * after the upsert; it's consumed (one-shot) by this invocation's own
+ * touchClerkHeartbeat() call in src/cli/index.ts.
+ */
+export function suppressNextClerkHeartbeat() {
+    suppressNextHeartbeat = true;
+}
+/**
+ * Item 27 (activity-based clerk liveness, 2026-09-03 user decision):
+ * bump first_clerk.last_seen so staleness reflects real activity, not
+ * just time-since-claim. Called once per CLI invocation, from
+ * src/cli/index.ts, AFTER the invoked command's own logic has run —
+ * deliberately not from inside getDb() itself. `clerk claim` reads
+ * first_clerk to decide whether the *existing* claim is stale before it
+ * does anything else; if a heartbeat fired on that same getDb() call it
+ * would stamp last_seen = now on the very row being checked (which may
+ * belong to a different, possibly-dead session) and erase the staleness
+ * the check exists to detect. Running the heartbeat after the command
+ * body closes that gap.
+ *
+ * A no-op if the store was never opened this invocation (e.g. --help),
+ * there's no first_clerk row yet (0 rows updated), or the invocation was
+ * itself a `clerk claim` (see suppressNextClerkHeartbeat). Never throws:
+ * a heartbeat failure must not fail the command it's riding on, so any
+ * error is only warned to stderr.
+ */
+export function touchClerkHeartbeat() {
+    if (suppressNextHeartbeat) {
+        suppressNextHeartbeat = false;
+        return;
+    }
+    if (!db)
+        return;
+    try {
+        db.prepare("UPDATE first_clerk SET last_seen = datetime('now') WHERE id = 1").run();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Warning: clerk heartbeat failed: ${msg}`);
+    }
+}
 function applyMigrations(database) {
     database.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
@@ -39,10 +94,17 @@ function applyMigrations(database) {
         return;
     const insertMigration = database.prepare("INSERT INTO schema_migrations (version, name) VALUES (?, ?)");
     for (const migration of pending) {
-        const run = database.transaction(() => {
+        // node:sqlite's DatabaseSync has no built-in `.transaction()` helper
+        // (unlike better-sqlite3) — drive BEGIN/COMMIT/ROLLBACK explicitly.
+        database.exec("BEGIN");
+        try {
             database.exec(migration.sql);
             insertMigration.run(migration.version, migration.name);
-        });
-        run();
+            database.exec("COMMIT");
+        }
+        catch (err) {
+            database.exec("ROLLBACK");
+            throw err;
+        }
     }
 }

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@devwithdavid/ledger",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Personal agent-orchestration ledger: SQLite state store, CLI, and herdr watcher plugin.",
+  "license": "MIT",
+  "repository": "https://yggdrasil.thekartiks.com/chewbakartik/ledger.git",
   "type": "module",
   "bin": {
     "ledger": "dist/cli/index.js"
   },
   "files": [
+    "LICENSE",
     "dist",
     "LEDGER.md",
     "README.md",
-    "herdr-plugin.toml"
+    "herdr-plugin.toml",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -19,14 +23,12 @@
     "prepare": "tsc -p tsconfig.json"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "dependencies": {
-    "better-sqlite3": "^11.10.0",
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.11",
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"
   }

package/skills/ledger/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ledger
+description: Act as the first clerk for `ledger`, a personal SQLite-backed agent-orchestration tool (herdr + treehouse). Use when asked to register a ledger project, break work into a roadmap, dispatch a coding agent via ledger, check on dispatched agents, run a ledger catch-up, or otherwise manage state via the `ledger` CLI.
+---
+
+Run `ledger docs` and read its full output before doing anything else in
+this role — that prints the complete clerk/agent reference (CLI surface,
+what the first clerk is responsible for, what a dispatched agent is told).
+
+This skill is intentionally just a pointer, not a copy of that content, so
+it can't drift out of sync with the real CLI, and carries no machine-
+specific path — `ledger docs` resolves its own reference doc relative to
+wherever the `ledger` package is actually installed on this machine.
+
+If `ledger` isn't found on PATH, it isn't installed here yet: find the
+`ledger` project's own repo (or ask the user where it's cloned) and follow
+its `README.md` install steps first.