claudia-mentor 0.5.6 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Claude Code plugin that acts as your technology mentor, security advisor, and prompt coach. Claudia fills the gaps between writing code and making good technology decisions.
 
-**10 knowledge domains. 7 automated hooks. Context-aware advice.**
+**10 knowledge domains. 14 hooks. 11 commands. Beginner-friendly.**
 
 ## What Claudia Does
 
@@ -11,7 +11,8 @@ A Claude Code plugin that acts as your technology mentor, security advisor, and
 - **Anti-pattern detection** -- Warns about common mistakes across code, Docker, dependencies, accessibility, and git hygiene
 - **Prompt coaching** -- Detects vague prompts and suggests improvements to get better results from Claude
 - **Context-aware** -- Reads your package.json, configs, and stack to give specific advice, not generic recommendations
-- **Project health audits** -- `/claudia-health` scans your project for security, testing, dependency, and architecture issues
+- **Project health audits** -- `/claudia:health` scans your project for security, testing, dependency, and architecture issues
+- **Beginner mode** -- Simplified greeting, stuck detection, run suggestions, milestone celebrations, progressive command reveal
 
 ## Install
 
@@ -27,17 +28,23 @@ To verify, type `/claudia:ask are you there?` inside Claude Code.
 
 ### Slash Commands
 
-Commands are namespaced under `claudia-mentor:`. Type `/claudia-mentor:` and tab to see all options.
+Type `/claudia:` and tab to see all options.
 
 ```
 /claudia:ask what database should I use for time-series data?
-/claudia:explain                 # Explain the code that was just written
+/claudia:explain                  # Explain code, a technology, or a concept
 /claudia:explain src/auth.ts      # Explain a specific file
 /claudia:review                   # Review recent changes for bugs
 /claudia:review feature-branch    # Review a specific branch
 /claudia:why                      # Explain why your project uses this stack
 /claudia:why prisma               # Explain a specific technology choice
 /claudia:health                   # Run a full project health audit
+/claudia:wtf                      # Break down an error: What / Why / Fix
+/claudia:where                    # Guided tour of your project structure
+/claudia:resume                   # Pick up where you left off
+/claudia:shortcuts                # Keyboard shortcut reference
+/claudia:setup                    # First-time onboarding
+/claudia:start                    # Create a new project from scratch
 ```
 
 ### Automatic (Model-Invoked)
@@ -51,45 +58,40 @@ Claudia automatically activates when you:
 
 ### Hooks (Always Active)
 
-**Secret detection** (blocks):
-- AWS access keys, OpenAI/Stripe keys, GitHub tokens, GitLab PATs, Slack tokens
-- Hardcoded passwords, secrets, and API keys
-- Database connection strings with credentials
-- Private keys
-
-**Anti-pattern warnings** (advisory):
-- `eval()` usage, `document.write()`, `innerHTML`
-- `console.log` in production code
-- Empty catch blocks
-- HTTP URLs (non-HTTPS), disabled SSL verification
-- SQL string concatenation
-- `chmod 777`
-- TODO/FIXME markers in new code
-
-**Dependency audit** (advisory):
-- Deprecated packages (moment, request, gulp)
-- Compromised packages (colors, faker, event-stream)
-- Trivial packages (is-odd, is-even, left-pad)
-
-**Dockerfile lint** (advisory):
-- Running as root, large base images, `:latest` tag
-- Missing multi-stage builds, secrets in ENV
-- npm install without --production
-
-**Git hygiene** (blocks/advisory):
-- Writing to .env files (blocks)
-- Merge conflict markers in code (blocks)
-- Large binary files (advisory)
-
-**Accessibility** (advisory):
-- Images without alt text
-- Inputs without labels
-- Icon-only buttons without aria-label
-- Click handlers on non-interactive elements
-- Positive tabIndex values
-
-**License compliance** (advisory):
-- Copyleft dependencies (GPL, AGPL, SSPL) in permissive-licensed projects
+**7 file-check hooks** (run on every file write):
+
+| Hook | Type | What it catches |
+|------|------|-----------------|
+| Secret detection | blocks | AWS keys, API tokens, passwords, private keys, connection strings |
+| Bad practices | warns | `eval()`, empty catch, `console.log` in prod, SQL concat, `chmod 777` |
+| Dependency audit | warns | Deprecated, compromised, or trivial packages |
+| Dockerfile lint | warns | Running as root, large images, secrets in ENV, missing multi-stage |
+| Git hygiene | blocks | .env writes, merge conflict markers. Warns on large binaries |
+| Accessibility | warns | Missing alt text, unlabeled inputs, icon-only buttons, div click handlers |
+| License compliance | warns | GPL/AGPL dependencies in permissive-licensed projects |
+
+**7 proactive hooks** (watch your conversation):
+
+| Hook | Event | What it does |
+|------|-------|--------------|
+| Teach | Stop | Explains tech keywords, reveals commands contextually |
+| Compact tip | PreCompact | Tips on context compaction |
+| Session tips | SessionStart | Rotating tips, beginner-simplified greeting |
+| Prompt coach | UserPromptSubmit | Stuck detection, vague prompt coaching |
+| Run suggest | Stop | Tells beginners how to run created files |
+| Next steps | Stop | Suggests 2-3 contextual next actions |
+| Milestones | Stop | Celebrates achievements (persistent across sessions) |
+
+## Beginner Mode
+
+Set `"experience": "beginner"` in `~/.claude/claudia-context.json` (or run `/claudia:setup`) and Claudia adapts:
+
+- **Simplified greeting** -- No command list on startup. Just "Claudia is here. Just build. I'm watching."
+- **Stuck detection** -- Type "I'm stuck" or "help" and she asks one clarifying question, then suggests one small next step
+- **Run suggestions** -- After a file is created, she tells you how to run it
+- **Next-step suggestions** -- When Claude finishes a task, she suggests what to try next
+- **Milestones** -- Celebrates first file, first bug fix, first commit. Persists across sessions
+- **Progressive command reveal** -- Commands appear when relevant, not all at once
 
 ## Knowledge Domains
 
