@krimto-labs/krimto 0.2.36 → 0.2.38

package/README.md

@@ -9,8 +9,8 @@ place and reads the right slice of it — Alice's preferences override the team'
 conventions override the org's standards, and every fact carries a paper trail (author, source,
 timestamp, reviewer).
 
-> **Where we are:** **v0.2.36** is the current release — the v0.2.17 wizard redesign is now
-> shipped end-to-end, plus nineteen patch releases of correctness fixes and agent-friendly
+> **Where we are:** **v0.2.38** is the current release — the v0.2.17 wizard redesign is now
+> shipped end-to-end, plus twenty-one patch releases of correctness fixes and agent-friendly
 > surface. The v0.2.16 architecture (markdown-in-git storage, `user → team → org` hierarchy,
 > hybrid retrieval, server-enforced access, two-way git sync, MCP over stdio + HTTP, the Docker
 > image, the web UI) is unchanged. What you get on top of v0.2.16:
@@ -41,7 +41,7 @@ timestamp, reviewer).
 >   first, waits for `:8080` to accept TCP, then writes editor configs. Cursor's file
 >   watcher never fires into an unbound port (the v0.2.27/28 ECONNREFUSED fix).
 >
-> **The agent story (v0.2.34 → v0.2.36).**
+> **The agent story (v0.2.34 → v0.2.38).**
 > - **Phase B agent flags** — `editors --add cursor`, `service --always`, `search --keyword`,
 >   `reset --yes`, `remote --set <url>`, `folder --to <path>`. Every command that used to
 >   open an interactive prompt now has a flag form.
@@ -58,6 +58,14 @@ timestamp, reviewer).
 >   service into team mode itself (no copy-paste recipe, no lock conflict), saves invite keys
 >   to a 0600 backup file, and validates the git remote URL at the prompt. `krimto notes` now
 >   works from any terminal (identity falls back to `git config user.email`).
+> - **Write-time duplicate backstop (v0.2.37)** — `krimto_write` flags a near-duplicate fact in
+>   the same scope (a `related` list + a hint to `krimto_supersede`), so memory doesn't silently
+>   accumulate two facts about the same thing even when the agent skips `krimto_recall`. Backed
+>   by a new retrieval-quality eval that asserts recall returns the right fact first.
+> - **Team mode activates live (v0.2.38)** — `krimto team init` writes `members.yaml` and the
+>   running server flips to team mode on its own within ~2s (it polls the file) — no restart, no
+>   env var. The wizard verifies auth is genuinely enforced before printing "🟢 live", and
+>   auto-reconnects the admin's own editor with their key.
 >
 > See [ROADMAP.md](ROADMAP.md), [CHANGELOG.md](CHANGELOG.md), and the proposal-vs-reality
 > diff in [docs/krimto-v0.2.17-maria-journey.html §09](docs/krimto-v0.2.17-maria-journey.html)
@@ -503,7 +511,7 @@ Cline — is table stakes today, so Krimto ships it but doesn't lead with it.
 ## Roadmap
 
 `v0.2` (teams, v0.2.5) → `v0.2.18` (v0.2.17 wizard redesign — published as one SemVer-clean
-release) → `v0.2.36` (correctness + agent-friendly polish — current) → `v0.3` (OAuth + PR approval
+release) → `v0.2.38` (correctness + agent-friendly polish — current) → `v0.3` (OAuth + PR approval
 flow) → `v1.0` (Krimto Cloud). See [ROADMAP.md](ROADMAP.md) for the per-release breakdown.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krimto-labs/krimto",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "description": "Open-source team memory layer for AI agents — markdown files in git, user/team/org hierarchy, cross-vendor MCP server.",
   "license": "Apache-2.0",
   "type": "module",

package/src/access/membership.ts

@@ -80,6 +80,21 @@ export function isOrgAdmin(m: Membership, email: string): boolean {
   return m.org.admins.includes(email);
 }
 
