@inixiative/archive 0.2.1 → 0.3.0

package/README.md

@@ -39,11 +39,11 @@ bun run archive list
 bun run archive search --query 'migration'
 ```
 
-Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. Nested checkouts are separate mappings. Unknown directories, symlinks and sessions without usable metadata are skipped. Incomplete or changing files remain at source and retry on the next scan. The initial collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. It retains prior manually assigned tags. It does not upload: run sync separately.
+Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. Repeat `--project-root` to map several checkouts to one project; `--worktrees` also accepts every current git worktree of each root, re-read on each scan. Nested checkouts are separate mappings. Unknown directories, symlinks and sessions without usable metadata are skipped. Incomplete or changing files remain at source and retry on the next scan. The initial collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. It retains prior manually assigned tags. It does not upload: run sync separately.
 
 ## Connect to BYO hosting
 
-Deploy the included Dockerfile with a persistent volume mounted at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. Compose binds only to loopback; put an HTTPS reverse proxy in front for remote use. Railway needs a `/data` volume. The Render blueprint provisions a dedicated disk and generated token.
+Deploy the included Dockerfile with a persistent volume mounted at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. Compose bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data`, so the store survives rebuilds, `down -v` and volume prunes, and binds only to loopback on port 4411 (or `ARCHIVE_PORT`); put an HTTPS reverse proxy in front for remote use. Railway needs a `/data` volume. The Render blueprint provisions a dedicated disk and generated token.
 
 Place the destination's token in an environment variable, then run:
 
@@ -61,13 +61,19 @@ bun run archive search --remote --query 'migration'
 
 ## Connect through Kingdom
 
-Use Kingdom's existing runtime enrollment for a user who manages the destination Kastle, then:
+Pair a runtime with Kingdom (Foundry: Settings → Kingdom) and expose its `kastle_runtime_` credential in an environment variable, then either let Kingdom store the archives:
 
 ```sh
-bun run archive connect --kind kingdom --url https://your-kingdom.example --kastle-id UUID --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+bun run archive connect --kind kingdom --url https://your-kingdom.example --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
 ```
 
-Optional repeated `--keep-id UUID` places sessions in Keeps owned by that Kastle. A Kingdom runtime credential is distinct from a standalone Archive token. Kingdom retains responsibility for user memberships, shares, revocation and hosted browsing. Connecting directly to Archive does not automatically register that server as a Kastle resource or mirror it into Kingdom; these are separate destinations.
+or forward them through Kingdom to a hosted Archive it has bound for that project:
+
+```sh
+bun run archive connect --kind kingdom --url https://your-kingdom.example --connection-id inixiative --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+```
+
+Kingdom takes the owner from the runtime credential; `--owner-model`, `--organization-id` and `--space-id` narrow it to an organization or space that owner manages. A forwarding connection accepts only its bound `projectId`, and the hosted Archive's own token stays in Kingdom's server environment. A Kingdom runtime credential is distinct from a standalone Archive token. Kingdom retains responsibility for memberships, shares, revocation and hosted browsing.
 
 Foundry exposes the same commands through `bun run archive`. Its defaults remain `.foundry/archives/archives.sqlite` and `.foundry/archives.json`. Its durable journal capture automatically publishes matching projects once destination credentials are in the viewer's environment. Restart the viewer after changing destination configuration.
 
