Document OpenAI cost repair without package script

doc/DATABASE.md

@@ -39,6 +39,16 @@ pnpm issue-references:backfill -- --company <company-id>
 
 Future issue, comment, and document writes sync references automatically without running the backfill command.
 
+Direct OpenAI metered cost events can also be repaired after migrating when older
+rows have nonzero token usage but no biller/provenance cost. Run the repair in
+dry-run mode first:
+
+```sh
+pnpm --filter @paperclipai/db exec tsx ../../scripts/repair-direct-openai-cost-events.ts --agent-name "Senior Planning Engineer Pro"
+```
+
+Then apply the same scoped command with `--apply` after reviewing the event list.
+
 This mode is ideal for local development and one-command installs.
 
 Docker note: the Docker quickstart image also uses embedded PostgreSQL by default. Persist `/paperclip` to keep DB state across container restarts (see `doc/DOCKER.md`).

package.json

@@ -24,7 +24,6 @@
     "db:generate": "pnpm --filter @paperclipai/db generate",
     "db:migrate": "pnpm --filter @paperclipai/db migrate",
     "issue-references:backfill": "pnpm run preflight:workspace-links && tsx scripts/backfill-issue-reference-mentions.ts",
-    "cost-events:repair-openai": "pnpm --filter @paperclipai/db exec tsx ../../scripts/repair-direct-openai-cost-events.ts",
     "secrets:migrate-inline-env": "tsx scripts/migrate-inline-env-secrets.ts",
     "db:backup": "./scripts/backup-db.sh",
     "paperclipai": "node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts",

scripts/repair-direct-openai-cost-events.test.mjs

@@ -15,10 +15,17 @@ function runHelperCheck(source) {
 }
 
 describe("repair-direct-openai-cost-events", () => {
-  it("starts through the package script and prints help", () => {
+  it("starts through the documented direct command and prints help", () => {
     const output = execFileSync(
       "pnpm",
-      ["cost-events:repair-openai", "--", "--help"],
+      [
+        "--filter",
+        "@paperclipai/db",
+        "exec",
+        "tsx",
+        "../../scripts/repair-direct-openai-cost-events.ts",
+        "--help",
+      ],
       { cwd: repoRoot, encoding: "utf8" },
     );
 

scripts/repair-direct-openai-cost-events.ts

@@ -469,8 +469,8 @@ function printHelp() {
   console.log(`Repair direct OpenAI metered cost_events rows with nonzero tokens and missing cost/provenance.
 
 Usage:
-  pnpm cost-events:repair-openai -- --agent-name "Senior Planning Engineer Pro"
-  pnpm cost-events:repair-openai -- --agent-name "Senior Planning Engineer Pro" --apply
+  pnpm --filter @paperclipai/db exec tsx ../../scripts/repair-direct-openai-cost-events.ts --agent-name "Senior Planning Engineer Pro"
+  pnpm --filter @paperclipai/db exec tsx ../../scripts/repair-direct-openai-cost-events.ts --agent-name "Senior Planning Engineer Pro" --apply
 
 Options:
   --apply              Persist repairs. Omit for dry-run.