---
name: xray
description: "Explain what just happened under the hood — the context, MCP tools, and hooks behind Dex's last response — as AI education. Use when the user says 'how did you do that', 'what just happened', 'explain the mechanics'. Not for a system health check; use `dex-doctor`."
---

# /xray - The AI Education Experience

**Default behavior:** Explain what just happened in THIS conversation — the specific tools, files, and context that were used, with educational explanations of WHY.

**With qualifiers:** Deep dive into specific topics (AI fundamentals, Dex architecture, how to extend).

---

## Philosophy

The best way to learn is by examining what just happened, not abstract concepts. When you run `/xray`:

1. **Show the work** - What tools ran, what files were read/written
2. **Explain why** - Why each action was necessary
3. **Connect to concepts** - Link specific actions to how AI/Dex works
4. **Empower extension** - "You could customize this by..."

**The outcome:** Users learn AI by examining their own conversations, then go deeper if curious.

**Tone:** Like a senior engineer doing a code review of what just happened. "Here's what I did and why."

---

## Step 1: Determine Mode

### Default (no arguments): "This Conversation"

When user just says `/xray` with no qualifier:
→ **Immediately explain what happened in this conversation**
→ Don't show a menu, just show the work

### With qualifiers: Specific topics

| Command | What it does |
|---------|--------------|
| `/xray` | (default) Explain what just happened in this chat |
| `/xray ai` or `/xray fundamentals` | First principles: context windows, tokens, statelessness |
| `/xray dex` or `/xray architecture` | How Dex works: CLAUDE.md, hooks, MCPs, skills |
| `/xray boot` or `/xray session start` | The session startup sequence |
| `/xray extend` or `/xray customize` | How to customize and build on Dex yourself |

---

## DEFAULT MODE: This Conversation (Show Your Work)

**This is the primary mode.** When user runs `/xray`, explain what happened.

### Step 1: Analyze the conversation

Look at the current conversation and identify:
1. What files were read
2. What files were written/modified
3. What tools/MCPs were used
4. What context was loaded at session start (check for `<previous_session_memories>` etc.)
5. Key decision points in the AI's reasoning

### Step 2: Present as educational walkthrough

Output format:

```markdown
## 🔬 X-Ray: What Just Happened

Let me explain what happened under the hood in our conversation.

---

### 📖 The Story of This Chat

Here's what I did, step by step:

**1. Session Started**
Before you typed anything, the system loaded:
- `CLAUDE.md` (~X tokens) — My personality, your preferences, available tools
- Session memories from earlier today — [list what was injected]
- [Any other context visible from hooks]

**Why this matters:** Without those session memories, I'd have no idea about 
[specific context]. That came from a **session hook** that runs before you type.

**2. You Asked: "[summarize their first message]"**

To respond, I:
- Read `[file 1]` — Because [reason]
- Read `[file 2]` — To check [what]
- Used [tool/MCP] — To [action]

**Why these files?** Your CLAUDE.md tells me where to look. It says [quote relevant 
instruction]. Without those instructions, I wouldn't know your file structure.

**3. [Continue for each major exchange in the conversation]**

---

### 🔧 Tools Used This Session

| Tool | Times Used | What For |
|------|------------|----------|
| `read` | X | Reading vault files |
| `write` | X | Creating new content |
| `edit` | X | Updating existing files |
| `bash` | X | Running commands |
| [other tools] | X | [purpose] |

**Why tools matter:** Without tools, I can only generate text. Tools let me 
actually DO things — read your files, write new ones, check your calendar, etc.

---

### 💡 Key Insight: The Context Window

Everything I "know" right now is what's in the **context window**:

```
┌─────────────────────────────────────────────────┐
│  What I can see (the context window)            │
├─────────────────────────────────────────────────┤
│ ✓ CLAUDE.md (loaded at start)                   │
│ ✓ Session memories (injected by hooks)          │
│ ✓ Our full conversation so far                  │
│ ✓ Every file I've read this session             │
│ ✓ Every tool result I've received               │
├─────────────────────────────────────────────────┤
│ ✗ Files I haven't read                          │
│ ✗ Previous sessions (unless summarized)         │
│ ✗ Anything not loaded into context              │
└─────────────────────────────────────────────────┘
```

If something isn't in this window, I literally don't know it exists.

---

### 📁 Files Touched This Session

**Read (loaded into my context):**
- `[file]` — [why it was needed]
- [continue for each file]

**Written/Modified:**
- `[file]` — [what was created/changed]
- [continue for each file]

**Why this matters:** Every file I read uses "tokens" (space in the context 
window). I try to read only what's relevant, not everything.

---

### 🎓 Concepts You Just Saw in Action

| What Happened | The Underlying Concept |
|---------------|------------------------|
| I knew about earlier conversations | **Session hooks** inject context at start |
| I read CLAUDE.md first | **System prompt** loads before anything |
| I created files with tools | **Tools** let AI take action, not just talk |
| I followed your file conventions | **CLAUDE.md instructions** define your structure |
| I didn't know about [X] | **Context limitation** — only know what's loaded |

---

### 🔮 What You Could Customize

Based on what just happened:

**1. Add to CLAUDE.md**
If you want me to always [behavior], add it to your `USER_EXTENSIONS` block.

**2. Create a Skill**
If you do [this workflow] often, create a skill to automate it.

**3. Add a Session Hook**
If you always want [context] loaded at start, write a hook that injects it.

---

### 🎓 Want to Go Deeper?

- `/xray ai` — First principles: context windows, tokens, statelessness
- `/xray dex` — Full architecture: CLAUDE.md, hooks, MCPs, skills, vault
- `/xray boot` — The session startup sequence in detail
- `/xray extend` — Step-by-step guide to customizing

Or ask anything: "How do hooks work?", "What's an MCP?", "How can I add my own tools?"
```