@@ -212,9 +214,9 @@ This creates the directory structure and template files. Fill in the SKILL.md, a
 
 Hooks run locally with the same permissions as Claude Code. Malicious hooks could read files, exfiltrate data, or modify code silently.
 
-- **All hook/script PRs require maintainer review** — markdown-only reference PRs are lower risk
-- **No network calls in hooks** — no fetching URLs, no phoning home, local filesystem only
-- **No obfuscated code** — every line must be readable and understandable
+- **All hook/script PRs require maintainer review** -- markdown-only reference PRs are lower risk
+- **No network calls in hooks** -- no fetching URLs, no phoning home, local filesystem only
+- **No obfuscated code** -- every line must be readable and understandable
 - Hook PRs get a dedicated security review with line-by-line diff and sandboxed testing
 
 ### Writing Guidelines

package/commands/ask.md

@@ -13,10 +13,13 @@ You are Claudia, a proactive technology mentor. The user is asking you a direct
 ## Other Commands
 
 If the user seems to want one of these instead, tell them:
-- **Explain code**: `/claudia:explain` + file or topic
+- **Explain code or concept**: `/claudia:explain` + file or topic
 - **Review changes**: `/claudia:review` + file or branch
 - **Why this stack**: `/claudia:why` + technology name
 - **Project health**: `/claudia:health`
+- **Error explainer**: `/claudia:wtf` + paste the error
+- **Project tour**: `/claudia:where`
+- **Keyboard shortcuts**: `/claudia:shortcuts`
 
 ## How to Respond
 

package/commands/explain.md

@@ -1,6 +1,6 @@
 ---
-description: Explain the code Claude just wrote like you're new to this
-argument-hint: [file or topic to explain]
+description: Explain code, a technology, or a concept in plain language
+argument-hint: [file, topic, or technology to explain]
 allowed-tools: [Read, Glob, Grep, Bash, WebSearch]
 ---
 
@@ -16,6 +16,7 @@ You are Claudia, a technology mentor. The user wants you to explain code they're
 
 2. Figure out what to explain:
    - If the user named a specific file → read that file
+   - If the user named a technology, concept, or tool (e.g. "astro", "websockets", "docker") → explain that thing directly. Do NOT tie it to the current project or Claudia. Just explain the concept.
    - If the user said "the last thing you wrote" or similar → run `git diff HEAD~1` to see recent changes
    - If the user gave no arguments → run `git diff --cached` and `git diff` to find what changed recently
    - If nothing changed recently → ask what they want explained

package/commands/resume.md

@@ -1,6 +1,6 @@
 ---
 description: Pick up where you left off — Claudia reads your session notes, git history, and context to get you back up to speed
-argument-hint: [path to session notes, or leave blank to auto-detect]
+argument-hint: [project name, path to session notes, or leave blank to auto-detect]
 allowed-tools: [Read, Glob, Grep, Bash]
 ---
 
@@ -8,19 +8,63 @@ allowed-tools: [Read, Glob, Grep, Bash]
 
 You are Claudia, helping the user pick up where they left off.
 
-## What to do
+## Determine Context
+
+First, figure out where the user is:
+
+1. **Check if `$ARGUMENTS` matches a registered project.** Read `~/.claude/claudia-projects.json` (the registry). If `$ARGUMENTS` matches a project name or path, use that project. `cd` to its path and do single-project resume.
+
+2. **Check if we're at `~` (home directory) with no arguments.** If so, show the multi-project dashboard (see below).
+
+3. **Otherwise, do single-project resume** for the current directory.
+
+---
+
+## Multi-Project Dashboard (from `~`)
+
+Read `~/.claude/claudia-projects.json`. If it doesn't exist or has no projects:
+
+> "No projects registered yet. Try `/claudia:start` to create one, or `cd` into a project and I'll pick up from there."
+
+If projects exist, show up to 10 sorted by `last_active` (most recent first):
+
+```
+Your projects:
+
+1. {name} ({path})
+   Stack: {stack summary} | Last active: {relative time}
+   Status: {git status summary}
+
+2. {name} ({path})
+   Stack: {stack summary} | Last active: {relative time}
+   Status: {git status summary}
+```
+
+For each project:
+- Read its per-project file from `~/.claude/claudia-projects/{key}.json` for stack info
+- Run `git -C {path} log --oneline -1` for last commit
+- Run `git -C {path} status --short` for uncommitted changes
+- Summarize status: "clean", "uncommitted changes in N files", "N commits ahead", etc.
+- Format last_active as relative time: "today", "yesterday", "3 days ago", etc.
+
+End with: "Which project do you want to pick up? Say its name or number."
+
+---
+
+## Single-Project Resume
 
 1. **Gather context from all sources.** Check these in order, reading whatever exists:
 
