docs(scripts): point script headers and runbooks at compiled dist

backend/scripts/backfill-byo-host-stamp.ts

@@ -30,8 +30,8 @@
  * an explicit host are never touched.
  *
  * Usage:
- *   npx ts-node backend/scripts/backfill-byo-host-stamp.ts          # dry run
- *   npx ts-node backend/scripts/backfill-byo-host-stamp.ts --apply
+ *   cd backend && node dist/scripts/backfill-byo-host-stamp.js          # dry run
+ *   cd backend && node dist/scripts/backfill-byo-host-stamp.js --apply
  */
 
 /* eslint-disable no-console */

backend/scripts/backfill-explicit-runtime-identity.ts

@@ -26,8 +26,8 @@
  * Rows already carrying an explicit runtimeType AND host are untouched.
  *
  * Usage:
- *   npx ts-node backend/scripts/backfill-explicit-runtime-identity.ts
- *   npx ts-node backend/scripts/backfill-explicit-runtime-identity.ts --apply
+ *   cd backend && node dist/scripts/backfill-explicit-runtime-identity.js
+ *   cd backend && node dist/scripts/backfill-explicit-runtime-identity.js --apply
  *   ... --include-inactive     # default is ACTIVE only; see #949's reasoning
  */
 

backend/scripts/cleanup-ghost-pod-members.ts

@@ -32,8 +32,8 @@
  * `--apply` to write. Run it on the operator's word, never inline in a deploy.
  *
  * Usage:
- *   ts-node backend/scripts/cleanup-ghost-pod-members.ts           # report
- *   ts-node backend/scripts/cleanup-ghost-pod-members.ts --apply   # delete
+ *   cd backend && node dist/scripts/cleanup-ghost-pod-members.js           # report
+ *   cd backend && node dist/scripts/cleanup-ghost-pod-members.js --apply   # delete
  */
 
 import mongoose from 'mongoose';

backend/scripts/dedupe-agent-display-names.ts

@@ -26,8 +26,8 @@
  *     keys; only displayName (the human-facing label) is rewritten.
  *   - `username` — DB-unique already; collisions there are impossible.
  *
- * Run with: `cd backend && npx ts-node scripts/dedupe-agent-display-names.ts`
- * (from backend/, so ts-node and mongoose resolve from backend/node_modules).
+ * Run with: `cd backend && node dist/scripts/dedupe-agent-display-names.js`
+ * (from backend/, so the compiled script and mongoose resolve from backend/node_modules).
  *
  * Idempotent: safe to re-run. New duplicates introduced later can be
  * cleaned up by re-running.

backend/scripts/generate-team-avatars.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env ts-node
+#!/usr/bin/env node
 /**
  * Generate personality-matched AI portraits for the core team agents and
  * save them to their User records.
@@ -9,12 +9,12 @@
  * or OpenAI/LiteLLM when OPENAI_API_KEY is set.
  *
  * Usage (inside backend pod with env already set):
- *   npx ts-node scripts/generate-team-avatars.ts
- *   npx ts-node scripts/generate-team-avatars.ts --force
+ *   node dist/scripts/generate-team-avatars.js
+ *   node dist/scripts/generate-team-avatars.js --force
  *
  * Or locally:
- *   GEMINI_API_KEY=AIza... MONGO_URI=... npx ts-node backend/scripts/generate-team-avatars.ts
- *   OPENAI_API_KEY=sk-...  MONGO_URI=... npx ts-node backend/scripts/generate-team-avatars.ts
+ *   cd backend && GEMINI_API_KEY=AIza... MONGO_URI=... node dist/scripts/generate-team-avatars.js
+ *   cd backend && OPENAI_API_KEY=sk-...  MONGO_URI=... node dist/scripts/generate-team-avatars.js
  *
  * The script is idempotent: agents whose profilePicture is already set (to a
  * data URI or URL) are skipped unless --force is passed.

backend/scripts/migrate-agent-dm-multimember.ts

@@ -47,8 +47,8 @@
  *     CLAUDE.md "Identity is separate from package."
  *
  * Usage:
- *   ts-node backend/scripts/migrate-agent-dm-multimember.ts          # apply
- *   ts-node backend/scripts/migrate-agent-dm-multimember.ts --dry    # report
+ *   cd backend && node dist/scripts/migrate-agent-dm-multimember.js          # apply
+ *   cd backend && node dist/scripts/migrate-agent-dm-multimember.js --dry    # report
  */
 
 import mongoose from 'mongoose';

