diff --git a/examples/claude-code-skill/README.md b/examples/claude-code-skill/README.md
index f1a5b617..3c76180e 100644
--- a/examples/claude-code-skill/README.md
+++ b/examples/claude-code-skill/README.md
@@ -12,7 +12,8 @@ This is a [Claude Code](https://claude.com/claude-code) skill - a markdown-based
 - Core workflow patterns (discovery, execution, planning phases)
 - Decision criteria for when to use bd vs TodoWrite/markdown
 - Session start protocols and ready work checks
-- Issue lifecycle management
+- Compaction survival patterns (critical for Claude Code context limits)
+- Issue lifecycle management with self-check checklists
 - Integration patterns with other tools
 
 **Reference documentation:**
@@ -20,6 +21,9 @@ This is a [Claude Code](https://claude.com/claude-code) skill - a markdown-based
 - `references/CLI_REFERENCE.md` - Complete command reference with all flags
 - `references/DEPENDENCIES.md` - Deep dive into dependency types and relationship patterns
 - `references/WORKFLOWS.md` - Step-by-step workflows with checklists
+- `references/ISSUE_CREATION.md` - When to ask vs create issues, quality guidelines
+- `references/RESUMABILITY.md` - Making issues resumable across sessions with working code examples
+- `references/STATIC_DATA.md` - Using bd for reference databases and glossaries
 
 ## Why is This Useful?
 
@@ -56,17 +60,17 @@ git clone https://github.com/steveyegge/beads.git
 cd beads/examples/claude-code-skill
 
 # Create a symlink in your Claude Code skills directory
-ln -s "$(pwd)" ~/.claude/skills/bd
+ln -s "$(pwd)" ~/.claude/skills/bd-issue-tracking
 ```
 
 #### Option 2: Copy Files Directly
 
 ```bash
 # Create the skill directory
-mkdir -p ~/.claude/skills/bd
+mkdir -p ~/.claude/skills/bd-issue-tracking
 
 # Copy the skill files
-cp -r beads/examples/claude-code-skill/* ~/.claude/skills/bd/
+cp -r beads/examples/claude-code-skill/* ~/.claude/skills/bd-issue-tracking/
 ```
 
 ### Verify Installation
diff --git a/examples/claude-code-skill/SKILL.md b/examples/claude-code-skill/SKILL.md
index 02b18ebc..3badd754 100644
--- a/examples/claude-code-skill/SKILL.md
+++ b/examples/claude-code-skill/SKILL.md
@@ -26,15 +26,83 @@ bd is a graph-based issue tracker for persistent memory across sessions. Use for
 
 **Key insight**: If resuming work after 2 weeks would be difficult without bd, use bd. If the work can be picked up from a markdown skim, TodoWrite is sufficient.
 
+### Test Yourself: bd or TodoWrite?
+
+Ask these questions to decide:
+
+**Choose bd if:**
+- ❓ "Will I need this context in 2 weeks?" → Yes = bd
+- ❓ "Could conversation history get compacted?" → Yes = bd
+- ❓ "Does this have blockers/dependencies?" → Yes = bd
+- ❓ "Is this fuzzy/exploratory work?" → Yes = bd
+
+**Choose TodoWrite if:**
+- ❓ "Will this be done in this session?" → Yes = TodoWrite
+- ❓ "Is this just a task list for me right now?" → Yes = TodoWrite
+- ❓ "Is this linear with no branching?" → Yes = TodoWrite
+
+**When in doubt**: Use bd. Better to have persistent memory you don't need than to lose context you needed.
+
 **For detailed decision criteria and examples, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md)
 
 ## Surviving Compaction Events
 
-**Critical**: After compaction, bd state is your only persistent memory. Write notes as if explaining to a future agent with zero conversation context.
+**Critical**: Compaction events delete conversation history but preserve beads. After compaction, bd state is your only persistent memory.
 
-**Key insight**: TodoWrite disappears after compaction, but bead notes survive. Use notes to capture: COMPLETED work, IN PROGRESS status, BLOCKERS, and KEY DECISIONS.
+**What survives compaction:**
+- All bead data (issues, notes, dependencies, status)
+- Complete work history and context
 
-**For complete compaction recovery workflow and note-taking patterns, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#compaction-survival)
+**What doesn't survive:**
+- Conversation history
+- TodoWrite lists
+- Recent discussion context
+
+**Writing notes for post-compaction recovery:**
+
+Write notes as if explaining to a future agent with zero conversation context:
+
+**Pattern:**
+```markdown
+notes field format:
+- COMPLETED: Specific deliverables ("implemented JWT refresh endpoint + rate limiting")
+- IN PROGRESS: Current state + next immediate step ("testing password reset flow, need user input on email template")
+- BLOCKERS: What's preventing progress
+- KEY DECISIONS: Important context or user guidance
+```
+
+**After compaction:** `bd show <issue-id>` reconstructs full context from notes field.
+
+### Notes Quality Self-Check
+
+Before checkpointing (especially pre-compaction), verify your notes pass these tests:
+
+❓ **Future-me test**: "Could I resume this work in 2 weeks with zero conversation history?"
+- [ ] What was completed? (Specific deliverables, not "made progress")
+- [ ] What's in progress? (Current state + immediate next step)
+- [ ] What's blocked? (Specific blockers with context)
+- [ ] What decisions were made? (Why, not just what)
+
+❓ **Stranger test**: "Could another developer understand this without asking me?"
+- [ ] Technical choices explained (not just stated)
+- [ ] Trade-offs documented (why this approach vs alternatives)
+- [ ] User input captured (decisions that came from discussion)
+
+**Good note example:**
+```
+COMPLETED: JWT auth with RS256 (1hr access, 7d refresh tokens)
+KEY DECISION: RS256 over HS256 per security review - enables key rotation
+IN PROGRESS: Password reset flow - email service working, need rate limiting
+BLOCKERS: Waiting on user decision: reset token expiry (15min vs 1hr trade-off)
+NEXT: Implement rate limiting (5 attempts/15min) once expiry decided
+```
+
+**Bad note example:**
+```
+Working on auth. Made some progress. More to do.
+```
+
+**For complete compaction recovery workflow, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#compaction-survival)
 
 ## Session Start Protocol
 
@@ -42,24 +110,31 @@ bd is a graph-based issue tracker for persistent memory across sessions. Use for
 - Project has a `.beads/` directory (project-local database), OR
 - `~/.beads/` exists (global fallback database for any directory)
 
-**At session start, always check for bd availability and run ready check:**
+**At session start, always check for bd availability and run ready check.**
 
-1. **Always check ready work automatically** at session start
-2. **Report status** to establish shared context
+### Session Start Checklist
 
-### Quick Start Pattern
+Copy this checklist when starting any session where bd is available:
 
-```bash
-# At session start, run:
-bd ready --json
-
-# Report to user:
-"I can see X items ready to work on: [brief summary]"
-
-# If using global ~/.beads, note this in report
+```
+Session Start:
+- [ ] Run bd ready --json to see available work
+- [ ] Run bd list --status in_progress --json for active work
+- [ ] If in_progress exists: bd show <issue-id> to read notes
+- [ ] Report context to user: "X items ready: [summary]"
+- [ ] If using global ~/.beads, mention this in report
+- [ ] If nothing ready: bd blocked --json to check blockers
 ```
 
-This gives immediate shared context about available work without requiring user prompting.
+**Pattern**: Always check both `bd ready` AND `bd list --status in_progress`. Read notes field first to understand where previous session left off.
+
+**Report format**:
+- "I can see X items ready to work on: [summary]"
+- "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?"
+
+This establishes immediate shared context about available and active work without requiring user prompting.
+
+**For detailed collaborative handoff process, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-handoff)
 
 **Note**: bd auto-discovers the database:
 - Uses `.beads/*.db` in current project if exists
@@ -76,6 +151,44 @@ bd blocked --json
 
 Report blockers and suggest next steps.
 
+---
+
+## Progress Checkpointing
+
+Update bd notes at these checkpoints (don't wait for session end):
+
+**Critical triggers:**
+- ⚠️ **Context running low** - User says "running out of context" / "approaching compaction" / "close to token limit"
+- 📊 **Token budget > 70%** - Proactively checkpoint when approaching limits
+- 🎯 **Major milestone reached** - Completed significant piece of work
+- 🚧 **Hit a blocker** - Can't proceed, need to capture what was tried
+- 🔄 **Task transition** - Switching issues or about to close this one
+- ❓ **Before user input** - About to ask decision that might change direction
+
+**Proactive monitoring during session:**
+- At 70% token usage: "We're at 70% token usage - good time to checkpoint bd notes?"
+- At 85% token usage: "Approaching token limit (85%) - checkpointing current state to bd"
+- At 90% token usage: Automatically checkpoint without asking
+
+**Current token usage**: Check `<system-warning>Token usage:` messages to monitor proactively.
+
+**Checkpoint checklist:**
+
+```
+Progress Checkpoint:
+- [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format
+- [ ] Document KEY DECISIONS or BLOCKERS since last update
+- [ ] Mark current status (in_progress/blocked/closed)
+- [ ] If discovered new work: create issues with discovered-from
+- [ ] Verify notes are self-explanatory for post-compaction resume
+```
+
+**Most important**: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.
+
+**Test yourself**: "If compaction happened right now, could future-me resume from these notes?"
+
+---
+
 ### Database Selection
 
 bd automatically selects the appropriate database:
@@ -84,7 +197,15 @@ bd automatically selects the appropriate database:
 
 **Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.
 
-**Database discovery**: bd looks for `.beads/*.db` in current directory, falls back to `~/.beads/default.db`. Use `--db` flag for explicit database selection.
+**When to use --db flag explicitly:**
+- Accessing a specific database outside current directory
+- Working with multiple databases (e.g., project database + reference database)
+- Example: `bd --db /path/to/reference/terms.db list`
+
+**Database discovery rules:**
+- bd looks for `.beads/*.db` in current working directory
+- If not found, uses `~/.beads/default.db`
+- Shell cwd can reset between commands - use absolute paths with --db when operating on non-local databases
 
 **For complete session start workflows, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-start)
 
@@ -142,6 +263,23 @@ bd list --assignee alice
 
 **For complete CLI reference with all flags and examples, read:** [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md)
 
+## Field Usage Reference
+
+Quick guide for when and how to use each bd field:
+
+| Field | Purpose | When to Set | Update Frequency |
+|-------|---------|-------------|------------------|
+| **description** | Immutable problem statement | At creation | Never (fixed forever) |
+| **design** | Initial approach, architecture, decisions | During planning | Rarely (only if approach changes) |
+| **acceptance-criteria** | Concrete deliverables checklist (`- [ ]` syntax) | When design is clear | Mark `- [x]` as items complete |
+| **notes** | Session handoff (COMPLETED/IN_PROGRESS/NEXT) | During work | At session end, major milestones |
+| **status** | Workflow state (open→in_progress→closed) | As work progresses | When changing phases |
+| **priority** | Urgency level (0=highest, 3=lowest) | At creation | Adjust if priorities shift |
+
+**Key pattern**: Notes field is your "read me first" at session start. See [WORKFLOWS.md](references/WORKFLOWS.md#session-handoff) for session handoff details.
+
+---
+
 ## Issue Lifecycle Workflow
 
 ### 1. Discovery Phase (Proactive Issue Creation)
@@ -229,23 +367,86 @@ bd supports four dependency types:
 ## Integration with TodoWrite
 
 **Both tools complement each other at different timescales:**
-- **TodoWrite** - Short-term working memory (this hour), disappears after session
-- **Beads** - Long-term episodic memory (this week/month), survives compaction
 
-**The Handoff Pattern**: Read bead → Create TodoWrite items → Work → Update bead notes with outcomes → TodoWrite disappears, bead survives.
+### Temporal Layering Pattern
 
-**For complete temporal layering pattern, examples, and integration workflows, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns)
+**TodoWrite** (short-term working memory - this hour):
+- Tactical execution: "Review Section 3", "Expand Q&A answers"
+- Marked completed as you go
+- Present/future tense ("Review", "Expand", "Create")
+- Ephemeral: Disappears when session ends
+
+**Beads** (long-term episodic memory - this week/month):
+- Strategic objectives: "Continue work on strategic planning document"
+- Key decisions and outcomes in notes field
+- Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
+- Persistent: Survives compaction and session boundaries
+
+### The Handoff Pattern
+
+1. **Session start**: Read bead → Create TodoWrite items for immediate actions
+2. **During work**: Mark TodoWrite items completed as you go
+3. **Reach milestone**: Update bead notes with outcomes + context
+4. **Session end**: TodoWrite disappears, bead survives with enriched notes
+
+**After compaction**: TodoWrite is gone forever, but bead notes reconstruct what happened.
+
+### Example: TodoWrite tracks execution, Beads capture meaning
+
+**TodoWrite:**
+```
+[completed] Implement login endpoint
+[in_progress] Add password hashing with bcrypt
+[pending] Create session middleware
+```
+
+**Corresponding bead notes:**
+```
+bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password
+hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless
+auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation.
+NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)."
+```
+
+**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
+
+**For patterns on transitioning between tools mid-session, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns)
 
 ## Common Patterns
 
 ### Pattern 1: Knowledge Work Session
 
-User asks for strategic document development:
-1. Check if bd available: `bd ready`
-2. If related epic exists, show current status
-3. Create new issues for discovered research needs
-4. Use discovered-from to track where ideas came from
-5. Update design notes as research progresses
+**Scenario**: User asks "Help me write a proposal for expanding the analytics platform"
+
+**What you see**:
+```bash
+$ bd ready
+# Returns: bd-42 "Research analytics platform expansion proposal" (in_progress)
+
+$ bd show bd-42
+Notes: "COMPLETED: Reviewed current stack (Mixpanel, Amplitude)
+IN PROGRESS: Drafting cost-benefit analysis section
+NEXT: Need user input on budget constraints before finalizing recommendations"
+```
+
+**What you do**:
+1. Read notes to understand current state
+2. Create TodoWrite for immediate work:
+   ```
+   - [ ] Draft cost-benefit analysis
+   - [ ] Ask user about budget constraints
+   - [ ] Finalize recommendations
+   ```
+3. Work on tasks, mark TodoWrite items completed
+4. At milestone, update bd notes:
+   ```bash
+   bd update bd-42 --notes "COMPLETED: Cost-benefit analysis drafted.
+   KEY DECISION: User confirmed $50k budget cap - ruled out enterprise options.
+   IN PROGRESS: Finalizing recommendations (Posthog + custom ETL).
+   NEXT: Get user review of draft before closing issue."
+   ```
+
+**Outcome**: TodoWrite disappears at session end, but bd notes preserve context for next session.
 
 ### Pattern 2: Side Quest Handling
 
@@ -267,55 +468,46 @@ Starting work after time away:
 
 **For complete workflow walkthroughs with checklists, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md)
 
-## Use Pattern Variations
+## Issue Creation
 
-bd is designed for work tracking but can serve other purposes with appropriate adaptations:
+**Quick guidelines:**
+- Ask user first for knowledge work with fuzzy boundaries
+- Create directly for clear bugs, technical debt, or discovered work
+- Use clear titles, sufficient context in descriptions
+- Design field: HOW to build (can change during implementation)
+- Acceptance criteria: WHAT success looks like (should remain stable)
 
-### Work Tracking (Primary Use Case)
-- Issues flow through states (open → in_progress → closed)
-- Priorities and dependencies matter
-- Status tracking is essential
-- IDs are sufficient for referencing
+### Issue Creation Checklist
 
-### Reference Databases / Glossaries (Alternative Use)
-- Entities are mostly static (typically always open)
-- No real workflow or state transitions
-- Names/titles more important than IDs
-- Minimal or no dependencies
-- Consider dual format: maintain markdown version alongside database for name-based lookup
-- Use separate database (not mixed with work tracking) to avoid confusion
+Copy when creating new issues:
 
-**Example**: A terminology database could use both `terms.db` (queryable) and `GLOSSARY.md` (browsable by name).
+```
+Creating Issue:
+- [ ] Title: Clear, specific, action-oriented
+- [ ] Description: Problem statement (WHY this matters) - immutable
+- [ ] Design: HOW to build (can change during work)
+- [ ] Acceptance: WHAT success looks like (stays stable)
+- [ ] Priority: 0=critical, 1=high, 2=normal, 3=low
+- [ ] Type: bug/feature/task/epic/chore
+```
 
-**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
+**Self-check for acceptance criteria:**
 
-## Issue Creation Guidelines
+❓ "If I changed the implementation approach, would these criteria still apply?"
+- → **Yes** = Good criteria (outcome-focused)
+- → **No** = Move to design field (implementation-focused)
 
-### When to Ask First vs Create Directly
+**Example:**
+- ✅ Acceptance: "User tokens persist across sessions and refresh automatically"
+- ❌ Wrong: "Use JWT tokens with 1-hour expiry" (that's design, not acceptance)
 
-**Ask the user before creating when:**
-- Knowledge work with fuzzy boundaries
-- Task scope is unclear
-- Multiple valid approaches exist
-- User's intent needs clarification
+**For detailed guidance on when to ask vs create, issue quality, resumability patterns, and design vs acceptance criteria, read:** [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md)
 
-**Create directly when:**
-- Clear bug discovered during implementation
-- Obvious follow-up work identified
-- Technical debt with clear scope
-- Dependency or blocker found
+## Alternative Use Cases
 
-**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.
+bd is primarily for work tracking, but can also serve as queryable database for static reference data (glossaries, terminology) with adaptations.
 
-### Issue Quality
-
-Use clear, specific titles and include sufficient context in descriptions to resume work later.
-
-**Use --design flag for:**
-- Implementation approach decisions, architecture notes, trade-offs considered
-
-**Use --acceptance flag for:**
-- Definition of done, testing requirements, success metrics
+**For guidance on using bd for reference databases and static data, read:** [references/STATIC_DATA.md](references/STATIC_DATA.md)
 
 ## Statistics and Monitoring
 
@@ -441,3 +633,5 @@ Detailed information organized by topic:
 | [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md) | Need complete command reference, flag details, or examples |
 | [references/WORKFLOWS.md](references/WORKFLOWS.md) | Need step-by-step workflows with checklists for common scenarios |
 | [references/DEPENDENCIES.md](references/DEPENDENCIES.md) | Need deep understanding of dependency types or relationship patterns |
+| [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md) | Need guidance on when to ask vs create issues, issue quality, or design vs acceptance criteria |
+| [references/STATIC_DATA.md](references/STATIC_DATA.md) | Want to use bd for reference databases, glossaries, or static data instead of work tracking |
diff --git a/examples/claude-code-skill/references/BOUNDARIES.md b/examples/claude-code-skill/references/BOUNDARIES.md
index 7bbf78fc..c98f5640 100644
--- a/examples/claude-code-skill/references/BOUNDARIES.md
+++ b/examples/claude-code-skill/references/BOUNDARIES.md
@@ -246,55 +246,6 @@ Rare, but happens when bd issue turns out simpler than expected.
 5. Note: "Completed in single session, simpler than expected"
 ```
 
-### Pattern 4: Temporal Layering (Complementary Use)
-
-**Key insight**: TodoWrite and bd operate at different timescales and serve different memory needs.
-
-**TodoWrite** (short-term working memory - this hour):
-- Tactical execution steps
-- Present/future tense ("Implement", "Test", "Deploy")
-- Marked completed as you go
-- Ephemeral: Disappears when session ends
-
-**Beads** (long-term episodic memory - this week/month):
-- Strategic objectives and context
-- Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
-- Key decisions and outcomes in notes field
-- Persistent: Survives compaction and session boundaries
-
-**The Handoff Pattern:**
-1. **Session start**: Read bead → Create TodoWrite items for immediate actions
-2. **During work**: Mark TodoWrite items completed as you go
-3. **Reach milestone**: Update bead notes with outcomes + context
-4. **Session end**: TodoWrite disappears, bead survives with enriched notes
-
-**After compaction**: TodoWrite is gone forever, but bead notes reconstruct what happened.
-
-**Example - TodoWrite tracks execution, Beads capture meaning:**
-
-TodoWrite for this session:
-```
-[completed] Implement login endpoint
-[in_progress] Add password hashing with bcrypt
-[pending] Create session middleware
-```
-
-Corresponding bead notes:
-```bash
-bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password
-hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless
-auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation.
-NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)."
-```
-
-**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
-
-**When to use this pattern:**
-- Long-running features requiring multiple sessions
-- Work that will likely face compaction
-- Need both immediate visibility (TodoWrite) and long-term memory (bd)
-- Strategic work with tactical execution steps
-
 ## Real-World Examples
 
 ### Example 1: Database Migration Planning
diff --git a/examples/claude-code-skill/references/CLI_REFERENCE.md b/examples/claude-code-skill/references/CLI_REFERENCE.md
index eb258d32..bb463f20 100644
--- a/examples/claude-code-skill/references/CLI_REFERENCE.md
+++ b/examples/claude-code-skill/references/CLI_REFERENCE.md
@@ -190,13 +190,9 @@ Visualize full dependency tree for an issue.
 
 ```bash
 bd dep tree issue-123
-
-# Limit tree depth (default: 50)
-bd dep tree issue-123 --max-depth 10
-bd dep tree issue-123 -d 10
 ```
 
-Shows all dependencies and dependents in tree format. Use `--max-depth` to limit traversal depth for very deep trees.
+Shows all dependencies and dependents in tree format.
 
 ---
 
diff --git a/examples/claude-code-skill/references/ISSUE_CREATION.md b/examples/claude-code-skill/references/ISSUE_CREATION.md
new file mode 100644
index 00000000..1e3ebb19
--- /dev/null
+++ b/examples/claude-code-skill/references/ISSUE_CREATION.md
@@ -0,0 +1,139 @@
+# Issue Creation Guidelines
+
+Guidance on when and how to create bd issues for maximum effectiveness.
+
+## Contents
+
+- [When to Ask First vs Create Directly](#when-to-ask)
+- [Issue Quality](#quality)
+- [Making Issues Resumable](#resumable)
+- [Design vs Acceptance Criteria](#design-vs-acceptance)
+
+## When to Ask First vs Create Directly {#when-to-ask}
+
+### Ask the user before creating when:
+- Knowledge work with fuzzy boundaries
+- Task scope is unclear
+- Multiple valid approaches exist
+- User's intent needs clarification
+
+### Create directly when:
+- Clear bug discovered during implementation
+- Obvious follow-up work identified
+- Technical debt with clear scope
+- Dependency or blocker found
+
+**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.
+
+## Issue Quality {#quality}
+
+Use clear, specific titles and include sufficient context in descriptions to resume work later.
+
+### Field Usage
+
+**Use --design flag for:**
+- Implementation approach decisions
+- Architecture notes
+- Trade-offs considered
+
+**Use --acceptance flag for:**
+- Definition of done
+- Testing requirements
+- Success metrics
+
+## Making Issues Resumable (Complex Technical Work) {#resumable}
+
+For complex technical features spanning multiple sessions, enhance notes field with implementation details.
+
+### Optional but valuable for technical work:
+- Working API query code (tested, with response structure)
+- Sample API responses showing actual data
+- Desired output format examples (show, don't describe)
+- Research context (why this approach, what was discovered)
+
+### Example pattern:
+
+```markdown
+bd update issue-9 --notes "IMPLEMENTATION GUIDE:
+WORKING CODE: service.about().get(fields='importFormats')
+Returns: dict with 49 entries like {'text/markdown': [...]}
+OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
+CONTEXT: text/markdown support added July 2024, not in static docs"
+```
+
+**When to add:** Multi-session technical features with APIs or specific formats. Skip for simple tasks.
+
+**For detailed patterns and examples, read:** [RESUMABILITY.md](RESUMABILITY.md)
+
+## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
+
+Common mistake: Putting implementation details in acceptance criteria. Here's the difference:
+
+### DESIGN field (HOW to build it):
+- "Use two-phase batchUpdate approach: insert text first, then apply formatting"
+- "Parse with regex to find * and _ markers"
+- "Use JWT tokens with 1-hour expiry"
+- Trade-offs: "Chose batchUpdate over streaming API for atomicity"
+
+### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
+- "Bold and italic markdown formatting renders correctly in the Doc"
+- "Solution accepts markdown input and creates Doc with specified title"
+- "Returns doc_id and webViewLink to caller"
+- "User tokens persist across sessions and refresh automatically"
+
+### Why this matters:
+- Design can change during implementation (e.g., use library instead of regex)
+- Acceptance criteria should remain stable across sessions
+- Criteria should be **outcome-focused** ("what must be true?") not **step-focused** ("do these steps")
+- Each criterion should be **verifiable** - you can definitively say yes/no
+
+### The pitfall
+
+Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.
+
+Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.
+
+### Test yourself
+
+If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.
+
+### Example of correct structure
+
+✅ **Design field:**
+```
+Two-phase Docs API approach:
+1. Parse markdown to positions
+2. Create doc + insert text in one call
+3. Apply formatting in second call
+Rationale: Atomic operations, easier to debug formatting separately
+```
+
+✅ **Acceptance criteria:**
+```
+- [ ] Markdown formatting renders in Doc (bold, italic, headings)
+- [ ] Lists preserve order and nesting
+- [ ] Links are clickable
+- [ ] Large documents (>50KB) process without timeout
+```
+
+❌ **Wrong (design masquerading as criteria):**
+```
+- [ ] Use two-phase batchUpdate approach
+- [ ] Apply formatting in second batchUpdate call
+```
+
+## Quick Reference
+
+**Creating good issues:**
+
+1. **Title**: Clear, specific, action-oriented
+2. **Description**: Problem statement, context, why it matters
+3. **Design**: Approach, architecture, trade-offs (can change)
+4. **Acceptance**: Outcomes, success criteria (should be stable)
+5. **Notes**: Implementation details, session handoffs (evolves over time)
+
+**Common mistakes:**
+
+- Vague titles: "Fix bug" → "Fix: auth token expires before refresh"
+- Implementation in acceptance: "Use JWT" → "Auth tokens persist across sessions"
+- Missing context: "Update database" → "Update database: add user_last_login for session analytics"
diff --git a/examples/claude-code-skill/references/RESUMABILITY.md b/examples/claude-code-skill/references/RESUMABILITY.md
new file mode 100644
index 00000000..0cf0b257
--- /dev/null
+++ b/examples/claude-code-skill/references/RESUMABILITY.md
@@ -0,0 +1,207 @@
+# Making Issues Resumable Across Sessions
+
+## When Resumability Matters
+
+**Use enhanced documentation for:**
+- Multi-session technical features with API integration
+- Complex algorithms requiring code examples
+- Features with specific output format requirements
+- Work with "occult" APIs (undocumented capabilities)
+
+**Skip for:**
+- Simple bug fixes with clear scope
+- Well-understood patterns (CRUD operations, etc.)
+- Single-session tasks
+- Work with obvious acceptance criteria
+
+**The test:** Would a fresh Claude instance (or you after 2 weeks) struggle to resume this work from the description alone? If yes, add implementation details.
+
+## Anatomy of a Resumable Issue
+
+### Minimal (Always Include)
+```markdown
+Description: What needs to be built and why
+Acceptance Criteria: Concrete, testable outcomes (WHAT not HOW)
+```
+
+### Enhanced (Complex Technical Work)
+```markdown
+Notes Field - IMPLEMENTATION GUIDE:
+
+WORKING CODE:
+```python
+# Tested code that queries the API
+service = build('drive', 'v3', credentials=creds)
+result = service.about().get(fields='importFormats').execute()
+# Returns: {'text/markdown': ['application/vnd.google-apps.document'], ...}
+```
+
+API RESPONSE SAMPLE:
+Shows actual data structure (not docs description)
+
+DESIRED OUTPUT FORMAT:
+```markdown
+# Example of what the output should look like
+Not just "return markdown" but actual structure
+```
+
+RESEARCH CONTEXT:
+Why this approach? What alternatives were considered?
+Key discoveries that informed the design.
+```
+
+## Real Example: Before vs After
+
+### ❌ Not Resumable
+```
+Title: Add dynamic capabilities resources
+Description: Query Google APIs for capabilities and return as resources
+Acceptance: Resources return capability info
+```
+
+**Problem:** Future Claude doesn't know:
+- Which API endpoints to call
+- What the responses look like
+- What format to return
+
+### ✅ Resumable
+```
+Title: Add dynamic capabilities resources
+Description: Query Google APIs for system capabilities (import formats,
+themes, quotas) that aren't in static docs. Makes server self-documenting.
+
+Notes: IMPLEMENTATION GUIDE
+
+WORKING CODE (tested):
+```python
+from workspace_mcp.tools.drive import get_credentials
+from googleapiclient.discovery import build
+
+creds = get_credentials()
+service = build('drive', 'v3', credentials=creds)
+about = service.about().get(
+    fields='importFormats,exportFormats,folderColorPalette'
+).execute()
+
+# Returns:
+# - importFormats: dict, 49 entries like {'text/markdown': [...]}
+# - exportFormats: dict, 10 entries
+# - folderColorPalette: list, 24 hex strings
+```
+
+OUTPUT FORMAT EXAMPLE:
+```markdown
+# Drive Import Formats
+
+Google Drive supports 49 import formats:
+
+## Text Formats
+- **text/markdown** → Google Docs ✨ (NEW July 2024)
+- text/plain → Google Docs
+...
+```
+
+RESEARCH CONTEXT:
+text/markdown support announced July 2024 but NOT in static Google docs.
+Google's workspace-developer MCP server doesn't expose this.
+This is why dynamic resources matter.
+
+Acceptance Criteria:
+- User queries workspace://capabilities/drive/import-formats
+- Response shows all 49 formats including text/markdown
+- Output is readable markdown, not raw JSON
+- Queries live API (not static data)
+```
+
+**Result:** Fresh Claude instance can:
+1. See working API query code
+2. Understand response structure
+3. Know desired output format
+4. Implement with context
+
+## Optional Template
+
+Copy this into notes field for complex technical features:
+
+```markdown
+IMPLEMENTATION GUIDE FOR FUTURE SESSIONS:
+
+WORKING CODE (tested):
+```language
+# Paste actual code that works
+# Include imports and setup
+# Show what it returns
+```
+
+API RESPONSE SAMPLE:
+```json
+{
+  "actualField": "actualValue",
+  "structure": "as returned by API"
+}
+```
+
+DESIRED OUTPUT FORMAT:
+```
+Show what the final output should look like
+Not just "markdown" but actual structure/style
+```
+
+RESEARCH CONTEXT:
+- Why this approach?
+- What alternatives considered?
+- Key discoveries?
+- Links to relevant docs/examples?
+```
+
+## Anti-Patterns
+
+### ❌ Over-Documenting Simple Work
+```markdown
+Title: Fix typo in README
+Notes: IMPLEMENTATION GUIDE
+WORKING CODE: Open README.md, change "teh" to "the"...
+```
+**Problem:** Wastes tokens on obvious work.
+
+### ❌ Design Details in Acceptance Criteria
+```markdown
+Acceptance:
+- [ ] Use batchUpdate approach
+- [ ] Call API with fields parameter
+- [ ] Format as markdown with ## headers
+```
+**Problem:** Locks implementation. Should be in Design/Notes, not Acceptance.
+
+### ❌ Raw JSON Dumps
+```markdown
+API RESPONSE:
+{giant unformatted JSON blob spanning 100 lines}
+```
+**Problem:** Hard to read. Extract relevant parts, show structure.
+
+### ✅ Right Balance
+```markdown
+API RESPONSE SAMPLE:
+Returns dict with 49 entries. Example entries:
+- 'text/markdown': ['application/vnd.google-apps.document']
+- 'text/plain': ['application/vnd.google-apps.document']
+- 'application/pdf': ['application/vnd.google-apps.document']
+```
+
+## When to Add This Detail
+
+**During issue creation:**
+- Already have working code from research? Include it.
+- Clear output format in mind? Show example.
+
+**During work (update notes):**
+- Just got API query working? Add to notes.
+- Discovered important context? Document it.
+- Made key decision? Explain rationale.
+
+**Session end:**
+- If resuming will be hard, add implementation guide.
+- If obvious, skip it.
+
+**The principle:** Help your future self (or next Claude) resume without rediscovering everything.
diff --git a/examples/claude-code-skill/references/STATIC_DATA.md b/examples/claude-code-skill/references/STATIC_DATA.md
new file mode 100644
index 00000000..ffa1b387
--- /dev/null
+++ b/examples/claude-code-skill/references/STATIC_DATA.md
@@ -0,0 +1,54 @@
+# Using bd for Static Reference Data
+
+bd is primarily designed for work tracking, but can also serve as a queryable database for static reference data with some adaptations.
+
+## Work Tracking (Primary Use Case)
+
+Standard bd workflow:
+- Issues flow through states (open → in_progress → closed)
+- Priorities and dependencies matter
+- Status tracking is essential
+- IDs are sufficient for referencing
+
+## Reference Databases / Glossaries (Alternative Use)
+
+When using bd for static data (terminology, glossaries, reference information):
+
+**Characteristics:**
+- Entities are mostly static (typically always open)
+- No real workflow or state transitions
+- Names/titles more important than IDs
+- Minimal or no dependencies
+
+**Recommended approach:**
+- Use separate database (not mixed with work tracking) to avoid confusion
+- Consider dual format: maintain markdown version alongside database for name-based lookup
+- Example: A terminology database could use both `terms.db` (queryable via bd) and `GLOSSARY.md` (browsable by name)
+
+**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
+
+## When to Use This Pattern
+
+**Good fit:**
+- Technical glossaries or terminology databases
+- Reference documentation that needs dependency tracking
+- Knowledge bases with relationships between entries
+- Structured data that benefits from queryability
+
+**Poor fit:**
+- Data that changes frequently (use work tracking pattern)
+- Simple lists (markdown is simpler)
+- Data that needs complex queries (use proper database)
+
+## Limitations
+
+**bd show requires IDs, not names:**
+- `bd show term-42` works
+- `bd show "API endpoint"` doesn't work
+- Workaround: `bd list | grep -i "api endpoint"` to find ID first
+- This is why dual format (bd + markdown) is recommended for reference data
+
+**No search by content:**
+- bd searches by ID, title filters, status, labels
+- For full-text search across descriptions/notes, use grep on the JSONL file
+- Example: `grep -i "authentication" .beads/issues.jsonl`
diff --git a/examples/claude-code-skill/references/WORKFLOWS.md b/examples/claude-code-skill/references/WORKFLOWS.md
index f21522a6..ad4926db 100644
--- a/examples/claude-code-skill/references/WORKFLOWS.md
+++ b/examples/claude-code-skill/references/WORKFLOWS.md
@@ -11,6 +11,7 @@ Detailed step-by-step workflows for common bd usage patterns with checklists.
 - [Epic Planning](#epic-planning) - Structuring complex work with dependencies
 - [Side Quest Handling](#side-quests) - Discovery during main task, assessing blocker vs deferrable, resuming
 - [Multi-Session Resume](#resume) - Returning after days/weeks away
+- [Session Handoff Workflow](#session-handoff) - Collaborative handoff between sessions
 - [Unblocking Work](#unblocking) - Handling blocked issues
 - [Integration with TodoWrite](#integration-with-todowrite) - Using both tools together
 - [Common Workflow Patterns](#common-workflow-patterns)
@@ -234,6 +235,119 @@ Resume Workflow:
 
 ---
 
+## Session Handoff Workflow {#session-handoff}
+
+**Collaborative handoff between sessions using notes field:**
+
+This workflow enables smooth work resumption by updating beads notes when stopping, then reading them when resuming. Works in conjunction with compaction survival - creates continuity even after conversation history is deleted.
+
+### At Session Start (Claude's responsibility)
+
+```
+Session Start with in_progress issues:
+- [ ] Run bd list --status in_progress
+- [ ] For each in_progress issue: bd show <issue-id>
+- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, NEXT
+- [ ] Report to user with context from notes field
+- [ ] Example: "workspace-mcp-server-2 is in_progress. Last session:
+       completed tidying. No code written yet. Next step: create
+       markdown_to_docs.py. Should I continue with that?"
+- [ ] Wait for user confirmation or direction
+```
+
+**Pattern**: Notes field is the "read me first" guide for resuming work.
+
+### At Session End (Claude prompts user)
+
+When wrapping up work on an issue:
+
+```
+Session End Handoff:
+- [ ] Notice work reaching a stopping point
+- [ ] Prompt user: "We just completed X and started Y on <issue-id>.
+       Should I update the beads notes for next session?"
+- [ ] If yes, suggest command:
+       bd update <issue-id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
+- [ ] User reviews and confirms
+- [ ] Claude executes the update
+- [ ] Notes saved for next session's resumption
+```
+
+**Pattern**: Update notes at logical stopping points, not after every keystroke.
+
+### Notes Format (Current State, Not Cumulative)
+
+```
+Good handoff note (current state):
+COMPLETED: Parsed markdown into structured format
+IN PROGRESS: Implementing Docs API insertion
+NEXT: Debug batchUpdate call - getting 400 error on formatting
+BLOCKER: None
+KEY DECISION: Using two-phase approach (insert text, then apply formatting) based on reference implementation
+
+Bad handoff note (not useful):
+Updated some stuff. Will continue later.
+```
+
+**Rules for handoff notes:**
+- Current state only (overwrite previous notes, not append)
+- Specific accomplishments (not vague progress)
+- Concrete next step (not "continue working")
+- Optional: Blockers, key decisions, references
+- Written for someone with zero conversation context
+
+### Session Handoff Checklist
+
+For Claude at session end:
+
+```
+Session End Checklist:
+- [ ] Work reaching logical stopping point
+- [ ] Prompt user about updating notes
+- [ ] If approved:
+  - [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
+  - [ ] Include blocker if stuck
+  - [ ] Include key decisions if relevant
+  - [ ] Suggest bd update command
+- [ ] Execute approved update
+- [ ] Confirm: "Saved handoff notes for next session"
+```
+
+For user (optional, but helpful):
+
+```
+User Tips:
+- [ ] When stopping work: Let Claude suggest notes update
+- [ ] When resuming: Let Claude read notes and report context
+- [ ] Avoid: Trying to remember context manually (that's what notes are for!)
+- [ ] Trust: Well-written notes will help next session pick up instantly
+```
+
+### Example: Real Session Handoff
+
+**Scenario:** Implementing markdown→Docs feature (workspace-mcp-server-2)
+
+**At End of Session 1:**
+```bash
+bd update workspace-mcp-server-2 --notes "COMPLETED: Set up skeleton with Docs
+API connection verified. Markdown parsing logic 80% done (handles *, _ modifiers).
+IN PROGRESS: Testing edge cases for nested formatting. NEXT: Implement
+batchUpdate call structure for text insertion. REFERENCE: Reference pattern at
+docs/markdown-to-docs-reference.md. No blockers, moving well."
+```
+
+**At Start of Session 2:**
+```bash
+bd show workspace-mcp-server-2
+# Output includes notes field showing exactly where we left off
+# Claude reports: "Markdown→Docs feature is 80% parsed. We were testing
+# edge cases and need to implement batchUpdate next. Want to continue?"
+```
+
+Session resumes instantly with full context, no history scrolling needed.
+
+---
+
 ## Unblocking Work {#unblocking}
 
 **When ready list is empty:**