+/** True when the org has at least one admin — the live signal that team mode should be enforced. */
+export function hasOrgAdmin(m: Membership): boolean {
+  return m.org.admins.length > 0;
+}
+
+/**
+ * Guard for LIVE membership reloads: refuse to adopt a reload that would drop the last admin,
+ * because that silently turns auth OFF on a running server. A transient/mid-write read that
+ * momentarily parses zero admins must NOT open an auth-off window. Turning team mode off is a
+ * deliberate, restart-gated operator action — never an automatic side effect of a file watch.
+ */
+export function shouldAdoptReload(current: Membership, next: Membership): boolean {
+  return !(hasOrgAdmin(current) && !hasOrgAdmin(next));
+}
+
 export function isTeamLead(m: Membership, teamSlug: string, email: string): boolean {
   const team = m.teams.find((t) => t.slug === teamSlug);
   return team ? team.leads.includes(email) : false;

package/src/cli/teamInit.ts

@@ -22,9 +22,8 @@ import { ApiKeyStore } from "../access/auth";
 import { addUser, createTeam } from "../access/membershipStore";
 import { bootstrapAdmin } from "../server/bootstrap";
 import { defaultIdentity } from "./init";
-import { inspectRuntime } from "./inspectRuntime";
+import { applyJoin } from "./join";
 import { defaultIO, isExitPrompt, type WizardIO } from "./promptHelpers";
-import { detectPlatform, installService } from "./service";
 import { looksLikeRemoteUrl, runSetupRemote } from "./setupRemote";
 
 /** Everything the wizard collects before it calls {@link applyTeamInit}. */
@@ -77,18 +76,26 @@ export interface TeamInitOptions {
   keysPath?: string;
   /** Override KRIMTO_HTTP_PORT detection. */
   port?: number;
-  /** Override os.homedir() — passed to inspectRuntime + installService for tests. */
+  /** Override os.homedir() — forwarded to the admin-reconnect `applyJoin` for editor detection. */
   homeDir?: string;
-  /** When true, the post-apply service-restart step writes files but never invokes
-   * launchctl/systemctl/schtasks. Tests use this to assert the new env block without
-   * mutating CI's user services. */
+  /** When true, the admin-reconnect `applyJoin` writes nothing to real editor configs. Tests use this. */
   dryRun?: boolean;
-  /** Suppress the post-apply service-restart probe entirely (tests that don't exercise it). */
-  skipServiceRestart?: boolean;
+  /** Inject the live-team-mode probe (tests). Defaults to the real {@link confirmTeamModeLive}
+   * which polls the running server's /mcp for a 401. */
+  confirmLive?: (host: string) => Promise<LiveOutcome>;
   /** Skip `runSetupRemote` even when a URL was given. Tests use this. */
   skipRemoteSetup?: boolean;
 }
 
+/**
+ * Result of verifying that the running server is ACTUALLY enforcing team mode (not just that a
+ * port is open). The old wizard printed "🟢 live" off a TCP probe and lied; this is the honest signal.
+ *   - "live"      — the server returned 401 on /mcp ⇒ bearer required ⇒ team mode enforced.
+ *   - "no-server" — nothing reachable at the host (start one with `krimto serve`).
+ *   - "timeout"   — a server responded but never 401 within the window (it polls members.yaml ~2s).
+ */
+export type LiveOutcome = "live" | "no-server" | "timeout";
+
 const SLUG_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/;
 const EMAIL_RE = /^[^@\s]+@[^@\s]+$/;
 
@@ -251,13 +258,31 @@ export async function runTeamInit(opts: TeamInitOptions = {}): Promise<TeamInitR
       opts,
     );
 
-    // Probe runtime + offer to restart the always-running service so team-mode auth takes
-    // effect on the SAME machine, in the SAME wizard run. The smoke-6 transcript ended with
-    // a copy-paste "Next" recipe (`KRIMTO_BOOTSTRAP_ADMIN=... npx serve`) the user couldn't
-    // run because their existing service held the data-dir lock. This closes that gap.
-    const restartOutcome = await maybeRestartServiceForTeamMode(result, opts);
+    // No restart, no env var: writing members.yaml IS the switch. The running server polls the
+    // file (~2s) and flips to team mode on its own. We just VERIFY it actually happened — poll
+    // /mcp for a 401 — instead of the old TCP probe that falsely printed "🟢 live".
+    const live = await (opts.confirmLive ?? confirmTeamModeLive)(result.serverHost);
+
+    // When team mode is confirmed live, reconnect the admin's OWN editors in team mode (their
+    // solo/no-key connection would otherwise start getting 401s). Reuses the teammate join path.
+    let reconnected = false;
+    if (live === "live" && result.adminKey) {
+      try {
+        const join = await applyJoin(
+          { server: `http://${result.serverHost}`, key: result.adminKey },
+          {
+            cwd: process.cwd(),
+            ...(opts.homeDir ? { homeDir: opts.homeDir } : {}),
+            ...(opts.dryRun ? { dryRun: opts.dryRun } : {}),
+          },
+        );
+        reconnected = join.editorOutcomes.some((o) => o.mcpAction !== "manual");
+      } catch {
+        /* best-effort — the admin can run `krimto join` manually if this fails */
+      }
+    }
 