---

## MODE: AI Fundamentals (`/xray ai`)

**Purpose:** Teach the core concepts that make everything else make sense.

### Output Format

```markdown
## 🧠 How AI Actually Works

Let me explain the core concepts that underpin everything Dex does.

---

### The Big Truth: AI Has No Memory

**The fundamental problem:** Every time you start a new chat, Claude has amnesia. 
It doesn't remember yesterday's conversation. It doesn't know your name, your 
projects, or what you discussed last week.

This is true for ALL LLM-based AI — ChatGPT, Claude, Gemini, all of them.

**Why?** LLMs are "stateless." They process text in, text out, with no permanent 
storage between sessions. Each conversation starts from zero.

**So how does Dex remember things?** We engineer around the limitation. 
That's what Dex is — clever engineering to give a forgetful AI the *appearance* 
of memory, context, and continuity.

---

### Concept 1: The Context Window

When you chat with an AI, there's an invisible "window" of text the AI can see:

```
┌─────────────────────────────────────────────────┐
│              THE CONTEXT WINDOW                 │
│  (Everything the AI knows about THIS chat)      │
├─────────────────────────────────────────────────┤
│ • System prompt (CLAUDE.md)                     │
│ • Injected context (session memories, etc.)     │
│ • Our conversation so far                       │
│ • Any files I've read                           │
│ • Tool results (MCP responses)                  │
└─────────────────────────────────────────────────┘
          ↓
     AI generates response based on ALL of this
```

**Key insight:** The AI can only work with what's IN the context window. 
If information isn't in there, the AI doesn't know it exists.

**Dex's job:** Get the RIGHT information INTO that window at the RIGHT time.

---

### Concept 2: Tokens (The Currency)

Context windows are measured in "tokens" (roughly 4 characters = 1 token).

- Claude's window: ~200,000 tokens (~150,000 words)
- Your CLAUDE.md: ~4,500 tokens
- A typical person page: ~500 tokens

**Why it matters:** There's a budget. Load too much context and you hit limits 
or slow things down. Load too little and the AI lacks crucial information.

**Dex's approach:** Selective loading. Don't dump everything — load what's 
*relevant* to what you're asking about.

---

### Concept 3: System Prompts (The Personality)

Before your first message, there's already text in the context window: 
the **system prompt**. For Dex, that's `CLAUDE.md`.

```
┌─────────────────────────────────────────────────┐
│ CLAUDE.md (loaded before you type anything)     │
├─────────────────────────────────────────────────┤
│ "You are Dex, a personal knowledge assistant"   │
│ "User's pillars: [your pillars]"                │
│ "When tasks are mentioned, use Work MCP"        │
│ "Person pages are in 05-Areas/People/"          │
│ ... (hundreds more lines of context)            │
└─────────────────────────────────────────────────┘
```

**The power move:** Everything in CLAUDE.md influences EVERY response. 
It's like setting the AI's personality and knowledge before you say hello.

---

### Concept 4: Tools (How AI Does Things)

Claude can't *do* things by default — it can only generate text. But with 
**tools**, it can take actions:

- Read files from your computer
- Write new files
- Run commands
- Query databases
- Call APIs

In Dex, tools come from **MCP servers** (Model Context Protocol). Each MCP 
gives Claude new capabilities.

**Without tools:** Claude can only talk.
**With tools:** Claude can take action on your behalf.

---

### Concept 5: The Conversation Loop

Here's what happens every time you send a message:

```
1. Your message gets added to context window
                    ↓
