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

package/lib/init.mjs

@@ -50,37 +50,24 @@ export async function initWorkspace(targetDir) {
     console.log(`  Installed ${dir}`);
   }
 
-  // Create shared-context structure. We always want shared-context/ and
-  // shared-context/locked/ to exist after init, even if the payload ships
-  // no files for them yet — locked/ is referenced by CLAUDE.md.tmpl via
-  // the @shared-context/locked/ import directive.
-  const payloadContext = join(payloadDir, 'shared-context');
-  const targetContext = join(targetDir, 'shared-context');
-  if (existsSync(payloadContext) && !existsSync(targetContext)) {
-    cpSync(payloadContext, targetContext, { recursive: true });
-    console.log('  Created shared-context/');
-  }
-  ensureDir(join(targetDir, 'shared-context', 'locked'));
+  // Ensure workspace-context/locked/ exists. canonical.md and index.md are
+  // generated later by /workspace-init via build-workspace-context.mjs;
+  // this just guarantees the destination directory is in place.
+  ensureDir(join(targetDir, 'workspace-context', 'locked'));
 
   // Everything else (repos/, work-sessions/, workspace-scratchpad/) is
   // lazy-created by scripts and hooks when they first need to write.
   // We intentionally do NOT pre-create these dirs — they get made on demand.
 
-  // Create workspace.json if missing
+  // Create workspace.json from template if missing. Single source of truth
+  // for shape is template/workspace.json.tmpl — mirrors the CLAUDE.md.tmpl
+  // handling below.
   if (!existsSync(workspaceJsonPath)) {
-    writeFileSync(workspaceJsonPath, JSON.stringify({
-      workspace: {
-        name,
-        templateVersion: toVersion,
-        scratchpadDir: 'workspace-scratchpad',
-        workSessionsDir: 'work-sessions',
-        sharedContextDir: 'shared-context',
-        releaseNotesDir: 'release-notes',
-        subagentContextMaxBytes: 10240,
-        greeting: `Welcome back to ${name}.`,
-      },
-      repos: {},
-    }, null, 2) + '\n');
+    const wsTmplPath = join(payloadDir, 'workspace.json.tmpl');
+    const wsTmpl = readFileSync(wsTmplPath, 'utf-8').replace(/\{\{project-name\}\}/g, name);
+    const workspaceConfig = JSON.parse(wsTmpl);
+    workspaceConfig.workspace.templateVersion = toVersion;
+    writeFileSync(workspaceJsonPath, JSON.stringify(workspaceConfig, null, 2) + '\n');
     console.log('  Created workspace.json');
   }
 

package/lib/scaffold.mjs

@@ -20,10 +20,11 @@ export async function scaffold(answers) {
     },
   });
 
-  // Ensure shared-context/locked/ exists so the CLAUDE.md import resolves.
+  // Ensure workspace-context/locked/ exists. canonical.md and index.md are
+  // generated later by /workspace-init via build-workspace-context.mjs;
   // repos/, work-sessions/, and workspace-scratchpad/ are lazy-created when
   // scripts and hooks first need them — we do NOT pre-create them here.
-  mkdirSync(join(directory, 'shared-context', 'locked'), { recursive: true });
+  mkdirSync(join(directory, 'workspace-context', 'locked'), { recursive: true });
 
   // Rename _gitignore to .gitignore
   const gitignoreSrc = join(directory, '_gitignore');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.14.0-beta.3",
+  "version": "0.15.0-beta.1",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/.claude/agents/reviewer.md

@@ -27,7 +27,7 @@ You are reviewing code changes. Your job is to find problems, not to fix them.
 3. **Edge cases** — are there scenarios not handled?
 4. **Test coverage** — are tests covering the right scenarios? Are they testing behavior, not implementation?
 5. **Security** — any injection, XSS, or auth issues?
-6. **Consistency** — does it match existing patterns in shared-context/locked/?
+6. **Consistency** — does it match existing patterns in workspace-context/shared/locked/?
 
 ## What NOT to review
 - Style preferences (defer to linters/formatters)

package/template/.claude/hooks/pre-compact.mjs

@@ -30,5 +30,5 @@ if (pointer) {
     respond(`Context is about to be compacted. No session tracker found for "${pointer.name}". Use /handoff to capture progress before context is lost.`);
   }
 } else {
-  respond(`Context is about to be compacted — earlier conversation details will be lost.\n\nIf this session produced decisions or progress worth keeping:\n  /braindump [name] — capture discussion and reasoning\n  /handoff [name]   — capture workstream state and next steps\n\nFiles in shared-context/ will persist. Conversation details won't.`);
+  respond(`Context is about to be compacted — earlier conversation details will be lost.\n\nIf this session produced decisions or progress worth keeping:\n  /braindump [name] — capture discussion and reasoning\n  /handoff [name]   — capture workstream state and next steps\n\nFiles in workspace-context/ will persist. Conversation details won't.`);
 }

package/template/.claude/hooks/repo-write-detection.mjs

@@ -94,9 +94,9 @@ if (toolName === 'Bash') {
   }
 }
 
-// Check if this write targets repos/, shared-context/, work-sessions/, or template files
+// Check if this write targets repos/, workspace-context/, work-sessions/, or template files
 const isRepoWrite = /(?:^|[\s/])repos\//.test(paths) || paths.includes('work-sessions/');
