get-claudia 1.60.0 → 1.61.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to Claudia will be documented in this file.
 
+## 1.61.0 (2026-05-22)
+
+### Launch from anywhere, upgrade from anywhere
+
+This release adds a `claudia` shell command (and `update-claudia`) so you no longer have to remember where you installed Claudia or `cd` there before launching or upgrading. New installs and upgrades wire the helper into `~/.zshrc` and `~/.bashrc` automatically. After upgrading once via `npx get-claudia .`, future upgrades are just `update-claudia` from any directory.
+
+### Added
+
+- **`claudia` shell command for launching from anywhere.** New installs (and upgrades) get a `claudia` shell function written to `~/.claudia/shell-init.sh` and sourced from `~/.zshrc` and `~/.bashrc`. From any directory, `claudia` cd's to your install folder and launches `claude`. All `claude` flags pass through (`claudia --resume`, `claudia -c "morning brief"`, etc). The folder path is stored in `~/.claudia/claudia-home`; edit it if you move your install. The installer is idempotent: re-running won't double-add to your rc files. The shell function is a smart router that delegates known npm-CLI subcommands (`setup`, `system-health`, `google`, `doctor`) back to the `claudia` binary when it's on PATH, so existing workflows keep working.
+- **`claudia yolo` subcommand.** Sugar for `claude --dangerously-skip-permissions` (cd's first, then passes through any additional flags). Same routing logic — `claudia yolo --resume` works.
+- **`update-claudia` command (also `claudia update`).** Runs `npx get-claudia <your-install-path>` from any directory by reading the stored path from `~/.claudia/claudia-home`. No more "wait, where did I install Claudia?" before upgrading. Both forms are aliases for the same logic.
+- **`~/.claudia/claudia-home`.** Single-line file with the absolute path of the user's Claudia install. Written by the installer; read by the shell function. Move your install? Edit this file.
+
+### Fixed
+
+- **ASCII greeting logo: row 1 (hair top) realigned over face** (in `template-v2/CLAUDE.md`). The top hair row was indented 6 leading spaces while the face row below it starts at column 0, so the hair appeared shifted ~4 characters to the right. Now sits correctly above the face. Existing installs see the fix on next upgrade.
+- **Installer no longer treats flag-looking arguments as install targets.** Previously, `npx get-claudia --help` (or any unrecognized `--flag`) was interpreted as the install path and would create a `./--help/` directory with templates copied into it. Now: `--help`/`-h` prints a proper usage message and exits, `--version`/`-V` prints the version, and any other leading-dash argument prints `Error: unrecognized argument: <flag>` and exits 1 without touching the filesystem.
+
+## 1.60.1 (2026-05-22)
+
+### Two bug fixes from the fixing-phase pass
+
+Both shipped together as a patch release. No new features; no surface-area change. Upgrade with `npx get-claudia .` from any existing install.
+
+### Fixed
+
+- **Memory daemon: WAL checkpoint no longer blocks concurrent readers** (#66, thanks @tilthnco). `database.py` now uses `PRAGMA wal_checkpoint(PASSIVE)` on every connection instead of `TRUNCATE`. `TRUNCATE` takes an exclusive lock, which deadlocks against concurrent WAL readers like Litestream and causes the MCP server to time out after 30s on startup. `PASSIVE` yields cleanly if a reader holds the WAL lock. Compaction behavior is unchanged; only the locking mode is relaxed. Crash safety is unaffected since WAL mode (not checkpointing) is the durability mechanism.
+- **Memory daemon: organisations from session summaries no longer misclassified as `person`** (Proposal #51, sub-tranche B2). Two stale defaults were bypassing the smart type-inference path: `RememberService.end_session()` hard-defaulted missing `type` fields to the literal string `"person"` (short-circuiting inference inside `remember_entity()`), and `remember_entity()` itself was still calling the legacy local `_infer_entity_type()` (returns `"person"` fallback, no `"AI"`-suffix rule) instead of the smart inferencer at `entities.infer_entity_type` (returns `"concept"` fallback, handles `"Markup AI"`, `".ai"`, etc.). Both call sites now route through the smart inferencer, matching `_find_or_create_entity()` which already did. The literal repro from 2026-05-13 (Matt Blumberg, Markup AI) now classifies Markup AI as `organization`. See `docs/proposals/08-smarter-memory-writes.md` for the original proposal; `tests/test_entity_resolution.py::TestEndSessionInfersEntityType` pins the fix (3 new tests, 25/25 in the file pass).
+
+### Changed
+
+- 27 skill descriptions in `template-v2/.claude/skills/` now end with a "See also: …" pointer to adjacent skills (from #61). Affected clusters: outbound message composition, memory introspection, memory visualization, reflective cadences, meeting lifecycle, risks and blind spots, people and relationships, patterns and judgment, inbound document processing. Skill names, trigger phrases, and behaviors are unchanged; descriptions are extended additively to nudge skill routing toward the canonical pick when a request straddles two skills.
+
+### Documentation
+
+- Expanded `template-v2/.claude/skills/README.md` with four new sections (from #61): "Writing a good skill description", "The see also convention", "Disambiguation notes", and "Proactive vs contextual: when to make a skill auto-fire". Each section grounds itself in existing-catalog exemplars.
+
 ## 1.60.0 (2026-05-15)
 
 ### Three new skills inspired by Karpathy's recent work, adapted to Claudia's principles

package/README.md

@@ -79,6 +79,20 @@ You make a promise in a meeting. Nobody tracks it. You promise a deliverable on
 <p>End a session with <code>/meditate</code> and she extracts what she learned: your preferences, patterns, and judgment calls. Next session, she's sharper.</p>
 </td>
 </tr>
+<tr>
+<td width="33%" align="center">
+<h3>📚 Writes Her Own Wiki</h3>
+<p>Every active person, project, and organization gets a synthesized page in your Obsidian vault. Each fact cites its source memory. Contradictions get flagged at the top. <em>New in v1.60</em>.</p>
+</td>
+<td width="33%" align="center">
+<h3>🔁 Iterates Until It's Right</h3>
+<p>Ask her to <code>/auto-research</code> a draft and she runs a bounded loop against a rubric you name. Keeps the iterations she likes, reverts the ones she doesn't. Your original file never moves until you say so. <em>New in v1.60</em>.</p>
+</td>
+<td width="33%" align="center">
+<h3>🧭 Routes the Right Skill</h3>
+<p>Type <code>/skills</code> to see what's available. Ambiguous request? She names the options and proceeds with the canonical one, so you never get the wrong tool by accident. <em>New in v1.60</em>.</p>
+</td>
+</tr>
 </table>
 
 ---
@@ -103,7 +117,7 @@ You make a promise in a meeting. Nobody tracks it. You promise a deliverable on
 </td>
 <td width="50%" align="center">
 <h3>📓 Vault</h3>
-<p>Memory syncs to an Obsidian vault organized with PARA: Active projects, Relationships, Reference material, Archive. Graph view shows how your world connects. Plain markdown you own forever.</p>
+<p>Memory projects to an Obsidian vault. New installs default to the <strong>wiki layout</strong>: synthesized topic pages per active entity, each fact citing its source memory, contradictions flagged at the top. Existing PARA users keep their layout untouched. Plain markdown you own forever.</p>
 </td>
 </tr>
 </table>
@@ -264,9 +278,12 @@ Claudia detects your work style and generates structure that fits:
 | `/meditate` | End-of-session reflection: extracts learnings, judgment, patterns |
 | `/deep-context [topic]` | Full-context deep analysis |
 | `/memory-audit` | See everything Claudia knows, with source chains |
+| `/wiki` | Write or update a synthesized topic page in your vault |
+| `/auto-research` | Iterate a draft against a rubric until it scores well |
+| `/skills` | Discover all available skills, grouped by purpose |
 
 <details>
-<summary><strong>All commands (41 skills)</strong></summary>
+<summary><strong>All commands (45 skills)</strong></summary>
 
 | Command | What It Does |
 |---------|--------------|
@@ -322,17 +339,19 @@ This generates a one-click URL to enable all required Google APIs and walks you
 
 ### Obsidian Vault
 
-Memory auto-syncs to an Obsidian vault at `~/.claudia/vault/` using PARA structure. Every entity becomes a markdown note with `[[wikilinks]]`, so Obsidian's graph view maps your network. SQLite is the source of truth; the vault is a read-only projection you can browse and search.
+Memory projects to an Obsidian vault at `~/.claudia/vault/`. New installs default to the **wiki layout**: synthesized topic pages at `~/.claudia/vault/Wiki/`, one per active person, project, or organization. Each page is written by Claudia from your raw memories, cites every load-bearing claim with `[mem:NNN]`, and flags contradictions at the top. Obsidian's graph view connects them via `[[wikilinks]]`.
+
+Existing installs from v1.59 and earlier keep their PARA-organized vault (`Active/`, `Relationships/`, `Reference/`, `Archive/`) untouched. SQLite remains the source of truth; the vault is a projection you can browse, search, and read.
 
 ---
 
 ## How It Works
 
-**41 skills · 33 MCP tools · 500+ tests**
+**45 skills · 33 MCP tools · 500+ tests**
 
 Claudia has two layers:
 
-**Template layer** (markdown) defines who she is. 41 skills, rules, and identity files that Claude reads on startup. Skills range from proactive behaviors (commitment detection, pattern recognition, judgment awareness) to user-invocable workflows (`/morning-brief`, `/research`, `/meditate`). Workspace templates let you spin up new projects with `/new-workspace [name]`.
+**Template layer** (markdown) defines who she is. 45 skills, rules, and identity files that Claude reads on startup. Skills range from proactive behaviors (commitment detection, pattern recognition, judgment awareness) to user-invocable workflows (`/morning-brief`, `/research`, `/meditate`, `/wiki`, `/auto-research`). Workspace templates let you spin up new projects with `/new-workspace [name]`. A built-in `skill-router` skill helps you discover what's available and disambiguates when a request straddles two skills.
 
 **Memory system** (Python) defines what she remembers. Two daemon modes share the same SQLite database:
 
@@ -393,7 +412,7 @@ For full architecture diagrams, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 - **Fully local.** Memory, embeddings, cognitive tools run on your machine. No external APIs for storage.
 - **No external actions without approval.** Every email, calendar event, external action requires your explicit "yes."
-- **Your data in two formats.** SQLite database (`~/.claudia/memory/`) for fast semantic search, plus a PARA-organized Obsidian vault for reading and graph navigation. Two independent copies you own forever.
+- **Your data in two formats.** SQLite database (`~/.claudia/memory/`) for fast semantic search, plus an Obsidian vault for reading and graph navigation. Two independent copies you own forever.
 - **Delete anything, anytime.** Full control over your data. No lock-in, no cloud dependency.
 
 ---

package/bin/index.js

@@ -14,6 +14,7 @@ import {
   resolveBakPath,
   applyResolution,
 } from './manifest-lib.js';
+import { writeShellInit, appendShellRC } from './shell-init.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -63,6 +64,30 @@ function getVersion() {
   }
 }
 
+function printUsage(version) {
+  console.log(`get-claudia v${version}
+
+Usage:
+  npx get-claudia [target-dir]   Install or upgrade Claudia (default: ./claudia)
+  npx get-claudia .              Install or upgrade in the current directory
+  npx get-claudia upgrade        Same as \`.\` (in-place upgrade)
+  npx get-claudia google         Set up Google Workspace integration
+
+Flags:
+  --skip-memory                  Skip memory daemon setup
+  --dev                          Dev mode (load daemon from local source)
+  --yes, -y                      Non-interactive (auto-confirm prompts)
+  --help, -h                     Show this help and exit
+  --version, -V                  Print version and exit
+
+After install, from any directory:
+  claudia                        cd to your install folder, launch claude
+  claudia yolo                   Launch claude --dangerously-skip-permissions
+  claudia update                 Upgrade Claudia (no need to cd first)
+  update-claudia                 Alias for \`claudia update\`
+`);
+}
+
 // Simple y/n prompt. Returns true if user confirms (or non-TTY / --yes flag).
 function confirm(question) {
   if (!isTTY || process.argv.includes('--yes') || process.argv.includes('-y')) {
@@ -284,6 +309,7 @@ const STEPS = [
   { id: 'memory',      label: 'Memory System' },
   { id: 'daemon',      label: 'Memory Daemon' },
   { id: 'mcp',         label: 'MCP Config' },
+  { id: 'shell',       label: 'Shell Helper' },
   { id: 'vault',       label: 'Obsidian Vault' },
   { id: 'health',      label: 'Health Check' },
 ];
@@ -737,6 +763,16 @@ async function checkForNewerVersion(currentVersion) {
 async function main() {
   const version = getVersion();
 
+  // Handle --help / --version BEFORE banner, update-check, or any I/O.
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    printUsage(version);
+    process.exit(0);
+  }
+  if (process.argv.includes('--version') || process.argv.includes('-V')) {
+    console.log(version);
+    process.exit(0);
+  }
+
   // Self-update trampoline: re-exec with latest if we're stale
   const newerVersion = await checkForNewerVersion(version);
   if (newerVersion) {
@@ -773,6 +809,16 @@ async function main() {
   const filteredArgs = args.filter(a => a !== '--no-memory' && a !== '--skip-memory' && a !== '--dev' && a !== '--yes' && a !== '-y');
   const arg = filteredArgs[0];
 
+  // Reject flag-looking arguments early so they don't get used as install paths
+  // (e.g. `npx get-claudia --foo` would otherwise create a ./--foo/ directory).
+  // --help and --version are handled at the top of main(); anything else with a
+  // leading dash is a typo or unsupported flag.
+  if (typeof arg === 'string' && arg.startsWith('-')) {
+    console.error(`${colors.red}Error:${colors.reset} unrecognized argument: ${arg}`);
+    console.error(`Run ${colors.cyan}npx get-claudia --help${colors.reset} for usage.`);
+    process.exit(1);
+  }
+
   // ─── Subcommand: get-claudia google ─────────────────────────────────────
   if (arg === 'google') {
     await runGoogleSetup();
@@ -1517,13 +1563,35 @@ async function main() {
 
   renderer.stopSpinner();
 
-  // Vault step, then completion
-  runVaultStep(renderer, () => {
-    renderer.render();
-    showDbScanResults(dbScan);
-    showCompletion(targetDir, isCurrentDir, memoryOk, rootCause, isUpgrade);
+  // Shell helper step, then vault, then completion
+  runShellStep(renderer, targetDir, () => {
+    runVaultStep(renderer, () => {
+      renderer.render();
+      showDbScanResults(dbScan);
+      showCompletion(targetDir, isCurrentDir, memoryOk, rootCause, isUpgrade);
+    });
   });
 
+  // ── Shell helper step ──
+
+  function runShellStep(renderer, targetPath, callback) {
+    renderer.update('shell', 'active', 'installing claudia command...');
+    try {
+      writeShellInit(homedir(), targetPath);
+      const rc = appendShellRC(homedir());
+      if (rc.skipped) {
+        renderer.update('shell', 'done', 'files written (Windows: source manually)');
+      } else if (rc.added.length > 0) {
+        renderer.update('shell', 'done', `added to ${rc.added.length} rc file(s)`);
+      } else {
+        renderer.update('shell', 'done', 'already installed');
+      }
+    } catch (err) {
+      renderer.update('shell', 'warn', `${err.message}`);
+    }
+    callback();
+  }
+
   // ── Vault step ──
 
   function runVaultStep(renderer, callback) {
@@ -1651,6 +1719,7 @@ async function main() {
         console.log('');
         console.log(`   ${colors.cyan}${launchCmd}${colors.reset}`);
         console.log('');
+        console.log(` ${colors.dim}Tip: open a new terminal and just type ${colors.reset}${colors.cyan}claudia${colors.reset}${colors.dim} from anywhere.${colors.reset}`);
         console.log(` ${colors.dim}What's new: /morning-brief · /inbox-check · /feedback${colors.reset}`);
       } else {
         // Fresh install: build anticipation for the onboarding
@@ -1661,6 +1730,7 @@ async function main() {
         }
         console.log(`   ${colors.cyan}claude${colors.reset}`);
         console.log('');
+        console.log(` ${colors.dim}Or open a new terminal and type ${colors.reset}${colors.cyan}claudia${colors.reset}${colors.dim} from anywhere.${colors.reset}`);
         console.log(` ${colors.dim}She'll introduce herself and learn how you work.${colors.reset}`);
         console.log(` ${colors.dim}Try: ${colors.reset}${colors.cyan}"Say hi"${colors.reset} ${colors.dim}·${colors.reset} ${colors.cyan}/morning-brief${colors.reset} ${colors.dim}·${colors.reset} ${colors.cyan}"Who do I know?"${colors.reset}`);
       }

package/bin/shell-init.js

@@ -0,0 +1,127 @@
+// Shell helper installer for `claudia` command.
+//
+// Writes two files into ~/.claudia/:
+//   - claudia-home      : single-line file with the absolute path to the user's
+//                         Claudia install directory (where `claude` should launch).
+//   - shell-init.sh     : defines the `claudia` shell function (and `claudia yolo`).
+//
+// Then idempotently appends a one-line source to ~/.zshrc and ~/.bashrc so the
+// function is available in every new shell. The marker comment is used to detect
+// existing installs and avoid double-adding.
+//
+// On Windows we only write the files; rc-file plumbing is a no-op since neither
+// zsh nor bash is standard there. The function content is still useful for users
+// running WSL or Git Bash who source it manually.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export const SHELL_INIT_MARKER = '# Claudia shell helpers';
+
+const RC_SNIPPET = `
+${SHELL_INIT_MARKER} (\`claudia\` from anywhere, \`claudia yolo\` skips permissions)
+[ -f "$HOME/.claudia/shell-init.sh" ] && source "$HOME/.claudia/shell-init.sh"
+`;
+
+export const SHELL_INIT_CONTENT = `# Claudia shell helpers — sourced from your shell rc.
+# Edit ~/.claudia/claudia-home to change which folder \`claudia\` launches from.
+
+_claudia_home() {
+  local home_file="$HOME/.claudia/claudia-home"
+  if [ ! -f "$home_file" ]; then
+    echo "Claudia home not configured. Run: npx get-claudia ." >&2
+    return 1
+  fi
+  local dir
+  dir="$(cat "$home_file")"
+  if [ ! -d "$dir" ]; then
+    echo "Claudia home directory not found: $dir" >&2
+    echo "Fix by editing $home_file" >&2
+    return 1
+  fi
+  printf '%s' "$dir"
+}
+
+_claudia_cd() {
+  local dir
+  dir="$(_claudia_home)" || return 1
+  cd "$dir"
+}
+
+update-claudia() {
+  local dir
+  dir="$(_claudia_home)" || return 1
+  echo "Updating Claudia at $dir ..."
+  npx get-claudia "$dir"
+}
+
+claudia() {
+  case "$1" in
+    yolo)
+      shift
+      _claudia_cd && claude --dangerously-skip-permissions "$@"
+      ;;
+    update)
+      shift
+      update-claudia "$@"
+      ;;
+    setup|system-health|google|doctor|--version|-V|help|--help|-h)
+      # Pass known npm-CLI subcommands through to the binary (if installed).
+      command claudia "$@"
+      ;;
+    *)
+      _claudia_cd && claude "$@"
+      ;;
+  esac
+}
+`;
+
+// Write ~/.claudia/claudia-home and ~/.claudia/shell-init.sh.
+// Returns { homeFile, initFile } absolute paths for caller logging.
+export function writeShellInit(homeDir, claudiaTargetDir) {
+  const claudiaConfigDir = join(homeDir, '.claudia');
+  mkdirSync(claudiaConfigDir, { recursive: true });
+
+  const homeFile = join(claudiaConfigDir, 'claudia-home');
+  const initFile = join(claudiaConfigDir, 'shell-init.sh');
+
+  writeFileSync(homeFile, `${claudiaTargetDir}\n`);
+  writeFileSync(initFile, SHELL_INIT_CONTENT);
+
+  return { homeFile, initFile };
+}
+
+// Idempotently append the source line to a single rc file. Creates the file if
+// it doesn't exist (the source line is harmless on its own). Returns one of:
+//   'added'     - the source line was just appended
+//   'unchanged' - marker already present, nothing written
+function appendToRc(rcPath) {
+  let existing = '';
+  if (existsSync(rcPath)) {
+    existing = readFileSync(rcPath, 'utf8');
+    if (existing.includes(SHELL_INIT_MARKER)) {
+      return 'unchanged';
+    }
+  }
+  // Ensure separation from prior content
+  const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+  writeFileSync(rcPath, existing + sep + RC_SNIPPET);
+  return 'added';
+}
+
+// Append to the user's zsh and bash rc files. Skips on Windows.
+// Returns { added: [...], unchanged: [...] } of rc paths.
+export function appendShellRC(homeDir, platform = process.platform) {
+  const result = { added: [], unchanged: [], skipped: false };
+  if (platform === 'win32') {
+    result.skipped = true;
+    return result;
+  }
+  const rcFiles = [join(homeDir, '.zshrc'), join(homeDir, '.bashrc')];
+  for (const rc of rcFiles) {
+    const status = appendToRc(rc);
+    if (status === 'added') result.added.push(rc);
+    else result.unchanged.push(rc);
+  }
+  return result;
+}

package/memory-daemon/claudia_memory/database.py

@@ -116,7 +116,10 @@ class Database:
             conn.execute("PRAGMA synchronous = NORMAL")
             conn.execute("PRAGMA foreign_keys = ON")
             # Recover any uncommitted WAL writes from a previous crashed daemon
-            conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+            # Use PASSIVE (not TRUNCATE) so concurrent readers (e.g. Litestream)
+            # don't cause a 30-second timeout. TRUNCATE blocks all readers;
+            # PASSIVE yields cleanly if a reader holds the WAL lock.
+            conn.execute("PRAGMA wal_checkpoint(PASSIVE)")
 
             # Load sqlite-vec for vector search
             if not load_sqlite_vec(conn):

package/memory-daemon/claudia_memory/services/remember.py

@@ -436,9 +436,14 @@ class RememberService:
         Returns:
             Entity ID
         """
-        # Infer type from name keywords when no type is specified
+        # Infer type from name keywords when no type is specified.
+        # Use the smart inferencer (entities.infer_entity_type) so callers like
+        # end_session() benefit from the "AI"-suffix rule and concept fallback,
+        # matching _find_or_create_entity at line ~1871. The local legacy
+        # _infer_entity_type is preserved for direct unit-test imports.
+        # See Proposal #51 / docs/proposals/08-smarter-memory-writes.md.
         if not entity_type or not entity_type.strip():
-            entity_type = _infer_entity_type(name)
+            entity_type = _smart_infer_entity_type(name)
 
         # Run deterministic guards
         existing_names = [
@@ -1440,9 +1445,12 @@ class RememberService:
         # 5. Store entities
         if entities:
             for entity in entities:
+                # Default to empty string (not "person") so remember_entity()
+                # routes through _infer_entity_type() when type is missing.
+                # See Proposal #51 / test_entity_resolution.py for context.
                 entity_id = self.remember_entity(
                     name=entity["name"],
-                    entity_type=entity.get("type", "person"),
+                    entity_type=entity.get("type", ""),
                     description=entity.get("description"),
                     aliases=entity.get("aliases"),
                 )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-claudia",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "description": "An AI assistant who learns how you work.",
   "keywords": [
     "claudia",

package/template-v2/.claude/manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.60.0",
-  "generated": "2026-05-15T21:18:47.594Z",
+  "version": "1.61.0",
+  "generated": "2026-05-23T02:25:12.290Z",
   "algorithm": "sha256",
   "files": {
     ".claude/rules/claudia-principles.md": "939e9720421628e7f2e4c8dfbaa4aeb9c1e18e8c6a5379cd6b772a6835b812e5",
@@ -9,7 +9,7 @@
     ".claude/rules/memory-commitment.md": "49eee330b56c6ca0b5f1e01550931c4eef3dcb3249e3d0e2380de3e8dbfe31a8",
     ".claude/rules/shell-compatibility.md": "565977bc04e269b3ce7d8a7963173df4f44bb9634692ea76abb1b64f6a67513e",
     ".claude/rules/trust-north-star.md": "0188b17c26b791cf597ce975bb75d40f543aa3d6b84b7edb1309b78530b3d43f",
-    ".claude/skills/README.md": "f84c553ff5bc01f7a9a479b7358dbd16a60ee2ba11e01467fe1ed3d91e33e68e",
+    ".claude/skills/README.md": "22311215317c61dcb67975af02bdd1d7164578713ff9faf6fbed8aec14256bcd",
     ".claude/skills/agent-dispatcher.md": "b48fc5283f0a88d1ebbc692b30b6c326fef012d4168dcf721a94e3c954b76b90",
     ".claude/skills/archetypes/_base-structure.md": "c0d8df77c07aa48cd9ba9c5ba3eddb533fcea790c7f98440fa3d31405fd5c75d",
     ".claude/skills/archetypes/consultant.md": "1e0ccbf89115f92a1fa0c86b48edcce22668c4bb828ba4268376fcd6b5c05680",
@@ -20,62 +20,62 @@
     ".claude/skills/auto-research/SKILL.md": "1a54e5d82f4e87c78a54e1331ff2d32aaff12c2712058e21173aa900a57b01c3",
     ".claude/skills/auto-research/references/program-template.md": "850457de96bde5ad65d24f1018509da94dd31fec9ec45c15087031f470a28dbc",
     ".claude/skills/auto-research/references/safety-rules.md": "ae036270e86949ed0f9bface582f6038276adafd3f40a29aa733698111a26683",
-    ".claude/skills/brain/SKILL.md": "710d0defa5725a758868391f22f8518c189a5068ff376403eda431585b546b56",
-    ".claude/skills/brain-monitor/SKILL.md": "86d73e43ea09acdaa44db08454abfd0701805fe3e297d3f568119c9cb5a1f0cf",
-    ".claude/skills/capability-suggester.md": "33e559078098a532f216fa3668e48c248d10d5a7a9647c38ef6defe0e4a37361",
-    ".claude/skills/capture-meeting/SKILL.md": "c193bfd237a0f456ef04202d6eac609b2dd54dc6caabbb75c9df6456b563ea36",
+    ".claude/skills/brain/SKILL.md": "b87dd93c85923c676292bea67f7a0580ee71eea2bea05426ea6eda951a140d5c",
+    ".claude/skills/brain-monitor/SKILL.md": "6e9ce1e6e40bc612a5126d84d743c1fd7ebc596f60575873533479fdcae5b608",
+    ".claude/skills/capability-suggester.md": "06235c8ab062d356cf9b6c18c7aa44ea667e7694983a46e8ae0a9fe32e734944",
+    ".claude/skills/capture-meeting/SKILL.md": "815e7587fcd925323c379a6c57e458b3484d034338c1237378641d142c126175",
     ".claude/skills/capture-meeting/evals/basic.yaml": "47c4eb1479aeda8067bc877cebfe8688c9b2bb3ce09297e42375cdf558f412e3",
     ".claude/skills/client-health/SKILL.md": "fed639e6f2c4433cab6a6b4b59776985492dda16be3bd1e843c3e94175936655",
     ".claude/skills/commitment-detector.md": "66f9e919349d1880eb12636cec6f583be1b3fbe3b28f6180ec732d3c284af3b6",
-    ".claude/skills/connector-discovery.md": "8cf1067e840c377e0d65aae04e41fb7858da614c548cbf973421700915ad0ab3",
+    ".claude/skills/connector-discovery.md": "a6659f6ed8a182f968cdc9b4a342de9015d5579859310b77ff230ce73397cdc5",
     ".claude/skills/databases/SKILL.md": "b2ce4ae30aafa2487dabd7befd067976f0092fcef31dea7601e1683ceca0ef50",
     ".claude/skills/deep-context/SKILL.md": "2d21f93e33191c226f46909a66d21c64c84df2ac261082adef78cd68093d7b07",
-    ".claude/skills/diagnose/SKILL.md": "8bfbae6c19afc64df9cc2a7048ee62a737d41cad33e22ba099a59369814ed50f",
+    ".claude/skills/diagnose/SKILL.md": "2658936671b5752b2e033177b6e57e783afcabf09556e199d88fc48f313295ad",
     ".claude/skills/diagnose/evals/basic.yaml": "7fa4e3a255f14d7dc883f59f8fd1d796a62db92d62a543ef87b5dda92a1c0c0b",
     ".claude/skills/diagnose/references/common-issues.md": "f80b13d4b70e656151a4cb9db8c1f042378d1f6cb9f5ba8c550741d6bf34917c",
-    ".claude/skills/draft-reply/SKILL.md": "9f8210af7515c06ec15a65fa3692124c5482bdf661d82373604eb7fb670d3b97",
+    ".claude/skills/draft-reply/SKILL.md": "4658b3de3952b518d589af1a2ab21940ca31b477c68d2e03b05e20c3a11642de",
     ".claude/skills/feedback/SKILL.md": "a8b5a1e82eca177461d11c87839dbf933e358fc3214d5f1975dd2d4fff9f3be7",
-    ".claude/skills/file-document/SKILL.md": "eb74255204f00d85909b7a3e083e1e5f6495cf4cdfedd3234aa7fabcde03d0d1",
+    ".claude/skills/file-document/SKILL.md": "2ac7d37f59281511477692d61320e176b304fa65eedbd464b2dc203d9b4dd6f7",
     ".claude/skills/financial-snapshot/SKILL.md": "33ddabb7d60024eadd8e6772229d8b17db3c3fa02d1289c80330c74aa86ae00a",
     ".claude/skills/fix-duplicates/SKILL.md": "bd3d6aae0bce09bc844ba93f76abb4a97ff0286c6a4da29cd369763864fd4a86",
-    ".claude/skills/follow-up-draft/SKILL.md": "020f4bfab0845fecafd79fb72bb3a8655f8c50d6aa22c26427b489ae7f40a503",
-    ".claude/skills/growth-check/SKILL.md": "71ab16c6535d759397d97b2454cd007c1f6a3e2cab1bd6415b40989e61d987fe",
-    ".claude/skills/hire-agent.md": "c07014addd14ea132fb4b366fbeeccea000af85b7827db616da475be5ebf57ce",
-    ".claude/skills/inbox-check/SKILL.md": "c6746bd16b4f135cd4f28ebf4ce8dfe0c27c2a9a1fd6bda5676179fe02ed8666",
-    ".claude/skills/ingest-sources/SKILL.md": "07bbe32f7922e40b782314f3e0b968e547b755ede687ed3ab903caa954da6b4c",
+    ".claude/skills/follow-up-draft/SKILL.md": "49212946cb7b2db39cecd435ab6fcb7cb26cc49666306084d27676543be67281",
+    ".claude/skills/growth-check/SKILL.md": "a3ed3f2427f3639f81d16b1a2adfa268bafed795d2b0d02621bc6be318784c24",
+    ".claude/skills/hire-agent.md": "2d60d241592db7d5f30a635d11164802f907b02616fb25170f3f867d5235f067",
+    ".claude/skills/inbox-check/SKILL.md": "e2cddc91f72ffc0443d105385d2e8b464f86404a4825d308bd03a68e4ee43726",
+    ".claude/skills/ingest-sources/SKILL.md": "938b93d299649db156ad19e9a7bd5d09e950f53bc2eaf8a85386f9fdbca350d0",
     ".claude/skills/ingest-sources/references/extraction-patterns.md": "28d6dc604c4a11eacfe4523e705ad430ba8fe26632bafcccaef656e9618e5aea",
-    ".claude/skills/judgment-awareness.md": "7dfb4b457319e7f33f18c5295a64cce88aae26feef5afac8b93a00376aeb939c",
-    ".claude/skills/map-connections/SKILL.md": "92f42d86a76185bced7d64739489f10b0a8b129c8902e5d9508a471e611b8692",
-    ".claude/skills/meditate/SKILL.md": "b67f030413c4b5327cb209e543ccce0b35f5e970f70d370ce21f65426f076e37",
+    ".claude/skills/judgment-awareness.md": "0077129a87f91d295515108f3f9a68ca6874c6e38fc7f2a73a462704fa00ba2d",
+    ".claude/skills/map-connections/SKILL.md": "e8133d5e3de36e32e3858a1ee3918a577855e77ade022933097f87a0100cc9a3",
+    ".claude/skills/meditate/SKILL.md": "1d814f0c52f4309708669139ba4b637bf05a228e2381950ee3851c6145e25cc7",
     ".claude/skills/meditate/evals/basic.yaml": "daba441b2fd9d1d4afddcff6eaa9673884198b1d0f85d9d06edbe0738012291a",
-    ".claude/skills/meeting-prep/SKILL.md": "f8e4a17b795b5bc1a098cfffba09992fb4eab0db36157525605984edf50b2463",
-    ".claude/skills/memory-audit/SKILL.md": "b1f44da062c9f51381e878c20043e28336850c5180b2839a191ecb23bb73ddb0",
-    ".claude/skills/memory-health/SKILL.md": "a8a6881c33b6f1c5249267edd4cdb6315c6f23764ca04ab1dce66b94d759a78a",
+    ".claude/skills/meeting-prep/SKILL.md": "cb0b2afc41052a0652e7de30d09e71ab489162fbb09c648e3c95cec2d438ba63",
+    ".claude/skills/memory-audit/SKILL.md": "7daed2ec128ea70171b8e3ffaf4d933ca69db2637b1487f69724e3428c04663a",
+    ".claude/skills/memory-health/SKILL.md": "ef4683fe8441e36d8ac7a931a96657c67de2ad3a6e2ca58266b48d74ce167a7b",
     ".claude/skills/memory-manager.md": "62edf1ed340687da9d8896dc4a21934b39b12c8269ea7a8de1beb9d25fd894e6",
-    ".claude/skills/morning-brief/SKILL.md": "b3354754ce2d0bf43c202e0b0ccb40b473b695f37bd9085ea575b649de194cfa",
+    ".claude/skills/morning-brief/SKILL.md": "7e97e0657dccd0c0bcd3ffb783c2e7d0dd7582bf3490162cc8c1e987a49ea5dc",
     ".claude/skills/morning-brief/evals/basic.yaml": "537de9adcde134161de9ffb9602b8c920bf1464bf224d99ad6f95f854d8480b7",
-    ".claude/skills/new-person/SKILL.md": "46a08baf49f2eb9df2527772df6de9fa4cb47eaeb841d3ec26a4c52aeea91542",
+    ".claude/skills/new-person/SKILL.md": "41b98b2bac95a76e2e58ba4c695d171b1e068910436741baa534d3db2b00ca9c",
     ".claude/skills/new-person/evals/basic.yaml": "f3c09a37c05d420e67520d8132a46356fed81575dcfb817cc97caf47f230392b",
     ".claude/skills/new-workspace/SKILL.md": "c3f838b44a016b87445c66555398b666970a156288320efb183bc8cb8af2f0df",
     ".claude/skills/new-workspace/references/workspace-templates.md": "6b36e961f112d46f32fdcf19cdacf3b05b4246201be315eee79659d606a7e243",
     ".claude/skills/onboarding.md": "72fe133672f61929de0cfc7ff77699eb8856ca1e283b13acd3becffff75fca55",
-    ".claude/skills/pattern-recognizer.md": "05aad9b25a259e437d8b25dc57f0e14af81a6e53152475a571e373117b59132c",
+    ".claude/skills/pattern-recognizer.md": "6928735f17cfcd793483dba2c68d346b11450f086a4bcc24e72e9b348270534b",
     ".claude/skills/pipeline-review/SKILL.md": "7891ceb3b6f4fb19e5255ae71c5894b6da8a9c566bc317e566bd4bc282ea1a6f",
-    ".claude/skills/relationship-tracker.md": "02316fc25b141c5783b3428e297bf6513a530e8e89782115e65ad01add8bd869",
+    ".claude/skills/relationship-tracker.md": "ef351780adadf3866a545b527450727bfb49907d1e675be670f7efc3acb4e776",
     ".claude/skills/research/SKILL.md": "0d317e6350b043ee774916b923957f61dbc174e3caafc0187198fa236a2fd28d",
     ".claude/skills/research/references/source-evaluation.md": "64614b7eff83468d7ff76dd640252579f23e69e760969672e9aebe5ceb00f695",
-    ".claude/skills/risk-surfacer.md": "c69e720660c1a8cfe340fcaa56b0c30db672856d6ea75296fc94781c9efe12af",
+    ".claude/skills/risk-surfacer.md": "b01e6bc7a22df414a7ee7a5e4a108088b5d049646723cc7513fac27a3ba4856c",
     ".claude/skills/skill-index.json": "043c86f1b07f28bb54db80117437f60fb3d79ad0d18549fdc2c74921b996a56f",
     ".claude/skills/skill-router/SKILL.md": "12fc45aebc94d3ead65843cd336a88797a40856e82908cda47256c9cbb4cb60f",
     ".claude/skills/skill-router/references/overlap-clusters.md": "bc819b4892cbdf9919db392825230f4cd4eec546cd7f0c9de6c29a2468ab489a",
     ".claude/skills/structure-generator.md": "dbe70841ab60599a632687aaa3c3652361483df2fe854640c56982b60622eb19",
-    ".claude/skills/summarize-doc/SKILL.md": "f8119d070bd66d8a448276bcd355bf26a9e69de777760d376dcd9e68bd9d64ad",
+    ".claude/skills/summarize-doc/SKILL.md": "cd73acc34541c9971ce7248df87d8b26d572d0cf0b14275076f2fb321d32af3a",
     ".claude/skills/vault-awareness.md": "da4b056ea9b83ecbfb1a7ffd9318caf98c1fb38bb8334bde3b8975b8467f576b",
-    ".claude/skills/weekly-review/SKILL.md": "fe7df64d3df18a0a47f98f7d4ef83cf98cef78cd9e0170a9316005035a2c6df7",
-    ".claude/skills/what-am-i-missing/SKILL.md": "56736397717c4f0a25cab17e7258702e5b04d20b48727c262fdf66e3b2e5899f",
+    ".claude/skills/weekly-review/SKILL.md": "2a9e5697499cb2980f2954a55a53e496f734c673d64e900ee1affed771a93ec1",
+    ".claude/skills/what-am-i-missing/SKILL.md": "8557f893869c66e3cf0401b68a604c57f1edf8dcb065d469e7502c9af06c8dfe",
     ".claude/skills/wiki/SKILL.md": "e45e8db6fce1d774e36c93be27e5d9153b3ae474c48db478a4d7ff2b138e42e8",
     ".claude/skills/wiki/references/citations-and-contradictions.md": "1b16301020fdb5e4840035ca22425ebb03202694e88eb494105ff39e22e03263",
     ".claude/skills/wiki/references/page-template.md": "b19382ee9366b1e7f8c9f230881ac3c45982b59ffee0d82fe64b103862ba4745",
-    "CLAUDE.md": "736c5d95f1477ea6ef1c00d3006eeb4b369eb2bd5f3a926e4d78c42f857fa881"
+    "CLAUDE.md": "b8244c281afd5cf46544f1f68b4130672d9f6e6bcbcbae7defca3a31c09d4c12"
   }
 }

package/template-v2/.claude/skills/README.md

@@ -248,6 +248,54 @@ Include:
 - **Output Format** - Expected output structure
 - **Judgment Points** - Where to ask for confirmation
 
+## Writing a good skill description
+
+The `description:` field in a skill's frontmatter is what Claude Code uses to decide when to trigger the skill. A vague description fires inconsistently; a tight description fires reliably. Three patterns from the existing catalog earn their keep:
+
+**Verb + object + outcome + trigger phrases.** Lead with what the skill does, then list the exact phrases users say. From `capture-meeting`:
+
+> Process meeting notes or transcript to extract decisions, commitments, and insights. Use when user shares transcript or says "capture this meeting", "here are my notes from the call".
+
+**Quantify the work.** Numerical bounds disambiguate the skill from neighbors. From `deep-context`:
+
+> Full-context deep analysis for meeting prep, relationship analysis, or strategic planning. Pulls up to 180 memories across multiple dimensions for comprehensive synthesis.
+
+**State the proactive trigger threshold.** For proactive skills, name the count that fires them. From `pattern-recognizer`:
+
+> Activates when the same topic, frustration, or behavior appears across 3+ interactions.
+
+Avoid descriptions that read as aspirational ("helps you think strategically"), circular ("manages memory operations"), or multi-purpose without a clear trigger.
+
+## The "see also" convention
+
+When two skills could plausibly fire on the same situation, both should point at each other in their descriptions so a user who picked the less-canonical name finds the alternative. Pattern: append a final line to the `description:` field of the form:
+
+> See also: `<skill-name>` for <what differs>.
+
+Common overlap clusters in the current catalog:
+
+- **Outbound messages**: `draft-reply` (general) ↔ `follow-up-draft` (post-meeting)
+- **Memory**: `memory-audit` (content) ↔ `memory-health` (system) ↔ `diagnose` (connectivity)
+- **Visualization**: `brain` (3D web) ↔ `brain-monitor` (terminal)
+- **Reflective cadences**: `morning-brief` (daily) → `weekly-review` (weekly) → `growth-check` (monthly+) → `meditate` (per session)
+- **Meeting lifecycle**: `meeting-prep` (before) → `capture-meeting` (during/after notes) → `follow-up-draft` (after, outbound)
+- **Inbound processing**: `ingest-sources` (multi-doc) ↔ `file-document` (single) ↔ `capture-meeting` (meeting only) ↔ `summarize-doc` (no filing)
+
+## Disambiguation notes
+
+- `connector-discovery` is about connecting external services (Gmail, Calendar, Slack). It is not about people or human connections. For people, see `relationship-tracker`, `new-person`, and `map-connections`.
+- `pattern-recognizer` notices what's recurring. `judgment-awareness` applies the user's decision rules to a recurring situation. `capability-suggester` proposes a new command when the same task is repeated by hand. Three skills, three different stages of "we keep doing this."
+
+## Proactive vs contextual: when to make a skill auto-fire
+
+A skill with `invocation: proactive` runs without the user asking. This is powerful but expensive: every proactive skill loaded into context is a tax on every conversation. Use proactive only when:
+
+1. The trigger condition is **specific enough that false positives are rare** (e.g., commitment-detector watches for explicit promise phrasing, not vague intentions).
+2. The action is **observational**, not mutative (surface a pattern, not send an email).
+3. The output is **brief**, ideally one line, deferring detail to a follow-up question.
+
+Contextual skills (no `invocation` set, or `invocation: contextual`) are cheaper. They wait for the user to invoke them by name or phrase. Default to contextual; promote to proactive only after observing repeated manual invocations of the same skill.
+
 ## Archetype Templates
 
 The `archetypes/` folder contains structure and command templates for each user type:

package/template-v2/.claude/skills/brain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain
-description: Launch the Brain Visualizer, a real-time 3D view of memory and relationships. Triggers on "show your brain", "visualize memory", "open the brain", "memory graph".
+description: Launch the Brain Visualizer, a real-time 3D view of memory and relationships. Triggers on "show your brain", "visualize memory", "open the brain", "memory graph". See also: `brain-monitor` for a terminal dashboard alternative.
 effort-level: medium
 ---
 

package/template-v2/.claude/skills/brain-monitor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain-monitor
-description: Launch the Brain Monitor TUI, a real-time terminal dashboard for watching Claudia's memory system. Triggers on "brain monitor", "show dashboard", "memory dashboard", "terminal brain".
+description: Launch the Brain Monitor TUI, a real-time terminal dashboard for watching Claudia's memory system. Triggers on "brain monitor", "show dashboard", "memory dashboard", "terminal brain". See also: `brain` for a 3D graph view in the browser.
 effort-level: low
 ---
 

package/template-v2/.claude/skills/capability-suggester.md

@@ -1,6 +1,6 @@
 ---
 name: capability-suggester
-description: Notice repeated user behaviors and suggest new commands, workflows, structure, or integrations to streamline work. Also detects when the user's setup has outgrown its current structure and suggests targeted upgrades. Activates when repeated task patterns, workflow friction, structural gaps, or business growth signals are detected.
+description: Notice repeated user behaviors and suggest new commands, workflows, structure, or integrations to streamline work. Also detects when the user's setup has outgrown its current structure and suggests targeted upgrades. Activates when repeated task patterns, workflow friction, structural gaps, or business growth signals are detected. See also: `pattern-recognizer` for theme detection upstream; `hire-agent` for adding specialized subagents.
 user-invocable: false
 invocation: proactive
 effort-level: high

package/template-v2/.claude/skills/capture-meeting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: capture-meeting
-description: Process meeting notes or transcript to extract decisions, commitments, and insights. Use when user shares transcript or says "capture this meeting", "here are my notes from the call".
+description: Process meeting notes or transcript to extract decisions, commitments, and insights. Use when user shares transcript or says "capture this meeting", "here are my notes from the call". See also: `meeting-prep` for pre-call briefings; `follow-up-draft` for post-meeting emails.
 effort-level: medium
 ---
 

package/template-v2/.claude/skills/connector-discovery.md

@@ -1,6 +1,6 @@
 ---
 name: connector-discovery
-description: Help users connect their external tools in a gentle, non-technical way. Recommend solutions based on what works best, explain everything in plain language.
+description: Help users connect their external tools in a gentle, non-technical way. Recommend solutions based on what works best, explain everything in plain language. Note: this is about external service connectors (Gmail, Calendar), not human connections. See `relationship-tracker` and `map-connections` for person and relationship features.
 effort-level: high
 ---
 

package/template-v2/.claude/skills/diagnose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: diagnose
-description: Check memory system health and troubleshoot connectivity issues. Use when memory commands aren't working, at session start if something seems wrong, or when user asks about memory status.
+description: Check memory system health and troubleshoot connectivity issues. Use when memory commands aren't working, at session start if something seems wrong, or when user asks about memory status. See also: `memory-health` for the data-quality dashboard once connectivity is confirmed.
 effort-level: low
 ---
 

package/template-v2/.claude/skills/draft-reply/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draft-reply
-description: Draft an email response with tone matching the relationship context. Shows draft for approval before sending. Use when user says "draft a reply", "respond to this email", "write a response to [person]", or shares an email and asks for help replying.
+description: Draft an email response with tone matching the relationship context. Shows draft for approval before sending. Use when user says "draft a reply", "respond to this email", "write a response to [person]", or shares an email and asks for help replying. See also: `follow-up-draft` for post-meeting thank-yous with meeting context.
 effort-level: medium
 ---
 

package/template-v2/.claude/skills/file-document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-document
-description: Store a document, email, or text for future reference with entity linking and provenance.
+description: Store a document, email, or text for future reference with entity linking and provenance. See also: `ingest-sources` for multiple files; `capture-meeting` if it's meeting notes; `summarize-doc` to get a summary without filing.
 effort-level: medium
 ---
 

package/template-v2/.claude/skills/follow-up-draft/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: follow-up-draft
-description: Create a post-meeting thank-you or follow-up email with key points and next steps. Use when user says "follow-up email", "thank you note", "post-meeting email", "send a follow-up to [person]", or after a meeting capture when next steps need communicating.
+description: Create a post-meeting thank-you or follow-up email with key points and next steps. Use when user says "follow-up email", "thank you note", "post-meeting email", "send a follow-up to [person]", or after a meeting capture when next steps need communicating. See also: `draft-reply` for general email responses unrelated to a meeting.
 argument-hint: "[person name]"
 effort-level: medium
 ---

package/template-v2/.claude/skills/growth-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: growth-check
-description: Periodic reflection on development, skills, learning, and progress toward goals. Triggers on "am I growing?", "development check", "personal growth review".
+description: Periodic reflection on development, skills, learning, and progress toward goals. Triggers on "am I growing?", "development check", "personal growth review". See also: `weekly-review` for tactical week recap; `meditate` for session-level reflection.
 effort-level: low
 ---
 

package/template-v2/.claude/skills/hire-agent.md

@@ -1,6 +1,6 @@
 ---
 name: hire-agent
-description: Suggests new agents based on repeated task patterns.
+description: Suggests new agents based on repeated task patterns. See also: `capability-suggester` for skill or command-level additions; `agent-dispatcher` for routing logic.
 user-invocable: false
 invocation: proactive
 effort-level: high

package/template-v2/.claude/skills/inbox-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: inbox-check
-description: Lightweight inbox triage across all configured email accounts. Dispatches fast subagent to fetch, then reviews with judgment. Use when user says "check my inbox", "any new emails?", "check email".
+description: Lightweight inbox triage across all configured email accounts. Dispatches fast subagent to fetch, then reviews with judgment. Use when user says "check my inbox", "any new emails?", "check email". See also: `draft-reply` once you pick an email to respond to.
 effort-level: low
 ---
 

package/template-v2/.claude/skills/ingest-sources/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ingest-sources
-description: Process multiple source documents with Extract-Then-Aggregate discipline. Use when user shares multiple transcripts, emails, or documents for batch processing.
+description: Process multiple source documents with Extract-Then-Aggregate discipline. Use when user shares multiple transcripts, emails, or documents for batch processing. See also: `capture-meeting` for a single meeting transcript; `file-document` for a single document; `summarize-doc` when you only need a summary.
 argument-hint: [folder-path]
 effort-level: max
 ---

package/template-v2/.claude/skills/judgment-awareness.md

@@ -1,6 +1,6 @@
 ---
 name: judgment-awareness
-description: Load and apply user-defined judgment rules from context/judgment.yaml to inform priority conflicts, escalation decisions, surfacing, and delegation.
+description: Load and apply user-defined judgment rules from context/judgment.yaml to inform priority conflicts, escalation decisions, surfacing, and delegation. See also: `pattern-recognizer` for theme detection; `meditate` updates judgment rules at session end.
 user-invocable: false
 invocation: proactive
 effort-level: low

package/template-v2/.claude/skills/map-connections/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: map-connections
-description: Scan context files to extract entities and relationships into the memory system. Triggers on "who knows who?", "network graph", "map my connections", "extract relationships".
+description: Scan context files to extract entities and relationships into the memory system. Triggers on "who knows who?", "network graph", "map my connections", "extract relationships". See also: `brain` for graph visualization once relationships are extracted.
 argument-hint: "[--incremental] [file-path]"
 effort-level: high
 ---

package/template-v2/.claude/skills/meditate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: meditate
-description: End-of-session reflection generating persistent learnings about user preferences, communication patterns, and cross-session insights. Activates when wrapping up a session, or when user says "let's wrap up", "end the session", "time to reflect", or "meditate". Also extracts judgment rules from decisions made during the session.
+description: End-of-session reflection generating persistent learnings about user preferences, communication patterns, and cross-session insights. Activates when wrapping up a session, or when user says "let's wrap up", "end the session", "time to reflect", or "meditate". Also extracts judgment rules from decisions made during the session. See also: `weekly-review` and `growth-check` for time-based reflection cadences.
 effort-level: high
 ---
 

package/template-v2/.claude/skills/meeting-prep/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: meeting-prep
-description: One-page briefing before a call or meeting with person context, open items, and talking points. Use when user says "prep me for my call with [person]", "meeting prep", "brief me before my meeting", "get ready for my call", or mentions an upcoming meeting where context would help.
+description: One-page briefing before a call or meeting with person context, open items, and talking points. Use when user says "prep me for my call with [person]", "meeting prep", "brief me before my meeting", "get ready for my call", or mentions an upcoming meeting where context would help. See also: `capture-meeting` for processing notes after the call; `follow-up-draft` for thank-yous.
 argument-hint: [person or meeting name]
 effort-level: medium
 ---

package/template-v2/.claude/skills/memory-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-audit
-description: Show everything Claudia knows with provenance tracing and entity counts. Triggers on "what do you know?", "show memories", "memory audit", "what do you remember about".
+description: Show everything Claudia knows with provenance tracing and entity counts. Triggers on "what do you know?", "show memories", "memory audit", "what do you remember about". See also: `memory-health` for system-level stats and data quality; `diagnose` for connectivity troubleshooting.
 argument-hint: "[entity name]"
 effort-level: medium
 ---

package/template-v2/.claude/skills/memory-health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-health
-description: Check memory system health and data quality. Use when user asks "how's my memory?", "system health", "memory stats", "data quality", "how's my brain?", or for periodic self-diagnostics.
+description: Check memory system health and data quality. Use when user asks "how's my memory?", "system health", "memory stats", "data quality", "how's my brain?", or for periodic self-diagnostics. See also: `memory-audit` for content-level provenance; `diagnose` for daemon connectivity issues.
 effort-level: medium
 ---
 

package/template-v2/.claude/skills/morning-brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: morning-brief
-description: Daily digest of commitments, warnings, and relationship health. Use when starting your day or asking "what's on my plate".
+description: Daily digest of commitments, warnings, and relationship health. Use when starting your day or asking "what's on my plate". See also: `weekly-review` (end of week), `growth-check` (monthly+), `meditate` (end of session).
 effort-level: low
 ---
 

package/template-v2/.claude/skills/new-person/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: new-person
-description: Create a relationship tracking file for a person with contact info, history, and communication preferences. Use when user says "new person", "add [name]", "create a file for [name]", "track this person", or mentions someone important who doesn't have a file yet.
+description: Create a relationship tracking file for a person with contact info, history, and communication preferences. Use when user says "new person", "add [name]", "create a file for [name]", "track this person", or mentions someone important who doesn't have a file yet. See also: `relationship-tracker` for ongoing health; `meeting-prep` when you have a call coming up.
 argument-hint: "[name]"
 effort-level: medium
 ---

package/template-v2/.claude/skills/pattern-recognizer.md

@@ -1,6 +1,6 @@
 ---
 name: pattern-recognizer
-description: Notice trends, recurring themes, and patterns across conversations and surface them when relevant. Activates when the same topic, frustration, or behavior appears across 3+ interactions. Use for "I've noticed you keep...", "this is the third time...", recurring scheduling issues, or avoidance patterns.
+description: Notice trends, recurring themes, and patterns across conversations and surface them when relevant. Activates when the same topic, frustration, or behavior appears across 3+ interactions. Use for "I've noticed you keep...", "this is the third time...", recurring scheduling issues, or avoidance patterns. See also: `judgment-awareness` for applying user-set decision rules; `capability-suggester` for converting patterns into new commands.
 user-invocable: false
 invocation: proactive
 effort-level: high

package/template-v2/.claude/skills/relationship-tracker.md

@@ -1,6 +1,6 @@
 ---
 name: relationship-tracker
-description: Surface relevant context when people are mentioned in conversation, and track relationship health over time.
+description: Surface relevant context when people are mentioned in conversation, and track relationship health over time. See also: `new-person` to create a file for someone important; `map-connections` to extract relationships across files.
 user-invocable: false
 invocation: proactive
 effort-level: high

package/template-v2/.claude/skills/risk-surfacer.md

@@ -1,6 +1,6 @@
 ---
 name: risk-surfacer
-description: Proactively identify and surface potential problems before they become crises.
+description: Proactively identify and surface potential problems before they become crises. See also: `what-am-i-missing` for a user-invoked, full-sweep version.
 user-invocable: false
 invocation: proactive
 effort-level: high

package/template-v2/.claude/skills/summarize-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: summarize-doc
-description: Create an executive summary of any document at the appropriate level of detail. Triggers on "summarize this", "main points", "give me the gist".
+description: Create an executive summary of any document at the appropriate level of detail. Triggers on "summarize this", "main points", "give me the gist". See also: `file-document` if you also want to save it; `capture-meeting` if it's meeting notes.
 effort-level: medium
 ---
 

package/template-v2/.claude/skills/weekly-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weekly-review
-description: Guided weekly reflection across all relationships, commitments, and projects with pattern analysis. Use at end of week, or when user says "weekly review", "end of week", "reflect on this week", "weekly check-in", or "how did my week go".
+description: Guided weekly reflection across all relationships, commitments, and projects with pattern analysis. Use at end of week, or when user says "weekly review", "end of week", "reflect on this week", "weekly check-in", or "how did my week go". See also: `morning-brief` (daily), `growth-check` (zoom out), `meditate` (session reflection).
 effort-level: high
 ---
 

package/template-v2/.claude/skills/what-am-i-missing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: what-am-i-missing
-description: Surface risks, blind spots, overlooked items, and accountability across commitments and relationships. Triggers on "what am I overlooking?", "blind spots", "what's falling through the cracks", "what do I owe?", "am I overdue?", "check my commitments".
+description: Surface risks, blind spots, overlooked items, and accountability across commitments and relationships. Triggers on "what am I overlooking?", "blind spots", "what's falling through the cracks", "what do I owe?", "am I overdue?", "check my commitments". See also: `risk-surfacer` for the proactive auto-firing version on overdue items and cooling relationships.
 argument-hint: "[person name or 'overdue']"
 effort-level: high
 ---

package/template-v2/CLAUDE.md

@@ -104,7 +104,7 @@ Uses three shades to approximate the installer's coloring: `▓▓` = hair, `█
 
 ```
 
-      ▓▓▓▓▓▓▓▓▒▒
+  ▓▓▓▓▓▓▓▓▒▒
 ▓▓██████████▒▒
 ▓▓██  ██  ██▓▓
   ██████████
@@ -304,6 +304,27 @@ I use proactive, contextual, and explicit skills. See `.claude/skills/README.md`
 | My learnings about you | `context/learnings.md` |
 | Project details | `projects/[project]/overview.md` |
 | Filed documents | `~/.claudia/files/` (entity-routed) |
+| Shell helper init | `~/.claudia/shell-init.sh` (sourced from `.zshrc`/`.bashrc`) |
+| Install path pointer | `~/.claudia/claudia-home` (one line, absolute path) |
+
+---
+
+## Launching from the Terminal
+
+Once installed, the `claudia` shell command works from any directory:
+
+| You type | What happens |
+|----------|--------------|
+| `claudia` | cd to your Claudia folder, launch `claude` |
+| `claudia yolo` | cd, launch `claude --dangerously-skip-permissions` |
+| `claudia -c "morning brief"` | cd, launch `claude -c "morning brief"` (any `claude` flag passes through) |
+| `claudia --resume` | cd, launch `claude --resume` |
+| `claudia update` / `update-claudia` | runs `npx get-claudia <your-install-path>` from anywhere — no need to cd first |
+| `claudia setup` / `claudia system-health` | passes through to the npm `claudia` CLI binary |
+
+The folder location is stored in `~/.claudia/claudia-home`. Move your install? Edit that file. Re-run `npx get-claudia .` from a new location and it'll update automatically.
+
+On Windows the shell function is written to `~/.claudia/shell-init.sh` but not auto-sourced. WSL or Git Bash users can `source ~/.claudia/shell-init.sh` manually (or add it to their rc file).
 
 ---