@ulysses-ai/create-workspace 0.14.0-beta.1 → 0.15.0-beta.0

package/template/.claude/recipes/migrate-from-notion.md

@@ -47,12 +47,12 @@ For each Notion page that contains project memory, context, or key decisions:
 ```
 Fetch the page content using the Notion MCP server.
 Determine scope:
-  - Architecture decisions, tech stack, stable conventions → shared-context/locked/
-  - Active project state, current priorities → shared-context/{user}/
+  - Architecture decisions, tech stack, stable conventions → workspace-context/shared/locked/
+  - Active project state, current priorities → workspace-context/team-member/{user}/
   - Historical context no longer relevant → skip
 
 For each section:
-  - Create a shared-context file with proper frontmatter:
+  - Create a workspace-context file with proper frontmatter:
     ---
     state: locked (or ephemeral)
     lifecycle: active
@@ -72,7 +72,7 @@ For each Notion page that contains session handoffs or context transfers:
 ```
 Fetch the page content using the Notion MCP server.
 For recent/active handoffs only (skip stale ones):
-  - Create shared-context/{user}/{handoff-name}.md
+  - Create workspace-context/team-member/{user}/{handoff-name}.md
   - Use handoff frontmatter format with type: handoff
   - Extract: status, key decisions, next steps, open questions
   - Set lifecycle: active (or paused if the work is suspended)
@@ -84,7 +84,7 @@ Check `CLAUDE.md.bak` for local preferences that aren't Notion-dependent:
 - Repo paths, coding conventions, project-specific notes
 - Add these to appropriate places:
   - Coding conventions → `.claude/rules/` (new rule file)
-  - Project notes → `shared-context/locked/` or `shared-context/{user}/`
+  - Project notes → `workspace-context/shared/locked/` or `workspace-context/team-member/{user}/`
   - Repo paths → already in `workspace.json`
 
 ### 6. Remove Notion dependency
@@ -108,7 +108,7 @@ Verify the workspace works without Notion:
 ### 7. Commit
 
 ```bash
-git add .claude/rules/ shared-context/
+git add .claude/rules/ workspace-context/
 git commit -m "chore: migrate Notion content to local files"
 ```
 

package/template/.claude/rules/coherent-revisions.md

@@ -6,7 +6,7 @@ This applies to all written output:
 - Project documentation
 - Specs and design docs
 - Code and logic changes including comments
-- Shared context documents (handoffs, braindumps, locked context)
+- Workspace-context files (handoffs, braindumps, locked truths)
 - Release notes
 - Open questions
 - Commit messages
@@ -18,7 +18,7 @@ Injected revisions create fragmented, hard-to-follow output where the seams betw
 ## In Practice
 
 - When updating a section of a document, rewrite the entire section — not just the changed sentences
-- When updating a shared-context file, rewrite it as a fresh snapshot of current understanding
+- When updating a workspace-context file, rewrite it as a fresh snapshot of current understanding
 - When synthesizing multiple sources into release notes, write the narrative from scratch — don't concatenate
 - When revising code with comments, ensure the comments tell a coherent story, not a changelog
 - Small, isolated edits (fixing a typo, updating a single value) are fine — this rule targets substantive revisions

package/template/.claude/rules/local-dev-environment.md.skip

@@ -1,6 +1,6 @@
 # Local Dev Environment
 
-Maintain a local-only document at `shared-context/locked/local-only-dev-environment.md` that captures machine-specific development context. This file is gitignored (local-only prefix) but positioned in locked for maximum visibility — Claude sees it every turn.
+Maintain a local-only document at `workspace-context/shared/locked/local-only-dev-environment.md` that captures machine-specific development context. This file is gitignored (local-only prefix) but positioned in locked for maximum visibility — Claude sees it every turn.
 
 ## What to Record
 
@@ -17,7 +17,7 @@ When you discover any of the following during work, add it to the local dev envi
 
 When you encounter a local development detail worth preserving:
 