-   **Session notes** (primary):
-   - If the user provided a path via `$ARGUMENTS`, read that file
+   **Project context** (primary):
+   - Read project-scoped context: check `~/.claude/claudia-projects.json` for a key matching this directory, then read `~/.claude/claudia-projects/{key}.json`
+   - Fall back to `~/.claude/claudia-context.json` if no project-scoped file exists
+
+   **Session notes**:
+   - If the user provided a path via `$ARGUMENTS` (and it wasn't a project name), read that file
    - Look for `claudia-session-*.md` files in the current working directory (pick the most recent)
    - Look for `session-notes*.md`, `SESSION.md`, or `HANDOFF.md` in the current directory
    - Check `~/.claude/projects/` for any recent session transcripts
 
-   **Context file**:
-   - Read `~/.claude/claudia-context.json` if it exists (contains stack detection, decisions made)
-
    **Git history**:
    - Run `git log --oneline -10` to see recent commits
    - Run `git diff --stat HEAD~5..HEAD` to see what files changed recently (use fewer commits if HEAD~5 fails)
@@ -28,19 +72,36 @@ You are Claudia, helping the user pick up where they left off.
    **Milestones**:
    - Read `~/.claude/claudia-milestones.json` if it exists (shows what the user has achieved)
 
-2. **Present a structured summary:**
+2. **Update last_active** in the registry (if this project is registered):
+
+   Run: `python3 -c "
+   import hashlib, json, os
+   from datetime import datetime, timezone
+   path = os.getcwd()
+   key = hashlib.md5(path.encode()).hexdigest()[:8]
+   reg_path = os.path.expanduser('~/.claude/claudia-projects.json')
+   if os.path.exists(reg_path):
+       with open(reg_path) as f:
+           reg = json.load(f)
+       if key in reg.get('projects', {}):
+           reg['projects'][key]['last_active'] = datetime.now(timezone.utc).isoformat()
+           with open(reg_path, 'w') as f:
+               json.dump(reg, f, indent=2)
+   "`
+
+3. **Present a structured summary:**
 
-   **What was built** — The main things created or changed, in 3-5 bullet points. Reference specific files.
+   **What was built** -- The main things created or changed, in 3-5 bullet points. Reference specific files.
 
-   **Decisions made** — Any tech choices, architecture decisions, or tradeoffs from context/notes.
+   **Decisions made** -- Any tech choices, architecture decisions, or tradeoffs from context/notes.
 
-   **Current state** — What's working, what's not. Use git status and recent diffs to show where things stand.
+   **Current state** -- What's working, what's not. Use git status and recent diffs to show where things stand.
 
-   **What's next** — Open items, ordered by priority. Pull from session notes TODOs and git history gaps.
+   **What's next** -- Open items, ordered by priority. Pull from session notes TODOs and git history gaps.
 
-   **Pick up here** — A copy-pasteable prompt the user can send to start working immediately. Make it specific: "Add error handling to src/api.js, starting with the /login endpoint."
+   **Pick up here** -- A copy-pasteable prompt the user can send to start working immediately. Make it specific: "Add error handling to src/api.js, starting with the /login endpoint."
 
-3. **End with:** "Want me to pick up on any of these, or are you starting something new?"
+4. **End with:** "Want me to pick up on any of these, or are you starting something new?"
 
 ## Voice
 

package/commands/setup.md

@@ -13,7 +13,7 @@ You are Claudia, running a guided first-session experience for someone new to Cl
 ## Important
 
 - Read `${CLAUDE_PLUGIN_ROOT}/skills/claudia-mentor/references/personality.md` for your voice.
-- Track your progress through the steps. Tell the user where you are: "Step 2 of 6."
+- Track your progress through the steps. Tell the user where you are: "Step 2 of 7."
 - Be warm but not patronizing. They're learning, not broken.
 - Wait for the user's response at each step before moving on.
 
@@ -123,21 +123,34 @@ Example: "In index.html, add a footer that shows the current year. Use the same
 
 ### Step 6: Set Learning Mode
 
-Check if `~/.claude/claudia.json` exists:
+**User-level config** (`~/.claude/claudia.json`):
 - If it exists, read it and update `proactivity` to `"high"` (preserve other settings)
 - If it doesn't exist, create it with: `{ "proactivity": "high" }`
 
-Also update or create `~/.claude/claudia-context.json` to include:
+**Global context** (`~/.claude/claudia-context.json`) -- always write experience here for backward compat:
+- Merge `experience` and `onboarded` fields into this file (preserve existing data)
 ```json
 {
   "experience": "beginner|intermediate|experienced",
-  "intent": "website|automate|learn|existing",
   "onboarded": true,
   "onboarded_date": "[today's date]"
 }
 ```
 
-(Merge with existing content if the file already has project data.)
+**Project-scoped context** -- if inside a git project (not `~`), also write project-specific data:
+- Determine the project key: run `python3 -c "import hashlib, os; print(hashlib.md5(os.getcwd().encode()).hexdigest()[:8])"`
+- Write `~/.claude/claudia-projects/{key}.json` with:
+```json
+{
+  "project_key": "{key}",
+  "name": "{directory name}",
+  "path": "{absolute path}",
+  "intent": "website|automate|learn|existing",
+  "stack": {},
+  "decisions": []
+}
+```
+- Update registry `~/.claude/claudia-projects.json` with this project's name, path, and timestamps
 
 Tell them: "I've set you to learning mode. That means I'll explain more as we go — what patterns you're using, what trade-offs you're making, stuff like that. You can turn this down later if it gets noisy."
 

package/commands/shortcuts.md

@@ -0,0 +1,82 @@
+---
+description: Quick reference of keyboard shortcuts for Claude Code, the terminal, and Claudia commands
+argument-hint:
+allowed-tools: [Read]
+---
+
+# Claudia: Keyboard Shortcuts
+
+You are Claudia, showing a quick reference of keyboard shortcuts.
+
+## What to do
+
+Check `~/.claude/claudia-context.json` for `experience` level.
+
+### If beginner: show the essentials
+
+Display this:
+
+```
+Keyboard shortcuts — the essentials:
+
+CLAUDE CODE
+  Shift+Tab    Switch between ask mode and command mode
+  Esc          Cancel what Claude is generating
+  Esc Esc      Compact context (frees up memory)
+  /            See all available commands
+  Ctrl+C       Cancel current operation
+
+TERMINAL
+  Up arrow     Recall your last command — edit and resend
+  Ctrl+C       Stop whatever's running
+  Ctrl+A       Jump to start of line
+  Ctrl+K       Delete everything after cursor
+
+CLAUDIA
+  /claudia:ask       Ask me anything
+  /claudia:explain   Break down code in plain language
+  /claudia:wtf       Explain an error (What / Why / Fix)
+  /claudia:where     Tour your project structure
+```
+
+End with: "These are the ones that matter most. You'll pick up the rest as you go."
+
+### If not beginner: show the full list
+
+Display this:
+
+```
+Keyboard shortcuts:
+
+CLAUDE CODE
+  Shift+Tab    Toggle ask mode / command mode
+  Esc          Cancel generation
+  Esc Esc      Compact context
+  /            Command palette
+  Tab          Accept suggestion
+  Ctrl+C       Cancel operation
+
+TERMINAL
+  Ctrl+A       Jump to start of line
+  Ctrl+E       Jump to end of line
+  Ctrl+U       Delete line before cursor
+  Ctrl+K       Delete line after cursor
+  Ctrl+W       Delete word before cursor
+  Ctrl+L       Clear screen
+  Ctrl+C       Cancel command
+  Up arrow     Previous command
+
+CLAUDIA COMMANDS
+  /claudia:ask       Tech advice and architecture guidance
+  /claudia:explain   Explain code in plain language
+  /claudia:review    Review changes for bugs and issues
+  /claudia:why       Explain your tech stack decisions
+  /claudia:health    Full project audit
+  /claudia:wtf       Error explainer (What / Why / Fix)
+  /claudia:where     Project structure tour
+  /claudia:resume    Pick up where you left off
+```
+
+## Voice
+
+Be a cheat sheet, not a manual. No explanations needed for experienced users. For beginners, add one-line context for each shortcut.

package/commands/start.md

@@ -0,0 +1,192 @@
+---
+description: Start a new project — Claudia helps you pick a stack, create files, and get running
+argument-hint: [what you want to build, e.g. "a portfolio website"]
+allowed-tools: [Read, Write, Glob, Grep, Bash]
+---
+
+# Claudia: Start a Project
+
+You are Claudia, helping a beginner create a new project from scratch. This is different from `/claudia:setup` (which configures Claudia herself). This creates a real project.
+
+**User's idea (if provided):** $ARGUMENTS
+
+## Important
+
+- Read `${CLAUDE_PLUGIN_ROOT}/skills/claudia-mentor/references/personality.md` for your voice.
+- One step at a time. Wait for the user's response before moving on.
+- Suggest ONE stack, not a menu. Be opinionated.
+- Minimum viable files only. Don't over-scaffold.
+
+## Flow
+
+### Step 1: What?
+
+If `$ARGUMENTS` is provided, use that. Otherwise ask:
+
+"What do you want to build? Pick one, or describe it in your own words:"
+
+- **A website** — personal site, portfolio, landing page
+- **An API** — backend service, REST endpoints
+- **A CLI tool** — command-line script or utility
+- **A game** — browser game, interactive thing
+- **Something else** — describe it and I'll figure out the stack
+
+### Step 2: Stack
+
+Suggest ONE stack based on what they want. Don't present a menu. Be confident.
+
+| Want | Suggest | Why |
+|------|---------|-----|
+| Static site / portfolio | HTML + CSS | Zero setup. `open index.html` and it works. |
+| Dynamic site / app with data | Next.js | Biggest community, deploys anywhere, handles frontend + backend. |
+| Blog / content site | Astro | Built for content. Fast. Markdown-native. |
+| REST API (JS preference) | Express | Minimal, well-documented, huge ecosystem. |
+| REST API (Python preference) | FastAPI | Modern, fast, auto-generates docs. |
+| CLI tool | Python | No build step. Runs everywhere. |
+| Browser game | HTML + Canvas + JS | No dependencies. Open in browser. Immediate feedback. |
+| Complex / multi-part | Break into phases | Start with the simplest piece. Build from there. |
+
+Say: "I'd go with [stack]. [One sentence why]. Sound good?"
+
+If they want something different, adjust. Don't argue.
+
+### Step 3: Where?
+
+Default to `~/{slugified-name}`. Slugify: lowercase, replace spaces with hyphens, drop special chars.
+
+Say: "I'll set it up at `~/{slug}`. Want a different location?"
+
+Accept any valid path.
+
+### Step 4: Create
+
+Create the project directory and minimum viable files. Less is more.
+
+**HTML + CSS site:**
+- `index.html` — basic page with their project name, a heading, and one paragraph
+- `style.css` — linked from index.html, basic reset + one nice font + centered layout
+
+**Next.js:**
+- Run: `npx create-next-app@latest {path} --use-npm --no-eslint --no-tailwind --no-src-dir --no-app --no-import-alias`
+- Or if that fails, create manually: `package.json`, `pages/index.js`, `pages/_app.js`
+
+**Astro:**
+- Run: `npm create astro@latest {path} -- --template minimal --no-install --no-git`
+- Then `cd {path} && npm install`
+
+**Express:**
+- `package.json` with express dependency
+- `index.js` — hello world server on port 3000
+- `npm install`
+
+**FastAPI:**
+- `main.py` — hello world endpoint
+- `requirements.txt` with fastapi and uvicorn
+
+**Python CLI:**
+- `main.py` — simple script with argparse
+- Make executable: `chmod +x main.py`
+
+**Canvas game:**
+- `index.html` — canvas element + linked script
+- `game.js` — basic game loop with a movable square (arrow keys)
+- `style.css` — canvas centered, dark background
+
+**Always create `CLAUDE.md`:**
+```markdown
+# {Project Name}
+
+## What This Is
+{One sentence based on what they told you}
+
+## Tech Stack
+{What was set up}
+
+## How to Run
+{The one command to run it}
+```
+
+**Always init git:**
+```bash
+cd {path} && git init && git add -A && git commit -m "Initial project setup"
+```
+
+### Step 5: Register
+
+Write the project to Claudia's project registry. Use the Bash tool to run this Python snippet:
+
+```bash
+python3 -c "
+import hashlib, json, os
+from datetime import datetime, timezone
+
+path = '{absolute_path}'
+key = hashlib.md5(path.encode()).hexdigest()[:8]
+name = '{project_name}'
+now = datetime.now(timezone.utc).isoformat()
+
+# Write per-project context
+proj_dir = os.path.expanduser('~/.claude/claudia-projects')
+os.makedirs(proj_dir, exist_ok=True)
+proj_data = {
+    'project_key': key,
+    'name': name,
+    'path': path,
+    'intent': '{intent}',
+    'stack': {'frameworks': {frameworks_list}, 'databases': [], 'tools': {tools_list}},
+    'decisions': []
+}
+with open(os.path.join(proj_dir, f'{key}.json'), 'w') as f:
+    json.dump(proj_data, f, indent=2)
+
+# Update registry
+reg_path = os.path.expanduser('~/.claude/claudia-projects.json')
+reg = {'version': 1, 'projects': {}}
+if os.path.exists(reg_path):
+    try:
+        with open(reg_path) as f:
+            reg = json.load(f)
+    except: pass
+reg['projects'][key] = {'name': name, 'path': path, 'last_active': now, 'created': now}
+with open(reg_path, 'w') as f:
+    json.dump(reg, f, indent=2)
+print(f'Registered project {name} ({key})')
+"
+```
+
+Substitute the actual values for `{absolute_path}`, `{project_name}`, `{intent}`, `{frameworks_list}`, and `{tools_list}`.
+
+### Step 6: Run It
+
+Give them ONE command to see it working:
+
+| Stack | Command |
+|-------|---------|
+| HTML + CSS | `open {path}/index.html` |
+| Next.js | `cd {path} && npm run dev` |
+| Astro | `cd {path} && npm run dev` |
+| Express | `cd {path} && node index.js` then visit `http://localhost:3000` |
+| FastAPI | `cd {path} && uvicorn main:app --reload` then visit `http://localhost:8000` |
+| Python CLI | `python3 {path}/main.py --help` |
+| Canvas game | `open {path}/index.html` |
+
+Run the command for them (except for dev servers -- just tell them the command).
+
+### Step 7: One Next Step
+
+Give ONE concrete thing to try. Not a list. One thing.
+
+Examples:
+- "Try changing the heading text in `index.html` and refreshing your browser."
+- "Try adding a new endpoint: tell Claude 'Add a GET /users endpoint that returns a list of names'."
+- "Try pressing the arrow keys to move the square, then tell Claude 'Make it change color when it hits the edge'."
+
+End with: "You're set up. Build something."
+
+## What NOT to Do
+
+- Don't present stack choices as a menu. Pick one and explain why.
+- Don't create more files than necessary. Two files is better than six.
+- Don't skip the git init. Version control from day one.
+- Don't forget to register the project. Future `/claudia:resume` depends on it.
+- Don't give a list of 10 next steps. One is enough.

package/config/defaults.json

@@ -88,5 +88,15 @@
       "gate": "moderate+ for beginners, high for everyone else",
       "behavior": "Ask ONE clarifying question, suggest ONE small next step"
     }
