Tutorials

Step-by-step guides for common ContextVault workflows.

Tutorial 1: Setting Up Your First Project

Learn how to initialize ContextVault in a new project and create your first documents.

Step 1: Install ContextVault

If you haven't already, install ContextVault:

# macOS/Linux
curl -sL https://ctx-vault.com/install | bash

# Windows PowerShell
irm https://ctx-vault.com/install.ps1 | iex

Step 2: Navigate to Your Project

cd /path/to/your/project

Step 3: Initialize the Vault

In Claude Code, type:

/ctx-init

This creates:

• .claude/vault/index.md — Your project's documentation index
• The directory structure for project-specific docs

Step 4: Bootstrap Documentation (Optional)

For existing codebases, auto-generate documentation:

/ctx-bootstrap

This scans your codebase and creates:

• P001_architecture.md — Tech stack and structure
• P00X_feature_*.md — One doc per major feature

Step 5: Check Your Status

/ctx-status

You should see your newly created documents listed.

Tutorial 2: Documenting Bug Fixes

Learn the best practice for documenting bugs and their solutions.

When to Document

• After fixing a non-trivial bug
• When the bug had a surprising root cause
• When the solution might help others (or future you)

Step 1: Fix the Bug

Work through your debugging process as normal.

Step 2: Document with /ctx-error

Once fixed, immediately document:

/ctx-error

Step 3: Provide Details

Claude will ask for:

• Error Message — The exact error or symptom
• Root Cause — What was actually wrong
• Solution — How you fixed it
• Prevention — How to avoid it in the future

Example Document Created

# P005 - TypeError in User Authentication

> **Status:** Active
> **Created:** 2026-01-20

## Error
TypeError: Cannot read property 'id' of undefined
at AuthService.validateToken (auth.ts:45)

## Root Cause
The JWT payload structure changed after upgrading jsonwebtoken.
Old: { userId: '123' }
New: { sub: '123' }

## Solution
Updated AuthService to use `payload.sub` instead of `payload.userId`.

## Prevention
- Pin jsonwebtoken version in package.json
- Add unit test for token payload structure

Tutorial 3: Creating Effective Session Handoffs

Learn how to end sessions so the next one can seamlessly continue.

When to Create Handoffs

• At the end of a work session
• Before switching to a different task/project
• When you want to preserve work-in-progress context

Step 1: Before Ending Your Session

/ctx-handoff

Step 2: Claude Generates the Summary

The handoff document includes:

• Completed — What was finished this session
• In Progress — What's partially done
• Blocked — Any blockers or issues
• Next Steps — What to do next session
• Context — Important things to remember

Example Handoff Document

# P008 - Session Handoff 2026-01-20

## Completed
- Implemented user registration API endpoint
- Added input validation with Zod
- Created database migration for users table

## In Progress
- Email verification flow (50% done)
  - Created email template
  - Still need: verification endpoint, token storage

## Blocked
- Waiting for SMTP credentials from DevOps

## Next Steps
1. Finish email verification endpoint
2. Add password reset flow
3. Write integration tests

## Context
- Using Resend for email (not SendGrid)
- Token expiry set to 24 hours per product decision

Step 3: Next Session Automatically Loads Context

When you start a new session, Claude reads the index and knows exactly where you left off.

Tutorial 4: Building a Global Pattern Library

Learn how to capture reusable patterns that help across all projects.

What Makes a Good Global Pattern?

• Useful in multiple projects
• Not specific to one codebase
• Solves a common problem

Examples of Global Patterns

Step 1: Identify a Reusable Pattern

When you solve a problem that could help in other projects.

Step 2: Document with /ctx-snippet

/ctx-snippet

Snippets default to global vault for reuse.

Step 3: Provide Pattern Details

• Name — Clear, searchable name
• Use Case — When to use this pattern
• Code — The actual snippet/pattern
• Notes — Gotchas, alternatives

Example Global Pattern

# G003 - Express Error Handler Pattern

## Use Case
Centralized error handling for Express APIs.

## Pattern
```javascript
const errorHandler = (err, req, res, next) => {
  const status = err.status || 500;
  const message = err.message || 'Internal Server Error';

  // Log for debugging
  console.error(`[${status}] ${message}`, err.stack);

  // Send response
  res.status(status).json({
    error: { message, code: err.code }
  });
};

// Use after all routes
app.use(errorHandler);
```

## Notes
- Always define after routes
- Extend for specific error types (ValidationError, etc.)
- Consider adding request ID for tracing

Tutorial 5: Team Workflow with Git

Share project documentation across your team by committing the vault.

Step 1: Add Vault to Git

# The .claude/vault directory is already git-friendly
git add .claude/vault/
git commit -m "Add project documentation vault"

Step 2: Team Members Pull the Vault

When team members clone or pull, they get all project docs:

git pull origin main
# Now everyone has .claude/vault/

Step 3: Individual Contributions

Each team member's Claude sessions can read and update the shared vault:

• Alice fixes a bug, documents with /ctx-error
• Bob implements a feature, documents with /ctx-doc
• Both commit their doc changes with their code

What to Keep Private

The global vault (~/.claude/vault/) is personal and never shared. It contains your individual patterns and preferences.