@@ -79,7 +85,9 @@ Only explicit `projectId` matches authorize publication. An archive with no matc
 bun run archive tag --id ARCHIVE_ID --tag reviewed
 ```
 
-Tags and heuristic category suggestions do not change ownership or routing. Jev integration is not enabled: the next step is labeled, shadow-mode tag/destination proposals, scored for accuracy and cross-organization mistakes before any automatic action. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
+Collectors add explicit tags from recorded session metadata: `repo:owner/name` and `branch:name` from git context, and with `--atlas` the `atlas:<concept>` of repository files the session's tool calls touched (from `atlas graph --json` in the session's checkout). Suggestions are computed on read and never stored: heuristic categories, plus `reference` suggestions for linked GitHub pull requests, issues and commits (`github:owner/repo#24`, `github:owner/repo@sha`) and Linear issues (`linear:KEY-12`). A link is a mention, not proof of work, so references stay suggestions.
+
+Tags and suggestions do not change ownership or routing. Jev integration is not enabled: the next step is labeled, shadow-mode tag/destination proposals, scored for accuracy and cross-organization mistakes before any automatic action. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/archive",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -13,7 +13,8 @@
     "./preview": "./src/preview.ts",
     "./cli": "./src/cli.ts",
     "./collector": "./src/collector.ts",