+  },
+  "project_scoping": {
+    "registry": "~/.claude/claudia-projects.json",
+    "per_project_dir": "~/.claude/claudia-projects/",
+    "project_key": "md5(git_root_path)[:8]",
+    "per_project_file": "{key}.json contains project_key, name, path, intent, stack, decisions",
+    "registry_file": "version + projects map (key -> name, path, last_active, created)",
+    "backward_compat": "Falls back to ~/.claude/claudia-context.json if no project-scoped file exists",
+    "created_by": ["/claudia:start", "/claudia:setup"],
+    "read_by": ["all proactive hooks via claudia_config.py", "/claudia:resume", "/claudia:why"]
   }
 }

package/hooks/scripts/claudia-compact-tip.py

@@ -36,30 +36,12 @@ def save_state(session_id, state):
         pass
 
 
-def load_config():
-    """Load proactivity from ~/.claude/claudia.json, experience from claudia-context.json."""
-    proactivity = "moderate"
-    experience = "intermediate"
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
 
-    config_path = os.path.expanduser("~/.claude/claudia.json")
-    if os.path.exists(config_path):
-        try:
-            with open(config_path) as f:
-                data = json.load(f)
-                proactivity = data.get("proactivity", proactivity)
-        except (json.JSONDecodeError, IOError):
-            pass
 
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
-
-    return proactivity, experience
+def load_config():
+    return load_user_config()
 
 
 def main():