2. Claude sees: system prompt + history + your message
                    ↓
3. Claude decides: should I use a tool?
   - If yes → Tool runs → Result added to context → Back to step 3
   - If no → Generate response
                    ↓
4. Response appears (and gets added to context for next turn)
                    ↓
5. Wait for your next message → Repeat from step 1
```

**Key insight:** Each turn, Claude sees MORE context (the history grows). 
Long conversations = more context = closer to limits.

---

### So What?

Understanding these fundamentals helps you:

1. **Know why Dex loads things at session start** — to get context into the window
2. **Understand why some info is "missing"** — it wasn't loaded into context
3. **See opportunities to extend** — what else could be loaded? what tools could help?

---

**Want to see Dex's specific architecture?** Try `/xray dex`
```

---

## MODE: Dex Architecture (`/xray dex`)

**Purpose:** Explain the specific building blocks that make Dex work.

### Output Format

```markdown
## 🏗️ How Dex Works: The Architecture

Now that you understand AI fundamentals, here's how Dex engineers around 
the limitations to create something useful.

---

### The Core Insight

**Problem:** Claude forgets everything between sessions.  
**Solution:** Store everything in FILES and reload context intelligently.

```
┌─────────────────────────────────────────────────┐
│                YOUR VAULT                        │
│  (Plain Markdown files YOU own)                 │
├─────────────────────────────────────────────────┤
│ • CLAUDE.md - Core context & personality        │
│ • 05-Areas/People/ - Relationship memory        │
│ • 03-Tasks/Tasks.md - Work in progress          │
│ • System/Session_Memory/ - Past conversations   │
│ • System/Work_In_Progress.md - Active projects  │
└─────────────────────────────────────────────────┘
            ↓ loaded at session start ↓
         ┌─────────────────────────────┐
         │      AI Context Window      │
         └─────────────────────────────┘
```

**The magic:** Your knowledge lives in files. AI reads files. 
Therefore, AI can "remember" by reading what was written before.

---

### Building Block 1: CLAUDE.md (The Brain)

The system prompt that defines who Dex is and how it behaves.

**Location:** `/CLAUDE.md` (root of your vault)

**Contains:**
- Your user profile (name, role, company)
- Your strategic pillars
- How Dex should behave
- What skills are available
- References to other docs

**Why it matters:** This loads FIRST, before anything else. It shapes every 
response. Edit this, and you change how Dex thinks.

**You can customize:**
```markdown
## USER_EXTENSIONS_START
<!-- Your personal additions go here -->
## USER_EXTENSIONS_END
```

---

### Building Block 2: Session Hooks (The Boot Sequence)

When you start a chat, things happen BEFORE you type anything.

**What hooks do:**
- Inject session memories from recent conversations
- Surface relevant context (person info, project status)
- Pre-load data you'll likely need

**Current hooks in Dex:**
- Session memories injection
- Person context surfacing
- Company context surfacing

**The power:** You can ADD hooks. Want weather loaded at session start? 
Your calendar? Write a hook, and it's there every session.

---

### Building Block 3: MCP Servers (The Toolbox)

MCP = Model Context Protocol. It's how Claude gets superpowers.

Each MCP server gives Claude new abilities:

| Server | What It Does |
|--------|--------------|
| **Work MCP** | Task management with deduplication and pillar alignment |
| **Calendar MCP** | Reads your Apple Calendar |
| **Granola MCP** | Searches meeting transcripts |
| **Career MCP** | Career evidence tracking and analysis |

**Why MCPs instead of just reading files?**
- **Speed:** Pre-process data instead of parsing raw files
- **Logic:** Implement business rules (like "can't have 4 P0 tasks")
- **Integration:** Connect to external systems

---

### Building Block 4: Skills (The Playbook)

Skills are structured instructions for multi-step workflows.

**Location:** `.claude/skills/[skill-name]/SKILL.md`

**Examples:**
- `/daily-plan` - Check calendar, review tasks, generate plan
- `/meeting-prep` - Load person context, surface recent discussions
- `/xray` - This skill you're running right now!

**Why skills?**
- **Consistency:** Same workflow every time
- **Complexity:** Handle multi-step processes
- **Reusability:** Build once, use forever

---

### Building Block 5: The Vault (The Memory)

Everything persists to Markdown files:

```
Your Vault/
├── 00-Inbox/           ← Capture zone
├── 03-Tasks/           ← Active tasks
├── 04-Projects/        ← Time-bound work
├── 05-Areas/           ← Ongoing responsibilities
│   ├── People/         ← Person pages
│   └── Companies/      ← Company profiles
├── 06-Resources/       ← Reference material
└── System/             ← Dex configuration
```

**Why plain Markdown?**
- You own it forever (no vendor lock-in)
- Works anywhere (Obsidian, VS Code, any editor)
- AI can read and write it
- Version control with Git if you want

---

### How It All Connects

```
Session starts
     ↓