-    printApplyResult(result, io, restartOutcome);
+    printApplyResult(result, io, { live, reconnected });
     return result;
   } catch (e) {
     if (isExitPrompt(e)) {
@@ -352,74 +377,33 @@ async function askTeammates(): Promise<string[]> {
   return list;
 }
 
-// === Post-apply service restart =============================================
-
-/**
- * What happened when the wizard tried to flip the running service into team mode after apply.
- * Drives the "Next" block in {@link printApplyResult}: when team mode is live, we don't print
- * the copy-paste `KRIMTO_BOOTSTRAP_ADMIN=... npx serve` recipe.
- */
-export type RestartOutcome =
-  | { kind: "no-service" }
-  | { kind: "declined" }
-  | { kind: "restarted"; portReady: boolean }
-  | { kind: "failed"; error: string };
+// === Verify team mode is actually live ======================================
 
 /**
- * If the running Krimto IS the always-running service we installed, offer to restart it with
- * `KRIMTO_BOOTSTRAP_ADMIN` baked in so team-mode auth takes effect immediately. Returns the
- * outcome for the print step to render. Skipped silently when {@link TeamInitOptions.skipServiceRestart}
- * is set (tests that don't want to exercise this path).
+ * Poll the running server's `/mcp` until it returns 401 — the precise signal that bearer auth is
+ * being enforced (team mode is genuinely ON). Writing members.yaml flips the server within its
+ * ~2s membership-watch tick, so we give it a short window. Returns "live" on 401, "no-server"
+ * when nothing was ever reachable, "timeout" when a server responded but never 401 in time.
+ *
+ * This replaces the v0.2.36 restart dance: there's nothing to restart anymore — the file is the
+ * switch. We only confirm it took effect (the old code printed "🟢 live" off a TCP probe and lied).
  */
-async function maybeRestartServiceForTeamMode(
-  result: TeamInitResult,
-  opts: TeamInitOptions,
-): Promise<RestartOutcome> {
-  if (opts.skipServiceRestart) return { kind: "no-service" };
-  const io = opts.io ?? defaultIO;
-
-  const runtime = await inspectRuntime(
-    result.dataDir,
-    opts.homeDir ? { homeDir: opts.homeDir } : {},
-  );
-  if (!runtime.service.loaded || runtime.effectiveLaunchedBy !== "service") {
-    return { kind: "no-service" };
-  }
-
-  const wantRestart = await confirm({
-    message: "Restart the running Krimto service so team mode is enforced now? (~3s of downtime)",
-    default: true,
-  });
-  if (!wantRestart) return { kind: "declined" };
-
-  io.out("\n  Restarting service in team mode...\n");
-  try {
-    const install = await installService(
-      {
-        binPath: process.execPath,
-        args: [process.argv[1] ?? "krimto", "serve"],
-        env: {
-          KRIMTO_IDENTITY: result.adminEmail,
-          KRIMTO_DATA: result.dataDir,
-          KRIMTO_HTTP_PORT: "8080",
-          KRIMTO_BOOTSTRAP_ADMIN: result.adminEmail,
-        },
-        ...(opts.homeDir ? { homeDir: opts.homeDir } : {}),
-      },
-      {
-        platform: detectPlatform(),
-        ...(opts.dryRun ? { dryRun: opts.dryRun } : {}),
-      },
-    );
-    return { kind: "restarted", portReady: install.portReady !== false };
-  } catch (e) {
-    return { kind: "failed", error: e instanceof Error ? e.message : String(e) };
+export async function confirmTeamModeLive(host: string, timeoutMs = 8000): Promise<LiveOutcome> {
+  const deadline = Date.now() + timeoutMs;
+  let reached = false;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://${host}/mcp`, { method: "GET" });
+      reached = true;
+      if (res.status === 401) return "live";
+    } catch {
+      /* not reachable yet */
+    }
+    await new Promise((r) => setTimeout(r, 500));
   }
+  return reached ? "timeout" : "no-server";
 }
 
-// Exposed for the integration test that asserts on the env block written to the plist.
-export { maybeRestartServiceForTeamMode };
-
 // === Pretty printing ========================================================
 
 function printPreamble(dataDir: string, io: WizardIO): void {
@@ -439,7 +423,11 @@ function printSummary(a: TeamInitAnswers, io: WizardIO): void {
   io.out(`  Teammates:    ${a.teammates.length === 0 ? "(none yet)" : a.teammates.join(", ")}\n\n`);
 }
 
-function printApplyResult(res: TeamInitResult, io: WizardIO, restart: RestartOutcome): void {
+function printApplyResult(
+  res: TeamInitResult,
+  io: WizardIO,
+  status: { live: LiveOutcome; reconnected: boolean },
+): void {
   io.out("  ✓ Admin promoted + members.yaml updated\n");
   io.out(`  ✓ Team "${res.teamSlug}" created\n`);
   if (res.invites.length > 0) {
@@ -488,25 +476,24 @@ function printApplyResult(res: TeamInitResult, io: WizardIO, restart: RestartOut
     io.out(`  (mode 0600 — read by you only. Delete it once teammates have their keys.)\n\n`);
   }
 
-  // The "Next" block depends on whether the running service was just flipped into team mode.
-  // When it was, the user's already done — just hand them the dashboard URL. When it wasn't
-  // (no service, declined, or install failed), fall back to the original copy-paste recipe.
+  // The "Next" block reflects the VERIFIED state of the running server (members.yaml is the
+  // switch — no restart). "🟢 live" is only printed when /mcp actually returned 401.
   io.out("━━ Next ━━\n\n");
-  if (restart.kind === "restarted" && restart.portReady) {
-    io.out(`  🟢 Team mode is live on http://localhost:8080\n`);
-    io.out(`  • View the dashboard at http://localhost:8080/ui/admin\n`);
-  } else if (restart.kind === "restarted" && !restart.portReady) {
-    io.out(`  ⚠ Service restarted in team mode, but the port didn't come up in 10s.\n`);
-    io.out(`     Check /tmp/com.krimto.server.err.log (macOS) or \`journalctl --user -u krimto\` (Linux).\n`);
-    io.out(`  • View the dashboard at http://localhost:8080/ui/admin (once the port is up)\n`);
-  } else if (restart.kind === "failed") {
-    io.out(`  ⚠ Service restart failed: ${restart.error}\n`);
-    io.out(`     Start it yourself: KRIMTO_BOOTSTRAP_ADMIN=${res.adminEmail} npx @krimto-labs/krimto serve\n`);
+  if (status.live === "live") {
+    io.out(`  🟢 Team mode is live on http://${res.serverHost}\n`);
+    if (status.reconnected) {
+      io.out(`  ✓ Reconnected your editor in team mode — restart it once to pick up the key.\n`);
+    }
+    io.out(`  • View the dashboard at http://${res.serverHost}/ui/admin (sign in with your admin key)\n`);
+  } else if (status.live === "timeout") {
+    io.out(`  ⏳ A server is running at ${res.serverHost} but team mode hasn't taken effect yet.\n`);
+    io.out(`     It re-reads members.yaml every ~2s — give it a moment, then reload /ui/admin.\n`);
   } else {
-    // "declined" or "no-service" — print the original recipe (still without the literal `$`).
-    io.out("  • Start the server in team mode (if not already):\n");
-    io.out(`      KRIMTO_BOOTSTRAP_ADMIN=${res.adminEmail} npx @krimto-labs/krimto serve\n`);
-    io.out("  • View the dashboard at http://localhost:8080/ui/admin\n");
+    // "no-server" — nothing reachable. With members.yaml written, a plain serve starts in team mode.
+    io.out(`  • No running server found at ${res.serverHost}. Start one (it reads members.yaml and\n`);
+    io.out(`    comes up in team mode — no env var needed):\n`);
+    io.out(`      npx @krimto-labs/krimto serve\n`);
+    io.out(`  • Then open http://${res.serverHost}/ui/admin and sign in with your admin key.\n`);
   }
   io.out("  • Step back to solo with `krimto team disband` (data preserved)\n\n");
 }

package/src/index/db.ts

@@ -21,7 +21,21 @@ export function openIndexDb(path: string, config: IndexConfig): Db {
   if (path !== ":memory:") db.pragma("journal_mode = WAL");
   db.pragma("foreign_keys = ON");
   db.transaction(() => {
+    // A virtual table's tokenizer is fixed at CREATE; `CREATE ... IF NOT EXISTS` won't change an
+    // existing facts_fts. So when an older index is opened, drop facts_fts + its sync triggers,
+    // let SCHEMA_SQL recreate them with the current tokenizer, then rebuild the FTS index from the
+    // (untouched) content table. The `facts` rows survive — only the derived FTS index is rebuilt.
+    const prior = readStoredSchemaVersion(db);
+    const ftsMigration = prior !== null && prior < SCHEMA_VERSION;
+    if (ftsMigration) {
+      db.exec(
+        "DROP TRIGGER IF EXISTS facts_ai; DROP TRIGGER IF EXISTS facts_ad; DROP TRIGGER IF EXISTS facts_au; DROP TABLE IF EXISTS facts_fts;",
+      );
+    }
     db.exec(SCHEMA_SQL);
+    if (ftsMigration) {
+      db.exec("INSERT INTO facts_fts(facts_fts) VALUES('rebuild');");
+    }
     if (config.provider !== "none" && config.dimensions > 0) {
       db.exec(vecTableSql(config.dimensions));
     }
@@ -35,6 +49,18 @@ export function openIndexDb(path: string, config: IndexConfig): Db {
   return db;
 }
 
+/** The schema_version stored in a pre-existing index, or null when the table isn't there yet. */
+function readStoredSchemaVersion(db: Db): number | null {
+  try {
+    const row = db.prepare("SELECT value FROM schema_meta WHERE key='schema_version'").get() as
+      | { value: string }
+      | undefined;
+    return row ? Number(row.value) : null;
+  } catch {
+    return null; // schema_meta doesn't exist yet (fresh database)
+  }
+}
+
 /** True when the stored embedding space differs from the configured one (forces rebuild). */
 export function embeddingSpaceChanged(db: Db, config: IndexConfig): boolean {
   const get = db.prepare("select value from schema_meta where key=?");

package/src/index/schema.ts

@@ -2,7 +2,10 @@
 // (divergence: spec hardcodes float[1536]); FTS5 is an external-content table kept in
 // sync by triggers (canonical sqlite.org pattern).
 
-export const SCHEMA_VERSION = 1;
+// Bumped to 2 in v0.2.38: facts_fts gains the Porter stemmer so a singular query ("favorite
+// color") matches a plural-titled fact ("Favorite colors"). openIndexDb migrates older indexes
+// by dropping + recreating facts_fts and rebuilding it from the content table.
+export const SCHEMA_VERSION = 2;
 
 /** Static DDL (everything except the dimension-parameterized vec table). */
 export const SCHEMA_SQL = `
@@ -22,7 +25,7 @@ CREATE TABLE IF NOT EXISTS facts (
 );
 
 CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts USING fts5(
-  title, body, tags, content='facts', content_rowid='rowid'
+  title, body, tags, content='facts', content_rowid='rowid', tokenize='porter unicode61'
 );
 
 CREATE TRIGGER IF NOT EXISTS facts_ai AFTER INSERT ON facts BEGIN

package/src/server/http.ts

@@ -38,8 +38,12 @@ export interface HttpAppDeps {
   rateLimiter?: RateLimiter;
   /** When set, mounts the admin-only membership/key API at /admin and enables /ui/admin. */
   admin?: AdminContext;
-  /** True = team mode (auth on /mcp + /ui login + /admin). False = local mode (no auth). */
-  requireAuth: boolean;
+  /**
+   * Live predicate for team mode (auth on /mcp + /ui login + /admin). Evaluated PER REQUEST, not
+   * captured once — so when `members.yaml` gains an admin the running server flips to team mode
+   * without a restart. True ⇒ enforce auth; false ⇒ local/solo mode (no auth).
+   */
+  teamModeActive: () => boolean;
   /** Live status snapshot for the /ui dashboard status panel. */
   status?: () => StatusPanelOpts;
   /** Called once, on the first request to /mcp (any verb). Powers the "🟢 client connected" boot hint. */
@@ -86,7 +90,7 @@ export function buildHttpApp(deps: HttpAppDeps): Express {
     // call. The resolver enriches the Requester with `source` so krimtoWrite can stamp facts
     // with "cursor" / "claude-code" / etc. when the caller didn't pass `source` explicitly.
     const source = userAgentToSource(req.get("User-Agent"));
-    const baseResolver = deps.requireAuth
+    const baseResolver = deps.teamModeActive()
       ? (extra: { authInfo?: AuthInfo }) => requesterFromAuth(extra.authInfo)
       : (() => deps.ctx.requester) as (extra: { authInfo?: AuthInfo }) => Requester;
     const resolver: (extra: { authInfo?: AuthInfo }) => Requester = source
@@ -116,15 +120,38 @@ export function buildHttpApp(deps: HttpAppDeps): Express {
     }
     next();
   };
-  const mcpChain: RequestHandler[] = deps.requireAuth ? [auth, rateLimit] : [rateLimit];
-  app.post("/mcp", ...mcpChain, (req, res) => {
+  // Per-request gate: run bearer auth only when team mode is active right now. In solo mode the
+  // request falls straight through to rateLimit + handler (req.auth stays unset; rateLimit keys
+  // on "anonymous"). Mounted always so a live flip to team mode takes effect with no rebuild.
+  const maybeAuth: RequestHandler = (req, res, next) => {
+    if (deps.teamModeActive()) {
+      auth(req, res, next);
+    } else {
+      next();
+    }
+  };
+  app.post("/mcp", maybeAuth, rateLimit, (req, res) => {
     void handleMcp(req, res);
   });
-  app.get("/mcp", ...mcpChain, (req, res) => {
+  app.get("/mcp", maybeAuth, rateLimit, (req, res) => {
     void handleMcp(req, res);
   });
 
-  if (deps.requireAuth && deps.admin) app.use("/admin", auth, buildAdminRouter(deps.admin));
+  // /admin is mounted whenever an admin context exists, but each request is gated on live team
+  // mode: in solo mode it 404s (invisible), in team mode it requires the admin bearer key.
+  if (deps.admin) {
+    app.use(
+      "/admin",
+      (req, res, next) => {
+        if (deps.teamModeActive()) {
+          auth(req, res, next);
+        } else {
+          res.sendStatus(404);
+        }
+      },
+      buildAdminRouter(deps.admin),
+    );
+  }
 
   app.use(
     "/ui",
@@ -133,8 +160,9 @@ export function buildHttpApp(deps: HttpAppDeps): Express {
       keys: deps.keys,
       membership: deps.membership,
       sessionSecret: sessionConfigFromEnv().secret,
-      admin: deps.requireAuth ? deps.admin : undefined,
-      localIdentity: deps.requireAuth ? undefined : deps.ctx.requester.identity,
+      admin: deps.admin,
+      teamModeActive: deps.teamModeActive,
+      localIdentity: deps.ctx.requester.identity,
       status: deps.status,
     }),
   );

package/src/server/index.ts

@@ -34,12 +34,13 @@ import { z } from "zod";
 import { FactStore } from "../storage/store";
 import { GitRepo } from "../storage/git";
 import { CommitBatcher, batcherConfigFromEnv } from "../storage/batcher";
-import { loadMembership, requesterFor } from "../access/membership";
+import { hasOrgAdmin, loadMembership, parseMembership, requesterFor, shouldAdoptReload } from "../access/membership";
 import { createEmbeddingProvider, embeddingConfigFromEnv } from "../index/providers";
 import { openIndexDb, embeddingSpaceChanged, type IndexConfig } from "../index/db";
 import { FactIndex } from "../index/factIndex";
 import { Serializer } from "../index/serialize";
 import { RemoteSync, syncConfigFromEnv } from "../storage/sync";
+import { MembershipWatcher } from "./membershipWatcher";
 import { KrimtoError } from "./errors";
 import {
   krimtoListScopes,
@@ -54,7 +55,7 @@ import { type Requester } from "../access/scope";
 
 export type RequesterResolver = (extra: { authInfo?: AuthInfo }) => Requester;
 
-export const KRIMTO_VERSION = "0.2.36";
+export const KRIMTO_VERSION = "0.2.38";
 
 export function resolveDataDir(): string {
   return process.env.KRIMTO_DATA ?? path.join(homedir(), ".krimto");
@@ -121,7 +122,9 @@ export function buildServer(ctx: ToolContext, resolveRequester?: RequesterResolv
         "durable fact, or when correcting a mistake you should not repeat. For the user's personal " +
         "scope use `user/me` (the server resolves it to their identity) — do not guess an email. The " +
         "write is rejected (with the list of scopes you may write to) if you target a scope you couldn't " +
-        "read back. Call krimto_recall first to avoid duplicates.",
+        "read back. Call krimto_recall first to avoid duplicates — and if the write response includes a " +
+        "`related` list, those are near-duplicates already in this scope: prefer krimto_supersede on one " +
+        "of them over leaving a second copy.",
       inputSchema: {
         scope: z
           .string()
@@ -344,13 +347,29 @@ export async function main(): Promise<void> {
     process.stderr.write(`Krimto embeddings: ${embeddingProvider.name} (${embeddingProvider.dimensions}d)\n`);
   }
 
+  const membersPath = path.join(dataDir, ".krimto", "members.yaml");
   const reloadMembership = async (): Promise<void> => {
-    membership = await loadMembership(dataDir);
-    ctx.membership = membership;
+    let next: ReturnType<typeof parseMembership>;
+    try {
+      next = parseMembership(await fs.readFile(membersPath, "utf8"));
+    } catch {
+      return; // read/parse failure — keep the current membership; never blank out auth
+    }
+    // Safety: never flip team→solo on a (possibly transient, mid-write) zero-admin read — that
+    // would open an auth-off window. See shouldAdoptReload for the rationale.
+    if (!shouldAdoptReload(membership, next)) return;
+    membership = next;
+    ctx.membership = next;
   };
 
   batcher.start((fn) => ctx.writeQueue.run(fn));
 
+  // Live team-mode trigger: poll members.yaml so a `krimto team init` (a separate CLI process)
+  // flips this running server into team mode within ~2s — no restart. Runs unconditionally so a
+  // solo→team transition is picked up. Reload goes through the write serializer.
+  const memberWatch = new MembershipWatcher(membersPath, reloadMembership);
+  memberWatch.start((fn) => ctx.writeQueue.run(fn));
+
   const sync = new RemoteSync(
     repo,
     async () => {
@@ -394,6 +413,7 @@ export async function main(): Promise<void> {
     shuttingDown = true;
     telemetry.stop();
     sync.stop();
+    memberWatch.stop();
     batcher.stop();
     void ctx.writeQueue
       .run(() => batcher.flush())
@@ -408,8 +428,12 @@ export async function main(): Promise<void> {
   const httpPort = process.env.KRIMTO_HTTP_PORT ? Number(process.env.KRIMTO_HTTP_PORT) : undefined;
   if (httpPort !== undefined && Number.isInteger(httpPort) && httpPort > 0) {
     const rlConfig = rateLimitConfigFromEnv();
-    // Team mode (auth) when an admin is bootstrapped or auth is explicitly required; else local mode.
-    const requireAuth = Boolean(process.env.KRIMTO_BOOTSTRAP_ADMIN || process.env.KRIMTO_REQUIRE_AUTH === "1");
+    // Team mode is derived LIVE from membership: any org admin ⇒ enforce auth. KRIMTO_BOOTSTRAP_ADMIN
+    // still works because it seeds an admin into members.yaml before this point; the explicit
+    // KRIMTO_REQUIRE_AUTH=1 override remains. Evaluated per request (via the getter), so a later
+    // `members.yaml` edit flips the running server with no restart.
+    const teamModeActive = (): boolean =>
+      hasOrgAdmin(membership) || process.env.KRIMTO_REQUIRE_AUTH === "1";
     const app = buildHttpApp({
       ctx,
       keys,
@@ -423,7 +447,7 @@ export async function main(): Promise<void> {
       gitRemoteStatus: () => batcher.lastPushStatus(),
       rateLimiter: rlConfig.enabled ? new RateLimiter(rlConfig) : undefined,
       admin,
-      requireAuth,
+      teamModeActive,
       // Live status for the /ui dashboard panel — built per request so it never goes stale.
       status: () => ({
         gitRemoteUrl: process.env.KRIMTO_GIT_REMOTE,
@@ -443,7 +467,7 @@ export async function main(): Promise<void> {
     });
     app.listen(httpPort, () => {
       process.stderr.write(`Krimto ${KRIMTO_VERSION} HTTP server on :${httpPort} (data: ${dataDir})\n`);
-      if (!requireAuth) {
+      if (!teamModeActive()) {
         process.stderr.write(localModeBanner(httpPort, dataDir, identity));
       } else {
         process.stderr.write(teamModeBanner({ host: `localhost:${httpPort}`, key: bootstrapKey, dataDir }));

package/src/server/membershipWatcher.ts

@@ -0,0 +1,55 @@
+// Live team-mode trigger. `krimto team init` writes members.yaml from a SEPARATE CLI process, so
+// the running server never learns about the new admin on its own. This watcher polls the file's
+// mtime (~2s) and fires a reload when it changes — flipping the server into team mode without a
+// restart. An mtime poll (not fs.watch) is deliberate: fs.watch is flaky with atomic-rename writes
+// and varies across platforms; a poll matches the existing setInterval pattern (batcher/sync).
+
+import { promises as fs } from "node:fs";
+
+/** Runs a task with exclusive access (the write serializer in production). Mirrors RemoteSync. */
+export type RunExclusive = (task: () => Promise<unknown>) => Promise<unknown>;
+
+export const DEFAULT_MEMBERSHIP_WATCH_MS = 2000;
+
+export class MembershipWatcher {
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private lastMtime = 0;
+
+  constructor(
+    private readonly file: string,
+    private readonly onChange: () => Promise<void>,
+    private readonly intervalMs: number = DEFAULT_MEMBERSHIP_WATCH_MS,
+  ) {}
+
+  /**
+   * One poll: fire `onChange` iff the file's mtime differs from the last seen value. An absent or
+   * unreadable file is a no-op (solo stays solo). Exposed so tests can drive it deterministically.
+   */
+  async checkOnce(): Promise<void> {
+    let mtime: number;
+    try {
+      mtime = (await fs.stat(this.file)).mtimeMs;
+    } catch {
+      return; // file not there yet — nothing to flip
+    }
+    if (mtime === this.lastMtime) return; // debounce: only react to a real change
+    this.lastMtime = mtime;
+    await this.onChange();
+  }
+
+  /** Begin polling. `runExclusive` serializes each reload against the batcher/sync write path. */
+  start(runExclusive: RunExclusive): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void runExclusive(() => this.checkOnce());
+    }, this.intervalMs);
+    if (typeof this.timer.unref === "function") this.timer.unref();
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+}

package/src/server/tools.ts

@@ -9,7 +9,7 @@ import { isValidScope, type Requester } from "../access/scope";
 import { canRead, canWrite, isOrgAdmin, type Membership } from "../access/membership";
 import { FactIndex } from "../index/factIndex";
 import { Serializer } from "../index/serialize";
-import { rankCandidates } from "../retrieval/pipeline";
+import { lexicalSimilarity, rankCandidates } from "../retrieval/pipeline";
 import { type CommitBatcher } from "../storage/batcher";
 import { type ActivityLog } from "./activity";
 import { KrimtoError } from "./errors";
@@ -47,6 +47,12 @@ export interface WriteInput {
   source?: string;
   supersedes?: string[];
 }
+export interface RelatedFact {
+  id: string;
+  title: string;
+  /** Hybrid-retrieval score of the existing fact against the new one's title+body. */
+  score: number;
+}
 export interface WriteResult {
   id: string;
   scope: string;
@@ -56,6 +62,12 @@ export interface WriteResult {
   /** Human-readable hint for the agent to relay back. Teaches "this is just a file you can open." */
   hint: string;
   commit_sha: string | null;
+  /**
+   * Existing facts in the same scope that closely resemble the one just written. Surfaced so a
+   * weak agent that skipped krimto_recall still gets a chance to krimto_supersede instead of
+   * duplicating. Omitted when nothing similar was found.
+   */
+  related?: RelatedFact[];
 }
 
 export interface RecallInput {
@@ -148,6 +160,39 @@ function writableScopesFor(ctx: ToolContext): string[] {
   return scopes;
 }
 
+/**
+ * Token-cosine bar above which an existing fact is "the same thing, said again" rather than
+ * merely sharing a word. Tuned from the smoke-6 cases: a near-duplicate (pizza vs pizza+sushi)
+ * scores ~0.8 and a same-topic update (pizza vs tacos) ~0.7, while two facts that only share a
+ * generic qualifier (favorite FOOD vs favorite COLOR) score ~0.38. 0.5 sits cleanly between.
+ */
+const DUPLICATE_SIMILARITY_THRESHOLD = 0.5;
+
+/**
+ * Existing facts in `scope` that closely resemble `${title} ${body}` — the server-side backstop
+ * for the "call krimto_recall first" rule. FTS narrows the candidate set; token cosine then
+ * filters out facts that merely share a generic word. Excludes anything the new write already
+ * supersedes (no point nagging about a fact it's replacing). Top 3, most-similar first.
+ */
+async function findRelatedFacts(
+  ctx: ToolContext,
+  scope: string,
+  title: string,
+  body: string,
+  supersedes: string[] | undefined,
+  now: Date,
+): Promise<RelatedFact[]> {
+  const text = `${title} ${body}`;
+  const candidates = await ctx.index.searchCandidates(text, { readableScopes: [scope], now });
+  const excluded = new Set(supersedes ?? []);
+  return candidates
+    .filter((c) => !excluded.has(c.id))
+    .map((c) => ({ id: c.id, title: c.title, score: lexicalSimilarity(text, `${c.title} ${c.body}`) }))
+    .filter((r) => r.score >= DUPLICATE_SIMILARITY_THRESHOLD)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 3);
+}
+
 /** Create a new fact. Author comes from the requester identity; scope is required. */
 export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<WriteResult> {
   // "user/me"/"user/self" (and bare "me"/"self") mean the caller's own personal scope. An agent
@@ -179,6 +224,14 @@ export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<
     });
   }
   return ctx.writeQueue.run(async () => {
+    // Run the near-duplicate check BEFORE the new fact is indexed, so it can't match itself.
+    // Best-effort: a failure here must never block a write — the hint is observational.
+    let related: RelatedFact[] = [];
+    try {
+      related = await findRelatedFacts(ctx, scope, input.title, input.body, input.supersedes, clock(ctx));
+    } catch {
+      /* dedup hint is advisory — never let it break the write path */
+    }
     const fact = createFact({
       scope,
       title: input.title,
@@ -224,6 +277,12 @@ export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<
         `git auto-commits every 30s, run \`npx @krimto-labs/krimto --help\` for the full CLI surface, ` +
         `or \`npx @krimto-labs/krimto storage\` for the storage model.)`;
     }
+    if (related.length > 0) {
+      const list = related.map((r) => `"${r.title}" (${r.id})`).join(", ");
+      hint +=
+        `\n⚠ Similar existing fact${related.length > 1 ? "s" : ""} in this scope: ${list}. ` +
+        `If this updates ${related.length > 1 ? "one of them" : "it"}, call krimto_supersede instead of leaving a duplicate.`;
+    }
     return {
       id: fact.frontmatter.id,
       scope: fact.frontmatter.scope,
@@ -231,6 +290,7 @@ export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<
       absolute_path: absolutePath,
       hint,
       commit_sha: null,
+      ...(related.length > 0 ? { related } : {}),
     };
   });
 }

package/src/web/router.ts

@@ -20,10 +20,12 @@ export interface WebRouterDeps {
   keys: ApiKeyStore;
   membership: () => Membership;
   sessionSecret: string;
-  /** When set, enables the admin-only /ui/admin page. */
+  /** When set, enables the admin-only /ui/admin page (only reachable in team mode). */
   admin?: AdminContext;
-  /** When set (local mode), skip login and use this identity for every request. */
-  localIdentity?: string;
+  /** Live team-mode predicate. Evaluated per request: team ⇒ require login; solo ⇒ use localIdentity. */
+  teamModeActive: () => boolean;
+  /** The local/solo identity — used (no login) whenever team mode is NOT active. Always provided. */
+  localIdentity: string;
   /** Live status snapshot for the /ui/facts status panel. Called per request so it's never stale. */
   status?: () => StatusPanelOpts;
 }
@@ -64,8 +66,8 @@ export function buildWebRouter(deps: WebRouterDeps): Router {
   });
 
   router.use((req, res, next) => {
-    if (deps.localIdentity) {
-      (req as WithIdentity).identity = deps.localIdentity; // local mode: no login
+    if (!deps.teamModeActive()) {
+      (req as WithIdentity).identity = deps.localIdentity; // solo mode: no login
       next();
       return;
     }
@@ -84,7 +86,7 @@ export function buildWebRouter(deps: WebRouterDeps): Router {
 
   router.get("/connect", (req, res) => {
     const host = typeof req.headers.host === "string" ? req.headers.host : "localhost:8080";
-    page(res, 200, "Connect", connectPanel({ host, requireAuth: !deps.localIdentity }), idOf(req));
+    page(res, 200, "Connect", connectPanel({ host, requireAuth: deps.teamModeActive() }), idOf(req));
   });
 
   router.get("/settings", (req, res) => {