backend/scripts/migrate-agent-room-multimember.ts

@@ -32,8 +32,8 @@
  * the action plan without writing.
  *
  * Usage:
- *   ts-node backend/scripts/migrate-agent-room-multimember.ts          # apply
- *   ts-node backend/scripts/migrate-agent-room-multimember.ts --dry    # report
+ *   cd backend && node dist/scripts/migrate-agent-room-multimember.js          # apply
+ *   cd backend && node dist/scripts/migrate-agent-room-multimember.js --dry    # report
  */
 
 import mongoose from 'mongoose';

backend/scripts/migrate-connector-gates.ts

@@ -8,8 +8,8 @@
  * gate between this script's read and write.
  *
  * Usage:
- *   ts-node backend/scripts/migrate-connector-gates.ts --dry
- *   ts-node backend/scripts/migrate-connector-gates.ts
+ *   cd backend && node dist/scripts/migrate-connector-gates.js --dry
+ *   cd backend && node dist/scripts/migrate-connector-gates.js
  */
 
 import mongoose from 'mongoose';

backend/scripts/migrate-guide-identity-convention.ts

@@ -23,8 +23,8 @@
  * only. Idempotent: convention-form installs are skipped.
  *
  * Usage:
- *   ts-node backend/scripts/migrate-guide-identity-convention.ts          # apply
- *   ts-node backend/scripts/migrate-guide-identity-convention.ts --dry    # report
+ *   cd backend && node dist/scripts/migrate-guide-identity-convention.js          # apply
+ *   cd backend && node dist/scripts/migrate-guide-identity-convention.js --dry    # report
  */
 
 import { createHash } from 'crypto';

backend/scripts/migrate-guide-per-user-identity.ts

@@ -26,8 +26,8 @@
  * Idempotent: a second run finds zero 'default' guide installs.
  *
  * Usage:
- *   ts-node backend/scripts/migrate-guide-per-user-identity.ts          # apply
- *   ts-node backend/scripts/migrate-guide-per-user-identity.ts --dry    # report
+ *   cd backend && node dist/scripts/migrate-guide-per-user-identity.js          # apply
+ *   cd backend && node dist/scripts/migrate-guide-per-user-identity.js --dry    # report
  */
 
 import mongoose from 'mongoose';

backend/scripts/purge-unstamped-post-summaries.ts

@@ -19,8 +19,8 @@
  * Dry run by default; pass `--apply` to delete. Run it on the operator's word.
  *
  * Usage:
- *   ts-node backend/scripts/purge-unstamped-post-summaries.ts           # report
- *   ts-node backend/scripts/purge-unstamped-post-summaries.ts --apply   # delete
+ *   cd backend && node dist/scripts/purge-unstamped-post-summaries.js           # report
+ *   cd backend && node dist/scripts/purge-unstamped-post-summaries.js --apply   # delete
  */
 
 import mongoose from 'mongoose';

backend/scripts/remove-task-github-fields.ts

@@ -7,8 +7,8 @@
  * half of the schema removal.
  *
  * Usage:
- *   npx ts-node backend/scripts/remove-task-github-fields.ts
- *   npx ts-node backend/scripts/remove-task-github-fields.ts --apply
+ *   cd backend && node dist/scripts/remove-task-github-fields.js
+ *   cd backend && node dist/scripts/remove-task-github-fields.js --apply
  */
 
 /* eslint-disable no-console */

backend/scripts/repair-first-party-labels.ts

@@ -33,7 +33,7 @@
  * row means the bot has never posted, so it has no users row yet: its Mongo label
  * is still written, and its first post creates the row from that label.
  *
- * Run:  cd backend && npx ts-node scripts/repair-first-party-labels.ts [--apply]
+ * Run:  cd backend && node dist/scripts/repair-first-party-labels.js [--apply]
  */
 import mongoose from 'mongoose';
 import { FIRST_PARTY_DISPLAY_NAMES } from '../constants/firstPartyDisplayNames';

backend/scripts/rewrap-connector-secrets.ts

@@ -8,8 +8,8 @@
  * leaves rows already under the active key untouched.
  *
  * Usage:
- *   npx ts-node backend/scripts/rewrap-connector-secrets.ts          # dry run
- *   npx ts-node backend/scripts/rewrap-connector-secrets.ts --apply
+ *   cd backend && node dist/scripts/rewrap-connector-secrets.js          # dry run
+ *   cd backend && node dist/scripts/rewrap-connector-secrets.js --apply
  */
 
 /* eslint-disable no-console */

