CLAUDE.md fleet audit: dedup vs global rules, archive session logs, fix stale guidance

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: vishalsachdev

CLAUDE.md

@@ -45,12 +45,12 @@ After a restart wipes process memory (pre-Postgres behavior) or when preloading
 
 ## Architecture gotchas
 
-- **`next start` doesn't read PORT from `.env.local`** — must be in shell env at `pm2 start` time. Already baked in; don't touch unless rebuilding the PM2 entry.
+- **PORT is already baked into the PM2 entry** — don't touch unless rebuilding it (global VPS rule: PORT goes in shell env at `pm2 start`, not `.env.local`).
 - **Admin seed `replaceMode: "metadata"` (default) preserves chat history**; `"full"` wipes the whole room. Matters for `/api/admin/seed` callers.
 - **AI reply streaming flushes to Postgres every ~1s** during generation, plus a final flush. A mid-stream process crash loses only the unflushed tail; reconnecting clients see the last flushed state, never permanently-empty bubbles.
 - **Don't write synthetic rows into `participants`** for non-membership purposes (e.g. file attribution, system messages). The participants table is the source of truth for the Participants sidebar, mention suggestions, the SSE snapshot, and `upsertParticipant` matches by `lower(email)` — so a synthetic row with a real user's email gets *adopted* by that user when they join, binding their cookie to the synthetic id. Attribute via lookup of an existing real participant instead, and accept "Unknown" as the fallback. Caught by codex-review on 2026-05-06.
 - **`POST /api/room` body field is `id`, not `slug`** — the spec uses "slug" throughout but the wire format takes `body.id` (validated against `/^[a-z0-9-]{3,40}$/`). Sending `{slug: "..."}` returns 400 `invalid_slug`. Caught during 2026-05-13 acceptance walk; the field name predates the spec rewrite and renaming would break the legacy admin path.
-- **Next 15 server components can't mutate cookies** — `cookies().delete()` / `.set()` only work in route handlers, server actions, and middleware. RSCs (even `dynamic = "force-dynamic"`) throw if you try. To recycle a stale cookie from a server-component page (e.g. `/dashboard` detects "cookie present + getCreator() null"), `redirect()` to a GET route handler that does the delete + redirects back. See `app/dashboard/auth/route.ts` GET handler for the pattern.
+- **Stale-cookie recycling**: `/dashboard` detects "cookie present + getCreator() null" and `redirect()`s to the `app/dashboard/auth/route.ts` GET handler, which deletes the cookie + redirects back (per the global Next-15 rule: RSCs can't mutate cookies).
 - **Renaming a room id orphans cookies.** Browser sessions store `mindforum_pid_<roomid>`; if you rename the room PK (insert-new → repoint children → delete-old transaction), users who joined the old id can't auth into the new id and must re-join. No FK ON UPDATE CASCADE on schema. Only safe before invitations go out.
 - **Room system prompts are hard-capped at 4000 characters, and two of three surfaces truncate SILENTLY.** Seed endpoint (`app/api/admin/seed/route.ts`) does `.slice(0, 4000)` and returns `ok: true`; the create-room UI uses `maxLength={4000}` with no counter; only the admin PATCH route rejects with 400. Guardrails sections live at the end of prompts, so truncation cuts exactly the safety text. After seeding or editing any room, verify the deployed prompt length matches the source. Long-form prompt docs are canonical sources, not paste-in blocks — deploy condensed <4000-char versions (pattern: msba-online `docs/mindforum-faculty-system-prompt.md`). Also: `rooms/seed-msba-rooms.py extract_prompt()` grabs the largest ``` fence, so prompts containing code fences seed the wrong fragment (issue #21) — keep room prompt files fence-free until fixed. Open issues: #20 (silent truncation), #21 (fence parsing).