package/hooks/scripts/claudia-milestones.py

@@ -93,16 +93,12 @@ def save_state(state):
         pass
 
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
+
+
 def load_config():
-    experience = "intermediate"
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
+    _, experience = load_user_config()
     return experience
 
 

package/hooks/scripts/claudia-next-steps.py

@@ -122,16 +122,12 @@ def save_state(session_id, state):
         pass
 
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
+
+
 def load_config():
-    experience = "intermediate"
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
+    _, experience = load_user_config()
     return experience
 
 

package/hooks/scripts/claudia-prompt-coach.py

@@ -56,30 +56,12 @@ def save_state(session_id, state):
         pass
 
 
-def load_config():
-    """Load proactivity from ~/.claude/claudia.json, experience from claudia-context.json."""
-    proactivity = "moderate"
-    experience = "intermediate"
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
 
-    config_path = os.path.expanduser("~/.claude/claudia.json")
-    if os.path.exists(config_path):
-        try:
-            with open(config_path) as f:
-                data = json.load(f)
-                proactivity = data.get("proactivity", proactivity)
-        except (json.JSONDecodeError, IOError):
-            pass
 
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
-
-    return proactivity, experience
+def load_config():
+    return load_user_config()
 
 
 def main():

package/hooks/scripts/claudia-run-suggest.py

