## 🔬 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**:

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?"

## 🧠 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:

**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`.

**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:

**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`

## 🏗️ 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.

**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

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

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

---

## 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

#### Step 2: Settings Load

#### Step 3: Hooks Fire (CRITICAL)

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

#### Step 4: CLAUDE.md Loads

#### Step 5: MCPs Connect

#### Step 6: Ready for Input

---

### 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`

## 🔬 X-Ray: Today

ScreenPipe isn't running, so I can't analyze your full day.

**To enable day analysis:**
1. Start ScreenPipe: Run `screenpipe` in terminal
2. It records your screen activity locally (nothing sent to cloud)
3. Come back and run `/xray today` again

**What you'll get:**
- Time breakdown by app
- Activity patterns
- "Moments you missed" where Dex could have helped

## 🔬 X-Ray: Today

[Activity summary from ScreenPipe]

---

### 🎓 How This Works

**What you just saw was ScreenPipe integration.** Here's what's happening:

1. **ScreenPipe records your screen** - Every few seconds, captures what's visible
2. **OCR extracts text** - It can "read" what's on screen
3. **A local database stores it** - SQLite on YOUR machine, not the cloud
4. **I query that database** - Via ScreenPipe tools

**Privacy model:**
- Everything stays on YOUR computer
- No data sent to external servers
- You control retention

**What this enables:**
- "What was I doing at 2pm?" → I can look it up
- "How much time in Slack?" → I can calculate
- "When did I see that error?" → I can search

---

[Continue with activity analysis, patterns, and suggestions]

## 🛠️ 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

---
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]

---

## 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)

Update `System/usage_log.md` to mark AI transparency education as used.

**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".