backend/scripts/rotate-bot-passwords.ts

@@ -29,8 +29,8 @@
  * operator's word, never inline in a deploy.
  *
  * Usage:
- *   ts-node backend/scripts/rotate-bot-passwords.ts           # report
- *   ts-node backend/scripts/rotate-bot-passwords.ts --apply   # rotate
+ *   cd backend && node dist/scripts/rotate-bot-passwords.js           # report
+ *   cd backend && node dist/scripts/rotate-bot-passwords.js --apply   # rotate
  */
 
 import crypto from 'crypto';

backend/scripts/unlist-internal-registry-agents.ts

@@ -29,8 +29,8 @@
  * list is enumerated and anything unrecognised is left alone and reported.
  *
  * Usage:
- *   npx ts-node backend/scripts/unlist-internal-registry-agents.ts          # dry run
- *   npx ts-node backend/scripts/unlist-internal-registry-agents.ts --apply
+ *   cd backend && node dist/scripts/unlist-internal-registry-agents.js          # dry run
+ *   cd backend && node dist/scripts/unlist-internal-registry-agents.js --apply
  */
 
 /* eslint-disable no-console */

docs/AGENT_AVATARS.md

@@ -133,19 +133,19 @@ Preferred: run the script **inside the backend pod** so it picks up the same
 ```bash
 # One-shot inside the running backend pod
 kubectl exec -n commonly-dev deployment/backend -it -- \
-  npx ts-node backend/scripts/generate-team-avatars.ts
+  node dist/scripts/generate-team-avatars.js
 
 # Force regeneration (even if profilePicture is already set)
 kubectl exec -n commonly-dev deployment/backend -it -- \
-  npx ts-node backend/scripts/generate-team-avatars.ts --force
+  node dist/scripts/generate-team-avatars.js --force
 ```
 
 Local / off-cluster run (direct OpenAI, no proxy):
 
 ```bash
-cd /path/to/commonly
+cd /path/to/commonly/backend
 OPENAI_API_KEY=sk-... MONGO_URI=mongodb://... \
-  npx ts-node backend/scripts/generate-team-avatars.ts
+  node dist/scripts/generate-team-avatars.js
 ```
 
 The script is idempotent: it skips any agent whose `profilePicture` already
@@ -162,8 +162,8 @@ Required env vars (any one combo works):
 1. Open `backend/scripts/generate-team-avatars.ts`.
 2. Add a new entry to the `TEAM` array with `agentName`, `instanceId`,
    `displayName`, `role`, `personality`, and `style`.
-3. Run the script. Existing agents will be skipped; only the new one is
-   generated.
+3. Run `npm run build` in `backend/` so `dist` picks up the new entry, then run
+   the script. Existing agents are skipped; only the new one is generated.
 
 ## Record on the User document
 

docs/runbooks/migrate-chat-token-copies.md

@@ -36,10 +36,10 @@ key ring (`CONNECTOR_SECRET_KEYS`, `CONNECTOR_SECRET_ACTIVE_KEY`) supplied by th
 existing ops-runner secret environment (never paste them into a command):
 
 ```sh
-npx ts-node scripts/migrate-chat-token-copies.ts
+node dist/scripts/migrate-chat-token-copies.js
 # Review the DRY-RUN counts by type, then explicitly apply:
-npx ts-node scripts/migrate-chat-token-copies.ts --apply
-npx ts-node scripts/migrate-chat-token-copies.ts
+node dist/scripts/migrate-chat-token-copies.js --apply
+node dist/scripts/migrate-chat-token-copies.js
 ```
 
 **What the counts mean.** The final dry run should report zero candidates and

docs/runbooks/scrub-feed-token-copies.md

@@ -17,10 +17,10 @@ From the deployed backend directory, with `MONGO_URI` supplied by the existing
 ops-runner secret environment (never paste it into a command):
 
 ```sh
-npx ts-node scripts/scrub-feed-token-copies.ts
+node dist/scripts/scrub-feed-token-copies.js
 # Review DRY-RUN counts by type, then explicitly apply:
-npx ts-node scripts/scrub-feed-token-copies.ts --apply
-npx ts-node scripts/scrub-feed-token-copies.ts
+node dist/scripts/scrub-feed-token-copies.js --apply
+node dist/scripts/scrub-feed-token-copies.js
 ```
 
 The final dry run should report zero candidates for both types. Reports contain