-    "./chatgpt": "./src/chatgpt.ts"
+    "./chatgpt": "./src/chatgpt.ts",
+    "./tags": "./src/tags.ts"
   },
   "files": [
     "src"
@@ -34,7 +35,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.34",
+    "@inixiative/config": "^0.5.36",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/cli.ts

@@ -7,6 +7,7 @@ import { parseArgs } from 'node:util';
 import { importChatGPTThread } from './chatgpt';
 import {
   archiveRequest,
+  kingdomFields,
   publishArchive,
   routingPreview,
   searchRemotes,
@@ -31,8 +32,10 @@ export async function runCli(args = Bun.argv.slice(2)) {
       url: { type: 'string' },
       kind: { type: 'string', default: 'archive' },
       'project-id': { type: 'string' },
-      'kastle-id': { type: 'string' },
-      'keep-id': { type: 'string', multiple: true },
+      'connection-id': { type: 'string' },
+      'owner-model': { type: 'string' },
+      'organization-id': { type: 'string' },
+      'space-id': { type: 'string' },
       'token-env': { type: 'string', default: 'ARCHIVE_TOKEN' },
       'token-file': { type: 'string' },
       file: { type: 'string' },
@@ -42,7 +45,9 @@ export async function runCli(args = Bun.argv.slice(2)) {
       'session-id': { type: 'string' },
       id: { type: 'string' },
       query: { type: 'string', default: '' },
-      'project-root': { type: 'string' },
+      'project-root': { type: 'string', multiple: true },
+      worktrees: { type: 'boolean', default: false },
+      atlas: { type: 'boolean', default: false },
       tag: { type: 'string', multiple: true },
       limit: { type: 'string', default: '100' },
       port: { type: 'string', default: process.env.PORT ?? '4411' },
@@ -61,9 +66,9 @@ export async function runCli(args = Bun.argv.slice(2)) {
   if (v.help || !command) {
     console.log(
       'Archive: init | serve | connect (setup) | preview | import | collect | list | export | tag | routes | sync | search\n' +
-        'connect --url HTTPS_URL --project-id ID --token-env ENV [--kind kingdom --kastle-id UUID]\n' +
+        'connect --url HTTPS_URL --project-id ID --token-env ENV [--kind kingdom [--connection-id ID] [--owner-model M --organization-id UUID --space-id UUID]]\n' +
         'import --file PATH --source codex|claude-code --project-id ID [--tag TAG]\n' +
-        'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD --project-id ID [--watch]\n' +
+        'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD [--project-root ...] [--worktrees] [--atlas] --project-id ID [--watch]\n' +
         'sync [--watch] | routes | search --query TEXT [--remote]\n' +
         'serve --home PATH [--port 4411 --hostname 127.0.0.1]\n' +
         'All commands accept --home PATH; integrations may use --store FILE --config FILE.',
@@ -107,7 +112,14 @@ export async function runCli(args = Bun.argv.slice(2)) {
       url: v.url,
       tokenEnv: v['token-env'],
       kind: v.kind,
-      ...(v.kind === 'kingdom' ? { kastleId: v['kastle-id'], keepIds: v['keep-id'] ?? [] } : {}),
+      ...(v.kind === 'kingdom'
+        ? {
+            connectionId: v['connection-id'],
+            ownerModel: v['owner-model'],
+            organizationId: v['organization-id'],
+            spaceId: v['space-id'],
+          }
+        : {}),
     });
     // Verify credentials and protocol before saving; no records uploaded by setup.
     const probe = await archiveRequest(destination, 'search', {
@@ -116,7 +128,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
       limit: 1,
       ...(destination.kind === 'archive'
         ? { projectId: destination.projectId }
-        : { kastleId: destination.kastleId }),
+        : kingdomFields(destination)),
     });
     if (!Array.isArray(probe.data?.archives))
       throw new Error('Destination is not an Archive-compatible endpoint');
@@ -195,7 +207,9 @@ export async function runCli(args = Bun.argv.slice(2)) {
           const result = await collectSessions(store, {
             directory: v.directory!,
             source: v.source as 'codex' | 'claude-code',
-            projectRoot: v['project-root']!,
+            projectRoots: v['project-root']!,
+            worktrees: v.worktrees,
+            atlas: v.atlas,
             projectId: v['project-id']!,
             tags: v.tag,
           });

package/src/client.ts

@@ -8,6 +8,17 @@ import type { LocalArchiveStore } from './local';
 
 export { type ArchiveDestination, archiveDestinationSchema } from './config';
 
+/** Identifies the Kingdom owner and forwarding connection; standalone Archive needs neither. */
+export function kingdomFields(destination: ArchiveDestination) {
+  if (destination.kind === 'archive') return {};
+  const { ownerModel, organizationId, spaceId, connectionId } = destination;
+  return Object.fromEntries(
+    Object.entries({ ownerModel, organizationId, spaceId, connectionId }).filter(
+      ([, value]) => value !== undefined,
+    ),
+  );
+}
+
 export async function archiveRequest(
   destination: ArchiveDestination,
   action: string,
@@ -16,9 +27,11 @@ export async function archiveRequest(
 ) {
   const url = destinationUrl(destination.url);
   const token = process.env[destination.tokenEnv];
-  if (!token || (destination.kind !== 'archive' && !token.startsWith('kastle_runtime_')))
+  if (!token || (destination.kind === 'kingdom' && !token.startsWith('kastle_runtime_')))
     throw new Error('Archive runtime credential unavailable');
-  const response = await transport(new URL(`api/v1/archive/${action}`, url), {
+  const path =
+    destination.kind === 'kingdom' && destination.connectionId ? `remote/${action}` : action;
+  const response = await transport(new URL(`api/v1/archive/${path}`, url), {
     method: 'POST',
     redirect: 'error',
     signal: AbortSignal.timeout(30_000),
@@ -41,19 +54,14 @@ export async function publishArchive(
   if (!archive || archive.snapshot.projectId !== destination.projectId)
     throw new Error('Archive is outside destination project');
   const receiptKey = destinationIdentity(destination);
-  const keepIds = [...new Set(destination.keepIds)].sort();
   let sent = false;
   for (let attempt = 0; attempt < 8; attempt++) {
     const latest = store.read(id)!;
     const previousDigest = store.receipt(id, receiptKey);
     let pending = store.pending(id, receiptKey);
     if (!pending) {
-      if (
-        previousDigest === latest.digest &&
-        store.receipt(id, `${receiptKey}:keeps`) === JSON.stringify(keepIds)
-      )
-        return { unchanged: !sent };
-      store.enqueue(id, receiptKey, { revision: latest.revision, keepIds });
+      if (previousDigest === latest.digest) return { unchanged: !sent };
+      store.enqueue(id, receiptKey, { revision: latest.revision, keepIds: [] });
       pending = store.pending(id, receiptKey)!;
     }
     const queued = store.read(id, pending.revision);
@@ -63,16 +71,14 @@ export async function publishArchive(
       destination,
       'ingest',
       {
-        ...(destination.kind === 'archive'
-          ? {}
-          : { kastleId: destination.kastleId, keepIds: pending.keepIds }),
+        ...kingdomFields(destination),
         previousDigest,
         snapshot: queued.snapshot,
       },
       transport,
     );
     if (body.data?.digest !== queued.digest) throw new Error('Archive acknowledgement mismatch');
-    store.delivered(id, receiptKey, queued.digest, JSON.stringify(pending.keepIds));
+    store.delivered(id, receiptKey, queued.digest, '[]');
     sent = true;
   }
   throw new Error('Archive changed repeatedly during publication; retry sync');
@@ -87,9 +93,9 @@ export function routingPreview(store: LocalArchiveStore, destinations: ArchiveDe
     destinations: destinations
       .filter((d) => d.projectId === archive.projectId)
       .map((d) => ({
-        kind: d.kind ?? 'kingdom',
+        kind: d.kind,
         url: d.url,
-        ...(d.kind === 'archive' ? {} : { kastleId: d.kastleId }),
+        ...kingdomFields(d),
       })),
   }));
 }
@@ -129,7 +135,7 @@ export async function searchRemotes(
           budget,
           ...(destination.kind === 'archive'
             ? { projectId: destination.projectId }
-            : { kastleId: destination.kastleId }),
+            : kingdomFields(destination)),
         });
         return {
           destination: destination.url,

package/src/collector.ts

@@ -1,15 +1,19 @@
-import { createReadStream, lstatSync, readdirSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { createInterface } from 'node:readline';
+import { closeSync, existsSync, lstatSync, openSync, readdirSync, readSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
 import { importTranscriptFile } from './import-file';
 import { archiveKey } from './index';
 import type { LocalArchiveStore } from './local';
+import { type AtlasFileConcepts, atlasTags, provenanceTags } from './tags';
 
 export interface CollectionSource {
   directory: string;
   source: 'codex' | 'claude-code';
-  projectRoot: string;
+  projectRoots: string[];
   projectId: string;
+  /** Also match the git worktrees of each root; nested checkouts stay separate. */
+  worktrees?: boolean;
+  /** Tag sessions with the Atlas concepts of files they touched, from `atlas graph` in the session's checkout. */
+  atlas?: boolean;
   tags?: string[];
 }
 
@@ -25,36 +29,88 @@ function files(directory: string): string[] {
   return result;
 }
 
+type SessionMetadata = { cwd: string; branch?: string; repository?: string };
+
 /** Match provider metadata, never text/tags/model suggestions. No implicit parent-directory routing. */
-async function sessionDirectory(file: string, source: CollectionSource['source']) {
-  const input = createReadStream(file, { encoding: 'utf8', end: 1_000_000 });
-  const lines = createInterface({ input, crlfDelay: Infinity });
+function sessionMetadata(
+  file: string,
+  source: CollectionSource['source'],
+): SessionMetadata | undefined {
+  // A bounded synchronous read: streamed readline could leave a watch loop waiting forever.
+  const buffer = Buffer.alloc(Math.min(lstatSync(file).size, 1_000_000));
+  const fd = openSync(file, 'r');
   try {
-    for await (const line of lines) {
-      let row: any;
-      try {
-        row = JSON.parse(line);
-      } catch {
-        return undefined;
-      }
-      const cwd =
-        source === 'codex' ? (row.type === 'session_meta' ? row.payload?.cwd : undefined) : row.cwd;
-      if (typeof cwd === 'string' && isAbsolute(cwd)) return resolve(cwd);
-    }
+    readSync(fd, buffer, 0, buffer.length, 0);
   } finally {
-    lines.close();
-    input.destroy();
+    closeSync(fd);
+  }
+  for (const line of buffer.toString('utf8').split('\n')) {
+    if (!line) continue;
+    let row: any;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      return undefined;
+    }
+    const meta = source === 'codex' ? (row.type === 'session_meta' ? row.payload : undefined) : row;
+    if (typeof meta?.cwd !== 'string' || !isAbsolute(meta.cwd)) continue;
+    const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+    return source === 'codex'
+      ? {
+          cwd: resolve(meta.cwd),
+          branch: text(meta.git?.branch),
+          repository: text(meta.git?.repository_url),
+        }
+      : { cwd: resolve(meta.cwd), branch: text(meta.gitBranch) };
   }
 }
 
+const git = (cwd: string, ...args: string[]) => {
+  const run = Bun.spawnSync(['git', '-C', cwd, ...args], { stderr: 'ignore' });
+  return run.success ? run.stdout.toString().trim() : undefined;
+};
+
+function atlasGraph(cwd: string): AtlasFileConcepts | undefined {
+  if (!existsSync(`${cwd}/.atlas`)) return;
+  const run = Bun.spawnSync([process.execPath, 'x', 'atlas', 'graph', '--json'], {
+    cwd,
+    stderr: 'ignore',
+  });
+  if (!run.success) return;
+  try {
+    return JSON.parse(run.stdout.toString()).fileToConcepts;
+  } catch {}
+}
+
+function worktreesOf(root: string): string[] {
+  const listed = Bun.spawnSync(['git', '-C', root, 'worktree', 'list', '--porcelain'], {
+    stderr: 'ignore',
+  });
+  if (!listed.success) return [];
+  return listed.stdout
+    .toString()
+    .split('\n')
+    .filter((line) => line.startsWith('worktree '))
+    .map((line) => resolve(line.slice('worktree '.length)));
+}
+
+/** Exact directories this collection accepts, re-read each scan so new worktrees join. */
+export function collectionRoots(config: CollectionSource): Set<string> {
+  const roots = config.projectRoots.map((root) => resolve(root));
+  return new Set(config.worktrees ? [...roots, ...roots.flatMap(worktreesOf)] : roots);
+}
+
 export async function collectSessions(store: LocalArchiveStore, config: CollectionSource) {
-  const root = resolve(config.projectRoot);
+  const roots = collectionRoots(config);
   const result = { imported: 0, unchanged: 0, skipped: 0, failed: 0 };
+  // Per scan: checkouts change between scans.
+  const repositories = new Map<string, string | undefined>();
+  const graphs = new Map<string, AtlasFileConcepts | undefined>();
   for (const file of files(config.directory)) {
     try {
-      const cwd = await sessionDirectory(file, config.source);
+      const meta = sessionMetadata(file, config.source);
       // Exact root selection avoids sweeping nested checkouts belonging to another organization.
-      if (!cwd || relative(root, cwd) !== '') {
+      if (!meta || !roots.has(meta.cwd)) {
         result.skipped++;
         continue;
       }
@@ -74,7 +130,21 @@ export async function collectSessions(store: LocalArchiveStore, config: Collecti
         result.failed++;
         continue;
       }
-      snapshot.tags = [...new Set([...(old?.snapshot.tags ?? []), ...(config.tags ?? [])])];
+      const { cwd } = meta;
+      if (!repositories.has(cwd)) repositories.set(cwd, git(cwd, 'remote', 'get-url', 'origin'));
+      if (config.atlas && !graphs.has(cwd)) graphs.set(cwd, atlasGraph(cwd));
+      const graph = graphs.get(cwd);
+      snapshot.tags = [
+        ...new Set([
+          ...(old?.snapshot.tags ?? []),
+          ...(config.tags ?? []),
+          ...provenanceTags({
+            branch: meta.branch,
+            repository: meta.repository ?? repositories.get(cwd),
+          }),
+          ...(graph ? atlasTags(snapshot, graph, roots) : []),
+        ]),
+      ].slice(0, 100);
       if (store.capture(snapshot).changed) result.imported++;
       else result.unchanged++;
     } catch {

package/src/config.ts

@@ -8,17 +8,28 @@ const common = {
   url: z.url(),
   tokenEnv: z.string().regex(/^[A-Z][A-Z0-9_]+$/),
 };
+/** Kingdom derives the owner from the runtime credential; these narrow it to a space or organization it manages. */
+export const kingdomOwnerFields = {
+  ownerModel: z.enum(['User', 'OrganizationUser', 'Organization', 'Space', 'SpaceUser']).optional(),
+  organizationId: z.uuid().optional(),
+  spaceId: z.uuid().optional(),
+};
 export const archiveDestinationSchema = z.union([
   z.strictObject({
     ...common,
     kind: z.literal('archive'),
-    keepIds: z.array(z.string()).max(0).default([]),
+    keepIds: z.array(z.string()).max(0).optional(),
   }),
   z.strictObject({
     ...common,
-    kind: z.literal('kingdom').optional(),
-    kastleId: z.uuid(),
-    keepIds: z.array(z.uuid()).max(50).default([]),
+    kind: z.literal('kingdom'),
+    /** A hosted Archive that Kingdom forwards to; omitted, Kingdom stores the archive itself. */
+    connectionId: z
+      .string()
+      .regex(/^[a-z0-9-]+$/)
+      .max(120)
+      .optional(),
+    ...kingdomOwnerFields,
   }),
 ]);
 export type ArchiveDestination = z.infer<typeof archiveDestinationSchema>;
@@ -52,7 +63,14 @@ export function destinationIdentity(destination: ArchiveDestination) {
   return JSON.stringify([
     url.origin,
     new URL(destination.url).pathname,
-    destination.kind === 'archive' ? 'standalone' : destination.kastleId,
+    destination.kind === 'archive'
+      ? 'standalone'
+      : [
+          destination.connectionId ?? 'kingdom',
+          destination.ownerModel ?? null,
+          destination.organizationId ?? null,
+          destination.spaceId ?? null,
+        ],
   ]);
 }
 export function connectDestination(file: string, input: unknown) {
@@ -72,7 +90,7 @@ export function connectDestination(file: string, input: unknown) {
   chmodSync(file, 0o600);
   return {
     configured: true,
-    kind: destination.kind ?? 'kingdom',
+    kind: destination.kind,
     projectId: destination.projectId,
     url: destination.url,
     tokenEnv: destination.tokenEnv,

package/src/import.ts

@@ -40,8 +40,13 @@ export function importTranscriptLines(
       sessionId ??= id;
     }
     if (options.source === 'claude-code' && row.sessionId) {
-      if (sessionId && sessionId !== row.sessionId) throw new Error('Mixed transcript sessions');
-      sessionId = row.sessionId;
+      // Subagent transcripts reuse their parent's sessionId; each is its own archive.
+      const id =
+        row.isSidechain && typeof row.agentId === 'string'
+          ? `${row.sessionId}/agent-${row.agentId}`
+          : row.sessionId;
+      if (sessionId && sessionId !== id) throw new Error('Mixed transcript sessions');
+      sessionId = id;
     }
     const timestamp = typeof row.timestamp === 'number' ? row.timestamp : Date.parse(row.timestamp);
     const add = (kind: ArchiveEntry['kind'], content: unknown, suffix: string, callId?: string) => {

package/src/local.ts

@@ -7,11 +7,11 @@ import {
   type ArchiveSnapshot,
   archiveKey,
   archiveSnapshotSchema,
-  categorySuggestions,
   chunkArchive,
   selectChunks,
   snapshotDigest,
 } from './index';
+import { suggestTags } from './tags';
 
 export class LocalArchiveStore {
   private readonly db: Database;
@@ -94,7 +94,7 @@ export class LocalArchiveStore {
         digest: archive.digest,
         ...snapshot,
         entries: entries.length,
-        suggestedTags: categorySuggestions(archive.snapshot),
+        suggestedTags: suggestTags(archive.snapshot),
       };
     });
   }

package/src/tags.ts

@@ -0,0 +1,78 @@
+import { type ArchiveSnapshot, categorySuggestions } from './index';
+
+export type TagSuggestion = { tag: string; origin: 'heuristic' | 'reference' };
+
+const references: [RegExp, (match: RegExpExecArray) => string][] = [
+  [
+    /github\.com\/([\w.-]+)\/([\w.-]+)\/(?:pull|issues)\/(\d+)/g,
+    (m) => `github:${m[1]}/${m[2]}#${m[3]}`.toLowerCase(),
+  ],
+  [
+    /github\.com\/([\w.-]+)\/([\w.-]+)\/commit\/([0-9a-f]{7,40})\b/g,
+    (m) => `github:${m[1]}/${m[2]}@${m[3].slice(0, 7)}`.toLowerCase(),
+  ],
+  [
+    /linear\.app\/[\w-]+\/issue\/([A-Za-z][A-Za-z0-9]*-\d+)/g,
+    (m) => `linear:${m[1].toUpperCase()}`,
+  ],
+];
+
+/** Issues, pull requests and commits the transcript links to, most-referenced first. A mention is not proof of work, so these stay suggestions. */
+export function referenceSuggestions(snapshot: ArchiveSnapshot, limit = 25): TagSuggestion[] {
+  const counts = new Map<string, number>();
+  for (const entry of snapshot.entries)
+    for (const [pattern, tag] of references)
+      for (const match of entry.text.matchAll(pattern)) {
+        const value = tag(match);
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+      }
+  return [...counts]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([tag]) => ({ tag, origin: 'reference' }));
+}
+
+/** Every computed suggestion for an archive. Suggestions never route or authorize. */
+export function suggestTags(snapshot: ArchiveSnapshot): TagSuggestion[] {
+  return [...categorySuggestions(snapshot), ...referenceSuggestions(snapshot)];
+}
+
+/** Recorded git context of a session, as explicit tags. */
+export function provenanceTags(context: { repository?: string; branch?: string }): string[] {
+  const repository = context.repository?.match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/);
+  return [
+    ...(repository ? [`repo:${repository[1].toLowerCase()}`] : []),
+    ...(context.branch && context.branch !== 'HEAD' ? [`branch:${context.branch}`] : []),
+  ].filter((tag) => tag.length <= 120);
+}
+
+/** `atlas graph --json`: repository-relative file paths to the concepts they are part of. */
+export type AtlasFileConcepts = Record<string, { partOf: string[] }>;
+
+/** Atlas concepts of the repository files a session's tool calls touched. */
+export function atlasTags(
+  snapshot: ArchiveSnapshot,
+  fileToConcepts: AtlasFileConcepts,
+  roots: Iterable<string>,
+  limit = 20,
+): string[] {
+  // Longest first: worktrees can live inside their main checkout.
+  const prefixes = [...roots]
+    .map((root) => `${root.replace(/\/+$/, '')}/`)
+    .sort((a, b) => b.length - a.length);
+  const counts = new Map<string, number>();
+  for (const entry of snapshot.entries) {
+    if (entry.kind !== 'tool-call') continue;
+    for (const [path] of entry.text.matchAll(/[\w@.~/-]+\.[A-Za-z]{1,6}\b/g)) {
+      const prefix = prefixes.find((candidate) => path.startsWith(candidate));
+      const relative = prefix ? path.slice(prefix.length) : path;
+      for (const concept of fileToConcepts[relative]?.partOf ?? [])
+        counts.set(concept, (counts.get(concept) ?? 0) + 1);
+    }
+  }
+  return [...counts]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([concept]) => `atlas:${concept}`)
+    .filter((tag) => tag.length <= 120);
+}