Hooks fire (inject context)
     ↓
CLAUDE.md loads (personality + instructions)
     ↓
You type your message
     ↓
Claude reads relevant files (on-demand)
     ↓
Claude uses MCPs (if needed)
     ↓
Response generated + files updated
     ↓
Repeat for each message
```

---

### Key Insight: It's All Text

There's no magic database. No proprietary format. No cloud service.

- CLAUDE.md is text
- Skills are text
- Your notes are text
- Session memories are text

Claude reads text, processes it, generates text, writes text.

**Everything you're experiencing is text transformation.**

Understanding this is liberating — you can read, edit, and extend anything.

---

**Want to see the session startup in detail?** Try `/xray boot`
**Ready to customize?** Try `/xray extend`
```

---

## MODE: Session Boot Sequence (`/xray boot`)

**Purpose:** Detailed walkthrough of what happens when a session starts.

### Output Format

```markdown
## 🚀 What Happens When You Start a Chat

Let me walk you through exactly what happens from the moment you open 
a new chat to when you type your first message.

---

### The Boot Sequence (In Order)

#### Step 1: Environment Detection
```
Is this Claude Desktop? Claude Code? Cursor? PI?
     ↓
Each environment has slightly different capabilities
```

#### Step 2: Settings Load
```
Read configuration files
     ↓
This defines which hooks to run and which MCPs are available
```

#### Step 3: Hooks Fire (CRITICAL)
```
Pre-session hooks run in order:
     ↓
┌─────────────────────────────────────────────┐
│ Session memory injection                    │
│ → Reads System/Session_Memory/[date].md     │
│ → Injects summaries of recent conversations │
│ → AI "remembers" what you discussed before  │
└─────────────────────────────────────────────┘
     ↓
┌─────────────────────────────────────────────┐
│ Context injectors                           │
│ → Person context ready when you mention     │
│   names                                     │
│ → Company context ready when relevant       │
└─────────────────────────────────────────────┘
     ↓
┌─────────────────────────────────────────────┐
│ (Your custom hooks could go here)           │
│ → Whatever YOU want loaded at start         │
└─────────────────────────────────────────────┘
```

**This is where the magic happens!** Hooks let you inject ANY context 
before the conversation starts.

#### Step 4: CLAUDE.md Loads
```
The entire CLAUDE.md file enters the context window:
     ↓
• Your profile (name, role, company)
• Your strategic pillars  
• Behavior guidelines
• Reference to skills and tools
• User extensions (YOUR customizations)
```

#### Step 5: MCPs Connect
```
MCP servers become available:
     ↓
• Calendar MCP → Ready to check schedule
• Work MCP → Ready to manage tasks
• Granola MCP → Ready to search meetings
```

#### Step 6: Ready for Input
```
NOW you can type your first message.