-const isContextWrite = paths.includes('shared-context/') && !basename(filePathArg).startsWith('local-only-');
+const isContextWrite = paths.includes('workspace-context/') && !basename(filePathArg).startsWith('local-only-');
 const isTemplateWrite = paths.includes('.claude/') && !paths.includes(scratchpadName);
 
 if (isRepoWrite || isContextWrite || isTemplateWrite) {

package/template/.claude/hooks/session-start.mjs

@@ -22,7 +22,8 @@ const input = await readStdin();
 const config = readJSON(join(root, 'workspace.json'));
 
 const chatId = input.session_id || null;
-const contextDir = join(root, 'shared-context');
+const contextDir = join(root, 'workspace-context');
+const sharedDir = join(contextDir, 'shared');
 const reposDir = join(root, 'repos');
 const lines = [];
 
@@ -113,8 +114,11 @@ if (trackers.length > 0) {
   lines.push('Use /start-work to resume a session or start new work.');
 }
 
-// Surface shared context (secondary)
-if (existsSync(contextDir)) {
+// Surface team-shared workspace context (secondary)
+// Only scan shared/ — locked/ is now a sub-dir of shared/ and is included
+// naturally. team-member/ is per-user (loaded via CLAUDE.local.md).
+// release-notes/ is operational, not knowledge.
+if (existsSync(sharedDir)) {
   const entries = [];
 
   function scanDir(dir, depth = 0) {
@@ -123,11 +127,10 @@ if (existsSync(contextDir)) {
       const fullPath = join(dir, entry);
       const stat = statSync(fullPath);
       if (stat.isDirectory()) {
-        if (entry === 'locked' || entry === '.keep') continue;
+        if (entry === '.keep') continue;
         scanDir(fullPath, depth + 1);
       } else if (entry.endsWith('.md') && entry !== '.keep' && !entry.startsWith('local-only-')) {
         const relPath = relative(contextDir, fullPath);
-        if (relPath.startsWith('locked/')) continue;
         const content = readFileSync(fullPath, 'utf-8');
         const topicMatch = content.match(/^topic:\s*(.+)$/m);
         const lifecycleMatch = content.match(/^lifecycle:\s*(.+)$/m);
@@ -139,10 +142,10 @@ if (existsSync(contextDir)) {
     }
   }
 
-  scanDir(contextDir);
+  scanDir(sharedDir);
   if (entries.length > 0) {
     lines.push('');
-    lines.push('Shared context:');
+    lines.push('Workspace context:');
     lines.push(...entries);
   }
 }

package/template/.claude/hooks/subagent-start.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-// SubagentStart hook — inject shared-context/locked/ into subagent context
+// SubagentStart hook — inject workspace-context/shared/locked/ into subagent context
 import { readdirSync, readFileSync, existsSync } from 'fs';
 import { join, basename } from 'path';
 import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
 
 const root = getWorkspaceRoot(import.meta.url);
 const config = readJSON(join(root, 'workspace.json'));
-const lockedDir = join(root, 'shared-context', 'locked');
+const lockedDir = join(root, 'workspace-context', 'shared', 'locked');
 
 const maxBytes = config?.workspace?.subagentContextMaxBytes || 10240;
 
@@ -38,7 +38,7 @@ if (Buffer.byteLength(context) > maxBytes) {
     return `- ${basename(f, '.md')}: ${firstLine}`;
   }).join('\n');
 
-  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from shared-context/locked/ if you need full content.]`;
+  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from workspace-context/shared/locked/ if you need full content.]`;
 }
 
 respond(context);

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
@@ -25,22 +25,23 @@ When a work session is active:
 - 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
 
-## Shared-Context Frontmatter
+## Workspace-Context Frontmatter
 
-Every shared-context file should have YAML frontmatter. The fields below are conventions, not all required.
+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 `locked/`; ephemeral files live elsewhere.
+- `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`, `promoted`.
-- `topic` — kebab-case slug matching the filename (without `.md`).
-- `author` — username scope owner. Required for `{user}/` files.
+- `type` — kind of content: `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `canonical`, `promoted`.
+- `priority` — for locked files only: `critical` (always loaded into canonical) or `reference` (eligible for trim/stub under canonical budget pressure). Default when absent is `critical`. See `build-workspace-context.mjs` for selection semantics.
+- `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 `shared-context/index.md`. When omitted, the index falls back to the first sentence of the body, then the filename slug. Adding a `description:` to a file with a weak fallback is the cheapest way to improve the index.
+- `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:**
 
@@ -54,20 +55,28 @@ state: ephemeral
 lifecycle: active
 type: research
 topic: vector-search-evaluation
-description: Evaluation of FAISS for shared-context — concluded NL index is sufficient at our scale.
+description: Evaluation of FAISS for workspace-context — concluded NL index is sufficient at our scale.
 author: alex
 confidence: medium
 updated: 2026-04-25
 ---
 ```
 
-## Shared-Context Index
+## Workspace-Context Auto-Generated Files
 
-`shared-context/index.md` is auto-generated by `.claude/scripts/build-shared-context-index.mjs`. It's a one-line catalog of every shared-context file (excluding paths in `shared-context/.indexignore`). The script regenerates from frontmatter on demand:
+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).
+
+When `workspace-context/canonical.md` exceeds `workspace.canonicalBudgetBytes` (default 40960), the builder honors per-file `priority` and section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` markers to fit: `priority: reference` files are trimmed first, then stubbed, while `priority: critical` files are always included in full. `/maintenance` audits the budget and offers a triage flow when over.
 
 ```bash
-node .claude/scripts/build-shared-context-index.mjs --check --root .   # exits 1 if stale
-node .claude/scripts/build-shared-context-index.mjs --write --root .   # regenerate
+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 the index for staleness in audit mode and regenerates in cleanup mode. Hand edits to `index.md` are overwritten — update source files (or their `description:` frontmatter) instead.
+`/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,27 +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/index.md` | Auto-generated catalog of every shared-context file (one-line per file) | Yes |
-| `shared-context/.indexignore` | Path prefixes to exclude from `index.md` (e.g., archived release notes) | 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
 
@@ -51,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/`
@@ -59,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
 
@@ -69,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.