codetrap 0.1.6 → 0.1.8

package/src/db/embedding-queries.ts

@@ -5,15 +5,17 @@ import {
   decodeEmbedding,
   encodeEmbedding,
   type EmbeddingConfig,
+  embeddingProfileId,
   type FreshEmbedding,
   type StoredEmbedding,
 } from "../lib/embedder";
 import type { EmbeddingStateCounts } from "../lib/embedding-health";
-import { embeddingIsFresh, passageHashForTrap } from "../lib/trap-search-document";
-import { countTraps, listTraps } from "./queries";
+import { passageHashForTrap } from "../lib/trap-search-document";
+import { countTraps } from "./queries";
 
 type TrapEmbeddingRow = {
   trap_id: number;
+  profile_id: string;
   provider: string;
   model: string;
   dimensions: number;
@@ -23,33 +25,98 @@ type TrapEmbeddingRow = {
   updated_at: string;
 };
 
-export function getEmbedding(db: Database, trapId: number): StoredEmbedding | null {
+export type EmbeddingProfileSummary = {
+  id: string;
+  provider: string;
+  model: string;
+  dimensions: number;
+  passage_version: number;
+  embedding_count: number;
+  updated_at: string | null;
+};
+
+type EmbeddingProfileRow = Omit<EmbeddingProfileSummary, "embedding_count"> & {
+  embedding_count: number;
+};
+
+type TrapEmbeddingStateRow = Trap & {
+  embedding_passage_hash: string | null;
+};
+
+type TrapAnyEmbeddingStateRow = Trap & {
+  has_embedding: number;
+};
+
+export function getEmbedding(
+  db: Database,
+  trapId: number,
+  config?: EmbeddingConfig
+): StoredEmbedding | null {
+  const profileClause = config ? "AND e.profile_id = ?" : "";
+  const params: SQLQueryBindings[] = [trapId];
+  if (config) params.push(embeddingProfileId(config));
+
   const row = db
-    .query("SELECT * FROM trap_embeddings WHERE trap_id = ?")
-    .get(trapId) as TrapEmbeddingRow | null;
+    .query(`
+      SELECT
+        e.trap_id,
+        e.profile_id,
+        p.provider,
+        p.model,
+        p.dimensions,
+        p.passage_version,
+        e.passage_hash,
+        e.embedding,
+        e.updated_at
+      FROM trap_embeddings e
+      JOIN embedding_profiles p ON p.id = e.profile_id
+      WHERE e.trap_id = ? ${profileClause}
+      ORDER BY e.updated_at DESC
+      LIMIT 1
+    `)
+    .get(...params) as TrapEmbeddingRow | null;
   return row ? rowToStoredEmbedding(row) : null;
 }
 
 export function upsertEmbedding(db: Database, record: StoredEmbedding): void {
+  const profileId = record.profile_id || embeddingProfileId({
+    provider: record.provider,
+    model: record.model,
+    dimensions: record.dimensions,
+    passageVersion: record.passage_version,
+  });
+
   db.prepare(`
-    INSERT INTO trap_embeddings (
-      trap_id, provider, model, dimensions, passage_version, passage_hash, embedding, updated_at
+    INSERT INTO embedding_profiles (
+      id, provider, model, dimensions, passage_version, created_at, updated_at
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
-    ON CONFLICT(trap_id) DO UPDATE SET
+    VALUES (?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    ON CONFLICT(id) DO UPDATE SET
       provider = excluded.provider,
       model = excluded.model,
       dimensions = excluded.dimensions,
       passage_version = excluded.passage_version,
-      passage_hash = excluded.passage_hash,
-      embedding = excluded.embedding,
       updated_at = datetime('now')
   `).run(
-    record.trap_id,
+    profileId,
     record.provider,
     record.model,
     record.dimensions,
-    record.passage_version,
+    record.passage_version
+  );
+
+  db.prepare(`
+    INSERT INTO trap_embeddings (
+      trap_id, profile_id, passage_hash, embedding, updated_at
+    )
+    VALUES (?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(trap_id, profile_id) DO UPDATE SET
+      passage_hash = excluded.passage_hash,
+      embedding = excluded.embedding,
+      updated_at = datetime('now')
+  `).run(
+    record.trap_id,
+    profileId,
     record.passage_hash,
     encodeEmbedding(record.embedding)
   );
@@ -65,16 +132,10 @@ export function getAllFreshEmbeddings(
   opts: { category?: string; scope?: string; status?: TrapStatus | "all" } = {}
 ): FreshEmbedding[] {
   const conditions = [
-    "e.provider = ?",
-    "e.model = ?",
-    "e.dimensions = ?",
-    "e.passage_version = ?",
+    "e.profile_id = ?",
   ];
   const params: SQLQueryBindings[] = [
-    config.provider,
-    config.model,
-    config.dimensions,
-    config.passageVersion,
+    embeddingProfileId(config),
   ];
 
   if (opts.category) {
@@ -116,22 +177,11 @@ export function getTrapsNeedingEmbeddings(
   config: EmbeddingConfig,
   opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
 ): Trap[] {
-  const traps = listTraps(db, {
-    scope: opts.scope,
-    category: opts.category,
-    status: opts.status,
-    limit: 100000,
-  });
-  const needed: Trap[] = [];
-
-  for (const trap of traps) {
-    const embedding = getEmbedding(db, trap.id);
-    if (opts.force || !embeddingIsFresh(trap, embedding, config)) {
-      needed.push(trap);
-    }
-  }
-
-  return needed.slice(0, opts.limit ?? needed.length);
+  const rows = trapEmbeddingStateRows(db, config, opts);
+  const needed = opts.force
+    ? rows
+    : rows.filter((row) => row.embedding_passage_hash !== passageHashForTrap(row));
+  return needed.map(rowToTrap).slice(0, opts.limit ?? needed.length);
 }
 
 export function countEmbeddableTraps(
@@ -146,24 +196,20 @@ export function getEmbeddingStateCounts(
   config: EmbeddingConfig | null,
   opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
 ): EmbeddingStateCounts {
-  const traps = listTraps(db, {
-    scope: opts.scope,
-    category: opts.category,
-    status: opts.status,
-    limit: 100000,
-  });
+  if (!config) return getAnyEmbeddingStateCounts(db, opts);
+
+  const rows = trapEmbeddingStateRows(db, config, opts);
   const counts: EmbeddingStateCounts = {
-    total: traps.length,
+    total: rows.length,
     fresh: 0,
     stale: 0,
     missing: 0,
   };
 
-  for (const trap of traps) {
-    const embedding = getEmbedding(db, trap.id);
-    if (!embedding) {
+  for (const row of rows) {
+    if (!row.embedding_passage_hash) {
       counts.missing++;
-    } else if (config && embeddingIsFresh(trap, embedding, config)) {
+    } else if (row.embedding_passage_hash === passageHashForTrap(row)) {
       counts.fresh++;
     } else {
       counts.stale++;
@@ -173,9 +219,56 @@ export function getEmbeddingStateCounts(
   return counts;
 }
 
+export function listEmbeddingProfiles(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): EmbeddingProfileSummary[] {
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+
+  if (opts.category) {
+    conditions.push("t.category = ?");
+    params.push(opts.category);
+  }
+  if (opts.scope) {
+    conditions.push("t.scope = ?");
+    params.push(opts.scope);
+  }
+  if (opts.status !== "all") {
+    conditions.push("t.status = ?");
+    params.push(opts.status ?? DEFAULT_TRAP_STATUS);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const rows = db
+    .query(`
+      SELECT
+        p.id,
+        p.provider,
+        p.model,
+        p.dimensions,
+        p.passage_version,
+        COUNT(e.trap_id) AS embedding_count,
+        MAX(e.updated_at) AS updated_at
+      FROM embedding_profiles p
+      JOIN trap_embeddings e ON e.profile_id = p.id
+      JOIN traps t ON t.id = e.trap_id
+      ${where}
+      GROUP BY p.id, p.provider, p.model, p.dimensions, p.passage_version
+      ORDER BY updated_at DESC, p.provider ASC, p.model ASC
+    `)
+    .all(...params) as EmbeddingProfileRow[];
+
+  return rows.map((row) => ({
+    ...row,
+    embedding_count: Number(row.embedding_count),
+  }));
+}
+
 function rowToStoredEmbedding(row: TrapEmbeddingRow): StoredEmbedding {
   return {
     trap_id: row.trap_id,
+    profile_id: row.profile_id,
     provider: row.provider,
     model: row.model,
     dimensions: row.dimensions,
@@ -185,3 +278,92 @@ function rowToStoredEmbedding(row: TrapEmbeddingRow): StoredEmbedding {
     updated_at: row.updated_at,
   };
 }
+
+function getAnyEmbeddingStateCounts(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): EmbeddingStateCounts {
+  const rows = trapAnyEmbeddingStateRows(db, opts);
+  const stale = rows.filter((row) => row.has_embedding > 0).length;
+  return {
+    total: rows.length,
+    fresh: 0,
+    stale,
+    missing: rows.length - stale,
+  };
+}
+
+function trapEmbeddingStateRows(
+  db: Database,
+  config: EmbeddingConfig,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): TrapEmbeddingStateRow[] {
+  const conditions: string[] = [];
+  const filterParams = trapFilterParams(conditions, opts, "t");
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  return db
+    .query(`
+      SELECT
+        t.*,
+        e.passage_hash AS embedding_passage_hash
+      FROM traps t
+      LEFT JOIN trap_embeddings e
+        ON e.trap_id = t.id
+       AND e.profile_id = ?
+      ${where}
+      ORDER BY t.updated_at DESC
+      LIMIT 100000
+    `)
+    .all(embeddingProfileId(config), ...filterParams) as TrapEmbeddingStateRow[];
+}
+
+function trapAnyEmbeddingStateRows(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): TrapAnyEmbeddingStateRow[] {
+  const conditions: string[] = [];
+  const params = trapFilterParams(conditions, opts, "t");
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  return db
+    .query(`
+      SELECT
+        t.*,
+        EXISTS (
+          SELECT 1
+          FROM trap_embeddings e
+          WHERE e.trap_id = t.id
+        ) AS has_embedding
+      FROM traps t
+      ${where}
+      ORDER BY t.updated_at DESC
+      LIMIT 100000
+    `)
+    .all(...params) as TrapAnyEmbeddingStateRow[];
+}
+
+function trapFilterParams(
+  conditions: string[],
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" },
+  alias: string
+): SQLQueryBindings[] {
+  const params: SQLQueryBindings[] = [];
+  const prefix = `${alias}.`;
+  if (opts.category) {
+    conditions.push(`${prefix}category = ?`);
+    params.push(opts.category);
+  }
+  if (opts.scope) {
+    conditions.push(`${prefix}scope = ?`);
+    params.push(opts.scope);
+  }
+  if (opts.status !== "all") {
+    conditions.push(`${prefix}status = ?`);
+    params.push(opts.status ?? DEFAULT_TRAP_STATUS);
+  }
+  return params;
+}
+
+function rowToTrap(row: TrapEmbeddingStateRow): Trap {
+  const { embedding_passage_hash: _embeddingPassageHash, ...trap } = row;
+  return trap as Trap;
+}

package/src/db/queries.ts

@@ -179,10 +179,6 @@ export function listTrapEvidence(db: Database, trapId: number): TrapEvidence[] {
     .all(trapId) as TrapEvidence[];
 }
 
-export function archiveTrap(db: Database, id: number): boolean {
-  return markTrapArchived(db, id);
-}
-
 export function markTrapArchived(db: Database, id: number): boolean {
   const result = db
     .prepare(
@@ -198,27 +194,6 @@ export function markTrapArchived(db: Database, id: number): boolean {
   return result.changes > 0;
 }
 
-export function supersedeTrap(
-  db: Database,
-  id: number,
-  supersededById: number,
-  stateKey?: string
-): boolean {
-  if (id === supersededById) return false;
-
-  const oldTrap = getTrap(db, id);
-  const newTrap = getTrap(db, supersededById);
-  if (!oldTrap || !newTrap) return false;
-
-  const key = stateKey ?? oldTrap.state_key ?? newTrap.state_key ?? `trap:${id}`;
-  const tx = db.transaction(() => {
-    markTrapSuperseded(db, id, key);
-    markTrapSuperseding(db, supersededById, id, key);
-  });
-  tx();
-  return true;
-}
-
 export function markTrapSuperseded(db: Database, id: number, stateKey: string): boolean {
   const result = db.prepare(supersedeTrapSql).run(stateKey, id);
   return result.changes > 0;

package/src/db/repository.ts

@@ -11,32 +11,39 @@ import type {
 import { SearchService, type SearchOptions } from "../lib/search-service";
 import {
   type EmbeddingConfig,
-  type EmbeddingProvider,
   type StoredEmbedding,
 } from "../lib/embedder";
+import {
+  embeddingRuntimeFrom,
+  type EmbeddingRuntime,
+  type EmbeddingRuntimeInput,
+} from "../lib/embedding-runtime";
 import { runEmbeddingJob } from "../lib/embedding-job";
 import { passageFieldsChanged } from "../lib/trap-search-document";
+import * as embeddingQueries from "./embedding-queries";
 import * as queries from "./queries";
 import type { TrapStatus } from "../lib/constants";
 import { TrapSearchPolicy } from "../lib/search-policy";
-import { DatabaseEmbeddingIndex } from "../lib/embedding-index";
+import type { RankingConfig } from "../lib/search-policy";
 import { archiveTrapLifecycle, supersedeTrapLifecycle } from "../lib/trap-lifecycle";
+import type { EmbeddingProfileSummary } from "./embedding-queries";
 
 export type TrapStats = ReturnType<typeof queries.getStats>;
-export type EmbeddingStateCounts = ReturnType<DatabaseEmbeddingIndex["stateCounts"]>;
+export type EmbeddingStateCounts = ReturnType<typeof embeddingQueries.getEmbeddingStateCounts>;
 export type TrapRecordInsert = queries.TrapRecordInsert;
 
 export class TrapRepository {
   private readonly searchService: SearchService;
   private readonly searchPolicy = new TrapSearchPolicy();
-  private readonly embeddingIndex: DatabaseEmbeddingIndex;
+  private readonly embeddings: EmbeddingRuntime;
 
   constructor(
     private readonly db: Database,
-    private readonly embedder?: EmbeddingProvider
+    embeddings?: EmbeddingRuntimeInput,
+    ranking?: RankingConfig
   ) {
-    this.searchService = new SearchService(db, embedder);
-    this.embeddingIndex = new DatabaseEmbeddingIndex(db);
+    this.embeddings = embeddingRuntimeFrom(embeddings);
+    this.searchService = new SearchService(db, this.embeddings, ranking);
   }
 
   add(input: TrapInput): number {
@@ -79,7 +86,7 @@ export class TrapRepository {
   update(id: number, input: TrapUpdate): boolean {
     const success = queries.updateTrap(this.db, id, input);
     if (success && passageFieldsChanged(input)) {
-      this.embeddingIndex.delete(id);
+      embeddingQueries.deleteEmbedding(this.db, id);
     }
     return success;
   }
@@ -114,7 +121,11 @@ export class TrapRepository {
   }
 
   embeddingStats(config: EmbeddingConfig | null, opts: { scope?: string; status?: TrapStatus | "all" } = {}): EmbeddingStateCounts {
-    return this.embeddingIndex.stateCounts(config, opts);
+    return embeddingQueries.getEmbeddingStateCounts(this.db, config, opts);
+  }
+
+  embeddingProfiles(opts: { scope?: string; status?: TrapStatus | "all" } = {}): EmbeddingProfileSummary[] {
+    return embeddingQueries.listEmbeddingProfiles(this.db, opts);
   }
 
   exportAll(): TrapExportRecord[] {
@@ -145,23 +156,23 @@ export class TrapRepository {
     return this.db.transaction(callback)();
   }
 
-  getEmbedding(trapId: number): StoredEmbedding | null {
-    return this.embeddingIndex.get(trapId);
+  getEmbedding(trapId: number, config?: EmbeddingConfig): StoredEmbedding | null {
+    return embeddingQueries.getEmbedding(this.db, trapId, config);
   }
 
   upsertEmbedding(record: StoredEmbedding): void {
-    this.embeddingIndex.save(record);
+    embeddingQueries.upsertEmbedding(this.db, record);
   }
 
   deleteEmbedding(trapId: number): void {
-    this.embeddingIndex.delete(trapId);
+    embeddingQueries.deleteEmbedding(this.db, trapId);
   }
 
   getTrapsNeedingEmbeddings(
     config: EmbeddingConfig,
     opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
   ): Trap[] {
-    return this.embeddingIndex.trapsNeedingEmbeddings(config, opts);
+    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, opts);
   }
 
   async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{
@@ -169,18 +180,18 @@ export class TrapRepository {
     skipped: number;
     batches: number;
   }> {
-    if (!this.embedder) {
-      throw new Error("Embedding provider is unavailable. Set JINA_API_KEY to generate embeddings.");
-    }
+    const provider = this.embeddings.requireProvider(
+      "Embedding provider is unavailable. Configure an embedding provider to generate embeddings."
+    );
 
     return runEmbeddingJob(
       {
-        countEmbeddable: (countOpts) => this.embeddingIndex.countEmbeddable(countOpts),
+        countEmbeddable: (countOpts) => embeddingQueries.countEmbeddableTraps(this.db, countOpts),
         trapsNeedingEmbeddings: (config, jobOpts) =>
-          this.embeddingIndex.trapsNeedingEmbeddings(config, jobOpts),
-        saveEmbedding: (record) => this.embeddingIndex.save(record),
+          embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, jobOpts),
+        saveEmbedding: (record) => embeddingQueries.upsertEmbedding(this.db, record),
       },
-      this.embedder,
+      provider,
       opts
     );
   }

package/src/db/schema.ts

@@ -175,6 +175,86 @@ function applyMigrations(db: Database, from: number): void {
 
     db.prepare("UPDATE schema_version SET version = ?").run(5);
   }
+
+  if (from < 6) {
+    migrateEmbeddingProfiles(db);
+    db.prepare("UPDATE schema_version SET version = ?").run(6);
+  }
+}
+
+function migrateEmbeddingProfiles(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS embedding_profiles (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      model TEXT NOT NULL,
+      dimensions INTEGER NOT NULL,
+      passage_version INTEGER NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+
+  const hasTrapEmbeddings = tableExists(db, "trap_embeddings");
+  if (!hasTrapEmbeddings || columnExists(db, "trap_embeddings", "profile_id")) {
+    createProfileAwareEmbeddingsTable(db);
+    return;
+  }
+
+  db.exec("ALTER TABLE trap_embeddings RENAME TO trap_embeddings_legacy_v5");
+  createProfileAwareEmbeddingsTable(db);
+
+  db.exec(`
+    INSERT OR IGNORE INTO embedding_profiles (
+      id, provider, model, dimensions, passage_version, created_at, updated_at
+    )
+    SELECT
+      provider || ':' || model || ':' || dimensions || ':p' || passage_version,
+      provider,
+      model,
+      dimensions,
+      passage_version,
+      MIN(updated_at),
+      MAX(updated_at)
+    FROM trap_embeddings_legacy_v5
+    GROUP BY provider, model, dimensions, passage_version;
+
+    INSERT OR REPLACE INTO trap_embeddings (
+      trap_id, profile_id, passage_hash, embedding, updated_at
+    )
+    SELECT
+      trap_id,
+      provider || ':' || model || ':' || dimensions || ':p' || passage_version,
+      passage_hash,
+      embedding,
+      updated_at
+    FROM trap_embeddings_legacy_v5;
+
+    DROP TABLE trap_embeddings_legacy_v5;
+  `);
+}
+
+function createProfileAwareEmbeddingsTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS trap_embeddings (
+      trap_id INTEGER NOT NULL REFERENCES traps(id) ON DELETE CASCADE,
+      profile_id TEXT NOT NULL REFERENCES embedding_profiles(id) ON DELETE CASCADE,
+      passage_hash TEXT NOT NULL,
+      embedding BLOB NOT NULL,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (trap_id, profile_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_trap_embeddings_profile
+      ON trap_embeddings(profile_id);
+  `);
+}
+
+function tableExists(db: Database, table: string): boolean {
+  const row = db
+    .query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+    .get(table) as { name: string } | null;
+  return row !== null;
 }
 
 function columnExists(db: Database, table: string, column: string): boolean {

package/src/index.ts

@@ -15,8 +15,12 @@ if (args.length === 0) {
 } else if (args[0] === "serve") {
   import("./mcp/server").then((m) => m.start());
 } else if (args[0] === "web") {
-  const { startWebServerFromArgs } = await import("./web/server");
-  await startWebServerFromArgs(args.slice(1));
+  if (args.slice(1).some(isHelpArg)) {
+    showWebHelp();
+  } else {
+    const { startWebServerFromArgs } = await import("./web/server");
+    await startWebServerFromArgs(args.slice(1));
+  }
 } else if (args[0] === "init") {
   const cwd = process.cwd();
   if (findProjectRoot(cwd)) {
@@ -31,6 +35,10 @@ if (args.length === 0) {
   await run(args, store);
 }
 
+function isHelpArg(arg: string | undefined): boolean {
+  return arg === "--help" || arg === "-h" || arg === "help";
+}
+
 function showHelp(): void {
   console.log("codetrap — capture coding pitfalls so AI doesn't repeat mistakes");
   console.log("");
@@ -45,9 +53,10 @@ function showHelp(): void {
   console.log("  add_trap_evidence     Attach evidence to a trap");
   console.log("  archive_trap          Archive a trap");
   console.log("  supersede_trap        Mark one trap as superseded by another");
-  console.log("  embed                 Generate embeddings for semantic search");
+  console.log("  embed                 Generate embeddings for semantic search (Ollama or Jina)");
+  console.log("  embeddings            Manage embedding profiles, provider config, and reindexing");
   console.log("  session               Record implementation notes and capture candidate traps");
-  console.log("  web                   Start local candidate review console");
+  console.log("  web                   Start local review and trap library console");
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
@@ -68,12 +77,28 @@ function showHelp(): void {
   console.log("  --no-rerank             Disable query-aware search reranking");
   console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");
-  console.log("  --project <path>        Project path for web review console");
-  console.log("  --host <host>           Host for web review console (default 127.0.0.1)");
-  console.log("  --port <n>              Port for web review console (default 4737)");
+  console.log("  --project <path>        Project path for web console");
+  console.log("  --host <host>           Host for web console (default 127.0.0.1)");
+  console.log("  --port <n>              Port for web console (default 4737)");
   console.log("  --json                  JSON output for search/show/list/stats/doctor; JSON input for add/edit");
   console.log("  --output-json           JSON output for add/edit when --json is used as input");
   console.log("  --from-project-path <path>  Source project path for scope repair/migration");
   console.log("  --to-project-path <path>    Destination project path for scope repair/migration");
   console.log("  --dry-run|--apply       Preview or apply scope repair/migration");
 }
+
+function showWebHelp(): void {
+  console.log("codetrap web — start the local review and trap library console");
+  console.log("");
+  console.log("Usage:");
+  console.log("  codetrap web [--project <path>] [--host <host>] [--port <n>]");
+  console.log("");
+  console.log("Options:");
+  console.log("  --project <path>  Project path to open in the web console");
+  console.log("  --host <host>     Host to bind (default 127.0.0.1)");
+  console.log("  --port <n>        Port to try first (default 4737; next free port is used if busy)");
+  console.log("");
+  console.log("Examples:");
+  console.log("  codetrap web");
+  console.log("  codetrap web --project /path/to/project --port 4789");
+}