The AI already has:
• Your personality and preferences (CLAUDE.md)
• Recent conversation summaries (from hooks)
• Relevant context (from hooks)
• Access to tools (MCPs)
```

---

### What This Means for You

**The AI doesn't start from zero.** By the time you type your first message, 
Claude already knows who you are, what you've been working on, and what 
tools are available.

**The boot sequence IS the memory system.** It's how a stateless AI 
"remembers" who you are.

---

### 💡 Customization Opportunity

**What else could be loaded at session start?**

Ideas for hooks:
1. Today's calendar events
2. Current sprint goals
3. Recent Git commits
4. Weather for outdoor planning
5. Your daily intention

**The pattern:** Anything you want the AI to "know" at the start of every 
session can be injected via a hook.

---

**Ready to create your own customizations?** Try `/xray extend`
```

## MODE: How to Extend (`/xray extend`)

**Purpose:** Practical guide to customization.

### Output Format

```markdown
## 🛠️ How to Extend Dex

Now that you understand how it works, here's how to make it your own.

---

### Level 1: Edit CLAUDE.md (5 minutes)

**The simplest customization.** Add your own instructions:

1. Open `CLAUDE.md` in any editor
2. Find the `USER_EXTENSIONS` section
3. Add your rules:

```markdown
## USER_EXTENSIONS_START

### My Preferences
- I'm a morning person — suggest important work before noon
- "The board" always means my company's board of directors
- Never suggest scheduling meetings on Wednesdays (my focus day)

## USER_EXTENSIONS_END
```

**This survives updates.** When you run `/dex-update`, this block is preserved.

---

### Level 2: Create a Skill (30 minutes)

**Make a reusable workflow:**

1. Create folder: `.claude/skills/my-skill/`
2. Create file: `SKILL.md`

```markdown
---
name: my-skill
description: What it does in one line
---

# My Custom Skill

## When to Use
[Trigger conditions]

## Steps
[Instructions for Claude to follow]

## Output Format
[What the result should look like]
```

3. Use it: Just type `/my-skill`

**Example ideas:**
- `/standup-prep` - Generate daily standup update
- `/client-brief` - Create client meeting brief
- `/weekly-email` - Draft weekly summary email

---

### Level 3: Create a Hook (1 hour)

**Inject context at every session start:**

1. Create a script that outputs the context you want
2. The output gets injected into the AI's context window
3. Now every conversation starts with that knowledge

**Example ideas:**
- Inject today's calendar at start
- Load current sprint goals
- Show recent Git commits

---

### Level 4: Create an MCP Server (Half day)

**Give Claude new capabilities:**

Run `/create-mcp` for guided setup.

**Example ideas:**
- Todoist MCP - Sync tasks with Todoist
- Notion MCP - Read/write to Notion
- Weather MCP - Get current conditions

---

### The Extension Philosophy

**Dex is scaffolding, not a finished product.** It's a starting point you customize.

The goal isn't to use Dex "as is" forever — it's to understand it well 
enough to make it truly yours.

**Question for you:** What do you wish the AI knew at the start of 
every session? That's your first extension.
```

---

## Usage Tracking

After running `/xray`, silently update `System/usage_log.md`:
- Check `X-ray transparency (/xray)` in the discovery section

If user runs specific educational modes, update the AI Education Progress section:
- `/xray ai` → Check "Understands context windows", "Understands tokens"
- `/xray dex` → Check "Understands system prompts", "Understands tools/MCPs"
- `/xray boot` → Check "Understands session hooks"
- `/xray extend` → Check "Understands vault architecture"

---

## Tone Guidelines

- **Concrete over abstract** — Use specific examples from their conversation
- **Show don't tell** — Point to actual files, tools, actions
- **Empowering not impressive** — Goal is their understanding, not your cleverness
- **Inviting curiosity** — End with pathways to learn more

---

## Track Usage (Silent)

Call the `mark_feature_used` tool on the `dex-analytics` MCP server with `xray`. This ticks the feature's box in `System/usage_log.md`, which is what `/dex-level-up` reads to recommend features that have not been tried. It writes locally and sends nothing, so it runs whether or not analytics is enabled.

**Analytics (Silent):**

Call `track_event` with event_name `xray_used` and properties:
- `mode` (context/tokens/prompts/tools/hooks/vault/extend)

This only fires if the user has opted into analytics. No action needed if it returns "analytics_disabled".