diff --git a/packages/gittensory-miner/README.md b/packages/gittensory-miner/README.md
index 817df5b7de..4959b3ec47 100644
--- a/packages/gittensory-miner/README.md
+++ b/packages/gittensory-miner/README.md
@@ -28,6 +28,10 @@ The package also includes an append-only governor decision ledger: `initGovernor
 persist structured allow/deny/throttle/kill-switch outcomes in local SQLite for contributor audit. Insert-only —
 no enforcement wiring yet. (#2328)
 
+The package also includes a local soft-claim ledger: `openClaimLedger` / `claimIssue` / `releaseClaim` /
+`listActiveClaims` persist which issues this miner instance has claimed on this machine. The table is local
+bookkeeping only — duplicate winners are adjudicated elsewhere via `@jsonbored/gittensory-engine`. (#2291)
+
 ## Install
 
 See [`docs/miner-goal-spec.md`](docs/miner-goal-spec.md) for the `.gittensory-miner.yml` field reference and [`.gittensory-miner.yml.example`](../../.gittensory-miner.yml.example) at the repo root.
diff --git a/test/unit/miner-claim-ledger-readme.test.ts b/test/unit/miner-claim-ledger-readme.test.ts
new file mode 100644
index 0000000000..c58b547b22
--- /dev/null
+++ b/test/unit/miner-claim-ledger-readme.test.ts
@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const readmePath = join(process.cwd(), "packages/gittensory-miner/README.md");
+
+describe("gittensory-miner claim ledger README (#2291)", () => {
+  it("documents the foundation claim ledger API surface", () => {
+    const readme = readFileSync(readmePath, "utf8");
+    expect(readme).toContain("openClaimLedger");
+    expect(readme).toContain("claimIssue");
+    expect(readme).toContain("releaseClaim");
+    expect(readme).toContain("listActiveClaims");
+    expect(readme).toContain("bookkeeping only");
+    expect(readme).toContain("@jsonbored/gittensory-engine");
+  });
+});