-1. Check if `shared-context/locked/local-only-dev-environment.md` exists
+1. Check if `workspace-context/shared/locked/local-only-dev-environment.md` exists
 2. If not, create it with this structure:
    ```markdown
    ---

package/template/.claude/rules/memory-guidance.md

@@ -15,7 +15,7 @@ When working in this workspace, pay attention to and save memories about:
 
 - Temporary debugging state
 - File contents (re-read them instead)
-- Anything already captured in a shared-context file
+- Anything already captured in a workspace-context file
 - Anything documented in .claude/rules/
 
 ## Session-Scoped vs Cross-Session
@@ -24,3 +24,56 @@ When a work session is active:
 - Decisions and progress from this session → update the session tracker body at `work-sessions/{name}/workspace/session.md` (consumed by /complete-work)
 - Patterns, corrections, and insights that apply beyond this session → auto-memory (persists across all sessions)
 - Don't duplicate: if something is already in the session tracker, don't also save it to auto-memory
+
+## Workspace-Context Frontmatter
+
+Every workspace-context file should have YAML frontmatter. The fields below are conventions, not all required.
+
+**Standard fields:**
+
+- `state` — `locked` (team truth) or `ephemeral` (working context). Locked files live under `shared/locked/`; ephemeral files live elsewhere under `shared/` or `team-member/{user}/`.
+- `lifecycle` — for ephemeral files: `active` (still relevant) or `resolved` (handled, kept for record).
+- `type` — kind of content: `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `canonical`, `promoted`.
+- `topic` — kebab-case slug matching the filename (after the type prefix, when one is present).
+- `author` — username scope owner. Required for `team-member/{user}/` files.
+- `updated` — ISO date of last meaningful edit. `/maintenance` flags stale `lifecycle: active` files based on this.
+
+**Index-feeding field:**
+
+- `description` — one-line summary, used verbatim by `workspace-context/index.md` and per-user team-member indexes. When omitted, the index falls back to the first sentence of the body, then the filename slug (with the `braindump_`/`handoff_`/`research_` prefix stripped). Adding a `description:` to a file with a weak fallback is the cheapest way to improve the index.
+
+**Optional confidence marker:**
+
+- `confidence` — `high` | `medium` | `low`. Apply to research, design, and exploration files where the conclusions might still shift. Skip on locked files (locked = high by definition) and on workflow artifacts like handoffs and braindumps. The frontmatter integrity check in `/maintenance` validates the value if present.
+
+**Example for a research file:**
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: research
+topic: vector-search-evaluation
+description: Evaluation of FAISS for workspace-context — concluded NL index is sufficient at our scale.
+author: alex
+confidence: medium
+updated: 2026-04-25
+---
+```
+
+## Workspace-Context Auto-Generated Files
+
+A single generator at `.claude/scripts/build-workspace-context.mjs` produces three artifacts in one pass:
+
+- `workspace-context/index.md` — navigation catalog of everything under `shared/` (locked files first, then the rest). Imported by the workspace-level `CLAUDE.md`.
+- `workspace-context/canonical.md` — verbatim concatenation of `shared/locked/*.md` so team truths are loaded into every session prompt. Also imported by `CLAUDE.md`.
+- `workspace-context/team-member/{user}/index.md` — per-user navigation catalog, one per team member. Imported by each user's gitignored `CLAUDE.local.md`.
+
+Gitignored files (e.g. anything matching `local-only-*`) are excluded automatically, and `workspace-context/.indexignore` adds path-prefix excludes for tracked files that shouldn't appear in the shared index (e.g. archived release notes).
+
+```bash
+node .claude/scripts/build-workspace-context.mjs --check --root .   # exits 1 if any artifact is stale or missing
+node .claude/scripts/build-workspace-context.mjs --write --root .   # regenerate all three
+```
+
+`/maintenance` checks staleness in audit mode and regenerates in cleanup mode. Hand edits to `index.md`, `canonical.md`, or any `team-member/{user}/index.md` are overwritten — update source files (or their `description:` frontmatter) instead.

package/template/.claude/rules/token-economics.md.skip

@@ -34,7 +34,7 @@ The single biggest source of session bloat is bash output you didn't bound. The
 "Ghost tokens" are context spend you can't see in any single tool result — structural bloat that accumulates across the session. Watch for:
 
 - **Unused skills.** A loaded skill that you never invoke costs input tokens every turn. If a workspace ships skills you don't use in the current task, that's silent overhead.
-- **Oversized locked context.** `shared-context/locked/` is injected into every session and every subagent. If it grows past 5% of the active model's context window, flag it (yellow); past 15%, treat as red. Absolute byte count is a weak proxy — duplicated coverage and stale references matter more.
+- **Oversized locked context.** `workspace-context/shared/locked/` is injected into every session and every subagent. If it grows past 5% of the active model's context window, flag it (yellow); past 15%, treat as red. Absolute byte count is a weak proxy — duplicated coverage and stale references matter more.
 - **Unused MCP servers.** Each MCP server's tool list is in your prompt whether you call it or not. If a server is registered but never used in this workspace's flow, surface it for cleanup.
 - **Resolved discussions still in context.** If the conversation has worked through a long debate that's now settled, that text is still occupying the window. Suggest `/braindump` to offload it into a file.
 - **Subagent context bloat.** A subagent prompt that ships more context than the task requires wastes tokens twice — once for the subagent, once for the dispatching model that wrote the prompt.
@@ -42,5 +42,5 @@ The single biggest source of session bloat is bash output you didn't bound. The
 ## Compaction Awareness
 
 - When approaching the compaction threshold, prioritize capturing over continuing. A `/braindump` or `/handoff` *before* compaction preserves reasoning that gets summarized away.
-- After compaction, avoid re-reading files that were already discussed — check `shared-context/` and the session tracker first.
+- After compaction, avoid re-reading files that were already discussed — check `workspace-context/` and the session tracker first.
 - The `PreCompact` hook will prompt for capture; treat that prompt as a real checkpoint, not a dismissable nag.

package/template/.claude/rules/work-item-tracking.md

@@ -69,7 +69,7 @@ The value is the adapter-prefixed issue ID. This survives adapter swaps — repl
 
 ## When NOT to maintain local state
 
-- Do not create, write to, or read `shared-context/open-work.md`. That file is deprecated.
+- Do not create, write to, or read `workspace-context/open-work.md`. That file is deprecated.
 - Do not write ticket state into `session.md` frontmatter beyond the `workItem:` pointer. Status, assignment, milestone, and labels live in the tracker.
 - Do not cache issue bodies locally. Always fetch via `tracker.getIssue(id)` when the content is needed.
 

package/template/.claude/rules/workspace-structure.md

@@ -14,25 +14,35 @@ This workspace follows the claude-workspace convention. All paths are relative t
 | `work-sessions/{name}/workspace/plan-*.md` | Plans for this session — consumed into release notes by /complete-work | Yes — on the session branch |
 | `work-sessions/{name}/workspace/repos/` | Real directory holding nested project worktrees for this session | No (gitignored) |
 | `work-sessions/{name}/workspace/repos/{repo}/` | Project worktree nested inside the workspace worktree | No (gitignored) |
-| `shared-context/` | Shared memory — handoffs, braindumps, team knowledge | Yes |
-| `shared-context/locked/` | Team truths — loaded every session, injected into subagents | Yes |
-| `shared-context/{user}/` | User-scoped working context — default for all captures | Yes |
+| `workspace-context/` | Team knowledge and per-user context | Yes |
+| `workspace-context/shared/` | Team-visible content — handoffs, braindumps, research, references | Yes |
+| `workspace-context/shared/locked/` | Canonical team truths — auto-concatenated into `canonical.md` and loaded into every session | Yes |
+| `workspace-context/team-member/{user}/` | Per-user working context — default destination for personal captures | Yes |
+| `workspace-context/index.md` | Auto-generated navigation catalog of `shared/` (locked first, then ephemerals) | Yes |
+| `workspace-context/canonical.md` | Auto-generated verbatim concatenation of `shared/locked/*.md` | Yes |
+| `workspace-context/team-member/{user}/index.md` | Auto-generated per-user navigation catalog | Yes |
+| `workspace-context/.indexignore` | Path prefixes to exclude from `index.md` (e.g., archived release notes) | Yes |
+| `workspace-context/release-notes/` | Per-branch release-note artifacts — `unreleased/` and `archive/` | Yes |
 | `workspace-scratchpad/` | Disposable workspace-scoped files — session log, hook debug output | No (gitignored, lazy) |
+| `CLAUDE.md` | Workspace launcher prompt — imports `canonical.md` and `index.md` | Yes |
+| `CLAUDE.local.md` | Per-user prompt — imports `team-member/{user}/index.md` | No (gitignored) |
 | `.claude/` | Claude Code configuration — rules, agents, skills, hooks, scripts, lib | Yes (except settings.local.json) |
 
 Session content (tracker, specs, plans) lives at the top of each session's workspace worktree. It is tracked on the session branch, not on main. Pushing the session branch carries durable session thinking across machines. When `/complete-work` finalizes the session, it synthesizes the content into release notes and removes the files from the branch before the final PR so main's top level stays free of session artifacts.
 
-## Shared Context Levels
+## Workspace-Context Levels
 
-| Level | What lives there | Default? |
-|-------|-----------------|----------|
-| `locked/` | Team truths — always loaded, injected into subagents | Promoted by /release |
-| Root | Team-visible ephemerals — cross-team handoffs, post-release leftovers | Explicit choice |
-| `{user}/` | Ongoing personal context — persists across work sessions | Default for captures |
+Three layers, in increasing trust order:
 
-Inflight session state lives inside the session worktree at `work-sessions/{name}/workspace/session.md`, not in `shared-context/`. Shared-context is for knowledge that outlives any individual session.
+| Level | Path | What lives there | How it gets there |
+|-------|------|-----------------|--------------------|
+| Personal | `team-member/{user}/` | Per-user braindumps, handoffs, research notes | Default destination for `/braindump`, `/handoff`, `/aside` |
+| Shared | `shared/` (root) | Team-visible ephemerals — cross-team handoffs, post-release leftovers, references | Explicit choice via `--scope shared` or `/promote` |
+| Canonical | `shared/locked/` | Promoted truths — naming conventions, post-release discipline, project status | Promoted by `/release` (or `/promote` with explicit locked target) |
 
-User-scoped is the default for captures. Root is only for content deliberately made team-visible.
+Canonical content is verbatim-loaded into every session via `CLAUDE.md` → `@workspace-context/canonical.md`. Personal content is loaded only for the active user via the gitignored `CLAUDE.local.md`.
+
+Inflight session state lives inside the session worktree at `work-sessions/{name}/workspace/session.md`, not in `workspace-context/`. Workspace-context is for knowledge that outlives any individual session.
 
 ## Spec and Plan Locations — MANDATORY OVERRIDE
 
@@ -49,7 +59,7 @@ If a spec/plan already exists for the current session, version it: `design-{topi
 
 `/complete-work` reads specs and plans from the worktree to synthesize release notes, then removes them in a dedicated commit before the final PR so main's tree stays pristine.
 
-## Naming Conventions
+## File Naming Conventions
 
 - Session folders: `work-sessions/{session-name}/`
 - Workspace worktrees: `work-sessions/{session-name}/workspace/`
@@ -57,7 +67,19 @@ If a spec/plan already exists for the current session, version it: `design-{topi
 - Session trackers: `work-sessions/{session-name}/workspace/session.md`
 - Specs: `design-{topic}.md` (top of worktree)
 - Plans: `plan-{topic}.md` (top of worktree)
-- Handoffs and braindumps: named by topic (no date prefix — use frontmatter `updated:`)
+
+For ephemeral content under `shared/` and `team-member/{user}/`, the filename prefix signals the type:
+
+| Skill | Filename prefix |
+|-------|-----------------|
+| `/braindump` | `braindump_{topic}.md` |
+| `/handoff` | `handoff_{topic}.md` |
+| `/aside` (full mode, dispatches researcher) | `research_{topic}.md` |
+| `/aside --quick` | `braindump_{topic}.md` (with `variant: aside` in frontmatter) |
+| `/promote` | preserves source prefix |
+| `/release` | strips prefix when locking — `shared/locked/` files use bare names since location signals the type |
+
+Local-only personal drafts get an additional `local-only-` prefix (e.g., `local-only-braindump_x.md`) which keeps them gitignored until promoted.
 
 ## Rules
 
@@ -67,3 +89,4 @@ If a spec/plan already exists for the current session, version it: `design-{topi
 - Source clones at `repos/{repo-name}/` stay on their default branch — never checkout a feature branch there.
 - `workspace-scratchpad/` is for disposable files only — session log, hook debug output, temporary pointers.
 - Project worktrees are nested inside the workspace worktree's real `repos/` directory — no symlink.
+- Hand edits to `index.md`, `canonical.md`, or any per-user `team-member/{user}/index.md` are overwritten by `build-workspace-context.mjs`. Update source files (or their `description:` frontmatter) instead.

package/template/.claude/scripts/build-workspace-context.mjs

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+// Generate workspace-context auto-files from filesystem state.
+//
+// One pass, three artifacts:
+//   workspace-context/index.md            — navigation surface (shared/ + shared/locked/)
+//   workspace-context/canonical.md        — full-content concat of shared/locked/*.md
+//   workspace-context/team-member/{user}/index.md — per-user navigation
+//
+// Source of truth: the filesystem. Hand edits are overwritten on regeneration.
+// Gitignored files are excluded automatically. .indexignore adds prefix excludes.
+//
+// Usage:
+//   node build-workspace-context.mjs --write [--root <workspace-root>]
+//   node build-workspace-context.mjs --check [--root <workspace-root>]
+//
+// --write regenerates all three artifacts.
+// --check exits 0 if everything matches, 1 if any is stale or missing. Reports per-file status.
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseSessionContent } from '../lib/session-frontmatter.mjs';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+const WC_DIR = 'workspace-context';
+const SHARED_DIR = 'shared';
+const LOCKED_DIR = 'locked';
+const TEAM_MEMBER_DIR = 'team-member';
+const INDEX_FILENAME = 'index.md';
+const CANONICAL_FILENAME = 'canonical.md';
+const IGNORE_FILENAME = '.indexignore';
+
+function parseArgs(argv) {
+  const args = { mode: null, root: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--write') args.mode = 'write';
+    else if (a === '--check') args.mode = 'check';
+    else if (a === '--root') args.root = argv[++i];
+  }
+  if (!args.mode) throw new Error('Specify --write or --check');
+  return args;
+}
+
+function walkMarkdown(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...walkMarkdown(full));
+    else if (st.isFile() && name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+function readDescription(filePath) {
+  let frontmatter = {};
+  let body = '';
+  try {
+    const parsed = parseSessionContent(readFileSync(filePath, 'utf-8'));
+    frontmatter = parsed.fields || {};
+    body = parsed.body || '';
+  } catch {
+    body = readFileSync(filePath, 'utf-8');
+  }
+
+  if (typeof frontmatter.description === 'string' && frontmatter.description.trim()) {
+    return frontmatter.description.trim();
+  }
+  const stripped = body.replace(/^#.*$/m, '').trim();
+  const firstParagraph = stripped.split(/\n\s*\n/, 1)[0] || '';
+  const firstSentence = firstParagraph.replace(/\n/g, ' ').match(/[^.!?]+[.!?]/);
+  if (firstSentence) {
+    const candidate = firstSentence[0].trim();
+    if (candidate.length > 0 && candidate.length <= 200) return candidate;
+  }
+  const filename = filePath.split(sep).pop() || '';
+  return filename.replace(/\.md$/, '').replace(/^(braindump|handoff|research)_/, '').replace(/-/g, ' ');
+}
+
+function readIgnorePrefixes(wcDir) {
+  const ignorePath = join(wcDir, IGNORE_FILENAME);
+  if (!existsSync(ignorePath)) return [];
+  return readFileSync(ignorePath, 'utf-8')
+    .split('\n')
+    .map((l) => l.replace(/#.*/, '').trim())
+    .filter((l) => l.length > 0);
+}
+
+function isIgnored(relativePath, prefixes) {
+  for (const prefix of prefixes) {
+    if (relativePath === prefix) return true;
+    if (relativePath.startsWith(prefix.endsWith('/') ? prefix : prefix + '/')) return true;
+  }
+  return false;
+}
+
+function gitIgnoredPaths(workspaceRoot, paths) {
+  if (paths.length === 0) return new Set();
+  const result = spawnSync('git', ['check-ignore', '--stdin'], {
+    cwd: workspaceRoot,
+    input: paths.join('\n'),
+    encoding: 'utf-8',
+  });
+  if (result.error || (result.status !== 0 && result.status !== 1)) return new Set();
+  return new Set(
+    result.stdout.split('\n').map((l) => l.trim()).filter((l) => l.length > 0),
+  );
+}
+
+function stripFrontmatter(content) {
+  if (!content.startsWith('---\n')) return content;
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) return content;
+  return content.slice(end + 5).replace(/^\n+/, '');
+}
+
+function describeAndPath(filePath, wcRoot) {
+  const rel = relative(wcRoot, filePath).split(sep).join('/');
+  return { rel, description: readDescription(filePath) };
+}
+
+// ---------- shared index ----------
+
+function buildSharedIndex(workspaceRoot) {
+  const wcRoot = join(workspaceRoot, WC_DIR);
+  const sharedDir = join(wcRoot, SHARED_DIR);
+  if (!existsSync(sharedDir)) return [];
+
+  const ignorePrefixes = readIgnorePrefixes(wcRoot);
+  const candidates = walkMarkdown(sharedDir);
+  const candidatePaths = candidates.map((f) => relative(workspaceRoot, f).split(sep).join('/'));
+  const gitIgnored = gitIgnoredPaths(workspaceRoot, candidatePaths);
+
+  const entries = [];
+  for (let i = 0; i < candidates.length; i++) {
+    const f = candidates[i];
+    const relToWC = relative(wcRoot, f).split(sep).join('/');
+    if (relToWC === INDEX_FILENAME || relToWC === CANONICAL_FILENAME) continue;
+    if (isIgnored(relToWC, ignorePrefixes)) continue;
+    if (gitIgnored.has(candidatePaths[i])) continue;
+    const isLocked = relToWC.startsWith(`${SHARED_DIR}/${LOCKED_DIR}/`);
+    const { description } = describeAndPath(f, wcRoot);
+    entries.push({ rel: relToWC, isLocked, description });
+  }
+  entries.sort((a, b) => {
+    if (a.isLocked !== b.isLocked) return a.isLocked ? -1 : 1;
+    return a.rel.localeCompare(b.rel);
+  });
+  return entries;
+}
+
+function renderSharedIndex(entries, generatedAt) {
+  const lines = [
+    '---',
+    'type: index',
+    `generated: ${generatedAt}`,
+    '---',
+    '',
+    '# workspace-context — index',
+    '',
+    '> Auto-generated by `.claude/scripts/build-workspace-context.mjs`. Hand edits will be overwritten — update source files instead.',
+    '',
+  ];
+  const locked = entries.filter((e) => e.isLocked);
+  const other = entries.filter((e) => !e.isLocked);
+  if (locked.length > 0) {
+    lines.push('## Canonical (in CLAUDE.md context verbatim)', '');
+    for (const e of locked) lines.push(`- [${e.rel}](${e.rel}) — ${e.description}`);
+    lines.push('');
+  }
+  if (other.length > 0) {
+    lines.push('## Shared', '');
+    for (const e of other) lines.push(`- [${e.rel}](${e.rel}) — ${e.description}`);
+    lines.push('');
+  }
+  if (entries.length === 0) {
+    lines.push('_(no shared workspace-context files yet)_', '');
+  }
+  return lines.join('\n');
+}
+
+// ---------- canonical concat ----------
+
+function buildCanonical(workspaceRoot) {
+  const lockedDir = join(workspaceRoot, WC_DIR, SHARED_DIR, LOCKED_DIR);
+  if (!existsSync(lockedDir)) return [];
+  return walkMarkdown(lockedDir)
+    .filter((f) => !f.endsWith('.keep'))
+    .sort()
+    .map((f) => ({
+      name: f.split(sep).pop().replace(/\.md$/, ''),
+      content: stripFrontmatter(readFileSync(f, 'utf-8')).trimEnd(),
+    }));
+}
+
+function renderCanonical(items, generatedAt) {
+  const lines = [
+    '---',
+    'type: canonical',
+    `generated: ${generatedAt}`,
+    '---',
+    '',
+    '# workspace-context — canonical truths',
+    '',
+    '> Auto-generated concatenation of `shared/locked/*.md`. Hand edits will be overwritten — update source files instead.',
+    '',
+  ];
+  for (const item of items) {
+    lines.push(`## ${item.name}`, '', item.content, '');
+  }
+  if (items.length === 0) {
+    lines.push('_(no canonical entries yet — promote one via `/release`)_', '');
+  }
+  return lines.join('\n');
+}
+
+// ---------- team-member indexes ----------
+
+function buildTeamMemberIndex(workspaceRoot, user) {
+  const userDir = join(workspaceRoot, WC_DIR, TEAM_MEMBER_DIR, user);
+  if (!existsSync(userDir)) return [];
+
+  const candidates = walkMarkdown(userDir).filter(
+    (f) => f.split(sep).pop() !== INDEX_FILENAME,
+  );
+  const candidatePaths = candidates.map((f) => relative(workspaceRoot, f).split(sep).join('/'));
+  const gitIgnored = gitIgnoredPaths(workspaceRoot, candidatePaths);
+
+  const entries = [];
+  for (let i = 0; i < candidates.length; i++) {
+    if (gitIgnored.has(candidatePaths[i])) continue;
+    const relToUserDir = relative(userDir, candidates[i]).split(sep).join('/');
+    const description = readDescription(candidates[i]);
+    entries.push({ rel: relToUserDir, description });
+  }
+  entries.sort((a, b) => a.rel.localeCompare(b.rel));
+  return entries;
+}
+
+function renderTeamMemberIndex(user, entries, generatedAt) {
+  const lines = [
+    '---',
+    'type: index',
+    `generated: ${generatedAt}`,
+    '---',
+    '',
+    `# ${user}'s context`,
+    '',
+    '> Auto-generated by `.claude/scripts/build-workspace-context.mjs`. Hand edits will be overwritten.',
+    '',
+  ];
+  for (const e of entries) {
+    lines.push(`- [${e.rel}](${e.rel}) — ${e.description}`);
+  }
+  if (entries.length === 0) {
+    lines.push('_(no personal context files yet)_');
+  }
+  return lines.join('\n') + '\n';
+}
+
+function listTeamMembers(workspaceRoot) {
+  const tmDir = join(workspaceRoot, WC_DIR, TEAM_MEMBER_DIR);
+  if (!existsSync(tmDir)) return [];
+  return readdirSync(tmDir)
+    .filter((name) => {
+      const full = join(tmDir, name);
+      return statSync(full).isDirectory();
+    })
+    .sort();
+}
+
+// ---------- orchestration ----------
+
+function fingerprint(content) {
+  return content
+    .split('\n')
+    .filter((l) => !l.startsWith('generated:'))
+    .join('\n');
+}
+
+function regenerateAll(workspaceRoot, generatedAt) {
+  const wcRoot = join(workspaceRoot, WC_DIR);
+  if (!existsSync(wcRoot)) return [];
+
+  const out = [];
+  const sharedEntries = buildSharedIndex(workspaceRoot);
+  out.push({
+    path: join(wcRoot, INDEX_FILENAME),
+    label: 'index.md',
+    content: renderSharedIndex(sharedEntries, generatedAt) + '\n',
+  });
+
+  const canonicalItems = buildCanonical(workspaceRoot);
+  out.push({
+    path: join(wcRoot, CANONICAL_FILENAME),
+    label: 'canonical.md',
+    content: renderCanonical(canonicalItems, generatedAt) + '\n',
+  });
+
+  for (const user of listTeamMembers(workspaceRoot)) {
+    const entries = buildTeamMemberIndex(workspaceRoot, user);
+    out.push({
+      path: join(wcRoot, TEAM_MEMBER_DIR, user, INDEX_FILENAME),
+      label: `team-member/${user}/index.md`,
+      content: renderTeamMemberIndex(user, entries, generatedAt),
+    });
+  }
+
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const generatedAt = new Date().toISOString();
+  const artifacts = regenerateAll(args.root, generatedAt);
+
+  if (args.mode === 'check') {
+    const stale = [];
+    const missing = [];
+    for (const a of artifacts) {
+      if (!existsSync(a.path)) { missing.push(a.label); continue; }
+      const onDisk = readFileSync(a.path, 'utf-8');
+      if (fingerprint(onDisk) !== fingerprint(a.content)) stale.push(a.label);
+    }
+    if (missing.length === 0 && stale.length === 0) {
+      process.stdout.write(JSON.stringify({ status: 'current', artifacts: artifacts.length }) + '\n');
+      process.exit(0);
+    }
+    process.stdout.write(JSON.stringify({ status: 'stale', missing, stale }) + '\n');
+    process.exit(1);
+  }
+
+  if (args.mode === 'write') {
+    for (const a of artifacts) writeFileSync(a.path, a.content);
+    process.stdout.write(
+      JSON.stringify({ status: 'written', artifacts: artifacts.map((a) => a.label) }) + '\n',
+    );
+    process.exit(0);
+  }
+}
+
+if (isMainModule(import.meta.url)) main();
+
+export {
+  buildSharedIndex,
+  renderSharedIndex,
+  buildCanonical,
+  renderCanonical,
+  buildTeamMemberIndex,
+  renderTeamMemberIndex,
+  listTeamMembers,
+  regenerateAll,
+  fingerprint,
+  readDescription,
+  stripFrontmatter,
+};