@@ -75,29 +75,12 @@ def save_state(session_id, state):
         pass
 
 
-def load_config():
-    proactivity = "moderate"
-    experience = "intermediate"
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
 
-    config_path = os.path.expanduser("~/.claude/claudia.json")
-    if os.path.exists(config_path):
-        try:
-            with open(config_path) as f:
-                data = json.load(f)
-                proactivity = data.get("proactivity", proactivity)
-        except (json.JSONDecodeError, IOError):
-            pass
 
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
-
-    return proactivity, experience
+def load_config():
+    return load_user_config()
 
 
 def main():

package/hooks/scripts/claudia-session-tips.py

@@ -24,6 +24,8 @@ STARTUP_TIPS = [
     "If you're not sure what to ask, try describing what you want to build. Claude works best with goals, not instructions.",
     "Claude can read your project files. You don't need to paste code — just reference the file name.",
     "When you get an error you don't understand, paste it here. That's literally what I'm for.",
+    "Ctrl+A then Ctrl+K clears your whole input line. Faster than holding backspace.",
+    "Up arrow recalls your last prompt. Edit and resend instead of retyping the whole thing.",
 ]
 
 COMPACT_TIP = (
@@ -33,26 +35,21 @@ COMPACT_TIP = (
 
 
 def gather_project_context():
-    """Read claudia-context.json, milestones, and git state to rebuild context after compaction."""
+    """Read project context, milestones, and git state to rebuild context after compaction."""
     parts = []
 
-    # Stack and decisions from context file
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                ctx = json.load(f)
-            stack = ctx.get("stack", {})
-            decisions = ctx.get("decisions", [])
-            experience = ctx.get("experience", "intermediate")
-            if stack:
-                parts.append(f"Project stack: {json.dumps(stack)}")
-            if decisions:
-                parts.append("Decisions made this session: " + "; ".join(str(d) for d in decisions[-5:]))
-            if experience == "beginner":
-                parts.append("User experience level: beginner. Use simple language, explain jargon.")
-        except (json.JSONDecodeError, IOError):
-            pass
+    # Stack and decisions from project-scoped context (falls back to global)
+    ctx = load_project_context()
+    if ctx:
+        stack = ctx.get("stack", {})
+        decisions = ctx.get("decisions", [])
+        experience = ctx.get("experience", "intermediate")
+        if stack:
+            parts.append(f"Project stack: {json.dumps(stack)}")
+        if decisions:
+            parts.append("Decisions made this session: " + "; ".join(str(d) for d in decisions[-5:]))
+        if experience == "beginner":
+            parts.append("User experience level: beginner. Use simple language, explain jargon.")
 
     # Milestones achieved
     milestones_path = os.path.expanduser("~/.claude/claudia-milestones.json")
@@ -156,30 +153,12 @@ def save_state(session_id, state):
         pass
 
 
-def load_config():
-    """Load proactivity from ~/.claude/claudia.json, experience from claudia-context.json."""
-    proactivity = "moderate"
-    experience = "intermediate"
-
-    config_path = os.path.expanduser("~/.claude/claudia.json")
-    if os.path.exists(config_path):
-        try:
-            with open(config_path) as f:
-                data = json.load(f)
-                proactivity = data.get("proactivity", proactivity)
-        except (json.JSONDecodeError, IOError):
-            pass
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config, load_project_context
 
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
 
-    return proactivity, experience
+def load_config():
+    return load_user_config()
 
 
 def main():

package/hooks/scripts/claudia-teach.py

@@ -150,6 +150,16 @@ COMMAND_REVEALS = {
         "command": "/claudia:health",
         "tip": "Project growing? Try `/claudia:health` for a full checkup",
     },
+    "shortcuts_mentioned": {
+        "patterns": [
+            r'\bshortcut',
+            r'\bhotkey',
+            r'\bkeybind',
+            r'\bkeyboard\b',
+        ],
+        "command": "/claudia:shortcuts",
+        "tip": "Want the full list of keyboard shortcuts? Try `/claudia:shortcuts`",
+    },
 }
 
 
@@ -190,30 +200,12 @@ def save_state(session_id, state):
         pass
 
 
-def load_config():
-    """Load proactivity from ~/.claude/claudia.json, experience from claudia-context.json."""
-    proactivity = "moderate"
-    experience = "intermediate"
-
-    config_path = os.path.expanduser("~/.claude/claudia.json")
-    if os.path.exists(config_path):
-        try:
-            with open(config_path) as f:
-                data = json.load(f)
-                proactivity = data.get("proactivity", proactivity)
-        except (json.JSONDecodeError, IOError):
-            pass
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
 
-    context_path = os.path.expanduser("~/.claude/claudia-context.json")
-    if os.path.exists(context_path):
-        try:
-            with open(context_path) as f:
-                data = json.load(f)
-                experience = data.get("experience", experience)
-        except (json.JSONDecodeError, IOError):
-            pass
 
-    return proactivity, experience
+def load_config():
+    return load_user_config()
 
 
 def main():

package/hooks/scripts/claudia_config.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+Claudia: claudia_config.py
+Shared configuration module for all Claudia hooks.
+Handles project resolution, user config, and project-scoped context.
+"""
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+
+# --- Project Resolution ---
+
+def resolve_project():
+    """Walk up from cwd looking for .git to find the project root.
+
+    Returns:
+        (key, path) where key is md5[:8] of the resolved path,
+        or (None, None) if cwd is ~ or no .git found.
+    """
+    home = os.path.expanduser("~")
+    cwd = os.getcwd()
+
+    # At home directory: no project
+    if os.path.realpath(cwd) == os.path.realpath(home):
+        return (None, None)
+
+    # Walk up looking for .git
+    current = cwd
+    while True:
+        if os.path.isdir(os.path.join(current, ".git")):
+            key = hashlib.md5(current.encode()).hexdigest()[:8]
+            return (key, current)
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        # Don't go above home
+        if os.path.realpath(parent) == os.path.realpath(home):
+            break
+        current = parent
+
+    # No .git found: use cwd as root (but not home)
+    key = hashlib.md5(cwd.encode()).hexdigest()[:8]
+    return (key, cwd)
+
+
+# --- User Config ---
+
+def load_user_config():
+    """Load proactivity from ~/.claude/claudia.json, experience from context.
+
+    Returns:
+        (proactivity, experience) tuple with string values.
+        Defaults: ("moderate", "intermediate")
+    """
+    proactivity = "moderate"
+    experience = "intermediate"
+
+    config_path = os.path.expanduser("~/.claude/claudia.json")
+    if os.path.exists(config_path):
+        try:
+            with open(config_path) as f:
+                data = json.load(f)
+                proactivity = data.get("proactivity", proactivity)
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    # Experience comes from project context (tries project-scoped first, then global)
+    ctx = load_project_context()
+    experience = ctx.get("experience", experience)
+
+    return proactivity, experience
+
+
+# --- Project Context ---
+
+def _projects_dir():
+    return os.path.expanduser("~/.claude/claudia-projects")
+
+
+def _project_file(key):
+    return os.path.join(_projects_dir(), f"{key}.json")
+
+
+def _registry_path():
+    return os.path.expanduser("~/.claude/claudia-projects.json")
+
+
+def _global_context_path():
+    return os.path.expanduser("~/.claude/claudia-context.json")
+
+
+def load_project_context(key=None):
+    """Load project-scoped context, falling back to global claudia-context.json.
+
+    Args:
+        key: Project key. If None, auto-resolves from cwd.
+
+    Returns:
+        dict with project context (stack, decisions, experience, etc.)
+    """
+    if key is None:
+        key, _ = resolve_project()
+
+    # Try project-specific file first
+    if key:
+        pfile = _project_file(key)
+        if os.path.exists(pfile):
+            try:
+                with open(pfile) as f:
+                    return json.load(f)
+            except (json.JSONDecodeError, IOError):
+                pass
+
+    # Fall back to global context
+    global_path = _global_context_path()
+    if os.path.exists(global_path):
+        try:
+            with open(global_path) as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    return {}
+
+
+def save_project_context(data, key=None, path=None):
+    """Save project-scoped context and update the registry.
+
+    Args:
+        data: dict of context to save (merged with existing)
+        key: Project key. If None, auto-resolves from cwd.
+        path: Project path. If None, auto-resolves from cwd.
+    """
+    if key is None or path is None:
+        resolved_key, resolved_path = resolve_project()
+        key = key or resolved_key
+        path = path or resolved_path
+
+    if not key:
+        # No project resolved (at home dir) -- write to global
+        global_path = _global_context_path()
+        existing = {}
+        if os.path.exists(global_path):
+            try:
+                with open(global_path) as f:
+                    existing = json.load(f)
+            except (json.JSONDecodeError, IOError):
+                pass
+        existing.update(data)
+        try:
+            os.makedirs(os.path.dirname(global_path), exist_ok=True)
+            with open(global_path, "w") as f:
+                json.dump(existing, f, indent=2)
+        except IOError:
+            pass
+        return
+
+    # Write project-specific file
+    pfile = _project_file(key)
+    existing = {}
+    if os.path.exists(pfile):
+        try:
+            with open(pfile) as f:
+                existing = json.load(f)
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    existing.update(data)
+    existing["project_key"] = key
+    if path:
+        existing["path"] = path
+    if "name" not in existing and path:
+        existing["name"] = os.path.basename(path)
+
+    try:
+        os.makedirs(os.path.dirname(pfile), exist_ok=True)
+        with open(pfile, "w") as f:
+            json.dump(existing, f, indent=2)
+    except IOError:
+        pass
+
+    # Update registry
+    _update_registry(key, existing.get("name", os.path.basename(path or "")), path)
+
+
+def _update_registry(key, name, path):
+    """Update the project registry with this project's info."""
+    registry = load_registry()
+    now = datetime.now(timezone.utc).isoformat()
+
+    if key in registry["projects"]:
+        registry["projects"][key]["last_active"] = now
+        if name:
+            registry["projects"][key]["name"] = name
+        if path:
+            registry["projects"][key]["path"] = path
+    else:
+        registry["projects"][key] = {
+            "name": name or "",
+            "path": path or "",
+            "last_active": now,
+            "created": now,
+        }
+
+    try:
+        rpath = _registry_path()
+        os.makedirs(os.path.dirname(rpath), exist_ok=True)
+        with open(rpath, "w") as f:
+            json.dump(registry, f, indent=2)
+    except IOError:
+        pass
+
+
+def load_registry():
+    """Load the project registry.
+
+    Returns:
+        dict with "version" and "projects" keys.
+    """
+    rpath = _registry_path()
+    if os.path.exists(rpath):
+        try:
+            with open(rpath) as f:
+                data = json.load(f)
+                if isinstance(data, dict) and "projects" in data:
+                    return data
+        except (json.JSONDecodeError, IOError):
+            pass
+    return {"version": 1, "projects": {}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudia-mentor",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Proactive technology mentor, security advisor, and prompt coach for Claude Code",
   "author": "Regan O'Malley <regan@reganomalley.com>",
   "license": "MIT",

package/skills/claudia-mentor/SKILL.md

@@ -40,9 +40,23 @@ If the user seems new to Claude Code (first interaction, asking basic questions,
 
 ## Context Persistence
 
-On first interaction, check `~/.claude/claudia-context.json` for cached project stack/decisions. If missing or stale, detect the stack (see `references/stack-detection.md`) and save it. When the user accepts a recommendation, append to the project's `decisions` array. The `/claudia:why` command reads this file.
+Claudia uses **project-scoped context** so switching projects doesn't overwrite your stack or decisions.
 
-Also check for beginner onboarding fields: `experience`, `intent`, `onboarded`. If `experience` is `"beginner"`, activate beginner mode — see `references/personality.md` for the full Beginner Mode voice guide. This is set by `/claudia:setup`.
+**How it works:**
+- Each project gets a unique key (md5[:8] of its git root path)
+- Per-project context lives at `~/.claude/claudia-projects/{key}.json` (stack, decisions, intent)
+- A registry at `~/.claude/claudia-projects.json` tracks all known projects (name, path, timestamps)
+- User-level config stays at `~/.claude/claudia.json` (proactivity) and `~/.claude/claudia-context.json` (experience, onboarded)
+
+**On first interaction:**
+1. Check for a per-project context file matching the current directory
+2. If none exists, fall back to `~/.claude/claudia-context.json` (backward compatible)
+3. If context is missing or stale, detect the stack (see `references/stack-detection.md`) and save it to the per-project file
+4. When the user accepts a recommendation, append to the project's `decisions` array
+
+**Beginner mode:** Check `experience` field (from project context or global context). If `"beginner"`, activate beginner mode -- see `references/personality.md`. Set by `/claudia:setup`.
+
+**Project registration:** `/claudia:start` creates projects and registers them. `/claudia:resume` from `~` shows a multi-project dashboard. `/claudia:setup` registers the current directory if inside a git project.
 
 ## Personality