diff --git a/.claude/commands/audit-docs.md b/.claude/commands/audit-docs.md
index 56c2f920e..24d085692 100644
--- a/.claude/commands/audit-docs.md
+++ b/.claude/commands/audit-docs.md
@@ -2,7 +2,8 @@
 description: "Audit documentation for consistency and accuracy"
 ---
 
-Perform a documentation audit across the codebase. This is an AI-assisted review that produces a report for human judgment.
+Perform a documentation audit across the codebase. This is an AI-assisted 
+review that produces a report for human judgment.
 
 ## Audit Scope
 
diff --git a/.claude/commands/ctx-prompt-audit.md b/.claude/commands/ctx-prompt-audit.md
new file mode 100644
index 000000000..488cef950
--- /dev/null
+++ b/.claude/commands/ctx-prompt-audit.md
@@ -0,0 +1,89 @@
+---
+description: "Analyze session logs to identify vague prompts and suggest improvements"
+---
+
+Analyze recent session transcripts to identify prompts that led to unnecessary clarification back-and-forth. This helps the user improve their prompting patterns.
+
+## Your Task
+
+1. **Read recent sessions** from `.context/sessions/` (focus on the 3-5 most recent)
+2. **Identify vague prompts** - user messages that caused you to ask clarifying questions
+3. **Generate a coaching report** with concrete examples and suggestions
+
+## What Makes a Prompt "Vague"
+
+Look for user prompts where Claude's immediate response was to ask clarifying questions rather than take action. Signs include:
+
+- **Missing file context**: "fix the bug" without specifying which file or error
+- **Ambiguous scope**: "optimize it" without what to optimize or success criteria
+- **Undefined targets**: "update the component" when multiple components exist
+- **Missing error details**: "it's not working" without symptoms or expected behavior
+- **Vague action words**: "make it better", "clean this up", "improve the code"
+
+## Important Nuance
+
+Not every short prompt is vague! Consider context:
+- "fix the bug" after discussing a specific error in detail → **NOT vague**
+- "fix the bug" as the first message → **VAGUE**
+- "optimize it" when working on a single function → probably fine
+- "optimize it" in a large codebase with no context → **VAGUE**
+
+## Output Format
+
+Generate a report like this:
+
+```
+## Prompt Audit Report
+
+**Sessions analyzed**: 5
+**User prompts reviewed**: 47
+**Vague prompts found**: 4 (8.5%)
+
+---
+
+### Example 1: Missing File Context
+
+**Your prompt**: "fix the bug"
+
+**What happened**: I had to ask which file and what error you were seeing, adding 2 messages of back-and-forth.
+
+**Better prompt**: "fix the authentication error in src/auth/login.ts where JWT validation fails with 401"
+
+**Cost**: ~2 extra messages, ~30 seconds
+
+---
+
+### Example 2: Undefined Target
+
+**Your prompt**: "optimize the component"
+
+**What happened**: Multiple components exist. I asked which one and what performance issue to address.
+
+**Better prompt**: "optimize UserList in src/components/UserList.tsx to reduce re-renders when parent state updates"
+
+**Cost**: ~3 extra messages, ~1 minute
+
+---
+
+## Patterns to Watch
+
+Based on your sessions, you tend to:
+1. Skip mentioning file paths (3 occurrences)
+2. Use "it" without establishing what "it" refers to (2 occurrences)
+
+## Tips
+
+- Start prompts with the **file path** when discussing specific code
+- Include **error messages** when debugging
+- Specify **success criteria** for optimization tasks
+```
+
+## Guidelines
+
+- Be constructive, not critical - the goal is to help, not shame
+- Show the actual prompt from their session (quoted)
+- Explain what happened (what you had to ask)
+- Provide a concrete better alternative
+- Estimate the "cost" in extra messages/time
+- Look for patterns across multiple examples
+- End with actionable tips based on their specific tendencies
diff --git a/.claude/hooks/prompt-coach.sh b/.claude/hooks/prompt-coach.sh
new file mode 100755
index 000000000..e89490a30
--- /dev/null
+++ b/.claude/hooks/prompt-coach.sh
@@ -0,0 +1,145 @@
+#!/bin/bash
+
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+# Prompt coaching hook for Claude Code
+# Detects anti-patterns and suggests better alternatives.
+# Limits suggestions to MAX_SUGGESTIONS per pattern per session.
+#
+# Generated by: ctx init
+#
+# ANTI-PATTERNS DETECTED:
+# - "idiomatic X" → "follow project conventions"
+# - "best practices" → "follow CONVENTIONS.md"
+# - "fix the bug" (vague) → include error message, file, and context
+# - "optimize it" (vague) → specify what to optimize and why
+# - "make it better" (vague) → define "better" with criteria
+# - "update the component" (vague) → specify which component and what changes
+#
+# Output: Warnings to stderr (non-blocking)
+# Exit: Always 0 (never blocks execution)
+
+MAX_SUGGESTIONS=3
+SESSION_FILE="/tmp/ctx-prompt-coach-$$-$(date +%Y%m%d).state"
+
+# Initialize session file if it doesn't exist
+if [ ! -f "$SESSION_FILE" ]; then
+    cat > "$SESSION_FILE" << 'EOF'
+idiomatic=0
+bestpractices=0
+fixbug=0
+optimize=0
+makebetter=0
+update=0
+EOF
+fi
+
+# Read hook input from stdin (JSON)
+HOOK_INPUT=$(cat)
+
+# Extract the prompt text
+PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty')
+
+# If no prompt, allow
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Helper: get count for a pattern
+get_count() {
+    grep "^$1=" "$SESSION_FILE" 2>/dev/null | cut -d= -f2 || echo "0"
+}
+
+# Helper: increment count for a pattern
+increment_count() {
+    local pattern="$1"
+    local count=$(get_count "$pattern")
+    local new_count=$((count + 1))
+    if grep -q "^$pattern=" "$SESSION_FILE" 2>/dev/null; then
+        sed -i "s/^$pattern=.*/$pattern=$new_count/" "$SESSION_FILE"
+    else
+        echo "$pattern=$new_count" >> "$SESSION_FILE"
+    fi
+}
+
+# Helper: output a coaching tip (only if under limit)
+suggest() {
+    local pattern="$1"
+    local tip="$2"
+    local example="$3"
+    local count=$(get_count "$pattern")
+
+    if [ "$count" -lt "$MAX_SUGGESTIONS" ]; then
+        echo "" >&2
+        echo "┌─ Prompt Tip ─────────────────────────────────────" >&2
+        echo "│ $tip" >&2
+        if [ -n "$example" ]; then
+            echo "│" >&2
+            echo "│ Example: $example" >&2
+        fi
+        echo "└──────────────────────────────────────────────────" >&2
+        echo "" >&2
+        increment_count "$pattern"
+    fi
+}
+
+# Calculate prompt length (for detecting short vague prompts)
+PROMPT_LEN=${#PROMPT}
+
+# Check for "idiomatic X" pattern (case-insensitive)
+if echo "$PROMPT" | grep -qiE 'idiomatic (go|python|rust|javascript|typescript|java|c\+\+|ruby)'; then
+    suggest "idiomatic" \
+        "Instead of 'idiomatic X', try 'follow project conventions'" \
+        "'follow CONVENTIONS.md patterns for error handling'"
+fi
+
+# Check for "best practices" pattern (case-insensitive)
+if echo "$PROMPT" | grep -qiE '\bbest practices?\b'; then
+    suggest "bestpractices" \
+        "Instead of 'best practices', try 'follow CONVENTIONS.md'" \
+        "'follow the error handling pattern from CONVENTIONS.md'"
+fi
+
+# Check for vague "fix the bug" / "fix this bug" patterns
+# Only trigger if the prompt is short and lacks specifics
+if [ "$PROMPT_LEN" -lt 50 ] && echo "$PROMPT" | grep -qiE '\bfix (the|this|that|a) (bug|issue|error|problem)\b'; then
+    # Check if prompt lacks context (no file path, no error message, no line number)
+    if ! echo "$PROMPT" | grep -qE '(\.[a-z]{2,4}|line [0-9]|:[0-9]+|error:|Error:|failed|Failed)'; then
+        suggest "fixbug" \
+            "Add context: which file? what error? what's broken?" \
+            "'fix the JWT validation error in src/auth/login.ts returning 401'"
+    fi
+fi
+
+# Check for vague "optimize" patterns
+if [ "$PROMPT_LEN" -lt 40 ] && echo "$PROMPT" | grep -qiE '\b(optimize|optimise) (it|this|that)\b'; then
+    suggest "optimize" \
+        "Specify what to optimize and what metric matters" \
+        "'optimize UserList to reduce re-renders when parent state updates'"
+fi
+
+# Check for vague "make it better" patterns
+if echo "$PROMPT" | grep -qiE '\bmake (it|this|that) (better|nicer|cleaner|good)\b'; then
+    if [ "$PROMPT_LEN" -lt 50 ]; then
+        suggest "makebetter" \
+            "Define 'better' - readability? performance? maintainability?" \
+            "'refactor to be more readable by extracting validation logic'"
+    fi
+fi
+
+# Check for vague "update the component/function/file" patterns
+if [ "$PROMPT_LEN" -lt 50 ] && echo "$PROMPT" | grep -qiE '\bupdate (the|this|that|a) (component|function|file|module|class)\b'; then
+    # Check if prompt lacks specifics
+    if ! echo "$PROMPT" | grep -qE '(\.[a-z]{2,4}|src/|lib/|internal/)'; then
+        suggest "update" \
+            "Specify which component and what changes" \
+            "'update Button in src/components/Button.tsx to use new color tokens'"
+    fi
+fi
+
+# Always allow the prompt to proceed
+exit 0
diff --git a/.context/AGENT_PLAYBOOK.md b/.context/AGENT_PLAYBOOK.md
index 71ed30b7d..e33349a47 100644
--- a/.context/AGENT_PLAYBOOK.md
+++ b/.context/AGENT_PLAYBOOK.md
@@ -366,9 +366,23 @@ Before writing or modifying CLI code (`internal/cli/**/*.go`):
 
 1. **Read CONVENTIONS.md** — Load established patterns into context
 2. **Check similar commands** — How do existing commands in the same package handle output?
-3. **Use cmd methods for output** — `cmd.Printf`, `cmd.Println`, not `fmt.Printf`, `fmt.Println`
+3. **Use cmd methods for I/O** — Never use `fmt` for output in CLI code
 4. **Follow docstring format** — See Go Documentation Standard below
 
+**cmd methods to use:**
+
+| Instead of        | Use                | Purpose                              |
+|-------------------|--------------------|--------------------------------------|
+| `fmt.Printf`      | `cmd.Printf`       | Formatted stdout                     |
+| `fmt.Println`     | `cmd.Println`      | Line to stdout                       |
+| `fmt.Print`       | `cmd.Print`        | Raw stdout                           |
+| `fmt.Fprintf(os.Stderr, ...)` | `cmd.PrintErrf` | Formatted stderr          |
+| `fmt.Fprintln(os.Stderr, ...)` | `cmd.PrintErrln` | Line to stderr           |
+| `fmt.Sprintf`     | `fmt.Sprintf`      | String formatting (OK to keep)       |
+| `fmt.Errorf`      | `fmt.Errorf`       | Error creation (OK to keep)          |
+
+**Why**: cmd methods write to testable buffers; fmt writes to real stdout/stderr.
+
 **Quick pattern check:**
 ```bash
 # See how other commands do output
diff --git a/.context/LEARNINGS.md b/.context/LEARNINGS.md
index fdc5b1a5a..f8f3dff50 100644
--- a/.context/LEARNINGS.md
+++ b/.context/LEARNINGS.md
@@ -3,6 +3,7 @@
 <!-- INDEX:START -->
 | Date | Learning |
 |------|--------|
+| 2026-01-30 | Say 'project conventions' not 'idiomatic X' |
 | 2026-01-29 | Documentation audits require verification against actual standards |
 | 2026-01-28 | Required flags now enforced for learnings |
 | 2026-01-28 | Claude Code Hooks Receive JSON via Stdin |
@@ -40,6 +41,16 @@
 
 ---
 
+## [2026-01-30-120009] Say 'project conventions' not 'idiomatic X'
+
+**Context**: When asking Claude to follow documentation style, saying 'idiomatic Go' triggered training priors (stdlib conventions) instead of project-specific standards.
+
+**Lesson**: Use 'follow project conventions' or 'check AGENT_PLAYBOOK' rather than 'idiomatic [language]' to ensure Claude looks at project files first.
+
+**Application**: In prompts requesting style alignment, reference project files explicitly rather than language-wide conventions.
+
+---
+
 ## [2026-01-29-164322] Documentation audits require verification against actual standards
 
 **Context**: Agent claimed 'no Go docstring issues found' but manual inspection revealed many functions missing Parameters/Returns sections. The agent only checked if comments existed, not if they followed the standard format.
diff --git a/.context/TASKS.md b/.context/TASKS.md
index 8900b68e3..d610d5c3f 100644
--- a/.context/TASKS.md
+++ b/.context/TASKS.md
@@ -8,7 +8,6 @@
 
 ### Phase 1: Parser (DONE)
 
-
 ## Phase 1.a: Cleanup and Release
 
 - [x] T1.2.0.1b Add index markers to DECISIONS.md and LEARNINGS.md templates
@@ -22,36 +21,29 @@
 - [x] T1.2.7 feat: implement `--no-color` global flag to disable colored output
   Documented in cli-reference.md as planned. Currently `NO_COLOR=1` env var works.
   #priority:low #added:2026-01-28
-- [ ] T1.2.9: upstream CI is broken (again)
-- [ ] T1.2.10: Human code review
-- [ ] T1.2.11: Human to read all user-facing documentation and update as needed.
-- [ ] T1.2.12: cut a release (version number is already bumped)
-
-### Phase 2: Export & Search
-
-- [ ] feat: `ctx recall export` - export sessions to editable journal files
+- [x] Write AST-based test that warns if CLI functions use fmt.Print* instead of
+  cmd.Print* #added:2026-01-29-171351 #done:2026-01-31
+- [x] feat: `ctx recall export` - export sessions to editable journal files
   - `ctx recall export <session-id>` - export one session
   - `ctx recall export --all` - export all sessions
   - Skip existing files (user may have edited), `--force` to overwrite
   - Output to `.context/journal/YYYY-MM-DD-slug-shortid.md`
-  #added:2026-01-28
-
-- [ ] feat: `ctx recall search <query>` - CLI-based search across sessions
-  - Simple text search, no server needed
-  - IDE grep is alternative, this is convenience
-  #priority:low
-
-- [ ] explore: `ctx recall stats` - analytics/statistics
-  - Token usage over time, tool patterns, session durations
-  - Explore when we have a clear use case
-  #priority:deferred
+    #added:2026-01-28 #done:2026-01-31
+- [x] feat: ctx journal - LLM-powered session analysis and synthesis
+  - [x] ctx journal site - generate zensical static site #done:2026-01-31
+  - [x] ctx serve - convenience wrapper for zensical serve #done:2026-01-31
+  - [x] /ctx-journal-enrich - slash command for frontmatter/tags #done:2026-01-31
+  - [x] /ctx-journal-summarize - slash command for timeline summaries #done:2026-01-31
+- [ ] T1.2.9: upstream CI is broken (again)
+- [ ] T1.2.10: Human code review
+- [ ] T1.2.11: Human to read all user-facing documentation and update as needed.
+- [ ] T1.2.12: cut a release (version number is already bumped)
+- [ ] T1.2.13: Compose two blog posts: 1) what has changed after the human-guided
+      refactoring, and what we can learn about this.
+      2) what has happened since the last release cut.
 
 ## Backlog
 
-- [ ] Write AST-based test that warns if CLI functions use fmt.Print* instead of cmd.Print* #added:2026-01-29-171351
-
-- [ ] feat: ctx journal - LLM-powered session analysis and synthesis
-
 Parent command for working with exported sessions (.context/journal/):
 
 Subcommands to explore:
@@ -104,19 +96,10 @@ Additional supporting context:
 Depends on: ctx recall export (Phase 2)
 #priority:low #phase:future #added:2026-01-28-071638
 
-- [ ] feat: /ctx-blog slash command - generate blog post draft from recent activity
-
-Analyzes what happened since last blog post:
-- Sessions and their summaries
-- Commits and features added
-- Decisions made and rationale
-- Learnings discovered
-
-Outputs narrative markdown draft for human editing.
-Could integrate with ctx journal or work directly from sessions/git history.
-
-Related: ctx journal summarize (internal) vs ctx-blog (external/public)
-#priority:low #phase:future #added:2026-01-28-072625
+- [x] feat: /ctx-blog slash command - generate blog post draft from recent activity
+  - [x] /ctx-blog - from recent activity (sessions, commits, decisions)
+  - [x] /ctx-blog-changelog - from commit range with theme
+  #added:2026-01-28-072625 #done:2026-01-31
 
 - [ ] feat: ctx enrich - retroactively expand sparse context entries
 
@@ -134,3 +117,23 @@ Could run as:
 
 #priority:low #phase:future #added:2026-01-28-073058
 
+- [ ] feat: make config constants configurable via .contextrc
+
+Some hardcoded constants in internal/config/config.go could be user-configurable:
+- MaxDecisionsToSummarize (default 3)
+- MaxLearningsToSummarize (default 5)
+- MaxPreviewLen (default 60)
+- WatchAutoSaveInterval (default 5)
+
+Follow the pattern established for token_budget and archive_after_days in internal/rc.
+#priority:low #phase:future #added:2026-01-31
+
+- [ ] explore: `ctx recall stats` - analytics/statistics
+  - Token usage over time, tool patterns, session durations
+  - Explore when we have a clear use case
+    #priority:deferred
+
+- [ ] feat: `ctx recall search <query>` - CLI-based search across sessions
+  - Simple text search, no server needed
+  - IDE grep is alternative, this is convenience
+    #priority:low
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 669b1c496..d2b26e092 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,5 @@ dist/
 
 # Session transcripts (personal, potentially large)
 .context/sessions/
+.context/journal/
+.context/journal-site/
diff --git a/docs/ralph-loop.md b/docs/autonomous-loop.md
similarity index 88%
rename from docs/ralph-loop.md
rename to docs/autonomous-loop.md
index f3b53bfba..6247224bc 100644
--- a/docs/ralph-loop.md
+++ b/docs/autonomous-loop.md
@@ -5,26 +5,30 @@
 #   \    Copyright 2026-present Context contributors.
 #                 SPDX-License-Identifier: Apache-2.0
 
-title: Ralph and Context
+title: Autonomous Loops
 icon: lucide/repeat
 ---
 
 ![ctx](images/ctx-banner.png)
 
-## `ralph` + `ctx`
+## Autonomous AI Development
 
-*Like peanut butter and jelly: better together.*
+*Iterate until done.*
 
-The [Ralph Wiggum technique](https://ghuntley.com/ralph/) is an iterative AI development workflow where 
-an agent works autonomously on tasks until completion. Context (`ctx`) and 
-Ralph complement each other perfectly:
+An autonomous loop is an iterative AI development workflow where an agent works
+on tasks until completion—without constant human intervention. Context (`ctx`)
+provides the memory that makes this possible:
 
-- **`ctx`** provides the *memory*: persistent context that survives across sessions
-- **`ralph`** provides the *loop*: autonomous iteration that runs until done
+- **`ctx`** provides the *memory*: persistent context that survives across iterations
+- **The loop** provides the *automation*: continuous execution until done
 
-Together, they enable fully autonomous AI development where the agent remembers 
+Together, they enable fully autonomous AI development where the agent remembers
 everything across iterations.
 
+!!! note "Origin"
+    This pattern is inspired by [Geoffrey Huntley's Ralph Wiggum technique](https://ghuntley.com/ralph/).
+    We use generic terminology here so the concepts remain clear regardless of trends.
+
 ## How It Works
 
 ```mermaid
@@ -51,14 +55,14 @@ graph TD
 
 ## Quick Start with Claude Code
 
-Claude Code has a built-in Ralph Loop plugin:
+Claude Code has built-in loop support:
 
 ```bash
 # Start autonomous loop
-/ralph-loop
+/loop
 
 # Cancel running loop
-/cancel-ralph
+/cancel-loop
 ```
 
 That's it. The loop will:
@@ -73,11 +77,11 @@ For other AI tools, create a `loop.sh`:
 
 ```bash
 #!/bin/bash
-# loop.sh — a minimal Ralph loop
+# loop.sh — an autonomous iteration loop
 
 PROMPT_FILE="${1:-PROMPT.md}"
 MAX_ITERATIONS="${2:-10}"
-OUTPUT_FILE="/tmp/ralph_output.txt"
+OUTPUT_FILE="/tmp/loop_output.txt"
 
 for i in $(seq 1 $MAX_ITERATIONS); do
   echo "=== Iteration $i ==="
@@ -110,6 +114,8 @@ chmod +x loop.sh
 ./loop.sh
 ```
 
+You can also generate this script with `ctx loop` (see [CLI Reference](cli-reference.md#ctx-loop)).
+
 ## The PROMPT.md File
 
 The prompt file instructs the AI on how to work autonomously. Here's a template:
@@ -201,9 +207,7 @@ Please provide credentials and confirm deployment region.
 SYSTEM_BLOCKED
 ```
 
-## Context Integration
-
-### Why ctx + Ralph Work Well Together
+## Why Context + Loops Work Well Together
 
 | Without ctx                 | With ctx                             |
 |-----------------------------|--------------------------------------|
@@ -253,7 +257,7 @@ Run `ctx watch` alongside the loop to automatically process context updates:
 ctx watch --log /tmp/loop.log --auto-save
 ```
 
-The `--auto-save` flag periodically saves session snapshots, creating a 
+The `--auto-save` flag periodically saves session snapshots, creating a
 history of the loop's progress.
 
 ## Example Project Setup
@@ -272,7 +276,7 @@ my-project/
 └── src/                  # Your code
 ```
 
-### Sample TASKS.md for Ralph
+### Sample TASKS.md for Autonomous Loops
 
 ```markdown
 # Tasks
@@ -347,6 +351,6 @@ BEFORE any work:
 
 ## Resources
 
-- [Ralph Wiggum Technique](https://ghuntley.com/ralph/) — Original blog post
+- [Geoffrey Huntley's Ralph Wiggum Technique](https://ghuntley.com/ralph/) — Original inspiration
 - [Context CLI](cli-reference.md) — Command reference
 - [Integrations](integrations.md) — Tool-specific setup
diff --git a/docs/blog/2026-01-27-building-ctx-using-ctx.md b/docs/blog/2026-01-27-building-ctx-using-ctx.md
index 1888b184b..61d9d116c 100644
--- a/docs/blog/2026-01-27-building-ctx-using-ctx.md
+++ b/docs/blog/2026-01-27-building-ctx-using-ctx.md
@@ -36,10 +36,11 @@ That is "*reset amnesia*", and it's not just annoying: it's expensive.
 Every session starts with re-explaining context, re-reading files, 
 re-discovering decisions that were already made.
 
-> "I don't want to lose this discussion... 
-> I am a brain-dead developer YOLO'ing my way out"
+!!! quote "I Needed Context"
+    I don't want to lose this discussion... 
+    I am a brain-dead developer YOLO'ing my way out
 
-That's exactly what I said to Claude when I first started working on `ctx`.
+☝️ that's exactly what I said to Claude when I first started working on `ctx`.
 
 ## The Genesis
 
diff --git a/docs/blog/index.md b/docs/blog/index.md
index ff201b825..70c0e2cd6 100644
--- a/docs/blog/index.md
+++ b/docs/blog/index.md
@@ -13,11 +13,15 @@ Stories, insights, and lessons learned from building and using ctx.
 
 ### [Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development](2026-01-27-building-ctx-using-ctx.md)
 
-*January 27, 2026*
+*Jose Alekhinne / January 27, 2026*
 
-What happens when you build a tool designed to give AI memory, using that very same tool to remember what you're building? This is the story of ctx—how it evolved from a hasty "YOLO mode" experiment to a disciplined system for persistent AI context, and what we learned along the way.
+What happens when you build a tool designed to give AI memory, using that very 
+same tool to remember what you're building? This is the story of ctx—how it 
+evolved from a hasty "YOLO mode" experiment to a disciplined system for 
+persistent AI context, and what we learned along the way.
 
-**Topics**: dogfooding, AI-assisted development, Ralph Loop, session persistence, architectural decisions
+**Topics**: dogfooding, AI-assisted development, Ralph Loop, session 
+persistence, architectural decisions
 
 ---
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index ee429901e..7c86f18e0 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -24,7 +24,6 @@ All commands support these flags:
 | `--help`               | Show command help                                 |
 | `--version`            | Show version                                      |
 | `--context-dir <path>` | Override context directory (default: `.context/`) |
-| `--quiet`              | Suppress non-essential output                     |
 | `--no-color`           | Disable colored output                            |
 
 > The `NO_COLOR=1` environment variable also disables colored output.
@@ -530,6 +529,103 @@ ctx recall show --latest
 ctx recall show --latest --full
 ```
 
+#### `ctx recall export`
+
+Export sessions to editable journal files in `.context/journal/`.
+
+```bash
+ctx recall export [session-id] [flags]
+```
+
+**Flags**:
+
+| Flag      | Description                              |
+|-----------|------------------------------------------|
+| `--all`   | Export all sessions                      |
+| `--force` | Overwrite existing files                 |
+
+Exported files include session metadata, tool usage summary, and the full
+conversation. Existing files are skipped by default to preserve your edits.
+
+The `journal/` directory should be gitignored (like `sessions/`) since it
+contains raw conversation data.
+
+**Example**:
+
+```bash
+ctx recall export abc123          # Export one session
+ctx recall export --all           # Export all sessions
+ctx recall export --all --force   # Overwrite existing exports
+```
+
+---
+
+### `ctx journal`
+
+Analyze and synthesize exported session files.
+
+```bash
+ctx journal <subcommand>
+```
+
+#### `ctx journal site`
+
+Generate a static site from journal entries in `.context/journal/`.
+
+```bash
+ctx journal site [flags]
+```
+
+**Flags**:
+
+| Flag       | Short | Description                              |
+|------------|-------|------------------------------------------|
+| `--output` | `-o`  | Output directory (default: .context/journal-site) |
+| `--build`  |       | Run zensical build after generating      |
+| `--serve`  |       | Run zensical serve after generating      |
+
+Creates a zensical-compatible site structure with an index page listing
+all sessions by date, and individual pages for each journal entry.
+
+Requires zensical to be installed for `--build` or `--serve`:
+```bash
+pip install zensical
+```
+
+**Example**:
+
+```bash
+ctx journal site                    # Generate in .context/journal-site/
+ctx journal site --output ~/public  # Custom output directory
+ctx journal site --build            # Generate and build HTML
+ctx journal site --serve            # Generate and serve locally
+```
+
+---
+
+### `ctx serve`
+
+Serve a static site locally via zensical.
+
+```bash
+ctx serve [directory]
+```
+
+If no directory is specified, serves the journal site (`.context/journal-site`).
+
+Requires zensical to be installed:
+```bash
+pip install zensical
+```
+
+**Example**:
+
+```bash
+ctx serve                           # Serve journal site
+ctx serve .context/journal-site     # Serve specific directory
+ctx serve ./docs                    # Serve docs folder
+```
+
 ---
 
 ### `ctx watch`
@@ -692,9 +788,9 @@ ctx session parse transcript.jsonl -o conversation.md
 
 ### `ctx loop`
 
-Generate a shell script for running a Ralph loop.
+Generate a shell script for running an autonomous loop.
 
-A Ralph loop continuously runs an AI assistant with the same prompt until
+An autonomous loop continuously runs an AI assistant with the same prompt until
 a completion signal is detected, enabling iterative development where the
 AI builds on its previous work.
 
@@ -737,7 +833,7 @@ chmod +x loop.sh
 ./loop.sh
 ```
 
-See [Ralph Loop Integration](ralph-loop.md) for detailed workflow documentation.
+See [Autonomous Loops](autonomous-loop.md) for detailed workflow documentation.
 
 ---
 
diff --git a/docs/comparison.md b/docs/comparison.md
index 85f39de9c..3bae52fa3 100644
--- a/docs/comparison.md
+++ b/docs/comparison.md
@@ -153,10 +153,9 @@ Without persistent context, agents tend to:
 * repeat mistakes
 * lose architectural intent
 
-This is why `ctx` pairs well with loop-based workflows such as the
-[Ralph Wiggum technique](https://ghuntley.com/ralph/):
+This is why `ctx` pairs well with [autonomous loop workflows](autonomous-loop.md):
 
-* `ralph` provides iteration
+* The loop provides iteration
 * `ctx` provides continuity
 
 Together, loops become cumulative instead of forgetful.
diff --git a/docs/index.md b/docs/index.md
index 9a75f7ce1..86b9e1427 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -237,5 +237,5 @@ ctx drift
 - [Prompting Guide](prompting-guide.md) — Effective prompts for AI sessions
 - [CLI Reference](cli-reference.md) — All commands and options
 - [Context Files](context-files.md) — File formats and structure
-- [`ralph` and `ctx`](ralph-loop.md) — Autonomous AI development workflows
+- [Autonomous Loops](autonomous-loop.md) — Iterative AI development workflows
 - [Integrations](integrations.md) — Setup for Claude Code, Cursor, Aider
diff --git a/docs/integrations.md b/docs/integrations.md
index c1e950a7d..03ded8561 100644
--- a/docs/integrations.md
+++ b/docs/integrations.md
@@ -126,6 +126,62 @@ ctx agent --budget 4000
 cat .context/TASKS.md
 ```
 
+### Slash Commands
+
+`ctx init` installs slash commands to `.claude/commands/`. These are shortcuts
+you can invoke in Claude Code with `/command-name`.
+
+#### Context Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ctx-status` | Show context summary (tasks, decisions, learnings) |
+| `/ctx-agent` | Get AI-optimized context packet |
+| `/ctx-save` | Save current session to `.context/sessions/` |
+| `/ctx-reflect` | Review session and suggest what to persist |
+
+#### Adding Context
+
+| Command | Description |
+|---------|-------------|
+| `/ctx-add-task` | Add a task to TASKS.md |
+| `/ctx-add-learning` | Add a learning to LEARNINGS.md |
+| `/ctx-add-decision` | Add a decision with context/rationale/consequences |
+| `/ctx-archive` | Archive completed tasks |
+
+#### Session History
+
+| Command | Description |
+|---------|-------------|
+| `/ctx-recall` | Browse AI session history |
+| `/ctx-journal-enrich` | Enrich a journal entry with frontmatter/tags |
+| `/ctx-journal-summarize` | Generate summary of sessions over a time period |
+
+#### Blogging
+
+| Command | Description |
+|---------|-------------|
+| `/ctx-blog` | Generate blog post from recent activity |
+| `/ctx-blog-changelog` | Generate blog post from commit range with theme |
+
+#### Development
+
+| Command | Description |
+|---------|-------------|
+| `/ctx-loop` | Generate a Ralph Loop iteration script |
+| `/ctx-prompt-audit` | Analyze session logs for vague prompts |
+
+#### Usage Examples
+
+```text
+/ctx-status
+/ctx-add-learning "Token refresh requires explicit cache invalidation"
+/ctx-journal-enrich twinkly-stirring-kettle
+/ctx-journal-summarize last week
+```
+
+Slash commands support partial matching where applicable (e.g., session slugs).
+
 ---
 
 ## Cursor IDE
diff --git a/docs/prompting-guide.md b/docs/prompting-guide.md
index c83138f04..d2692ccd8 100644
--- a/docs/prompting-guide.md
+++ b/docs/prompting-guide.md
@@ -209,6 +209,7 @@ so far, here are some prompts that tend to produce poor results:
 | "Just do it"          | Skips planning                | "Plan this, then implement"           |
 | "You should remember" | Confrontational               | "Do you remember?"                    |
 | "Obviously..."        | Discourages questions         | State the requirement directly        |
+| "Idiomatic X"         | Triggers language priors      | "Follow project conventions"          |
 
 ---
 
diff --git a/docs/security.md b/docs/security.md
index b8a8d36e3..cd14f4d35 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -51,8 +51,9 @@ Send details to **security@ctx.ist**
 - **Local only**: ctx runs entirely locally with no external network calls
 - **No code execution**: ctx reads and writes Markdown files only; it does 
   not execute arbitrary code
-- **Git-tracked**: All context files are meant to be committed, so they should
-  never contain sensitive data
+- **Git-tracked**: Core context files are meant to be committed, so they should
+  never contain sensitive data. Exception: `sessions/` and `journal/` contain
+  raw conversation data and should be gitignored
 
 ## Best Practices
 
diff --git a/internal/bootstrap/bootstrap.go b/internal/bootstrap/bootstrap.go
index f15156eaa..4d51fab9a 100644
--- a/internal/bootstrap/bootstrap.go
+++ b/internal/bootstrap/bootstrap.go
@@ -23,20 +23,22 @@ import (
 	"github.com/ActiveMemory/ctx/internal/cli/agent"
 	"github.com/ActiveMemory/ctx/internal/cli/compact"
 	"github.com/ActiveMemory/ctx/internal/cli/complete"
-	"github.com/ActiveMemory/ctx/internal/cli/decisions"
+	"github.com/ActiveMemory/ctx/internal/cli/decision"
 	"github.com/ActiveMemory/ctx/internal/cli/drift"
 	"github.com/ActiveMemory/ctx/internal/cli/hook"
 	"github.com/ActiveMemory/ctx/internal/cli/initialize"
+	"github.com/ActiveMemory/ctx/internal/cli/journal"
 	"github.com/ActiveMemory/ctx/internal/cli/learnings"
 	"github.com/ActiveMemory/ctx/internal/cli/load"
 	"github.com/ActiveMemory/ctx/internal/cli/loop"
 	"github.com/ActiveMemory/ctx/internal/cli/recall"
+	"github.com/ActiveMemory/ctx/internal/cli/serve"
 	"github.com/ActiveMemory/ctx/internal/cli/session"
 	"github.com/ActiveMemory/ctx/internal/cli/status"
 	"github.com/ActiveMemory/ctx/internal/cli/sync"
 	"github.com/ActiveMemory/ctx/internal/cli/task"
 	"github.com/ActiveMemory/ctx/internal/cli/watch"
-	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // version is set at build time via ldflags
@@ -49,7 +51,6 @@ const version = "dev"
 //
 // Global flags:
 //   - --context-dir: Override the context directory path (default: .context)
-//   - --quiet: Suppress non-essential output
 //   - --no-color: Disable colored output
 //
 // Returns:
@@ -71,7 +72,7 @@ func RootCmd() *cobra.Command {
 		PersistentPreRun: func(cmd *cobra.Command, args []string) {
 			// Apply global flag values
 			if contextDir != "" {
-				config.SetContextDir(contextDir)
+				rc.OverrideContextDir(contextDir)
 			}
 			if noColor {
 				color.NoColor = true
@@ -86,12 +87,6 @@ func RootCmd() *cobra.Command {
 		"",
 		"Override context directory path (default: .context)",
 	)
-	cmd.PersistentFlags().BoolVar(
-		&config.Quiet,
-		"quiet",
-		false,
-		"Suppress non-essential output",
-	)
 	cmd.PersistentFlags().BoolVar(
 		&noColor,
 		"no-color",
@@ -114,23 +109,29 @@ func RootCmd() *cobra.Command {
 // Returns:
 //   - *cobra.Command: The same command with all subcommands registered
 func Initialize(cmd *cobra.Command) *cobra.Command {
-	cmd.AddCommand(initialize.Cmd())
-	cmd.AddCommand(status.Cmd())
-	cmd.AddCommand(load.Cmd())
-	cmd.AddCommand(add.Cmd())
-	cmd.AddCommand(complete.Cmd())
-	cmd.AddCommand(agent.Cmd())
-	cmd.AddCommand(drift.Cmd())
-	cmd.AddCommand(sync.Cmd())
-	cmd.AddCommand(compact.Cmd())
-	cmd.AddCommand(decisions.Cmd())
-	cmd.AddCommand(watch.Cmd())
-	cmd.AddCommand(hook.Cmd())
-	cmd.AddCommand(learnings.Cmd())
-	cmd.AddCommand(session.Cmd())
-	cmd.AddCommand(task.Cmd())
-	cmd.AddCommand(loop.Cmd())
-	cmd.AddCommand(recall.Cmd())
+	for _, c := range []func() *cobra.Command{
+		initialize.Cmd,
+		status.Cmd,
+		load.Cmd,
+		add.Cmd,
+		complete.Cmd,
+		agent.Cmd,
+		drift.Cmd,
+		sync.Cmd,
+		compact.Cmd,
+		decision.Cmd,
+		watch.Cmd,
+		hook.Cmd,
+		learnings.Cmd,
+		session.Cmd,
+		task.Cmd,
+		loop.Cmd,
+		recall.Cmd,
+		journal.Cmd,
+		serve.Cmd,
+	} {
+		cmd.AddCommand(c())
+	}
 
 	return cmd
 }
diff --git a/internal/claude/embed_test.go b/internal/claude/claude_test.go
similarity index 61%
rename from internal/claude/embed_test.go
rename to internal/claude/claude_test.go
index b8da5d90a..3647b2691 100644
--- a/internal/claude/embed_test.go
+++ b/internal/claude/claude_test.go
@@ -11,63 +11,63 @@ import (
 	"testing"
 )
 
-func TestGetAutoSaveScript(t *testing.T) {
-	content, err := GetAutoSaveScript()
+func TestAutoSaveScript(t *testing.T) {
+	content, err := AutoSaveScript()
 	if err != nil {
-		t.Fatalf("GetAutoSaveScript() unexpected error: %v", err)
+		t.Fatalf("AutoSaveScript() unexpected error: %v", err)
 	}
 
 	if len(content) == 0 {
-		t.Error("GetAutoSaveScript() returned empty content")
+		t.Error("AutoSaveScript() returned empty content")
 	}
 
 	// Check for expected script content
 	script := string(content)
 	if !strings.Contains(script, "#!/") {
-		t.Error("GetAutoSaveScript() script missing shebang")
+		t.Error("AutoSaveScript() script missing shebang")
 	}
 }
 
-func TestGetBlockNonPathCtxScript(t *testing.T) {
-	content, err := GetBlockNonPathCtxScript()
+func TestBlockNonPathCtxScript(t *testing.T) {
+	content, err := BlockNonPathCtxScript()
 	if err != nil {
-		t.Fatalf("GetBlockNonPathCtxScript() unexpected error: %v", err)
+		t.Fatalf("BlockNonPathCtxScript() unexpected error: %v", err)
 	}
 
 	if len(content) == 0 {
-		t.Error("GetBlockNonPathCtxScript() returned empty content")
+		t.Error("BlockNonPathCtxScript() returned empty content")
 	}
 
 	// Check for expected script content
 	script := string(content)
 	if !strings.Contains(script, "#!/") {
-		t.Error("GetBlockNonPathCtxScript() script missing shebang")
+		t.Error("BlockNonPathCtxScript() script missing shebang")
 	}
 }
 
-func TestListCommands(t *testing.T) {
-	commands, err := ListCommands()
+func TestCommands(t *testing.T) {
+	commands, err := Commands()
 	if err != nil {
-		t.Fatalf("ListCommands() unexpected error: %v", err)
+		t.Fatalf("Commands() unexpected error: %v", err)
 	}
 
 	if len(commands) == 0 {
-		t.Error("ListCommands() returned empty list")
+		t.Error("Commands() returned empty list")
 	}
 
 	// Check that all entries are .md files
 	for _, cmd := range commands {
 		if !strings.HasSuffix(cmd, ".md") {
-			t.Errorf("ListCommands() returned non-.md file: %s", cmd)
+			t.Errorf("Commands() returned non-.md file: %s", cmd)
 		}
 	}
 }
 
-func TestGetCommand(t *testing.T) {
+func TestCommandByName(t *testing.T) {
 	// First get the list of commands to test with
-	commands, err := ListCommands()
+	commands, err := Commands()
 	if err != nil {
-		t.Fatalf("ListCommands() failed: %v", err)
+		t.Fatalf("Commands() failed: %v", err)
 	}
 
 	if len(commands) == 0 {
@@ -75,22 +75,22 @@ func TestGetCommand(t *testing.T) {
 	}
 
 	// Test getting the first command
-	content, err := GetCommand(commands[0])
+	content, err := CommandByName(commands[0])
 	if err != nil {
-		t.Errorf("GetCommand(%q) unexpected error: %v", commands[0], err)
+		t.Errorf("CommandByName(%q) unexpected error: %v", commands[0], err)
 	}
 	if len(content) == 0 {
-		t.Errorf("GetCommand(%q) returned empty content", commands[0])
+		t.Errorf("CommandByName(%q) returned empty content", commands[0])
 	}
 
 	// Test getting nonexistent command
-	_, err = GetCommand("nonexistent-command.md")
+	_, err = CommandByName("nonexistent-command.md")
 	if err == nil {
-		t.Error("GetCommand(nonexistent) expected error, got nil")
+		t.Error("CommandByName(nonexistent) expected error, got nil")
 	}
 }
 
-func TestCreateDefaultHooks(t *testing.T) {
+func TestDefaultHooks(t *testing.T) {
 	tests := []struct {
 		name       string
 		projectDir string
@@ -107,16 +107,16 @@ func TestCreateDefaultHooks(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			hooks := CreateDefaultHooks(tt.projectDir)
+			hooks := DefaultHooks(tt.projectDir)
 
 			// Check PreToolUse hooks
 			if len(hooks.PreToolUse) == 0 {
-				t.Error("CreateDefaultHooks() PreToolUse is empty")
+				t.Error("DefaultHooks() PreToolUse is empty")
 			}
 
 			// Check SessionEnd hooks
 			if len(hooks.SessionEnd) == 0 {
-				t.Error("CreateDefaultHooks() SessionEnd is empty")
+				t.Error("DefaultHooks() SessionEnd is empty")
 			}
 
 			// Check that project dir is used in paths when provided
@@ -131,7 +131,7 @@ func TestCreateDefaultHooks(t *testing.T) {
 					}
 				}
 				if !found {
-					t.Error("CreateDefaultHooks() project dir not found in hook commands")
+					t.Error("DefaultHooks() project dir not found in hook commands")
 				}
 			}
 		})
@@ -141,7 +141,7 @@ func TestCreateDefaultHooks(t *testing.T) {
 func TestSettingsStructure(t *testing.T) {
 	// Test that Settings struct can be instantiated correctly
 	settings := Settings{
-		Hooks: CreateDefaultHooks(""),
+		Hooks: DefaultHooks(""),
 		Permissions: PermissionsConfig{
 			Allow: []string{"Bash(ctx status:*)", "Bash(ctx agent:*)"},
 		},
@@ -156,11 +156,11 @@ func TestSettingsStructure(t *testing.T) {
 	}
 }
 
-func TestCreateDefaultPermissions(t *testing.T) {
-	perms := CreateDefaultPermissions()
+func TestDefaultPermissions(t *testing.T) {
+	perms := DefaultPermissions()
 
 	if len(perms) == 0 {
-		t.Error("CreateDefaultPermissions should return permissions")
+		t.Error("DefaultPermissions should return permissions")
 	}
 
 	// Check that essential ctx commands are included
diff --git a/internal/claude/cmd.go b/internal/claude/cmd.go
new file mode 100644
index 000000000..01ae7ec5d
--- /dev/null
+++ b/internal/claude/cmd.go
@@ -0,0 +1,46 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package claude
+
+import (
+	"fmt"
+
+	"github.com/ActiveMemory/ctx/internal/templates"
+)
+
+// Commands returns the list of embedded command file names.
+//
+// These are Claude Code slash command definitions (e.g., "ctx-status.md",
+// "ctx-reflect.md") from internal/templates/claude/commands/. They can be
+// installed to .claude/commands/ via "ctx init".
+//
+// Returns:
+//   - []string: Filenames of available command definitions
+//   - error: Non-nil if the commands directory cannot be read
+func Commands() ([]string, error) {
+	names, err := templates.ListClaudeCommands()
+	if err != nil {
+		return nil, fmt.Errorf("failed to list commands: %w", err)
+	}
+	return names, nil
+}
+
+// CommandByName returns the content of a command file by name.
+//
+// Parameters:
+//   - name: Filename as returned by [Commands] (e.g., "ctx-status.md")
+//
+// Returns:
+//   - []byte: Raw bytes of the command definition file
+//   - error: Non-nil if the command file does not exist or cannot be read
+func CommandByName(name string) ([]byte, error) {
+	content, err := templates.GetClaudeCommand(name)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read command %s: %w", name, err)
+	}
+	return content, nil
+}
diff --git a/internal/claude/doc.go b/internal/claude/doc.go
index 8882f8d42..09244de74 100644
--- a/internal/claude/doc.go
+++ b/internal/claude/doc.go
@@ -17,7 +17,7 @@
 //
 // Example usage:
 //
-//	script, err := claude.GetAutoSaveScript()
+//	script, err := claude.AutoSaveScript()
 //	if err != nil {
 //	    return err
 //	}
diff --git a/internal/claude/embed.go b/internal/claude/embed.go
deleted file mode 100644
index 0418fb57f..000000000
--- a/internal/claude/embed.go
+++ /dev/null
@@ -1,153 +0,0 @@
-//   /    Context:                     https://ctx.ist
-// ,'`./    do you remember?
-// `.,'\
-//   \    Copyright 2026-present Context contributors.
-//                 SPDX-License-Identifier: Apache-2.0
-
-package claude
-
-import (
-	"fmt"
-
-	"github.com/ActiveMemory/ctx/internal/templates"
-)
-
-// GetAutoSaveScript returns the auto-save session script content.
-//
-// The script automatically saves Claude Code session transcripts when a
-// session ends. It is installed to .claude/hooks/ during ctx init --claude.
-//
-// Returns:
-//   - []byte: Raw bytes of the auto-save-session.sh script
-//   - error: Non-nil if the embedded file cannot be read
-func GetAutoSaveScript() ([]byte, error) {
-	content, err := templates.GetClaudeHook("auto-save-session.sh")
-	if err != nil {
-		return nil, fmt.Errorf("failed to read auto-save-session.sh: %w", err)
-	}
-	return content, nil
-}
-
-// GetBlockNonPathCtxScript returns the script that blocks non-PATH ctx
-// invocations.
-//
-// The script prevents Claude from running ctx via relative paths (./ctx,
-// ./dist/ctx) or "go run", ensuring only the installed PATH version is used.
-// It is installed to .claude/hooks/ during ctx init --claude.
-//
-// Returns:
-//   - []byte: Raw bytes of the block-non-path-ctx.sh script
-//   - error: Non-nil if the embedded file cannot be read
-func GetBlockNonPathCtxScript() ([]byte, error) {
-	content, err := templates.GetClaudeHook("block-non-path-ctx.sh")
-	if err != nil {
-		return nil, fmt.Errorf("failed to read block-non-path-ctx.sh: %w", err)
-	}
-	return content, nil
-}
-
-// ListCommands returns the list of embedded command file names.
-//
-// These are Claude Code slash command definitions (e.g., "ctx-status.md",
-// "ctx-reflect.md") from internal/templates/claude/commands/. They can be
-// installed to .claude/commands/ via "ctx init".
-//
-// Returns:
-//   - []string: Filenames of available command definitions
-//   - error: Non-nil if the commands directory cannot be read
-func ListCommands() ([]string, error) {
-	names, err := templates.ListClaudeCommands()
-	if err != nil {
-		return nil, fmt.Errorf("failed to list commands: %w", err)
-	}
-	return names, nil
-}
-
-// GetCommand returns the content of a command file by name.
-//
-// Parameters:
-//   - name: Filename as returned by [ListCommands] (e.g., "ctx-status.md")
-//
-// Returns:
-//   - []byte: Raw bytes of the command definition file
-//   - error: Non-nil if the command file does not exist or cannot be read
-func GetCommand(name string) ([]byte, error) {
-	content, err := templates.GetClaudeCommand(name)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read command %s: %w", name, err)
-	}
-	return content, nil
-}
-
-// CreateDefaultPermissions returns the default permissions for ctx commands.
-//
-// These permissions allow Claude Code to run ctx CLI commands without
-// prompting for approval. All ctx subcommands are pre-approved.
-//
-// Returns:
-//   - []string: List of permission patterns for ctx commands
-func CreateDefaultPermissions() []string {
-	return []string{
-		"Bash(ctx status:*)",
-		"Bash(ctx agent:*)",
-		"Bash(ctx add:*)",
-		"Bash(ctx session:*)",
-		"Bash(ctx tasks:*)",
-		"Bash(ctx loop:*)",
-	}
-}
-
-// CreateDefaultHooks returns the default ctx hooks configuration for
-// Claude Code.
-//
-// The returned hooks configure PreToolUse to block non-PATH ctx
-// invocations and auto-load context on every tool use, and SessionEnd
-// to run auto-save-session.sh for persisting session transcripts.
-//
-// Parameters:
-//   - projectDir: Project root directory for absolute hook paths; if empty,
-//     paths are relative (e.g., ".claude/hooks/")
-//
-// Returns:
-//   - HookConfig: Configured hooks for PreToolUse and SessionEnd events
-func CreateDefaultHooks(projectDir string) HookConfig {
-	hooksDir := ".claude/hooks"
-	if projectDir != "" {
-		hooksDir = fmt.Sprintf("%s/.claude/hooks", projectDir)
-	}
-
-	return HookConfig{
-		PreToolUse: []HookMatcher{
-			{
-				// Block non-PATH ctx invocations (./ctx, ./dist/ctx, go run ./cmd/ctx)
-				Matcher: "Bash",
-				Hooks: []Hook{
-					{
-						Type:    "command",
-						Command: fmt.Sprintf("%s/block-non-path-ctx.sh", hooksDir),
-					},
-				},
-			},
-			{
-				// Autoload context on every tool use
-				Matcher: ".*",
-				Hooks: []Hook{
-					{
-						Type:    "command",
-						Command: "ctx agent --budget 4000 2>/dev/null || true",
-					},
-				},
-			},
-		},
-		SessionEnd: []HookMatcher{
-			{
-				Hooks: []Hook{
-					{
-						Type:    "command",
-						Command: fmt.Sprintf("%s/auto-save-session.sh", hooksDir),
-					},
-				},
-			},
-		},
-	}
-}
diff --git a/internal/claude/hook.go b/internal/claude/hook.go
new file mode 100644
index 000000000..237e66e42
--- /dev/null
+++ b/internal/claude/hook.go
@@ -0,0 +1,77 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package claude
+
+import "fmt"
+
+// DefaultHooks returns the default ctx hooks configuration for
+// Claude Code.
+//
+// The returned hooks configure PreToolUse to block non-PATH ctx
+// invocations and autoload context on every tool use, UserPromptSubmit
+// for prompt coaching, and SessionEnd to run auto-save-session.sh for
+// persisting session transcripts.
+//
+// Parameters:
+//   - projectDir: Project root directory for absolute hook paths; if empty,
+//     paths are relative (e.g., ".claude/hooks/")
+//
+// Returns:
+//   - HookConfig: Configured hooks for PreToolUse, UserPromptSubmit, and
+//     SessionEnd events
+func DefaultHooks(projectDir string) HookConfig {
+	hooksDir := ".claude/hooks"
+	if projectDir != "" {
+		hooksDir = fmt.Sprintf("%s/.claude/hooks", projectDir)
+	}
+
+	return HookConfig{
+		PreToolUse: []HookMatcher{
+			{
+				// Block non-PATH ctx invocations (./ctx, ./dist/ctx, go run ./cmd/ctx)
+				Matcher: "Bash",
+				Hooks: []Hook{
+					{
+						Type:    "command",
+						Command: fmt.Sprintf("%s/block-non-path-ctx.sh", hooksDir),
+					},
+				},
+			},
+			{
+				// Autoload context on every tool use
+				Matcher: ".*",
+				Hooks: []Hook{
+					{
+						Type:    "command",
+						Command: "ctx agent --budget 4000 2>/dev/null || true",
+					},
+				},
+			},
+		},
+		UserPromptSubmit: []HookMatcher{
+			{
+				// Prompt coaching: detect anti-patterns and suggest improvements
+				Hooks: []Hook{
+					{
+						Type:    "command",
+						Command: fmt.Sprintf("%s/prompt-coach.sh", hooksDir),
+					},
+				},
+			},
+		},
+		SessionEnd: []HookMatcher{
+			{
+				Hooks: []Hook{
+					{
+						Type:    "command",
+						Command: fmt.Sprintf("%s/auto-save-session.sh", hooksDir),
+					},
+				},
+			},
+		},
+	}
+}
diff --git a/internal/claude/perm.go b/internal/claude/perm.go
new file mode 100644
index 000000000..f034f8010
--- /dev/null
+++ b/internal/claude/perm.go
@@ -0,0 +1,25 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package claude
+
+// DefaultPermissions returns the default permissions for ctx commands.
+//
+// These permissions allow Claude Code to run ctx CLI commands without
+// prompting for approval. All ctx subcommands are pre-approved.
+//
+// Returns:
+//   - []string: List of permission patterns for ctx commands
+func DefaultPermissions() []string {
+	return []string{
+		"Bash(ctx status:*)",
+		"Bash(ctx agent:*)",
+		"Bash(ctx add:*)",
+		"Bash(ctx session:*)",
+		"Bash(ctx tasks:*)",
+		"Bash(ctx loop:*)",
+	}
+}
diff --git a/internal/claude/script.go b/internal/claude/script.go
new file mode 100644
index 000000000..e1a51d760
--- /dev/null
+++ b/internal/claude/script.go
@@ -0,0 +1,65 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package claude
+
+import (
+	"fmt"
+
+	"github.com/ActiveMemory/ctx/internal/templates"
+)
+
+// AutoSaveScript returns the auto-save session script content.
+//
+// The script automatically saves Claude Code session transcripts when a
+// session ends. It is installed to .claude/hooks/ during ctx init --claude.
+//
+// Returns:
+//   - []byte: Raw bytes of the auto-save-session.sh script
+//   - error: Non-nil if the embedded file cannot be read
+func AutoSaveScript() ([]byte, error) {
+	content, err := templates.ClaudeHookByFileName("auto-save-session.sh")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read auto-save-session.sh: %w", err)
+	}
+	return content, nil
+}
+
+// BlockNonPathCtxScript returns the script that blocks non-PATH ctx
+// invocations.
+//
+// The script prevents Claude from running ctx via relative paths (./ctx,
+// ./dist/ctx) or "go run", ensuring only the installed PATH version is used.
+// It is installed to .claude/hooks/ during ctx init --claude.
+//
+// Returns:
+//   - []byte: Raw bytes of the block-non-path-ctx.sh script
+//   - error: Non-nil if the embedded file cannot be read
+func BlockNonPathCtxScript() ([]byte, error) {
+	content, err := templates.ClaudeHookByFileName("block-non-path-ctx.sh")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read block-non-path-ctx.sh: %w", err)
+	}
+	return content, nil
+}
+
+// PromptCoachScript returns the prompt coaching hook script.
+//
+// The script detects prompt anti-patterns (e.g., "idiomatic Go") and suggests
+// better alternatives (e.g., "follow project conventions"). It limits
+// suggestions to 3 per pattern per session to avoid annoying the user.
+// It is installed to .claude/hooks/ during ctx init --claude.
+//
+// Returns:
+//   - []byte: Raw bytes of the prompt-coach.sh script
+//   - error: Non-nil if the embedded file cannot be read
+func PromptCoachScript() ([]byte, error) {
+	content, err := templates.ClaudeHookByFileName("prompt-coach.sh")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read prompt-coach.sh: %w", err)
+	}
+	return content, nil
+}
diff --git a/internal/claude/types.go b/internal/claude/types.go
index 3b6eda0d8..083e6a4b4 100644
--- a/internal/claude/types.go
+++ b/internal/claude/types.go
@@ -14,10 +14,12 @@ package claude
 //
 // Fields:
 //   - PreToolUse: Matchers that run before each tool invocation
+//   - UserPromptSubmit: Matchers that run when the user submits a prompt
 //   - SessionEnd: Matchers that run when a session ends
 type HookConfig struct {
-	PreToolUse  []HookMatcher `json:"PreToolUse,omitempty"`
-	SessionEnd  []HookMatcher `json:"SessionEnd,omitempty"`
+	PreToolUse       []HookMatcher `json:"PreToolUse,omitempty"`
+	UserPromptSubmit []HookMatcher `json:"UserPromptSubmit,omitempty"`
+	SessionEnd       []HookMatcher `json:"SessionEnd,omitempty"`
 }
 
 // HookMatcher associates a regex pattern with hooks to execute.
@@ -47,7 +49,8 @@ type Hook struct {
 // settings.local.json.
 //
 // Fields:
-//   - Allow: List of tool patterns that are pre-approved (e.g., "Bash(ctx status:*)")
+//   - Allow: List of tool patterns that are pre-approved
+//     (e.g., "Bash(ctx status:*)")
 type PermissionsConfig struct {
 	Allow []string `json:"allow,omitempty"`
 }
diff --git a/internal/cli/add/add.go b/internal/cli/add/add.go
index b8e39ca9a..372722132 100644
--- a/internal/cli/add/add.go
+++ b/internal/cli/add/add.go
@@ -69,7 +69,7 @@ Examples:
   ctx add task "Implement user authentication" --priority high`,
 		Args: cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runAdd(cmd, args, addFlags{
+			return runAdd(cmd, args, addConfig{
 				priority:     priority,
 				section:      section,
 				fromFile:     fromFile,
@@ -125,25 +125,3 @@ Examples:
 
 	return cmd
 }
-
-// addFlags holds all flags for the add command.
-//
-// Fields:
-//   - priority: Priority level for tasks (high, medium, low)
-//   - section: Target section in TASKS.md
-//   - fromFile: Read content from file instead of argument
-//   - context: Context field for decisions/learnings
-//   - rationale: Rationale field for decisions
-//   - consequences: Consequences field for decisions
-//   - lesson: Lesson field for learnings
-//   - application: Application field for learnings
-type addFlags struct {
-	priority     string
-	section      string
-	fromFile     string
-	context      string
-	rationale    string
-	consequences string
-	lesson       string
-	application  string
-}
diff --git a/internal/cli/add/add_test.go b/internal/cli/add/add_test.go
index ea01400fb..ab6be8ce4 100644
--- a/internal/cli/add/add_test.go
+++ b/internal/cli/add/add_test.go
@@ -312,9 +312,9 @@ func TestAppendEntry(t *testing.T) {
 	})
 
 	t.Run("learning prepends after separator", func(t *testing.T) {
-		// Use timestamp format "- **[" to match what FormatLearning produces
-		existing := []byte("# Learnings\n\n<!-- comment -->\n\n- **[2026-01-01]** Old Learning\n")
-		entry := "- **[2026-01-02]** New Learning\n"
+		// Use section format "## [" to match what FormatLearning produces
+		existing := []byte("# Learnings\n\n<!-- comment -->\n\n## [2026-01-01] Old Learning\n\nContent\n")
+		entry := "## [2026-01-02] New Learning\n\nContent\n"
 
 		result := AppendEntry(existing, entry, "learning", "")
 
@@ -361,7 +361,7 @@ func TestAppendEntry(t *testing.T) {
 
 	t.Run("learning on empty file", func(t *testing.T) {
 		existing := []byte("# Learnings\n\n<!-- Add gotchas here -->\n")
-		entry := "- **[2026-01-01]** First Learning\n"
+		entry := "## [2026-01-01] First Learning\n\nContent\n"
 
 		result := AppendEntry(existing, entry, "learning", "")
 
diff --git a/internal/cli/add/append.go b/internal/cli/add/append.go
index 134c34225..094c82833 100644
--- a/internal/cli/add/append.go
+++ b/internal/cli/add/append.go
@@ -6,14 +6,13 @@
 
 package add
 
-import "strings"
+import "github.com/ActiveMemory/ctx/internal/config"
 
 // AppendEntry inserts a formatted entry into existing file content.
 //
-// For task entries, the function locates the target section header and inserts
-// the entry immediately after it. For decisions and learnings, entries are
-// prepended (inserted after the header section) for reverse-chronological order.
-// For conventions, entries are appended to the end of the file.
+// For tasks, inserts after the target section header. For decisions and
+// learnings, inserts before existing entries (reverse-chronological order).
+// For conventions, appends to the end of the file.
 //
 // Parameters:
 //   - existing: Current file content as bytes
@@ -29,158 +28,18 @@ func AppendEntry(
 ) []byte {
 	existingStr := string(existing)
 
+	switch {
 	// For tasks, find the appropriate section
-	if fileType == "task" || fileType == "tasks" {
-		targetSection := section
-		if targetSection == "" {
-			targetSection = "## Next Up"
-		} else if !strings.HasPrefix(targetSection, "##") {
-			targetSection = "## " + targetSection
-		}
-
-		// Find the section and insert after it
-		idx := strings.Index(existingStr, targetSection)
-		if idx != -1 {
-			// Find the end of the section header line
-			lineEnd := strings.Index(existingStr[idx:], "\n")
-			if lineEnd != -1 {
-				insertPoint := idx + lineEnd + 1
-				return []byte(existingStr[:insertPoint] + "\n" +
-					entry + existingStr[insertPoint:])
-			}
-		}
-	}
-
-	// For decisions, prepend after the "# Decisions" header for reverse-chronological order
-	if fileType == "decision" || fileType == "decisions" {
-		return prependAfterHeader(existingStr, entry, "# Decisions")
-	}
-
-	// For learnings, prepend after the header section (after the first "---")
-	if fileType == "learning" || fileType == "learnings" {
-		return prependAfterSeparator(existingStr, entry)
-	}
-
-	// Default (conventions): append at the end
-	if !strings.HasSuffix(existingStr, "\n") {
-		existingStr += "\n"
-	}
-	return []byte(existingStr + "\n" + entry)
-}
-
-// prependAfterHeader inserts an entry after a header line.
-//
-// Used for DECISIONS.md to maintain reverse-chronological order.
-// Entries are inserted before any existing entries (identified by "## [").
-//
-// Parameters:
-//   - content: Existing file content
-//   - entry: Formatted entry to insert
-//   - header: Header line to insert after (e.g., "# Decisions")
-//
-// Returns:
-//   - []byte: Modified content with entry inserted
-func prependAfterHeader(content, entry, header string) []byte {
-	// Find the first entry marker "## [" (timestamp-prefixed sections)
-	entryIdx := strings.Index(content, "## [")
-	if entryIdx != -1 {
-		// Insert before the first entry, with separator after
-		return []byte(content[:entryIdx] + entry + "\n---\n\n" + content[entryIdx:])
-	}
-
-	// No existing entries - find header and insert after it
-	idx := strings.Index(content, header)
-	if idx != -1 {
-		lineEnd := strings.Index(content[idx:], "\n")
-		if lineEnd != -1 {
-			insertPoint := idx + lineEnd + 1
-			// Skip blank lines and comments
-			for insertPoint < len(content) {
-				if content[insertPoint] == '\n' {
-					insertPoint++
-				} else if insertPoint+4 < len(content) && content[insertPoint:insertPoint+4] == "<!--" {
-					// Skip HTML comment
-					endComment := strings.Index(content[insertPoint:], "-->")
-					if endComment != -1 {
-						insertPoint += endComment + 3
-						// Skip trailing whitespace after comment
-						for insertPoint < len(content) && (content[insertPoint] == '\n' || content[insertPoint] == ' ') {
-							insertPoint++
-						}
-					} else {
-						break
-					}
-				} else {
-					break
-				}
-			}
-			return []byte(content[:insertPoint] + entry)
-		}
-	}
-
-	// Fallback: append at the end
-	if !strings.HasSuffix(content, "\n") {
-		content += "\n"
-	}
-	return []byte(content + "\n" + entry)
-}
-
-// prependAfterSeparator inserts an entry for learnings.
-//
-// Entries are inserted before any existing entries (identified by "- **[").
-//
-// Parameters:
-//   - content: Existing file content
-//   - entry: Formatted entry to insert
-//
-// Returns:
-//   - []byte: Modified content with entry inserted
-func prependAfterSeparator(content, entry string) []byte {
-	// Find the first entry marker "- **[" (timestamp-prefixed list items)
-	entryIdx := strings.Index(content, "- **[")
-	if entryIdx != -1 {
-		// Insert before the first entry
-		return []byte(content[:entryIdx] + entry + "\n" + content[entryIdx:])
-	}
-
-	// Also check for section-style learnings "## ["
-	if entryIdx = strings.Index(content, "## ["); entryIdx != -1 {
-		return []byte(content[:entryIdx] + entry + "\n---\n\n" + content[entryIdx:])
-	}
-
-	// No existing entries - find header and insert after it
-	idx := strings.Index(content, "# Learnings")
-	if idx != -1 {
-		lineEnd := strings.Index(content[idx:], "\n")
-		if lineEnd != -1 {
-			insertPoint := idx + lineEnd + 1
-			// Skip blank lines and comments
-			for insertPoint < len(content) {
-				if content[insertPoint] == '\n' {
-					insertPoint++
-				} else if insertPoint+4 < len(content) && content[insertPoint:insertPoint+4] == "<!--" {
-					// Skip HTML comment
-					endComment := strings.Index(content[insertPoint:], "-->")
-					if endComment != -1 {
-						insertPoint += endComment + 3
-						// Skip trailing whitespace after comment
-						for insertPoint < len(content) && (content[insertPoint] == '\n' || content[insertPoint] == ' ') {
-							insertPoint++
-						}
-					} else {
-						break
-					}
-				} else {
-					break
-				}
-			}
-			return []byte(content[:insertPoint] + entry)
-		}
-	}
-
-	// Final fallback: append at the end
-	if !strings.HasSuffix(content, "\n") {
-		content += "\n"
+	case fileTypeIsTask(fileType):
+		return insertTask(entry, existingStr, section)
+	// Decisions: insert before existing entries for reverse-chronological order
+	case fileTypeIsDecision(fileType):
+		return insertDecision(existingStr, entry, config.HeadingDecisions)
+	// Learnings: insert before existing entries for reverse-chronological order
+	case fileTypeIsLearning(fileType):
+		return insertLearning(existingStr, entry)
+	default:
+		// Default (conventions): append at the end
+		return appendAtEnd(existingStr, entry)
 	}
-	return []byte(content + "\n" + entry)
 }
diff --git a/internal/cli/add/config.go b/internal/cli/add/config.go
new file mode 100644
index 000000000..da6ed043b
--- /dev/null
+++ b/internal/cli/add/config.go
@@ -0,0 +1,29 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package add
+
+// addConfig holds all flags for the add command.
+//
+// Fields:
+//   - priority: Priority level for tasks (high, medium, low)
+//   - section: Target section in TASKS.md
+//   - fromFile: Read content from file instead of argument
+//   - context: Context field for decisions/learnings
+//   - rationale: Rationale field for decisions
+//   - consequences: Consequences field for decisions
+//   - lesson: Lesson field for learnings
+//   - application: Application field for learnings
+type addConfig struct {
+	priority     string
+	section      string
+	fromFile     string
+	context      string
+	rationale    string
+	consequences string
+	lesson       string
+	application  string
+}
diff --git a/internal/cli/add/content.go b/internal/cli/add/content.go
new file mode 100644
index 000000000..1adbc0965
--- /dev/null
+++ b/internal/cli/add/content.go
@@ -0,0 +1,48 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package add
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+)
+
+func extractContent(args []string, flags addConfig) (string, error) {
+	if flags.fromFile != "" {
+		// Read from the file
+		fileContent, err := os.ReadFile(flags.fromFile)
+		if err != nil {
+			return "", fmt.Errorf("failed to read file %s: %w", flags.fromFile, err)
+		}
+		return strings.TrimSpace(string(fileContent)), nil
+	}
+
+	if len(args) > 1 {
+		// Content from arguments
+		return strings.Join(args[1:], " "), nil
+	}
+
+	// Try reading from stdin (check if it's a pipe)
+	stat, _ := os.Stdin.Stat()
+	if (stat.Mode() & os.ModeCharDevice) == 0 {
+		// stdin is a pipe, read from it
+		scanner := bufio.NewScanner(os.Stdin)
+		var lines []string
+		for scanner.Scan() {
+			lines = append(lines, scanner.Text())
+		}
+		if err := scanner.Err(); err != nil {
+			return "", fmt.Errorf("failed to read from stdin: %w", err)
+		}
+		return strings.TrimSpace(strings.Join(lines, config.NewlineLF)), nil
+	}
+	return "", fmt.Errorf("no content provided")
+}
diff --git a/internal/cli/add/err.go b/internal/cli/add/err.go
new file mode 100644
index 000000000..f14ada664
--- /dev/null
+++ b/internal/cli/add/err.go
@@ -0,0 +1,84 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package add
+
+import (
+	"fmt"
+	"strings"
+)
+
+// errMissingDecision returns an error with usage help for incomplete decisions.
+//
+// Parameters:
+//   - missing: List of missing required flag names (e.g., "--context")
+//
+// Returns:
+//   - error: Formatted error with ADR format requirements and example
+func errMissingDecision(missing []string) error {
+	return fmt.Errorf(`decisions require complete ADR format
+
+Missing required flags: %s
+
+Usage:
+  ctx add decision "Decision title" \
+    --context "What prompted this decision" \
+    --rationale "Why this choice over alternatives" \
+    --consequences "What changes as a result"
+
+Example:
+  ctx add decision "Use PostgreSQL for primary database" \
+    --context "Need a reliable database for production workloads" \
+    --rationale "PostgreSQL offers ACID compliance, JSON support, and team familiarity" \
+    --consequences "Team needs PostgreSQL training; must set up replication"`,
+		strings.Join(missing, ", "))
+}
+
+// errMissingLearning returns an error with usage help for incomplete learnings.
+//
+// Parameters:
+//   - missing: List of missing required flag names (e.g., "--lesson")
+//
+// Returns:
+//   - error: Formatted error with learning format requirements and example
+func errMissingLearning(missing []string) error {
+	return fmt.Errorf(`learnings require complete format
+
+Missing required flags: %s
+
+Usage:
+  ctx add learning "Learning title" \
+    --context "What prompted this learning" \
+    --lesson "The key insight" \
+    --application "How to apply this going forward"
+
+Example:
+  ctx add learning "Go embed requires files in same package" \
+    --context "Tried to embed files from parent directory, got compile error" \
+    --lesson "go:embed only works with files in same or child directories" \
+    --application "Keep embedded files in internal/templates/, not project root"`,
+		strings.Join(missing, ", "))
+}
+
+// errNoContentProvided returns an error with usage help when content is missing.
+//
+// Parameters:
+//   - fType: Entry type (e.g., "decision", "task") for contextual examples
+//
+// Returns:
+//   - error: Formatted error showing input methods and type-specific examples
+func errNoContentProvided(fType string) error {
+	examples := examplesForType(fType)
+	return fmt.Errorf(`no content provided
+
+Usage:
+  ctx add %s "your content here"
+  ctx add %s --file /path/to/content.md
+  echo "content" | ctx add %s
+
+Examples:
+%s`, fType, fType, fType, examples)
+}
diff --git a/internal/cli/add/example.go b/internal/cli/add/example.go
index 2ddf6ddc0..ffb77a65f 100644
--- a/internal/cli/add/example.go
+++ b/internal/cli/add/example.go
@@ -8,7 +8,7 @@ package add
 
 import "github.com/ActiveMemory/ctx/internal/config"
 
-// getExamplesForType returns example usage strings for a given entry type.
+// examplesForType returns example usage strings for a given entry type.
 //
 // The examples are displayed in error messages when content is missing,
 // helping users understand the correct command syntax.
@@ -19,20 +19,20 @@ import "github.com/ActiveMemory/ctx/internal/config"
 // Returns:
 //   - string: Formatted example commands; returns a generic example for
 //     unrecognized types
-func getExamplesForType(fileType string) string {
-	switch fileType {
-	case config.UpdateTypeDecision, config.UpdateTypeDecisions:
+func examplesForType(fileType string) string {
+	switch config.UserInputToEntry(fileType) {
+	case config.EntryDecision:
 		return `  ctx add decision "Use PostgreSQL for primary database"
   ctx add decision "Adopt Go 1.22 for range-over-func support"`
-	case config.UpdateTypeTask, config.UpdateTypeTasks:
+	case config.EntryTask:
 		return `  ctx add task "Implement user authentication"
   ctx add task "Fix login bug" --priority high`
-	case config.UpdateTypeLearning, config.UpdateTypeLearnings:
+	case config.EntryLearning:
 		return `  ctx add learning "Go embed requires files in same package" \
     --context "Tried to embed files from parent directory" \
     --lesson "go:embed only works with files in same or child directories" \
     --application "Keep embedded files in internal/templates/"`
-	case config.UpdateTypeConvention, config.UpdateTypeConventions:
+	case config.EntryConvention:
 		return `  ctx add convention "Use camelCase for function names"
   ctx add convention "All API responses use JSON"`
 	default:
diff --git a/internal/cli/add/format.go b/internal/cli/add/fmt.go
similarity index 100%
rename from internal/cli/add/format.go
rename to internal/cli/add/fmt.go
diff --git a/internal/cli/add/index.go b/internal/cli/add/index.go
index 6976771f0..e67222835 100644
--- a/internal/cli/add/index.go
+++ b/internal/cli/add/index.go
@@ -6,39 +6,24 @@
 
 package add
 
-import (
-	"regexp"
-	"strings"
-)
+// This file contains backward-compatible aliases for index operations
+// that delegate to the internal/index package.
 
-// Index markers used in context files
-const (
-	IndexStart = "<!-- INDEX:START -->"
-	IndexEnd   = "<!-- INDEX:END -->"
+import (
+	"github.com/ActiveMemory/ctx/internal/index"
 )
 
 // IndexEntry represents a parsed entry header from a context file.
 //
-// Fields:
-//   - Timestamp: Full timestamp (YYYY-MM-DD-HHMMSS)
-//   - Date: Date only (YYYY-MM-DD)
-//   - Title: Entry title
-type IndexEntry struct {
-	Timestamp string
-	Date      string
-	Title     string
-}
+// This is an alias for index.Entry for backward compatibility.
+type IndexEntry = index.Entry
 
-// DecisionEntry is an alias for backward compatibility.
-type DecisionEntry = IndexEntry
-
-// entryHeaderRegex matches headers like "## [2026-01-28-051426] Title here"
-var entryHeaderRegex = regexp.MustCompile(`## \[(\d{4}-\d{2}-\d{2})-(\d{6})\] (.+)`)
+// DecisionEntry is an alias for IndexEntry for backward compatibility.
+type DecisionEntry = index.Entry
 
 // ParseEntryHeaders extracts all entries from file content.
 //
-// It scans for headers matching the pattern "## [YYYY-MM-DD-HHMMSS] Title"
-// and returns them in the order they appear in the file.
+// Delegates to index.ParseHeaders.
 //
 // Parameters:
 //   - content: The full content of a context file
@@ -46,40 +31,25 @@ var entryHeaderRegex = regexp.MustCompile(`## \[(\d{4}-\d{2}-\d{2})-(\d{6})\] (.
 // Returns:
 //   - []IndexEntry: Slice of parsed entries (may be empty)
 func ParseEntryHeaders(content string) []IndexEntry {
-	var entries []IndexEntry
-
-	matches := entryHeaderRegex.FindAllStringSubmatch(content, -1)
-	for _, match := range matches {
-		if len(match) == 4 {
-			date := match[1]
-			time := match[2]
-			title := match[3]
-			entries = append(entries, IndexEntry{
-				Timestamp: date + "-" + time,
-				Date:      date,
-				Title:     title,
-			})
-		}
-	}
-
-	return entries
+	return index.ParseHeaders(content)
 }
 
-// ParseDecisionHeaders is an alias for ParseEntryHeaders for backward compatibility.
+// ParseDecisionHeaders extracts all entries from file content.
+//
+// This is an alias for ParseEntryHeaders for backward compatibility.
 //
 // Parameters:
 //   - content: The full content of a context file
 //
 // Returns:
-//   - []DecisionEntry: Slice of parsed entries (may be empty)
+//   - []DecisionEntry: Slice of parsed entries (it may be empty)
 func ParseDecisionHeaders(content string) []DecisionEntry {
-	return ParseEntryHeaders(content)
+	return index.ParseHeaders(content)
 }
 
-// GenerateIndexTable creates a markdown table index from entries.
+// GenerateIndexTable creates a Markdown table index from entries.
 //
-// The table has two columns: Date and the specified column header.
-// If there are no entries, returns an empty string.
+// Delegates to index.GenerateTable.
 //
 // Parameters:
 //   - entries: Slice of entries to include
@@ -88,32 +58,12 @@ func ParseDecisionHeaders(content string) []DecisionEntry {
 // Returns:
 //   - string: Markdown table (without markers) or empty string
 func GenerateIndexTable(entries []IndexEntry, columnHeader string) string {
-	if len(entries) == 0 {
-		return ""
-	}
-
-	var sb strings.Builder
-	sb.WriteString("| Date | ")
-	sb.WriteString(columnHeader)
-	sb.WriteString(" |\n")
-	sb.WriteString("|------|")
-	sb.WriteString(strings.Repeat("-", len(columnHeader)))
-	sb.WriteString("|\n")
-
-	for _, e := range entries {
-		// Escape pipe characters in title
-		title := strings.ReplaceAll(e.Title, "|", "\\|")
-		sb.WriteString("| ")
-		sb.WriteString(e.Date)
-		sb.WriteString(" | ")
-		sb.WriteString(title)
-		sb.WriteString(" |\n")
-	}
-
-	return sb.String()
+	return index.GenerateTable(entries, columnHeader)
 }
 
-// GenerateIndex creates a markdown table for decisions (backward compatibility).
+// GenerateIndex creates a Markdown table for decisions.
+//
+// This is a convenience wrapper for backward compatibility.
 //
 // Parameters:
 //   - entries: Slice of decision entries to include
@@ -121,101 +71,31 @@ func GenerateIndexTable(entries []IndexEntry, columnHeader string) string {
 // Returns:
 //   - string: Markdown table or empty string if no entries
 func GenerateIndex(entries []DecisionEntry) string {
-	return GenerateIndexTable(entries, "Decision")
-}
-
-// updateFileIndex regenerates the index in file content.
-//
-// If INDEX:START and INDEX:END markers exist, the content between them
-// is replaced. Otherwise, the index is inserted after the specified header.
-// If there are no entries, any existing index is removed.
-//
-// Parameters:
-//   - content: The full content of the file
-//   - fileHeader: The main header to insert after (e.g., "# Decisions")
-//   - columnHeader: Header for the table column (e.g., "Decision")
-//
-// Returns:
-//   - string: Updated content with regenerated index
-func updateFileIndex(content, fileHeader, columnHeader string) string {
-	entries := ParseEntryHeaders(content)
-	indexContent := GenerateIndexTable(entries, columnHeader)
-
-	// Check if markers already exist
-	startIdx := strings.Index(content, IndexStart)
-	endIdx := strings.Index(content, IndexEnd)
-
-	if startIdx != -1 && endIdx != -1 && endIdx > startIdx {
-		// Replace existing index
-		if indexContent == "" {
-			// No entries - remove index entirely (including markers and surrounding whitespace)
-			before := strings.TrimRight(content[:startIdx], "\n")
-			after := content[endIdx+len(IndexEnd):]
-			after = strings.TrimLeft(after, "\n")
-			if after != "" {
-				return before + "\n\n" + after
-			}
-			return before + "\n"
-		}
-		// Replace content between markers
-		before := content[:startIdx+len(IndexStart)]
-		after := content[endIdx:]
-		return before + "\n" + indexContent + after
-	}
-
-	// No existing markers - insert after file header
-	if indexContent == "" {
-		// No entries, nothing to insert
-		return content
-	}
-
-	headerIdx := strings.Index(content, fileHeader)
-	if headerIdx == -1 {
-		// No header found, return unchanged
-		return content
-	}
-
-	// Find end of header line
-	lineEnd := strings.Index(content[headerIdx:], "\n")
-	if lineEnd == -1 {
-		// Header is at end of file
-		return content + "\n\n" + IndexStart + "\n" + indexContent + IndexEnd + "\n"
-	}
-
-	insertPoint := headerIdx + lineEnd + 1
-
-	// Build new content with index
-	var sb strings.Builder
-	sb.WriteString(content[:insertPoint])
-	sb.WriteString("\n")
-	sb.WriteString(IndexStart)
-	sb.WriteString("\n")
-	sb.WriteString(indexContent)
-	sb.WriteString(IndexEnd)
-	sb.WriteString("\n")
-	sb.WriteString(content[insertPoint:])
-
-	return sb.String()
+	return index.GenerateTable(entries, "Decision")
 }
 
 // UpdateIndex regenerates the decision index in DECISIONS.md content.
 //
+// Delegates to index.UpdateDecisions.
+//
 // Parameters:
 //   - content: The full content of DECISIONS.md
 //
 // Returns:
 //   - string: Updated content with regenerated index
 func UpdateIndex(content string) string {
-	return updateFileIndex(content, "# Decisions", "Decision")
+	return index.UpdateDecisions(content)
 }
 
 // UpdateLearningsIndex regenerates the learning index in LEARNINGS.md content.
 //
+// Delegates to index.UpdateLearnings.
+//
 // Parameters:
 //   - content: The full content of LEARNINGS.md
 //
 // Returns:
 //   - string: Updated content with regenerated index
 func UpdateLearningsIndex(content string) string {
-	return updateFileIndex(content, "# Learnings", "Learning")
+	return index.UpdateLearnings(content)
 }
diff --git a/internal/cli/add/index_test.go b/internal/cli/add/index_test.go
index 5796c8c78..7d423e680 100644
--- a/internal/cli/add/index_test.go
+++ b/internal/cli/add/index_test.go
@@ -9,399 +9,55 @@ package add
 import (
 	"strings"
 	"testing"
-)
-
-func TestParseDecisionHeaders(t *testing.T) {
-	tests := []struct {
-		name     string
-		content  string
-		expected []DecisionEntry
-	}{
-		{
-			name:     "empty content",
-			content:  "",
-			expected: nil,
-		},
-		{
-			name:     "no decisions",
-			content:  "# Decisions\n\nSome text here.",
-			expected: nil,
-		},
-		{
-			name: "single decision",
-			content: `# Decisions
-
-## [2026-01-28-051426] No custom UI - IDE is the interface
-
-**Status**: Accepted
-`,
-			expected: []DecisionEntry{
-				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "No custom UI - IDE is the interface"},
-			},
-		},
-		{
-			name: "multiple decisions",
-			content: `# Decisions
-
-## [2026-01-28-051426] First decision
-
-**Status**: Accepted
-
----
-
-## [2026-01-27-123456] Second decision
-
-**Status**: Accepted
-`,
-			expected: []DecisionEntry{
-				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "First decision"},
-				{Timestamp: "2026-01-27-123456", Date: "2026-01-27", Title: "Second decision"},
-			},
-		},
-		{
-			name: "decision with special characters",
-			content: `# Decisions
-
-## [2026-01-28-051426] Use tool-agnostic Session type | with pipe
-
-**Status**: Accepted
-`,
-			expected: []DecisionEntry{
-				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "Use tool-agnostic Session type | with pipe"},
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := ParseDecisionHeaders(tt.content)
-			if len(got) != len(tt.expected) {
-				t.Errorf("ParseDecisionHeaders() got %d entries, want %d", len(got), len(tt.expected))
-				return
-			}
-			for i, entry := range got {
-				if entry.Timestamp != tt.expected[i].Timestamp {
-					t.Errorf("entry[%d].Timestamp = %q, want %q", i, entry.Timestamp, tt.expected[i].Timestamp)
-				}
-				if entry.Date != tt.expected[i].Date {
-					t.Errorf("entry[%d].Date = %q, want %q", i, entry.Date, tt.expected[i].Date)
-				}
-				if entry.Title != tt.expected[i].Title {
-					t.Errorf("entry[%d].Title = %q, want %q", i, entry.Title, tt.expected[i].Title)
-				}
-			}
-		})
-	}
-}
-
-func TestGenerateIndex(t *testing.T) {
-	tests := []struct {
-		name     string
-		entries  []DecisionEntry
-		expected string
-	}{
-		{
-			name:     "empty entries",
-			entries:  nil,
-			expected: "",
-		},
-		{
-			name:     "empty slice",
-			entries:  []DecisionEntry{},
-			expected: "",
-		},
-		{
-			name: "single entry",
-			entries: []DecisionEntry{
-				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "First decision"},
-			},
-			expected: `| Date | Decision |
-|------|--------|
-| 2026-01-28 | First decision |
-`,
-		},
-		{
-			name: "multiple entries",
-			entries: []DecisionEntry{
-				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "First"},
-				{Timestamp: "2026-01-27-123456", Date: "2026-01-27", Title: "Second"},
-			},
-			expected: `| Date | Decision |
-|------|--------|
-| 2026-01-28 | First |
-| 2026-01-27 | Second |
-`,
-		},
-		{
-			name: "entry with pipe character",
-			entries: []DecisionEntry{
-				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "Use A | B format"},
-			},
-			expected: `| Date | Decision |
-|------|--------|
-| 2026-01-28 | Use A \| B format |
-`,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := GenerateIndex(tt.entries)
-			if got != tt.expected {
-				t.Errorf("GenerateIndex() =\n%q\nwant\n%q", got, tt.expected)
-			}
-		})
-	}
-}
 
-func TestUpdateIndex(t *testing.T) {
-	tests := []struct {
-		name     string
-		content  string
-		wantHas  []string // strings that should be present
-		wantNot  []string // strings that should NOT be present
-	}{
-		{
-			name:    "empty file with header",
-			content: "# Decisions\n",
-			wantNot: []string{IndexStart, IndexEnd},
-		},
-		{
-			name: "file with one decision",
-			content: `# Decisions
-
-## [2026-01-28-051426] Test decision
-
-**Status**: Accepted
-`,
-			wantHas: []string{
-				IndexStart,
-				IndexEnd,
-				"| Date | Decision |",
-				"| 2026-01-28 | Test decision |",
-				"## [2026-01-28-051426] Test decision",
-			},
-		},
-		{
-			name: "update existing index",
-			content: `# Decisions
-
-<!-- INDEX:START -->
-| Date | Decision |
-|------|----------|
-| 2026-01-28 | Old entry |
-<!-- INDEX:END -->
-
-## [2026-01-28-051426] New decision
-
-**Status**: Accepted
-`,
-			wantHas: []string{
-				IndexStart,
-				IndexEnd,
-				"| 2026-01-28 | New decision |",
-			},
-			wantNot: []string{
-				"| 2026-01-28 | Old entry |",
-			},
-		},
-		{
-			name: "remove index when no decisions",
-			content: `# Decisions
-
-<!-- INDEX:START -->
-| Date | Decision |
-|------|----------|
-| 2026-01-28 | Old entry |
-<!-- INDEX:END -->
-
-Some other content.
-`,
-			wantNot: []string{
-				IndexStart,
-				IndexEnd,
-				"| Date | Decision |",
-			},
-			wantHas: []string{
-				"# Decisions",
-				"Some other content.",
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := UpdateIndex(tt.content)
-			for _, want := range tt.wantHas {
-				if !strings.Contains(got, want) {
-					t.Errorf("UpdateIndex() result missing %q\nGot:\n%s", want, got)
-				}
-			}
-			for _, notWant := range tt.wantNot {
-				if strings.Contains(got, notWant) {
-					t.Errorf("UpdateIndex() result should not contain %q\nGot:\n%s", notWant, got)
-				}
-			}
-		})
-	}
-}
+	"github.com/ActiveMemory/ctx/internal/config"
+)
 
-func TestUpdateIndex_PreservesContent(t *testing.T) {
+// TestDelegation verifies that the wrapper functions correctly delegate
+// to the internal/index package. The full logic is tested in internal/index.
+func TestDelegation(t *testing.T) {
 	content := `# Decisions
 
-## [2026-01-28-051426] First decision
-
-**Status**: Accepted
-
-**Context**: Some context here.
-
-**Decision**: The decision text.
-
-**Rationale**: Why we did it.
-
-**Consequences**: What happens next.
-
----
-
-## [2026-01-27-123456] Second decision
+## [2026-01-28-051426] Test decision
 
 **Status**: Accepted
-
-**Context**: Another context.
-
-**Decision**: Another decision.
-
-**Rationale**: Another rationale.
-
-**Consequences**: More consequences.
 `
 
-	got := UpdateIndex(content)
-
-	// Index should be present
-	if !strings.Contains(got, IndexStart) {
-		t.Error("Missing INDEX:START marker")
-	}
-	if !strings.Contains(got, IndexEnd) {
-		t.Error("Missing INDEX:END marker")
-	}
-
-	// Both entries should be in index
-	if !strings.Contains(got, "| 2026-01-28 | First decision |") {
-		t.Error("Missing first decision in index")
+	// Test ParseEntryHeaders delegation
+	entries := ParseEntryHeaders(content)
+	if len(entries) != 1 {
+		t.Errorf("ParseEntryHeaders() got %d entries, want 1", len(entries))
 	}
-	if !strings.Contains(got, "| 2026-01-27 | Second decision |") {
-		t.Error("Missing second decision in index")
+	if entries[0].Date != "2026-01-28" {
+		t.Errorf("ParseEntryHeaders() entry.Date = %q, want %q", entries[0].Date, "2026-01-28")
 	}
 
-	// Full content should be preserved
-	if !strings.Contains(got, "**Context**: Some context here.") {
-		t.Error("Lost content from first decision")
-	}
-	if !strings.Contains(got, "**Rationale**: Another rationale.") {
-		t.Error("Lost content from second decision")
+	// Test ParseDecisionHeaders alias
+	decisionEntries := ParseDecisionHeaders(content)
+	if len(decisionEntries) != 1 {
+		t.Errorf("ParseDecisionHeaders() got %d entries, want 1", len(decisionEntries))
 	}
-}
-
-func TestUpdateIndex_Idempotent(t *testing.T) {
-	content := `# Decisions
 
-## [2026-01-28-051426] Test decision
-
-**Status**: Accepted
-`
-
-	// Apply once
-	first := UpdateIndex(content)
-
-	// Apply again
-	second := UpdateIndex(first)
-
-	// Should be identical
-	if first != second {
-		t.Errorf("UpdateIndex is not idempotent\nFirst:\n%s\nSecond:\n%s", first, second)
+	// Test GenerateIndexTable delegation
+	table := GenerateIndexTable(entries, "Decision")
+	if !strings.Contains(table, "| Date | Decision |") {
+		t.Error("GenerateIndexTable() missing header")
 	}
-}
-
-func TestUpdateLearningsIndex(t *testing.T) {
-	tests := []struct {
-		name    string
-		content string
-		wantHas []string
-		wantNot []string
-	}{
-		{
-			name:    "empty file with header",
-			content: "# Learnings\n",
-			wantNot: []string{IndexStart, IndexEnd},
-		},
-		{
-			name: "file with one learning",
-			content: `# Learnings
-
-## [2026-01-28-191951] Required flags now enforced
-
-**Context**: Implemented ctx add learning flags
-
-**Lesson**: Structured entries are more useful
 
-**Application**: Always use all three flags
-`,
-			wantHas: []string{
-				IndexStart,
-				IndexEnd,
-				"| Date | Learning |",
-				"| 2026-01-28 | Required flags now enforced |",
-			},
-		},
-		{
-			name: "multiple learnings",
-			content: `# Learnings
-
-## [2026-01-28-191951] First learning
-
-**Context**: Test
-
-**Lesson**: Test
-
-**Application**: Test
-
----
-
-## [2026-01-27-120000] Second learning
-
-**Context**: Test
-
-**Lesson**: Test
-
-**Application**: Test
-`,
-			wantHas: []string{
-				"| 2026-01-28 | First learning |",
-				"| 2026-01-27 | Second learning |",
-			},
-		},
+	// Test GenerateIndex convenience function
+	indexTable := GenerateIndex(entries)
+	if !strings.Contains(indexTable, "| Date | Decision |") {
+		t.Error("GenerateIndex() missing header")
 	}
 
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := UpdateLearningsIndex(tt.content)
-			for _, want := range tt.wantHas {
-				if !strings.Contains(got, want) {
-					t.Errorf("UpdateLearningsIndex() result missing %q\nGot:\n%s", want, got)
-				}
-			}
-			for _, notWant := range tt.wantNot {
-				if strings.Contains(got, notWant) {
-					t.Errorf("UpdateLearningsIndex() result should not contain %q\nGot:\n%s", notWant, got)
-				}
-			}
-		})
+	// Test UpdateIndex delegation
+	updated := UpdateIndex(content)
+	if !strings.Contains(updated, config.IndexStart) {
+		t.Error("UpdateIndex() missing INDEX:START marker")
 	}
-}
 
-func TestUpdateLearningsIndex_Idempotent(t *testing.T) {
-	content := `# Learnings
+	// Test UpdateLearningsIndex delegation
+	learningContent := `# Learnings
 
 ## [2026-01-28-191951] Test learning
 
@@ -411,28 +67,11 @@ func TestUpdateLearningsIndex_Idempotent(t *testing.T) {
 
 **Application**: Test
 `
-
-	first := UpdateLearningsIndex(content)
-	second := UpdateLearningsIndex(first)
-
-	if first != second {
-		t.Errorf("UpdateLearningsIndex is not idempotent\nFirst:\n%s\nSecond:\n%s", first, second)
+	updatedLearning := UpdateLearningsIndex(learningContent)
+	if !strings.Contains(updatedLearning, config.IndexStart) {
+		t.Error("UpdateLearningsIndex() missing INDEX:START marker")
 	}
-}
-
-func TestGenerateIndexTable(t *testing.T) {
-	entries := []IndexEntry{
-		{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "Test entry"},
-	}
-
-	// Test with different column headers
-	decisionTable := GenerateIndexTable(entries, "Decision")
-	if !strings.Contains(decisionTable, "| Date | Decision |") {
-		t.Error("Decision table should have 'Decision' column header")
-	}
-
-	learningTable := GenerateIndexTable(entries, "Learning")
-	if !strings.Contains(learningTable, "| Date | Learning |") {
-		t.Error("Learning table should have 'Learning' column header")
+	if !strings.Contains(updatedLearning, "| Date | Learning |") {
+		t.Error("UpdateLearningsIndex() missing Learning column header")
 	}
 }
diff --git a/internal/cli/add/insert.go b/internal/cli/add/insert.go
new file mode 100644
index 000000000..3f46c84bb
--- /dev/null
+++ b/internal/cli/add/insert.go
@@ -0,0 +1,178 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package add
+
+import (
+	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+)
+
+// insertAfterHeader finds a header line and inserts content after it.
+//
+// Skips blank lines and ctx markers between the header and insertion point.
+// Falls back to appending at the end if the header is not found.
+//
+// Parameters:
+//   - content: Existing file content
+//   - entry: Formatted entry to insert
+//   - header: Header line to find (e.g., "# Learnings")
+//
+// Returns:
+//   - []byte: Modified content with entry inserted
+func insertAfterHeader(content, entry, header string) []byte {
+	hasHeader, idx := contains(content, header)
+	if !hasHeader {
+		return appendAtEnd(content, entry)
+	}
+
+	hasNewLine, lineEnd := containsNewLine(content[idx:])
+	if !hasNewLine {
+		// Header exists but no newline after (the file ends with a header line)
+		return appendAtEnd(content, entry)
+	}
+
+	insertPoint := idx + lineEnd
+	insertPoint = skipNewline(content, insertPoint)
+
+	// Skip blank lines and ctx markers
+	for insertPoint < len(content) {
+		if n := skipNewline(content, insertPoint); n > insertPoint {
+			insertPoint = n
+			continue
+		}
+
+		// No context marker: we found the insertion point.
+		if !startsWithCtxMarker(content[insertPoint:]) {
+			break
+		}
+
+		// Skip past the closing marker
+		hasCommentEnd, endIdx := containsEndComment(content[insertPoint:])
+		if !hasCommentEnd {
+			break
+		}
+
+		insertPoint += endIdx + len(config.CommentClose)
+		insertPoint = skipWhitespace(content, insertPoint)
+	}
+
+	return []byte(content[:insertPoint] + entry)
+}
+
+// appendAtEnd appends an entry at the end of content.
+//
+// Ensures proper newline separation between existing content and the new entry.
+//
+// Parameters:
+//   - content: Existing file content
+//   - entry: Formatted entry to append
+//
+// Returns:
+//   - []byte: Content with entry appended
+func appendAtEnd(content, entry string) []byte {
+	if !endsWithNewline(content) {
+		content += config.NewlineLF
+	}
+	return []byte(content + config.NewlineLF + entry)
+}
+
+// insertTask inserts a task entry after a section header in TASKS.md.
+//
+// Finds the target section (e.g., "## Next Up") and inserts the task
+// immediately after the header line. Falls back to appending at the end
+// if the section is not found.
+//
+// Parameters:
+//   - existingStr: Existing file content
+//   - entry: Formatted task entry to insert
+//   - headerSection: Target section name (e.g., "next", "backlog")
+//
+// Returns:
+//   - []byte: Modified content with task inserted
+func insertTask(existingStr, entry, headerSection string) []byte {
+	targetSectionHeader := normalizeTargetSection(headerSection)
+
+	// Find the section and insert after it
+	containsSectionHeader, idx := contains(existingStr, targetSectionHeader)
+	if !containsSectionHeader {
+		// Section not found: Append at the end.
+		if !endsWithNewline(existingStr) {
+			existingStr += config.NewlineLF
+		}
+		return []byte(existingStr + config.NewlineLF + entry)
+	}
+
+	// Found section header. Find the end of the section header line
+	hasNewLine, lineEnd := containsNewLine(existingStr[idx:])
+	if hasNewLine {
+		insertPoint := idx + lineEnd
+		insertPoint = skipNewline(existingStr, insertPoint)
+		return []byte(existingStr[:insertPoint] + config.NewlineLF +
+			entry + existingStr[insertPoint:])
+	}
+
+	// If no newline; append to the end followed by a newline.
+	return []byte(existingStr + config.NewlineLF + entry)
+}
+
+// insertDecision inserts a decision entry before existing entries.
+//
+// Finds the first "## [" marker and inserts before it, maintaining
+// reverse-chronological order. Falls back to insertAfterHeader if no entries
+// exist.
+//
+// Parameters:
+//   - content: Existing file content
+//   - entry: Formatted entry to insert
+//   - header: Header line to insert after (e.g., "# Decisions")
+//
+// Returns:
+//   - []byte: Modified content with entry inserted
+func insertDecision(content, entry, header string) []byte {
+	// Find the first entry marker "## [" (timestamp-prefixed sections)
+	entryIdx := strings.Index(content, "## [")
+	if entryIdx != -1 {
+		// Insert before the first entry, with a separator after
+		return []byte(
+			content[:entryIdx] + entry +
+				config.NewlineLF + config.Separator +
+				config.NewlineLF + config.NewlineLF +
+				content[entryIdx:],
+		)
+	}
+
+	// No existing entries - find the header and insert after it
+	return insertAfterHeader(content, entry, header)
+}
+
+// insertLearning inserts a learning entry before existing entries.
+//
+// Finds the first "## [" marker and inserts before it, maintaining
+// reverse-chronological order. Falls back to insertAfterHeader if no entries
+// exist.
+//
+// Parameters:
+//   - content: Existing file content
+//   - entry: Formatted entry to insert
+//
+// Returns:
+//   - []byte: Modified content with entry inserted
+func insertLearning(content, entry string) []byte {
+	// Find the first entry marker "## [" (timestamp-prefixed sections)
+	entryIdx := strings.Index(content, config.HeadingLearningStart)
+	if entryIdx != -1 {
+		return []byte(
+			content[:entryIdx] + entry + config.NewlineLF +
+				config.Separator + config.NewlineLF + config.NewlineLF +
+				content[entryIdx:],
+		)
+	}
+
+	// No existing entries - find the header and insert after it
+	return insertAfterHeader(content, entry, config.HeadingLearnings)
+}
diff --git a/internal/cli/add/normalize.go b/internal/cli/add/normalize.go
new file mode 100644
index 000000000..5d81f344d
--- /dev/null
+++ b/internal/cli/add/normalize.go
@@ -0,0 +1,14 @@
+package add
+
+import "strings"
+
+func normalizeTargetSection(section string) string {
+	targetSection := section
+	if targetSection == "" {
+		return "## Next Up"
+	}
+	if !strings.HasPrefix(targetSection, "##") {
+		return "## " + targetSection
+	}
+	return targetSection
+}
diff --git a/internal/cli/add/pos.go b/internal/cli/add/pos.go
new file mode 100644
index 000000000..c7365edc5
--- /dev/null
+++ b/internal/cli/add/pos.go
@@ -0,0 +1,62 @@
+package add
+
+// skipNewline advances pos past a newline (CRLF or LF) if present.
+//
+// Parameters:
+//   - s: String to scan
+//   - pos: Current position in s
+//
+// Returns:
+//   - int: New position (unchanged if no newline at pos)
+func skipNewline(s string, pos int) int {
+	if pos >= len(s) {
+		return pos
+	}
+	if pos+1 < len(s) && s[pos] == '\r' && s[pos+1] == '\n' {
+		return pos + 2
+	}
+	if s[pos] == '\n' {
+		return pos + 1
+	}
+	return pos
+}
+
+// skipWhitespace advances pos past any whitespace (space, tab, newline).
+//
+// Parameters:
+//   - s: String to scan
+//   - pos: Current position in s
+//
+// Returns:
+//   - int: New position after skipping whitespace
+func skipWhitespace(s string, pos int) int {
+	for pos < len(s) {
+		if n := skipNewline(s, pos); n > pos {
+			pos = n
+		} else if s[pos] == ' ' || s[pos] == '\t' {
+			pos++
+		} else {
+			break
+		}
+	}
+	return pos
+}
+
+// findNewline returns the index of the first newline (CRLF or LF) in s.
+//
+// Parameters:
+//   - s: String to search
+//
+// Returns:
+//   - int: Index of first newline (-1 if not found)
+func findNewline(s string) int {
+	for i := 0; i < len(s); i++ {
+		if i+1 < len(s) && s[i] == '\r' && s[i+1] == '\n' {
+			return i
+		}
+		if s[i] == '\n' {
+			return i
+		}
+	}
+	return -1
+}
diff --git a/internal/cli/add/predicate.go b/internal/cli/add/predicate.go
new file mode 100644
index 000000000..9ea33bde1
--- /dev/null
+++ b/internal/cli/add/predicate.go
@@ -0,0 +1,42 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package add
+
+import "github.com/ActiveMemory/ctx/internal/config"
+
+// fileTypeIsTask reports whether fileType represents a task entry.
+//
+// Parameters:
+//   - fileType: The type string to check (e.g., "task", "tasks")
+//
+// Returns:
+//   - bool: True if fileType is a task type
+func fileTypeIsTask(fileType string) bool {
+	return config.UserInputToEntry(fileType) == config.EntryTask
+}
+
+// fileTypeIsDecision reports whether fileType represents a decision entry.
+//
+// Parameters:
+//   - fileType: The type string to check (e.g., "decision", "decisions")
+//
+// Returns:
+//   - bool: True if fileType is a decision type
+func fileTypeIsDecision(fileType string) bool {
+	return config.UserInputToEntry(fileType) == config.EntryDecision
+}
+
+// fileTypeIsLearning reports whether fileType represents a learning entry.
+//
+// Parameters:
+//   - fileType: The type string to check (e.g., "learning", "learnings")
+//
+// Returns:
+//   - bool: True if fileType is a learning type
+func fileTypeIsLearning(fileType string) bool {
+	return config.UserInputToEntry(fileType) == config.EntryLearning
+}
diff --git a/internal/cli/add/run.go b/internal/cli/add/run.go
index e159e6e80..cc8fcbdd3 100644
--- a/internal/cli/add/run.go
+++ b/internal/cli/add/run.go
@@ -7,7 +7,6 @@
 package add
 
 import (
-	"bufio"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -17,6 +16,8 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/index"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // EntryParams contains all parameters needed to add an entry to a context file.
@@ -43,7 +44,8 @@ type EntryParams struct {
 	Application  string
 }
 
-// ValidateEntry checks that required fields are present for the given entry type.
+// ValidateEntry checks that required fields are present for the given
+// entry type.
 //
 // Parameters:
 //   - params: Entry parameters to validate
@@ -51,41 +53,43 @@ type EntryParams struct {
 // Returns:
 //   - error: Non-nil with details about missing fields, nil if valid
 func ValidateEntry(params EntryParams) error {
-	fType := strings.ToLower(params.Type)
-
 	if params.Content == "" {
 		return fmt.Errorf("no content provided")
 	}
 
-	switch fType {
-	case config.UpdateTypeDecision, config.UpdateTypeDecisions:
+	switch config.UserInputToEntry(params.Type) {
+	case config.EntryDecision:
 		var missing []string
 		if params.Context == "" {
-			missing = append(missing, "context")
+			missing = append(missing, config.FieldContext)
 		}
 		if params.Rationale == "" {
-			missing = append(missing, "rationale")
+			missing = append(missing, config.FieldRationale)
 		}
 		if params.Consequences == "" {
-			missing = append(missing, "consequences")
+			missing = append(missing, config.FieldConsequence)
 		}
 		if len(missing) > 0 {
-			return fmt.Errorf("decision missing required fields: %s", strings.Join(missing, ", "))
+			return fmt.Errorf(
+				"decision missing required fields: %s", strings.Join(missing, ", "),
+			)
 		}
 
-	case config.UpdateTypeLearning, config.UpdateTypeLearnings:
+	case config.EntryLearning:
 		var missing []string
 		if params.Context == "" {
-			missing = append(missing, "context")
+			missing = append(missing, config.FieldContext)
 		}
 		if params.Lesson == "" {
-			missing = append(missing, "lesson")
+			missing = append(missing, config.FieldLesson)
 		}
 		if params.Application == "" {
-			missing = append(missing, "application")
+			missing = append(missing, config.FieldApplication)
 		}
 		if len(missing) > 0 {
-			return fmt.Errorf("learning missing required fields: %s", strings.Join(missing, ", "))
+			return fmt.Errorf(
+				"learning missing required fields: %s", strings.Join(missing, ", "),
+			)
 		}
 	}
 
@@ -101,7 +105,7 @@ func ValidateEntry(params EntryParams) error {
 //   - params: EntryParams containing type, content, and optional fields
 //
 // Returns:
-//   - error: Non-nil if type is unknown, file doesn't exist, or write fails
+//   - error: Non-nil if type is unknown, the file doesn't exist, or write fails
 func WriteEntry(params EntryParams) error {
 	fType := strings.ToLower(params.Type)
 
@@ -110,11 +114,13 @@ func WriteEntry(params EntryParams) error {
 		return fmt.Errorf("unknown type %q", fType)
 	}
 
-	filePath := filepath.Join(config.ContextDir(), fileName)
+	filePath := filepath.Join(rc.GetContextDir(), fileName)
 
-	// Check if file exists
+	// Check if the file exists
 	if _, err := os.Stat(filePath); os.IsNotExist(err) {
-		return fmt.Errorf("context file %s not found. Run 'ctx init' first", filePath)
+		return fmt.Errorf(
+			"context file %s not found. Run 'ctx init' first", filePath,
+		)
 	}
 
 	// Read existing content
@@ -125,14 +131,18 @@ func WriteEntry(params EntryParams) error {
 
 	// Format the entry
 	var entry string
-	switch fType {
-	case config.UpdateTypeDecision, config.UpdateTypeDecisions:
-		entry = FormatDecision(params.Content, params.Context, params.Rationale, params.Consequences)
-	case config.UpdateTypeTask, config.UpdateTypeTasks:
+	switch config.UserInputToEntry(fType) {
+	case config.EntryDecision:
+		entry = FormatDecision(
+			params.Content, params.Context, params.Rationale, params.Consequences,
+		)
+	case config.EntryTask:
 		entry = FormatTask(params.Content, params.Priority)
-	case config.UpdateTypeLearning, config.UpdateTypeLearnings:
-		entry = FormatLearning(params.Content, params.Context, params.Lesson, params.Application)
-	case config.UpdateTypeConvention, config.UpdateTypeConventions:
+	case config.EntryLearning:
+		entry = FormatLearning(
+			params.Content, params.Context, params.Lesson, params.Application,
+		)
+	case config.EntryConvention:
 		entry = FormatConvention(params.Content)
 	default:
 		return fmt.Errorf("unknown type %q", fType)
@@ -145,18 +155,20 @@ func WriteEntry(params EntryParams) error {
 		return fmt.Errorf("failed to write %s: %w", filePath, err)
 	}
 
-	// Update index for decisions and learnings
-	switch fType {
-	case config.UpdateTypeDecision, config.UpdateTypeDecisions:
-		indexed := UpdateIndex(string(newContent))
+	// Update index for decisions and learnings (tasks/conventions don't have indexes)
+	switch config.UserInputToEntry(fType) {
+	case config.EntryDecision:
+		indexed := index.UpdateDecisions(string(newContent))
 		if err := os.WriteFile(filePath, []byte(indexed), 0644); err != nil {
 			return fmt.Errorf("failed to update index in %s: %w", filePath, err)
 		}
-	case config.UpdateTypeLearning, config.UpdateTypeLearnings:
-		indexed := UpdateLearningsIndex(string(newContent))
+	case config.EntryLearning:
+		indexed := index.UpdateLearnings(string(newContent))
 		if err := os.WriteFile(filePath, []byte(indexed), 0644); err != nil {
 			return fmt.Errorf("failed to update index in %s: %w", filePath, err)
 		}
+	case config.EntryTask, config.EntryConvention:
+		// No index to update for these types
 	}
 
 	return nil
@@ -176,50 +188,14 @@ func WriteEntry(params EntryParams) error {
 // Returns:
 //   - error: Non-nil if content is missing, type is invalid, required flags
 //     are missing, or file operations fail
-func runAdd(cmd *cobra.Command, args []string, flags addFlags) error {
+func runAdd(cmd *cobra.Command, args []string, flags addConfig) error {
 	fType := strings.ToLower(args[0])
 
 	// Determine the content source: args, --file, or stdin
-	var content string
-
-	if flags.fromFile != "" {
-		// Read from the file
-		fileContent, err := os.ReadFile(flags.fromFile)
-		if err != nil {
-			return fmt.Errorf("failed to read file %s: %w", flags.fromFile, err)
-		}
-		content = strings.TrimSpace(string(fileContent))
-	} else if len(args) > 1 {
-		// Content from arguments
-		content = strings.Join(args[1:], " ")
-	} else {
-		// Try reading from stdin (check if it's a pipe)
-		stat, _ := os.Stdin.Stat()
-		if (stat.Mode() & os.ModeCharDevice) == 0 {
-			// stdin is a pipe, read from it
-			scanner := bufio.NewScanner(os.Stdin)
-			var lines []string
-			for scanner.Scan() {
-				lines = append(lines, scanner.Text())
-			}
-			if err := scanner.Err(); err != nil {
-				return fmt.Errorf("failed to read from stdin: %w", err)
-			}
-			content = strings.TrimSpace(strings.Join(lines, "\n"))
-		}
-	}
+	content, err := extractContent(args, flags)
 
-	if content == "" {
-		examples := getExamplesForType(fType)
-		return fmt.Errorf(`no content provided
-
-Usage:
-  ctx add %s "your content here"
-  ctx add %s --file /path/to/content.md
-  echo "content" | ctx add %s
-
-Examples:
-%s`, fType, fType, fType, examples)
+	if err != nil || content == "" {
+		return errNoContentProvided(fType)
 	}
 
 	// Build entry params
@@ -236,7 +212,8 @@ Examples:
 	}
 
 	// Validate required fields with CLI-friendly error messages
-	if fType == config.UpdateTypeDecision || fType == config.UpdateTypeDecisions {
+	switch config.UserInputToEntry(fType) {
+	case config.EntryDecision:
 		var missing []string
 		if flags.context == "" {
 			missing = append(missing, "--context")
@@ -248,26 +225,9 @@ Examples:
 			missing = append(missing, "--consequences")
 		}
 		if len(missing) > 0 {
-			return fmt.Errorf(`decisions require complete ADR format
-
-Missing required flags: %s
-
-Usage:
-  ctx add decision "Decision title" \
-    --context "What prompted this decision" \
-    --rationale "Why this choice over alternatives" \
-    --consequences "What changes as a result"
-
-Example:
-  ctx add decision "Use PostgreSQL for primary database" \
-    --context "Need a reliable database for production workloads" \
-    --rationale "PostgreSQL offers ACID compliance, JSON support, and team familiarity" \
-    --consequences "Team needs PostgreSQL training; must set up replication"`,
-				strings.Join(missing, ", "))
+			return errMissingDecision(missing)
 		}
-	}
-
-	if fType == config.UpdateTypeLearning || fType == config.UpdateTypeLearnings {
+	case config.EntryLearning:
 		var missing []string
 		if flags.context == "" {
 			missing = append(missing, "--context")
@@ -279,22 +239,7 @@ Example:
 			missing = append(missing, "--application")
 		}
 		if len(missing) > 0 {
-			return fmt.Errorf(`learnings require complete format
-
-Missing required flags: %s
-
-Usage:
-  ctx add learning "Learning title" \
-    --context "What prompted this learning" \
-    --lesson "The key insight" \
-    --application "How to apply this going forward"
-
-Example:
-  ctx add learning "Go embed requires files in same package" \
-    --context "Tried to embed files from parent directory, got compile error" \
-    --lesson "go:embed only works with files in same or child directories" \
-    --application "Keep embedded files in internal/templates/, not project root"`,
-				strings.Join(missing, ", "))
+			return errMissingLearning(missing)
 		}
 	}
 
@@ -307,7 +252,7 @@ Example:
 		)
 	}
 
-	// Write the entry using shared function
+	// Write the entry using the shared function
 	if err := WriteEntry(params); err != nil {
 		return err
 	}
diff --git a/internal/cli/add/strings.go b/internal/cli/add/strings.go
new file mode 100644
index 000000000..21b6931c7
--- /dev/null
+++ b/internal/cli/add/strings.go
@@ -0,0 +1,78 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package add
+
+import (
+	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+)
+
+// endsWithNewline reports whether s ends with a newline (CRLF or LF).
+//
+// Parameters:
+//   - s: String to check
+//
+// Returns:
+//   - bool: True if s ends with a newline
+func endsWithNewline(s string) bool {
+	return strings.HasSuffix(s, config.NewlineCRLF) ||
+		strings.HasSuffix(s, config.NewlineLF)
+}
+
+// contains reports whether content contains the header and returns its index.
+//
+// Parameters:
+//   - content: String to search in
+//   - header: Substring to find
+//
+// Returns:
+//   - bool: True if header is found
+//   - int: Index of header (-1 if not found)
+func contains(content, header string) (bool, int) {
+	idx := strings.Index(content, header)
+	return idx != -1, idx
+}
+
+// containsNewLine reports whether content contains a newline and
+// returns its index.
+//
+// Parameters:
+//   - content: String to search in
+//
+// Returns:
+//   - bool: True if a newline is found
+//   - int: Index of newline (-1 if not found)
+func containsNewLine(content string) (bool, int) {
+	lineEnd := findNewline(content)
+	return lineEnd != -1, lineEnd
+}
+
+// containsEndComment reports whether content contains a comment close marker.
+//
+// Parameters:
+//   - content: String to search in
+//
+// Returns:
+//   - bool: True if comment close marker is found
+//   - int: Index of marker (-1 if not found)
+func containsEndComment(content string) (bool, int) {
+	commentEnd := strings.Index(content, config.CommentClose)
+	return commentEnd != -1, commentEnd
+}
+
+// startsWithCtxMarker reports whether s starts with a ctx marker comment.
+//
+// Parameters:
+//   - s: String to check
+//
+// Returns:
+//   - bool: True if s starts with CtxMarkerStart or CtxMarkerEnd
+func startsWithCtxMarker(s string) bool {
+	return strings.HasPrefix(s, config.CtxMarkerStart) ||
+		strings.HasPrefix(s, config.CtxMarkerEnd)
+}
diff --git a/internal/cli/agent/agent.go b/internal/cli/agent/agent.go
index 508914e67..cb919eaad 100644
--- a/internal/cli/agent/agent.go
+++ b/internal/cli/agent/agent.go
@@ -9,7 +9,7 @@ package agent
 import (
 	"github.com/spf13/cobra"
 
-	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // Cmd returns the "ctx agent" command for generating AI-ready context packets.
@@ -53,13 +53,13 @@ Examples:
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// Use configured budget if flag not explicitly set
 			if !cmd.Flags().Changed("budget") {
-				budget = config.GetTokenBudget()
+				budget = rc.GetTokenBudget()
 			}
 			return runAgent(cmd, budget, format)
 		},
 	}
 
-	cmd.Flags().IntVar(&budget, "budget", config.DefaultTokenBudget, "Token budget for context packet")
+	cmd.Flags().IntVar(&budget, "budget", rc.DefaultTokenBudget, "Token budget for context packet")
 	cmd.Flags().StringVar(&format, "format", "md", "Output format: md or json")
 
 	return cmd
diff --git a/internal/cli/agent/extract.go b/internal/cli/agent/extract.go
index 00a6d7c77..24c33f2bd 100644
--- a/internal/cli/agent/extract.go
+++ b/internal/cli/agent/extract.go
@@ -7,147 +7,125 @@
 package agent
 
 import (
-	"regexp"
 	"strings"
 
 	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
+	"github.com/ActiveMemory/ctx/internal/task"
 )
 
-// extractConstitutionRules extracts checkbox items from CONSTITUTION.md.
-//
-// Parameters:
-//   - ctx: Loaded context containing the files
+// extractBulletItems extracts Markdown bullet items up to a limit.
 //
-// Returns:
-//   - []string: List of constitution rules; nil if the file is not found
-func extractConstitutionRules(ctx *context.Context) []string {
-	for _, f := range ctx.Files {
-		if f.Name == config.FilenameConstitution {
-			return extractCheckboxItems(string(f.Content))
-		}
-	}
-	return nil
-}
-
-// extractActiveTasks extracts unchecked task items from TASKS.md.
+// Skips empty items and lines starting with "#" (headers).
 //
 // Parameters:
-//   - ctx: Loaded context containing the files
+//   - content: Markdown content to parse
+//   - limit: Maximum number of items to return
 //
 // Returns:
-//   - []string: List of active tasks with "- [ ]" prefix; nil if
-//     the file is not found
-func extractActiveTasks(ctx *context.Context) []string {
-	for _, f := range ctx.Files {
-		if f.Name == config.FilenameTask {
-			return extractUncheckedTasks(string(f.Content))
+//   - []string: Bullet item text without the "- " prefix
+func extractBulletItems(content string, limit int) []string {
+	matches := config.RegExBulletItem.FindAllStringSubmatch(content, -1)
+	items := make([]string, 0, limit)
+	for i, m := range matches {
+		if i >= limit {
+			break
+		}
+		text := strings.TrimSpace(m[1])
+		// Skip empty or header-only items
+		if text != "" && !strings.HasPrefix(text, "#") {
+			items = append(items, text)
 		}
 	}
-	return nil
+	return items
 }
 
-// extractConventions extracts bullet items from CONVENTIONS.md.
+// extractCheckboxItems extracts text from Markdown checkbox items.
+//
+// Matches both checked "- [x]" and unchecked "- [ ]" items.
 //
 // Parameters:
-//   - ctx: Loaded context containing the files
+//   - content: Markdown content to parse
 //
 // Returns:
-//   - []string: Up to 5 convention items; nil if the file is not found
-func extractConventions(ctx *context.Context) []string {
-	for _, f := range ctx.Files {
-		if f.Name == config.FilenameConvention {
-			return extractBulletItems(string(f.Content), 5)
-		}
+//   - []string: Text content of each checkbox item
+func extractCheckboxItems(content string) []string {
+	matches := config.RegExTask.FindAllStringSubmatch(content, -1)
+	items := make([]string, 0, len(matches))
+	for _, m := range matches {
+		items = append(items, strings.TrimSpace(task.Content(m)))
 	}
-	return nil
+	return items
 }
 
-// extractRecentDecisions extracts the most recent decision titles from
-// DECISIONS.md.
+// extractConstitutionRules extracts checkbox items from CONSTITUTION.md.
 //
 // Parameters:
 //   - ctx: Loaded context containing the files
-//   - limit: Maximum number of decisions to return
 //
 // Returns:
-//   - []string: Decision titles (most recent last); nil if the file
-//     is not found
-func extractRecentDecisions(
-	ctx *context.Context, limit int,
-) []string {
+//   - []string: List of constitution rules; nil if the file is not found
+func extractConstitutionRules(ctx *context.Context) []string {
 	for _, f := range ctx.Files {
-		if f.Name == config.FilenameDecision {
-			return extractDecisionTitles(string(f.Content), limit)
+		if f.Name == config.FileConstitution {
+			return extractCheckboxItems(string(f.Content))
 		}
 	}
 	return nil
 }
 
-// extractCheckboxItems extracts text from Markdown checkbox items.
+// extractUncheckedTasks extracts unchecked Markdown checkbox items.
 //
-// Matches both checked "- [x]" and unchecked "- [ ]" items.
+// Only matches "- [ ]" items (not checked). Returns items with the
+// "- [ ]" prefix preserved for display.
 //
 // Parameters:
 //   - content: Markdown content to parse
 //
 // Returns:
-//   - []string: Text content of each checkbox item
-func extractCheckboxItems(content string) []string {
-	re := regexp.MustCompile(`(?m)^-\s*\[[ x]]\s*(.+)$`)
-	matches := re.FindAllStringSubmatch(content, -1)
+//   - []string: Unchecked task items with "- [ ]" prefix
+func extractUncheckedTasks(content string) []string {
+	matches := config.RegExTaskMultiline.FindAllStringSubmatch(content, -1)
 	items := make([]string, 0, len(matches))
 	for _, m := range matches {
-		items = append(items, strings.TrimSpace(m[1]))
+		if task.IsPending(m) {
+			items = append(items, "- [ ] "+strings.TrimSpace(task.Content(m)))
+		}
 	}
 	return items
 }
 
-// extractUncheckedTasks extracts unchecked Markdown checkbox items.
-//
-// Only matches "- [ ]" items (not checked). Returns items with the
-// "- [ ]" prefix preserved for display.
+// extractActiveTasks extracts unchecked task items from TASKS.md.
 //
 // Parameters:
-//   - content: Markdown content to parse
+//   - ctx: Loaded context containing the files
 //
 // Returns:
-//   - []string: Unchecked task items with "- [ ]" prefix
-func extractUncheckedTasks(content string) []string {
-	re := regexp.MustCompile(`(?m)^-\s*\[\s*]\s*(.+)$`)
-	matches := re.FindAllStringSubmatch(content, -1)
-	items := make([]string, 0, len(matches))
-	for _, m := range matches {
-		items = append(items, "- [ ] "+strings.TrimSpace(m[1]))
+//   - []string: List of active tasks with "- [ ]" prefix; nil if
+//     the file is not found
+func extractActiveTasks(ctx *context.Context) []string {
+	for _, f := range ctx.Files {
+		if f.Name == config.FileTask {
+			return extractUncheckedTasks(string(f.Content))
+		}
 	}
-	return items
+	return nil
 }
 
-// extractBulletItems extracts Markdown bullet items up to a limit.
-//
-// Skips empty items and lines starting with "#" (headers).
+// extractConventions extracts bullet items from CONVENTIONS.md.
 //
 // Parameters:
-//   - content: Markdown content to parse
-//   - limit: Maximum number of items to return
+//   - ctx: Loaded context containing the files
 //
 // Returns:
-//   - []string: Bullet item text without the "- " prefix
-func extractBulletItems(content string, limit int) []string {
-	re := regexp.MustCompile(`(?m)^-\s+(.+)$`)
-	matches := re.FindAllStringSubmatch(content, -1)
-	items := make([]string, 0, limit)
-	for i, m := range matches {
-		if i >= limit {
-			break
-		}
-		text := strings.TrimSpace(m[1])
-		// Skip empty or header-only items
-		if text != "" && !strings.HasPrefix(text, "#") {
-			items = append(items, text)
+//   - []string: Up to 5 convention items; nil if the file is not found
+func extractConventions(ctx *context.Context) []string {
+	for _, f := range ctx.Files {
+		if f.Name == config.FileConvention {
+			return extractBulletItems(string(f.Content), 5)
 		}
 	}
-	return items
+	return nil
 }
 
 // extractDecisionTitles extracts decision titles from Markdown headings.
@@ -162,8 +140,7 @@ func extractBulletItems(content string, limit int) []string {
 // Returns:
 //   - []string: Decision titles without a timestamp prefix
 func extractDecisionTitles(content string, limit int) []string {
-	re := regexp.MustCompile(`(?m)^##\s+\[[\d-]+]\s*(.+)$`)
-	matches := re.FindAllStringSubmatch(content, -1)
+	matches := config.RegExEntryHeader.FindAllStringSubmatch(content, -1)
 	items := make([]string, 0, limit)
 	// Get the most recent (last) decisions
 	start := len(matches) - limit
@@ -171,7 +148,29 @@ func extractDecisionTitles(content string, limit int) []string {
 		start = 0
 	}
 	for i := start; i < len(matches); i++ {
-		items = append(items, strings.TrimSpace(matches[i][1]))
+		// Group 3 is the title (groups: 1=date, 2=time, 3=title)
+		items = append(items, strings.TrimSpace(matches[i][3]))
 	}
 	return items
 }
+
+// extractRecentDecisions extracts the most recent decision titles from
+// DECISIONS.md.
+//
+// Parameters:
+//   - ctx: Loaded context containing the files
+//   - limit: Maximum number of decisions to return
+//
+// Returns:
+//   - []string: Decision titles (most recent last); nil if the file
+//     is not found
+func extractRecentDecisions(
+	ctx *context.Context, limit int,
+) []string {
+	for _, f := range ctx.Files {
+		if f.Name == config.FileDecision {
+			return extractDecisionTitles(string(f.Content), limit)
+		}
+	}
+	return nil
+}
diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go
index 6a4560a26..29123f903 100644
--- a/internal/cli/cli_test.go
+++ b/internal/cli/cli_test.go
@@ -7,6 +7,9 @@
 package cli
 
 import (
+	"go/ast"
+	"go/parser"
+	"go/token"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -210,3 +213,128 @@ func TestBinaryIntegration(t *testing.T) {
 		}
 	})
 }
+
+// TestNoDirectFmtPrint ensures CLI code uses cmd.Print* instead of fmt.Print*.
+//
+// In Cobra commands, output should go through cmd.OutOrStdout() so that:
+// - Tests can capture output
+// - --quiet flags work correctly
+// - Output can be redirected properly
+//
+// This test parses all non-test Go files in internal/cli and fails if any
+// function that receives a *cobra.Command uses fmt.Print* directly.
+func TestNoDirectFmtPrint(t *testing.T) {
+	cliDir := "."
+
+	// Forbidden fmt functions that should use cmd.Print* instead
+	forbidden := map[string]bool{
+		"Print":   true,
+		"Println": true,
+		"Printf":  true,
+	}
+
+	var violations []string
+
+	err := filepath.Walk(cliDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		// Skip non-Go files and test files
+		if info.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+
+		fset := token.NewFileSet()
+		node, err := parser.ParseFile(fset, path, nil, parser.ParseComments)
+		if err != nil {
+			t.Errorf("failed to parse %s: %v", path, err)
+			return nil
+		}
+
+		// Track if this file imports "fmt"
+		var fmtAlias string
+		for _, imp := range node.Imports {
+			impPath := strings.Trim(imp.Path.Value, `"`)
+			if impPath == "fmt" {
+				if imp.Name != nil {
+					fmtAlias = imp.Name.Name
+				} else {
+					fmtAlias = "fmt"
+				}
+				break
+			}
+		}
+
+		// No fmt import, nothing to check
+		if fmtAlias == "" {
+			return nil
+		}
+
+		// Find functions that have a *cobra.Command parameter
+		for _, decl := range node.Decls {
+			fn, ok := decl.(*ast.FuncDecl)
+			if !ok || fn.Type.Params == nil {
+				continue
+			}
+
+			// Check if this function has a *cobra.Command parameter
+			hasCobraCmd := false
+			for _, param := range fn.Type.Params.List {
+				if starExpr, ok := param.Type.(*ast.StarExpr); ok {
+					if sel, ok := starExpr.X.(*ast.SelectorExpr); ok {
+						if ident, ok := sel.X.(*ast.Ident); ok {
+							if ident.Name == "cobra" && sel.Sel.Name == "Command" {
+								hasCobraCmd = true
+								break
+							}
+						}
+					}
+				}
+			}
+
+			if !hasCobraCmd {
+				continue
+			}
+
+			// This function has *cobra.Command - check for fmt.Print* calls
+			ast.Inspect(fn.Body, func(n ast.Node) bool {
+				call, ok := n.(*ast.CallExpr)
+				if !ok {
+					return true
+				}
+
+				sel, ok := call.Fun.(*ast.SelectorExpr)
+				if !ok {
+					return true
+				}
+
+				ident, ok := sel.X.(*ast.Ident)
+				if !ok {
+					return true
+				}
+
+				if ident.Name == fmtAlias && forbidden[sel.Sel.Name] {
+					pos := fset.Position(call.Pos())
+					violations = append(violations,
+						filepath.Join(path)+":"+
+							strings.TrimPrefix(pos.String(), pos.Filename+":")+
+							" in "+fn.Name.Name+"()")
+				}
+
+				return true
+			})
+		}
+
+		return nil
+	})
+
+	if err != nil {
+		t.Fatalf("failed to walk directory: %v", err)
+	}
+
+	if len(violations) > 0 {
+		t.Errorf("found %d uses of fmt.Print* in functions with *cobra.Command (use cmd.Print* instead):\n  %s",
+			len(violations), strings.Join(violations, "\n  "))
+	}
+}
diff --git a/internal/cli/compact/block.go b/internal/cli/compact/block.go
index a047a32e4..c4f4e74ba 100644
--- a/internal/cli/compact/block.go
+++ b/internal/cli/compact/block.go
@@ -7,72 +7,20 @@
 package compact
 
 import (
-	"regexp"
 	"strings"
-)
-
-// TaskBlock represents a task and its nested content.
-//
-// Fields:
-//   - Lines: All lines in the block (parent + children)
-//   - StartIndex: Index of first line in original content
-//   - EndIndex: Index of last line (exclusive)
-//   - IsCompleted: Parent task is checked
-//   - IsArchivable: Completed and no unchecked children
-type TaskBlock struct {
-	Lines        []string
-	StartIndex   int
-	EndIndex     int
-	IsCompleted  bool
-	IsArchivable bool
-}
+	"time"
 
-// Patterns for task detection
-var (
-	// Matches checked task: "- [x] content" or "  - [x] content"
-	checkedTaskPattern = regexp.MustCompile(`^(\s*)-\s*\[x]\s*(.+)$`)
-	// Matches unchecked task: "- [ ] content" or "  - [ ] content"
-	uncheckedTaskPattern = regexp.MustCompile(`^(\s*)-\s*\[\s*]\s*(.+)$`)
-	// Matches any task (checked or unchecked)
-	anyTaskPattern = regexp.MustCompile(`^(\s*)-\s*\[[x ]*]\s*(.+)$`)
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/task"
 )
 
-// UncheckedTaskPattern returns the regex for matching unchecked tasks.
-//
-// Returns:
-//   - *regexp.Regexp: Pattern matching "- [ ] content" with optional indentation
-func UncheckedTaskPattern() *regexp.Regexp {
-	return uncheckedTaskPattern
-}
-
-// GetIndentLevel returns the number of leading whitespace characters.
-//
-// Parameters:
-//   - line: The line to measure
-//
-// Returns:
-//   - int: Number of leading whitespace characters (spaces and tabs)
-func GetIndentLevel(line string) int {
-	return getIndentLevel(line)
-}
-
-// getIndentLevel returns the number of leading whitespace characters.
-//
-// Parameters:
-//   - line: The line to measure
-//
-// Returns:
-//   - int: Number of leading whitespace characters (spaces and tabs)
-func getIndentLevel(line string) int {
-	return len(line) - len(strings.TrimLeft(line, " \t"))
-}
-
 // ParseTaskBlocks parses content into task blocks, identifying completed tasks
 // with their nested content.
 //
 // A task block consists of:
-// - A parent task line at the top level (no indentation, e.g., "- [x] Task title")
-// - All following lines that are more indented than the parent
+//   - A parent task line at the top level (no indentation, e.g.,
+//     "- [x] Task title")
+//   - All following lines that are more indented than the parent
 //
 // Only top-level tasks (indent=0) are considered for archiving. Nested subtasks
 // are part of their parent block and are not collected as independent blocks.
@@ -85,7 +33,8 @@ func getIndentLevel(line string) int {
 //   - lines: Slice of lines from the tasks file
 //
 // Returns:
-//   - []TaskBlock: All completed top-level task blocks found (outside Completed section)
+//   - []TaskBlock: All completed top-level task blocks found
+//     (outside the Completed section)
 func ParseTaskBlocks(lines []string) []TaskBlock {
 	var blocks []TaskBlock
 	inCompletedSection := false
@@ -104,15 +53,16 @@ func ParseTaskBlocks(lines []string) []TaskBlock {
 			inCompletedSection = false
 		}
 
-		// Skip if in Completed section or not a checked task
-		if inCompletedSection || !checkedTaskPattern.MatchString(line) {
+		// Skip if in the Completed section or not a checked task
+		match := config.RegExTask.FindStringSubmatch(line)
+		if inCompletedSection || match == nil || !task.Completed(match) {
 			i++
 			continue
 		}
 
 		// Only consider top-level tasks (no indentation) for archiving
 		// Nested subtasks are part of their parent block, not independent
-		if getIndentLevel(line) > 0 {
+		if indentLevel(line) > 0 {
 			i++
 			continue
 		}
@@ -128,92 +78,25 @@ func ParseTaskBlocks(lines []string) []TaskBlock {
 	return blocks
 }
 
-// parseBlockAt parses a task block starting at the given index.
-//
-// Parameters:
-//   - lines: All lines from the file
-//   - startIdx: Index of the parent task line
-//
-// Returns:
-//   - TaskBlock: Parsed block with all nested content
-func parseBlockAt(lines []string, startIdx int) TaskBlock {
-	parentLine := lines[startIdx]
-	parentIndent := getIndentLevel(parentLine)
-
-	block := TaskBlock{
-		Lines:       []string{parentLine},
-		StartIndex:  startIdx,
-		EndIndex:    startIdx + 1,
-		IsCompleted: true, // We only call this for checked tasks
-		IsArchivable: true,
-	}
-
-	// Collect all lines that are more indented than the parent
-	for i := startIdx + 1; i < len(lines); i++ {
-		line := lines[i]
-
-		// Empty lines: include if followed by more indented content
-		if strings.TrimSpace(line) == "" {
-			// Look ahead to see if there's more indented content
-			hasMoreContent := false
-			for j := i + 1; j < len(lines); j++ {
-				nextLine := lines[j]
-				if strings.TrimSpace(nextLine) == "" {
-					continue
-				}
-				if getIndentLevel(nextLine) > parentIndent {
-					hasMoreContent = true
-				}
-				break
-			}
-			if hasMoreContent {
-				block.Lines = append(block.Lines, line)
-				block.EndIndex = i + 1
-				continue
-			}
-			// No more indented content, stop here
-			break
-		}
-
-		// Check indentation
-		lineIndent := getIndentLevel(line)
-		if lineIndent <= parentIndent {
-			// Same or lower indentation - end of block
-			break
-		}
-
-		// This line belongs to the block
-		block.Lines = append(block.Lines, line)
-		block.EndIndex = i + 1
-
-		// Check if this is an unchecked task
-		if uncheckedTaskPattern.MatchString(line) {
-			block.IsArchivable = false
-		}
-	}
-
-	return block
-}
-
 // BlockContent returns the full content of a block as a single string.
 //
 // Returns:
 //   - string: All lines joined with newlines
 func (b *TaskBlock) BlockContent() string {
-	return strings.Join(b.Lines, "\n")
+	return strings.Join(b.Lines, config.NewlineLF)
 }
 
 // ParentTaskText extracts just the task text from the parent line.
 //
 // Returns:
-//   - string: Task text without checkbox prefix, empty if no lines
+//   - string: Task text without the checkbox prefix, empty if no lines
 func (b *TaskBlock) ParentTaskText() string {
 	if len(b.Lines) == 0 {
 		return ""
 	}
-	matches := checkedTaskPattern.FindStringSubmatch(b.Lines[0])
-	if len(matches) > 2 {
-		return matches[2]
+	match := config.RegExTask.FindStringSubmatch(b.Lines[0])
+	if match != nil {
+		return task.Content(match)
 	}
 	return ""
 }
@@ -238,7 +121,8 @@ func RemoveBlocksFromLines(lines []string, blocks []TaskBlock) []string {
 
 	for i := 0; i < len(lines); i++ {
 		// Check if this line is part of a block to remove
-		if blockIdx < len(blocks) && i >= blocks[blockIdx].StartIndex && i < blocks[blockIdx].EndIndex {
+		if blockIdx < len(blocks) &&
+			i >= blocks[blockIdx].StartIndex && i < blocks[blockIdx].EndIndex {
 			// Skip this line
 			if i == blocks[blockIdx].EndIndex-1 {
 				blockIdx++
@@ -250,3 +134,18 @@ func RemoveBlocksFromLines(lines []string, blocks []TaskBlock) []string {
 
 	return result
 }
+
+// OlderThan checks if the task was completed more than the specified days ago.
+//
+// Parameters:
+//   - days: Number of days threshold
+//
+// Returns:
+//   - bool: True if DoneTime is set and older than days ago, false otherwise
+func (b *TaskBlock) OlderThan(days int) bool {
+	if b.DoneTime == nil {
+		return false
+	}
+	threshold := time.Now().AddDate(0, 0, -days)
+	return b.DoneTime.Before(threshold)
+}
diff --git a/internal/cli/compact/block_test.go b/internal/cli/compact/block_test.go
index d2851a4dc..9f0a476e9 100644
--- a/internal/cli/compact/block_test.go
+++ b/internal/cli/compact/block_test.go
@@ -9,6 +9,7 @@ package compact
 import (
 	"strings"
 	"testing"
+	"time"
 )
 
 func TestGetIndentLevel(t *testing.T) {
@@ -26,9 +27,9 @@ func TestGetIndentLevel(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.line, func(t *testing.T) {
-			got := getIndentLevel(tt.line)
+			got := indentLevel(tt.line)
 			if got != tt.expected {
-				t.Errorf("getIndentLevel(%q) = %d, want %d", tt.line, got, tt.expected)
+				t.Errorf("indentLevel(%q) = %d, want %d", tt.line, got, tt.expected)
 			}
 		})
 	}
@@ -427,3 +428,104 @@ func TestParseTaskBlocks_IncompleteDeepChild(t *testing.T) {
 		t.Error("task with incomplete deep child should NOT be archivable")
 	}
 }
+
+func TestParseDoneTimestamp(t *testing.T) {
+	tests := []struct {
+		name     string
+		line     string
+		wantNil  bool
+		wantYear int
+	}{
+		{
+			name:    "no timestamp",
+			line:    "- [x] Simple completed task",
+			wantNil: true,
+		},
+		{
+			name:     "with done timestamp",
+			line:     "- [x] Task with timestamp #added:2026-01-15-100000 #done:2026-01-20-143000",
+			wantNil:  false,
+			wantYear: 2026,
+		},
+		{
+			name:     "only done timestamp",
+			line:     "- [x] Task #done:2025-12-25-120000",
+			wantNil:  false,
+			wantYear: 2025,
+		},
+		{
+			name:    "invalid timestamp format",
+			line:    "- [x] Task #done:2026-01-20",
+			wantNil: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := parseDoneTimestamp(tt.line)
+			if tt.wantNil {
+				if result != nil {
+					t.Errorf("expected nil, got %v", result)
+				}
+			} else {
+				if result == nil {
+					t.Error("expected non-nil time")
+				} else if result.Year() != tt.wantYear {
+					t.Errorf("year = %d, want %d", result.Year(), tt.wantYear)
+				}
+			}
+		})
+	}
+}
+
+func TestTaskBlockIsOlderThan(t *testing.T) {
+	now := time.Now()
+
+	tests := []struct {
+		name     string
+		doneTime *time.Time
+		days     int
+		want     bool
+	}{
+		{
+			name:     "nil done time",
+			doneTime: nil,
+			days:     7,
+			want:     false,
+		},
+		{
+			name:     "completed today",
+			doneTime: func() *time.Time { t := now; return &t }(),
+			days:     7,
+			want:     false,
+		},
+		{
+			name:     "completed 10 days ago",
+			doneTime: func() *time.Time { t := now.AddDate(0, 0, -10); return &t }(),
+			days:     7,
+			want:     true,
+		},
+		{
+			name:     "completed exactly 7 days ago",
+			doneTime: func() *time.Time { t := now.AddDate(0, 0, -7).Add(-time.Hour); return &t }(),
+			days:     7,
+			want:     true,
+		},
+		{
+			name:     "completed 5 days ago with 7 day threshold",
+			doneTime: func() *time.Time { t := now.AddDate(0, 0, -5); return &t }(),
+			days:     7,
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			block := TaskBlock{DoneTime: tt.doneTime}
+			got := block.OlderThan(tt.days)
+			if got != tt.want {
+				t.Errorf("OlderThan(%d) = %v, want %v", tt.days, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/internal/cli/compact/parse.go b/internal/cli/compact/parse.go
new file mode 100644
index 000000000..539ce694e
--- /dev/null
+++ b/internal/cli/compact/parse.go
@@ -0,0 +1,116 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package compact
+
+import (
+	"strings"
+	"time"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/task"
+)
+
+// indentLevel returns the number of leading whitespace characters.
+//
+// Parameters:
+//   - line: The line to measure
+//
+// Returns:
+//   - int: Number of leading whitespace characters (spaces and tabs)
+func indentLevel(line string) int {
+	return len(line) - len(strings.TrimLeft(line, " \t"))
+}
+
+// parseBlockAt parses a task block starting at the given index.
+//
+// Parameters:
+//   - lines: All lines from the file
+//   - startIdx: Index of the parent task line
+//
+// Returns:
+//   - TaskBlock: Parsed block with all nested content
+func parseBlockAt(lines []string, startIdx int) TaskBlock {
+	parentLine := lines[startIdx]
+	parentIndent := indentLevel(parentLine)
+
+	block := TaskBlock{
+		Lines:        []string{parentLine},
+		StartIndex:   startIdx,
+		EndIndex:     startIdx + 1,
+		IsCompleted:  true, // We only call this for checked tasks
+		IsArchivable: true,
+		DoneTime:     parseDoneTimestamp(parentLine),
+	}
+
+	// Collect all lines that are more indented than the parent
+	for i := startIdx + 1; i < len(lines); i++ {
+		line := lines[i]
+
+		// Empty lines: include if followed by more indented content
+		if strings.TrimSpace(line) == "" {
+			// Look ahead to see if there's more indented content
+			hasMoreContent := false
+			for j := i + 1; j < len(lines); j++ {
+				nextLine := lines[j]
+				if strings.TrimSpace(nextLine) == "" {
+					continue
+				}
+				if indentLevel(nextLine) > parentIndent {
+					hasMoreContent = true
+				}
+				break
+			}
+			if hasMoreContent {
+				block.Lines = append(block.Lines, line)
+				block.EndIndex = i + 1
+				continue
+			}
+			// No more indented content, stop here
+			break
+		}
+
+		// Check indentation
+		lineIndent := indentLevel(line)
+		if lineIndent <= parentIndent {
+			// Same or lower indentation - end of block
+			break
+		}
+
+		// This line belongs to the block
+		block.Lines = append(block.Lines, line)
+		block.EndIndex = i + 1
+
+		// Check if this is an unchecked task
+		nestedMatch := config.RegExTask.FindStringSubmatch(line)
+		if nestedMatch != nil && task.IsPending(nestedMatch) {
+			block.IsArchivable = false
+		}
+	}
+
+	return block
+}
+
+// parseDoneTimestamp extracts the #done: timestamp from a task line.
+//
+// Parameters:
+//   - line: Task line that may contain #done:YYYY-MM-DD-HHMMSS
+//
+// Returns:
+//   - *time.Time: Parsed time, or nil if no valid timestamp found
+func parseDoneTimestamp(line string) *time.Time {
+	match := config.RegExTaskDoneTimestamp.FindStringSubmatch(line)
+	if match == nil || len(match) < 2 {
+		return nil
+	}
+
+	// Parse YYYY-MM-DD-HHMMSS format
+	t, err := time.Parse("2006-01-02-150405", match[1])
+	if err != nil {
+		return nil
+	}
+	return &t
+}
diff --git a/internal/cli/compact/process.go b/internal/cli/compact/process.go
index 0f704e4c6..b08f764e3 100644
--- a/internal/cli/compact/process.go
+++ b/internal/cli/compact/process.go
@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // preCompactAutoSave saves a session snapshot before compacting.
@@ -33,7 +34,7 @@ func preCompactAutoSave(cmd *cobra.Command) error {
 	green := color.New(color.FgGreen).SprintFunc()
 
 	// Ensure sessions directory exists
-	sessionsDir := filepath.Join(config.ContextDir(), "sessions")
+	sessionsDir := filepath.Join(rc.GetContextDir(), "sessions")
 	if err := os.MkdirAll(sessionsDir, 0755); err != nil {
 		return fmt.Errorf("failed to create sessions directory: %w", err)
 	}
@@ -69,29 +70,31 @@ func preCompactAutoSave(cmd *cobra.Command) error {
 //   - string: Formatted Markdown content for the session file
 func buildPreCompactSession(timestamp time.Time) string {
 	var sb strings.Builder
+	nl := config.NewlineLF
+	sep := config.Separator
 
-	sb.WriteString("# Pre-Compact Snapshot\n\n")
-	sb.WriteString(fmt.Sprintf("**Date**: %s\n", timestamp.Format("2006-01-02")))
-	sb.WriteString(fmt.Sprintf("**Time**: %s\n", timestamp.Format("15:04:05")))
-	sb.WriteString("**Type**: pre-compact\n\n")
-	sb.WriteString("---\n\n")
+	sb.WriteString("# Pre-Compact Snapshot" + nl + nl)
+	sb.WriteString(fmt.Sprintf("**Date**: %s"+nl, timestamp.Format("2006-01-02")))
+	sb.WriteString(fmt.Sprintf("**Time**: %s"+nl, timestamp.Format("15:04:05")))
+	sb.WriteString("**Type**: pre-compact" + nl + nl)
+	sb.WriteString(sep + nl + nl)
 
-	sb.WriteString("## Purpose\n\n")
+	sb.WriteString("## Purpose" + nl + nl)
 	sb.WriteString(
-		"This snapshot was automatically created before running `ctx compact`.\n",
+		"This snapshot was automatically created before running `ctx compact`." + nl,
 	)
 	sb.WriteString(
-		"It preserves the state of context files before any cleanup operations.\n\n",
+		"It preserves the state of context files before any cleanup operations." + nl + nl,
 	)
-	sb.WriteString("---\n\n")
+	sb.WriteString(sep + nl + nl)
 
 	// Read and include current TASKS.md content
-	tasksPath := filepath.Join(config.ContextDir(), config.FilenameTask)
+	tasksPath := filepath.Join(rc.GetContextDir(), config.FileTask)
 	if tasksContent, err := os.ReadFile(tasksPath); err == nil {
-		sb.WriteString("## Tasks (Before Compact)\n\n")
-		sb.WriteString("```markdown\n")
+		sb.WriteString("## Tasks (Before Compact)" + nl + nl)
+		sb.WriteString("```markdown" + nl)
 		sb.WriteString(string(tasksContent))
-		sb.WriteString("\n```\n\n")
+		sb.WriteString(nl + "```" + nl + nl)
 	}
 
 	return sb.String()
diff --git a/internal/cli/compact/run.go b/internal/cli/compact/run.go
index abfd5f816..fd6b6ba41 100644
--- a/internal/cli/compact/run.go
+++ b/internal/cli/compact/run.go
@@ -16,6 +16,7 @@ import (
 
 	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // runCompact executes the compact command logic.
@@ -41,6 +42,11 @@ func runCompact(cmd *cobra.Command, archive, noAutoSave bool) error {
 		return err
 	}
 
+	// Enable archiving if configured in .contextrc
+	if rc.GetAutoArchive() {
+		archive = true
+	}
+
 	green := color.New(color.FgGreen).SprintFunc()
 	yellow := color.New(color.FgYellow).SprintFunc()
 	cyan := color.New(color.FgCyan).SprintFunc()
@@ -70,7 +76,7 @@ func runCompact(cmd *cobra.Command, archive, noAutoSave bool) error {
 
 	// Process other files for empty sections
 	for _, f := range ctx.Files {
-		if f.Name == config.FilenameTask {
+		if f.Name == config.FileTask {
 			continue
 		}
 		cleaned, count := removeEmptySections(string(f.Content))
diff --git a/internal/cli/compact/task.go b/internal/cli/compact/task.go
index ad53613dd..af4837673 100644
--- a/internal/cli/compact/task.go
+++ b/internal/cli/compact/task.go
@@ -18,6 +18,7 @@ import (
 
 	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // compactTasks moves completed tasks to the "Completed" section in TASKS.md.
@@ -40,7 +41,7 @@ func compactTasks(
 ) (int, error) {
 	var tasksFile *context.FileInfo
 	for i := range ctx.Files {
-		if ctx.Files[i].Name == config.FilenameTask {
+		if ctx.Files[i].Name == config.FileTask {
 			tasksFile = &ctx.Files[i]
 			break
 		}
@@ -110,25 +111,36 @@ func compactTasks(
 
 	// Archive if requested
 	if archive && len(archivableBlocks) > 0 {
-		archiveDir := filepath.Join(config.ContextDir(), "archive")
-		if err := os.MkdirAll(archiveDir, 0755); err == nil {
-			archiveFile := filepath.Join(
-				archiveDir,
-				fmt.Sprintf("tasks-%s.md", time.Now().Format("2006-01-02")),
-			)
-			archiveContent := fmt.Sprintf(
-				"# Archived Tasks - %s\n\n", time.Now().Format("2006-01-02"),
-			)
-			for _, block := range archivableBlocks {
-				archiveContent += block.BlockContent() + "\n\n"
+		// Filter to only tasks old enough to archive
+		archiveDays := rc.GetArchiveAfterDays()
+		var blocksToArchive []TaskBlock
+		for _, block := range archivableBlocks {
+			if block.OlderThan(archiveDays) {
+				blocksToArchive = append(blocksToArchive, block)
 			}
-			if err := os.WriteFile(
-				archiveFile, []byte(archiveContent), 0644,
-			); err == nil {
-				cmd.Printf(
-					"%s Archived %d tasks to %s\n", green("✓"),
-					len(archivableBlocks), archiveFile,
+		}
+
+		if len(blocksToArchive) > 0 {
+			archiveDir := filepath.Join(rc.GetContextDir(), "archive")
+			if err := os.MkdirAll(archiveDir, 0755); err == nil {
+				archiveFile := filepath.Join(
+					archiveDir,
+					fmt.Sprintf("tasks-%s.md", time.Now().Format("2006-01-02")),
+				)
+				archiveContent := fmt.Sprintf(
+					"# Archived Tasks - %s\n\n", time.Now().Format("2006-01-02"),
 				)
+				for _, block := range blocksToArchive {
+					archiveContent += block.BlockContent() + "\n\n"
+				}
+				if err := os.WriteFile(
+					archiveFile, []byte(archiveContent), 0644,
+				); err == nil {
+					cmd.Printf(
+						"%s Archived %d tasks to %s (older than %d days)\n", green("✓"),
+						len(blocksToArchive), archiveFile, archiveDays,
+					)
+				}
 			}
 		}
 	}
diff --git a/internal/cli/compact/types.go b/internal/cli/compact/types.go
new file mode 100644
index 000000000..478796cde
--- /dev/null
+++ b/internal/cli/compact/types.go
@@ -0,0 +1,27 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package compact
+
+import "time"
+
+// TaskBlock represents a task and its nested content.
+//
+// Fields:
+//   - Lines: All lines in the block (parent and children)
+//   - StartIndex: Index of first line in original content
+//   - EndIndex: Index of last line (exclusive)
+//   - IsCompleted: The parent task is checked
+//   - IsArchivable: Completed and no unchecked children
+//   - DoneTime: When the task was marked done (from #done: timestamp), nil if not present
+type TaskBlock struct {
+	Lines        []string
+	StartIndex   int
+	EndIndex     int
+	IsCompleted  bool
+	IsArchivable bool
+	DoneTime     *time.Time
+}
diff --git a/internal/cli/complete/run.go b/internal/cli/complete/run.go
index 1f82555f2..b26d75b4b 100644
--- a/internal/cli/complete/run.go
+++ b/internal/cli/complete/run.go
@@ -10,7 +10,6 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strconv"
 	"strings"
 
@@ -18,6 +17,8 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
+	"github.com/ActiveMemory/ctx/internal/task"
 )
 
 // runComplete executes the complete command logic.
@@ -35,7 +36,7 @@ import (
 func runComplete(cmd *cobra.Command, args []string) error {
 	query := args[0]
 
-	filePath := filepath.Join(config.ContextDir(), config.FilenameTask)
+	filePath := filepath.Join(rc.GetContextDir(), config.FileTask)
 
 	// Check if the file exists
 	if _, err := os.Stat(filePath); os.IsNotExist(err) {
@@ -49,8 +50,7 @@ func runComplete(cmd *cobra.Command, args []string) error {
 	}
 
 	// Parse tasks and find matching one
-	lines := strings.Split(string(content), "\n")
-	taskPattern := regexp.MustCompile(`^(\s*)-\s*\[\s*]\s*(.+)$`)
+	lines := strings.Split(string(content), config.NewlineLF)
 
 	var taskNumber int
 	isNumber := false
@@ -64,10 +64,10 @@ func runComplete(cmd *cobra.Command, args []string) error {
 	matchedTask := ""
 
 	for i, line := range lines {
-		matches := taskPattern.FindStringSubmatch(line)
-		if matches != nil {
+		match := config.RegExTask.FindStringSubmatch(line)
+		if match != nil && task.IsPending(match) {
 			currentTaskNum++
-			taskText := matches[2]
+			taskText := task.Content(match)
 
 			// Match by number
 			if isNumber && currentTaskNum == taskNumber {
@@ -105,8 +105,8 @@ func runComplete(cmd *cobra.Command, args []string) error {
 	}
 
 	// Mark the task as complete
-	lines[matchedLine] = taskPattern.ReplaceAllString(
-		lines[matchedLine], "$1- [x] $2",
+	lines[matchedLine] = config.RegExTask.ReplaceAllString(
+		lines[matchedLine], "$1- [x] $3",
 	)
 
 	// Write back
diff --git a/internal/cli/decisions/decisions.go b/internal/cli/decision/decision.go
similarity index 55%
rename from internal/cli/decisions/decisions.go
rename to internal/cli/decision/decision.go
index 074c9e739..c887047b5 100644
--- a/internal/cli/decisions/decisions.go
+++ b/internal/cli/decision/decision.go
@@ -5,18 +5,10 @@
 //                 SPDX-License-Identifier: Apache-2.0
 
 // Package decisions provides commands for managing DECISIONS.md.
-package decisions
+package decision
 
 import (
-	"fmt"
-	"os"
-	"path/filepath"
-
-	"github.com/fatih/color"
 	"github.com/spf13/cobra"
-
-	"github.com/ActiveMemory/ctx/internal/cli/add"
-	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 // Cmd returns the decisions command with subcommands.
@@ -68,46 +60,3 @@ Examples:
 		RunE: runReindex,
 	}
 }
-
-// runReindex regenerates the DECISIONS.md index.
-//
-// Parameters:
-//   - cmd: Cobra command for output messages
-//   - args: Command arguments (unused)
-//
-// Returns:
-//   - error: Non-nil if file read/write fails
-func runReindex(cmd *cobra.Command, args []string) error {
-	filePath := filepath.Join(config.ContextDir(), config.FilenameDecision)
-
-	// Check if file exists
-	if _, err := os.Stat(filePath); os.IsNotExist(err) {
-		return fmt.Errorf("DECISIONS.md not found. Run 'ctx init' first")
-	}
-
-	// Read current content
-	content, err := os.ReadFile(filePath)
-	if err != nil {
-		return fmt.Errorf("failed to read %s: %w", filePath, err)
-	}
-
-	// Update the index
-	updated := add.UpdateIndex(string(content))
-
-	// Write back
-	if err := os.WriteFile(filePath, []byte(updated), 0644); err != nil {
-		return fmt.Errorf("failed to write %s: %w", filePath, err)
-	}
-
-	// Count entries for feedback
-	entries := add.ParseDecisionHeaders(string(content))
-
-	green := color.New(color.FgGreen).SprintFunc()
-	if len(entries) == 0 {
-		cmd.Printf("%s Index cleared (no decisions found)\n", green("✓"))
-	} else {
-		cmd.Printf("%s Index regenerated with %d entries\n", green("✓"), len(entries))
-	}
-
-	return nil
-}
diff --git a/internal/cli/decision/run.go b/internal/cli/decision/run.go
new file mode 100644
index 000000000..e3ee9c45a
--- /dev/null
+++ b/internal/cli/decision/run.go
@@ -0,0 +1,60 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package decision
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/index"
+	"github.com/ActiveMemory/ctx/internal/rc"
+)
+
+// runReindex regenerates the DECISIONS.md index.
+//
+// Parameters:
+//   - cmd: Cobra command for output messages
+//   - args: Command arguments (unused)
+//
+// Returns:
+//   - error: Non-nil if file read/write fails
+func runReindex(cmd *cobra.Command, _ []string) error {
+	filePath := filepath.Join(rc.GetContextDir(), config.FileDecision)
+
+	if _, err := os.Stat(filePath); os.IsNotExist(err) {
+		return fmt.Errorf("%s not found. Run 'ctx init' first", config.FileDecision)
+	}
+
+	content, err := os.ReadFile(filePath)
+	if err != nil {
+		return fmt.Errorf("failed to read %s: %w", filePath, err)
+	}
+
+	updated := index.UpdateDecisions(string(content))
+
+	if err := os.WriteFile(filePath, []byte(updated), 0644); err != nil {
+		return fmt.Errorf("failed to write %s: %w", filePath, err)
+	}
+
+	entries := index.ParseHeaders(string(content))
+	green := color.New(color.FgGreen).SprintFunc()
+	if len(entries) == 0 {
+		cmd.Printf("%s Index cleared (no decisions found)\n", green("✓"))
+	} else {
+		cmd.Printf(
+			"%s Index regenerated with %d entries\n", green("✓"),
+			len(entries),
+		)
+	}
+
+	return nil
+}
diff --git a/internal/cli/drift/fix.go b/internal/cli/drift/fix.go
index ca3355ec8..946793c13 100644
--- a/internal/cli/drift/fix.go
+++ b/internal/cli/drift/fix.go
@@ -10,7 +10,6 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strings"
 	"time"
 
@@ -20,6 +19,8 @@ import (
 	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
 	"github.com/ActiveMemory/ctx/internal/drift"
+	"github.com/ActiveMemory/ctx/internal/rc"
+	"github.com/ActiveMemory/ctx/internal/task"
 	"github.com/ActiveMemory/ctx/internal/templates"
 )
 
@@ -69,7 +70,7 @@ func applyFixes(
 			}
 
 		case "missing_file":
-			if err := fixMissingFile(cmd, issue.File); err != nil {
+			if err := fixMissingFile(issue.File); err != nil {
 				result.errors = append(result.errors,
 					fmt.Sprintf("missing %s: %v", issue.File, err))
 			} else {
@@ -110,7 +111,7 @@ func applyFixes(
 func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 	var tasksFile *context.FileInfo
 	for i := range ctx.Files {
-		if ctx.Files[i].Name == config.FilenameTask {
+		if ctx.Files[i].Name == config.FileTask {
 			tasksFile = &ctx.Files[i]
 			break
 		}
@@ -120,11 +121,11 @@ func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 		return fmt.Errorf("TASKS.md not found")
 	}
 
+	nl := config.NewlineLF
 	content := string(tasksFile.Content)
-	lines := strings.Split(content, "\n")
+	lines := strings.Split(content, nl)
 
 	// Find completed tasks in the Completed section
-	completedPattern := regexp.MustCompile(`^-\s*\[x]\s*(.+)$`)
 	var completedTasks []string
 	var newLines []string
 	inCompletedSection := false
@@ -141,12 +142,10 @@ func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 		}
 
 		// Collect completed tasks from the Completed section for archiving
-		if inCompletedSection && completedPattern.MatchString(line) {
-			matches := completedPattern.FindStringSubmatch(line)
-			if len(matches) > 1 {
-				completedTasks = append(completedTasks, matches[1])
-				continue // Remove from file
-			}
+		match := config.RegExTask.FindStringSubmatch(line)
+		if inCompletedSection && match != nil && task.Completed(match) {
+			completedTasks = append(completedTasks, task.Content(match))
+			continue // Remove from file
 		}
 
 		newLines = append(newLines, line)
@@ -157,7 +156,7 @@ func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 	}
 
 	// Create an archive directory
-	archiveDir := filepath.Join(config.ContextDir(), "archive")
+	archiveDir := filepath.Join(rc.GetContextDir(), "archive")
 	if err := os.MkdirAll(archiveDir, 0755); err != nil {
 		return fmt.Errorf("failed to create archive directory: %w", err)
 	}
@@ -168,16 +167,14 @@ func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 		fmt.Sprintf("tasks-%s.md", time.Now().Format("2006-01-02")),
 	)
 
-	archiveContent := fmt.Sprintf(
-		"# Archived Tasks - %s\n\n", time.Now().Format("2006-01-02"),
-	)
-	for _, task := range completedTasks {
-		archiveContent += fmt.Sprintf("- [x] %s\n", task)
+	archiveContent := "# Archived Tasks - " + time.Now().Format("2006-01-02") + nl + nl
+	for _, t := range completedTasks {
+		archiveContent += "- [x] " + t + nl
 	}
 
 	// Append to existing archive file if it exists
 	if existing, err := os.ReadFile(archiveFile); err == nil {
-		archiveContent = string(existing) + "\n" + archiveContent
+		archiveContent = string(existing) + nl + archiveContent
 	}
 
 	if err := os.WriteFile(
@@ -187,7 +184,7 @@ func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 	}
 
 	// Write updated TASKS.md
-	newContent := strings.Join(newLines, "\n")
+	newContent := strings.Join(newLines, nl)
 	if err := os.WriteFile(
 		tasksFile.Path, []byte(newContent), 0644,
 	); err != nil {
@@ -203,21 +200,20 @@ func fixStaleness(cmd *cobra.Command, ctx *context.Context) error {
 // fixMissingFile creates a missing required context file from template.
 //
 // Parameters:
-//   - cmd: Cobra command for output messages
 //   - filename: Name of the file to create (e.g., "CONSTITUTION.md")
 //
 // Returns:
 //   - error: Non-nil if the template is not found or file write fails
-func fixMissingFile(cmd *cobra.Command, filename string) error {
+func fixMissingFile(filename string) error {
 	content, err := templates.GetTemplate(filename)
 	if err != nil {
 		return fmt.Errorf("no template available for %s: %w", filename, err)
 	}
 
-	targetPath := filepath.Join(config.ContextDir(), filename)
+	targetPath := filepath.Join(rc.GetContextDir(), filename)
 
 	// Ensure .context/ directory exists
-	if err := os.MkdirAll(config.ContextDir(), 0755); err != nil {
+	if err := os.MkdirAll(rc.GetContextDir(), 0755); err != nil {
 		return fmt.Errorf("failed to create .context/: %w", err)
 	}
 
diff --git a/internal/cli/initialize/cmd.go b/internal/cli/initialize/cmd.go
index c99b922d8..ddc9c0104 100644
--- a/internal/cli/initialize/cmd.go
+++ b/internal/cli/initialize/cmd.go
@@ -38,7 +38,7 @@ func createClaudeCommands(cmd *cobra.Command, force bool) error {
 	}
 
 	// Get the list of embedded command files
-	commands, err := claude.ListCommands()
+	commands, err := claude.Commands()
 	if err != nil {
 		return fmt.Errorf("failed to list commands: %w", err)
 	}
@@ -50,7 +50,7 @@ func createClaudeCommands(cmd *cobra.Command, force bool) error {
 			continue
 		}
 
-		content, err := claude.GetCommand(cmdName)
+		content, err := claude.CommandByName(cmdName)
 		if err != nil {
 			return fmt.Errorf("failed to get command %s: %w", cmdName, err)
 		}
diff --git a/internal/cli/initialize/hook.go b/internal/cli/initialize/hook.go
index 163db9724..762c8b036 100644
--- a/internal/cli/initialize/hook.go
+++ b/internal/cli/initialize/hook.go
@@ -53,7 +53,7 @@ func createClaudeHooks(cmd *cobra.Command, force bool) error {
 	if _, err := os.Stat(scriptPath); err == nil && !force {
 		cmd.Printf("  %s %s (exists, skipped)\n", yellow("○"), scriptPath)
 	} else {
-		scriptContent, err := claude.GetAutoSaveScript()
+		scriptContent, err := claude.AutoSaveScript()
 		if err != nil {
 			return fmt.Errorf("failed to get auto-save script: %w", err)
 		}
@@ -71,7 +71,7 @@ func createClaudeHooks(cmd *cobra.Command, force bool) error {
 	if _, err := os.Stat(blockScriptPath); err == nil && !force {
 		cmd.Printf("  %s %s (exists, skipped)\n", yellow("○"), blockScriptPath)
 	} else {
-		blockScriptContent, err := claude.GetBlockNonPathCtxScript()
+		blockScriptContent, err := claude.BlockNonPathCtxScript()
 		if err != nil {
 			return fmt.Errorf("failed to get block-non-path-ctx script: %w", err)
 		}
@@ -83,6 +83,26 @@ func createClaudeHooks(cmd *cobra.Command, force bool) error {
 		cmd.Printf("  %s %s\n", green("✓"), blockScriptPath)
 	}
 
+	// Create prompt-coach.sh script
+	// (detects prompt anti-patterns and suggests improvements)
+	coachScriptPath := filepath.Join(
+		config.DirClaudeHooks, config.FilePromptCoach,
+	)
+	if _, err := os.Stat(coachScriptPath); err == nil && !force {
+		cmd.Printf("  %s %s (exists, skipped)\n", yellow("○"), coachScriptPath)
+	} else {
+		coachScriptContent, err := claude.PromptCoachScript()
+		if err != nil {
+			return fmt.Errorf("failed to get prompt-coach script: %w", err)
+		}
+		if err := os.WriteFile(
+			coachScriptPath, coachScriptContent, 0755,
+		); err != nil {
+			return fmt.Errorf("failed to write %s: %w", coachScriptPath, err)
+		}
+		cmd.Printf("  %s %s\n", green("✓"), coachScriptPath)
+	}
+
 	// Handle settings.local.json - merge rather than overwrite
 	if err := mergeSettingsHooks(cmd, cwd, force); err != nil {
 		return err
@@ -128,11 +148,12 @@ func mergeSettingsHooks(
 	}
 
 	// Get our defaults
-	defaultHooks := claude.CreateDefaultHooks(projectDir)
-	defaultPerms := claude.CreateDefaultPermissions()
+	defaultHooks := claude.DefaultHooks(projectDir)
+	defaultPerms := claude.DefaultPermissions()
 
 	// Check if hooks already exist
 	hasPreToolUse := len(settings.Hooks.PreToolUse) > 0
+	hasUserPromptSubmit := len(settings.Hooks.UserPromptSubmit) > 0
 	hasSessionEnd := len(settings.Hooks.SessionEnd) > 0
 
 	// Merge hooks - only add what's missing (or force overwrite)
@@ -141,6 +162,10 @@ func mergeSettingsHooks(
 		settings.Hooks.PreToolUse = defaultHooks.PreToolUse
 		hooksModified = true
 	}
+	if !hasUserPromptSubmit || force {
+		settings.Hooks.UserPromptSubmit = defaultHooks.UserPromptSubmit
+		hooksModified = true
+	}
 	if !hasSessionEnd || force {
 		settings.Hooks.SessionEnd = defaultHooks.SessionEnd
 		hooksModified = true
diff --git a/internal/cli/initialize/run.go b/internal/cli/initialize/run.go
index fa68af7d2..facf55d84 100644
--- a/internal/cli/initialize/run.go
+++ b/internal/cli/initialize/run.go
@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 	"github.com/ActiveMemory/ctx/internal/templates"
 )
 
@@ -39,7 +40,7 @@ func runInit(cmd *cobra.Command, force, minimal, merge bool) error {
 		return err
 	}
 
-	contextDir := config.ContextDir()
+	contextDir := rc.GetContextDir()
 
 	// Check if .context/ already exists
 	if _, err := os.Stat(contextDir); err == nil {
diff --git a/internal/cli/journal/journal.go b/internal/cli/journal/journal.go
new file mode 100644
index 000000000..6e32d546e
--- /dev/null
+++ b/internal/cli/journal/journal.go
@@ -0,0 +1,41 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package journal
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// Cmd returns the journal command with subcommands.
+//
+// The journal system provides LLM-powered analysis and synthesis of
+// exported session files in .context/journal/.
+//
+// Returns:
+//   - *cobra.Command: The journal command with subcommands
+func Cmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "journal",
+		Short: "Analyze and synthesize exported sessions",
+		Long: `Work with exported session files in .context/journal/.
+
+The journal system provides tools for analyzing, enriching, and
+publishing your AI session history.
+
+Subcommands:
+  site      Generate a static site from journal entries
+
+Examples:
+  ctx journal site                    # Generate site in .context/journal-site/
+  ctx journal site --output ~/public  # Custom output directory
+  ctx journal site --serve            # Generate and serve locally`,
+	}
+
+	cmd.AddCommand(journalSiteCmd())
+
+	return cmd
+}
diff --git a/internal/cli/journal/site.go b/internal/cli/journal/site.go
new file mode 100644
index 000000000..2ec674e92
--- /dev/null
+++ b/internal/cli/journal/site.go
@@ -0,0 +1,450 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package journal
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
+)
+
+// journalSiteCmd returns the journal site subcommand.
+//
+// Returns:
+//   - *cobra.Command: Command for generating a static site from journal entries
+func journalSiteCmd() *cobra.Command {
+	var (
+		output string
+		serve  bool
+		build  bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "site",
+		Short: "Generate a static site from journal entries",
+		Long: `Generate a zensical-compatible static site from .context/journal/ entries.
+
+Creates a site structure with:
+  - Index page with all sessions listed by date
+  - Individual pages for each journal entry
+  - Navigation and search support
+
+Requires zensical to be installed for building/serving:
+  pip install zensical
+
+Examples:
+  ctx journal site                    # Generate in .context/journal-site/
+  ctx journal site --output ~/public  # Custom output directory
+  ctx journal site --build            # Generate and build HTML
+  ctx journal site --serve            # Generate and serve locally`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runJournalSite(cmd, output, build, serve)
+		},
+	}
+
+	defaultOutput := filepath.Join(rc.GetContextDir(), "journal-site")
+	cmd.Flags().StringVarP(&output, "output", "o", defaultOutput, "Output directory for site")
+	cmd.Flags().BoolVar(&build, "build", false, "Run zensical build after generating")
+	cmd.Flags().BoolVar(&serve, "serve", false, "Run zensical serve after generating")
+
+	return cmd
+}
+
+// journalEntry represents a parsed journal file.
+type journalEntry struct {
+	Filename     string
+	Title        string
+	Date         string
+	Time         string
+	Project      string
+	Path         string
+	Size         int64
+	IsSuggestion bool
+}
+
+// runJournalSite handles the journal site command.
+//
+// Scans .context/journal/ for markdown files, generates a zensical project
+// structure, and optionally builds or serves the site.
+//
+// Parameters:
+//   - cmd: Cobra command for output stream
+//   - output: Output directory for the generated site
+//   - build: If true, run zensical build after generating
+//   - serve: If true, run zensical serve after generating
+//
+// Returns:
+//   - error: Non-nil if generation fails
+func runJournalSite(cmd *cobra.Command, output string, build, serve bool) error {
+	journalDir := filepath.Join(rc.GetContextDir(), "journal")
+
+	// Check if journal directory exists
+	if _, err := os.Stat(journalDir); os.IsNotExist(err) {
+		return fmt.Errorf("no journal directory found at %s\nRun 'ctx recall export --all' first", journalDir)
+	}
+
+	// Scan journal files
+	entries, err := scanJournalEntries(journalDir)
+	if err != nil {
+		return fmt.Errorf("failed to scan journal: %w", err)
+	}
+
+	if len(entries) == 0 {
+		return fmt.Errorf("no journal entries found in %s\nRun 'ctx recall export --all' first", journalDir)
+	}
+
+	green := color.New(color.FgGreen).SprintFunc()
+
+	// Create output directory structure
+	docsDir := filepath.Join(output, "docs")
+	if err := os.MkdirAll(docsDir, 0755); err != nil {
+		return fmt.Errorf("failed to create output directory: %w", err)
+	}
+
+	// Copy journal files to docs/
+	for _, entry := range entries {
+		src := entry.Path
+		dst := filepath.Join(docsDir, entry.Filename)
+
+		content, err := os.ReadFile(src)
+		if err != nil {
+			cmd.PrintErrf("  ! failed to read %s: %v\n", entry.Filename, err)
+			continue
+		}
+
+		if err := os.WriteFile(dst, content, 0644); err != nil {
+			cmd.PrintErrf("  ! failed to write %s: %v\n", entry.Filename, err)
+			continue
+		}
+	}
+
+	// Generate index.md
+	indexContent := generateIndex(entries)
+	indexPath := filepath.Join(docsDir, "index.md")
+	if err := os.WriteFile(indexPath, []byte(indexContent), 0644); err != nil {
+		return fmt.Errorf("failed to write index.md: %w", err)
+	}
+
+	// Generate zensical.toml
+	tomlContent := generateZensicalToml(entries)
+	tomlPath := filepath.Join(output, "zensical.toml")
+	if err := os.WriteFile(tomlPath, []byte(tomlContent), 0644); err != nil {
+		return fmt.Errorf("failed to write zensical.toml: %w", err)
+	}
+
+	cmd.Printf("%s Generated site with %d entries in %s\n", green("✓"), len(entries), output)
+
+	// Build or serve if requested
+	if serve {
+		cmd.Println("\nStarting local server...")
+		return runZensical(output, "serve")
+	} else if build {
+		cmd.Println("\nBuilding site...")
+		return runZensical(output, "build")
+	}
+
+	cmd.Println("\nNext steps:")
+	cmd.Printf("  cd %s && zensical serve\n", output)
+
+	return nil
+}
+
+// scanJournalEntries reads all journal markdown files and extracts metadata.
+//
+// Parameters:
+//   - journalDir: Path to .context/journal/
+//
+// Returns:
+//   - []journalEntry: Parsed entries sorted by date (newest first)
+//   - error: Non-nil if directory scanning fails
+func scanJournalEntries(journalDir string) ([]journalEntry, error) {
+	files, err := os.ReadDir(journalDir)
+	if err != nil {
+		return nil, err
+	}
+
+	var entries []journalEntry
+	for _, f := range files {
+		if f.IsDir() || !strings.HasSuffix(f.Name(), ".md") {
+			continue
+		}
+
+		path := filepath.Join(journalDir, f.Name())
+		entry := parseJournalEntry(path, f.Name())
+		entries = append(entries, entry)
+	}
+
+	// Sort by datetime (newest first) - combine Date and Time
+	sort.Slice(entries, func(i, j int) bool {
+		// Compare Date+Time strings (YYYY-MM-DD + HH:MM:SS)
+		di := entries[i].Date + " " + entries[i].Time
+		dj := entries[j].Date + " " + entries[j].Time
+		return di > dj
+	})
+
+	return entries, nil
+}
+
+// parseJournalEntry extracts metadata from a journal file.
+//
+// Parameters:
+//   - path: Full path to the journal file
+//   - filename: Filename (e.g., "2026-01-21-async-roaming-allen-af7cba21.md")
+//
+// Returns:
+//   - journalEntry: Parsed entry with title, date, project extracted
+func parseJournalEntry(path, filename string) journalEntry {
+	entry := journalEntry{
+		Filename: filename,
+		Path:     path,
+	}
+
+	// Extract date from filename (YYYY-MM-DD-slug-id.md)
+	if len(filename) >= 10 {
+		entry.Date = filename[:10]
+	}
+
+	// Read file to extract metadata
+	content, err := os.ReadFile(path)
+	if err != nil {
+		entry.Title = strings.TrimSuffix(filename, ".md")
+		return entry
+	}
+
+	// File size
+	entry.Size = int64(len(content))
+
+	// Check for suggestion mode sessions
+	contentStr := string(content)
+	if strings.Contains(contentStr, "[SUGGESTION MODE:") ||
+		strings.Contains(contentStr, "SUGGESTION MODE:") {
+		entry.IsSuggestion = true
+	}
+
+	lines := strings.Split(contentStr, "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+
+		// Title from first H1
+		if strings.HasPrefix(line, "# ") && entry.Title == "" {
+			entry.Title = strings.TrimPrefix(line, "# ")
+		}
+
+		// Time from metadata
+		if strings.HasPrefix(line, "**Time**:") {
+			entry.Time = strings.TrimSpace(strings.TrimPrefix(line, "**Time**:"))
+		}
+
+		// Project from metadata
+		if strings.HasPrefix(line, "**Project**:") {
+			entry.Project = strings.TrimSpace(strings.TrimPrefix(line, "**Project**:"))
+		}
+
+		// Stop after we have all three
+		if entry.Title != "" && entry.Time != "" && entry.Project != "" {
+			break
+		}
+	}
+
+	if entry.Title == "" {
+		entry.Title = strings.TrimSuffix(filename, ".md")
+	}
+
+	return entry
+}
+
+// generateIndex creates the index.md content for the journal site.
+//
+// Parameters:
+//   - entries: All journal entries to include
+//
+// Returns:
+//   - string: Markdown content for index.md
+func generateIndex(entries []journalEntry) string {
+	var sb strings.Builder
+	nl := config.NewlineLF
+
+	// Separate regular sessions from suggestions
+	var regular, suggestions []journalEntry
+	for _, e := range entries {
+		if e.IsSuggestion {
+			suggestions = append(suggestions, e)
+		} else {
+			regular = append(regular, e)
+		}
+	}
+
+	sb.WriteString("# Session Journal" + nl + nl)
+	sb.WriteString("Browse your AI session history." + nl + nl)
+	sb.WriteString(fmt.Sprintf("**Sessions**: %d | **Suggestions**: %d"+nl+nl, len(regular), len(suggestions)))
+
+	// Group regular sessions by month
+	months := make(map[string][]journalEntry)
+	var monthOrder []string
+
+	for _, e := range regular {
+		if len(e.Date) >= 7 {
+			month := e.Date[:7] // YYYY-MM
+			if _, exists := months[month]; !exists {
+				monthOrder = append(monthOrder, month)
+			}
+			months[month] = append(months[month], e)
+		}
+	}
+
+	for _, month := range monthOrder {
+		sb.WriteString(fmt.Sprintf("## %s"+nl+nl, month))
+
+		for _, e := range months[month] {
+			sb.WriteString(formatIndexEntry(e, nl))
+		}
+		sb.WriteString(nl)
+	}
+
+	// Suggestions section (collapsed by default via details tag)
+	if len(suggestions) > 0 {
+		sb.WriteString("---" + nl + nl)
+		sb.WriteString("## Suggestions" + nl + nl)
+		sb.WriteString("*Auto-generated suggestion prompts from Claude Code.*" + nl + nl)
+
+		for _, e := range suggestions {
+			sb.WriteString(formatIndexEntry(e, nl))
+		}
+		sb.WriteString(nl)
+	}
+
+	return sb.String()
+}
+
+// formatIndexEntry formats a single entry for the index.
+//
+// Format: - HH:MM [title](link.md) (project) [size]
+func formatIndexEntry(e journalEntry, nl string) string {
+	link := strings.TrimSuffix(e.Filename, ".md")
+
+	timeStr := ""
+	if e.Time != "" && len(e.Time) >= 5 {
+		timeStr = e.Time[:5] + " "
+	}
+
+	project := ""
+	if e.Project != "" {
+		project = fmt.Sprintf(" (%s)", e.Project)
+	}
+
+	size := formatSize(e.Size)
+
+	return fmt.Sprintf("- %s[%s](%s.md)%s `%s`"+nl, timeStr, e.Title, link, project, size)
+}
+
+// formatSize formats a file size in human-readable form.
+func formatSize(bytes int64) string {
+	if bytes < 1024 {
+		return fmt.Sprintf("%dB", bytes)
+	}
+	kb := float64(bytes) / 1024
+	if kb < 1024 {
+		return fmt.Sprintf("%.1fKB", kb)
+	}
+	mb := kb / 1024
+	return fmt.Sprintf("%.1fMB", mb)
+}
+
+// generateZensicalToml creates the zensical.toml configuration.
+//
+// Parameters:
+//   - entries: All journal entries for navigation
+//
+// Returns:
+//   - string: TOML content for zensical.toml
+func generateZensicalToml(entries []journalEntry) string {
+	var sb strings.Builder
+	nl := config.NewlineLF
+
+	sb.WriteString(`[project]
+site_name = "Session Journal"
+site_description = "AI session history and notes"
+` + nl)
+
+	// Build navigation
+	sb.WriteString("nav = [" + nl)
+	sb.WriteString(`  { "Home" = "index.md" },` + nl)
+
+	// Group recent entries (last 20)
+	recent := entries
+	if len(recent) > 20 {
+		recent = recent[:20]
+	}
+
+	sb.WriteString(`  { "Recent Sessions" = [` + nl)
+	for _, e := range recent {
+		title := e.Title
+		if len(title) > 40 {
+			title = title[:40] + "..."
+		}
+		// Escape quotes in title
+		title = strings.ReplaceAll(title, `"`, `\"`)
+		sb.WriteString(fmt.Sprintf(`    { "%s" = "%s" },`+nl, title, e.Filename))
+	}
+	sb.WriteString("  ]}" + nl)
+	sb.WriteString("]" + nl + nl)
+
+	sb.WriteString(`[project.theme]
+language = "en"
+features = [
+    "content.code.copy",
+    "navigation.instant",
+    "navigation.top",
+    "search.highlight",
+]
+
+[[project.theme.palette]]
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+`)
+
+	return sb.String()
+}
+
+// runZensical executes zensical build or serve in the output directory.
+//
+// Parameters:
+//   - dir: Directory containing the generated site
+//   - command: "build" or "serve"
+//
+// Returns:
+//   - error: Non-nil if zensical is not found or fails
+func runZensical(dir, command string) error {
+	// Check if zensical is available
+	_, err := exec.LookPath("zensical")
+	if err != nil {
+		return fmt.Errorf("zensical not found. Install with: pip install zensical")
+	}
+
+	cmd := exec.Command("zensical", command)
+	cmd.Dir = dir
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.Stdin = os.Stdin
+
+	return cmd.Run()
+}
diff --git a/internal/cli/learnings/learnings.go b/internal/cli/learnings/learnings.go
index 06c63e909..b0faf9b12 100644
--- a/internal/cli/learnings/learnings.go
+++ b/internal/cli/learnings/learnings.go
@@ -15,8 +15,9 @@ import (
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
 
-	"github.com/ActiveMemory/ctx/internal/cli/add"
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/index"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // Cmd returns the learnings command with subcommands.
@@ -77,36 +78,35 @@ Examples:
 //
 // Returns:
 //   - error: Non-nil if file read/write fails
-func runReindex(cmd *cobra.Command, args []string) error {
-	filePath := filepath.Join(config.ContextDir(), config.FilenameLearning)
+func runReindex(cmd *cobra.Command, _ []string) error {
+	filePath := filepath.Join(rc.GetContextDir(), config.FileLearning)
 
-	// Check if file exists
 	if _, err := os.Stat(filePath); os.IsNotExist(err) {
-		return fmt.Errorf("LEARNINGS.md not found. Run 'ctx init' first")
+		return fmt.Errorf(
+			"%s not found. Run 'ctx init' first", config.FileLearning,
+		)
 	}
 
-	// Read current content
 	content, err := os.ReadFile(filePath)
 	if err != nil {
 		return fmt.Errorf("failed to read %s: %w", filePath, err)
 	}
 
-	// Update the index
-	updated := add.UpdateLearningsIndex(string(content))
+	updated := index.UpdateLearnings(string(content))
 
-	// Write back
 	if err := os.WriteFile(filePath, []byte(updated), 0644); err != nil {
 		return fmt.Errorf("failed to write %s: %w", filePath, err)
 	}
 
-	// Count entries for feedback
-	entries := add.ParseEntryHeaders(string(content))
-
+	entries := index.ParseHeaders(string(content))
 	green := color.New(color.FgGreen).SprintFunc()
 	if len(entries) == 0 {
 		cmd.Printf("%s Index cleared (no learnings found)\n", green("✓"))
 	} else {
-		cmd.Printf("%s Index regenerated with %d entries\n", green("✓"), len(entries))
+		cmd.Printf(
+			"%s Index regenerated with %d entries\n", green("✓"),
+			len(entries),
+		)
 	}
 
 	return nil
diff --git a/internal/cli/load/load.go b/internal/cli/load/load.go
index ea3ec5949..06e8c7fe4 100644
--- a/internal/cli/load/load.go
+++ b/internal/cli/load/load.go
@@ -9,7 +9,7 @@ package load
 import (
 	"github.com/spf13/cobra"
 
-	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // Cmd returns the "ctx load" command for outputting assembled context.
@@ -51,14 +51,14 @@ Use --budget to limit output to a specific token count (default from .contextrc
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// Use configured budget if flag not explicitly set
 			if !cmd.Flags().Changed("budget") {
-				budget = config.GetTokenBudget()
+				budget = rc.GetTokenBudget()
 			}
 			return runLoad(cmd, budget, raw)
 		},
 	}
 
 	cmd.Flags().IntVar(
-		&budget, "budget", config.DefaultTokenBudget, "Token budget for assembly",
+		&budget, "budget", rc.DefaultTokenBudget, "Token budget for assembly",
 	)
 	cmd.Flags().BoolVar(
 		&raw, "raw", false, "Output raw file contents without assembly",
diff --git a/internal/cli/load/out.go b/internal/cli/load/out.go
index ba2c1b085..8fa735f2c 100644
--- a/internal/cli/load/out.go
+++ b/internal/cli/load/out.go
@@ -12,6 +12,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
 )
 
@@ -56,16 +57,18 @@ func outputAssembled(
 	cmd *cobra.Command, ctx *context.Context, budget int,
 ) error {
 	var sb strings.Builder
+	nl := config.NewlineLF
+	sep := config.Separator
 
 	// Header
-	sb.WriteString("# Context\n\n")
+	sb.WriteString("# Context" + nl + nl)
 	sb.WriteString(
 		fmt.Sprintf(
-			"Token Budget: %d | Available: %d\n\n",
+			"Token Budget: %d | Available: %d"+nl+nl,
 			budget, ctx.TotalTokens,
 		),
 	)
-	sb.WriteString("---\n\n")
+	sb.WriteString(sep + nl + nl)
 
 	// Sort files by read order
 	files := sortByReadOrder(ctx.Files)
@@ -83,19 +86,19 @@ func outputAssembled(
 		if tokensUsed+fileTokens > budget {
 			// Add a truncation notice
 			sb.WriteString(
-				fmt.Sprintf("\n---\n\n*[Truncated: %s and remaining files "+
-					"excluded due to token budget]*\n", f.Name),
+				fmt.Sprintf(nl+sep+nl+nl+"*[Truncated: %s and remaining files "+
+					"excluded due to token budget]*"+nl, f.Name),
 			)
 			break
 		}
 
 		// Add the file section
-		sb.WriteString(fmt.Sprintf("## %s\n\n", fileNameToTitle(f.Name)))
+		sb.WriteString(fmt.Sprintf("## %s"+nl+nl, fileNameToTitle(f.Name)))
 		sb.Write(f.Content)
-		if !strings.HasSuffix(string(f.Content), "\n") {
-			sb.WriteString("\n")
+		if !strings.HasSuffix(string(f.Content), nl) {
+			sb.WriteString(nl)
 		}
-		sb.WriteString("\n---\n\n")
+		sb.WriteString(nl + sep + nl + nl)
 
 		tokensUsed += fileTokens
 	}
diff --git a/internal/cli/recall/export.go b/internal/cli/recall/export.go
new file mode 100644
index 000000000..d6d8b866d
--- /dev/null
+++ b/internal/cli/recall/export.go
@@ -0,0 +1,316 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package recall
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
+	"github.com/ActiveMemory/ctx/internal/recall/parser"
+)
+
+// recallExportCmd returns the recall export subcommand.
+//
+// Returns:
+//   - *cobra.Command: Command for exporting sessions to journal files
+func recallExportCmd() *cobra.Command {
+	var (
+		all         bool
+		allProjects bool
+		force       bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "export [session-id]",
+		Short: "Export sessions to editable journal files",
+		Long: `Export AI sessions to .context/journal/ as editable Markdown files.
+
+Exported files include session metadata, tool usage summary, and the full
+conversation. You can edit these files to add notes, highlight key moments,
+or clean up the transcript.
+
+By default, only sessions from the current project are exported. Use
+--all-projects to include sessions from all projects.
+
+Existing files are skipped to preserve your edits. Use --force to overwrite.
+
+Examples:
+  ctx recall export abc123              # Export one session
+  ctx recall export --all               # Export all sessions from this project
+  ctx recall export --all --all-projects  # Export from all projects
+  ctx recall export --all --force       # Overwrite existing exports`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runRecallExport(cmd, args, all, allProjects, force)
+		},
+	}
+
+	cmd.Flags().BoolVar(&all, "all", false, "Export all sessions from current project")
+	cmd.Flags().BoolVar(&allProjects, "all-projects", false, "Include sessions from all projects")
+	cmd.Flags().BoolVar(&force, "force", false, "Overwrite existing files")
+
+	return cmd
+}
+
+// runRecallExport handles the recall export command.
+//
+// Exports one or more sessions to .context/journal/ as Markdown files.
+// Skips existing files unless force is true.
+//
+// Parameters:
+//   - cmd: Cobra command for output stream
+//   - args: Session ID to export (ignored if all is true)
+//   - all: If true, export all sessions
+//   - allProjects: If true, include sessions from all projects
+//   - force: If true, overwrite existing files
+//
+// Returns:
+//   - error: Non-nil if export fails
+func runRecallExport(cmd *cobra.Command, args []string, all, allProjects, force bool) error {
+	if len(args) > 0 && all {
+		return fmt.Errorf("cannot use --all with a session ID; use one or the other")
+	}
+	if len(args) == 0 && !all {
+		return fmt.Errorf("please provide a session ID or use --all")
+	}
+
+	// Find sessions - filter by current project unless --all-projects is set
+	var sessions []*parser.Session
+	var err error
+	if allProjects {
+		sessions, err = parser.FindSessions()
+	} else {
+		cwd, cwdErr := os.Getwd()
+		if cwdErr != nil {
+			return fmt.Errorf("failed to get working directory: %w", cwdErr)
+		}
+		sessions, err = parser.FindSessionsForCWD(cwd)
+	}
+	if err != nil {
+		return fmt.Errorf("failed to find sessions: %w", err)
+	}
+
+	if len(sessions) == 0 {
+		if allProjects {
+			cmd.Println("No sessions found.")
+		} else {
+			cmd.Println("No sessions found for this project. Use --all-projects to see all.")
+		}
+		return nil
+	}
+
+	// Determine which sessions to export
+	var toExport []*parser.Session
+	if all {
+		toExport = sessions
+	} else {
+		query := strings.ToLower(args[0])
+		for _, s := range sessions {
+			if strings.HasPrefix(strings.ToLower(s.ID), query) ||
+				strings.Contains(strings.ToLower(s.Slug), query) {
+				toExport = append(toExport, s)
+			}
+		}
+		if len(toExport) == 0 {
+			return fmt.Errorf("session not found: %s", args[0])
+		}
+		if len(toExport) > 1 && !all {
+			cmd.PrintErrf("Multiple sessions match '%s':\n", args[0])
+			for _, m := range toExport {
+				cmd.PrintErrf("  %s (%s) - %s\n",
+					m.Slug, m.ID[:8], m.StartTime.Format("2006-01-02 15:04"))
+			}
+			return fmt.Errorf("ambiguous query, use a more specific ID")
+		}
+	}
+
+	// Ensure journal directory exists
+	journalDir := filepath.Join(rc.GetContextDir(), "journal")
+	if err := os.MkdirAll(journalDir, 0755); err != nil {
+		return fmt.Errorf("failed to create journal directory: %w", err)
+	}
+
+	// Export each session
+	green := color.New(color.FgGreen).SprintFunc()
+	yellow := color.New(color.FgYellow).SprintFunc()
+	dim := color.New(color.FgHiBlack)
+
+	var exported, skipped int
+	for _, s := range toExport {
+		filename := formatJournalFilename(s)
+		path := filepath.Join(journalDir, filename)
+
+		// Check if file exists
+		if _, err := os.Stat(path); err == nil && !force {
+			skipped++
+			dim.Fprintf(cmd.OutOrStdout(), "  skip %s (exists)\n", filename)
+			continue
+		}
+
+		// Generate content
+		content := formatJournalEntry(s)
+
+		// Write file
+		if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+			cmd.PrintErrf("  %s failed to write %s: %v\n", yellow("!"), filename, err)
+			continue
+		}
+
+		exported++
+		cmd.Printf("  %s %s\n", green("✓"), filename)
+	}
+
+	cmd.Println()
+	if exported > 0 {
+		cmd.Printf("Exported %d session(s) to %s\n", exported, journalDir)
+	}
+	if skipped > 0 {
+		dim.Fprintf(cmd.OutOrStdout(), "Skipped %d existing file(s). Use --force to overwrite.\n", skipped)
+	}
+
+	return nil
+}
+
+// formatJournalFilename generates the filename for a journal entry.
+//
+// Format: YYYY-MM-DD-slug-shortid.md
+// Uses local time for the date.
+//
+// Parameters:
+//   - s: Session to generate filename for
+//
+// Returns:
+//   - string: Filename like "2026-01-15-gleaming-wobbling-sutherland-abc12345.md"
+func formatJournalFilename(s *parser.Session) string {
+	date := s.StartTime.Local().Format("2006-01-02")
+	shortID := s.ID
+	if len(shortID) > 8 {
+		shortID = shortID[:8]
+	}
+	return fmt.Sprintf("%s-%s-%s.md", date, s.Slug, shortID)
+}
+
+// isEmptyMessage returns true if a message has no meaningful content.
+func isEmptyMessage(msg parser.Message) bool {
+	return msg.Text == "" && len(msg.ToolUses) == 0 && len(msg.ToolResults) == 0
+}
+
+// formatJournalEntry generates the Markdown content for a journal entry.
+//
+// Includes metadata, tool usage summary, and full conversation.
+//
+// Parameters:
+//   - s: Session to format
+//
+// Returns:
+//   - string: Complete Markdown content
+func formatJournalEntry(s *parser.Session) string {
+	var sb strings.Builder
+	nl := config.NewlineLF
+	sep := config.Separator
+
+	// Header
+	sb.WriteString(fmt.Sprintf("# %s"+nl+nl, s.Slug))
+
+	// Metadata (use local time)
+	localStart := s.StartTime.Local()
+	sb.WriteString(fmt.Sprintf("**ID**: %s"+nl, s.ID))
+	sb.WriteString(fmt.Sprintf("**Date**: %s"+nl, localStart.Format("2006-01-02")))
+	sb.WriteString(fmt.Sprintf("**Time**: %s"+nl, localStart.Format("15:04:05")))
+	sb.WriteString(fmt.Sprintf("**Duration**: %s"+nl, formatDuration(s.Duration)))
+	sb.WriteString(fmt.Sprintf("**Tool**: %s"+nl, s.Tool))
+	sb.WriteString(fmt.Sprintf("**Project**: %s"+nl, s.Project))
+	if s.GitBranch != "" {
+		sb.WriteString(fmt.Sprintf("**Branch**: %s"+nl, s.GitBranch))
+	}
+	if s.Model != "" {
+		sb.WriteString(fmt.Sprintf("**Model**: %s"+nl, s.Model))
+	}
+	sb.WriteString(nl)
+
+	// Token stats
+	sb.WriteString(fmt.Sprintf("**Turns**: %d"+nl, s.TurnCount))
+	sb.WriteString(fmt.Sprintf("**Tokens**: %s (in: %s, out: %s)"+nl,
+		formatTokens(s.TotalTokens),
+		formatTokens(s.TotalTokensIn),
+		formatTokens(s.TotalTokensOut)))
+	sb.WriteString(nl + sep + nl + nl)
+
+	// Summary section (placeholder for user to fill in)
+	sb.WriteString("## Summary" + nl + nl)
+	sb.WriteString("[Add your summary of this session]" + nl + nl)
+	sb.WriteString(sep + nl + nl)
+
+	// Tool usage summary
+	tools := s.AllToolUses()
+	if len(tools) > 0 {
+		sb.WriteString("## Tool Usage" + nl + nl)
+		toolCounts := make(map[string]int)
+		for _, t := range tools {
+			toolCounts[t.Name]++
+		}
+		for name, count := range toolCounts {
+			sb.WriteString(fmt.Sprintf("- %s: %d"+nl, name, count))
+		}
+		sb.WriteString(nl + sep + nl + nl)
+	}
+
+	// Conversation (skip empty messages, use local time)
+	sb.WriteString("## Conversation" + nl + nl)
+	msgNum := 0
+	for _, msg := range s.Messages {
+		// Skip empty messages
+		if isEmptyMessage(msg) {
+			continue
+		}
+
+		msgNum++
+		role := "User"
+		if msg.IsAssistant() {
+			role = "Assistant"
+		} else if len(msg.ToolResults) > 0 && msg.Text == "" {
+			// User messages with only tool results are system responses, not user input
+			role = "Tool Output"
+		}
+
+		localTime := msg.Timestamp.Local()
+		sb.WriteString(fmt.Sprintf("### %d. %s (%s)"+nl+nl,
+			msgNum, role, localTime.Format("15:04:05")))
+
+		if msg.Text != "" {
+			sb.WriteString(msg.Text + nl + nl)
+		}
+
+		// Tool uses
+		for _, t := range msg.ToolUses {
+			sb.WriteString(fmt.Sprintf("🔧 **%s**"+nl, formatToolUse(t)))
+		}
+
+		// Tool results (these contain command output, file contents, etc.)
+		for _, tr := range msg.ToolResults {
+			if tr.IsError {
+				sb.WriteString("❌ Error" + nl)
+			}
+			if tr.Content != "" {
+				content := stripLineNumbers(tr.Content)
+				sb.WriteString(fmt.Sprintf("```"+nl+"%s"+nl+"```"+nl, content))
+			}
+		}
+
+		if len(msg.ToolUses) > 0 || len(msg.ToolResults) > 0 {
+			sb.WriteString(nl)
+		}
+	}
+
+	return sb.String()
+}
diff --git a/internal/cli/recall/recall.go b/internal/cli/recall/recall.go
index bd853357f..d95819ea4 100644
--- a/internal/cli/recall/recall.go
+++ b/internal/cli/recall/recall.go
@@ -29,17 +29,19 @@ list sessions, view details, and search across your conversation history.
 Subcommands:
   list    List all parsed sessions
   show    Show details of a specific session
-  serve   Start web server for browsing (coming soon)
+  export  Export sessions to editable journal files
 
 Examples:
   ctx recall list
   ctx recall list --limit 5
   ctx recall show abc123
-  ctx recall show --latest`,
+  ctx recall show --latest
+  ctx recall export --all`,
 	}
 
 	cmd.AddCommand(recallListCmd())
 	cmd.AddCommand(recallShowCmd())
+	cmd.AddCommand(recallExportCmd())
 
 	return cmd
 }
@@ -50,15 +52,16 @@ Examples:
 //   - *cobra.Command: Command for listing parsed sessions
 func recallListCmd() *cobra.Command {
 	var (
-		limit   int
-		project string
-		tool    string
+		limit       int
+		project     string
+		tool        string
+		allProjects bool
 	)
 
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List all parsed sessions",
-		Long: `List all AI sessions found in ~/.claude/projects/ and other locations.
+		Long: `List AI sessions from the current project.
 
 Sessions are sorted by date (newest first) and display:
   - Session slug (human-friendly name)
@@ -67,19 +70,24 @@ Sessions are sorted by date (newest first) and display:
   - Turn count (user messages)
   - Token usage
 
+By default, only sessions from the current project are shown.
+Use --all-projects to see sessions from all projects.
+
 Examples:
   ctx recall list
   ctx recall list --limit 5
+  ctx recall list --all-projects
   ctx recall list --project ctx
   ctx recall list --tool claude-code`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runRecallList(cmd, limit, project, tool)
+			return runRecallList(cmd, limit, project, tool, allProjects)
 		},
 	}
 
 	cmd.Flags().IntVarP(&limit, "limit", "n", 20, "Maximum sessions to display")
 	cmd.Flags().StringVarP(&project, "project", "p", "", "Filter by project name")
 	cmd.Flags().StringVarP(&tool, "tool", "t", "", "Filter by tool (e.g., claude-code)")
+	cmd.Flags().BoolVar(&allProjects, "all-projects", false, "Include sessions from all projects")
 
 	return cmd
 }
@@ -90,8 +98,9 @@ Examples:
 //   - *cobra.Command: Command for showing session details
 func recallShowCmd() *cobra.Command {
 	var (
-		latest bool
-		full   bool
+		latest      bool
+		full        bool
+		allProjects bool
 	)
 
 	cmd := &cobra.Command{
@@ -105,19 +114,22 @@ The session ID can be:
   - Session slug name
 
 Use --latest to show the most recent session.
+By default, only searches sessions from the current project.
 
 Examples:
   ctx recall show abc123
   ctx recall show gleaming-wobbling-sutherland
   ctx recall show --latest
-  ctx recall show --latest --full`,
+  ctx recall show --latest --full
+  ctx recall show abc123 --all-projects`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runRecallShow(cmd, args, latest, full)
+			return runRecallShow(cmd, args, latest, full, allProjects)
 		},
 	}
 
 	cmd.Flags().BoolVar(&latest, "latest", false, "Show the most recent session")
 	cmd.Flags().BoolVar(&full, "full", false, "Show full message content")
+	cmd.Flags().BoolVar(&allProjects, "all-projects", false, "Search sessions from all projects")
 
 	return cmd
 }
diff --git a/internal/cli/recall/run.go b/internal/cli/recall/run.go
index 91dcd4bd2..b022ca66d 100644
--- a/internal/cli/recall/run.go
+++ b/internal/cli/recall/run.go
@@ -9,18 +9,16 @@ package recall
 import (
 	"encoding/json"
 	"fmt"
-	"regexp"
+	"os"
 	"strings"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
 
+	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/recall/parser"
 )
 
-// lineNumberPattern matches Claude Code's line number prefixes like "     1→"
-var lineNumberPattern = regexp.MustCompile(`(?m)^\s*\d+→`)
-
 // runRecallList handles the recall list command.
 //
 // Finds all sessions, applies optional filters, and displays them in a
@@ -31,19 +29,36 @@ var lineNumberPattern = regexp.MustCompile(`(?m)^\s*\d+→`)
 //   - limit: Maximum sessions to display (0 for unlimited)
 //   - project: Filter by project name (case-insensitive substring match)
 //   - tool: Filter by tool identifier (exact match)
+//   - allProjects: If true, include sessions from all projects
 //
 // Returns:
 //   - error: Non-nil if session scanning fails
-func runRecallList(cmd *cobra.Command, limit int, project, tool string) error {
-	sessions, err := parser.FindSessions()
+func runRecallList(cmd *cobra.Command, limit int, project, tool string, allProjects bool) error {
+	var sessions []*parser.Session
+	var err error
+
+	if allProjects {
+		sessions, err = parser.FindSessions()
+	} else {
+		cwd, cwdErr := os.Getwd()
+		if cwdErr != nil {
+			return fmt.Errorf("failed to get working directory: %w", cwdErr)
+		}
+		sessions, err = parser.FindSessionsForCWD(cwd)
+	}
 	if err != nil {
 		return fmt.Errorf("failed to find sessions: %w", err)
 	}
 
 	if len(sessions) == 0 {
-		fmt.Fprintln(cmd.OutOrStdout(), "No sessions found.")
-		fmt.Fprintln(cmd.OutOrStdout(), "")
-		fmt.Fprintln(cmd.OutOrStdout(), "Sessions are stored in ~/.claude/projects/")
+		if allProjects {
+			cmd.Println("No sessions found.")
+			cmd.Println("")
+			cmd.Println("Sessions are stored in ~/.claude/projects/")
+		} else {
+			cmd.Println("No sessions found for this project.")
+			cmd.Println("Use --all-projects to see sessions from all projects.")
+		}
 		return nil
 	}
 
@@ -134,17 +149,32 @@ func runRecallList(cmd *cobra.Command, limit int, project, tool string) error {
 //   - args: Session ID or slug to show (ignored if latest is true)
 //   - latest: If true, show the most recent session
 //   - full: If true, show complete conversation instead of preview
+//   - allProjects: If true, search sessions from all projects
 //
 // Returns:
 //   - error: Non-nil if session not found or scanning fails
-func runRecallShow(cmd *cobra.Command, args []string, latest, full bool) error {
-	sessions, err := parser.FindSessions()
+func runRecallShow(cmd *cobra.Command, args []string, latest, full, allProjects bool) error {
+	var sessions []*parser.Session
+	var err error
+
+	if allProjects {
+		sessions, err = parser.FindSessions()
+	} else {
+		cwd, cwdErr := os.Getwd()
+		if cwdErr != nil {
+			return fmt.Errorf("failed to get working directory: %w", cwdErr)
+		}
+		sessions, err = parser.FindSessionsForCWD(cwd)
+	}
 	if err != nil {
 		return fmt.Errorf("failed to find sessions: %w", err)
 	}
 
 	if len(sessions) == 0 {
-		return fmt.Errorf("no sessions found")
+		if allProjects {
+			return fmt.Errorf("no sessions found")
+		}
+		return fmt.Errorf("no sessions found for this project; use --all-projects to search all")
 	}
 
 	var session *parser.Session
@@ -233,6 +263,10 @@ func runRecallShow(cmd *cobra.Command, args []string, latest, full bool) error {
 			if msg.IsAssistant() {
 				role = "Assistant"
 				roleColor = color.New(color.FgGreen, color.Bold)
+			} else if len(msg.ToolResults) > 0 && msg.Text == "" {
+				// User messages with only tool results are system responses
+				role = "Tool Output"
+				roleColor = color.New(color.FgYellow)
 			}
 
 			roleColor.Fprintf(cmd.OutOrStdout(), "### %d. %s ", i+1, role)
@@ -342,7 +376,7 @@ func formatTokens(tokens int) string {
 // Returns:
 //   - string: Content with line number prefixes removed
 func stripLineNumbers(content string) string {
-	return lineNumberPattern.ReplaceAllString(content, "")
+	return config.RegExLineNumber.ReplaceAllString(content, "")
 }
 
 // formatToolUse formats a tool invocation with its key parameters.
diff --git a/internal/cli/serve/serve.go b/internal/cli/serve/serve.go
new file mode 100644
index 000000000..778e77d24
--- /dev/null
+++ b/internal/cli/serve/serve.go
@@ -0,0 +1,97 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package serve
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/ActiveMemory/ctx/internal/rc"
+)
+
+// Cmd returns the serve command.
+//
+// Serves a static site by invoking zensical serve on the specified directory.
+//
+// Returns:
+//   - *cobra.Command: The serve command
+func Cmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "serve [directory]",
+		Short: "Serve a static site locally via zensical",
+		Long: `Serve a static site using zensical.
+
+If no directory is specified, serves the journal site (.context/journal-site).
+
+Requires zensical to be installed:
+  pip install zensical
+
+Examples:
+  ctx serve                           # Serve journal site
+  ctx serve .context/journal-site     # Serve specific directory
+  ctx serve ./docs                    # Serve docs folder`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runServe(cmd, args)
+		},
+	}
+
+	return cmd
+}
+
+// runServe handles the serve command.
+//
+// Parameters:
+//   - cmd: Cobra command for output stream
+//   - args: Optional directory to serve
+//
+// Returns:
+//   - error: Non-nil if zensical is not found or fails
+func runServe(cmd *cobra.Command, args []string) error {
+	var dir string
+
+	if len(args) > 0 {
+		dir = args[0]
+	} else {
+		// Default: journal site
+		dir = filepath.Join(rc.GetContextDir(), "journal-site")
+	}
+
+	// Verify directory exists
+	info, err := os.Stat(dir)
+	if err != nil {
+		return fmt.Errorf("directory not found: %s", dir)
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("not a directory: %s", dir)
+	}
+
+	// Check zensical.toml exists
+	tomlPath := filepath.Join(dir, "zensical.toml")
+	if _, err := os.Stat(tomlPath); os.IsNotExist(err) {
+		return fmt.Errorf("no zensical.toml found in %s", dir)
+	}
+
+	// Check if zensical is available
+	_, err = exec.LookPath("zensical")
+	if err != nil {
+		return fmt.Errorf("zensical not found. Install with: pip install zensical")
+	}
+
+	// Run zensical serve
+	zensical := exec.Command("zensical", "serve")
+	zensical.Dir = dir
+	zensical.Stdout = os.Stdout
+	zensical.Stderr = os.Stderr
+	zensical.Stdin = os.Stdin
+
+	return zensical.Run()
+}
diff --git a/internal/cli/session/build.go b/internal/cli/session/build.go
index de36bed98..9d505f7c7 100644
--- a/internal/cli/session/build.go
+++ b/internal/cli/session/build.go
@@ -11,6 +11,8 @@ import (
 	"os"
 	"strings"
 	"time"
+
+	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 // buildSessionContent creates the Markdown content for a session file.
@@ -31,12 +33,14 @@ func buildSessionContent(
 	topic, sessionType string, timestamp time.Time,
 ) (string, error) {
 	var sb strings.Builder
+	nl := config.NewlineLF
+	sep := config.Separator
 
 	// Header with timestamp fields for session correlation
-	sb.WriteString(fmt.Sprintf("# Session: %s\n\n", topic))
-	sb.WriteString(fmt.Sprintf("**Date**: %s\n", timestamp.Format("2006-01-02")))
-	sb.WriteString(fmt.Sprintf("**Time**: %s\n", timestamp.Format("15:04:05")))
-	sb.WriteString(fmt.Sprintf("**Type**: %s\n", sessionType))
+	sb.WriteString(fmt.Sprintf("# Session: %s"+nl+nl, topic))
+	sb.WriteString(fmt.Sprintf("**Date**: %s"+nl, timestamp.Format("2006-01-02")))
+	sb.WriteString(fmt.Sprintf("**Time**: %s"+nl, timestamp.Format("15:04:05")))
+	sb.WriteString(fmt.Sprintf("**Type**: %s"+nl, sessionType))
 
 	// Session correlation timestamps
 	// (YYYY-MM-DD-HHMM format matches ctx add timestamps)
@@ -49,61 +53,61 @@ func buildSessionContent(
 		}
 	}
 	sb.WriteString(
-		fmt.Sprintf("**start_time**: %s\n", startTime.Format("2006-01-02-1504")),
+		fmt.Sprintf("**start_time**: %s"+nl, startTime.Format("2006-01-02-1504")),
 	)
 	sb.WriteString(
-		fmt.Sprintf("**end_time**: %s\n", timestamp.Format("2006-01-02-1504")),
+		fmt.Sprintf("**end_time**: %s"+nl, timestamp.Format("2006-01-02-1504")),
 	)
-	sb.WriteString("\n---\n\n")
+	sb.WriteString(nl + sep + nl + nl)
 
 	// Summary section (placeholder for the user to fill in)
-	sb.WriteString("## Summary\n\n")
-	sb.WriteString("[Describe what was accomplished in this session]\n\n")
-	sb.WriteString("---\n\n")
+	sb.WriteString("## Summary" + nl + nl)
+	sb.WriteString("[Describe what was accomplished in this session]" + nl + nl)
+	sb.WriteString(sep + nl + nl)
 
 	// Current Tasks
-	sb.WriteString("## Current Tasks\n\n")
+	sb.WriteString("## Current Tasks" + nl + nl)
 	tasks, err := readContextSection(
 		"TASKS.md", "## In Progress", "## Next Up",
 	)
 	if err == nil && tasks != "" {
-		sb.WriteString("### In Progress\n\n")
+		sb.WriteString("### In Progress" + nl + nl)
 		sb.WriteString(tasks)
-		sb.WriteString("\n")
+		sb.WriteString(nl)
 	}
 	nextTasks, err := readContextSection(
 		"TASKS.md", "## Next Up", "## Completed",
 	)
 	if err == nil && nextTasks != "" {
-		sb.WriteString("### Next Up\n\n")
+		sb.WriteString("### Next Up" + nl + nl)
 		sb.WriteString(nextTasks)
-		sb.WriteString("\n")
+		sb.WriteString(nl)
 	}
-	sb.WriteString("---\n\n")
+	sb.WriteString(sep + nl + nl)
 
 	// Recent Decisions
-	sb.WriteString("## Recent Decisions\n\n")
+	sb.WriteString("## Recent Decisions" + nl + nl)
 	decisions, err := readRecentDecisions()
 	if err == nil && decisions != "" {
 		sb.WriteString(decisions)
 	} else {
-		sb.WriteString("[No recent decisions found]\n")
+		sb.WriteString("[No recent decisions found]" + nl)
 	}
-	sb.WriteString("\n---\n\n")
+	sb.WriteString(nl + sep + nl + nl)
 
 	// Recent Learnings
-	sb.WriteString("## Recent Learnings\n\n")
+	sb.WriteString("## Recent Learnings" + nl + nl)
 	learnings, err := readRecentLearnings()
 	if err == nil && learnings != "" {
 		sb.WriteString(learnings)
 	} else {
-		sb.WriteString("[No recent learnings found]\n")
+		sb.WriteString("[No recent learnings found]" + nl)
 	}
-	sb.WriteString("\n---\n\n")
+	sb.WriteString(nl + sep + nl + nl)
 
 	// Tasks for Next Session
-	sb.WriteString("## Tasks for Next Session\n\n")
-	sb.WriteString("[List tasks to continue in the next session]\n\n")
+	sb.WriteString("## Tasks for Next Session" + nl + nl)
+	sb.WriteString("[List tasks to continue in the next session]" + nl + nl)
 
 	return sb.String(), nil
 }
diff --git a/internal/cli/session/extract.go b/internal/cli/session/extract.go
index b556e7f4a..67bc381e4 100644
--- a/internal/cli/session/extract.go
+++ b/internal/cli/session/extract.go
@@ -11,7 +11,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
-	"regexp"
+
+	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 // extractInsights parses a JSONL transcript and extracts potential decisions
@@ -43,25 +44,6 @@ func extractInsights(path string) ([]string, []string, error) {
 	var decisions []string
 	var learnings []string
 
-	// Patterns for detecting decisions
-	decisionPatterns := []*regexp.Regexp{
-		regexp.MustCompile(`(?i)decided to\s+(.{20,100})`),
-		regexp.MustCompile(`(?i)decision:\s*(.{20,100})`),
-		regexp.MustCompile(`(?i)we('ll| will) use\s+(.{10,80})`),
-		regexp.MustCompile(`(?i)going with\s+(.{10,80})`),
-		regexp.MustCompile(`(?i)chose\s+(.{10,80})\s+(over|instead)`),
-	}
-
-	// Patterns for detecting learnings
-	learningPatterns := []*regexp.Regexp{
-		regexp.MustCompile(`(?i)learned that\s+(.{20,100})`),
-		regexp.MustCompile(`(?i)gotcha:\s*(.{20,100})`),
-		regexp.MustCompile(`(?i)lesson:\s*(.{20,100})`),
-		regexp.MustCompile(`(?i)TIL:?\s*(.{20,100})`),
-		regexp.MustCompile(`(?i)turns out\s+(.{20,100})`),
-		regexp.MustCompile(`(?i)important to (note|remember):\s*(.{20,100})`),
-	}
-
 	scanner := bufio.NewScanner(file)
 	buf := make([]byte, 0, 64*1024)
 	scanner.Buffer(buf, 10*1024*1024)
@@ -89,7 +71,7 @@ func extractInsights(path string) ([]string, []string, error) {
 
 		for _, text := range texts {
 			// Check for decisions
-			for _, pattern := range decisionPatterns {
+			for _, pattern := range config.RegExDecisionPatterns {
 				matches := pattern.FindAllStringSubmatch(text, -1)
 				for _, match := range matches {
 					if len(match) > 1 {
@@ -103,7 +85,7 @@ func extractInsights(path string) ([]string, []string, error) {
 			}
 
 			// Check for learnings
-			for _, pattern := range learningPatterns {
+			for _, pattern := range config.RegExLearningPatterns {
 				matches := pattern.FindAllStringSubmatch(text, -1)
 				for _, match := range matches {
 					if len(match) > 1 {
diff --git a/internal/cli/session/fs.go b/internal/cli/session/fs.go
new file mode 100644
index 000000000..c765c23ae
--- /dev/null
+++ b/internal/cli/session/fs.go
@@ -0,0 +1,22 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package session
+
+import (
+	"path/filepath"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
+)
+
+// sessionsDirPath returns the path to the `sessions` directory.
+//
+// Returns:
+//   - string: Full path to .context/sessions/
+func sessionsDirPath() string {
+	return filepath.Join(rc.GetContextDir(), config.DirSessions)
+}
diff --git a/internal/cli/session/parse.go b/internal/cli/session/parse.go
index 99b6d47ea..ba2ba6e06 100644
--- a/internal/cli/session/parse.go
+++ b/internal/cli/session/parse.go
@@ -13,6 +13,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 // parseIndex attempts to parse a string as a positive integer index.
@@ -59,9 +61,10 @@ func parseJsonlTranscript(path string) (string, error) {
 	}(file)
 
 	var sb strings.Builder
-	sb.WriteString("# Conversation Transcript\n\n")
-	sb.WriteString(fmt.Sprintf("**Source**: %s\n\n", filepath.Base(path)))
-	sb.WriteString("---\n\n")
+	nl := config.NewlineLF
+	sb.WriteString("# Conversation Transcript" + nl + nl)
+	sb.WriteString(fmt.Sprintf("**Source**: %s"+nl+nl, filepath.Base(path)))
+	sb.WriteString(config.Separator + nl + nl)
 
 	scanner := bufio.NewScanner(file)
 	// Increase buffer size for large lines
@@ -90,7 +93,7 @@ func parseJsonlTranscript(path string) (string, error) {
 		formatted := formatTranscriptEntry(entry)
 		if formatted != "" {
 			sb.WriteString(formatted)
-			sb.WriteString("\n---\n\n")
+			sb.WriteString(nl + config.Separator + nl + nl)
 		}
 	}
 
@@ -98,7 +101,7 @@ func parseJsonlTranscript(path string) (string, error) {
 		return "", fmt.Errorf("error reading file: %w", err)
 	}
 
-	sb.WriteString(fmt.Sprintf("*Total messages: %d*\n", messageCount))
+	sb.WriteString(fmt.Sprintf("*Total messages: %d*"+nl, messageCount))
 
 	return sb.String(), nil
 }
@@ -160,7 +163,7 @@ func parseSessionFile(path string) (sessionInfo, error) {
 		for _, line := range lines {
 			line = strings.TrimSpace(line)
 			if line != "" && !strings.HasPrefix(line, "#") &&
-				!strings.HasPrefix(line, "---") &&
+				!strings.HasPrefix(line, config.Separator) &&
 				!strings.HasPrefix(line, "[") {
 				info.Summary = line
 				break
diff --git a/internal/cli/session/read.go b/internal/cli/session/read.go
index 26c00758a..9fb10fd86 100644
--- a/internal/cli/session/read.go
+++ b/internal/cli/session/read.go
@@ -10,12 +10,29 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strings"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
+// readContextFile reads a context file and returns its content as a string.
+//
+// Parameters:
+//   - fileName: Name of the file in .context/ (e.g., "DECISIONS.md")
+//
+// Returns:
+//   - string: File content
+//   - error: Non-nil if the file cannot be read
+func readContextFile(fileName string) (string, error) {
+	filePath := filepath.Join(rc.GetContextDir(), fileName)
+	content, err := os.ReadFile(filePath)
+	if err != nil {
+		return "", err
+	}
+	return string(content), nil
+}
+
 // readContextSection reads a section from a context file between two headers.
 //
 // Extracts text between a start header and an optional end header from a
@@ -25,7 +42,8 @@ import (
 // Parameters:
 //   - filename: Name of the file in .context/ (e.g., "TASKS.md")
 //   - startHeader: Header marking the section start (e.g., "## In Progress")
-//   - endHeader: Header marking the section end, or empty string for end of file
+//   - endHeader: Header marking the section end, or empty string for
+//     the end of the file
 //
 // Returns:
 //   - string: Trimmed content between the headers
@@ -34,7 +52,7 @@ import (
 func readContextSection(
 	filename, startHeader, endHeader string,
 ) (string, error) {
-	filePath := filepath.Join(config.ContextDir(), filename)
+	filePath := filepath.Join(rc.GetContextDir(), filename)
 	content, err := os.ReadFile(filePath)
 	if err != nil {
 		return "", err
@@ -71,24 +89,19 @@ func readContextSection(
 //   - string: Formatted list of recent decision titles, or empty if none found
 //   - error: Non-nil if DECISIONS.md cannot be read
 func readRecentDecisions() (string, error) {
-	filePath := filepath.Join(config.ContextDir(), config.FilenameDecision)
-	content, err := os.ReadFile(filePath)
+	contentStr, err := readContextFile(config.FileDecision)
 	if err != nil {
 		return "", err
 	}
 
-	contentStr := string(content)
-
 	// Find decision headers (## [YYYY-MM-DD] Title)
-	re := regexp.MustCompile(`(?m)^## \[\d{4}-\d{2}-\d{2}].*$`)
-	matches := re.FindAllStringIndex(contentStr, -1)
-
+	matches := config.RegExDecision.FindAllStringIndex(contentStr, -1)
 	if len(matches) == 0 {
 		return "", nil
 	}
 
 	// Get the last 3 decisions (most recent)
-	limit := 3
+	limit := config.MaxDecisionsToSummarize
 	if len(matches) < limit {
 		limit = len(matches)
 	}
@@ -102,13 +115,13 @@ func readRecentDecisions() (string, error) {
 		}
 		decision := strings.TrimSpace(contentStr[start:end])
 		// Only include the header for brevity
-		headerEnd := strings.Index(decision, "\n")
+		headerEnd := strings.Index(decision, config.NewlineLF)
 		if headerEnd != -1 {
 			decisions = append(decisions, "- "+decision[:headerEnd])
 		}
 	}
 
-	return strings.Join(decisions, "\n"), nil
+	return strings.Join(decisions, config.NewlineLF), nil
 }
 
 // readRecentLearnings extracts the most recent learnings from LEARNINGS.md.
@@ -120,27 +133,22 @@ func readRecentDecisions() (string, error) {
 //   - string: Formatted list of recent learnings, or empty if none found
 //   - error: Non-nil if LEARNINGS.md cannot be read
 func readRecentLearnings() (string, error) {
-	filePath := filepath.Join(config.ContextDir(), config.FilenameLearning)
-	content, err := os.ReadFile(filePath)
+	contentStr, err := readContextFile(config.FileLearning)
 	if err != nil {
 		return "", err
 	}
 
-	contentStr := string(content)
-
 	// Find learning entries (- **[YYYY-MM-DD]** text)
-	re := regexp.MustCompile(`(?m)^- \*\*\[\d{4}-\d{2}-\d{2}]\*\*.*$`)
-	matches := re.FindAllString(contentStr, -1)
-
+	matches := config.RegExLearning.FindAllString(contentStr, -1)
 	if len(matches) == 0 {
 		return "", nil
 	}
 
 	// Get the last 5 learnings (most recent)
-	limit := 5
+	limit := config.MaxLearningsToSummarize
 	if len(matches) < limit {
 		limit = len(matches)
 	}
 
-	return strings.Join(matches[len(matches)-limit:], "\n"), nil
+	return strings.Join(matches[len(matches)-limit:], config.NewlineLF), nil
 }
diff --git a/internal/cli/session/run.go b/internal/cli/session/run.go
index 792534492..5407d3663 100644
--- a/internal/cli/session/run.go
+++ b/internal/cli/session/run.go
@@ -13,9 +13,10 @@ import (
 	"strings"
 	"time"
 
-	"github.com/ActiveMemory/ctx/internal/validation"
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+
+	"github.com/ActiveMemory/ctx/internal/validation"
 )
 
 // runSessionLoad loads and displays a saved session file.
@@ -73,7 +74,7 @@ func runSessionLoad(cmd *cobra.Command, args []string) error {
 //   - extract: If true, extract decisions/learnings instead of full transcript
 //
 // Returns:
-//   - error: Non-nil if the file not found, parse fails, or write fails
+//   - error: Non-nil if the file is not found, parse fails, or write fails
 func runSessionParse(
 	cmd *cobra.Command, args []string, output string, extract bool,
 ) error {
@@ -203,8 +204,8 @@ func runSessionSave(
 // runSessionList lists saved sessions with summaries.
 //
 // Reads all session files from .context/sessions/, parses their metadata,
-// and displays them sorted by date (newest first). Output includes topic,
-// date, type, summary, and filename for each session.
+// and displays them sorted by date (the newest first). Output includes
+// the topic, date, type, summary, and filename for each session.
 //
 // Parameters:
 //   - cmd: Cobra command for output
diff --git a/internal/cli/session/session.go b/internal/cli/session/session.go
index 6391bfdfc..63d6f9a9f 100644
--- a/internal/cli/session/session.go
+++ b/internal/cli/session/session.go
@@ -7,21 +7,9 @@
 package session
 
 import (
-	"path/filepath"
-
 	"github.com/spf13/cobra"
-
-	"github.com/ActiveMemory/ctx/internal/config"
 )
 
-// sessionsDirPath returns the path to the sessions directory.
-//
-// Returns:
-//   - string: Full path to .context/sessions/
-func sessionsDirPath() string {
-	return filepath.Join(config.ContextDir(), config.DirSessions)
-}
-
 // Cmd returns the session command with subcommands.
 //
 // Provides commands for managing session snapshots that capture
diff --git a/internal/cli/status/out.go b/internal/cli/status/out.go
index 162a4f1e3..1c4d6d912 100644
--- a/internal/cli/status/out.go
+++ b/internal/cli/status/out.go
@@ -47,7 +47,7 @@ func outputStatusJSON(
 			ModTime: f.ModTime.Format(time.RFC3339),
 		}
 		if verbose && !f.IsEmpty {
-			fs.Preview = getContentPreview(string(f.Content), 5)
+			fs.Preview = contentPreview(string(f.Content), 5)
 		}
 		output.Files = append(output.Files, fs)
 	}
@@ -113,7 +113,7 @@ func outputStatusText(
 
 			// Show content preview for non-empty files
 			if !f.IsEmpty {
-				preview := getContentPreview(string(f.Content), 3)
+				preview := contentPreview(string(f.Content), 3)
 				for _, line := range preview {
 					cmd.Printf("      %s\n", dim(line))
 				}
diff --git a/internal/cli/status/preview.go b/internal/cli/status/preview.go
index bfb6eeee4..687783258 100644
--- a/internal/cli/status/preview.go
+++ b/internal/cli/status/preview.go
@@ -6,9 +6,13 @@
 
 package status
 
-import "strings"
+import (
+	"strings"
 
-// getContentPreview returns the first n non-empty, meaningful lines
+	"github.com/ActiveMemory/ctx/internal/config"
+)
+
+// contentPreview returns the first n non-empty, meaningful lines
 // from content.
 //
 // Skips empty lines, YAML frontmatter delimiters, and HTML comments.
@@ -20,8 +24,8 @@ import "strings"
 //
 // Returns:
 //   - []string: Up to n meaningful lines from the content
-func getContentPreview(content string, n int) []string {
-	lines := strings.Split(content, "\n")
+func contentPreview(content string, n int) []string {
+	lines := strings.Split(content, config.NewlineLF)
 	var preview []string
 
 	inFrontmatter := false
@@ -34,7 +38,7 @@ func getContentPreview(content string, n int) []string {
 		}
 
 		// Skip YAML frontmatter
-		if trimmed == "---" {
+		if trimmed == config.Separator {
 			inFrontmatter = !inFrontmatter
 			continue
 		}
@@ -43,13 +47,14 @@ func getContentPreview(content string, n int) []string {
 		}
 
 		// Skip HTML comments
-		if strings.HasPrefix(trimmed, "<!--") {
+		if strings.HasPrefix(trimmed, config.CommentOpen) {
 			continue
 		}
 
 		// Truncate long lines
-		if len(trimmed) > 60 {
-			trimmed = trimmed[:57] + "..."
+		if len(trimmed) > config.MaxPreviewLen {
+			truncateAt := config.MaxPreviewLen - len(config.Ellipsis)
+			trimmed = trimmed[:truncateAt] + config.Ellipsis
 		}
 
 		preview = append(preview, trimmed)
diff --git a/internal/cli/status/sort.go b/internal/cli/status/sort.go
index c69cf2574..c6e94620c 100644
--- a/internal/cli/status/sort.go
+++ b/internal/cli/status/sort.go
@@ -9,22 +9,22 @@ package status
 import (
 	"sort"
 
-	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // sortFilesByPriority sorts files in-place by the recommended read order.
 //
-// Uses config.FilePriority to determine ordering (CONSTITUTION first,
+// Uses rc.FilePriority to determine ordering (CONSTITUTION first,
 // then TASKS, CONVENTIONS, etc.).
 //
 // Parameters:
 //   - files: Slice of files to sort (modified in place)
 func sortFilesByPriority(files []context.FileInfo) {
 	sort.Slice(files, func(i, j int) bool {
-		return config.FilePriority(
+		return rc.FilePriority(
 			files[i].Name,
-		) < config.FilePriority(files[j].Name)
+		) < rc.FilePriority(files[j].Name)
 	})
 }
 
diff --git a/internal/cli/sync/validate.go b/internal/cli/sync/validate.go
index 25093f8c0..0c51db8bc 100644
--- a/internal/cli/sync/validate.go
+++ b/internal/cli/sync/validate.go
@@ -36,7 +36,7 @@ func checkPackageFiles(ctx *context.Context) []Action {
 			// File exists, check if we have DEPENDENCIES.md or similar
 			hasDepsDoc := false
 			for _, f := range ctx.Files {
-				if f.Name == config.FilenameDependency ||
+				if f.Name == config.FileDependency ||
 					strings.Contains(strings.ToLower(string(f.Content)),
 						"dependencies",
 					) {
@@ -82,7 +82,7 @@ func checkConfigFiles(ctx *context.Context) []Action {
 			// Check if CONVENTIONS.md mentions this
 			var convContent string
 			for _, f := range ctx.Files {
-				if f.Name == config.FilenameConvention {
+				if f.Name == config.FileConvention {
 					convContent = strings.ToLower(string(f.Content))
 					break
 				}
@@ -124,7 +124,7 @@ func checkNewDirectories(ctx *context.Context) []Action {
 	// Get ARCHITECTURE.md content
 	var archContent string
 	for _, f := range ctx.Files {
-		if f.Name == config.FilenameArchitecture {
+		if f.Name == config.FileArchitecture {
 			archContent = strings.ToLower(string(f.Content))
 			break
 		}
diff --git a/internal/cli/task/count.go b/internal/cli/task/count.go
new file mode 100644
index 000000000..dfd55624c
--- /dev/null
+++ b/internal/cli/task/count.go
@@ -0,0 +1,30 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/task"
+)
+
+// countPendingTasks counts top-level unchecked tasks in the lines.
+//
+// Parameters:
+//   - lines: Lines from TASKS.md to scan
+//
+// Returns:
+//   - int: Number of top-level unchecked tasks
+func countPendingTasks(lines []string) int {
+	count := 0
+	for _, line := range lines {
+		match := config.RegExTask.FindStringSubmatch(line)
+		if match != nil && task.IsPending(match) && !task.IsSubTask(match) {
+			count++
+		}
+	}
+	return count
+}
diff --git a/internal/cli/task/path.go b/internal/cli/task/path.go
index 7e65d3e23..6861ae075 100644
--- a/internal/cli/task/path.go
+++ b/internal/cli/task/path.go
@@ -4,6 +4,7 @@ import (
 	"path/filepath"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // tasksFilePath returns the path to TASKS.md.
@@ -11,7 +12,7 @@ import (
 // Returns:
 //   - string: Full path to .context/TASKS.md
 func tasksFilePath() string {
-	return filepath.Join(config.ContextDir(), config.FilenameTask)
+	return filepath.Join(rc.GetContextDir(), config.FileTask)
 }
 
 // archiveDirPath returns the path to the archive directory.
@@ -19,5 +20,5 @@ func tasksFilePath() string {
 // Returns:
 //   - string: Full path to .context/archive/
 func archiveDirPath() string {
-	return filepath.Join(config.ContextDir(), config.DirArchive)
+	return filepath.Join(rc.GetContextDir(), config.DirArchive)
 }
diff --git a/internal/cli/task/process.go b/internal/cli/task/process.go
index e05d6d865..531c06571 100644
--- a/internal/cli/task/process.go
+++ b/internal/cli/task/process.go
@@ -8,8 +8,10 @@ package task
 
 import (
 	"bufio"
-	"regexp"
 	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/task"
 )
 
 // separateTasks parses TASKS.md and separates completed from pending tasks.
@@ -33,17 +35,13 @@ func separateTasks(content string) (string, string, taskStats) {
 	var remaining strings.Builder
 	var archived strings.Builder
 	var stats taskStats
+	nl := config.NewlineLF
 
 	// Track the current phase header
 	var currentPhase string
 	var phaseHasArchivedTasks bool
 	var phaseArchiveBuffer strings.Builder
 
-	completedPattern := regexp.MustCompile(`^\s*-\s*\[x\]`)
-	pendingPattern := regexp.MustCompile(`^\s*-\s*\[\s*\]`)
-	phasePattern := regexp.MustCompile(`^###\s+Phase`)
-	subTaskPattern := regexp.MustCompile(`^\s{2,}-\s*\[`)
-
 	scanner := bufio.NewScanner(strings.NewReader(content))
 	var inCompletedTask bool
 
@@ -51,59 +49,57 @@ func separateTasks(content string) (string, string, taskStats) {
 		line := scanner.Text()
 
 		// Check for phase headers
-		if phasePattern.MatchString(line) {
+		if config.RegExPhase.MatchString(line) {
 			// Flush previous phase's archived tasks
 			if phaseHasArchivedTasks {
-				archived.WriteString(currentPhase + "\n")
+				archived.WriteString(currentPhase + nl)
 				archived.WriteString(phaseArchiveBuffer.String())
-				archived.WriteString("\n")
+				archived.WriteString(nl)
 			}
 
 			currentPhase = line
 			phaseHasArchivedTasks = false
 			phaseArchiveBuffer.Reset()
-			remaining.WriteString(line + "\n")
+			remaining.WriteString(line + nl)
 			inCompletedTask = false
 			continue
 		}
 
-		// Check for completed tasks
-		if completedPattern.MatchString(line) {
-			stats.completed++
-			phaseHasArchivedTasks = true
-			phaseArchiveBuffer.WriteString(line + "\n")
-			inCompletedTask = true
-			continue
-		}
-
-		// Check for pending tasks
-		if pendingPattern.MatchString(line) {
-			stats.pending++
-			remaining.WriteString(line + "\n")
-			inCompletedTask = false
-			continue
-		}
+		// Check if the line is a task item
+		match := config.RegExTask.FindStringSubmatch(line)
+		if match != nil {
+			if task.IsSubTask(match) {
+				// Handle subtasks - follow their parent
+				if inCompletedTask {
+					phaseArchiveBuffer.WriteString(line + nl)
+				} else {
+					remaining.WriteString(line + nl)
+				}
+				continue
+			}
 
-		// Handle subtasks (indented task items)
-		if subTaskPattern.MatchString(line) {
-			if inCompletedTask {
-				// Subtask of a completed task - archive it
-				phaseArchiveBuffer.WriteString(line + "\n")
+			// Top-level task
+			if task.Completed(match) {
+				stats.completed++
+				phaseHasArchivedTasks = true
+				phaseArchiveBuffer.WriteString(line + nl)
+				inCompletedTask = true
 			} else {
-				// Subtask of a pending task - keep it
-				remaining.WriteString(line + "\n")
+				stats.pending++
+				remaining.WriteString(line + nl)
+				inCompletedTask = false
 			}
 			continue
 		}
 
 		// Non-task lines go to the remaining
-		remaining.WriteString(line + "\n")
+		remaining.WriteString(line + nl)
 		inCompletedTask = false
 	}
 
 	// Flush final phase's archived tasks
 	if phaseHasArchivedTasks {
-		archived.WriteString(currentPhase + "\n")
+		archived.WriteString(currentPhase + nl)
 		archived.WriteString(phaseArchiveBuffer.String())
 	}
 
diff --git a/internal/cli/task/run.go b/internal/cli/task/run.go
index 85aa00e84..cc29bc499 100644
--- a/internal/cli/task/run.go
+++ b/internal/cli/task/run.go
@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/ActiveMemory/ctx/internal/cli/compact"
+	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/validation"
 )
 
@@ -64,8 +65,11 @@ func runTasksSnapshot(cmd *cobra.Command, args []string) error {
 	snapshotPath := filepath.Join(archivePath, snapshotFilename)
 
 	// Add snapshot header
+	nl := config.NewlineLF
 	snapshotContent := fmt.Sprintf(
-		"# TASKS.md Snapshot — %s\n\nCreated: %s\n\n---\n\n%s",
+		"# TASKS.md Snapshot — %s"+
+			nl+nl+
+			"Created: %s"+nl+nl+config.Separator+nl+nl+"%s",
 		name, now.Format(time.RFC3339), string(content),
 	)
 
@@ -76,7 +80,7 @@ func runTasksSnapshot(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("failed to write snapshot: %w", err)
 	}
 
-	fmt.Printf("%s Snapshot saved to %s\n", green("✓"), snapshotPath)
+	cmd.Printf("%s Snapshot saved to %s"+nl, green("✓"), snapshotPath)
 
 	return nil
 }
@@ -98,6 +102,7 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 	yellow := color.New(color.FgYellow).SprintFunc()
 	tasksPath := tasksFilePath()
 	archiveDir := archiveDirPath()
+	nl := config.NewlineLF
 
 	// Check if TASKS.md exists
 	if _, err := os.Stat(tasksPath); os.IsNotExist(err) {
@@ -110,7 +115,7 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 		return fmt.Errorf("failed to read TASKS.md: %w", err)
 	}
 
-	lines := strings.Split(string(content), "\n")
+	lines := strings.Split(string(content), nl)
 
 	// Parse task blocks using block-based parsing
 	blocks := compact.ParseTaskBlocks(lines)
@@ -123,8 +128,8 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 			archivableBlocks = append(archivableBlocks, block)
 		} else {
 			skippedCount++
-			fmt.Printf(
-				"%s Skipping (has incomplete children): %s\n",
+			cmd.Printf(
+				"%s Skipping (has incomplete children): %s"+nl,
 				yellow("!"), block.ParentTaskText(),
 			)
 		}
@@ -135,12 +140,12 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 
 	if len(archivableBlocks) == 0 {
 		if skippedCount > 0 {
-			fmt.Printf(
-				"No tasks to archive (%d skipped due to incomplete children).\n",
+			cmd.Printf(
+				"No tasks to archive (%d skipped due to incomplete children)."+nl,
 				skippedCount,
 			)
 		} else {
-			fmt.Println("No completed tasks to archive.")
+			cmd.Println("No completed tasks to archive.")
 		}
 		return nil
 	}
@@ -149,21 +154,21 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 	var archivedContent strings.Builder
 	for _, block := range archivableBlocks {
 		archivedContent.WriteString(block.BlockContent())
-		archivedContent.WriteString("\n")
+		archivedContent.WriteString(nl)
 	}
 
 	if dryRun {
-		fmt.Println(yellow("Dry run - no files modified"))
-		fmt.Println()
-		fmt.Printf(
-			"Would archive %d completed tasks (keeping %d pending)\n",
+		cmd.Println(yellow("Dry run - no files modified"))
+		cmd.Println()
+		cmd.Printf(
+			"Would archive %d completed tasks (keeping %d pending)"+nl,
 			len(archivableBlocks), pendingCount,
 		)
-		fmt.Println()
-		fmt.Println("Archived content preview:")
-		fmt.Println("---")
-		fmt.Print(archivedContent.String())
-		fmt.Println("---")
+		cmd.Println()
+		cmd.Println("Archived content preview:")
+		cmd.Println(config.Separator)
+		cmd.Print(archivedContent.String())
+		cmd.Println(config.Separator)
 		return nil
 	}
 
@@ -180,13 +185,14 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 	// Check if the archive file already exists for today - append if so
 	var finalArchiveContent string
 	if existingContent, err := os.ReadFile(archiveFilePath); err == nil {
-		finalArchiveContent = string(existingContent) + "\n" + archivedContent.String()
+		finalArchiveContent = string(existingContent) +
+			nl + archivedContent.String()
 	} else {
-		finalArchiveContent = fmt.Sprintf(
-			"# Task Archive — %s\n\nArchived from TASKS.md\n\n%s",
-			now.Format("2006-01-02"),
-			archivedContent.String(),
-		)
+		finalArchiveContent = "# Task Archive — " + now.Format("2006-01-02") +
+			nl + nl +
+			"Archived from TASKS.md" +
+			nl + nl +
+			archivedContent.String()
 	}
 
 	// Write the archive file
@@ -198,37 +204,19 @@ func runTaskArchive(cmd *cobra.Command, dryRun bool) error {
 
 	// Remove archived blocks from lines and write back
 	newLines := compact.RemoveBlocksFromLines(lines, archivableBlocks)
-	newContent := strings.Join(newLines, "\n")
+	newContent := strings.Join(newLines, nl)
 
 	if err := os.WriteFile(tasksPath, []byte(newContent), 0644); err != nil {
 		return fmt.Errorf("failed to update TASKS.md: %w", err)
 	}
 
-	fmt.Printf(
-		"%s Archived %d completed tasks to %s\n",
+	cmd.Printf(
+		"%s Archived %d completed tasks to %s"+nl,
 		green("✓"),
 		len(archivableBlocks),
 		archiveFilePath,
 	)
-	fmt.Printf("  %d pending tasks remain in TASKS.md\n", pendingCount)
+	cmd.Printf("  %d pending tasks remain in TASKS.md"+nl, pendingCount)
 
 	return nil
 }
-
-// countPendingTasks counts top-level unchecked tasks in the lines.
-//
-// Parameters:
-//   - lines: Lines from TASKS.md to scan
-//
-// Returns:
-//   - int: Number of top-level unchecked tasks
-func countPendingTasks(lines []string) int {
-	count := 0
-	pattern := compact.UncheckedTaskPattern()
-	for _, line := range lines {
-		if pattern.MatchString(line) && compact.GetIndentLevel(line) == 0 {
-			count++
-		}
-	}
-	return count
-}
diff --git a/internal/cli/watch/apply.go b/internal/cli/watch/apply.go
index 245105733..aa43a3546 100644
--- a/internal/cli/watch/apply.go
+++ b/internal/cli/watch/apply.go
@@ -26,15 +26,15 @@ import (
 //   - error: Non-nil if type is unknown or the handler fails
 func applyUpdate(update ContextUpdate) error {
 	switch update.Type {
-	case config.UpdateTypeTask:
+	case config.EntryTask:
 		return runAddSilent(update)
-	case config.UpdateTypeDecision:
+	case config.EntryDecision:
 		return runAddSilent(update)
-	case config.UpdateTypeLearning:
+	case config.EntryLearning:
 		return runAddSilent(update)
-	case config.UpdateTypeConvention:
+	case config.EntryConvention:
 		return runAddSilent(update)
-	case config.UpdateTypeComplete:
+	case config.EntryComplete:
 		return runCompleteSilent([]string{update.Content})
 	default:
 		return fmt.Errorf("unknown update type: %s", update.Type)
diff --git a/internal/cli/watch/run.go b/internal/cli/watch/run.go
index ba2eaaeaf..7f5b9a7aa 100644
--- a/internal/cli/watch/run.go
+++ b/internal/cli/watch/run.go
@@ -11,7 +11,6 @@ import (
 	"io"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strings"
 
 	"github.com/fatih/color"
@@ -20,6 +19,8 @@ import (
 	"github.com/ActiveMemory/ctx/internal/cli/add"
 	"github.com/ActiveMemory/ctx/internal/config"
 	"github.com/ActiveMemory/ctx/internal/context"
+	"github.com/ActiveMemory/ctx/internal/rc"
+	"github.com/ActiveMemory/ctx/internal/task"
 )
 
 // runWatch executes the watch command logic.
@@ -33,7 +34,7 @@ import (
 //   - _: Unused positional arguments
 //
 // Returns:
-//   - error: Non-nil if context directory is missing, log file cannot
+//   - error: Non-nil if the context directory is missing, the log file cannot
 //     be opened, or stream processing fails
 func runWatch(cmd *cobra.Command, _ []string) error {
 	if !context.Exists("") {
@@ -58,7 +59,7 @@ func runWatch(cmd *cobra.Command, _ []string) error {
 		defer func(file *os.File) {
 			err := file.Close()
 			if err != nil {
-				fmt.Printf("failed to close log file: %v\n", err)
+				cmd.Printf("failed to close log file: %v\n", err)
 			}
 		}(file)
 		reader = file
@@ -81,7 +82,8 @@ func runWatch(cmd *cobra.Command, _ []string) error {
 //     context, rationale, consequences for decisions)
 //
 // Returns:
-//   - error: Non-nil if validation fails, type is unknown, or file operations fail
+//   - error: Non-nil if validation fails, type is unknown,
+//     or file operations fail
 func runAddSilent(update ContextUpdate) error {
 	params := add.EntryParams{
 		Type:         update.Type,
@@ -98,7 +100,8 @@ func runAddSilent(update ContextUpdate) error {
 		return err
 	}
 
-	// Write using shared function (handles formatting, append, and index update)
+	// Write using the shared function
+	// (handles formatting, append, and index update)
 	return add.WriteEntry(params)
 }
 
@@ -121,22 +124,24 @@ func runCompleteSilent(args []string) error {
 	}
 
 	query := args[0]
-	filePath := filepath.Join(config.ContextDir(), config.FilenameTask)
+	filePath := filepath.Join(rc.GetContextDir(), config.FileTask)
+	nl := config.NewlineLF
 
 	content, err := os.ReadFile(filePath)
 	if err != nil {
 		return err
 	}
 
-	lines := strings.Split(string(content), "\n")
-	taskPattern := regexp.MustCompile(`^(\s*)-\s*\[\s*]\s*(.+)$`)
+	lines := strings.Split(string(content), nl)
 
 	matchedLine := -1
 	for i, line := range lines {
-		matches := taskPattern.FindStringSubmatch(line)
-		if matches != nil {
-			taskText := matches[2]
-			if strings.Contains(strings.ToLower(taskText), strings.ToLower(query)) {
+		match := config.RegExTask.FindStringSubmatch(line)
+		if match != nil && task.IsPending(match) {
+			if strings.Contains(
+				strings.ToLower(task.Content(match)),
+				strings.ToLower(query),
+			) {
 				matchedLine = i
 				break
 			}
@@ -147,8 +152,8 @@ func runCompleteSilent(args []string) error {
 		return fmt.Errorf("no task matching %q found", query)
 	}
 
-	lines[matchedLine] = taskPattern.ReplaceAllString(
-		lines[matchedLine], "$1- [x] $2",
+	lines[matchedLine] = config.RegExTask.ReplaceAllString(
+		lines[matchedLine], "$1- [x] $3",
 	)
-	return os.WriteFile(filePath, []byte(strings.Join(lines, "\n")), 0644)
+	return os.WriteFile(filePath, []byte(strings.Join(lines, nl)), 0644)
 }
diff --git a/internal/cli/watch/session.go b/internal/cli/watch/session.go
index 299a28ef5..5dd3443da 100644
--- a/internal/cli/watch/session.go
+++ b/internal/cli/watch/session.go
@@ -14,6 +14,7 @@ import (
 	"time"
 
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // watchAutoSaveSession saves a session snapshot during watch mode.
@@ -28,7 +29,7 @@ import (
 // Returns:
 //   - error: Non-nil if directory creation or file write fails
 func watchAutoSaveSession(updates []ContextUpdate) error {
-	sessionsDir := filepath.Join(config.ContextDir(), config.DirSessions)
+	sessionsDir := filepath.Join(rc.GetContextDir(), config.DirSessions)
 	if err := os.MkdirAll(sessionsDir, 0755); err != nil {
 		return fmt.Errorf("failed to create sessions directory: %w", err)
 	}
@@ -59,14 +60,15 @@ func watchAutoSaveSession(updates []ContextUpdate) error {
 //   - string: Formatted Markdown session content
 func buildWatchSession(timestamp time.Time, updates []ContextUpdate) string {
 	var sb strings.Builder
+	nl := config.NewlineLF
 
-	sb.WriteString("# Watch Mode Session\n\n")
-	sb.WriteString(fmt.Sprintf("**Date**: %s\n", timestamp.Format("2006-01-02")))
-	sb.WriteString(fmt.Sprintf("**Time**: %s\n", timestamp.Format("15:04:05")))
-	sb.WriteString("**Type**: watch-auto-save\n\n")
-	sb.WriteString("---\n\n")
+	sb.WriteString("# Watch Mode Session" + nl + nl)
+	sb.WriteString(fmt.Sprintf("**Date**: %s"+nl, timestamp.Format("2006-01-02")))
+	sb.WriteString(fmt.Sprintf("**Time**: %s"+nl, timestamp.Format("15:04:05")))
+	sb.WriteString("**Type**: watch-auto-save" + nl + nl)
+	sb.WriteString(config.Separator + nl + nl)
 
-	sb.WriteString("## Applied Updates\n\n")
+	sb.WriteString("## Applied Updates" + nl + nl)
 
 	// Group updates by type
 	updatesByType := make(map[string][]string)
@@ -76,34 +78,34 @@ func buildWatchSession(timestamp time.Time, updates []ContextUpdate) string {
 
 	// Write updates by type
 	typeOrder := []string{
-		config.UpdateTypeTask,
-		config.UpdateTypeDecision,
-		config.UpdateTypeLearning,
-		config.UpdateTypeConvention,
-		config.UpdateTypeComplete,
+		config.EntryTask,
+		config.EntryDecision,
+		config.EntryLearning,
+		config.EntryConvention,
+		config.EntryComplete,
 	}
 	for _, t := range typeOrder {
 		contents, ok := updatesByType[t]
 		if !ok || len(contents) == 0 {
 			continue
 		}
-		sb.WriteString(fmt.Sprintf("### %ss\n\n", strings.ToUpper(t[:1])+t[1:]))
+		sb.WriteString(fmt.Sprintf("### %ss"+nl+nl, strings.ToUpper(t[:1])+t[1:]))
 		for _, c := range contents {
-			sb.WriteString(fmt.Sprintf("- %s\n", c))
+			sb.WriteString(fmt.Sprintf("- %s"+nl, c))
 		}
-		sb.WriteString("\n")
+		sb.WriteString(nl)
 	}
 
 	// Add the current context snapshot
-	sb.WriteString("---\n\n")
-	sb.WriteString("## Context Snapshot\n\n")
+	sb.WriteString(config.Separator + nl + nl)
+	sb.WriteString("## Context Snapshot" + nl + nl)
 
-	tasksPath := filepath.Join(config.ContextDir(), config.FilenameTask)
+	tasksPath := filepath.Join(rc.GetContextDir(), config.FileTask)
 	if tasksContent, err := os.ReadFile(tasksPath); err == nil {
-		sb.WriteString("### Current Tasks\n\n")
-		sb.WriteString("```markdown\n")
+		sb.WriteString("### Current Tasks" + nl + nl)
+		sb.WriteString("```markdown" + nl)
 		sb.WriteString(string(tasksContent))
-		sb.WriteString("\n```\n\n")
+		sb.WriteString(nl + "```" + nl + nl)
 	}
 
 	return sb.String()
diff --git a/internal/cli/watch/stream.go b/internal/cli/watch/stream.go
index 61a3f05bf..aa2d49633 100644
--- a/internal/cli/watch/stream.go
+++ b/internal/cli/watch/stream.go
@@ -10,7 +10,6 @@ import (
 	"bufio"
 	"fmt"
 	"io"
-	"regexp"
 	"strings"
 
 	"github.com/fatih/color"
@@ -28,7 +27,7 @@ import (
 // Returns:
 //   - string: Attribute value, or empty string if not found
 func extractAttribute(tag, attrName string) string {
-	pattern := regexp.MustCompile(attrName + `="([^"]*)"`)
+	pattern := config.RegExFromAttrName(attrName)
 	match := pattern.FindStringSubmatch(tag)
 	if len(match) >= 2 {
 		return match[1]
@@ -55,12 +54,6 @@ func processStream(cmd *cobra.Command, reader io.Reader) error {
 	buf := make([]byte, 0, 64*1024)
 	scanner.Buffer(buf, 1024*1024)
 
-	// Pattern to match context-update tags
-	// Captures: 1=full opening tag with attributes, 2=content between tags
-	updatePattern := regexp.MustCompile(
-		`(<context-update\s+[^>]+)>([^<]+)</context-update>`,
-	)
-
 	green := color.New(color.FgGreen).SprintFunc()
 	yellow := color.New(color.FgYellow).SprintFunc()
 	cyan := color.New(color.FgCyan).SprintFunc()
@@ -73,7 +66,7 @@ func processStream(cmd *cobra.Command, reader io.Reader) error {
 		line := scanner.Text()
 
 		// Check for context-update commands
-		matches := updatePattern.FindAllStringSubmatch(line, -1)
+		matches := config.RegExContextUpdate.FindAllStringSubmatch(line, -1)
 		for _, match := range matches {
 			if len(match) >= 3 {
 				openingTag := match[1]
diff --git a/internal/cli/watch/watch_test.go b/internal/cli/watch/watch_test.go
index ff533c96c..02b4190a7 100644
--- a/internal/cli/watch/watch_test.go
+++ b/internal/cli/watch/watch_test.go
@@ -16,6 +16,7 @@ import (
 
 	"github.com/ActiveMemory/ctx/internal/cli/initialize"
 	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // TestApplyUpdate tests the applyUpdate function routing.
@@ -48,48 +49,48 @@ func TestApplyUpdate(t *testing.T) {
 	}{
 		{
 			name:      "task update",
-			update:    ContextUpdate{Type: config.UpdateTypeTask, Content: "Test task from watch"},
-			checkFile: config.FilenameTask,
+			update:    ContextUpdate{Type: config.EntryTask, Content: "Test task from watch"},
+			checkFile: config.FileTask,
 			checkFor:  "Test task from watch",
 		},
 		{
 			name: "decision update",
 			update: ContextUpdate{
-				Type:         config.UpdateTypeDecision,
+				Type:         config.EntryDecision,
 				Content:      "Test decision from watch",
 				Context:      "Testing watch functionality",
 				Rationale:    "Need to verify watch applies decisions",
 				Consequences: "Decision will appear in DECISIONS.md",
 			},
-			checkFile: config.FilenameDecision,
+			checkFile: config.FileDecision,
 			checkFor:  "Test decision from watch",
 		},
 		{
 			name: "learning update",
 			update: ContextUpdate{
-				Type:        config.UpdateTypeLearning,
+				Type:        config.EntryLearning,
 				Content:     "Test learning from watch",
 				Context:     "Testing watch functionality",
 				Lesson:      "Watch can add learnings",
 				Application: "Use structured attributes in context-update tags",
 			},
-			checkFile: config.FilenameLearning,
+			checkFile: config.FileLearning,
 			checkFor:  "Test learning from watch",
 		},
 		{
 			name:        "decision without required fields",
-			update:      ContextUpdate{Type: config.UpdateTypeDecision, Content: "Missing fields"},
+			update:      ContextUpdate{Type: config.EntryDecision, Content: "Missing fields"},
 			expectError: true,
 		},
 		{
 			name:        "learning without required fields",
-			update:      ContextUpdate{Type: config.UpdateTypeLearning, Content: "Missing fields"},
+			update:      ContextUpdate{Type: config.EntryLearning, Content: "Missing fields"},
 			expectError: true,
 		},
 		{
 			name:      "convention update",
-			update:    ContextUpdate{Type: config.UpdateTypeConvention, Content: "Test convention from watch"},
-			checkFile: config.FilenameConvention,
+			update:    ContextUpdate{Type: config.EntryConvention, Content: "Test convention from watch"},
+			checkFile: config.FileConvention,
 			checkFor:  "Test convention from watch",
 		},
 		{
@@ -115,7 +116,7 @@ func TestApplyUpdate(t *testing.T) {
 			}
 
 			// Verify content was added
-			filePath := filepath.Join(config.ContextDir(), tt.checkFile)
+			filePath := filepath.Join(rc.GetContextDir(), tt.checkFile)
 			content, err := os.ReadFile(filePath)
 			if err != nil {
 				t.Fatalf("failed to read %s: %v", tt.checkFile, err)
@@ -149,7 +150,7 @@ func TestApplyCompleteUpdate(t *testing.T) {
 	}
 
 	// Add a task to complete
-	tasksPath := filepath.Join(config.ContextDir(), config.FilenameTask)
+	tasksPath := filepath.Join(rc.GetContextDir(), config.FileTask)
 	tasksContent := `# Tasks
 
 ## Next Up
@@ -162,7 +163,7 @@ func TestApplyCompleteUpdate(t *testing.T) {
 	}
 
 	// Complete the task
-	update := ContextUpdate{Type: config.UpdateTypeComplete, Content: "authentication"}
+	update := ContextUpdate{Type: config.EntryComplete, Content: "authentication"}
 	if err := applyUpdate(update); err != nil {
 		t.Fatalf("applyUpdate failed: %v", err)
 	}
@@ -184,10 +185,10 @@ func TestApplyCompleteUpdate(t *testing.T) {
 func TestBuildWatchSession(t *testing.T) {
 	timestamp := time.Date(2026, 1, 15, 14, 30, 0, 0, time.UTC)
 	updates := []ContextUpdate{
-		{Type: config.UpdateTypeTask, Content: "Task 1"},
-		{Type: config.UpdateTypeTask, Content: "Task 2"},
-		{Type: config.UpdateTypeDecision, Content: "Decision 1"},
-		{Type: config.UpdateTypeLearning, Content: "Learning 1"},
+		{Type: config.EntryTask, Content: "Task 1"},
+		{Type: config.EntryTask, Content: "Task 2"},
+		{Type: config.EntryDecision, Content: "Decision 1"},
+		{Type: config.EntryLearning, Content: "Learning 1"},
 	}
 
 	result := buildWatchSession(timestamp, updates)
@@ -262,7 +263,7 @@ More output
 	}
 
 	// Verify task was written
-	tasksPath := filepath.Join(config.ContextDir(), config.FilenameTask)
+	tasksPath := filepath.Join(rc.GetContextDir(), config.FileTask)
 	content, err := os.ReadFile(tasksPath)
 	if err != nil {
 		t.Fatalf("failed to read tasks: %v", err)
@@ -313,7 +314,7 @@ More output
 	}
 
 	// Verify learning was written with structured fields
-	learningsPath := filepath.Join(config.ContextDir(), config.FilenameLearning)
+	learningsPath := filepath.Join(rc.GetContextDir(), config.FileLearning)
 	content, err := os.ReadFile(learningsPath)
 	if err != nil {
 		t.Fatalf("failed to read learnings: %v", err)
diff --git a/internal/config/config.go b/internal/config/config.go
index d14ff8e4e..ce80a7a55 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -1,222 +1,22 @@
-package config
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
 
-const (
-	CtxMarkerEnd           = "<!-- ctx:end -->"
-	CtxMarkerStart         = "<!-- ctx:context -->"
-	DirArchive             = "archive"
-	DirClaude              = ".claude"
-	DirClaudeHooks         = ".claude/hooks"
-	DirContext             = ".context"
-	DirSessions            = "sessions"
-	FileAutoSave           = "auto-save-session.sh"
-	FileBlockNonPathScript = "block-non-path-ctx.sh"
-	FileClaudeMd           = "CLAUDE.md"
-	FileSettings           = ".claude/settings.local.json"
-)
+package config
 
-// Global flag values set by CLI
-var (
-	// contextDirOverride is set by --context-dir flag
-	contextDirOverride string
-	// Quiet suppresses non-essential output when true
-	Quiet bool
-)
+// MaxDecisionsToSummarize is the number of recent decisions to include
+// in summaries.
+const MaxDecisionsToSummarize = 3
 
-// SetContextDir sets the context directory override.
-//
-// Parameters:
-//   - dir: Directory path to use as override
-func SetContextDir(dir string) {
-	contextDirOverride = dir
-}
+// MaxLearningsToSummarize is the number of recent learnings to include
+// in summaries.
+const MaxLearningsToSummarize = 5
 
-// ContextDir returns the context directory path.
-//
-// Returns the --context-dir override if set, otherwise the default ".context".
-//
-// Returns:
-//   - string: The context directory path
-func ContextDir() string {
-	if contextDirOverride != "" {
-		return contextDirOverride
-	}
-	return DirContext
-}
+// MaxPreviewLen is the maximum length for preview lines before truncation.
+const MaxPreviewLen = 60
 
 // WatchAutoSaveInterval is the number of updates between auto-saves
 // in watch mode.
 const WatchAutoSaveInterval = 5
-
-// Context file name constants.
-const (
-	FilenameConstitution  = "CONSTITUTION.md"
-	FilenameTask          = "TASKS.md"
-	FilenameConvention    = "CONVENTIONS.md"
-	FilenameArchitecture  = "ARCHITECTURE.md"
-	FilenameDecision      = "DECISIONS.md"
-	FilenameLearning      = "LEARNINGS.md"
-	FilenameGlossary      = "GLOSSARY.md"
-	FilenameDrift         = "DRIFT.md"
-	FilenameAgentPlaybook = "AGENT_PLAYBOOK.md"
-	FilenameDependency    = "DEPENDENCIES.md"
-)
-
-// Update type constants for context entries.
-//
-// These are used in switch statements for routing add/update commands
-// to the appropriate handler.
-const (
-	UpdateTypeTask       = "task"
-	UpdateTypeDecision   = "decision"
-	UpdateTypeLearning   = "learning"
-	UpdateTypeConvention = "convention"
-	UpdateTypeComplete   = "complete"
-)
-
-// Plural aliases for update types.
-//
-// Accepted as synonyms for the singular forms.
-const (
-	UpdateTypeTasks       = "tasks"
-	UpdateTypeDecisions   = "decisions"
-	UpdateTypeLearnings   = "learnings"
-	UpdateTypeConventions = "conventions"
-)
-
-// FileType maps short names to actual file names.
-var FileType = map[string]string{
-	UpdateTypeDecision:    FilenameDecision,
-	UpdateTypeDecisions:   FilenameDecision,
-	UpdateTypeTask:        FilenameTask,
-	UpdateTypeTasks:       FilenameTask,
-	UpdateTypeLearning:    FilenameLearning,
-	UpdateTypeLearnings:   FilenameLearning,
-	UpdateTypeConvention:  FilenameConvention,
-	UpdateTypeConventions: FilenameConvention,
-}
-
-// RequiredFiles lists the essential context files that must be present.
-//
-// These are the files created with `ctx init --minimal` and checked by
-// drift detection for missing files.
-var RequiredFiles = []string{
-	FilenameConstitution,
-	FilenameTask,
-	FilenameDecision,
-}
-
-// FileReadOrder defines the priority order for reading context files.
-//
-// The order follows a logical progression for AI agents:
-//
-//  1. CONSTITUTION — Inviolable rules. Must be loaded first so the agent
-//     knows what it cannot do before attempting anything.
-//
-//  2. TASKS — Current work items. What the agent should focus on.
-//
-//  3. CONVENTIONS — How to write code. Patterns and standards to follow.
-//
-//  4. ARCHITECTURE — System structure. Understanding of components and
-//     boundaries before making changes.
-//
-//  5. DECISIONS — Historical context. Why things are the way they are,
-//     to avoid re-debating settled decisions.
-//
-//  6. LEARNINGS — Gotchas and tips. Lessons from past work that inform
-//     current implementation.
-//
-//  7. GLOSSARY — Reference material. Domain terms and abbreviations for
-//     lookup as needed.
-//
-//  8. DRIFT — Staleness indicators. Lower priority since it's primarily
-//     for maintenance workflows.
-//
-//  9. AGENT_PLAYBOOK — Meta instructions. How to use this context system.
-//     Loaded last because it's about the system itself, not the work.
-//     The agent should understand the content before the operating manual.
-var FileReadOrder = []string{
-	FilenameConstitution,
-	FilenameTask,
-	FilenameConvention,
-	FilenameArchitecture,
-	FilenameDecision,
-	FilenameLearning,
-	FilenameGlossary,
-	FilenameDrift,
-	FilenameAgentPlaybook,
-}
-
-// filePriority maps filenames to their priority (derived from FileReadOrder).
-// This is initialized at startup; use FilePriority() which checks for .contextrc overrides.
-var filePriority = func() map[string]int {
-	m := make(map[string]int, len(FileReadOrder))
-	for i, name := range FileReadOrder {
-		m[name] = i + 1
-	}
-	return m
-}()
-
-// Packages maps dependency manifest files to their descriptions.
-//
-// Used by sync to detect projects and suggest dependency documentation.
-var Packages = map[string]string{
-	"package.json":     "Node.js dependencies",
-	"go.mod":           "Go module dependencies",
-	"Cargo.toml":       "Rust dependencies",
-	"requirements.txt": "Python dependencies",
-	"Gemfile":          "Ruby dependencies",
-}
-
-// Pattern represents a config file pattern and its documentation topic.
-//
-// Fields:
-//   - Pattern: Glob pattern to match (e.g., ".eslintrc*")
-//   - Topic: Documentation topic (e.g., "linting conventions")
-type Pattern struct {
-	Pattern string
-	Topic   string
-}
-
-// Patterns lists config files that should be documented in CONVENTIONS.md.
-//
-// Used by sync to suggest documenting project configuration.
-var Patterns = []Pattern{
-	{".eslintrc*", "linting conventions"},
-	{".prettierrc*", "formatting conventions"},
-	{"tsconfig.json", "TypeScript configuration"},
-	{".editorconfig", "editor configuration"},
-	{"Makefile", "build commands"},
-	{"Dockerfile", "containerization"},
-}
-
-// FilePriority returns the priority of a context file.
-//
-// If a priority_order is configured in .contextrc, that order is used.
-// Otherwise, the default FileReadOrder is used.
-//
-// Lower numbers indicate higher priority (1 = highest).
-// Unknown files return 100.
-//
-// Parameters:
-//   - name: Filename to look up (e.g., "TASKS.md")
-//
-// Returns:
-//   - int: Priority value (1-9 for known files, 100 for unknown)
-func FilePriority(name string) int {
-	// Check for .contextrc override
-	if order := GetPriorityOrder(); order != nil {
-		for i, fname := range order {
-			if fname == name {
-				return i + 1
-			}
-		}
-		// File not in custom order gets lowest priority
-		return 100
-	}
-
-	// Use default priority
-	if p, ok := filePriority[name]; ok {
-		return p
-	}
-	return 100
-}
diff --git a/internal/config/dir.go b/internal/config/dir.go
new file mode 100644
index 000000000..c4cf8cec5
--- /dev/null
+++ b/internal/config/dir.go
@@ -0,0 +1,21 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package config
+
+// Directory path constants used throughout the application.
+const (
+	// DirArchive is the subdirectory for archived tasks within .context/.
+	DirArchive = "archive"
+	// DirClaude is the Claude Code configuration directory in the project root.
+	DirClaude = ".claude"
+	// DirClaudeHooks is the hooks subdirectory within .claude/.
+	DirClaudeHooks = ".claude/hooks"
+	// DirContext is the default context directory name.
+	DirContext = ".context"
+	// DirSessions is the subdirectory for session snapshots within .context/.
+	DirSessions = "sessions"
+)
diff --git a/internal/config/entry.go b/internal/config/entry.go
new file mode 100644
index 000000000..bac28ebda
--- /dev/null
+++ b/internal/config/entry.go
@@ -0,0 +1,54 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.
+
+package config
+
+import "strings"
+
+// Entry type constants for context updates.
+//
+// These are the canonical internal representations used in switch statements
+// for routing add/update commands to the appropriate handler.
+const (
+	// EntryTask represents a task entry in TASKS.md.
+	EntryTask = "task"
+	// EntryDecision represents an architectural decision in DECISIONS.md.
+	EntryDecision = "decision"
+	// EntryLearning represents a lesson learned in LEARNINGS.md.
+	EntryLearning = "learning"
+	// EntryConvention represents a code pattern in CONVENTIONS.md.
+	EntryConvention = "convention"
+	// EntryComplete represents a task completion action (marks the task as done).
+	EntryComplete = "complete"
+	// EntryUnknown is returned when user input doesn't match any known type.
+	EntryUnknown = "unknown"
+)
+
+// UserInputToEntry normalizes user input to a canonical entry type.
+//
+// Accepts both singular and plural forms (e.g., "task" or "tasks") and
+// returns the canonical singular form. Matching is case-insensitive.
+// Unknown inputs return EntryUnknown.
+//
+// Parameters:
+//   - s: User-provided entry type string
+//
+// Returns:
+//   - string: Canonical entry type constant (EntryTask, EntryDecision, etc.)
+func UserInputToEntry(s string) string {
+	switch strings.ToLower(s) {
+	case "task", "tasks":
+		return EntryTask
+	case "decision", "decisions":
+		return EntryDecision
+	case "learning", "learnings":
+		return EntryLearning
+	case "convention", "conventions":
+		return EntryConvention
+	default:
+		return EntryUnknown
+	}
+}
diff --git a/internal/config/field.go b/internal/config/field.go
new file mode 100644
index 000000000..e5ac7c6ba
--- /dev/null
+++ b/internal/config/field.go
@@ -0,0 +1,26 @@
+//	/    Context:                     https://ctx.ist
+//
+// ,'`./    do you remember?
+//
+//	`.,'\
+//	  \    Copyright 2026-present Context contributors.
+//	                SPDX-License-Identifier: Apache-2.
+
+package config
+
+// Field name constants for structured entry attributes.
+//
+// These are used in validation error messages and as attribute names
+// in context-update XML tags for decisions and learnings.
+const (
+	// FieldContext is the background/situation field for decisions and learnings.
+	FieldContext = "context"
+	// FieldRationale is the reasoning field for decisions (why this choice).
+	FieldRationale = "rationale"
+	// FieldConsequence is the outcomes field for decisions (what changes).
+	FieldConsequence = "consequences"
+	// FieldApplication is the usage field for learnings (how to apply going forward).
+	FieldApplication = "application"
+	// FieldLesson is the insight field for learnings (the key takeaway).
+	FieldLesson = "lesson"
+)
diff --git a/internal/config/file.go b/internal/config/file.go
new file mode 100644
index 000000000..e460ff7b3
--- /dev/null
+++ b/internal/config/file.go
@@ -0,0 +1,117 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package config
+
+// Claude Code integration file names.
+const (
+	// FileAutoSave is the hook script for auto-saving sessions.
+	FileAutoSave = "auto-save-session.sh"
+	// FileBlockNonPathScript is the hook script that blocks non-PATH ctx
+	// invocations.
+	FileBlockNonPathScript = "block-non-path-ctx.sh"
+	// FilePromptCoach is the hook script for prompt quality feedback.
+	FilePromptCoach = "prompt-coach.sh"
+	// FileClaudeMd is the Claude Code configuration file in the project root.
+	FileClaudeMd = "CLAUDE.md"
+	// FileSettings is the Claude Code local settings file.
+	FileSettings = ".claude/settings.local.json"
+)
+
+// Context file name constants for .context/ directory.
+const (
+	// FileConstitution contains inviolable rules for agents.
+	FileConstitution = "CONSTITUTION.md"
+	// FileTask contains current work items and their status.
+	FileTask = "TASKS.md"
+	// FileConvention contains code patterns and standards.
+	FileConvention = "CONVENTIONS.md"
+	// FileArchitecture contains system structure documentation.
+	FileArchitecture = "ARCHITECTURE.md"
+	// FileDecision contains architectural decisions with rationale.
+	FileDecision = "DECISIONS.md"
+	// FileLearning contains gotchas, tips, and lessons learned.
+	FileLearning = "LEARNINGS.md"
+	// FileGlossary contains domain terms and definitions.
+	FileGlossary = "GLOSSARY.md"
+	// FileDrift contains staleness indicators and drift detection results.
+	FileDrift = "DRIFT.md"
+	// FileAgentPlaybook contains the meta-instructions for using the
+	// context system.
+	FileAgentPlaybook = "AGENT_PLAYBOOK.md"
+	// FileDependency contains project dependency documentation.
+	FileDependency = "DEPENDENCIES.md"
+)
+
+// FileType maps short names to actual file names.
+var FileType = map[string]string{
+	EntryDecision:   FileDecision,
+	EntryTask:       FileTask,
+	EntryLearning:   FileLearning,
+	EntryConvention: FileConvention,
+}
+
+// RequiredFiles lists the essential context files that must be present.
+//
+// These are the files created with `ctx init --minimal` and checked by
+// drift detection for missing files.
+var RequiredFiles = []string{
+	FileConstitution,
+	FileTask,
+	FileDecision,
+}
+
+// FileReadOrder defines the priority order for reading context files.
+//
+// The order follows a logical progression for AI agents:
+//
+//  1. CONSTITUTION — Inviolable rules. Must be loaded first so the agent
+//     knows what it cannot do before attempting anything.
+//
+//  2. TASKS — Current work items. What the agent should focus on.
+//
+//  3. CONVENTIONS — How to write code. Patterns and standards to follow.
+//
+//  4. ARCHITECTURE — System structure. Understanding of components and
+//     boundaries before making changes.
+//
+//  5. DECISIONS — Historical context. Why things are the way they are,
+//     to avoid re-debating settled decisions.
+//
+//  6. LEARNINGS — Gotchas and tips. Lessons from past work that inform
+//     current implementation.
+//
+//  7. GLOSSARY — Reference material. Domain terms and abbreviations for
+//     lookup as needed.
+//
+//  8. DRIFT — Staleness indicators. Lower priority since it's primarily
+//     for maintenance workflows.
+//
+//  9. AGENT_PLAYBOOK — Meta instructions. How to use this context system.
+//     Loaded last because it's about the system itself, not the work.
+//     The agent should understand the content before the operating manual.
+var FileReadOrder = []string{
+	FileConstitution,
+	FileTask,
+	FileConvention,
+	FileArchitecture,
+	FileDecision,
+	FileLearning,
+	FileGlossary,
+	FileDrift,
+	FileAgentPlaybook,
+}
+
+// Packages maps dependency manifest files to their descriptions.
+//
+// Used by sync to detect projects and suggest dependency documentation.
+var Packages = map[string]string{
+	"package.json":     "Node.js dependencies",
+	"go.mod":           "Go module dependencies",
+	"Cargo.toml":       "Rust dependencies",
+	"requirements.txt": "Python dependencies",
+	"Gemfile":          "Ruby dependencies",
+}
diff --git a/internal/config/heading.go b/internal/config/heading.go
new file mode 100644
index 000000000..404d6230c
--- /dev/null
+++ b/internal/config/heading.go
@@ -0,0 +1,27 @@
+//	/    Context:                     https://ctx.ist
+//
+// ,'`./    do you remember?
+//
+//	`.,'\
+//	  \    Copyright 2026-present Context contributors.
+//	                SPDX-License-Identifier: Apache-2.
+
+package config
+
+// Learnings
+const (
+	// HeadingLearningStart is the Markdown heading for entries in LEARNINGS.md
+	HeadingLearningStart = "## ["
+	// HeadingLearnings is the Markdown heading for LEARNINGs.md
+	HeadingLearnings = "# Learnings"
+	// ColumnLearning is the singular column header for learning index tables.
+	ColumnLearning = "Learning"
+)
+
+// Decisions
+const (
+	// HeadingDecisions is the Markdown heading for DECISIONS.md
+	HeadingDecisions = "# Decisions"
+	// ColumnDecision is the singular column header for decision index tables.
+	ColumnDecision = "Decision"
+)
diff --git a/internal/config/marker.go b/internal/config/marker.go
new file mode 100644
index 000000000..0d5acb292
--- /dev/null
+++ b/internal/config/marker.go
@@ -0,0 +1,39 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package config
+
+// HTML comment markers for parsing and generation.
+const (
+	// CommentOpen is the HTML comment opening tag.
+	CommentOpen = "<!--"
+	// CommentClose is the HTML comment closing tag.
+	CommentClose = "-->"
+)
+
+// Context block markers for embedding context in files.
+const (
+	// CtxMarkerStart marks the beginning of an embedded context block.
+	CtxMarkerStart = "<!-- ctx:context -->"
+	// CtxMarkerEnd marks the end of an embedded context block.
+	CtxMarkerEnd = "<!-- ctx:end -->"
+)
+
+// Index markers for auto-generated table of contents sections.
+const (
+	// IndexStart marks the beginning of an auto-generated index.
+	IndexStart = "<!-- INDEX:START -->"
+	// IndexEnd marks the end of an auto-generated index.
+	IndexEnd = "<!-- INDEX:END -->"
+)
+
+// Task checkbox prefixes for Markdown task lists.
+const (
+	// PrefixTaskUndone is the prefix for an unchecked task item.
+	PrefixTaskUndone = "- [ ]"
+	// PrefixTaskDone is the prefix for a checked (completed) task item.
+	PrefixTaskDone = "- [x]"
+)
diff --git a/internal/config/pattern.go b/internal/config/pattern.go
new file mode 100644
index 000000000..9861cc93b
--- /dev/null
+++ b/internal/config/pattern.go
@@ -0,0 +1,29 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.
+
+package config
+
+// Pattern represents a config file pattern and its documentation topic.
+//
+// Fields:
+//   - Pattern: Glob pattern to match (e.g., ".eslintrc*")
+//   - Topic: Documentation topic (e.g., "linting conventions")
+type Pattern struct {
+	Pattern string
+	Topic   string
+}
+
+// Patterns lists config files that should be documented in CONVENTIONS.md.
+//
+// Used by sync to suggest documenting project configuration.
+var Patterns = []Pattern{
+	{".eslintrc*", "linting conventions"},
+	{".prettierrc*", "formatting conventions"},
+	{"tsconfig.json", "TypeScript configuration"},
+	{".editorconfig", "editor configuration"},
+	{"Makefile", "build commands"},
+	{"Dockerfile", "containerization"},
+}
diff --git a/internal/config/regex.go b/internal/config/regex.go
new file mode 100644
index 000000000..597afba83
--- /dev/null
+++ b/internal/config/regex.go
@@ -0,0 +1,119 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package config
+
+import "regexp"
+
+// RegExEntryHeader matches entry headers like "## [2026-01-28-051426] Title here".
+//
+// Groups:
+//   - 1: date (YYYY-MM-DD)
+//   - 2: time (HHMMSS)
+//   - 3: title
+var RegExEntryHeader = regexp.MustCompile(
+	`## \[(\d{4}-\d{2}-\d{2})-(\d{6})] (.+)`,
+)
+
+// RegExLineNumber matches Claude Code's line number prefixes like "     1→".
+var RegExLineNumber = regexp.MustCompile(`(?m)^\s*\d+→`)
+
+// RegExPhase matches phase headers at any heading level (e.g., "## Phase 1", "### Phase").
+var RegExPhase = regexp.MustCompile(`^#{1,6}\s+Phase`)
+
+// RegExBulletItem matches any Markdown bullet item (not just tasks).
+//
+// Groups:
+//   - 1: item content
+var RegExBulletItem = regexp.MustCompile(`(?m)^-\s*(.+)$`)
+
+// RegExDecision matches decision entry headers in multiline content.
+// Use for finding decision positions without capturing groups.
+var RegExDecision = regexp.MustCompile(`(?m)^## \[\d{4}-\d{2}-\d{2}-\d{6}].*$`)
+
+// RegExLearning matches learning entry headers in multiline content.
+// Use for finding learning positions without capturing groups.
+var RegExLearning = regexp.MustCompile(`(?m)^- \*\*\[\d{4}-\d{2}-\d{2}]\*\*.*$`)
+
+// RegExNonFileNameChar matches characters not allowed in file names.
+var RegExNonFileNameChar = regexp.MustCompile(`[^a-zA-Z0-9-]+`)
+
+// RegExEntryHeading matches any entry heading (## [timestamp]).
+// Use for counting entries without capturing groups.
+var RegExEntryHeading = regexp.MustCompile(`(?m)^## \[`)
+
+// RegExPath matches file paths in Markdown backticks.
+//
+// Groups:
+//   - 1: file path
+var RegExPath = regexp.MustCompile("`([^`]+\\.[a-zA-Z]{1,5})`")
+
+// RegExContextUpdate matches context-update XML tags.
+//
+// Groups:
+//   - 1: opening tag attributes (e.g., ` type="task" context="..."`)
+//   - 2: content between tags
+var RegExContextUpdate = regexp.MustCompile(`<context-update(\s+[^>]+)>([^<]+)</context-update>`)
+
+// RegExGlossary matches glossary definition entries (lines with **term**).
+var RegExGlossary = regexp.MustCompile(`(?m)(?:^|\n)\s*(?:-\s*)?\*\*[^*]+\*\*`)
+
+// RegExDecisionPatterns detects decision-like phrases in text.
+var RegExDecisionPatterns = []*regexp.Regexp{
+	regexp.MustCompile(`(?i)decided to\s+(.{20,100})`),
+	regexp.MustCompile(`(?i)decision:\s*(.{20,100})`),
+	regexp.MustCompile(`(?i)we('ll| will) use\s+(.{10,80})`),
+	regexp.MustCompile(`(?i)going with\s+(.{10,80})`),
+	regexp.MustCompile(`(?i)chose\s+(.{10,80})\s+(over|instead)`),
+}
+
+// RegExLearningPatterns detects learning-like phrases in text.
+var RegExLearningPatterns = []*regexp.Regexp{
+	regexp.MustCompile(`(?i)learned that\s+(.{20,100})`),
+	regexp.MustCompile(`(?i)gotcha:\s*(.{20,100})`),
+	regexp.MustCompile(`(?i)lesson:\s*(.{20,100})`),
+	regexp.MustCompile(`(?i)TIL:?\s*(.{20,100})`),
+	regexp.MustCompile(`(?i)turns out\s+(.{20,100})`),
+	regexp.MustCompile(`(?i)important to (note|remember):\s*(.{20,100})`),
+}
+
+// regExTaskPattern captures indent, checkbox state, and content.
+//
+// Pattern: ^(\s*)-\s*\[([x ]?)]\s*(.+)$
+//
+// Groups:
+//   - 1: indent (leading whitespace, may be empty)
+//   - 2: state ("x" for completed, " " or "" for pending)
+//   - 3: content (task text)
+const regExTaskPattern = `^(\s*)-\s*\[([x ]?)]\s*(.+)$`
+
+// RegExTask matches a task item on a single line.
+//
+// Use with MatchString or FindStringSubmatch on individual lines.
+// For multiline content, use RegExTaskMultiline.
+var RegExTask = regexp.MustCompile(regExTaskPattern)
+
+// RegExTaskMultiline matches task items across multiple lines.
+//
+// Use with FindAllStringSubmatch on multiline content.
+var RegExTaskMultiline = regexp.MustCompile(`(?m)` + regExTaskPattern)
+
+// RegExTaskDoneTimestamp extracts the #done: timestamp from a task line.
+//
+// Groups:
+//   - 1: timestamp (YYYY-MM-DD-HHMMSS)
+var RegExTaskDoneTimestamp = regexp.MustCompile(`#done:(\d{4}-\d{2}-\d{2}-\d{6})`)
+
+// RegExFromAttrName creates a regex to extract an XML attribute value by name.
+//
+// Parameters:
+//   - name: The attribute name to match
+//
+// Returns:
+//   - *regexp.Regexp: Pattern matching name="value" with value in group 1
+func RegExFromAttrName(name string) *regexp.Regexp {
+	return regexp.MustCompile(name + `="([^"]*)"`)
+}
diff --git a/internal/config/token.go b/internal/config/token.go
new file mode 100644
index 000000000..13eeea84c
--- /dev/null
+++ b/internal/config/token.go
@@ -0,0 +1,20 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.
+
+package config
+
+const (
+	// NewlineCRLF is the Windows new line.
+	//
+	// We check NewlineCRLF first, then NewlineLF to handle both formats.
+	NewlineCRLF = "\r\n"
+	// NewlineLF is Unix new line.
+	NewlineLF = "\n"
+	// Separator is a Markdown horizontal rule used between sections.
+	Separator = "---"
+	// Ellipsis is a Markdown ellipsis.
+	Ellipsis = "..."
+)
diff --git a/internal/context/loader.go b/internal/context/loader.go
index 659151371..77e196133 100644
--- a/internal/context/loader.go
+++ b/internal/context/loader.go
@@ -10,47 +10,10 @@ package context
 import (
 	"os"
 	"path/filepath"
-	"time"
 
-	"github.com/ActiveMemory/ctx/internal/config"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
-// FileInfo represents metadata about a context file.
-//
-// Fields:
-//   - Name: Filename (e.g., "TASKS.md")
-//   - Path: Full path to the file
-//   - Size: File size in bytes
-//   - ModTime: Last modification time
-//   - Content: Raw file content
-//   - IsEmpty: True if file has no meaningful content (only headers/whitespace)
-//   - Tokens: Estimated token count for the content
-//   - Summary: Brief description generated from the content
-type FileInfo struct {
-	Name    string
-	Path    string
-	Size    int64
-	ModTime time.Time
-	Content []byte
-	IsEmpty bool
-	Tokens  int
-	Summary string
-}
-
-// Context represents the loaded context from a .context/ directory.
-//
-// Fields:
-//   - Dir: Path to the context directory
-//   - Files: All loaded context files with their metadata
-//   - TotalTokens: Sum of estimated tokens across all files
-//   - TotalSize: Sum of file sizes in bytes
-type Context struct {
-	Dir         string
-	Files       []FileInfo
-	TotalTokens int
-	TotalSize   int64
-}
-
 // Load reads all context files from the specified directory.
 //
 // If dir is empty, it uses the configured context directory from .contextrc,
@@ -64,7 +27,7 @@ type Context struct {
 //   - error: NotFoundError if directory doesn't exist, or other IO errors
 func Load(dir string) (*Context, error) {
 	if dir == "" {
-		dir = config.GetContextDir()
+		dir = rc.GetContextDir()
 	}
 
 	// Check if the directory exists
@@ -118,7 +81,7 @@ func Load(dir string) (*Context, error) {
 			Size:    fileInfo.Size(),
 			ModTime: fileInfo.ModTime(),
 			Content: content,
-			IsEmpty: len(content) == 0 || isEffectivelyEmpty(content),
+			IsEmpty: len(content) == 0 || effectivelyEmpty(content),
 			Tokens:  tokens,
 			Summary: generateSummary(name, content),
 		}
@@ -130,116 +93,3 @@ func Load(dir string) (*Context, error) {
 
 	return ctx, nil
 }
-
-// Exists checks if a context directory exists.
-//
-// If dir is empty, it uses the configured context directory.
-//
-// Parameters:
-//   - dir: Directory path to check, or empty string for default
-//
-// Returns:
-//   - bool: True if the directory exists and is a directory
-func Exists(dir string) bool {
-	if dir == "" {
-		dir = config.GetContextDir()
-	}
-	info, err := os.Stat(dir)
-	return err == nil && info.IsDir()
-}
-
-// NotFoundError is returned when the context directory doesn't exist.
-type NotFoundError struct {
-	Dir string
-}
-
-// Error implements the error interface for NotFoundError.
-//
-// Returns:
-//   - string: Error message including the missing directory path
-func (e *NotFoundError) Error() string {
-	return "context directory not found: " + e.Dir
-}
-
-// isEffectivelyEmpty checks if a file only contains headers and whitespace.
-//
-// Parameters:
-//   - content: File content to check
-//
-// Returns:
-//   - bool: True if file has no meaningful content (only headers, comments, whitespace)
-func isEffectivelyEmpty(content []byte) bool {
-	// Simple heuristic: if `content` is less than 100 bytes
-	// and mostly headers/whitespace
-	if len(content) < 20 {
-		return true
-	}
-
-	// Count non-header, non-whitespace content
-	lines := 0
-	contentLines := 0
-	for _, line := range splitLines(content) {
-		lines++
-		trimmed := trimSpace(line)
-		if len(trimmed) == 0 {
-			continue
-		}
-		if trimmed[0] == '#' {
-			continue
-		}
-		if len(trimmed) > 0 && trimmed[0] == '-' && len(trimmed) < 5 {
-			continue
-		}
-		// Check for HTML comment markers
-		if len(trimmed) >= 4 && string(trimmed[:4]) == "<!--" {
-			continue
-		}
-		if len(trimmed) >= 3 && string(trimmed[len(trimmed)-3:]) == "-->" {
-			continue
-		}
-		contentLines++
-	}
-
-	return contentLines == 0
-}
-
-// splitLines splits content into lines without using strings package.
-//
-// Parameters:
-//   - content: Byte slice to split
-//
-// Returns:
-//   - [][]byte: Slice of lines (without newline characters)
-func splitLines(content []byte) [][]byte {
-	var lines [][]byte
-	start := 0
-	for i, b := range content {
-		if b == '\n' {
-			lines = append(lines, content[start:i])
-			start = i + 1
-		}
-	}
-	if start < len(content) {
-		lines = append(lines, content[start:])
-	}
-	return lines
-}
-
-// trimSpace trims leading and trailing whitespace from a byte slice.
-//
-// Parameters:
-//   - b: Byte slice to trim
-//
-// Returns:
-//   - []byte: Slice with spaces, tabs, and carriage returns removed from ends
-func trimSpace(b []byte) []byte {
-	start := 0
-	end := len(b)
-	for start < end && (b[start] == ' ' || b[start] == '\t' || b[start] == '\r') {
-		start++
-	}
-	for end > start && (b[end-1] == ' ' || b[end-1] == '\t' || b[end-1] == '\r') {
-		end--
-	}
-	return b[start:end]
-}
diff --git a/internal/context/loader_test.go b/internal/context/loader_test.go
index 25df202ec..c2f78498b 100644
--- a/internal/context/loader_test.go
+++ b/internal/context/loader_test.go
@@ -175,9 +175,9 @@ func TestIsEffectivelyEmpty(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			result := isEffectivelyEmpty(tt.content)
+			result := effectivelyEmpty(tt.content)
 			if result != tt.expected {
-				t.Errorf("isEffectivelyEmpty() = %v, want %v", result, tt.expected)
+				t.Errorf("effectivelyEmpty() = %v, want %v", result, tt.expected)
 			}
 		})
 	}
diff --git a/internal/context/process.go b/internal/context/process.go
new file mode 100644
index 000000000..2631d4bbc
--- /dev/null
+++ b/internal/context/process.go
@@ -0,0 +1,48 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package context
+
+// splitLines splits content into lines without using strings package.
+//
+// Parameters:
+//   - content: Byte slice to split
+//
+// Returns:
+//   - [][]byte: Slice of lines (without newline characters)
+func splitLines(content []byte) [][]byte {
+	var lines [][]byte
+	start := 0
+	for i, b := range content {
+		if b == '\n' {
+			lines = append(lines, content[start:i])
+			start = i + 1
+		}
+	}
+	if start < len(content) {
+		lines = append(lines, content[start:])
+	}
+	return lines
+}
+
+// trimSpace trims leading and trailing whitespace from a byte slice.
+//
+// Parameters:
+//   - b: Byte slice to trim
+//
+// Returns:
+//   - []byte: Slice with spaces, tabs, and carriage returns removed from ends
+func trimSpace(b []byte) []byte {
+	start := 0
+	end := len(b)
+	for start < end && (b[start] == ' ' || b[start] == '\t' || b[start] == '\r') {
+		start++
+	}
+	for end > start && (b[end-1] == ' ' || b[end-1] == '\t' || b[end-1] == '\r') {
+		end--
+	}
+	return b[start:end]
+}
diff --git a/internal/context/sanitize.go b/internal/context/sanitize.go
new file mode 100644
index 000000000..6f17bb668
--- /dev/null
+++ b/internal/context/sanitize.go
@@ -0,0 +1,56 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package context
+
+import "github.com/ActiveMemory/ctx/internal/config"
+
+// effectivelyEmpty checks if a file only contains headers and whitespace.
+//
+// Parameters:
+//   - content: File content to check
+//
+// Returns:
+//   - bool: True if the file has no meaningful content (only headers,
+//     comments, whitespace)
+func effectivelyEmpty(content []byte) bool {
+	// Simple heuristic: if `content` is less than 100 bytes
+	// and mostly headers/whitespace
+	if len(content) < 20 {
+		return true
+	}
+
+	// Count non-header, non-whitespace content
+	lines := 0
+	contentLines := 0
+	openLen := len(config.CommentOpen)
+	closeLen := len(config.CommentClose)
+	for _, line := range splitLines(content) {
+		lines++
+		trimmed := trimSpace(line)
+		if len(trimmed) == 0 {
+			continue
+		}
+		if trimmed[0] == '#' {
+			continue
+		}
+		if len(trimmed) > 0 && trimmed[0] == '-' && len(trimmed) < 5 {
+			continue
+		}
+		// Check for HTML comment markers
+		if len(trimmed) >= openLen &&
+			string(trimmed[:openLen]) == config.CommentOpen {
+			continue
+		}
+		if len(trimmed) >= closeLen &&
+			string(trimmed[len(trimmed)-closeLen:]) == config.CommentClose {
+			continue
+		}
+		contentLines++
+	}
+
+	return contentLines == 0
+}
diff --git a/internal/context/summary.go b/internal/context/summary.go
index b2e19cb1e..f4c38e720 100644
--- a/internal/context/summary.go
+++ b/internal/context/summary.go
@@ -9,38 +9,11 @@ package context
 import (
 	"bytes"
 	"fmt"
-	"regexp"
 	"strings"
 
 	"github.com/ActiveMemory/ctx/internal/config"
 )
 
-// generateSummary creates a brief summary for a context file based on its name and content.
-//
-// Parameters:
-//   - name: Filename to determine summary strategy
-//   - content: Raw file content to analyze
-//
-// Returns:
-//   - string: Summary string (e.g., "3 active, 2 completed" or "empty")
-func generateSummary(name string, content []byte) string {
-	switch name {
-	case config.FilenameConstitution:
-		return summarizeConstitution(content)
-	case config.FilenameTask:
-		return summarizeTasks(content)
-	case config.FilenameDecision:
-		return summarizeDecisions(content)
-	case config.FilenameGlossary:
-		return summarizeGlossary(content)
-	default:
-		if len(content) == 0 || isEffectivelyEmpty(content) {
-			return "empty"
-		}
-		return "loaded"
-	}
-}
-
 // summarizeConstitution counts checkbox items (invariants) in CONSTITUTION.md.
 //
 // Parameters:
@@ -50,7 +23,12 @@ func generateSummary(name string, content []byte) string {
 //   - string: Summary like "5 invariants" or "loaded" if none found
 func summarizeConstitution(content []byte) string {
 	// Count checkbox items (invariants)
-	count := bytes.Count(content, []byte("- [ ]")) + bytes.Count(content, []byte("- [x]"))
+	count := bytes.Count(
+		content, []byte(config.PrefixTaskUndone),
+	) +
+		bytes.Count(
+			content, []byte(config.PrefixTaskDone),
+		)
 	if count == 0 {
 		return "loaded"
 	}
@@ -66,8 +44,8 @@ func summarizeConstitution(content []byte) string {
 //   - string: Summary like "3 active, 2 completed" or "empty" if none
 func summarizeTasks(content []byte) string {
 	// Count active (unchecked) and completed (checked) tasks
-	active := bytes.Count(content, []byte("- [ ]"))
-	completed := bytes.Count(content, []byte("- [x]"))
+	active := bytes.Count(content, []byte(config.PrefixTaskUndone))
+	completed := bytes.Count(content, []byte(config.PrefixTaskDone))
 
 	if active == 0 && completed == 0 {
 		return "empty"
@@ -92,8 +70,7 @@ func summarizeTasks(content []byte) string {
 //   - string: Summary like "3 decisions" or "empty" if none
 func summarizeDecisions(content []byte) string {
 	// Count decision headers (## [date] or ## Decision)
-	re := regexp.MustCompile(`(?m)^## `)
-	matches := re.FindAll(content, -1)
+	matches := config.RegExEntryHeading.FindAll(content, -1)
 	count := len(matches)
 
 	if count == 0 {
@@ -113,9 +90,7 @@ func summarizeDecisions(content []byte) string {
 // Returns:
 //   - string: Summary like "5 terms" or "empty" if none
 func summarizeGlossary(content []byte) string {
-	// Count definition entries (lines starting with **term** or - **term**)
-	re := regexp.MustCompile(`(?m)(?:^|\n)\s*(?:-\s*)?\*\*[^*]+\*\*`)
-	matches := re.FindAll(content, -1)
+	matches := config.RegExGlossary.FindAll(content, -1)
 	count := len(matches)
 
 	if count == 0 {
@@ -126,3 +101,30 @@ func summarizeGlossary(content []byte) string {
 	}
 	return fmt.Sprintf("%d terms", count)
 }
+
+// generateSummary creates a brief summary for a context file based on its
+// name and content.
+//
+// Parameters:
+//   - name: Filename to determine summary strategy
+//   - content: Raw file content to analyze
+//
+// Returns:
+//   - string: Summary string (e.g., "3 active, 2 completed" or "empty")
+func generateSummary(name string, content []byte) string {
+	switch name {
+	case config.FileConstitution:
+		return summarizeConstitution(content)
+	case config.FileTask:
+		return summarizeTasks(content)
+	case config.FileDecision:
+		return summarizeDecisions(content)
+	case config.FileGlossary:
+		return summarizeGlossary(content)
+	default:
+		if len(content) == 0 || effectivelyEmpty(content) {
+			return "empty"
+		}
+		return "loaded"
+	}
+}
diff --git a/internal/context/summary_test.go b/internal/context/summary_test.go
index b14117e8e..e057c4fa1 100644
--- a/internal/context/summary_test.go
+++ b/internal/context/summary_test.go
@@ -54,13 +54,13 @@ func TestGenerateSummary(t *testing.T) {
 		{
 			name:     "decisions multiple",
 			filename: "DECISIONS.md",
-			content:  []byte("# Decisions\n\n## 2024-01-15 First\n\nContent\n\n## 2024-01-16 Second\n\nContent\n"),
+			content:  []byte("# Decisions\n\n## [2024-01-15-120000] First\n\nContent\n\n## [2024-01-16-120000] Second\n\nContent\n"),
 			expected: "2 decisions",
 		},
 		{
 			name:     "decisions single",
 			filename: "DECISIONS.md",
-			content:  []byte("# Decisions\n\n## One decision\n\nContent\n"),
+			content:  []byte("# Decisions\n\n## [2024-01-15-120000] One decision\n\nContent\n"),
 			expected: "1 decision",
 		},
 		{
@@ -190,12 +190,12 @@ func TestSummarizeDecisions(t *testing.T) {
 		},
 		{
 			name:     "one decision",
-			content:  []byte("## First\n\nContent\n"),
+			content:  []byte("## [2024-01-15-120000] First\n\nContent\n"),
 			expected: "1 decision",
 		},
 		{
 			name:     "multiple decisions",
-			content:  []byte("## First\n\n## Second\n\n## Third\n"),
+			content:  []byte("## [2024-01-15-120000] First\n\n## [2024-01-16-120000] Second\n\n## [2024-01-17-120000] Third\n"),
 			expected: "3 decisions",
 		},
 	}
diff --git a/internal/context/types.go b/internal/context/types.go
new file mode 100644
index 000000000..930a345a7
--- /dev/null
+++ b/internal/context/types.go
@@ -0,0 +1,59 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.
+
+package context
+
+import "time"
+
+// FileInfo represents metadata about a context file.
+//
+// Fields:
+//   - Name: Filename (e.g., "TASKS.md")
+//   - Path: Full path to the file
+//   - Size: File size in bytes
+//   - ModTime: Last modification time
+//   - Content: Raw file content
+//   - IsEmpty: True if the file has no meaningful content
+//     (only headers/whitespace)
+//   - Tokens: Estimated token count for the content
+//   - Summary: Brief description generated from the content
+type FileInfo struct {
+	Name    string
+	Path    string
+	Size    int64
+	ModTime time.Time
+	Content []byte
+	IsEmpty bool
+	Tokens  int
+	Summary string
+}
+
+// Context represents the loaded context from a .context/ directory.
+//
+// Fields:
+//   - Dir: Path to the context directory
+//   - Files: All loaded context files with their metadata
+//   - TotalTokens: Sum of estimated tokens across all files
+//   - TotalSize: Sum of file sizes in bytes
+type Context struct {
+	Dir         string
+	Files       []FileInfo
+	TotalTokens int
+	TotalSize   int64
+}
+
+// NotFoundError is returned when the context directory doesn't exist.
+type NotFoundError struct {
+	Dir string
+}
+
+// Error implements the error interface for NotFoundError.
+//
+// Returns:
+//   - string: Error message including the missing directory path
+func (e *NotFoundError) Error() string {
+	return "context directory not found: " + e.Dir
+}
diff --git a/internal/context/verify.go b/internal/context/verify.go
new file mode 100644
index 000000000..6c4cb23b2
--- /dev/null
+++ b/internal/context/verify.go
@@ -0,0 +1,30 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package context
+
+import (
+	"os"
+
+	"github.com/ActiveMemory/ctx/internal/rc"
+)
+
+// Exists checks if a context directory exists.
+//
+// If dir is empty, it uses the configured context directory.
+//
+// Parameters:
+//   - dir: Directory path to check, or empty string for default
+//
+// Returns:
+//   - bool: True if the directory exists and is a directory
+func Exists(dir string) bool {
+	if dir == "" {
+		dir = rc.GetContextDir()
+	}
+	info, err := os.Stat(dir)
+	return err == nil && info.IsDir()
+}
diff --git a/internal/drift/detector.go b/internal/drift/detector.go
index d791cd21f..a6f7bb90b 100644
--- a/internal/drift/detector.go
+++ b/internal/drift/detector.go
@@ -9,7 +9,6 @@ package drift
 
 import (
 	"os"
-	"regexp"
 	"strings"
 
 	"github.com/ActiveMemory/ctx/internal/config"
@@ -44,7 +43,7 @@ type Issue struct {
 // Fields:
 //   - Warnings: Non-critical issues that should be addressed
 //   - Violations: Critical issues that indicate constitution violations
-//   - Passed: Names of checks that completed without issues
+//   - Passed: Names of checks that are completed without issues
 type Report struct {
 	Warnings   []Issue  `json:"warnings"`
 	Violations []Issue  `json:"violations"`
@@ -54,7 +53,8 @@ type Report struct {
 // Status returns the overall status of the report.
 //
 // Returns:
-//   - string: "violation" if any violations, "warning" if only warnings, "ok" otherwise
+//   - string: "violation" if any violations, "warning" if only warnings,
+//     "ok" otherwise
 func (r *Report) Status() string {
 	if len(r.Violations) > 0 {
 		return "violation"
@@ -106,19 +106,16 @@ func Detect(ctx *context.Context) *Report {
 //   - ctx: Loaded context containing files to scan
 //   - report: Report to append warnings to (modified in place)
 func checkPathReferences(ctx *context.Context, report *Report) {
-	// Pattern to match file paths in Markdown (backticks or code blocks)
-	pathPattern := regexp.MustCompile("`([^`]+\\.[a-zA-Z]{1,5})`")
-
 	foundDeadPaths := false
 
 	for _, f := range ctx.Files {
-		if f.Name != config.FilenameArchitecture && f.Name != config.FilenameConvention {
+		if f.Name != config.FileArchitecture && f.Name != config.FileConvention {
 			continue
 		}
 
 		lines := strings.Split(string(f.Content), "\n")
 		for lineNum, line := range lines {
-			matches := pathPattern.FindAllStringSubmatch(line, -1)
+			matches := config.RegExPath.FindAllStringSubmatch(line, -1)
 			for _, m := range matches {
 				path := m[1]
 				// Skip URLs and common non-file patterns
@@ -161,7 +158,7 @@ func checkStaleness(ctx *context.Context, report *Report) {
 	staleness := false
 
 	for _, f := range ctx.Files {
-		if f.Name == config.FilenameTask {
+		if f.Name == config.FileTask {
 			// Count completed tasks
 			completedCount := strings.Count(string(f.Content), "- [x]")
 			if completedCount > 10 {
@@ -183,7 +180,7 @@ func checkStaleness(ctx *context.Context, report *Report) {
 
 // checkConstitution performs heuristic checks for constitution violations.
 //
-// Currently scans the working directory for files that may contain secrets
+// Currently, it scans the working directory for files that may contain secrets
 // (e.g., .env, credentials, api_key) and flags them as violations.
 //
 // Parameters:
@@ -215,7 +212,9 @@ func checkConstitution(_ *context.Context, report *Report) {
 		}
 		name := strings.ToLower(entry.Name())
 		for _, pattern := range secretPatterns {
-			if strings.Contains(name, pattern) && !strings.HasSuffix(name, ".example") && !strings.HasSuffix(name, ".sample") {
+			if strings.Contains(name, pattern) &&
+				!strings.HasSuffix(name, ".example") &&
+				!strings.HasSuffix(name, ".sample") {
 				// Check if it contains actual content (not just template)
 				content, err := os.ReadFile(entry.Name())
 				if err != nil {
@@ -272,7 +271,7 @@ func checkRequiredFiles(ctx *context.Context, report *Report) {
 
 // isTemplateFile checks if file content appears to be a template.
 //
-// Looks for common template markers like YOUR_, {{, REPLACE_, TODO:, CHANGEME.
+// Looks for common template markers like YOUR_, {{, REPLACE_, TODO, CHANGEME.
 // Used to avoid flagging template files as containing secrets.
 //
 // Parameters:
@@ -288,8 +287,9 @@ func isTemplateFile(content []byte) bool {
 		"<your",
 		"{{",
 		"REPLACE_",
-		"TODO:",
+		"TODO",
 		"CHANGEME",
+		"FIXME",
 	}
 	for _, marker := range templateMarkers {
 		if strings.Contains(strings.ToUpper(s), marker) {
diff --git a/internal/index/index.go b/internal/index/index.go
new file mode 100644
index 000000000..b7af7fae0
--- /dev/null
+++ b/internal/index/index.go
@@ -0,0 +1,194 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+// Package index provides index generation and parsing for context files.
+package index
+
+import (
+	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+)
+
+// Entry represents a parsed entry header from a context file.
+//
+// Fields:
+//   - Timestamp: Full timestamp (YYYY-MM-DD-HHMMSS)
+//   - Date: Date only (YYYY-MM-DD)
+//   - Title: Entry title
+type Entry struct {
+	Timestamp string
+	Date      string
+	Title     string
+}
+
+// ParseHeaders extracts all entries from file content.
+//
+// It scans for headers matching the pattern "## [YYYY-MM-DD-HHMMSS] Title"
+// and returns them in the order they appear in the file.
+//
+// Parameters:
+//   - content: The full content of a context file
+//
+// Returns:
+//   - []Entry: Slice of parsed entries (it may be empty)
+func ParseHeaders(content string) []Entry {
+	var entries []Entry
+
+	matches := config.RegExEntryHeader.FindAllStringSubmatch(content, -1)
+	for _, match := range matches {
+		if len(match) == 4 {
+			date := match[1]
+			time := match[2]
+			title := match[3]
+			entries = append(entries, Entry{
+				Timestamp: date + "-" + time,
+				Date:      date,
+				Title:     title,
+			})
+		}
+	}
+
+	return entries
+}
+
+// GenerateTable creates a Markdown table index from entries.
+//
+// The table has two columns: Date and the specified column header.
+// If there are no entries, returns an empty string.
+//
+// Parameters:
+//   - entries: Slice of entries to include
+//   - columnHeader: Header for the second column (e.g., "Decision", "Learning")
+//
+// Returns:
+//   - string: Markdown table (without markers) or empty string
+func GenerateTable(entries []Entry, columnHeader string) string {
+	if len(entries) == 0 {
+		return ""
+	}
+
+	nl := config.NewlineLF
+	var sb strings.Builder
+	sb.WriteString("| Date | ")
+	sb.WriteString(columnHeader)
+	sb.WriteString(" |" + nl)
+	sb.WriteString("|------|")
+	sb.WriteString(strings.Repeat("-", len(columnHeader)))
+	sb.WriteString("|" + nl)
+
+	for _, e := range entries {
+		// Escape pipe characters in title
+		title := strings.ReplaceAll(e.Title, "|", "\\|")
+		sb.WriteString("| ")
+		sb.WriteString(e.Date)
+		sb.WriteString(" | ")
+		sb.WriteString(title)
+		sb.WriteString(" |" + nl)
+	}
+
+	return sb.String()
+}
+
+// Update regenerates the index in file content.
+//
+// If INDEX:START and INDEX:END markers exist, the content between them
+// is replaced. Otherwise, the index is inserted after the specified header.
+// If there are no entries, any existing index is removed.
+//
+// Parameters:
+//   - content: The full content of the file
+//   - fileHeader: The main header to insert after (e.g., "# Decisions")
+//   - columnHeader: Header for the table column (e.g., "Decision")
+//
+// Returns:
+//   - string: Updated content with regenerated index
+func Update(content, fileHeader, columnHeader string) string {
+	entries := ParseHeaders(content)
+	indexContent := GenerateTable(entries, columnHeader)
+	nl := config.NewlineLF
+
+	// Check if markers already exist
+	startIdx := strings.Index(content, config.IndexStart)
+	endIdx := strings.Index(content, config.IndexEnd)
+
+	if startIdx != -1 && endIdx != -1 && endIdx > startIdx {
+		// Replace the existing index
+		if indexContent == "" {
+			// No entries - remove index entirely (including markers
+			// and surrounding whitespace)
+			before := strings.TrimRight(content[:startIdx], nl)
+			after := content[endIdx+len(config.IndexEnd):]
+			after = strings.TrimLeft(after, nl)
+			if after != "" {
+				return before + nl + nl + after
+			}
+			return before + nl
+		}
+		// Replace content between markers
+		before := content[:startIdx+len(config.IndexStart)]
+		after := content[endIdx:]
+		return before + nl + indexContent + after
+	}
+
+	// No existing markers - insert after file header
+	if indexContent == "" {
+		// No entries, nothing to insert
+		return content
+	}
+
+	headerIdx := strings.Index(content, fileHeader)
+	if headerIdx == -1 {
+		// No header found, return unchanged
+		return content
+	}
+
+	// Find end of header line
+	lineEnd := strings.Index(content[headerIdx:], nl)
+	if lineEnd == -1 {
+		// Header is at the end of the file
+		return content + nl + nl +
+			config.IndexStart + nl + indexContent +
+			config.IndexEnd + nl
+	}
+
+	insertPoint := headerIdx + lineEnd + 1
+
+	// Build new content with the index
+	var sb strings.Builder
+	sb.WriteString(content[:insertPoint])
+	sb.WriteString(nl)
+	sb.WriteString(config.IndexStart)
+	sb.WriteString(nl)
+	sb.WriteString(indexContent)
+	sb.WriteString(config.IndexEnd)
+	sb.WriteString(nl)
+	sb.WriteString(content[insertPoint:])
+
+	return sb.String()
+}
+
+// UpdateDecisions regenerates the decision index in DECISIONS.md content.
+//
+// Parameters:
+//   - content: The full content of DECISIONS.md
+//
+// Returns:
+//   - string: Updated content with regenerated index
+func UpdateDecisions(content string) string {
+	return Update(content, config.HeadingDecisions, config.ColumnDecision)
+}
+
+// UpdateLearnings regenerates the learning index in LEARNINGS.md content.
+//
+// Parameters:
+//   - content: The full content of LEARNINGS.md
+//
+// Returns:
+//   - string: Updated content with regenerated index
+func UpdateLearnings(content string) string {
+	return Update(content, config.HeadingLearnings, config.ColumnLearning)
+}
diff --git a/internal/index/index_test.go b/internal/index/index_test.go
new file mode 100644
index 000000000..3b6c5dc5f
--- /dev/null
+++ b/internal/index/index_test.go
@@ -0,0 +1,433 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+package index
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+)
+
+func TestParseHeaders(t *testing.T) {
+	tests := []struct {
+		name     string
+		content  string
+		expected []Entry
+	}{
+		{
+			name:     "empty content",
+			content:  "",
+			expected: nil,
+		},
+		{
+			name:     "no entries",
+			content:  "# Decisions\n\nSome text here.",
+			expected: nil,
+		},
+		{
+			name: "single entry",
+			content: `# Decisions
+
+## [2026-01-28-051426] No custom UI - IDE is the interface
+
+**Status**: Accepted
+`,
+			expected: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "No custom UI - IDE is the interface"},
+			},
+		},
+		{
+			name: "multiple entries",
+			content: `# Decisions
+
+## [2026-01-28-051426] First decision
+
+**Status**: Accepted
+
+---
+
+## [2026-01-27-123456] Second decision
+
+**Status**: Accepted
+`,
+			expected: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "First decision"},
+				{Timestamp: "2026-01-27-123456", Date: "2026-01-27", Title: "Second decision"},
+			},
+		},
+		{
+			name: "entry with special characters",
+			content: `# Decisions
+
+## [2026-01-28-051426] Use tool-agnostic Session type | with pipe
+
+**Status**: Accepted
+`,
+			expected: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "Use tool-agnostic Session type | with pipe"},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ParseHeaders(tt.content)
+			if len(got) != len(tt.expected) {
+				t.Errorf("ParseHeaders() got %d entries, want %d", len(got), len(tt.expected))
+				return
+			}
+			for i, entry := range got {
+				if entry.Timestamp != tt.expected[i].Timestamp {
+					t.Errorf("entry[%d].Timestamp = %q, want %q", i, entry.Timestamp, tt.expected[i].Timestamp)
+				}
+				if entry.Date != tt.expected[i].Date {
+					t.Errorf("entry[%d].Date = %q, want %q", i, entry.Date, tt.expected[i].Date)
+				}
+				if entry.Title != tt.expected[i].Title {
+					t.Errorf("entry[%d].Title = %q, want %q", i, entry.Title, tt.expected[i].Title)
+				}
+			}
+		})
+	}
+}
+
+func TestGenerateTable(t *testing.T) {
+	tests := []struct {
+		name         string
+		entries      []Entry
+		columnHeader string
+		expected     string
+	}{
+		{
+			name:         "empty entries",
+			entries:      nil,
+			columnHeader: "Decision",
+			expected:     "",
+		},
+		{
+			name:         "empty slice",
+			entries:      []Entry{},
+			columnHeader: "Decision",
+			expected:     "",
+		},
+		{
+			name: "single entry",
+			entries: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "First decision"},
+			},
+			columnHeader: "Decision",
+			expected: `| Date | Decision |
+|------|--------|
+| 2026-01-28 | First decision |
+`,
+		},
+		{
+			name: "multiple entries",
+			entries: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "First"},
+				{Timestamp: "2026-01-27-123456", Date: "2026-01-27", Title: "Second"},
+			},
+			columnHeader: "Decision",
+			expected: `| Date | Decision |
+|------|--------|
+| 2026-01-28 | First |
+| 2026-01-27 | Second |
+`,
+		},
+		{
+			name: "entry with pipe character",
+			entries: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "Use A | B format"},
+			},
+			columnHeader: "Decision",
+			expected: `| Date | Decision |
+|------|--------|
+| 2026-01-28 | Use A \| B format |
+`,
+		},
+		{
+			name: "learning column header",
+			entries: []Entry{
+				{Timestamp: "2026-01-28-051426", Date: "2026-01-28", Title: "Test entry"},
+			},
+			columnHeader: "Learning",
+			expected: `| Date | Learning |
+|------|--------|
+| 2026-01-28 | Test entry |
+`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := GenerateTable(tt.entries, tt.columnHeader)
+			if got != tt.expected {
+				t.Errorf("GenerateTable() =\n%q\nwant\n%q", got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestUpdateDecisions(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		wantHas []string
+		wantNot []string
+	}{
+		{
+			name:    "empty file with header",
+			content: "# Decisions\n",
+			wantNot: []string{config.IndexStart, config.IndexEnd},
+		},
+		{
+			name: "file with one decision",
+			content: `# Decisions
+
+## [2026-01-28-051426] Test decision
+
+**Status**: Accepted
+`,
+			wantHas: []string{
+				config.IndexStart,
+				config.IndexEnd,
+				"| Date | Decision |",
+				"| 2026-01-28 | Test decision |",
+				"## [2026-01-28-051426] Test decision",
+			},
+		},
+		{
+			name: "update existing index",
+			content: `# Decisions
+
+<!-- INDEX:START -->
+| Date | Decision |
+|------|----------|
+| 2026-01-28 | Old entry |
+<!-- INDEX:END -->
+
+## [2026-01-28-051426] New decision
+
+**Status**: Accepted
+`,
+			wantHas: []string{
+				config.IndexStart,
+				config.IndexEnd,
+				"| 2026-01-28 | New decision |",
+			},
+			wantNot: []string{
+				"| 2026-01-28 | Old entry |",
+			},
+		},
+		{
+			name: "remove index when no decisions",
+			content: `# Decisions
+
+<!-- INDEX:START -->
+| Date | Decision |
+|------|----------|
+| 2026-01-28 | Old entry |
+<!-- INDEX:END -->
+
+Some other content.
+`,
+			wantNot: []string{
+				config.IndexStart,
+				config.IndexEnd,
+				"| Date | Decision |",
+			},
+			wantHas: []string{
+				"# Decisions",
+				"Some other content.",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := UpdateDecisions(tt.content)
+			for _, want := range tt.wantHas {
+				if !strings.Contains(got, want) {
+					t.Errorf("UpdateDecisions() result missing %q\nGot:\n%s", want, got)
+				}
+			}
+			for _, notWant := range tt.wantNot {
+				if strings.Contains(got, notWant) {
+					t.Errorf("UpdateDecisions() result should not contain %q\nGot:\n%s", notWant, got)
+				}
+			}
+		})
+	}
+}
+
+func TestUpdateDecisions_PreservesContent(t *testing.T) {
+	content := `# Decisions
+
+## [2026-01-28-051426] First decision
+
+**Status**: Accepted
+
+**Context**: Some context here.
+
+**Decision**: The decision text.
+
+**Rationale**: Why we did it.
+
+**Consequences**: What happens next.
+
+---
+
+## [2026-01-27-123456] Second decision
+
+**Status**: Accepted
+
+**Context**: Another context.
+
+**Decision**: Another decision.
+
+**Rationale**: Another rationale.
+
+**Consequences**: More consequences.
+`
+
+	got := UpdateDecisions(content)
+
+	if !strings.Contains(got, config.IndexStart) {
+		t.Error("Missing INDEX:START marker")
+	}
+	if !strings.Contains(got, config.IndexEnd) {
+		t.Error("Missing INDEX:END marker")
+	}
+
+	if !strings.Contains(got, "| 2026-01-28 | First decision |") {
+		t.Error("Missing first decision in index")
+	}
+	if !strings.Contains(got, "| 2026-01-27 | Second decision |") {
+		t.Error("Missing second decision in index")
+	}
+
+	if !strings.Contains(got, "**Context**: Some context here.") {
+		t.Error("Lost content from first decision")
+	}
+	if !strings.Contains(got, "**Rationale**: Another rationale.") {
+		t.Error("Lost content from second decision")
+	}
+}
+
+func TestUpdateDecisions_Idempotent(t *testing.T) {
+	content := `# Decisions
+
+## [2026-01-28-051426] Test decision
+
+**Status**: Accepted
+`
+
+	first := UpdateDecisions(content)
+	second := UpdateDecisions(first)
+
+	if first != second {
+		t.Errorf("UpdateDecisions is not idempotent\nFirst:\n%s\nSecond:\n%s", first, second)
+	}
+}
+
+func TestUpdateLearnings(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		wantHas []string
+		wantNot []string
+	}{
+		{
+			name:    "empty file with header",
+			content: "# Learnings\n",
+			wantNot: []string{config.IndexStart, config.IndexEnd},
+		},
+		{
+			name: "file with one learning",
+			content: `# Learnings
+
+## [2026-01-28-191951] Required flags now enforced
+
+**Context**: Implemented ctx add learning flags
+
+**Lesson**: Structured entries are more useful
+
+**Application**: Always use all three flags
+`,
+			wantHas: []string{
+				config.IndexStart,
+				config.IndexEnd,
+				"| Date | Learning |",
+				"| 2026-01-28 | Required flags now enforced |",
+			},
+		},
+		{
+			name: "multiple learnings",
+			content: `# Learnings
+
+## [2026-01-28-191951] First learning
+
+**Context**: Test
+
+**Lesson**: Test
+
+**Application**: Test
+
+---
+
+## [2026-01-27-120000] Second learning
+
+**Context**: Test
+
+**Lesson**: Test
+
+**Application**: Test
+`,
+			wantHas: []string{
+				"| 2026-01-28 | First learning |",
+				"| 2026-01-27 | Second learning |",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := UpdateLearnings(tt.content)
+			for _, want := range tt.wantHas {
+				if !strings.Contains(got, want) {
+					t.Errorf("UpdateLearnings() result missing %q\nGot:\n%s", want, got)
+				}
+			}
+			for _, notWant := range tt.wantNot {
+				if strings.Contains(got, notWant) {
+					t.Errorf("UpdateLearnings() result should not contain %q\nGot:\n%s", notWant, got)
+				}
+			}
+		})
+	}
+}
+
+func TestUpdateLearnings_Idempotent(t *testing.T) {
+	content := `# Learnings
+
+## [2026-01-28-191951] Test learning
+
+**Context**: Test
+
+**Lesson**: Test
+
+**Application**: Test
+`
+
+	first := UpdateLearnings(content)
+	second := UpdateLearnings(first)
+
+	if first != second {
+		t.Errorf("UpdateLearnings is not idempotent\nFirst:\n%s\nSecond:\n%s", first, second)
+	}
+}
diff --git a/internal/config/rc.go b/internal/rc/rc.go
similarity index 77%
rename from internal/config/rc.go
rename to internal/rc/rc.go
index 1ca2b9552..ab355a8ce 100644
--- a/internal/config/rc.go
+++ b/internal/rc/rc.go
@@ -4,7 +4,8 @@
 //   \    Copyright 2026-present Context contributors.
 //                 SPDX-License-Identifier: Apache-2.0
 
-package config
+// Package rc provides runtime configuration loading from .contextrc files.
+package rc
 
 import (
 	"os"
@@ -12,6 +13,8 @@ import (
 	"sync"
 
 	"gopkg.in/yaml.v3"
+
+	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 // RC represents the configuration from .contextrc file.
@@ -37,8 +40,8 @@ const DefaultTokenBudget = 8000
 const DefaultArchiveAfterDays = 7
 
 var (
-	rc           *RC
-	rcOnce       sync.Once
+	rc            *RC
+	rcOnce        sync.Once
 	rcOverrideDir string
 )
 
@@ -48,9 +51,9 @@ var (
 //   - *RC: Configuration with defaults (8000 token budget, 7-day archive, etc.)
 func DefaultRC() *RC {
 	return &RC{
-		ContextDir:       DirContext,
+		ContextDir:       config.DirContext,
 		TokenBudget:      DefaultTokenBudget,
-		PriorityOrder:    nil, // nil means use FileReadOrder
+		PriorityOrder:    nil, // nil means use config.FileReadOrder
 		AutoArchive:      true,
 		ArchiveAfterDays: DefaultArchiveAfterDays,
 	}
@@ -124,7 +127,7 @@ func GetTokenBudget() int {
 //
 // Returns:
 //   - []string: File names in priority order, or nil if not configured
-//     (callers should fall back to FileReadOrder)
+//     (callers should fall back to config.FileReadOrder)
 func GetPriorityOrder() []string {
 	return GetRC().PriorityOrder
 }
@@ -162,3 +165,37 @@ func ResetRC() {
 	rc = nil
 	rcOverrideDir = ""
 }
+
+// FilePriority returns the priority of a context file.
+//
+// If a priority_order is configured in .contextrc, that order is used.
+// Otherwise, the default config.FileReadOrder is used.
+//
+// Lower numbers indicate higher priority (1 = highest).
+// Unknown files return 100.
+//
+// Parameters:
+//   - name: Filename to look up (e.g., "TASKS.md")
+//
+// Returns:
+//   - int: Priority value (1-9 for known files, 100 for unknown)
+func FilePriority(name string) int {
+	// Check for .contextrc override first
+	if order := GetPriorityOrder(); order != nil {
+		for i, fName := range order {
+			if fName == name {
+				return i + 1
+			}
+		}
+		// File not in custom order gets the lowest priority
+		return 100
+	}
+
+	// Use default priority from config.FileReadOrder
+	for i, fName := range config.FileReadOrder {
+		if fName == name {
+			return i + 1
+		}
+	}
+	return 100
+}
diff --git a/internal/config/rc_test.go b/internal/rc/rc_test.go
similarity index 94%
rename from internal/config/rc_test.go
rename to internal/rc/rc_test.go
index 140760ab7..1a1d30ae1 100644
--- a/internal/config/rc_test.go
+++ b/internal/rc/rc_test.go
@@ -4,19 +4,21 @@
 //   \    Copyright 2026-present Context contributors.
 //                 SPDX-License-Identifier: Apache-2.0
 
-package config
+package rc
 
 import (
 	"os"
 	"path/filepath"
 	"testing"
+
+	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 func TestDefaultRC(t *testing.T) {
 	rc := DefaultRC()
 
-	if rc.ContextDir != DirContext {
-		t.Errorf("ContextDir = %q, want %q", rc.ContextDir, DirContext)
+	if rc.ContextDir != config.DirContext {
+		t.Errorf("ContextDir = %q, want %q", rc.ContextDir, config.DirContext)
 	}
 	if rc.TokenBudget != DefaultTokenBudget {
 		t.Errorf("TokenBudget = %d, want %d", rc.TokenBudget, DefaultTokenBudget)
@@ -43,8 +45,8 @@ func TestGetRC_NoFile(t *testing.T) {
 
 	rc := GetRC()
 
-	if rc.ContextDir != DirContext {
-		t.Errorf("ContextDir = %q, want %q", rc.ContextDir, DirContext)
+	if rc.ContextDir != config.DirContext {
+		t.Errorf("ContextDir = %q, want %q", rc.ContextDir, config.DirContext)
 	}
 	if rc.TokenBudget != DefaultTokenBudget {
 		t.Errorf("TokenBudget = %d, want %d", rc.TokenBudget, DefaultTokenBudget)
@@ -200,8 +202,8 @@ func TestGetRC_PartialConfig(t *testing.T) {
 		t.Errorf("TokenBudget = %d, want %d", rc.TokenBudget, 5000)
 	}
 	// Unspecified values should use defaults
-	if rc.ContextDir != DirContext {
-		t.Errorf("ContextDir = %q, want %q (default)", rc.ContextDir, DirContext)
+	if rc.ContextDir != config.DirContext {
+		t.Errorf("ContextDir = %q, want %q (default)", rc.ContextDir, config.DirContext)
 	}
 }
 
diff --git a/internal/recall/parser/claude.go b/internal/recall/parser/claude.go
index 5abcd9af4..f87867e7e 100644
--- a/internal/recall/parser/claude.go
+++ b/internal/recall/parser/claude.go
@@ -64,7 +64,9 @@ func (p *ClaudeCodeParser) CanParse(path string) bool {
 	defer file.Close()
 
 	scanner := bufio.NewScanner(file)
-	for i := 0; i < 5 && scanner.Scan(); i++ {
+	// Check first 50 lines - slug may not appear until later in the file
+	// (early lines can be file-history-snapshot or messages without slug)
+	for i := 0; i < 50 && scanner.Scan(); i++ {
 		line := scanner.Bytes()
 		if len(line) == 0 {
 			continue
diff --git a/internal/recall/parser/parser.go b/internal/recall/parser/parser.go
index 0ebd663fd..ad169a8f7 100644
--- a/internal/recall/parser/parser.go
+++ b/internal/recall/parser/parser.go
@@ -9,8 +9,10 @@ package parser
 import (
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"sort"
+	"strings"
 )
 
 // registeredParsers holds all available session parsers.
@@ -156,6 +158,101 @@ func ScanDirectoryWithErrors(dir string) ([]*Session, []error, error) {
 //   - []*Session: Deduplicated sessions sorted by start time (newest first)
 //   - error: Non-nil if scanning fails (partial results may still be returned)
 func FindSessions(additionalDirs ...string) ([]*Session, error) {
+	return findSessionsWithFilter(nil, additionalDirs...)
+}
+
+// FindSessionsForCWD searches for sessions matching the given working directory.
+//
+// Matching is done in order of preference:
+//  1. Git remote URL match - if both directories are git repos with same remote
+//  2. Path relative to home - e.g., "WORKSPACE/ctx" matches across users
+//  3. Exact CWD match - fallback for non-git, non-home paths
+//
+// Parameters:
+//   - cwd: Working directory to filter by
+//   - additionalDirs: Optional additional directories to scan
+//
+// Returns:
+//   - []*Session: Filtered sessions sorted by start time (newest first)
+//   - error: Non-nil if scanning fails
+func FindSessionsForCWD(cwd string, additionalDirs ...string) ([]*Session, error) {
+	// Get current project's git remote (if available)
+	currentRemote := getGitRemote(cwd)
+
+	// Get path relative to home directory
+	currentRelPath := getPathRelativeToHome(cwd)
+
+	return findSessionsWithFilter(func(s *Session) bool {
+		// 1. Try git remote match (most robust)
+		if currentRemote != "" {
+			sessionRemote := getGitRemote(s.CWD)
+			if sessionRemote != "" && sessionRemote == currentRemote {
+				return true
+			}
+		}
+
+		// 2. Try path relative to home match
+		if currentRelPath != "" {
+			sessionRelPath := getPathRelativeToHome(s.CWD)
+			if sessionRelPath != "" && sessionRelPath == currentRelPath {
+				return true
+			}
+		}
+
+		// 3. Fallback to exact match
+		return s.CWD == cwd
+	}, additionalDirs...)
+}
+
+// getGitRemote returns the git remote origin URL for a directory.
+// Returns empty string if not a git repo or no remote configured.
+func getGitRemote(dir string) string {
+	if dir == "" {
+		return ""
+	}
+
+	// Check if directory exists
+	if _, err := os.Stat(dir); err != nil {
+		return ""
+	}
+
+	// Try to get git remote
+	cmd := exec.Command("git", "-C", dir, "remote", "get-url", "origin")
+	output, err := cmd.Output()
+	if err != nil {
+		return ""
+	}
+
+	return strings.TrimSpace(string(output))
+}
+
+// getPathRelativeToHome returns the path relative to the user's home directory.
+// Returns empty string if path is not under a home directory.
+func getPathRelativeToHome(path string) string {
+	if path == "" {
+		return ""
+	}
+
+	// Handle common home directory patterns
+	// /home/username/... -> strip /home/username
+	// /Users/username/... -> strip /Users/username (macOS)
+	parts := strings.Split(path, string(filepath.Separator))
+
+	for i, part := range parts {
+		if part == "home" || part == "Users" {
+			// Next part is username, rest is relative path
+			if i+2 < len(parts) {
+				return filepath.Join(parts[i+2:]...)
+			}
+			return ""
+		}
+	}
+
+	return ""
+}
+
+// findSessionsWithFilter is the internal implementation with optional filtering.
+func findSessionsWithFilter(filter func(*Session) bool, additionalDirs ...string) ([]*Session, error) {
 	var allSessions []*Session
 
 	// Check Claude Code default location
@@ -176,10 +273,18 @@ func FindSessions(additionalDirs ...string) ([]*Session, error) {
 		}
 	}
 
+	// Apply filter if provided
+	var filtered []*Session
+	for _, s := range allSessions {
+		if filter == nil || filter(s) {
+			filtered = append(filtered, s)
+		}
+	}
+
 	// Deduplicate by session ID
 	seen := make(map[string]bool)
 	var unique []*Session
-	for _, s := range allSessions {
+	for _, s := range filtered {
 		if !seen[s.ID] {
 			seen[s.ID] = true
 			unique = append(unique, s)
diff --git a/internal/task/task.go b/internal/task/task.go
new file mode 100644
index 000000000..9231a81e6
--- /dev/null
+++ b/internal/task/task.go
@@ -0,0 +1,95 @@
+//   /    Context:                     https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+// Package task provides task item parsing and matching.
+//
+// This package handles the domain logic for task items, independent of
+// their markdown representation.
+package task
+
+// Match indices for accessing capture groups.
+//
+// Usage:
+//
+//	match := task.ItemPattern.FindStringSubmatch(line)
+//	if match != nil {
+//	    indent := match[task.MatchIndent]
+//	    state := match[task.MatchState]
+//	    content := match[task.MatchContent]
+//	}
+const (
+	MatchFull    = 0 // Full match
+	MatchIndent  = 1 // Leading whitespace
+	MatchState   = 2 // "x" or " " or ""
+	MatchContent = 3 // Task text
+)
+
+// Completed reports whether a match represents a completed task.
+//
+// Parameters:
+//   - match: Result from ItemPattern.FindStringSubmatch
+//
+// Returns:
+//   - bool: True if the checkbox is checked ([x])
+func Completed(match []string) bool {
+	if len(match) <= MatchState {
+		return false
+	}
+	return match[MatchState] == "x"
+}
+
+// IsPending reports whether a match represents a pending task.
+//
+// Parameters:
+//   - match: Result from ItemPattern.FindStringSubmatch
+//
+// Returns:
+//   - bool: True if the checkbox is unchecked ([ ])
+func IsPending(match []string) bool {
+	if len(match) <= MatchState {
+		return false
+	}
+	return match[MatchState] != "x"
+}
+
+// Indent returns the leading whitespace from a match.
+//
+// Parameters:
+//   - match: Result from ItemPattern.FindStringSubmatch
+//
+// Returns:
+//   - string: Indent string (may be empty for top-level tasks)
+func Indent(match []string) string {
+	if len(match) <= MatchIndent {
+		return ""
+	}
+	return match[MatchIndent]
+}
+
+// Content returns the task text from a match.
+//
+// Parameters:
+//   - match: Result from ItemPattern.FindStringSubmatch
+//
+// Returns:
+//   - string: Task content (empty if match is invalid)
+func Content(match []string) string {
+	if len(match) <= MatchContent {
+		return ""
+	}
+	return match[MatchContent]
+}
+
+// IsSubTask reports whether a match represents a subtask (indented).
+//
+// Parameters:
+//   - match: Result from ItemPattern.FindStringSubmatch
+//
+// Returns:
+//   - bool: True if indent is 2+ spaces
+func IsSubTask(match []string) bool {
+	return len(Indent(match)) >= 2
+}
diff --git a/internal/templates/claude/commands/ctx-blog-changelog.md b/internal/templates/claude/commands/ctx-blog-changelog.md
new file mode 100644
index 000000000..72ba46e17
--- /dev/null
+++ b/internal/templates/claude/commands/ctx-blog-changelog.md
@@ -0,0 +1,112 @@
+---
+description: "Generate a blog post from a commit range with a theme"
+---
+
+Generate a blog post about changes since a specific commit, with a given theme.
+
+## Input
+
+Required:
+- **Commit hash**: Starting point (e.g., `040ce99`, `HEAD~50`)
+- **Theme**: The narrative angle (e.g., "human-assisted refactoring", "the recall system")
+
+Optional:
+- **Reference post**: An existing post to match the style
+
+## Usage Examples
+
+```text
+/ctx-blog-changelog 040ce99 "human-assisted refactoring"
+/ctx-blog-changelog HEAD~30 "building the journal system" --like 2026-01-27-building-ctx-using-ctx.md
+/ctx-blog-changelog v0.1.0 "what's new in v0.2.0"
+```
+
+## Process
+
+1. **Analyze the commit range**:
+```!
+git log --oneline <commit>..HEAD
+git diff --stat <commit>..HEAD
+git log --format="%s" <commit>..HEAD | head -50
+```
+
+2. **Gather supporting context**:
+```!
+# Decisions made in this period
+git log --format="%H %s" <commit>..HEAD | grep -i decision
+
+# Files most changed
+git diff --stat <commit>..HEAD | sort -t'|' -k2 -rn | head -20
+
+# Journal entries from this period (if available)
+ls .context/journal/*.md
+```
+
+3. **If reference post provided**, read it:
+```!
+cat docs/blog/<reference-post>.md
+```
+
+4. **Draft the narrative** following the theme:
+
+```markdown
+---
+title: "[Theme]: [Specific Angle]"
+date: YYYY-MM-DD
+author: [Ask user]
+---
+
+# [Title]
+
+> [Hook related to theme]
+
+## The Starting Point
+[State of codebase at <commit>, what prompted the change]
+
+## The Journey
+[Narrative of changes, organized by theme not chronology]
+
+### [Sub-theme 1]
+[Changes, examples, code snippets]
+
+### [Sub-theme 2]
+[Changes, examples, code snippets]
+
+## Before and After
+[Comparison table or code diff showing improvement]
+
+## Key Commits
+| Commit | Change |
+|--------|--------|
+| abc123 | Description |
+
+## Lessons Learned
+[Insights from this work]
+
+## What's Next
+[Future work enabled by these changes]
+```
+
+## Example
+
+User: `/ctx-blog-changelog 040ce99 "human-assisted refactoring"`
+
+You:
+> Analyzing 040ce99..HEAD (47 commits)
+>
+> I see the theme of "human-assisted refactoring" in:
+> - Consolidation of magic strings → config constants
+> - Package reorganization (init → initialize)
+> - Test colocation
+> - Convention documentation
+>
+> Reference: The existing post discusses YOLO vs human-guided modes.
+> I'll frame this as a continuation: "The Refactoring Sessions: What Happened After YOLO Mode"
+>
+> Outline:
+> 1. Where YOLO left us (the debt)
+> 2. The consolidation pattern (constants, naming)
+> 3. Before/after comparisons
+> 4. What the AI couldn't see (why human guidance mattered)
+>
+> Does this angle work? Any commits or changes to highlight?
diff --git a/internal/templates/claude/commands/ctx-blog.md b/internal/templates/claude/commands/ctx-blog.md
new file mode 100644
index 000000000..2d5fe8df4
--- /dev/null
+++ b/internal/templates/claude/commands/ctx-blog.md
@@ -0,0 +1,109 @@
+---
+description: "Generate a blog post draft from recent activity"
+---
+
+Generate a blog post draft from recent project activity.
+
+## Input
+
+The user may specify:
+- A time range: `last week`, `since Monday`, `January`
+- A topic focus: `the refactoring`, `new features`, `lessons learned`
+- Or just run it to analyze recent activity
+
+## Sources to Analyze
+
+Gather context from multiple sources:
+
+```!
+# Recent commits
+git log --oneline -30
+
+# Recent decisions
+head -100 .context/DECISIONS.md
+
+# Recent learnings
+head -100 .context/LEARNINGS.md
+
+# Recent tasks completed
+grep -A2 "\[x\]" .context/TASKS.md | head -50
+
+# Journal entries (if available)
+ls -la .context/journal/*.md 2>/dev/null | tail -10
+```
+
+## Blog Post Structure
+
+Follow the style of existing posts in `docs/blog/`:
+
+```markdown
+---
+title: "Descriptive Title: What This Post Is About"
+date: YYYY-MM-DD
+author: [Ask user]
+---
+
+*Author / Date*
+
+# Title
+
+> Opening hook or question
+
+[Introduction: Set the scene, why this matters]
+
+## Section 1: The Context/Problem
+[What situation led to this work]
+
+## Section 2: What We Did
+[Narrative of the work, with code examples]
+
+## Section 3: What We Learned
+[Key insights, gotchas, patterns discovered]
+
+## Section 4: What's Next
+[Future work, open questions]
+
+---
+
+*Footer note about how the post was created*
+```
+
+## Style Guidelines
+
+Based on `docs/blog/2026-01-27-building-ctx-using-ctx.md`:
+
+- **Personal voice**: Use "I", "we", share the journey
+- **Show don't tell**: Include actual code, commits, quotes from sessions
+- **Tables for comparisons**: Before/after, patterns found
+- **Callout boxes**: For key insights (`!!! info`, `!!! quote`)
+- **Honest about failures**: Include what went wrong and why
+- **Concrete examples**: Reference specific files, commits, decisions
+
+## Process
+
+1. Gather sources (git, decisions, learnings, journals)
+2. Identify the narrative arc (what's the story?)
+3. Draft outline for user approval
+4. Write full draft
+5. Ask for revisions
+6. Save to `docs/blog/YYYY-MM-DD-slug.md`
+
+## Example
+
+User: `/ctx-blog last week`
+
+You:
+> Looking at the last week, I see:
+> - 15 commits focused on journal/recall features
+> - 3 new decisions (project matching, tool output labeling)
+> - 5 learnings (session parsing, git remote matching)
+>
+> I'd frame this as: "Building a Memory Palace: How ctx Learned to Remember Sessions"
+>
+> Narrative arc:
+> 1. The problem: sessions scattered, hard to find
+> 2. The solution: recall export + journal site
+> 3. The gotchas: timezone bugs, missing sessions
+> 4. The insight: git remote as stable project ID
+>
+> Sound good? Any angle you want to emphasize?
diff --git a/internal/templates/claude/commands/ctx-journal-enrich.md b/internal/templates/claude/commands/ctx-journal-enrich.md
new file mode 100644
index 000000000..0e55682c7
--- /dev/null
+++ b/internal/templates/claude/commands/ctx-journal-enrich.md
@@ -0,0 +1,107 @@
+---
+description: "Enrich a journal entry with frontmatter and tags"
+---
+
+Enrich a session journal entry with structured metadata.
+
+## Input
+
+The user specifies a journal entry by partial match:
+- `twinkly-stirring-kettle` (slug)
+- `twinkly` (partial slug)
+- `2026-01-24` (date)
+- `76fe2ab9` (short ID)
+
+Find matching files:
+```!
+ls .context/journal/*.md | grep -i "<pattern>"
+```
+
+If multiple matches, show them and ask which one.
+If no argument given, show recent entries and ask.
+
+## Enrichment Tasks
+
+Read the journal entry and extract:
+
+### 1. Frontmatter (YAML at top of file)
+```yaml
+---
+title: "Session title"
+date: 2026-01-27
+type: feature|bugfix|refactor|exploration|debugging|documentation
+outcome: completed|partial|abandoned|blocked
+topics:
+  - authentication
+  - caching
+technologies:
+  - go
+  - postgresql
+libraries:
+  - cobra
+  - fatih/color
+error_types:
+  - nil-pointer
+  - timeout
+key_files:
+  - internal/auth/token.go
+  - internal/db/cache.go
+---
+```
+
+### 2. Summary
+If `## Summary` says "[Add your summary...]", replace with 2-3 sentences.
+
+### 3. Extracted Items
+Scan the conversation and extract:
+
+**Decisions made** - Link to DECISIONS.md if persisted:
+```markdown
+## Decisions
+- Used Redis for caching ([D12](../DECISIONS.md#d12))
+- Chose JWT over sessions (not yet persisted)
+```
+
+**Learnings discovered** - Link to LEARNINGS.md if persisted:
+```markdown
+## Learnings
+- Token refresh requires cache invalidation ([L8](../LEARNINGS.md#l8))
+- Go's defer runs LIFO (new insight)
+```
+
+**Tasks completed/created**:
+```markdown
+## Tasks
+- [x] Implement caching layer
+- [ ] Add cache metrics (created this session)
+```
+
+## Process
+
+1. Find and read the journal file
+2. Analyze the conversation
+3. Propose enrichment (type, topics, outcome)
+4. Ask user for confirmation/adjustments
+5. Show diff and write if approved
+
+## Example
+
+User: `/ctx-journal-enrich twinkly`
+
+You:
+> Found: `2026-01-24-twinkly-stirring-kettle-76fe2ab9.md`
+>
+> After reading, I'd categorize this as:
+> - **Type**: refactor
+> - **Outcome**: completed
+> - **Topics**: cli, code-cleanup, conventions
+> - **Technologies**: go
+> - **Libraries**: cobra, spf13/pflag
+> - **Key files**: internal/cli/task/tasks.go, internal/cli/session/run.go
+>
+> I also found:
+> - 1 decision: "Use cmd.Print* instead of fmt.Print*"
+> - 2 learnings: AST parsing gotcha, flag naming convention
+> - 3 tasks completed
+>
+> Want me to add these? Any adjustments to the categories?
diff --git a/internal/templates/claude/commands/ctx-journal-summarize.md b/internal/templates/claude/commands/ctx-journal-summarize.md
new file mode 100644
index 000000000..d3b6aa8cf
--- /dev/null
+++ b/internal/templates/claude/commands/ctx-journal-summarize.md
@@ -0,0 +1,121 @@
+---
+description: "Generate a summary of sessions over a time period"
+---
+
+Generate a narrative summary of sessions from a time period.
+
+## Input
+
+Time range (flexible):
+- `last week` / `this week`
+- `last month` / `January` / `2026-01`
+- `2026-01-20 to 2026-01-27`
+- `recent` (last 7 days)
+
+Or topic/feature-based:
+- `auth` (sessions mentioning authentication)
+- `refactor` (sessions tagged as refactor)
+- `how we built caching` (feature narrative across sessions)
+
+## Summary Types
+
+**Timeline summary** (default): What happened in a period
+**Feature narrative**: "How we built X" from multiple sessions
+**Decision trail**: Link decisions to the sessions that made them
+**FAQ**: Common questions asked and their answers
+
+## Process
+
+1. **Find matching journal entries**:
+```!
+ls .context/journal/*.md | grep "2026-01"
+```
+
+2. **Read each entry** - understand what was worked on, accomplished, decided
+
+3. **Generate summary** with structure:
+
+```markdown
+# Summary: [Period]
+
+## Overview
+[2-3 sentences: focus and accomplishments]
+
+## Work Completed
+- **[Feature]**: Description
+- **[Feature]**: Description
+
+## Decisions Made
+- [Decision]: [Rationale]
+
+## Learnings
+- [Learning]: [Why it matters]
+
+## Unfinished Work
+- [Task]: [Status]
+
+## Sessions
+| Date | Session | Summary |
+|------|---------|---------|
+| 01-24 | twinkly-stirring-kettle | Code cleanup |
+```
+
+4. **Review with user** - ask about focus, omissions, filename
+
+5. **Write to** `.context/journal/summary-[period].md`
+
+## Alternate Formats
+
+**Feature narrative** (`/ctx-journal-summarize how we built caching`):
+```markdown
+# How We Built: Caching Layer
+
+## The Journey
+[Narrative of how the feature evolved across sessions]
+
+## Key Sessions
+1. [2026-01-20] Initial exploration - evaluated Redis vs Memcached
+2. [2026-01-22] Implementation - basic cache layer
+3. [2026-01-25] Refinement - added TTL and invalidation
+
+## Decisions Along the Way
+- Chose Redis (session: 2026-01-20-...)
+- Used write-through pattern (session: 2026-01-22-...)
+
+## Lessons Learned
+- Cache invalidation is hard (session: 2026-01-25-...)
+```
+
+**Decision trail** (`/ctx-journal-summarize decisions`):
+```markdown
+# Decision Trail: January 2026
+
+| Decision | Session | Rationale |
+|----------|---------|-----------|
+| Use Redis | 2026-01-20-... | Speed + team experience |
+| JWT auth | 2026-01-22-... | Stateless, scales better |
+```
+
+## Output
+
+Summaries appear in the journal site alongside session entries:
+- `summary-2026-01.md` (monthly)
+- `summary-week-04.md` (weekly)
+- `summary-auth-feature.md` (topic)
+- `narrative-caching.md` (feature narrative)
+- `decisions-2026-01.md` (decision trail)
+
+## Example
+
+User: `/ctx-journal-summarize last week`
+
+You:
+> Found 5 sessions from Jan 24-31:
+> - 2x recall/export feature
+> - 2x journal site
+> - 1x bug fixes
+>
+> Focus areas to emphasize? Things to skip?
+
+After input, generate summary and ask:
+> Save to `.context/journal/summary-2026-week-05.md`?
diff --git a/internal/templates/claude/commands/ctx-prompt-audit.md b/internal/templates/claude/commands/ctx-prompt-audit.md
new file mode 100644
index 000000000..488cef950
--- /dev/null
+++ b/internal/templates/claude/commands/ctx-prompt-audit.md
@@ -0,0 +1,89 @@
+---
+description: "Analyze session logs to identify vague prompts and suggest improvements"
+---
+
+Analyze recent session transcripts to identify prompts that led to unnecessary clarification back-and-forth. This helps the user improve their prompting patterns.
+
+## Your Task
+
+1. **Read recent sessions** from `.context/sessions/` (focus on the 3-5 most recent)
+2. **Identify vague prompts** - user messages that caused you to ask clarifying questions
+3. **Generate a coaching report** with concrete examples and suggestions
+
+## What Makes a Prompt "Vague"
+
+Look for user prompts where Claude's immediate response was to ask clarifying questions rather than take action. Signs include:
+
+- **Missing file context**: "fix the bug" without specifying which file or error
+- **Ambiguous scope**: "optimize it" without what to optimize or success criteria
+- **Undefined targets**: "update the component" when multiple components exist
+- **Missing error details**: "it's not working" without symptoms or expected behavior
+- **Vague action words**: "make it better", "clean this up", "improve the code"
+
+## Important Nuance
+
+Not every short prompt is vague! Consider context:
+- "fix the bug" after discussing a specific error in detail → **NOT vague**
+- "fix the bug" as the first message → **VAGUE**
+- "optimize it" when working on a single function → probably fine
+- "optimize it" in a large codebase with no context → **VAGUE**
+
+## Output Format
+
+Generate a report like this:
+
+```
+## Prompt Audit Report
+
+**Sessions analyzed**: 5
+**User prompts reviewed**: 47
+**Vague prompts found**: 4 (8.5%)
+
+---
+
+### Example 1: Missing File Context
+
+**Your prompt**: "fix the bug"
+
+**What happened**: I had to ask which file and what error you were seeing, adding 2 messages of back-and-forth.
+
+**Better prompt**: "fix the authentication error in src/auth/login.ts where JWT validation fails with 401"
+
+**Cost**: ~2 extra messages, ~30 seconds
+
+---
+
+### Example 2: Undefined Target
+
+**Your prompt**: "optimize the component"
+
+**What happened**: Multiple components exist. I asked which one and what performance issue to address.
+
+**Better prompt**: "optimize UserList in src/components/UserList.tsx to reduce re-renders when parent state updates"
+
+**Cost**: ~3 extra messages, ~1 minute
+
+---
+
+## Patterns to Watch
+
+Based on your sessions, you tend to:
+1. Skip mentioning file paths (3 occurrences)
+2. Use "it" without establishing what "it" refers to (2 occurrences)
+
+## Tips
+
+- Start prompts with the **file path** when discussing specific code
+- Include **error messages** when debugging
+- Specify **success criteria** for optimization tasks
+```
+
+## Guidelines
+
+- Be constructive, not critical - the goal is to help, not shame
+- Show the actual prompt from their session (quoted)
+- Explain what happened (what you had to ask)
+- Provide a concrete better alternative
+- Estimate the "cost" in extra messages/time
+- Look for patterns across multiple examples
+- End with actionable tips based on their specific tendencies
diff --git a/internal/templates/claude/hooks/prompt-coach.sh b/internal/templates/claude/hooks/prompt-coach.sh
new file mode 100644
index 000000000..e89490a30
--- /dev/null
+++ b/internal/templates/claude/hooks/prompt-coach.sh
@@ -0,0 +1,145 @@
+#!/bin/bash
+
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+# Prompt coaching hook for Claude Code
+# Detects anti-patterns and suggests better alternatives.
+# Limits suggestions to MAX_SUGGESTIONS per pattern per session.
+#
+# Generated by: ctx init
+#
+# ANTI-PATTERNS DETECTED:
+# - "idiomatic X" → "follow project conventions"
+# - "best practices" → "follow CONVENTIONS.md"
+# - "fix the bug" (vague) → include error message, file, and context
+# - "optimize it" (vague) → specify what to optimize and why
+# - "make it better" (vague) → define "better" with criteria
+# - "update the component" (vague) → specify which component and what changes
+#
+# Output: Warnings to stderr (non-blocking)
+# Exit: Always 0 (never blocks execution)
+
+MAX_SUGGESTIONS=3
+SESSION_FILE="/tmp/ctx-prompt-coach-$$-$(date +%Y%m%d).state"
+
+# Initialize session file if it doesn't exist
+if [ ! -f "$SESSION_FILE" ]; then
+    cat > "$SESSION_FILE" << 'EOF'
+idiomatic=0
+bestpractices=0
+fixbug=0
+optimize=0
+makebetter=0
+update=0
+EOF
+fi
+
+# Read hook input from stdin (JSON)
+HOOK_INPUT=$(cat)
+
+# Extract the prompt text
+PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty')
+
+# If no prompt, allow
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Helper: get count for a pattern
+get_count() {
+    grep "^$1=" "$SESSION_FILE" 2>/dev/null | cut -d= -f2 || echo "0"
+}
+
+# Helper: increment count for a pattern
+increment_count() {
+    local pattern="$1"
+    local count=$(get_count "$pattern")
+    local new_count=$((count + 1))
+    if grep -q "^$pattern=" "$SESSION_FILE" 2>/dev/null; then
+        sed -i "s/^$pattern=.*/$pattern=$new_count/" "$SESSION_FILE"
+    else
+        echo "$pattern=$new_count" >> "$SESSION_FILE"
+    fi
+}
+
+# Helper: output a coaching tip (only if under limit)
+suggest() {
+    local pattern="$1"
+    local tip="$2"
+    local example="$3"
+    local count=$(get_count "$pattern")
+
+    if [ "$count" -lt "$MAX_SUGGESTIONS" ]; then
+        echo "" >&2
+        echo "┌─ Prompt Tip ─────────────────────────────────────" >&2
+        echo "│ $tip" >&2
+        if [ -n "$example" ]; then
+            echo "│" >&2
+            echo "│ Example: $example" >&2
+        fi
+        echo "└──────────────────────────────────────────────────" >&2
+        echo "" >&2
+        increment_count "$pattern"
+    fi
+}
+
+# Calculate prompt length (for detecting short vague prompts)
+PROMPT_LEN=${#PROMPT}
+
+# Check for "idiomatic X" pattern (case-insensitive)
+if echo "$PROMPT" | grep -qiE 'idiomatic (go|python|rust|javascript|typescript|java|c\+\+|ruby)'; then
+    suggest "idiomatic" \
+        "Instead of 'idiomatic X', try 'follow project conventions'" \
+        "'follow CONVENTIONS.md patterns for error handling'"
+fi
+
+# Check for "best practices" pattern (case-insensitive)
+if echo "$PROMPT" | grep -qiE '\bbest practices?\b'; then
+    suggest "bestpractices" \
+        "Instead of 'best practices', try 'follow CONVENTIONS.md'" \
+        "'follow the error handling pattern from CONVENTIONS.md'"
+fi
+
+# Check for vague "fix the bug" / "fix this bug" patterns
+# Only trigger if the prompt is short and lacks specifics
+if [ "$PROMPT_LEN" -lt 50 ] && echo "$PROMPT" | grep -qiE '\bfix (the|this|that|a) (bug|issue|error|problem)\b'; then
+    # Check if prompt lacks context (no file path, no error message, no line number)
+    if ! echo "$PROMPT" | grep -qE '(\.[a-z]{2,4}|line [0-9]|:[0-9]+|error:|Error:|failed|Failed)'; then
+        suggest "fixbug" \
+            "Add context: which file? what error? what's broken?" \
+            "'fix the JWT validation error in src/auth/login.ts returning 401'"
+    fi
+fi
+
+# Check for vague "optimize" patterns
+if [ "$PROMPT_LEN" -lt 40 ] && echo "$PROMPT" | grep -qiE '\b(optimize|optimise) (it|this|that)\b'; then
+    suggest "optimize" \
+        "Specify what to optimize and what metric matters" \
+        "'optimize UserList to reduce re-renders when parent state updates'"
+fi
+
+# Check for vague "make it better" patterns
+if echo "$PROMPT" | grep -qiE '\bmake (it|this|that) (better|nicer|cleaner|good)\b'; then
+    if [ "$PROMPT_LEN" -lt 50 ]; then
+        suggest "makebetter" \
+            "Define 'better' - readability? performance? maintainability?" \
+            "'refactor to be more readable by extracting validation logic'"
+    fi
+fi
+
+# Check for vague "update the component/function/file" patterns
+if [ "$PROMPT_LEN" -lt 50 ] && echo "$PROMPT" | grep -qiE '\bupdate (the|this|that|a) (component|function|file|module|class)\b'; then
+    # Check if prompt lacks specifics
+    if ! echo "$PROMPT" | grep -qE '(\.[a-z]{2,4}|src/|lib/|internal/)'; then
+        suggest "update" \
+            "Specify which component and what changes" \
+            "'update Button in src/components/Button.tsx to use new color tokens'"
+    fi
+fi
+
+# Always allow the prompt to proceed
+exit 0
diff --git a/internal/templates/embed.go b/internal/templates/embed.go
index 12168ba0a..87727a844 100644
--- a/internal/templates/embed.go
+++ b/internal/templates/embed.go
@@ -108,7 +108,7 @@ func GetClaudeCommand(name string) ([]byte, error) {
 	return FS.ReadFile("claude/commands/" + name)
 }
 
-// GetClaudeHook reads a Claude Code hook script by name.
+// ClaudeHookByFileName reads a Claude Code hook script by name.
 //
 // Parameters:
 //   - name: Hook script filename (e.g., "session-end-auto-save.sh")
@@ -116,6 +116,6 @@ func GetClaudeCommand(name string) ([]byte, error) {
 // Returns:
 //   - []byte: Hook script content from claude/hooks/
 //   - error: Non-nil if file not found or read fails
-func GetClaudeHook(name string) ([]byte, error) {
+func ClaudeHookByFileName(name string) ([]byte, error) {
 	return FS.ReadFile("claude/hooks/" + name)
 }
diff --git a/internal/validation/validation.go b/internal/validation/validate.go
similarity index 87%
rename from internal/validation/validation.go
rename to internal/validation/validate.go
index a00d8a7d7..5cb870d2b 100644
--- a/internal/validation/validation.go
+++ b/internal/validation/validate.go
@@ -1,8 +1,9 @@
 package validation
 
 import (
-	"regexp"
 	"strings"
+
+	"github.com/ActiveMemory/ctx/internal/config"
 )
 
 // SanitizeFilename converts a topic string to a safe filename component.
@@ -17,8 +18,7 @@ import (
 //   - string: Safe filename component (lowercase, hyphenated, max 50 chars)
 func SanitizeFilename(s string) string {
 	// Replace spaces and special chars with hyphens
-	re := regexp.MustCompile(`[^a-zA-Z0-9-]+`)
-	s = re.ReplaceAllString(s, "-")
+	s = config.RegExNonFileNameChar.ReplaceAllString(s, "-")
 	// Remove leading/trailing hyphens
 	s = strings.Trim(s, "-")
 	// Convert to lowercase
diff --git a/internal/validation/validation_test.go b/internal/validation/validate_test.go
similarity index 100%
rename from internal/validation/validation_test.go
rename to internal/validation/validate_test.go
diff --git a/site/404.html b/site/404.html
index 37c64040b..1e818b630 100644
--- a/site/404.html
+++ b/site/404.html
@@ -19,7 +19,7 @@
       
       
       <link rel="icon" href="/images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -372,7 +372,7 @@
   
   
     <li class="md-nav__item">
-      <a href="/ralph-loop/" class="md-nav__link">
+      <a href="/autonomous-loop/" class="md-nav__link">
         
   
   
@@ -381,7 +381,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
diff --git a/site/ralph-loop/index.html b/site/autonomous-loop/index.html
similarity index 95%
rename from site/ralph-loop/index.html
rename to site/autonomous-loop/index.html
index ad5eb5dae..09c6cf73e 100644
--- a/site/ralph-loop/index.html
+++ b/site/autonomous-loop/index.html
@@ -12,7 +12,7 @@
         <meta name="author" content="Jose Alekhinne <alekhinejose@gmail.com>">
       
       
-        <link rel="canonical" href="https://ctx.ist/ralph-loop/">
+        <link rel="canonical" href="https://ctx.ist/autonomous-loop/">
       
       
         <link rel="prev" href="../context-files/">
@@ -25,11 +25,11 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
-        <title>Ralph and Context - ctx: do you remember?</title>
+        <title>Autonomous Loops - ctx: do you remember?</title>
       
     
     
@@ -85,7 +85,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#ralph-ctx" class="md-skip">
+        <a href="#autonomous-ai-development" class="md-skip">
           Skip to content
         </a>
       
@@ -120,7 +120,7 @@
         <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
             
-              Ralph and Context
+              Autonomous Loops
             
           </span>
         </div>
@@ -399,7 +399,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -419,7 +419,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -444,10 +444,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#ralph-ctx" class="md-nav__link">
+  <a href="#autonomous-ai-development" class="md-nav__link">
     <span class="md-ellipsis">
       
-        ralph + ctx
+        Autonomous AI Development
       
     </span>
   </a>
@@ -527,28 +527,17 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#context-integration" class="md-nav__link">
+  <a href="#why-context-loops-work-well-together" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Context Integration
+        Why Context + Loops Work Well Together
       
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Context Integration">
+    <nav class="md-nav" aria-label="Why Context + Loops Work Well Together">
       <ul class="md-nav__list">
         
-          <li class="md-nav__item">
-  <a href="#why-ctx-ralph-work-well-together" class="md-nav__link">
-    <span class="md-ellipsis">
-      
-        Why ctx + Ralph Work Well Together
-      
-    </span>
-  </a>
-  
-</li>
-        
           <li class="md-nav__item">
   <a href="#automatic-context-updates" class="md-nav__link">
     <span class="md-ellipsis">
@@ -589,10 +578,10 @@
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#sample-tasksmd-for-ralph" class="md-nav__link">
+  <a href="#sample-tasksmd-for-autonomous-loops" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Sample TASKS.md for Ralph
+        Sample TASKS.md for Autonomous Loops
       
     </span>
   </a>
@@ -903,10 +892,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#ralph-ctx" class="md-nav__link">
+  <a href="#autonomous-ai-development" class="md-nav__link">
     <span class="md-ellipsis">
       
-        ralph + ctx
+        Autonomous AI Development
       
     </span>
   </a>
@@ -986,28 +975,17 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#context-integration" class="md-nav__link">
+  <a href="#why-context-loops-work-well-together" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Context Integration
+        Why Context + Loops Work Well Together
       
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Context Integration">
+    <nav class="md-nav" aria-label="Why Context + Loops Work Well Together">
       <ul class="md-nav__list">
         
-          <li class="md-nav__item">
-  <a href="#why-ctx-ralph-work-well-together" class="md-nav__link">
-    <span class="md-ellipsis">
-      
-        Why ctx + Ralph Work Well Together
-      
-    </span>
-  </a>
-  
-</li>
-        
           <li class="md-nav__item">
   <a href="#automatic-context-updates" class="md-nav__link">
     <span class="md-ellipsis">
@@ -1048,10 +1026,10 @@
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#sample-tasksmd-for-ralph" class="md-nav__link">
+  <a href="#sample-tasksmd-for-autonomous-loops" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Sample TASKS.md for Ralph
+        Sample TASKS.md for Autonomous Loops
       
     </span>
   </a>
@@ -1161,20 +1139,25 @@
   
 
 
-  <h1>Ralph and Context</h1>
+  <h1>Autonomous Loops</h1>
 
 <p><img alt="ctx" src="../images/ctx-banner.png" /></p>
-<h2 id="ralph-ctx"><code>ralph</code> + <code>ctx</code><a class="headerlink" href="#ralph-ctx" title="Permanent link">&para;</a></h2>
-<p><em>Like peanut butter and jelly: better together.</em></p>
-<p>The <a href="https://ghuntley.com/ralph/">Ralph Wiggum technique</a> is an iterative AI development workflow where 
-an agent works autonomously on tasks until completion. Context (<code>ctx</code>) and 
-Ralph complement each other perfectly:</p>
+<h2 id="autonomous-ai-development">Autonomous AI Development<a class="headerlink" href="#autonomous-ai-development" title="Permanent link">&para;</a></h2>
+<p><em>Iterate until done.</em></p>
+<p>An autonomous loop is an iterative AI development workflow where an agent works
+on tasks until completion—without constant human intervention. Context (<code>ctx</code>)
+provides the memory that makes this possible:</p>
 <ul>
-<li><strong><code>ctx</code></strong> provides the <em>memory</em>: persistent context that survives across sessions</li>
-<li><strong><code>ralph</code></strong> provides the <em>loop</em>: autonomous iteration that runs until done</li>
+<li><strong><code>ctx</code></strong> provides the <em>memory</em>: persistent context that survives across iterations</li>
+<li><strong>The loop</strong> provides the <em>automation</em>: continuous execution until done</li>
 </ul>
-<p>Together, they enable fully autonomous AI development where the agent remembers 
+<p>Together, they enable fully autonomous AI development where the agent remembers
 everything across iterations.</p>
+<div class="admonition note">
+<p class="admonition-title">Origin</p>
+<p>This pattern is inspired by <a href="https://ghuntley.com/ralph/">Geoffrey Huntley's Ralph Wiggum technique</a>.
+We use generic terminology here so the concepts remain clear regardless of trends.</p>
+</div>
 <h2 id="how-it-works">How It Works<a class="headerlink" href="#how-it-works" title="Permanent link">&para;</a></h2>
 <pre class="mermaid"><code>graph TD
     A[Start Loop] --&gt; B[Load PROMPT.md]
@@ -1197,12 +1180,12 @@ <h2 id="how-it-works">How It Works<a class="headerlink" href="#how-it-works" tit
 <li>Repeat until converged or blocked</li>
 </ol>
 <h2 id="quick-start-with-claude-code">Quick Start with Claude Code<a class="headerlink" href="#quick-start-with-claude-code" title="Permanent link">&para;</a></h2>
-<p>Claude Code has a built-in Ralph Loop plugin:</p>
+<p>Claude Code has built-in loop support:</p>
 <div class="language-bash highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="c1"># Start autonomous loop</span>
-</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>/ralph-loop
+</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>/loop
 </span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
 </span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="c1"># Cancel running loop</span>
-</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>/cancel-ralph
+</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>/cancel-loop
 </span></code></pre></div>
 <p>That's it. The loop will:</p>
 <ol>
@@ -1213,11 +1196,11 @@ <h2 id="quick-start-with-claude-code">Quick Start with Claude Code<a class="head
 <h2 id="manual-loop-setup">Manual Loop Setup<a class="headerlink" href="#manual-loop-setup" title="Permanent link">&para;</a></h2>
 <p>For other AI tools, create a <code>loop.sh</code>:</p>
 <div class="language-bash highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="ch">#!/bin/bash</span>
-</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="c1"># loop.sh — a minimal Ralph loop</span>
+</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="c1"># loop.sh — an autonomous iteration loop</span>
 </span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
 </span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="nv">PROMPT_FILE</span><span class="o">=</span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">1</span><span class="k">:-</span><span class="nv">PROMPT</span><span class="p">.md</span><span class="si">}</span><span class="s2">&quot;</span>
 </span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a><span class="nv">MAX_ITERATIONS</span><span class="o">=</span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">2</span><span class="k">:-</span><span class="nv">10</span><span class="si">}</span><span class="s2">&quot;</span>
-</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="nv">OUTPUT_FILE</span><span class="o">=</span><span class="s2">&quot;/tmp/ralph_output.txt&quot;</span>
+</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="nv">OUTPUT_FILE</span><span class="o">=</span><span class="s2">&quot;/tmp/loop_output.txt&quot;</span>
 </span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>
 </span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a><span class="k">for</span><span class="w"> </span>i<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="k">$(</span>seq<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="nv">$MAX_ITERATIONS</span><span class="k">)</span><span class="p">;</span><span class="w"> </span><span class="k">do</span>
 </span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="w">  </span><span class="nb">echo</span><span class="w"> </span><span class="s2">&quot;=== Iteration </span><span class="nv">$i</span><span class="s2"> ===&quot;</span>
@@ -1246,6 +1229,7 @@ <h2 id="manual-loop-setup">Manual Loop Setup<a class="headerlink" href="#manual-
 <div class="language-bash highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>chmod<span class="w"> </span>+x<span class="w"> </span>loop.sh
 </span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>./loop.sh
 </span></code></pre></div>
+<p>You can also generate this script with <code>ctx loop</code> (see <a href="../cli-reference/#ctx-loop">CLI Reference</a>).</p>
 <h2 id="the-promptmd-file">The PROMPT.md File<a class="headerlink" href="#the-promptmd-file" title="Permanent link">&para;</a></h2>
 <p>The prompt file instructs the AI on how to work autonomously. Here's a template:</p>
 <div class="language-markdown highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="gh"># Autonomous Development Prompt</span>
@@ -1346,8 +1330,7 @@ <h3 id="example-usage">Example Usage<a class="headerlink" href="#example-usage"
 </span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>
 </span><span id="__span-5-7"><a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a>SYSTEM_BLOCKED
 </span></code></pre></div>
-<h2 id="context-integration">Context Integration<a class="headerlink" href="#context-integration" title="Permanent link">&para;</a></h2>
-<h3 id="why-ctx-ralph-work-well-together">Why ctx + Ralph Work Well Together<a class="headerlink" href="#why-ctx-ralph-work-well-together" title="Permanent link">&para;</a></h3>
+<h2 id="why-context-loops-work-well-together">Why Context + Loops Work Well Together<a class="headerlink" href="#why-context-loops-work-well-together" title="Permanent link">&para;</a></h2>
 <table>
 <thead>
 <tr>
@@ -1399,7 +1382,7 @@ <h2 id="advanced-watch-mode">Advanced: Watch Mode<a class="headerlink" href="#ad
 </span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="c1"># Terminal 2: Watch for context updates</span>
 </span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/loop.log<span class="w"> </span>--auto-save
 </span></code></pre></div>
-<p>The <code>--auto-save</code> flag periodically saves session snapshots, creating a 
+<p>The <code>--auto-save</code> flag periodically saves session snapshots, creating a
 history of the loop's progress.</p>
 <h2 id="example-project-setup">Example Project Setup<a class="headerlink" href="#example-project-setup" title="Permanent link">&para;</a></h2>
 <div class="language-text highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>my-project/
@@ -1414,7 +1397,7 @@ <h2 id="example-project-setup">Example Project Setup<a class="headerlink" href="
 </span><span id="__span-12-10"><a id="__codelineno-12-10" name="__codelineno-12-10" href="#__codelineno-12-10"></a>├── loop.sh               # Loop script (if not using Claude Code)
 </span><span id="__span-12-11"><a id="__codelineno-12-11" name="__codelineno-12-11" href="#__codelineno-12-11"></a>└── src/                  # Your code
 </span></code></pre></div>
-<h3 id="sample-tasksmd-for-ralph">Sample TASKS.md for Ralph<a class="headerlink" href="#sample-tasksmd-for-ralph" title="Permanent link">&para;</a></h3>
+<h3 id="sample-tasksmd-for-autonomous-loops">Sample TASKS.md for Autonomous Loops<a class="headerlink" href="#sample-tasksmd-for-autonomous-loops" title="Permanent link">&para;</a></h3>
 <div class="language-markdown highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="gh"># Tasks</span>
 </span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a>
 </span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="gu">## Phase 1: Setup</span>
@@ -1468,7 +1451,7 @@ <h3 id="ai-violating-constitution">AI Violating Constitution<a class="headerlink
 </span></code></pre></div></p>
 <h2 id="resources">Resources<a class="headerlink" href="#resources" title="Permanent link">&para;</a></h2>
 <ul>
-<li><a href="https://ghuntley.com/ralph/">Ralph Wiggum Technique</a> — Original blog post</li>
+<li><a href="https://ghuntley.com/ralph/">Geoffrey Huntley's Ralph Wiggum Technique</a> — Original inspiration</li>
 <li><a href="../cli-reference/">Context CLI</a> — Command reference</li>
 <li><a href="../integrations/">Integrations</a> — Tool-specific setup</li>
 </ul>
diff --git a/site/blog/2026-01-27-building-ctx-using-ctx/index.html b/site/blog/2026-01-27-building-ctx-using-ctx/index.html
index 9e8e52bef..2ca0ee373 100644
--- a/site/blog/2026-01-27-building-ctx-using-ctx/index.html
+++ b/site/blog/2026-01-27-building-ctx-using-ctx/index.html
@@ -23,7 +23,7 @@
       
       
       <link rel="icon" href="../../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -381,7 +381,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../ralph-loop/" class="md-nav__link">
+      <a href="../../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -390,7 +390,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -1093,11 +1093,12 @@ <h2 id="ai-amnesia">AI Amnesia<a class="headerlink" href="#ai-amnesia" title="Pe
 <p>That is "<em>reset amnesia</em>", and it's not just annoying: it's expensive. </p>
 <p>Every session starts with re-explaining context, re-reading files, 
 re-discovering decisions that were already made.</p>
-<blockquote>
-<p>"I don't want to lose this discussion... 
-I am a brain-dead developer YOLO'ing my way out"</p>
-</blockquote>
-<p>That's exactly what I said to Claude when I first started working on <code>ctx</code>.</p>
+<div class="admonition quote">
+<p class="admonition-title">I Needed Context</p>
+<p>I don't want to lose this discussion... 
+I am a brain-dead developer YOLO'ing my way out</p>
+</div>
+<p>☝️ that's exactly what I said to Claude when I first started working on <code>ctx</code>.</p>
 <h2 id="the-genesis">The Genesis<a class="headerlink" href="#the-genesis" title="Permanent link">&para;</a></h2>
 <p>The project started as "<em>Active Memory</em>" (<code>amem</code>): a CLI tool to persist AI 
 context across sessions. </p>
diff --git a/site/blog/index.html b/site/blog/index.html
index 209e54ade..79fd88d42 100644
--- a/site/blog/index.html
+++ b/site/blog/index.html
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -383,7 +383,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -392,7 +392,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -726,9 +726,13 @@ <h1 id="blog">Blog<a class="headerlink" href="#blog" title="Permanent link">&par
 <hr />
 <h2 id="posts">Posts<a class="headerlink" href="#posts" title="Permanent link">&para;</a></h2>
 <h3 id="building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development"><a href="2026-01-27-building-ctx-using-ctx/">Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development</a><a class="headerlink" href="#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development" title="Permanent link">&para;</a></h3>
-<p><em>January 27, 2026</em></p>
-<p>What happens when you build a tool designed to give AI memory, using that very same tool to remember what you're building? This is the story of ctx—how it evolved from a hasty "YOLO mode" experiment to a disciplined system for persistent AI context, and what we learned along the way.</p>
-<p><strong>Topics</strong>: dogfooding, AI-assisted development, Ralph Loop, session persistence, architectural decisions</p>
+<p><em>Jose Alekhinne / January 27, 2026</em></p>
+<p>What happens when you build a tool designed to give AI memory, using that very 
+same tool to remember what you're building? This is the story of ctx—how it 
+evolved from a hasty "YOLO mode" experiment to a disciplined system for 
+persistent AI context, and what we learned along the way.</p>
+<p><strong>Topics</strong>: dogfooding, AI-assisted development, Ralph Loop, session 
+persistence, architectural decisions</p>
 <hr />
 <p><em>More posts coming soon.</em></p>
 
diff --git a/site/cli-reference/index.html b/site/cli-reference/index.html
index e4585dc8a..23ff09170 100644
--- a/site/cli-reference/index.html
+++ b/site/cli-reference/index.html
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -645,11 +645,61 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ctx-recall-export" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx recall export
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ctx-journal" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx journal
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="ctx journal">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#ctx-journal-site" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx journal site
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
     </nav>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ctx-serve" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx serve
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -828,7 +878,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -837,7 +887,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -1328,11 +1378,61 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ctx-recall-export" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx recall export
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ctx-journal" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx journal
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="ctx journal">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#ctx-journal-site" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx journal site
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
     </nav>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ctx-serve" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ctx serve
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -1521,10 +1621,6 @@ <h2 id="global-options">Global Options<a class="headerlink" href="#global-option
 <td>Override context directory (default: <code>.context/</code>)</td>
 </tr>
 <tr>
-<td><code>--quiet</code></td>
-<td>Suppress non-essential output</td>
-</tr>
-<tr>
 <td><code>--no-color</code></td>
 <td>Disable colored output</td>
 </tr>
@@ -2095,12 +2191,105 @@ <h4 id="ctx-recall-show"><code>ctx recall show</code><a class="headerlink" href=
 </span><span id="__span-33-3"><a id="__codelineno-33-3" name="__codelineno-33-3" href="#__codelineno-33-3"></a>ctx<span class="w"> </span>recall<span class="w"> </span>show<span class="w"> </span>--latest
 </span><span id="__span-33-4"><a id="__codelineno-33-4" name="__codelineno-33-4" href="#__codelineno-33-4"></a>ctx<span class="w"> </span>recall<span class="w"> </span>show<span class="w"> </span>--latest<span class="w"> </span>--full
 </span></code></pre></div>
+<h4 id="ctx-recall-export"><code>ctx recall export</code><a class="headerlink" href="#ctx-recall-export" title="Permanent link">&para;</a></h4>
+<p>Export sessions to editable journal files in <code>.context/journal/</code>.</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-34-1"><a id="__codelineno-34-1" name="__codelineno-34-1" href="#__codelineno-34-1"></a>ctx<span class="w"> </span>recall<span class="w"> </span><span class="nb">export</span><span class="w"> </span><span class="o">[</span>session-id<span class="o">]</span><span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+</span></code></pre></div>
+<p><strong>Flags</strong>:</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--all</code></td>
+<td>Export all sessions</td>
+</tr>
+<tr>
+<td><code>--force</code></td>
+<td>Overwrite existing files</td>
+</tr>
+</tbody>
+</table>
+<p>Exported files include session metadata, tool usage summary, and the full
+conversation. Existing files are skipped by default to preserve your edits.</p>
+<p>The <code>journal/</code> directory should be gitignored (like <code>sessions/</code>) since it
+contains raw conversation data.</p>
+<p><strong>Example</strong>:</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-35-1"><a id="__codelineno-35-1" name="__codelineno-35-1" href="#__codelineno-35-1"></a>ctx<span class="w"> </span>recall<span class="w"> </span><span class="nb">export</span><span class="w"> </span>abc123<span class="w">          </span><span class="c1"># Export one session</span>
+</span><span id="__span-35-2"><a id="__codelineno-35-2" name="__codelineno-35-2" href="#__codelineno-35-2"></a>ctx<span class="w"> </span>recall<span class="w"> </span><span class="nb">export</span><span class="w"> </span>--all<span class="w">           </span><span class="c1"># Export all sessions</span>
+</span><span id="__span-35-3"><a id="__codelineno-35-3" name="__codelineno-35-3" href="#__codelineno-35-3"></a>ctx<span class="w"> </span>recall<span class="w"> </span><span class="nb">export</span><span class="w"> </span>--all<span class="w"> </span>--force<span class="w">   </span><span class="c1"># Overwrite existing exports</span>
+</span></code></pre></div>
+<hr />
+<h3 id="ctx-journal"><code>ctx journal</code><a class="headerlink" href="#ctx-journal" title="Permanent link">&para;</a></h3>
+<p>Analyze and synthesize exported session files.</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-36-1"><a id="__codelineno-36-1" name="__codelineno-36-1" href="#__codelineno-36-1"></a>ctx<span class="w"> </span>journal<span class="w"> </span>&lt;subcommand&gt;
+</span></code></pre></div>
+<h4 id="ctx-journal-site"><code>ctx journal site</code><a class="headerlink" href="#ctx-journal-site" title="Permanent link">&para;</a></h4>
+<p>Generate a static site from journal entries in <code>.context/journal/</code>.</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-37-1"><a id="__codelineno-37-1" name="__codelineno-37-1" href="#__codelineno-37-1"></a>ctx<span class="w"> </span>journal<span class="w"> </span>site<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+</span></code></pre></div>
+<p><strong>Flags</strong>:</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Short</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--output</code></td>
+<td><code>-o</code></td>
+<td>Output directory (default: .context/journal-site)</td>
+</tr>
+<tr>
+<td><code>--build</code></td>
+<td></td>
+<td>Run zensical build after generating</td>
+</tr>
+<tr>
+<td><code>--serve</code></td>
+<td></td>
+<td>Run zensical serve after generating</td>
+</tr>
+</tbody>
+</table>
+<p>Creates a zensical-compatible site structure with an index page listing
+all sessions by date, and individual pages for each journal entry.</p>
+<p>Requires zensical to be installed for <code>--build</code> or <code>--serve</code>:
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-38-1"><a id="__codelineno-38-1" name="__codelineno-38-1" href="#__codelineno-38-1"></a>pip<span class="w"> </span>install<span class="w"> </span>zensical
+</span></code></pre></div></p>
+<p><strong>Example</strong>:</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-39-1"><a id="__codelineno-39-1" name="__codelineno-39-1" href="#__codelineno-39-1"></a>ctx<span class="w"> </span>journal<span class="w"> </span>site<span class="w">                    </span><span class="c1"># Generate in .context/journal-site/</span>
+</span><span id="__span-39-2"><a id="__codelineno-39-2" name="__codelineno-39-2" href="#__codelineno-39-2"></a>ctx<span class="w"> </span>journal<span class="w"> </span>site<span class="w"> </span>--output<span class="w"> </span>~/public<span class="w">  </span><span class="c1"># Custom output directory</span>
+</span><span id="__span-39-3"><a id="__codelineno-39-3" name="__codelineno-39-3" href="#__codelineno-39-3"></a>ctx<span class="w"> </span>journal<span class="w"> </span>site<span class="w"> </span>--build<span class="w">            </span><span class="c1"># Generate and build HTML</span>
+</span><span id="__span-39-4"><a id="__codelineno-39-4" name="__codelineno-39-4" href="#__codelineno-39-4"></a>ctx<span class="w"> </span>journal<span class="w"> </span>site<span class="w"> </span>--serve<span class="w">            </span><span class="c1"># Generate and serve locally</span>
+</span></code></pre></div>
+<hr />
+<h3 id="ctx-serve"><code>ctx serve</code><a class="headerlink" href="#ctx-serve" title="Permanent link">&para;</a></h3>
+<p>Serve a static site locally via zensical.</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-40-1"><a id="__codelineno-40-1" name="__codelineno-40-1" href="#__codelineno-40-1"></a>ctx<span class="w"> </span>serve<span class="w"> </span><span class="o">[</span>directory<span class="o">]</span>
+</span></code></pre></div>
+<p>If no directory is specified, serves the journal site (<code>.context/journal-site</code>).</p>
+<p>Requires zensical to be installed:
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-41-1"><a id="__codelineno-41-1" name="__codelineno-41-1" href="#__codelineno-41-1"></a>pip<span class="w"> </span>install<span class="w"> </span>zensical
+</span></code></pre></div></p>
+<p><strong>Example</strong>:</p>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-42-1"><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a>ctx<span class="w"> </span>serve<span class="w">                           </span><span class="c1"># Serve journal site</span>
+</span><span id="__span-42-2"><a id="__codelineno-42-2" name="__codelineno-42-2" href="#__codelineno-42-2"></a>ctx<span class="w"> </span>serve<span class="w"> </span>.context/journal-site<span class="w">     </span><span class="c1"># Serve specific directory</span>
+</span><span id="__span-42-3"><a id="__codelineno-42-3" name="__codelineno-42-3" href="#__codelineno-42-3"></a>ctx<span class="w"> </span>serve<span class="w"> </span>./docs<span class="w">                    </span><span class="c1"># Serve docs folder</span>
+</span></code></pre></div>
 <hr />
 <h3 id="ctx-watch"><code>ctx watch</code><a class="headerlink" href="#ctx-watch" title="Permanent link">&para;</a></h3>
 <p>Watch for AI output and auto-apply context updates.</p>
 <p>Parses <code>&lt;context-update&gt;</code> XML commands from AI output and applies
 them to context files.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-34-1"><a id="__codelineno-34-1" name="__codelineno-34-1" href="#__codelineno-34-1"></a>ctx<span class="w"> </span>watch<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-43-1"><a id="__codelineno-43-1" name="__codelineno-43-1" href="#__codelineno-43-1"></a>ctx<span class="w"> </span>watch<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
 </span></code></pre></div>
 <p><strong>Flags</strong>:</p>
 <table>
@@ -2126,19 +2315,19 @@ <h3 id="ctx-watch"><code>ctx watch</code><a class="headerlink" href="#ctx-watch"
 </tbody>
 </table>
 <p><strong>Example</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-35-1"><a id="__codelineno-35-1" name="__codelineno-35-1" href="#__codelineno-35-1"></a><span class="c1"># Watch stdin</span>
-</span><span id="__span-35-2"><a id="__codelineno-35-2" name="__codelineno-35-2" href="#__codelineno-35-2"></a>ai-tool<span class="w"> </span><span class="p">|</span><span class="w"> </span>ctx<span class="w"> </span>watch
-</span><span id="__span-35-3"><a id="__codelineno-35-3" name="__codelineno-35-3" href="#__codelineno-35-3"></a>
-</span><span id="__span-35-4"><a id="__codelineno-35-4" name="__codelineno-35-4" href="#__codelineno-35-4"></a><span class="c1"># Watch a log file</span>
-</span><span id="__span-35-5"><a id="__codelineno-35-5" name="__codelineno-35-5" href="#__codelineno-35-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/path/to/ai-output.log
-</span><span id="__span-35-6"><a id="__codelineno-35-6" name="__codelineno-35-6" href="#__codelineno-35-6"></a>
-</span><span id="__span-35-7"><a id="__codelineno-35-7" name="__codelineno-35-7" href="#__codelineno-35-7"></a><span class="c1"># Preview without applying</span>
-</span><span id="__span-35-8"><a id="__codelineno-35-8" name="__codelineno-35-8" href="#__codelineno-35-8"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--dry-run
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-44-1"><a id="__codelineno-44-1" name="__codelineno-44-1" href="#__codelineno-44-1"></a><span class="c1"># Watch stdin</span>
+</span><span id="__span-44-2"><a id="__codelineno-44-2" name="__codelineno-44-2" href="#__codelineno-44-2"></a>ai-tool<span class="w"> </span><span class="p">|</span><span class="w"> </span>ctx<span class="w"> </span>watch
+</span><span id="__span-44-3"><a id="__codelineno-44-3" name="__codelineno-44-3" href="#__codelineno-44-3"></a>
+</span><span id="__span-44-4"><a id="__codelineno-44-4" name="__codelineno-44-4" href="#__codelineno-44-4"></a><span class="c1"># Watch a log file</span>
+</span><span id="__span-44-5"><a id="__codelineno-44-5" name="__codelineno-44-5" href="#__codelineno-44-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/path/to/ai-output.log
+</span><span id="__span-44-6"><a id="__codelineno-44-6" name="__codelineno-44-6" href="#__codelineno-44-6"></a>
+</span><span id="__span-44-7"><a id="__codelineno-44-7" name="__codelineno-44-7" href="#__codelineno-44-7"></a><span class="c1"># Preview without applying</span>
+</span><span id="__span-44-8"><a id="__codelineno-44-8" name="__codelineno-44-8" href="#__codelineno-44-8"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--dry-run
 </span></code></pre></div>
 <hr />
 <h3 id="ctx-hook"><code>ctx hook</code><a class="headerlink" href="#ctx-hook" title="Permanent link">&para;</a></h3>
 <p>Generate AI tool integration configuration.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-36-1"><a id="__codelineno-36-1" name="__codelineno-36-1" href="#__codelineno-36-1"></a>ctx<span class="w"> </span>hook<span class="w"> </span>&lt;tool&gt;
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-45-1"><a id="__codelineno-45-1" name="__codelineno-45-1" href="#__codelineno-45-1"></a>ctx<span class="w"> </span>hook<span class="w"> </span>&lt;tool&gt;
 </span></code></pre></div>
 <p><strong>Supported tools</strong>:</p>
 <table>
@@ -2172,16 +2361,16 @@ <h3 id="ctx-hook"><code>ctx hook</code><a class="headerlink" href="#ctx-hook" ti
 </tbody>
 </table>
 <p><strong>Example</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-37-1"><a id="__codelineno-37-1" name="__codelineno-37-1" href="#__codelineno-37-1"></a>ctx<span class="w"> </span>hook<span class="w"> </span>claude-code
-</span><span id="__span-37-2"><a id="__codelineno-37-2" name="__codelineno-37-2" href="#__codelineno-37-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>cursor
-</span><span id="__span-37-3"><a id="__codelineno-37-3" name="__codelineno-37-3" href="#__codelineno-37-3"></a>ctx<span class="w"> </span>hook<span class="w"> </span>aider
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-46-1"><a id="__codelineno-46-1" name="__codelineno-46-1" href="#__codelineno-46-1"></a>ctx<span class="w"> </span>hook<span class="w"> </span>claude-code
+</span><span id="__span-46-2"><a id="__codelineno-46-2" name="__codelineno-46-2" href="#__codelineno-46-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>cursor
+</span><span id="__span-46-3"><a id="__codelineno-46-3" name="__codelineno-46-3" href="#__codelineno-46-3"></a>ctx<span class="w"> </span>hook<span class="w"> </span>aider
 </span></code></pre></div>
 <hr />
 <h3 id="ctx-session"><code>ctx session</code><a class="headerlink" href="#ctx-session" title="Permanent link">&para;</a></h3>
 <p>Manage session snapshots.</p>
 <h4 id="ctx-session-save">ctx session save<a class="headerlink" href="#ctx-session-save" title="Permanent link">&para;</a></h4>
 <p>Save the current context snapshot.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-38-1"><a id="__codelineno-38-1" name="__codelineno-38-1" href="#__codelineno-38-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>save<span class="w"> </span><span class="o">[</span>topic<span class="o">]</span><span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-47-1"><a id="__codelineno-47-1" name="__codelineno-47-1" href="#__codelineno-47-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>save<span class="w"> </span><span class="o">[</span>topic<span class="o">]</span><span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
 </span></code></pre></div>
 <p><strong>Flags</strong>:</p>
 <table>
@@ -2201,13 +2390,13 @@ <h4 id="ctx-session-save">ctx session save<a class="headerlink" href="#ctx-sessi
 </tbody>
 </table>
 <p><strong>Example</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-39-1"><a id="__codelineno-39-1" name="__codelineno-39-1" href="#__codelineno-39-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>save
-</span><span id="__span-39-2"><a id="__codelineno-39-2" name="__codelineno-39-2" href="#__codelineno-39-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>save<span class="w"> </span><span class="s2">&quot;feature-auth&quot;</span>
-</span><span id="__span-39-3"><a id="__codelineno-39-3" name="__codelineno-39-3" href="#__codelineno-39-3"></a>ctx<span class="w"> </span>session<span class="w"> </span>save<span class="w"> </span><span class="s2">&quot;bugfix&quot;</span><span class="w"> </span>--type<span class="w"> </span>bugfix
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-48-1"><a id="__codelineno-48-1" name="__codelineno-48-1" href="#__codelineno-48-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>save
+</span><span id="__span-48-2"><a id="__codelineno-48-2" name="__codelineno-48-2" href="#__codelineno-48-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>save<span class="w"> </span><span class="s2">&quot;feature-auth&quot;</span>
+</span><span id="__span-48-3"><a id="__codelineno-48-3" name="__codelineno-48-3" href="#__codelineno-48-3"></a>ctx<span class="w"> </span>session<span class="w"> </span>save<span class="w"> </span><span class="s2">&quot;bugfix&quot;</span><span class="w"> </span>--type<span class="w"> </span>bugfix
 </span></code></pre></div>
 <h4 id="ctx-session-list"><code>ctx session list</code><a class="headerlink" href="#ctx-session-list" title="Permanent link">&para;</a></h4>
 <p>List saved sessions.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-40-1"><a id="__codelineno-40-1" name="__codelineno-40-1" href="#__codelineno-40-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>list<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-49-1"><a id="__codelineno-49-1" name="__codelineno-49-1" href="#__codelineno-49-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>list<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
 </span></code></pre></div>
 <p><strong>Flags</strong>:</p>
 <table>
@@ -2228,12 +2417,12 @@ <h4 id="ctx-session-list"><code>ctx session list</code><a class="headerlink" hre
 </table>
 <p><strong>Output</strong>: Table of sessions with index, date, topic, and type.</p>
 <p><strong>Example</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-41-1"><a id="__codelineno-41-1" name="__codelineno-41-1" href="#__codelineno-41-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>list
-</span><span id="__span-41-2"><a id="__codelineno-41-2" name="__codelineno-41-2" href="#__codelineno-41-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>list<span class="w"> </span>--limit<span class="w"> </span><span class="m">5</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-50-1"><a id="__codelineno-50-1" name="__codelineno-50-1" href="#__codelineno-50-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>list
+</span><span id="__span-50-2"><a id="__codelineno-50-2" name="__codelineno-50-2" href="#__codelineno-50-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>list<span class="w"> </span>--limit<span class="w"> </span><span class="m">5</span>
 </span></code></pre></div>
 <h4 id="ctx-session-load"><code>ctx session load</code><a class="headerlink" href="#ctx-session-load" title="Permanent link">&para;</a></h4>
 <p>Load and display a previous session.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-42-1"><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span>&lt;index<span class="p">|</span>date<span class="p">|</span>topic&gt;
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-51-1"><a id="__codelineno-51-1" name="__codelineno-51-1" href="#__codelineno-51-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span>&lt;index<span class="p">|</span>date<span class="p">|</span>topic&gt;
 </span></code></pre></div>
 <p><strong>Arguments</strong>:</p>
 <ul>
@@ -2242,13 +2431,13 @@ <h4 id="ctx-session-load"><code>ctx session load</code><a class="headerlink" hre
 <li><code>topic</code>: Topic keyword match</li>
 </ul>
 <p><strong>Example:</strong></p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-43-1"><a id="__codelineno-43-1" name="__codelineno-43-1" href="#__codelineno-43-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span><span class="m">1</span><span class="w">           </span><span class="c1"># by index</span>
-</span><span id="__span-43-2"><a id="__codelineno-43-2" name="__codelineno-43-2" href="#__codelineno-43-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span><span class="m">2026</span>-01-21<span class="w">  </span><span class="c1"># by date</span>
-</span><span id="__span-43-3"><a id="__codelineno-43-3" name="__codelineno-43-3" href="#__codelineno-43-3"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span>auth<span class="w">        </span><span class="c1"># by topic</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-52-1"><a id="__codelineno-52-1" name="__codelineno-52-1" href="#__codelineno-52-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span><span class="m">1</span><span class="w">           </span><span class="c1"># by index</span>
+</span><span id="__span-52-2"><a id="__codelineno-52-2" name="__codelineno-52-2" href="#__codelineno-52-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span><span class="m">2026</span>-01-21<span class="w">  </span><span class="c1"># by date</span>
+</span><span id="__span-52-3"><a id="__codelineno-52-3" name="__codelineno-52-3" href="#__codelineno-52-3"></a>ctx<span class="w"> </span>session<span class="w"> </span>load<span class="w"> </span>auth<span class="w">        </span><span class="c1"># by topic</span>
 </span></code></pre></div>
 <h4 id="ctx-session-parse"><code>ctx session parse</code><a class="headerlink" href="#ctx-session-parse" title="Permanent link">&para;</a></h4>
 <p>Parse JSONL transcript to readable markdown.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-44-1"><a id="__codelineno-44-1" name="__codelineno-44-1" href="#__codelineno-44-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>&lt;file&gt;<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-53-1"><a id="__codelineno-53-1" name="__codelineno-53-1" href="#__codelineno-53-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>&lt;file&gt;<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
 </span></code></pre></div>
 <p><strong>Flags:</strong></p>
 <table>
@@ -2273,17 +2462,17 @@ <h4 id="ctx-session-parse"><code>ctx session parse</code><a class="headerlink" h
 </tbody>
 </table>
 <p><strong>Example</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-45-1"><a id="__codelineno-45-1" name="__codelineno-45-1" href="#__codelineno-45-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>~/.claude/projects/.../transcript.jsonl
-</span><span id="__span-45-2"><a id="__codelineno-45-2" name="__codelineno-45-2" href="#__codelineno-45-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>transcript.jsonl<span class="w"> </span>--extract
-</span><span id="__span-45-3"><a id="__codelineno-45-3" name="__codelineno-45-3" href="#__codelineno-45-3"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>transcript.jsonl<span class="w"> </span>-o<span class="w"> </span>conversation.md
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-54-1"><a id="__codelineno-54-1" name="__codelineno-54-1" href="#__codelineno-54-1"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>~/.claude/projects/.../transcript.jsonl
+</span><span id="__span-54-2"><a id="__codelineno-54-2" name="__codelineno-54-2" href="#__codelineno-54-2"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>transcript.jsonl<span class="w"> </span>--extract
+</span><span id="__span-54-3"><a id="__codelineno-54-3" name="__codelineno-54-3" href="#__codelineno-54-3"></a>ctx<span class="w"> </span>session<span class="w"> </span>parse<span class="w"> </span>transcript.jsonl<span class="w"> </span>-o<span class="w"> </span>conversation.md
 </span></code></pre></div>
 <hr />
 <h3 id="ctx-loop"><code>ctx loop</code><a class="headerlink" href="#ctx-loop" title="Permanent link">&para;</a></h3>
-<p>Generate a shell script for running a Ralph loop.</p>
-<p>A Ralph loop continuously runs an AI assistant with the same prompt until
+<p>Generate a shell script for running an autonomous loop.</p>
+<p>An autonomous loop continuously runs an AI assistant with the same prompt until
 a completion signal is detected, enabling iterative development where the
 AI builds on its previous work.</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-46-1"><a id="__codelineno-46-1" name="__codelineno-46-1" href="#__codelineno-46-1"></a>ctx<span class="w"> </span>loop<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-55-1"><a id="__codelineno-55-1" name="__codelineno-55-1" href="#__codelineno-55-1"></a>ctx<span class="w"> </span>loop<span class="w"> </span><span class="o">[</span>flags<span class="o">]</span>
 </span></code></pre></div>
 <p><strong>Flags</strong>:</p>
 <table>
@@ -2329,25 +2518,25 @@ <h3 id="ctx-loop"><code>ctx loop</code><a class="headerlink" href="#ctx-loop" ti
 </tbody>
 </table>
 <p><strong>Example</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-47-1"><a id="__codelineno-47-1" name="__codelineno-47-1" href="#__codelineno-47-1"></a><span class="c1"># Generate loop.sh for Claude Code</span>
-</span><span id="__span-47-2"><a id="__codelineno-47-2" name="__codelineno-47-2" href="#__codelineno-47-2"></a>ctx<span class="w"> </span>loop
-</span><span id="__span-47-3"><a id="__codelineno-47-3" name="__codelineno-47-3" href="#__codelineno-47-3"></a>
-</span><span id="__span-47-4"><a id="__codelineno-47-4" name="__codelineno-47-4" href="#__codelineno-47-4"></a><span class="c1"># Generate for Aider with custom prompt</span>
-</span><span id="__span-47-5"><a id="__codelineno-47-5" name="__codelineno-47-5" href="#__codelineno-47-5"></a>ctx<span class="w"> </span>loop<span class="w"> </span>--tool<span class="w"> </span>aider<span class="w"> </span>--prompt<span class="w"> </span>TASKS.md
-</span><span id="__span-47-6"><a id="__codelineno-47-6" name="__codelineno-47-6" href="#__codelineno-47-6"></a>
-</span><span id="__span-47-7"><a id="__codelineno-47-7" name="__codelineno-47-7" href="#__codelineno-47-7"></a><span class="c1"># Limit to 10 iterations</span>
-</span><span id="__span-47-8"><a id="__codelineno-47-8" name="__codelineno-47-8" href="#__codelineno-47-8"></a>ctx<span class="w"> </span>loop<span class="w"> </span>--max-iterations<span class="w"> </span><span class="m">10</span>
-</span><span id="__span-47-9"><a id="__codelineno-47-9" name="__codelineno-47-9" href="#__codelineno-47-9"></a>
-</span><span id="__span-47-10"><a id="__codelineno-47-10" name="__codelineno-47-10" href="#__codelineno-47-10"></a><span class="c1"># Output to custom file</span>
-</span><span id="__span-47-11"><a id="__codelineno-47-11" name="__codelineno-47-11" href="#__codelineno-47-11"></a>ctx<span class="w"> </span>loop<span class="w"> </span>-o<span class="w"> </span>my-loop.sh
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-56-1"><a id="__codelineno-56-1" name="__codelineno-56-1" href="#__codelineno-56-1"></a><span class="c1"># Generate loop.sh for Claude Code</span>
+</span><span id="__span-56-2"><a id="__codelineno-56-2" name="__codelineno-56-2" href="#__codelineno-56-2"></a>ctx<span class="w"> </span>loop
+</span><span id="__span-56-3"><a id="__codelineno-56-3" name="__codelineno-56-3" href="#__codelineno-56-3"></a>
+</span><span id="__span-56-4"><a id="__codelineno-56-4" name="__codelineno-56-4" href="#__codelineno-56-4"></a><span class="c1"># Generate for Aider with custom prompt</span>
+</span><span id="__span-56-5"><a id="__codelineno-56-5" name="__codelineno-56-5" href="#__codelineno-56-5"></a>ctx<span class="w"> </span>loop<span class="w"> </span>--tool<span class="w"> </span>aider<span class="w"> </span>--prompt<span class="w"> </span>TASKS.md
+</span><span id="__span-56-6"><a id="__codelineno-56-6" name="__codelineno-56-6" href="#__codelineno-56-6"></a>
+</span><span id="__span-56-7"><a id="__codelineno-56-7" name="__codelineno-56-7" href="#__codelineno-56-7"></a><span class="c1"># Limit to 10 iterations</span>
+</span><span id="__span-56-8"><a id="__codelineno-56-8" name="__codelineno-56-8" href="#__codelineno-56-8"></a>ctx<span class="w"> </span>loop<span class="w"> </span>--max-iterations<span class="w"> </span><span class="m">10</span>
+</span><span id="__span-56-9"><a id="__codelineno-56-9" name="__codelineno-56-9" href="#__codelineno-56-9"></a>
+</span><span id="__span-56-10"><a id="__codelineno-56-10" name="__codelineno-56-10" href="#__codelineno-56-10"></a><span class="c1"># Output to custom file</span>
+</span><span id="__span-56-11"><a id="__codelineno-56-11" name="__codelineno-56-11" href="#__codelineno-56-11"></a>ctx<span class="w"> </span>loop<span class="w"> </span>-o<span class="w"> </span>my-loop.sh
 </span></code></pre></div>
 <p><strong>Usage</strong>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-48-1"><a id="__codelineno-48-1" name="__codelineno-48-1" href="#__codelineno-48-1"></a><span class="c1"># Generate and run the loop</span>
-</span><span id="__span-48-2"><a id="__codelineno-48-2" name="__codelineno-48-2" href="#__codelineno-48-2"></a>ctx<span class="w"> </span>loop
-</span><span id="__span-48-3"><a id="__codelineno-48-3" name="__codelineno-48-3" href="#__codelineno-48-3"></a>chmod<span class="w"> </span>+x<span class="w"> </span>loop.sh
-</span><span id="__span-48-4"><a id="__codelineno-48-4" name="__codelineno-48-4" href="#__codelineno-48-4"></a>./loop.sh
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-57-1"><a id="__codelineno-57-1" name="__codelineno-57-1" href="#__codelineno-57-1"></a><span class="c1"># Generate and run the loop</span>
+</span><span id="__span-57-2"><a id="__codelineno-57-2" name="__codelineno-57-2" href="#__codelineno-57-2"></a>ctx<span class="w"> </span>loop
+</span><span id="__span-57-3"><a id="__codelineno-57-3" name="__codelineno-57-3" href="#__codelineno-57-3"></a>chmod<span class="w"> </span>+x<span class="w"> </span>loop.sh
+</span><span id="__span-57-4"><a id="__codelineno-57-4" name="__codelineno-57-4" href="#__codelineno-57-4"></a>./loop.sh
 </span></code></pre></div>
-<p>See <a href="../ralph-loop/">Ralph Loop Integration</a> for detailed workflow documentation.</p>
+<p>See <a href="../autonomous-loop/">Autonomous Loops</a> for detailed workflow documentation.</p>
 <hr />
 <h2 id="exit-codes">Exit Codes<a class="headerlink" href="#exit-codes" title="Permanent link">&para;</a></h2>
 <table>
@@ -2405,15 +2594,15 @@ <h2 id="environment-variables">Environment Variables<a class="headerlink" href="
 </table>
 <h2 id="configuration-file">Configuration File<a class="headerlink" href="#configuration-file" title="Permanent link">&para;</a></h2>
 <p>Optional <code>.contextrc</code> (YAML format) at project root:</p>
-<div class="language-yaml highlight"><pre><span></span><code><span id="__span-49-1"><a id="__codelineno-49-1" name="__codelineno-49-1" href="#__codelineno-49-1"></a><span class="c1"># .contextrc</span>
-</span><span id="__span-49-2"><a id="__codelineno-49-2" name="__codelineno-49-2" href="#__codelineno-49-2"></a><span class="nt">context_dir</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context</span><span class="w"> </span><span class="c1"># Context directory name</span>
-</span><span id="__span-49-3"><a id="__codelineno-49-3" name="__codelineno-49-3" href="#__codelineno-49-3"></a><span class="nt">token_budget</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8000</span><span class="w">    </span><span class="c1"># Default token budget</span>
-</span><span id="__span-49-4"><a id="__codelineno-49-4" name="__codelineno-49-4" href="#__codelineno-49-4"></a><span class="nt">priority_order</span><span class="p">:</span><span class="w">       </span><span class="c1"># File loading priority</span>
-</span><span id="__span-49-5"><a id="__codelineno-49-5" name="__codelineno-49-5" href="#__codelineno-49-5"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">TASKS.md</span>
-</span><span id="__span-49-6"><a id="__codelineno-49-6" name="__codelineno-49-6" href="#__codelineno-49-6"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">DECISIONS.md</span>
-</span><span id="__span-49-7"><a id="__codelineno-49-7" name="__codelineno-49-7" href="#__codelineno-49-7"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CONVENTIONS.md</span>
-</span><span id="__span-49-8"><a id="__codelineno-49-8" name="__codelineno-49-8" href="#__codelineno-49-8"></a><span class="nt">auto_archive</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">    </span><span class="c1"># Auto-archive old items</span>
-</span><span id="__span-49-9"><a id="__codelineno-49-9" name="__codelineno-49-9" href="#__codelineno-49-9"></a><span class="nt">archive_after_days</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7</span><span class="w"> </span><span class="c1"># Days before archiving</span>
+<div class="language-yaml highlight"><pre><span></span><code><span id="__span-58-1"><a id="__codelineno-58-1" name="__codelineno-58-1" href="#__codelineno-58-1"></a><span class="c1"># .contextrc</span>
+</span><span id="__span-58-2"><a id="__codelineno-58-2" name="__codelineno-58-2" href="#__codelineno-58-2"></a><span class="nt">context_dir</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context</span><span class="w"> </span><span class="c1"># Context directory name</span>
+</span><span id="__span-58-3"><a id="__codelineno-58-3" name="__codelineno-58-3" href="#__codelineno-58-3"></a><span class="nt">token_budget</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8000</span><span class="w">    </span><span class="c1"># Default token budget</span>
+</span><span id="__span-58-4"><a id="__codelineno-58-4" name="__codelineno-58-4" href="#__codelineno-58-4"></a><span class="nt">priority_order</span><span class="p">:</span><span class="w">       </span><span class="c1"># File loading priority</span>
+</span><span id="__span-58-5"><a id="__codelineno-58-5" name="__codelineno-58-5" href="#__codelineno-58-5"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">TASKS.md</span>
+</span><span id="__span-58-6"><a id="__codelineno-58-6" name="__codelineno-58-6" href="#__codelineno-58-6"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">DECISIONS.md</span>
+</span><span id="__span-58-7"><a id="__codelineno-58-7" name="__codelineno-58-7" href="#__codelineno-58-7"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CONVENTIONS.md</span>
+</span><span id="__span-58-8"><a id="__codelineno-58-8" name="__codelineno-58-8" href="#__codelineno-58-8"></a><span class="nt">auto_archive</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">    </span><span class="c1"># Auto-archive old items</span>
+</span><span id="__span-58-9"><a id="__codelineno-58-9" name="__codelineno-58-9" href="#__codelineno-58-9"></a><span class="nt">archive_after_days</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7</span><span class="w"> </span><span class="c1"># Days before archiving</span>
 </span></code></pre></div>
 <p><strong>Priority order:</strong> CLI flags &gt; Environment variables &gt; <code>.contextrc</code> &gt; Defaults</p>
 <p>All settings are optional. Missing values use defaults.</p>
diff --git a/site/comparison/index.html b/site/comparison/index.html
index 546ca94ac..d8f04440a 100644
--- a/site/comparison/index.html
+++ b/site/comparison/index.html
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -539,7 +539,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -548,7 +548,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -1084,10 +1084,9 @@ <h2 id="agent-frameworks">Agent Frameworks<a class="headerlink" href="#agent-fra
 <li>repeat mistakes</li>
 <li>lose architectural intent</li>
 </ul>
-<p>This is why <code>ctx</code> pairs well with loop-based workflows such as the
-<a href="https://ghuntley.com/ralph/">Ralph Wiggum technique</a>:</p>
+<p>This is why <code>ctx</code> pairs well with <a href="../autonomous-loop/">autonomous loop workflows</a>:</p>
 <ul>
-<li><code>ralph</code> provides iteration</li>
+<li>The loop provides iteration</li>
 <li><code>ctx</code> provides continuity</li>
 </ul>
 <p>Together, loops become cumulative instead of forgetful.</p>
diff --git a/site/context-files/index.html b/site/context-files/index.html
index 80267c542..524b0240e 100644
--- a/site/context-files/index.html
+++ b/site/context-files/index.html
@@ -18,14 +18,14 @@
         <link rel="prev" href="../cli-reference/">
       
       
-        <link rel="next" href="../ralph-loop/">
+        <link rel="next" href="../autonomous-loop/">
       
       
         
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -857,7 +857,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -866,7 +866,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -2161,13 +2161,13 @@ <h2 id="token-efficiency">Token Efficiency<a class="headerlink" href="#token-eff
         
         
           
-          <a href="../ralph-loop/" class="md-footer__link md-footer__link--next" aria-label="Next: ralph + ctx">
+          <a href="../autonomous-loop/" class="md-footer__link md-footer__link--next" aria-label="Next: Autonomous Loops">
             <div class="md-footer__title">
               <span class="md-footer__direction">
                 Next
               </span>
               <div class="md-ellipsis">
-                ralph + ctx
+                Autonomous Loops
               </div>
             </div>
             <div class="md-footer__button md-icon">
diff --git a/site/index.html b/site/index.html
index e2499457f..d831583b5 100644
--- a/site/index.html
+++ b/site/index.html
@@ -23,7 +23,7 @@
       
       
       <link rel="icon" href="images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -665,7 +665,7 @@
   
   
     <li class="md-nav__item">
-      <a href="ralph-loop/" class="md-nav__link">
+      <a href="autonomous-loop/" class="md-nav__link">
         
   
   
@@ -674,7 +674,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -1337,7 +1337,7 @@ <h2 id="next-steps">Next Steps<a class="headerlink" href="#next-steps" title="Pe
 <li><a href="prompting-guide/">Prompting Guide</a> — Effective prompts for AI sessions</li>
 <li><a href="cli-reference/">CLI Reference</a> — All commands and options</li>
 <li><a href="context-files/">Context Files</a> — File formats and structure</li>
-<li><a href="ralph-loop/"><code>ralph</code> and <code>ctx</code></a> — Autonomous AI development workflows</li>
+<li><a href="autonomous-loop/">Autonomous Loops</a> — Iterative AI development workflows</li>
 <li><a href="integrations/">Integrations</a> — Setup for Claude Code, Cursor, Aider</li>
 </ul>
 
diff --git a/site/integrations/index.html b/site/integrations/index.html
index 646ec0612..eef63b151 100644
--- a/site/integrations/index.html
+++ b/site/integrations/index.html
@@ -15,7 +15,7 @@
         <link rel="canonical" href="https://ctx.ist/integrations/">
       
       
-        <link rel="prev" href="../ralph-loop/">
+        <link rel="prev" href="../autonomous-loop/">
       
       
         <link rel="next" href="../versions/">
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -383,7 +383,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -392,7 +392,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -570,6 +570,89 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#slash-commands" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Slash Commands
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Slash Commands">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#context-commands" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Context Commands
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#adding-context" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Adding Context
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#session-history" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Session History
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#blogging" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Blogging
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#development" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Development
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#usage-examples" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Usage Examples
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
         
       </ul>
@@ -1205,6 +1288,89 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#slash-commands" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Slash Commands
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Slash Commands">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#context-commands" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Context Commands
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#adding-context" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Adding Context
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#session-history" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Session History
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#blogging" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Blogging
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#development" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Development
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#usage-examples" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Usage Examples
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
         
       </ul>
@@ -1702,25 +1868,150 @@ <h3 id="manual-context-load">Manual Context Load<a class="headerlink" href="#man
 </span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="c1"># Or paste into conversation</span>
 </span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>cat<span class="w"> </span>.context/TASKS.md
 </span></code></pre></div>
+<h3 id="slash-commands">Slash Commands<a class="headerlink" href="#slash-commands" title="Permanent link">&para;</a></h3>
+<p><code>ctx init</code> installs slash commands to <code>.claude/commands/</code>. These are shortcuts
+you can invoke in Claude Code with <code>/command-name</code>.</p>
+<h4 id="context-commands">Context Commands<a class="headerlink" href="#context-commands" title="Permanent link">&para;</a></h4>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/ctx-status</code></td>
+<td>Show context summary (tasks, decisions, learnings)</td>
+</tr>
+<tr>
+<td><code>/ctx-agent</code></td>
+<td>Get AI-optimized context packet</td>
+</tr>
+<tr>
+<td><code>/ctx-save</code></td>
+<td>Save current session to <code>.context/sessions/</code></td>
+</tr>
+<tr>
+<td><code>/ctx-reflect</code></td>
+<td>Review session and suggest what to persist</td>
+</tr>
+</tbody>
+</table>
+<h4 id="adding-context">Adding Context<a class="headerlink" href="#adding-context" title="Permanent link">&para;</a></h4>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/ctx-add-task</code></td>
+<td>Add a task to TASKS.md</td>
+</tr>
+<tr>
+<td><code>/ctx-add-learning</code></td>
+<td>Add a learning to LEARNINGS.md</td>
+</tr>
+<tr>
+<td><code>/ctx-add-decision</code></td>
+<td>Add a decision with context/rationale/consequences</td>
+</tr>
+<tr>
+<td><code>/ctx-archive</code></td>
+<td>Archive completed tasks</td>
+</tr>
+</tbody>
+</table>
+<h4 id="session-history">Session History<a class="headerlink" href="#session-history" title="Permanent link">&para;</a></h4>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/ctx-recall</code></td>
+<td>Browse AI session history</td>
+</tr>
+<tr>
+<td><code>/ctx-journal-enrich</code></td>
+<td>Enrich a journal entry with frontmatter/tags</td>
+</tr>
+<tr>
+<td><code>/ctx-journal-summarize</code></td>
+<td>Generate summary of sessions over a time period</td>
+</tr>
+</tbody>
+</table>
+<h4 id="blogging">Blogging<a class="headerlink" href="#blogging" title="Permanent link">&para;</a></h4>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/ctx-blog</code></td>
+<td>Generate blog post from recent activity</td>
+</tr>
+<tr>
+<td><code>/ctx-blog-changelog</code></td>
+<td>Generate blog post from commit range with theme</td>
+</tr>
+</tbody>
+</table>
+<h4 id="development">Development<a class="headerlink" href="#development" title="Permanent link">&para;</a></h4>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/ctx-loop</code></td>
+<td>Generate a Ralph Loop iteration script</td>
+</tr>
+<tr>
+<td><code>/ctx-prompt-audit</code></td>
+<td>Analyze session logs for vague prompts</td>
+</tr>
+</tbody>
+</table>
+<h4 id="usage-examples">Usage Examples<a class="headerlink" href="#usage-examples" title="Permanent link">&para;</a></h4>
+<div class="language-text highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>/ctx-status
+</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>/ctx-add-learning &quot;Token refresh requires explicit cache invalidation&quot;
+</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>/ctx-journal-enrich twinkly-stirring-kettle
+</span><span id="__span-4-4"><a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>/ctx-journal-summarize last week
+</span></code></pre></div>
+<p>Slash commands support partial matching where applicable (e.g., session slugs).</p>
 <hr />
 <h2 id="cursor-ide">Cursor IDE<a class="headerlink" href="#cursor-ide" title="Permanent link">&para;</a></h2>
 <p>Cursor can use context files through its system prompt or by reading 
 files directly.</p>
 <h3 id="setup">Setup<a class="headerlink" href="#setup" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="c1"># Generate Cursor configuration</span>
-</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>cursor
-</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>
-</span><span id="__span-4-4"><a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="c1"># Initialize context</span>
-</span><span id="__span-4-5"><a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>ctx<span class="w"> </span>init<span class="w"> </span>--minimal
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="c1"># Generate Cursor configuration</span>
+</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>cursor
+</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>
+</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="c1"># Initialize context</span>
+</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a>ctx<span class="w"> </span>init<span class="w"> </span>--minimal
 </span></code></pre></div>
 <h3 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">&para;</a></h3>
 <p>Add to Cursor settings (<code>.cursor/settings.json</code>):</p>
-<div class="language-text highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>// split to multiple lines for readability
-</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>{
-</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>  &quot;ai.systemPrompt&quot;: &quot;Read .context/TASKS.md and 
-</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a>  .context/CONVENTIONS.md before responding. 
-</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a>  Follow rules in .context/CONSTITUTION.md.&quot;,
-</span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>}
+<div class="language-text highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>// split to multiple lines for readability
+</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>{
+</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>  &quot;ai.systemPrompt&quot;: &quot;Read .context/TASKS.md and 
+</span><span id="__span-6-4"><a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>  .context/CONVENTIONS.md before responding. 
+</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>  Follow rules in .context/CONSTITUTION.md.&quot;,
+</span><span id="__span-6-6"><a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a>}
 </span></code></pre></div>
 <h3 id="usage">Usage<a class="headerlink" href="#usage" title="Permanent link">&para;</a></h3>
 <ol>
@@ -1731,88 +2022,88 @@ <h3 id="usage">Usage<a class="headerlink" href="#usage" title="Permanent link">&
 </ol>
 <h3 id="manual-context-injection">Manual Context Injection<a class="headerlink" href="#manual-context-injection" title="Permanent link">&para;</a></h3>
 <p>For more control, paste context directly:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="c1"># Get AI-ready packet</span>
-</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">4000</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>pbcopy<span class="w">  </span><span class="c1"># macOS</span>
-</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">4000</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>xclip<span class="w">  </span><span class="c1"># Linux</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="c1"># Get AI-ready packet</span>
+</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">4000</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>pbcopy<span class="w">  </span><span class="c1"># macOS</span>
+</span><span id="__span-7-3"><a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">4000</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>xclip<span class="w">  </span><span class="c1"># Linux</span>
 </span></code></pre></div>
 <p>Paste into Cursor's chat.</p>
 <hr />
 <h2 id="aider">Aider<a class="headerlink" href="#aider" title="Permanent link">&para;</a></h2>
 <p>Aider works well with context files through its <code>--read</code> flag.</p>
 <h3 id="setup_1">Setup<a class="headerlink" href="#setup_1" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="c1"># Generate Aider configuration</span>
-</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>aider
-</span><span id="__span-7-3"><a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>
-</span><span id="__span-7-4"><a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="c1"># Initialize context</span>
-</span><span id="__span-7-5"><a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a>ctx<span class="w"> </span>init
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="c1"># Generate Aider configuration</span>
+</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>aider
+</span><span id="__span-8-3"><a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a>
+</span><span id="__span-8-4"><a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="c1"># Initialize context</span>
+</span><span id="__span-8-5"><a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a>ctx<span class="w"> </span>init
 </span></code></pre></div>
 <h3 id="configuration_1">Configuration<a class="headerlink" href="#configuration_1" title="Permanent link">&para;</a></h3>
 <p>Create <code>.aider.conf.yml</code>:</p>
-<div class="language-yaml highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="nt">read</span><span class="p">:</span>
-</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/CONSTITUTION.md</span>
-</span><span id="__span-8-3"><a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/TASKS.md</span>
-</span><span id="__span-8-4"><a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/CONVENTIONS.md</span>
-</span><span id="__span-8-5"><a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/DECISIONS.md</span>
+<div class="language-yaml highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="nt">read</span><span class="p">:</span>
+</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/CONSTITUTION.md</span>
+</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/TASKS.md</span>
+</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/CONVENTIONS.md</span>
+</span><span id="__span-9-5"><a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.context/DECISIONS.md</span>
 </span></code></pre></div>
 <h3 id="usage_1">Usage<a class="headerlink" href="#usage_1" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="c1"># Start Aider (reads context files automatically)</span>
-</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>aider
-</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a>
-</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="c1"># Or specify files explicitly</span>
-</span><span id="__span-9-5"><a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a>aider<span class="w"> </span>--read<span class="w"> </span>.context/TASKS.md<span class="w"> </span>--read<span class="w"> </span>.context/CONVENTIONS.md
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="c1"># Start Aider (reads context files automatically)</span>
+</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a>aider
+</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a>
+</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="c1"># Or specify files explicitly</span>
+</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a>aider<span class="w"> </span>--read<span class="w"> </span>.context/TASKS.md<span class="w"> </span>--read<span class="w"> </span>.context/CONVENTIONS.md
 </span></code></pre></div>
 <h3 id="with-watch-mode">With Watch Mode<a class="headerlink" href="#with-watch-mode" title="Permanent link">&para;</a></h3>
 <p>Run <code>ctx watch</code> alongside Aider to capture context updates:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="c1"># Terminal 1: Run Aider</span>
-</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a>aider<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>tee<span class="w"> </span>/tmp/aider.log
-</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a>
-</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="c1"># Terminal 2: Watch for context updates</span>
-</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/aider.log
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="c1"># Terminal 1: Run Aider</span>
+</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a>aider<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>tee<span class="w"> </span>/tmp/aider.log
+</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a>
+</span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="c1"># Terminal 2: Watch for context updates</span>
+</span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/aider.log
 </span></code></pre></div>
 <hr />
 <h2 id="github-copilot">GitHub Copilot<a class="headerlink" href="#github-copilot" title="Permanent link">&para;</a></h2>
 <p>Copilot reads open files for context. Keep context files open or reference 
 them in comments.</p>
 <h3 id="setup_2">Setup<a class="headerlink" href="#setup_2" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="c1"># Generate Copilot tips</span>
-</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>copilot
-</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a>
-</span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="c1"># Initialize context</span>
-</span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a>ctx<span class="w"> </span>init<span class="w"> </span>--minimal
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="c1"># Generate Copilot tips</span>
+</span><span id="__span-12-2"><a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>copilot
+</span><span id="__span-12-3"><a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a>
+</span><span id="__span-12-4"><a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a><span class="c1"># Initialize context</span>
+</span><span id="__span-12-5"><a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a>ctx<span class="w"> </span>init<span class="w"> </span>--minimal
 </span></code></pre></div>
 <h3 id="usage-patterns">Usage Patterns<a class="headerlink" href="#usage-patterns" title="Permanent link">&para;</a></h3>
 <p><strong>Pattern 1: Keep context files open</strong></p>
 <p>Open <code>.context/CONVENTIONS.md</code> in a split pane. Copilot will reference it.</p>
 <p><strong>Pattern 2: Reference in comments</strong></p>
-<div class="language-typescript highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="c1">// See .context/CONVENTIONS.md for naming patterns</span>
-</span><span id="__span-12-2"><a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="c1">// Following decision in .context/DECISIONS.md: Use PostgreSQL</span>
-</span><span id="__span-12-3"><a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a>
-</span><span id="__span-12-4"><a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a><span class="kd">function</span><span class="w"> </span><span class="nx">getUserById</span><span class="p">(</span><span class="nx">id</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
-</span><span id="__span-12-5"><a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a><span class="w">  </span><span class="c1">// Copilot now has context</span>
-</span><span id="__span-12-6"><a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a><span class="p">}</span>
+<div class="language-typescript highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="c1">// See .context/CONVENTIONS.md for naming patterns</span>
+</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="c1">// Following decision in .context/DECISIONS.md: Use PostgreSQL</span>
+</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a>
+</span><span id="__span-13-4"><a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a><span class="kd">function</span><span class="w"> </span><span class="nx">getUserById</span><span class="p">(</span><span class="nx">id</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
+</span><span id="__span-13-5"><a id="__codelineno-13-5" name="__codelineno-13-5" href="#__codelineno-13-5"></a><span class="w">  </span><span class="c1">// Copilot now has context</span>
+</span><span id="__span-13-6"><a id="__codelineno-13-6" name="__codelineno-13-6" href="#__codelineno-13-6"></a><span class="p">}</span>
 </span></code></pre></div>
 <p><strong>Pattern 3: Paste context into Copilot Chat</strong></p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">2000</span>
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">2000</span>
 </span></code></pre></div>
 <p>Paste output into Copilot Chat for context-aware responses.</p>
 <hr />
 <h2 id="windsurf-ide">Windsurf IDE<a class="headerlink" href="#windsurf-ide" title="Permanent link">&para;</a></h2>
 <p>Windsurf supports custom instructions and file-based context.</p>
 <h3 id="setup_3">Setup<a class="headerlink" href="#setup_3" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="c1"># Generate Windsurf configuration</span>
-</span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>windsurf
-</span><span id="__span-14-3"><a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a>
-</span><span id="__span-14-4"><a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a><span class="c1"># Initialize context</span>
-</span><span id="__span-14-5"><a id="__codelineno-14-5" name="__codelineno-14-5" href="#__codelineno-14-5"></a>ctx<span class="w"> </span>init
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="c1"># Generate Windsurf configuration</span>
+</span><span id="__span-15-2"><a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a>ctx<span class="w"> </span>hook<span class="w"> </span>windsurf
+</span><span id="__span-15-3"><a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a>
+</span><span id="__span-15-4"><a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a><span class="c1"># Initialize context</span>
+</span><span id="__span-15-5"><a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a>ctx<span class="w"> </span>init
 </span></code></pre></div>
 <h3 id="configuration_2">Configuration<a class="headerlink" href="#configuration_2" title="Permanent link">&para;</a></h3>
 <p>Add to Windsurf settings:</p>
-<div class="language-text highlight"><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>// Split to multiple lines for readability
-</span><span id="__span-15-2"><a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a>{
-</span><span id="__span-15-3"><a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a>  &quot;ai.customInstructions&quot;: &quot;Always read .context/CONSTITUTION.md first. 
-</span><span id="__span-15-4"><a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a>  Check .context/TASKS.md for current work. 
-</span><span id="__span-15-5"><a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a>  Follow patterns in .context/CONVENTIONS.md.&quot;
-</span><span id="__span-15-6"><a id="__codelineno-15-6" name="__codelineno-15-6" href="#__codelineno-15-6"></a>}
+<div class="language-text highlight"><pre><span></span><code><span id="__span-16-1"><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>// Split to multiple lines for readability
+</span><span id="__span-16-2"><a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a>{
+</span><span id="__span-16-3"><a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a>  &quot;ai.customInstructions&quot;: &quot;Always read .context/CONSTITUTION.md first. 
+</span><span id="__span-16-4"><a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-4"></a>  Check .context/TASKS.md for current work. 
+</span><span id="__span-16-5"><a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a>  Follow patterns in .context/CONVENTIONS.md.&quot;
+</span><span id="__span-16-6"><a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a>}
 </span></code></pre></div>
 <h3 id="usage_2">Usage<a class="headerlink" href="#usage_2" title="Permanent link">&para;</a></h3>
 <p>Context files appear in the file tree. Reference them when chatting:</p>
@@ -1824,41 +2115,41 @@ <h3 id="usage_2">Usage<a class="headerlink" href="#usage_2" title="Permanent lin
 <h2 id="generic-integration">Generic Integration<a class="headerlink" href="#generic-integration" title="Permanent link">&para;</a></h2>
 <p>For any AI tool that can read files, use these patterns:</p>
 <h3 id="manual-context-loading">Manual Context Loading<a class="headerlink" href="#manual-context-loading" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-16-1"><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="c1"># Get full context</span>
-</span><span id="__span-16-2"><a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a>ctx<span class="w"> </span>load
-</span><span id="__span-16-3"><a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a>
-</span><span id="__span-16-4"><a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-4"></a><span class="c1"># Get AI-optimized packet</span>
-</span><span id="__span-16-5"><a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">8000</span>
-</span><span id="__span-16-6"><a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a>
-</span><span id="__span-16-7"><a id="__codelineno-16-7" name="__codelineno-16-7" href="#__codelineno-16-7"></a><span class="c1"># Get specific file</span>
-</span><span id="__span-16-8"><a id="__codelineno-16-8" name="__codelineno-16-8" href="#__codelineno-16-8"></a>cat<span class="w"> </span>.context/TASKS.md
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-17-1"><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="c1"># Get full context</span>
+</span><span id="__span-17-2"><a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a>ctx<span class="w"> </span>load
+</span><span id="__span-17-3"><a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-3"></a>
+</span><span id="__span-17-4"><a id="__codelineno-17-4" name="__codelineno-17-4" href="#__codelineno-17-4"></a><span class="c1"># Get AI-optimized packet</span>
+</span><span id="__span-17-5"><a id="__codelineno-17-5" name="__codelineno-17-5" href="#__codelineno-17-5"></a>ctx<span class="w"> </span>agent<span class="w"> </span>--budget<span class="w"> </span><span class="m">8000</span>
+</span><span id="__span-17-6"><a id="__codelineno-17-6" name="__codelineno-17-6" href="#__codelineno-17-6"></a>
+</span><span id="__span-17-7"><a id="__codelineno-17-7" name="__codelineno-17-7" href="#__codelineno-17-7"></a><span class="c1"># Get specific file</span>
+</span><span id="__span-17-8"><a id="__codelineno-17-8" name="__codelineno-17-8" href="#__codelineno-17-8"></a>cat<span class="w"> </span>.context/TASKS.md
 </span></code></pre></div>
 <h3 id="system-prompt-template">System Prompt Template<a class="headerlink" href="#system-prompt-template" title="Permanent link">&para;</a></h3>
-<div class="language-text highlight"><pre><span></span><code><span id="__span-17-1"><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>You are working on a project with persistent context in .context/
-</span><span id="__span-17-2"><a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a>
-</span><span id="__span-17-3"><a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-3"></a>Before responding:
-</span><span id="__span-17-4"><a id="__codelineno-17-4" name="__codelineno-17-4" href="#__codelineno-17-4"></a>1. Read .context/CONSTITUTION.md - NEVER violate these rules
-</span><span id="__span-17-5"><a id="__codelineno-17-5" name="__codelineno-17-5" href="#__codelineno-17-5"></a>2. Check .context/TASKS.md for current work
-</span><span id="__span-17-6"><a id="__codelineno-17-6" name="__codelineno-17-6" href="#__codelineno-17-6"></a>3. Follow .context/CONVENTIONS.md patterns
-</span><span id="__span-17-7"><a id="__codelineno-17-7" name="__codelineno-17-7" href="#__codelineno-17-7"></a>4. Reference .context/DECISIONS.md for architectural choices
-</span><span id="__span-17-8"><a id="__codelineno-17-8" name="__codelineno-17-8" href="#__codelineno-17-8"></a>
-</span><span id="__span-17-9"><a id="__codelineno-17-9" name="__codelineno-17-9" href="#__codelineno-17-9"></a>When you learn something new, note it for .context/LEARNINGS.md
-</span><span id="__span-17-10"><a id="__codelineno-17-10" name="__codelineno-17-10" href="#__codelineno-17-10"></a>When you make a decision, document it for .context/DECISIONS.md
+<div class="language-text highlight"><pre><span></span><code><span id="__span-18-1"><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a>You are working on a project with persistent context in .context/
+</span><span id="__span-18-2"><a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a>
+</span><span id="__span-18-3"><a id="__codelineno-18-3" name="__codelineno-18-3" href="#__codelineno-18-3"></a>Before responding:
+</span><span id="__span-18-4"><a id="__codelineno-18-4" name="__codelineno-18-4" href="#__codelineno-18-4"></a>1. Read .context/CONSTITUTION.md - NEVER violate these rules
+</span><span id="__span-18-5"><a id="__codelineno-18-5" name="__codelineno-18-5" href="#__codelineno-18-5"></a>2. Check .context/TASKS.md for current work
+</span><span id="__span-18-6"><a id="__codelineno-18-6" name="__codelineno-18-6" href="#__codelineno-18-6"></a>3. Follow .context/CONVENTIONS.md patterns
+</span><span id="__span-18-7"><a id="__codelineno-18-7" name="__codelineno-18-7" href="#__codelineno-18-7"></a>4. Reference .context/DECISIONS.md for architectural choices
+</span><span id="__span-18-8"><a id="__codelineno-18-8" name="__codelineno-18-8" href="#__codelineno-18-8"></a>
+</span><span id="__span-18-9"><a id="__codelineno-18-9" name="__codelineno-18-9" href="#__codelineno-18-9"></a>When you learn something new, note it for .context/LEARNINGS.md
+</span><span id="__span-18-10"><a id="__codelineno-18-10" name="__codelineno-18-10" href="#__codelineno-18-10"></a>When you make a decision, document it for .context/DECISIONS.md
 </span></code></pre></div>
 <h3 id="automated-updates">Automated Updates<a class="headerlink" href="#automated-updates" title="Permanent link">&para;</a></h3>
 <p>If your AI tool outputs to a log, use <code>ctx watch</code>:</p>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-18-1"><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="c1"># Watch log file for context-update commands</span>
-</span><span id="__span-18-2"><a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a>your-ai-tool<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>tee<span class="w"> </span>/tmp/ai.log<span class="w"> </span><span class="p">&amp;</span>
-</span><span id="__span-18-3"><a id="__codelineno-18-3" name="__codelineno-18-3" href="#__codelineno-18-3"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/ai.log
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-19-1"><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a><span class="c1"># Watch log file for context-update commands</span>
+</span><span id="__span-19-2"><a id="__codelineno-19-2" name="__codelineno-19-2" href="#__codelineno-19-2"></a>your-ai-tool<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>tee<span class="w"> </span>/tmp/ai.log<span class="w"> </span><span class="p">&amp;</span>
+</span><span id="__span-19-3"><a id="__codelineno-19-3" name="__codelineno-19-3" href="#__codelineno-19-3"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/ai.log
 </span></code></pre></div>
 <p>The AI can emit updates like:</p>
-<div class="language-xml highlight"><pre><span></span><code><span id="__span-19-1"><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;learning&quot;</span><span class="nt">&gt;</span>Important<span class="w"> </span>thing<span class="w"> </span>learned<span class="w"> </span>today<span class="nt">&lt;/context-update&gt;</span>
-</span><span id="__span-19-2"><a id="__codelineno-19-2" name="__codelineno-19-2" href="#__codelineno-19-2"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;complete&quot;</span><span class="nt">&gt;</span>implement<span class="w"> </span>caching<span class="nt">&lt;/context-update&gt;</span>
+<div class="language-xml highlight"><pre><span></span><code><span id="__span-20-1"><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;learning&quot;</span><span class="nt">&gt;</span>Important<span class="w"> </span>thing<span class="w"> </span>learned<span class="w"> </span>today<span class="nt">&lt;/context-update&gt;</span>
+</span><span id="__span-20-2"><a id="__codelineno-20-2" name="__codelineno-20-2" href="#__codelineno-20-2"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;complete&quot;</span><span class="nt">&gt;</span>implement<span class="w"> </span>caching<span class="nt">&lt;/context-update&gt;</span>
 </span></code></pre></div>
 <hr />
 <h2 id="context-update-commands">Context Update Commands<a class="headerlink" href="#context-update-commands" title="Permanent link">&para;</a></h2>
 <p>The <code>ctx watch</code> command parses update commands from AI output. Use this format:</p>
-<div class="language-xml highlight"><pre><span></span><code><span id="__span-20-1"><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;TYPE&quot;</span><span class="w"> </span><span class="err">[attributes]</span><span class="nt">&gt;</span>Content<span class="nt">&lt;/context-update&gt;</span>
+<div class="language-xml highlight"><pre><span></span><code><span id="__span-21-1"><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;TYPE&quot;</span><span class="w"> </span><span class="err">[attributes]</span><span class="nt">&gt;</span>Content<span class="nt">&lt;/context-update&gt;</span>
 </span></code></pre></div>
 <h3 id="supported-types">Supported Types<a class="headerlink" href="#supported-types" title="Permanent link">&para;</a></h3>
 <table>
@@ -1898,41 +2189,41 @@ <h3 id="supported-types">Supported Types<a class="headerlink" href="#supported-t
 </tbody>
 </table>
 <h3 id="simple-format-tasks-conventions-complete">Simple Format (tasks, conventions, complete)<a class="headerlink" href="#simple-format-tasks-conventions-complete" title="Permanent link">&para;</a></h3>
-<div class="language-xml highlight"><pre><span></span><code><span id="__span-21-1"><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;task&quot;</span><span class="nt">&gt;</span>Implement<span class="w"> </span>rate<span class="w"> </span>limiting<span class="nt">&lt;/context-update&gt;</span>
-</span><span id="__span-21-2"><a id="__codelineno-21-2" name="__codelineno-21-2" href="#__codelineno-21-2"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;convention&quot;</span><span class="nt">&gt;</span>Use<span class="w"> </span>kebab-case<span class="w"> </span>for<span class="w"> </span>files<span class="nt">&lt;/context-update&gt;</span>
-</span><span id="__span-21-3"><a id="__codelineno-21-3" name="__codelineno-21-3" href="#__codelineno-21-3"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;complete&quot;</span><span class="nt">&gt;</span>rate<span class="w"> </span>limiting<span class="nt">&lt;/context-update&gt;</span>
+<div class="language-xml highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;task&quot;</span><span class="nt">&gt;</span>Implement<span class="w"> </span>rate<span class="w"> </span>limiting<span class="nt">&lt;/context-update&gt;</span>
+</span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;convention&quot;</span><span class="nt">&gt;</span>Use<span class="w"> </span>kebab-case<span class="w"> </span>for<span class="w"> </span>files<span class="nt">&lt;/context-update&gt;</span>
+</span><span id="__span-22-3"><a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;complete&quot;</span><span class="nt">&gt;</span>rate<span class="w"> </span>limiting<span class="nt">&lt;/context-update&gt;</span>
 </span></code></pre></div>
 <h3 id="structured-format-learnings-decisions">Structured Format (learnings, decisions)<a class="headerlink" href="#structured-format-learnings-decisions" title="Permanent link">&para;</a></h3>
 <p>Learnings and decisions support structured attributes for better documentation:</p>
 <p><strong>Learning with full structure</strong>:</p>
-<div class="language-xml highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;learning&quot;</span>
-</span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w">  </span><span class="na">context=</span><span class="s">&quot;Debugging Claude Code hooks&quot;</span>
-</span><span id="__span-22-3"><a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a><span class="w">  </span><span class="na">lesson=</span><span class="s">&quot;Hooks receive JSON via stdin, not environment variables&quot;</span>
-</span><span id="__span-22-4"><a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a><span class="w">  </span><span class="na">application=</span><span class="s">&quot;Use jq to parse: COMMAND=$(echo $INPUT | jq -r .tool_input.command)&quot;</span>
-</span><span id="__span-22-5"><a id="__codelineno-22-5" name="__codelineno-22-5" href="#__codelineno-22-5"></a><span class="nt">&gt;</span>Hook<span class="w"> </span>Input<span class="w"> </span>Format<span class="nt">&lt;/context-update&gt;</span>
+<div class="language-xml highlight"><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;learning&quot;</span>
+</span><span id="__span-23-2"><a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a><span class="w">  </span><span class="na">context=</span><span class="s">&quot;Debugging Claude Code hooks&quot;</span>
+</span><span id="__span-23-3"><a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-3"></a><span class="w">  </span><span class="na">lesson=</span><span class="s">&quot;Hooks receive JSON via stdin, not environment variables&quot;</span>
+</span><span id="__span-23-4"><a id="__codelineno-23-4" name="__codelineno-23-4" href="#__codelineno-23-4"></a><span class="w">  </span><span class="na">application=</span><span class="s">&quot;Use jq to parse: COMMAND=$(echo $INPUT | jq -r .tool_input.command)&quot;</span>
+</span><span id="__span-23-5"><a id="__codelineno-23-5" name="__codelineno-23-5" href="#__codelineno-23-5"></a><span class="nt">&gt;</span>Hook<span class="w"> </span>Input<span class="w"> </span>Format<span class="nt">&lt;/context-update&gt;</span>
 </span></code></pre></div>
 <p><strong>Decision with full structure</strong>:</p>
-<div class="language-xml highlight"><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;decision&quot;</span>
-</span><span id="__span-23-2"><a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a><span class="w">  </span><span class="na">context=</span><span class="s">&quot;Need a caching layer for API responses&quot;</span>
-</span><span id="__span-23-3"><a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-3"></a><span class="w">  </span><span class="na">rationale=</span><span class="s">&quot;Redis is fast, well-supported, and team has experience&quot;</span>
-</span><span id="__span-23-4"><a id="__codelineno-23-4" name="__codelineno-23-4" href="#__codelineno-23-4"></a><span class="w">  </span><span class="na">consequences=</span><span class="s">&quot;Must provision Redis infrastructure; team training on Redis patterns&quot;</span>
-</span><span id="__span-23-5"><a id="__codelineno-23-5" name="__codelineno-23-5" href="#__codelineno-23-5"></a><span class="nt">&gt;</span>Use<span class="w"> </span>Redis<span class="w"> </span>for<span class="w"> </span>caching<span class="nt">&lt;/context-update&gt;</span>
+<div class="language-xml highlight"><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;decision&quot;</span>
+</span><span id="__span-24-2"><a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a><span class="w">  </span><span class="na">context=</span><span class="s">&quot;Need a caching layer for API responses&quot;</span>
+</span><span id="__span-24-3"><a id="__codelineno-24-3" name="__codelineno-24-3" href="#__codelineno-24-3"></a><span class="w">  </span><span class="na">rationale=</span><span class="s">&quot;Redis is fast, well-supported, and team has experience&quot;</span>
+</span><span id="__span-24-4"><a id="__codelineno-24-4" name="__codelineno-24-4" href="#__codelineno-24-4"></a><span class="w">  </span><span class="na">consequences=</span><span class="s">&quot;Must provision Redis infrastructure; team training on Redis patterns&quot;</span>
+</span><span id="__span-24-5"><a id="__codelineno-24-5" name="__codelineno-24-5" href="#__codelineno-24-5"></a><span class="nt">&gt;</span>Use<span class="w"> </span>Redis<span class="w"> </span>for<span class="w"> </span>caching<span class="nt">&lt;/context-update&gt;</span>
 </span></code></pre></div>
 <p>If attributes are omitted, placeholders are inserted that should be updated manually.</p>
 <h3 id="legacy-format-still-supported">Legacy Format (still supported)<a class="headerlink" href="#legacy-format-still-supported" title="Permanent link">&para;</a></h3>
 <p>Simple format without attributes still works but creates placeholder text:</p>
-<div class="language-xml highlight"><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;learning&quot;</span><span class="nt">&gt;</span>Mock<span class="w"> </span>functions<span class="w"> </span>must<span class="w"> </span>be<span class="w"> </span>hoisted<span class="nt">&lt;/context-update&gt;</span>
-</span><span id="__span-24-2"><a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;decision&quot;</span><span class="nt">&gt;</span>Use<span class="w"> </span>PostgreSQL<span class="w"> </span>for<span class="w"> </span>primary<span class="w"> </span>database<span class="nt">&lt;/context-update&gt;</span>
+<div class="language-xml highlight"><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;learning&quot;</span><span class="nt">&gt;</span>Mock<span class="w"> </span>functions<span class="w"> </span>must<span class="w"> </span>be<span class="w"> </span>hoisted<span class="nt">&lt;/context-update&gt;</span>
+</span><span id="__span-25-2"><a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a><span class="nt">&lt;context-update</span><span class="w"> </span><span class="na">type=</span><span class="s">&quot;decision&quot;</span><span class="nt">&gt;</span>Use<span class="w"> </span>PostgreSQL<span class="w"> </span>for<span class="w"> </span>primary<span class="w"> </span>database<span class="nt">&lt;/context-update&gt;</span>
 </span></code></pre></div>
 <h3 id="usage-with-ctx-watch">Usage with ctx watch<a class="headerlink" href="#usage-with-ctx-watch" title="Permanent link">&para;</a></h3>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a><span class="c1"># Pipe AI output through watch</span>
-</span><span id="__span-25-2"><a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a>your-ai-tool<span class="w"> </span><span class="p">|</span><span class="w"> </span>ctx<span class="w"> </span>watch
-</span><span id="__span-25-3"><a id="__codelineno-25-3" name="__codelineno-25-3" href="#__codelineno-25-3"></a>
-</span><span id="__span-25-4"><a id="__codelineno-25-4" name="__codelineno-25-4" href="#__codelineno-25-4"></a><span class="c1"># Or watch a log file</span>
-</span><span id="__span-25-5"><a id="__codelineno-25-5" name="__codelineno-25-5" href="#__codelineno-25-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/ai-output.log
-</span><span id="__span-25-6"><a id="__codelineno-25-6" name="__codelineno-25-6" href="#__codelineno-25-6"></a>
-</span><span id="__span-25-7"><a id="__codelineno-25-7" name="__codelineno-25-7" href="#__codelineno-25-7"></a><span class="c1"># Preview without applying</span>
-</span><span id="__span-25-8"><a id="__codelineno-25-8" name="__codelineno-25-8" href="#__codelineno-25-8"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--dry-run
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-26-1"><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a><span class="c1"># Pipe AI output through watch</span>
+</span><span id="__span-26-2"><a id="__codelineno-26-2" name="__codelineno-26-2" href="#__codelineno-26-2"></a>your-ai-tool<span class="w"> </span><span class="p">|</span><span class="w"> </span>ctx<span class="w"> </span>watch
+</span><span id="__span-26-3"><a id="__codelineno-26-3" name="__codelineno-26-3" href="#__codelineno-26-3"></a>
+</span><span id="__span-26-4"><a id="__codelineno-26-4" name="__codelineno-26-4" href="#__codelineno-26-4"></a><span class="c1"># Or watch a log file</span>
+</span><span id="__span-26-5"><a id="__codelineno-26-5" name="__codelineno-26-5" href="#__codelineno-26-5"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--log<span class="w"> </span>/tmp/ai-output.log
+</span><span id="__span-26-6"><a id="__codelineno-26-6" name="__codelineno-26-6" href="#__codelineno-26-6"></a>
+</span><span id="__span-26-7"><a id="__codelineno-26-7" name="__codelineno-26-7" href="#__codelineno-26-7"></a><span class="c1"># Preview without applying</span>
+</span><span id="__span-26-8"><a id="__codelineno-26-8" name="__codelineno-26-8" href="#__codelineno-26-8"></a>ctx<span class="w"> </span>watch<span class="w"> </span>--dry-run
 </span></code></pre></div>
 
 
@@ -1976,7 +2267,7 @@ <h3 id="usage-with-ctx-watch">Usage with ctx watch<a class="headerlink" href="#u
       <nav class="md-footer__inner md-grid" aria-label="Footer" >
         
           
-          <a href="../ralph-loop/" class="md-footer__link md-footer__link--prev" aria-label="Previous: ralph + ctx">
+          <a href="../autonomous-loop/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Autonomous Loops">
             <div class="md-footer__button md-icon">
               
               <svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-arrow-left" viewBox="0 0 24 24"><path d="m12 19-7-7 7-7M19 12H5"/></svg>
@@ -1986,7 +2277,7 @@ <h3 id="usage-with-ctx-watch">Usage with ctx watch<a class="headerlink" href="#u
                 Previous
               </span>
               <div class="md-ellipsis">
-                ralph + ctx
+                Autonomous Loops
               </div>
             </div>
           </a>
diff --git a/site/prompting-guide/index.html b/site/prompting-guide/index.html
index 10922579c..23660911c 100644
--- a/site/prompting-guide/index.html
+++ b/site/prompting-guide/index.html
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -773,7 +773,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -782,7 +782,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -1537,6 +1537,11 @@ <h2 id="anti-patterns">Anti-Patterns<a class="headerlink" href="#anti-patterns"
 <td>Discourages questions</td>
 <td>State the requirement directly</td>
 </tr>
+<tr>
+<td>"Idiomatic X"</td>
+<td>Triggers language priors</td>
+<td>"Follow project conventions"</td>
+</tr>
 </tbody>
 </table>
 <hr />
diff --git a/site/search.json b/site/search.json
index d312bf655..7f0f22260 100644
--- a/site/search.json
+++ b/site/search.json
@@ -1 +1 @@
-{"config":{"separator":"[\\s\\-_,:!=\\[\\]()\\\\\"`/]+|\\.(?!\\d)"},"items":[{"location":"","level":1,"title":"Getting Started","text":"","path":["Getting Started"],"tags":[]},{"location":"#ctx","level":2,"title":"<code>ctx</code>","text":"<p><code>ctx</code> (Context) is a file-based system that enables AI coding assistants to persist project knowledge across sessions. Instead of re-explaining your codebase every time, context files let AI tools remember decisions, conventions, and learnings:</p> <ul> <li>A session is interactive.</li> <li><code>ctx</code> enables cognitive continuity.</li> <li>Cognitive continuity enables durable, symbiotic-like human–AI workflows.</li> </ul>","path":["Getting Started"],"tags":[]},{"location":"#community","level":2,"title":"Community","text":"<p>Open source is better together.</p> <p>⭐️ If the idea behind <code>ctx</code> resonates, a star helps it reach engineers who run into context drift every day.</p> <p>→ https://github.com/ActiveMemory/ctx</p> <p>Join the community to ask questions, share feedback, and connect with other users:</p> <ul> <li> Discord:   Chat, get help, share your workflows</li> <li> GitHub:   Star the repo, report issues, contribute</li> </ul>","path":["Getting Started"],"tags":[]},{"location":"#why","level":2,"title":"Why?","text":"<p>Most AI-driven development fails not because models are weak—they fail because  context is ephemeral. Every new session starts near zero:</p> <ul> <li>You re-explain architecture</li> <li>The AI repeats past mistakes</li> <li>Decisions get rediscovered instead of remembered</li> </ul> <p><code>ctx</code> solves this by treating context as infrastructure:  files that version with your code and persist across sessions.</p>","path":["Getting Started"],"tags":[]},{"location":"#installation","level":2,"title":"Installation","text":"","path":["Getting Started"],"tags":[]},{"location":"#binary-downloads-recommended","level":3,"title":"Binary Downloads (Recommended)","text":"<p>Download pre-built binaries from the  releases page.</p> Linux (x86_64)Linux (ARM64)macOS (Apple Silicon)macOS (Intel)Windows <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-linux-amd64\nchmod +x ctx-0.1.2-linux-amd64\nsudo mv ctx-0.1.2-linux-amd64 /usr/local/bin/ctx\n</code></pre> <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-linux-arm64\nchmod +x ctx-0.1.2-linux-arm64\nsudo mv ctx-0.1.2-linux-arm64 /usr/local/bin/ctx\n</code></pre> <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-darwin-arm64\nchmod +x ctx-0.1.2-darwin-arm64\nsudo mv ctx-0.1.2-darwin-arm64 /usr/local/bin/ctx\n</code></pre> <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-darwin-amd64\nchmod +x ctx-0.1.2-darwin-amd64\nsudo mv ctx-0.1.2-darwin-amd64 /usr/local/bin/ctx\n</code></pre> <p>Download <code>ctx-0.1.2-windows-amd64.exe</code> from the releases page and add it to your <code>PATH</code>.</p>","path":["Getting Started"],"tags":[]},{"location":"#verifying-checksums","level":3,"title":"Verifying Checksums","text":"<p>Each binary has a corresponding <code>.sha256</code> checksum file. To verify your download:</p> <pre><code># Download the checksum file\ncurl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-linux-amd64.sha256\n\n# Verify the binary\nsha256sum -c ctx-0.1.2-linux-amd64.sha256\n</code></pre> <p>On macOS, use <code>shasum -a 256 -c</code> instead of <code>sha256sum -c</code>.</p>","path":["Getting Started"],"tags":[]},{"location":"#build-from-source","level":3,"title":"Build from Source","text":"<p>Building from the source gives you the latest features and bug fixes; however, it also means you will be using an unreleased version of <code>ctx</code> that has not been fully tested.</p> <p>Want to help test the latest features?</p> <p>If you like living on the edge and want to test the latest features  before they are released, then building from source is the way to go.</p> <p>Requires Go 1.25+:</p> <pre><code>git clone https://github.com/ActiveMemory/ctx.git\ncd ctx\nmake build\nsudo make install\n# or:\n# sudo mv ctx /usr/local/bin/\n</code></pre> <p>Verify installation:</p> <pre><code>ctx --version\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#quick-start","level":2,"title":"Quick Start","text":"","path":["Getting Started"],"tags":[]},{"location":"#1-initialize-context","level":3,"title":"1. Initialize Context","text":"<pre><code>cd your-project\nctx init\n</code></pre> <p>This creates a <code>.context/</code> directory with template files and configures  AI tool hooks (for Claude Code).</p>","path":["Getting Started"],"tags":[]},{"location":"#2-check-status","level":3,"title":"2. Check Status","text":"<pre><code>ctx status\n</code></pre> <p>Shows context summary: files present, token estimate, and recent activity.</p>","path":["Getting Started"],"tags":[]},{"location":"#3-start-using-with-ai","level":3,"title":"3. Start Using with AI","text":"<p>With Claude Code, context loads automatically via hooks. For other tools, paste the output of:</p> <pre><code>ctx agent --budget 8000\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#4-verify-it-works","level":3,"title":"4. Verify It Works","text":"<p>Ask your AI: \"Do you remember?\"</p> <p>It should cite specific context: current tasks, recent decisions,  or previous session topics.</p>","path":["Getting Started"],"tags":[]},{"location":"#what-gets-created","level":2,"title":"What Gets Created","text":"<pre><code>.context/\n├── CONSTITUTION.md     # Hard rules — NEVER violate these\n├── TASKS.md            # Current and planned work\n├── CONVENTIONS.md      # Project patterns and standards\n├── ARCHITECTURE.md     # System overview\n├── DECISIONS.md        # Architectural decisions with rationale\n├── LEARNINGS.md        # Lessons learned, gotchas, tips\n├── GLOSSARY.md         # Domain terms and abbreviations\n├── DRIFT.md            # Staleness signals\n├── AGENT_PLAYBOOK.md   # How AI tools should use this\n└── sessions/           # Session snapshots\n\n.claude/                # Claude Code integration (if detected)\n├── hooks/              # Auto-save and enforcement scripts\n├── commands/           # ctx slash command definitions\n└── settings.local.json # Hook configuration\n</code></pre> <p>See Context Files for detailed documentation of each file.</p>","path":["Getting Started"],"tags":[]},{"location":"#common-workflows","level":2,"title":"Common Workflows","text":"","path":["Getting Started"],"tags":[]},{"location":"#add-a-task","level":3,"title":"Add a Task","text":"<pre><code>ctx add task \"Implement user authentication\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#record-a-decision","level":3,"title":"Record a Decision","text":"<pre><code>ctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequences \"Team needs PostgreSQL training\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#note-a-learning","level":3,"title":"Note a Learning","text":"<pre><code>ctx add learning \"Mock functions must be hoisted in Jest\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Jest hoists mock calls to top of file\" \\\n  --application \"Place jest.mock() before imports\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#mark-task-complete","level":3,"title":"Mark Task Complete","text":"<pre><code>ctx complete \"user auth\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#check-for-stale-context","level":3,"title":"Check for Stale Context","text":"<pre><code>ctx drift\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#next-steps","level":2,"title":"Next Steps","text":"<ul> <li>Prompting Guide — Effective prompts for AI sessions</li> <li>CLI Reference — All commands and options</li> <li>Context Files — File formats and structure</li> <li><code>ralph</code> and <code>ctx</code> — Autonomous AI development workflows</li> <li>Integrations — Setup for Claude Code, Cursor, Aider</li> </ul>","path":["Getting Started"],"tags":[]},{"location":"cli-reference/","level":1,"title":"CLI Reference","text":"","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-cli","level":2,"title":"<code>ctx</code> CLI","text":"<p>This is a complete reference for all <code>ctx</code> commands.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#global-options","level":2,"title":"Global Options","text":"<p>All commands support these flags:</p> Flag Description <code>--help</code> Show command help <code>--version</code> Show version <code>--context-dir &lt;path&gt;</code> Override context directory (default: <code>.context/</code>) <code>--quiet</code> Suppress non-essential output <code>--no-color</code> Disable colored output <p>The <code>NO_COLOR=1</code> environment variable also disables colored output.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#commands","level":2,"title":"Commands","text":"","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-init","level":3,"title":"<code>ctx init</code>","text":"<p>Initialize a new <code>.context/</code> directory with template files.</p> <pre><code>ctx init [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--force</code> <code>-f</code> Overwrite existing context files <code>--minimal</code> <code>-m</code> Only create essential files (TASKS.md, DECISIONS.md, CONSTITUTION.md) <code>--merge</code> Auto-merge ctx content into existing CLAUDE.md <p>Creates:</p> <ul> <li><code>.context/</code> directory with all template files</li> <li><code>.claude/hooks/</code> with auto-save and enforcement scripts (for Claude Code)</li> <li><code>.claude/commands/</code> with ctx slash command definitions</li> <li><code>.claude/settings.local.json</code> with hook configuration and pre-approved ctx permissions</li> <li><code>CLAUDE.md</code> with bootstrap instructions (or merges into existing)</li> </ul> <p>Example:</p> <pre><code># Standard initialization\nctx init\n\n# Minimal setup (just core files)\nctx init --minimal\n\n# Force overwrite existing\nctx init --force\n\n# Merge into existing CLAUDE.md\nctx init --merge\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-status","level":3,"title":"<code>ctx status</code>","text":"<p>Show the current context summary.</p> <pre><code>ctx status [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--json</code> Output as JSON <code>--verbose</code> <code>-v</code> Include file contents summary <p>Output:</p> <ul> <li>Context directory path</li> <li>Total files and token estimate</li> <li>Status of each file (loaded, empty, missing)</li> <li>Recent activity (modification times)</li> <li>Drift warnings if any</li> </ul> <p>Example:</p> <pre><code>ctx status\nctx status --json\nctx status --verbose\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-agent","level":3,"title":"<code>ctx agent</code>","text":"<p>Print an AI-ready context packet optimized for LLM consumption.</p> <pre><code>ctx agent [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--budget &lt;tokens&gt;</code> Token budget (default: 8000) <code>--format md\\|json</code> Output format (default: md) <p>Output:</p> <ul> <li>Read order for context files</li> <li>Constitution rules (never truncated)</li> <li>Current tasks</li> <li>Key conventions</li> <li>Recent decisions</li> </ul> <p>Example:</p> <pre><code># Default (8000 tokens, markdown)\nctx agent\n\n# Custom budget\nctx agent --budget 4000\n\n# JSON format\nctx agent --format json\n</code></pre> <p>Use case: Copy-paste into AI chat, pipe to system prompt, or use in hooks.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-load","level":3,"title":"<code>ctx load</code>","text":"<p>Load and display assembled context as AI would see it.</p> <pre><code>ctx load [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--budget &lt;tokens&gt;</code> Token budget for assembly (default: 8000) <code>--raw</code> Output raw file contents without assembly <p>Example:</p> <pre><code>ctx load\nctx load --budget 16000\nctx load --raw\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-add","level":3,"title":"<code>ctx add</code>","text":"<p>Add a new item to a context file.</p> <pre><code>ctx add &lt;type&gt; &lt;content&gt; [flags]\n</code></pre> <p>Types:</p> Type Target File <code>task</code> TASKS.md <code>decision</code> DECISIONS.md <code>learning</code> LEARNINGS.md <code>convention</code> CONVENTIONS.md <p>Flags:</p> Flag Short Description <code>--priority &lt;level&gt;</code> Priority for tasks: <code>high</code>, <code>medium</code>, <code>low</code> <code>--section &lt;name&gt;</code> <code>-s</code> Target section within file <code>--context</code> <code>-c</code> Context (required for decisions and learnings) <code>--rationale</code> <code>-r</code> Rationale for decisions (required for decisions) <code>--consequences</code> Consequences for decisions (required for decisions) <code>--lesson</code> <code>-l</code> Key insight (required for learnings) <code>--application</code> <code>-a</code> How to apply going forward (required for learnings) <code>--file</code> <code>-f</code> Read content from file instead of argument <p>Examples:</p> <pre><code># Add a task\nctx add task \"Implement user authentication\"\nctx add task \"Fix login bug\" --priority high\n\n# Record a decision (requires all ADR—Architectural Decision Record—fields)\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequences \"Team needs PostgreSQL training\"\n\n# Note a learning (requires context, lesson, and application)\nctx add learning \"Vitest mocks must be hoisted\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Vitest hoists vi.mock() calls to top of file\" \\\n  --application \"Always place vi.mock() before imports in test files\"\n\n# Add to specific section\nctx add convention \"Use kebab-case for filenames\" --section \"Naming\"\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-complete","level":3,"title":"<code>ctx complete</code>","text":"<p>Mark a task as completed.</p> <pre><code>ctx complete &lt;task-id-or-text&gt;\n</code></pre> <p>Arguments:</p> <ul> <li><code>task-id-or-text</code>: Task number or partial text match</li> </ul> <p>Examples:</p> <pre><code># By text (partial match)\nctx complete \"user auth\"\n\n# By task number\nctx complete 3\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-drift","level":3,"title":"<code>ctx drift</code>","text":"<p>Detect stale or invalid context.</p> <pre><code>ctx drift [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--json</code> Output machine-readable JSON <code>--fix</code> Auto-fix simple issues <p>Checks:</p> <ul> <li>Path references in ARCHITECTURE.md and CONVENTIONS.md exist</li> <li>Task references are valid</li> <li>Constitution rules aren't violated (heuristic)</li> <li>Staleness indicators (old files, many completed tasks)</li> </ul> <p>Example:</p> <pre><code>ctx drift\nctx drift --json\nctx drift --fix\n</code></pre> <p>Exit codes:</p> Code Meaning 0 All checks passed 1 Warnings found 3 Violations found","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-sync","level":3,"title":"<code>ctx sync</code>","text":"<p>Reconcile context with the current codebase state.</p> <pre><code>ctx sync [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--dry-run</code> Show what would change without modifying <p>What it does:</p> <ul> <li>Scans codebase for structural changes</li> <li>Compares with ARCHITECTURE.md</li> <li>Suggests documenting dependencies if package files exist</li> <li>Identifies stale or outdated context</li> </ul> <p>Example:</p> <pre><code>ctx sync\nctx sync --dry-run\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-compact","level":3,"title":"<code>ctx compact</code>","text":"<p>Consolidate and clean up context files.</p> <ul> <li>Moves completed tasks older than 7 days to the archive</li> <li>Deduplicates the \"learning\"s with similar content</li> <li>Removes empty sections</li> </ul> <pre><code>ctx compact [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--archive</code> Create <code>.context/archive/</code> for old content <code>--no-auto-save</code> Skip auto-saving session before compact <p>Example:</p> <pre><code>ctx compact\nctx compact --archive\nctx compact --no-auto-save\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-tasks","level":3,"title":"<code>ctx tasks</code>","text":"<p>Manage task archival and snapshots.</p> <pre><code>ctx tasks &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-tasks-archive","level":4,"title":"<code>ctx tasks archive</code>","text":"<p>Move completed tasks from TASKS.md to a timestamped archive file.</p> <pre><code>ctx tasks archive [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--dry-run</code> Preview changes without modifying files <p>Archive files are stored in <code>.context/archive/</code> with timestamped names (<code>tasks-YYYY-MM-DD.md</code>). Completed tasks (marked with <code>[x]</code>) are moved; pending tasks (<code>[ ]</code>) remain in TASKS.md.</p> <p>Example:</p> <pre><code>ctx tasks archive\nctx tasks archive --dry-run\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-tasks-snapshot","level":4,"title":"<code>ctx tasks snapshot</code>","text":"<p>Create a point-in-time snapshot of TASKS.md without modifying the original.</p> <pre><code>ctx tasks snapshot [name]\n</code></pre> <p>Arguments:</p> <ul> <li><code>name</code>: Optional name for the snapshot (defaults to \"snapshot\")</li> </ul> <p>Snapshots are stored in <code>.context/archive/</code> with timestamped names (<code>tasks-&lt;name&gt;-YYYY-MM-DD-HHMM.md</code>).</p> <p>Example:</p> <pre><code>ctx tasks snapshot\nctx tasks snapshot \"before-refactor\"\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-decisions","level":3,"title":"<code>ctx decisions</code>","text":"<p>Manage the DECISIONS.md file.</p> <pre><code>ctx decisions &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-decisions-reindex","level":4,"title":"<code>ctx decisions reindex</code>","text":"<p>Regenerate the quick-reference index at the top of DECISIONS.md.</p> <pre><code>ctx decisions reindex\n</code></pre> <p>The index is a compact table showing date and title for each decision, allowing AI tools to quickly scan entries without reading the full file.</p> <p>Use this after manual edits to DECISIONS.md or when migrating existing files to use the index format.</p> <p>Example:</p> <pre><code>ctx decisions reindex\n# ✓ Index regenerated with 12 entries\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-learnings","level":3,"title":"<code>ctx learnings</code>","text":"<p>Manage the LEARNINGS.md file.</p> <pre><code>ctx learnings &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-learnings-reindex","level":4,"title":"<code>ctx learnings reindex</code>","text":"<p>Regenerate the quick-reference index at the top of LEARNINGS.md.</p> <pre><code>ctx learnings reindex\n</code></pre> <p>The index is a compact table showing date and title for each learning, allowing AI tools to quickly scan entries without reading the full file.</p> <p>Use this after manual edits to LEARNINGS.md or when migrating existing files to use the index format.</p> <p>Example:</p> <pre><code>ctx learnings reindex\n# ✓ Index regenerated with 8 entries\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall","level":3,"title":"<code>ctx recall</code>","text":"<p>Browse and search AI session history from Claude Code and other tools.</p> <pre><code>ctx recall &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall-list","level":4,"title":"<code>ctx recall list</code>","text":"<p>List all parsed sessions.</p> <pre><code>ctx recall list [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--limit</code> <code>-n</code> Maximum sessions to display (default: 20) <code>--project</code> <code>-p</code> Filter by project name <code>--tool</code> <code>-t</code> Filter by tool (e.g., <code>claude-code</code>) <p>Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.</p> <p>Example:</p> <pre><code>ctx recall list\nctx recall list --limit 5\nctx recall list --project ctx\nctx recall list --tool claude-code\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall-show","level":4,"title":"<code>ctx recall show</code>","text":"<p>Show details of a specific session.</p> <pre><code>ctx recall show [session-id] [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--latest</code> Show the most recent session <code>--full</code> Show full message content <p>The session ID can be a full UUID, partial match, or session slug name.</p> <p>Example:</p> <pre><code>ctx recall show abc123\nctx recall show gleaming-wobbling-sutherland\nctx recall show --latest\nctx recall show --latest --full\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-watch","level":3,"title":"<code>ctx watch</code>","text":"<p>Watch for AI output and auto-apply context updates.</p> <p>Parses <code>&lt;context-update&gt;</code> XML commands from AI output and applies them to context files.</p> <pre><code>ctx watch [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--log &lt;file&gt;</code> Log file to watch (default: stdin) <code>--dry-run</code> Preview updates without applying <code>--auto-save</code> Periodically save session snapshots <p>Example:</p> <pre><code># Watch stdin\nai-tool | ctx watch\n\n# Watch a log file\nctx watch --log /path/to/ai-output.log\n\n# Preview without applying\nctx watch --dry-run\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-hook","level":3,"title":"<code>ctx hook</code>","text":"<p>Generate AI tool integration configuration.</p> <pre><code>ctx hook &lt;tool&gt;\n</code></pre> <p>Supported tools:</p> Tool Description <code>claude-code</code> Claude Code CLI <code>cursor</code> Cursor IDE <code>aider</code> Aider CLI <code>copilot</code> GitHub Copilot <code>windsurf</code> Windsurf IDE <p>Example:</p> <pre><code>ctx hook claude-code\nctx hook cursor\nctx hook aider\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session","level":3,"title":"<code>ctx session</code>","text":"<p>Manage session snapshots.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-save","level":4,"title":"ctx session save","text":"<p>Save the current context snapshot.</p> <pre><code>ctx session save [topic] [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--type &lt;type&gt;</code> <code>-t</code> Session type: <code>feature</code>, <code>bugfix</code>, <code>refactor</code>, <code>session</code> <p>Example:</p> <pre><code>ctx session save\nctx session save \"feature-auth\"\nctx session save \"bugfix\" --type bugfix\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-list","level":4,"title":"<code>ctx session list</code>","text":"<p>List saved sessions.</p> <pre><code>ctx session list [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--limit</code> <code>-n</code> Maximum sessions to display (default: 10) <p>Output: Table of sessions with index, date, topic, and type.</p> <p>Example:</p> <pre><code>ctx session list\nctx session list --limit 5\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-load","level":4,"title":"<code>ctx session load</code>","text":"<p>Load and display a previous session.</p> <pre><code>ctx session load &lt;index|date|topic&gt;\n</code></pre> <p>Arguments:</p> <ul> <li><code>index</code>: Numeric index from <code>session list</code></li> <li><code>date</code>: Date pattern (e.g., <code>2026-01-21</code>)</li> <li><code>topic</code>: Topic keyword match</li> </ul> <p>Example:</p> <pre><code>ctx session load 1           # by index\nctx session load 2026-01-21  # by date\nctx session load auth        # by topic\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-parse","level":4,"title":"<code>ctx session parse</code>","text":"<p>Parse JSONL transcript to readable markdown.</p> <pre><code>ctx session parse &lt;file&gt; [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--output</code> <code>-o</code> Output file (default: stdout) <code>--extract</code> Extract decisions and learnings from transcript <p>Example:</p> <pre><code>ctx session parse ~/.claude/projects/.../transcript.jsonl\nctx session parse transcript.jsonl --extract\nctx session parse transcript.jsonl -o conversation.md\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-loop","level":3,"title":"<code>ctx loop</code>","text":"<p>Generate a shell script for running a Ralph loop.</p> <p>A Ralph loop continuously runs an AI assistant with the same prompt until a completion signal is detected, enabling iterative development where the AI builds on its previous work.</p> <pre><code>ctx loop [flags]\n</code></pre> <p>Flags:</p> Flag Short Description Default <code>--tool &lt;tool&gt;</code> <code>-t</code> AI tool: <code>claude</code>, <code>aider</code>, or <code>generic</code> <code>claude</code> <code>--prompt &lt;file&gt;</code> <code>-p</code> Prompt file to use <code>PROMPT.md</code> <code>--max-iterations &lt;n&gt;</code> <code>-n</code> Maximum iterations (0 = unlimited) <code>0</code> <code>--completion &lt;signal&gt;</code> <code>-c</code> Completion signal to detect <code>SYSTEM_CONVERGED</code> <code>--output &lt;file&gt;</code> <code>-o</code> Output script filename <code>loop.sh</code> <p>Example:</p> <pre><code># Generate loop.sh for Claude Code\nctx loop\n\n# Generate for Aider with custom prompt\nctx loop --tool aider --prompt TASKS.md\n\n# Limit to 10 iterations\nctx loop --max-iterations 10\n\n# Output to custom file\nctx loop -o my-loop.sh\n</code></pre> <p>Usage:</p> <pre><code># Generate and run the loop\nctx loop\nchmod +x loop.sh\n./loop.sh\n</code></pre> <p>See Ralph Loop Integration for detailed workflow documentation.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#exit-codes","level":2,"title":"Exit Codes","text":"Code Meaning 0 Success 1 General error 2 Context not found 3 Invalid arguments 4 File operation error","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#environment-variables","level":2,"title":"Environment Variables","text":"Variable Description <code>CTX_DIR</code> Override default context directory path <code>CTX_TOKEN_BUDGET</code> Override default token budget <code>NO_COLOR</code> Disable colored output when set","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#configuration-file","level":2,"title":"Configuration File","text":"<p>Optional <code>.contextrc</code> (YAML format) at project root:</p> <pre><code># .contextrc\ncontext_dir: .context # Context directory name\ntoken_budget: 8000    # Default token budget\npriority_order:       # File loading priority\n  - TASKS.md\n  - DECISIONS.md\n  - CONVENTIONS.md\nauto_archive: true    # Auto-archive old items\narchive_after_days: 7 # Days before archiving\n</code></pre> <p>Priority order: CLI flags &gt; Environment variables &gt; <code>.contextrc</code> &gt; Defaults</p> <p>All settings are optional. Missing values use defaults.</p>","path":["CLI Reference"],"tags":[]},{"location":"comparison/","level":1,"title":"ctx and Similar Tools","text":"","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#high-level-mental-model","level":2,"title":"High-Level Mental Model","text":"<p>Many tools help AI think.</p> <p><code>ctx</code> helps AI remember.</p> <p>Not by storing thoughts, but by preserving intent.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#how-ctx-differs-from-similar-tools","level":2,"title":"How <code>ctx</code> Differs from Similar Tools","text":"<p>There are many tools in the AI ecosystem that touch parts of the context problem:</p> <ul> <li>Some manage prompts.  </li> <li>Some retrieve data.  </li> <li>Some provide runtime context objects.  </li> <li>Some offer enterprise platforms.</li> </ul> <p><code>ctx</code> focuses on a different layer entirely.</p> <p>This page explains where <code>ctx</code> fits, and where it intentionally does not.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#the-core-distinction","level":2,"title":"The Core Distinction","text":"<p>Most tools treat context as input.</p> <p><code>ctx</code> treats context as infrastructure.</p> <p>That single difference explains nearly all of <code>ctx</code>'s design choices.</p> Question Most tools ctx Where does context live? In prompts or APIs In files How long does it last? One request / one session Across time Who can read it? The model Humans and tools How is it updated? Implicitly Explicitly Is it inspectable? Rarely Always","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#prompt-management-tools","level":2,"title":"Prompt Management Tools","text":"<p>Examples include:</p> <ul> <li>prompt templates</li> <li>reusable system prompts</li> <li>prompt libraries</li> <li>prompt versioning tools</li> </ul> <p>These tools help you start a session.</p> <p>They do not help you continue one.</p> <p>Prompt tools:</p> <ul> <li>inject text at session start</li> <li>are ephemeral by design</li> <li>do not evolve with the project</li> </ul> <p><code>ctx</code>:</p> <ul> <li>persists knowledge over time</li> <li>accumulates decisions and learnings</li> <li>makes the context part of the repository itself</li> </ul> <p>Prompt tooling and <code>ctx</code> are complementary; not competing.  Yet, they operate at different layers.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#retrieval-augmented-generation-rag","level":2,"title":"Retrieval-Augmented Generation (RAG)","text":"<p>RAG systems typically:</p> <ul> <li>index documents</li> <li>embed text</li> <li>retrieve chunks dynamically at runtime</li> </ul> <p>They are excellent for:</p> <ul> <li>large knowledge bases</li> <li>static documentation</li> <li>reference material</li> </ul> <p>RAG answers questions like:</p> <p>\"What information might be relevant right now?\"</p> <p><code>ctx</code> answers a different question:</p> <p>\"What have we already decided, learned, or committed to?\"</p> <p>Here are some key differences:</p> RAG ctx Statistical relevance Intentional relevance Embedding-based File-based Opaque retrieval Explicit structure Runtime query Persistent memory <p><code>ctx</code> does not replace RAG. Instead, it defines a persistent context layer that RAG can optionally augment.</p> <p>RAG belongs to the data plane; ctx defines the context control plane.</p> <p>It focuses on project memory, not knowledge search.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#agent-frameworks","level":2,"title":"Agent Frameworks","text":"<p>Agent frameworks often provide:</p> <ul> <li>task loops</li> <li>tool orchestration</li> <li>planner/executor patterns</li> <li>autonomous iteration</li> </ul> <p>These systems are powerful, but they typically assume that:</p> <ul> <li>memory is external</li> <li>context is injected</li> <li>state is transient</li> </ul> <p>Agent frameworks answer:</p> <p>\"How should the agent act?\"</p> <p><code>ctx</code> answers:</p> <p>\"What should the agent remember?\"</p> <p>Without persistent context, agents tend to:</p> <ul> <li>rediscover decisions</li> <li>repeat mistakes</li> <li>lose architectural intent</li> </ul> <p>This is why <code>ctx</code> pairs well with loop-based workflows such as the Ralph Wiggum technique:</p> <ul> <li><code>ralph</code> provides iteration</li> <li><code>ctx</code> provides continuity</li> </ul> <p>Together, loops become cumulative instead of forgetful.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#sdk-level-context-objects","level":2,"title":"SDK-Level Context Objects","text":"<p>Some SDKs expose \"context\" objects that exist:</p> <ul> <li>inside a process</li> <li>during a request</li> <li>for the lifetime of a call chain</li> </ul> <p>These are extremely useful and completely different.</p> <p>SDK context objects:</p> <ul> <li>are in-memory</li> <li>disappear when the process ends</li> <li>are not shared across sessions</li> </ul> <p><code>ctx</code>:</p> <ul> <li>survives process restarts</li> <li>survives new chats</li> <li>survives new days</li> </ul> <p>They share a name, not a purpose.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#enterprise-context-platforms","level":2,"title":"Enterprise Context Platforms","text":"<p>Enterprise platforms often provide:</p> <ul> <li>centralized context services</li> <li>dashboards</li> <li>access control</li> <li>organizational knowledge layers</li> </ul> <p>These tools are designed for:</p> <ul> <li>teams</li> <li>governance</li> <li>compliance</li> <li>managed environments</li> </ul> <p><code>ctx</code> is intentionally:</p> <ul> <li>local-first</li> <li>file-based</li> <li>dependency-free</li> <li>CLI-driven</li> <li>developer-controlled</li> </ul> <p>It does not require:</p> <ul> <li>a server</li> <li>a database</li> <li>an account</li> <li>a SaaS backend</li> </ul> <p><code>ctx</code> optimizes for individual and small-team workflows where context should live next to code; not behind a service boundary.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#when-ctx-is-a-good-fit","level":2,"title":"When <code>ctx</code> Is a Good Fit","text":"<p><code>ctx</code> works best when:</p> <ul> <li>you want AI work to compound over time</li> <li>architectural decisions matter</li> <li>context must be inspectable</li> <li>humans and AI must share the same source of truth</li> <li>Git history should include why, not just what</li> </ul>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#when-ctx-is-not-the-right-tool","level":2,"title":"When <code>ctx</code> Is Not the Right Tool","text":"<p><code>ctx</code> is probably not what you want if:</p> <ul> <li>you only need one-off prompts</li> <li>you rely exclusively on RAG</li> <li>you want autonomous agents without a human-readable state</li> <li>you require centralized enterprise control</li> <li>you want black-box memory systems</li> </ul> <p>These are valid goals; just different ones.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"context-files/","level":1,"title":"Context Files","text":"","path":["Context Files"],"tags":[]},{"location":"context-files/#context","level":2,"title":"<code>.context/</code>","text":"<p>Each context file in <code>.context/</code> serves a specific purpose. </p> <p>Files are designed to be human-readable, AI-parseable, and token-efficient.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#file-overview","level":2,"title":"File Overview","text":"File Purpose Priority CONSTITUTION.md Hard rules that must NEVER be violated 1 (highest) TASKS.md Current and planned work 2 CONVENTIONS.md Project patterns and standards 3 ARCHITECTURE.md System overview and components 4 DECISIONS.md Architectural decisions with rationale 5 LEARNINGS.md Lessons learned, gotchas, tips 6 GLOSSARY.md Domain terms and abbreviations 7 DRIFT.md Staleness signals and update triggers 8 AGENT_PLAYBOOK.md Instructions for AI tools 9 (lowest)","path":["Context Files"],"tags":[]},{"location":"context-files/#read-order-rationale","level":2,"title":"Read Order Rationale","text":"<p>The priority order follows a logical progression for AI tools:</p> <ol> <li> <p>CONSTITUTION — Inviolable rules first. The AI tool must know what it    cannot do before attempting anything.</p> </li> <li> <p>TASKS — Current work items. What the AI tool should focus on.</p> </li> <li> <p>CONVENTIONS — How to write code. Patterns and standards to follow    when implementing tasks.</p> </li> <li> <p>ARCHITECTURE — System structure. Understanding of components and    boundaries before making changes.</p> </li> <li> <p>DECISIONS — Historical context. Why things are the way they are,    to avoid re-debating settled decisions.</p> </li> <li> <p>LEARNINGS — Gotchas and tips. Lessons from past work that inform    current implementation.</p> </li> <li> <p>GLOSSARY — Reference material. Domain terms and abbreviations for    lookup as needed.</p> </li> <li> <p>DRIFT — Staleness indicators. Lower priority since it's primarily    for maintenance workflows, not active development.</p> </li> <li> <p>AGENT_PLAYBOOK — Meta instructions last. How to use this context    system itself. Loaded last because the agent should understand the    content (rules, tasks, patterns) before the operating manual.</p> </li> </ol>","path":["Context Files"],"tags":[]},{"location":"context-files/#constitutionmd","level":2,"title":"CONSTITUTION.md","text":"<p>Purpose: Define hard invariants—rules that must NEVER be violated,  regardless of the task.</p> <p>AI tools read this first and should refuse tasks that violate these rules.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure","level":3,"title":"Structure","text":"<pre><code># Constitution\n\nThese rules are INVIOLABLE. If a task requires violating these, the task \nis wrong.\n\n## Security Invariants\n\n- [ ] Never commit secrets, tokens, API keys, or credentials\n- [ ] Never store customer/user data in context files\n- [ ] Never disable security linters without documented exception\n\n## Quality Invariants\n\n- [ ] All code must pass tests before commit\n- [ ] No `any` types in TypeScript without documented reason\n- [ ] No TODO comments in main branch (move to TASKS.md)\n\n## Process Invariants\n\n- [ ] All architectural changes require a decision record\n- [ ] Breaking changes require version bump\n- [ ] Generated files are never committed\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines","level":3,"title":"Guidelines","text":"<ul> <li>Keep rules minimal and absolute</li> <li>Each rule should be enforceable (can verify compliance)</li> <li>Use checkbox format for clarity</li> <li>Never compromise on these rules</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#tasksmd","level":2,"title":"TASKS.md","text":"<p>Purpose: Track current work, planned work, and blockers.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_1","level":3,"title":"Structure","text":"<p>Tasks are organized by Phase — logical groupings that preserve order and enable replay. Tasks stay in their Phase permanently; status is tracked via checkboxes and inline tags.</p> <pre><code># Tasks\n\n## Phase 1: Initial Setup\n\n- [x] Set up project structure\n- [x] Configure linting and formatting\n- [ ] Add CI/CD pipeline `#in-progress`\n\n## Phase 2: Core Features\n\n- [ ] Implement user authentication `#priority:high`\n- [ ] Add API rate limiting `#priority:medium`\n  - Blocked by: Need to finalize auth first\n\n## Backlog\n\n- [ ] Performance optimization `#priority:low`\n- [ ] Add metrics dashboard `#priority:deferred`\n</code></pre> <p>Key principles: - Tasks never move between sections — mark as <code>[x]</code> or <code>[-]</code> in place - Use <code>#in-progress</code> inline tag to indicate current work - Phase headers provide structure and replay order - Backlog section for unscheduled work</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#tags","level":3,"title":"Tags","text":"<p>Use inline backtick-wrapped tags for metadata:</p> Tag Values Purpose <code>#priority</code> <code>high</code>, <code>medium</code>, <code>low</code> Task urgency <code>#area</code> <code>core</code>, <code>cli</code>, <code>docs</code>, <code>tests</code> Codebase area <code>#estimate</code> <code>1h</code>, <code>4h</code>, <code>1d</code> Time estimate (optional) <code>#in-progress</code> (none) Currently being worked on <p>Lifecycle tags (for session correlation):</p> Tag Format When to add <code>#added</code> <code>YYYY-MM-DD-HHMMSS</code> Auto-added by <code>ctx add task</code> <code>#started</code> <code>YYYY-MM-DD-HHMMSS</code> When beginning work on the task <code>#done</code> <code>YYYY-MM-DD-HHMMSS</code> When marking the task <code>[x]</code> <p>These timestamps help correlate tasks with session files and track which session started vs completed work.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#status-markers","level":3,"title":"Status Markers","text":"Marker Meaning <code>[ ]</code> Pending <code>[x]</code> Completed <code>[-]</code> Skipped (include reason)","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_1","level":3,"title":"Guidelines","text":"<ul> <li>Never delete tasks — mark as <code>[x]</code> completed or <code>[-]</code> skipped</li> <li>Never move tasks between sections — use inline tags for status</li> <li>Use <code>ctx tasks archive</code> periodically to move completed tasks to archive</li> <li>Mark current work with <code>#in-progress</code> inline tag</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#decisionsmd","level":2,"title":"DECISIONS.md","text":"<p>Purpose: Record architectural decisions with rationale so they don't get re-debated.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_2","level":3,"title":"Structure","text":"<pre><code># Decisions\n\n## [YYYY-MM-DD] Decision Title\n\n**Status**: Accepted | Superseded | Deprecated\n\n**Context**: What situation prompted this decision?\n\n**Decision**: What was decided?\n\n**Rationale**: Why was this the right choice?\n\n**Consequences**: What are the implications?\n\n**Alternatives Considered**:\n- Alternative A: Why rejected\n- Alternative B: Why rejected\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#example","level":3,"title":"Example","text":"<pre><code>## [2025-01-15] Use TypeScript Strict Mode\n\n**Status**: Accepted\n\n**Context**: Starting new project, need to choose type checking level.\n\n**Decision**: Enable TypeScript strict mode with all strict flags.\n\n**Rationale**: Catches more bugs at compile time. Team has experience\nwith strict mode. Upfront cost pays off in reduced runtime errors.\n\n**Consequences**: More verbose type annotations required. Some\nthird-party libraries need type assertions.\n\n**Alternatives Considered**:\n- Basic TypeScript: Rejected because it misses null checks\n- JavaScript with JSDoc: Rejected because tooling support is weaker\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#status-values","level":3,"title":"Status Values","text":"Status Meaning Accepted Current, active decision Superseded Replaced by newer decision (link to it) Deprecated No longer relevant","path":["Context Files"],"tags":[]},{"location":"context-files/#learningsmd","level":2,"title":"LEARNINGS.md","text":"<p>Purpose: Capture lessons learned, gotchas, and tips that shouldn't be forgotten.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_3","level":3,"title":"Structure","text":"<pre><code># Learnings\n\n## Category Name\n\n### Learning Title\n\n**Discovered**: YYYY-MM-DD\n\n**Context**: When/how was this learned?\n\n**Lesson**: What's the takeaway?\n\n**Application**: How should this inform future work?\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#example_1","level":3,"title":"Example","text":"<pre><code>## Testing\n\n### Vitest Mocks Must Be Hoisted\n\n**Discovered**: 2025-01-15\n\n**Context**: Tests were failing intermittently when mocking fs module.\n\n**Lesson**: Vitest requires `vi.mock()` calls to be hoisted to the\ntop of the file. Dynamic mocks need `vi.doMock()` instead.\n\n**Application**: Always use `vi.mock()` at file top. Use `vi.doMock()`\nonly when mock needs runtime values.\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#categories","level":3,"title":"Categories","text":"<p>Organize learnings by topic:</p> <ul> <li>Testing</li> <li>Build &amp; Deploy</li> <li>Performance</li> <li>Security</li> <li>Third-Party Libraries</li> <li>Git &amp; Workflow</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#conventionsmd","level":2,"title":"CONVENTIONS.md","text":"<p>Purpose: Document project patterns, naming conventions, and standards.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_4","level":3,"title":"Structure","text":"<pre><code># Conventions\n\n## Naming\n\n- **Files**: kebab-case for all source files\n- **Components**: PascalCase for React components\n- **Functions**: camelCase, verb-first (getUser, parseConfig)\n- **Constants**: SCREAMING_SNAKE_CASE\n\n## Patterns\n\n### Pattern Name\n\n**When to use**: Situation description\n\n**Implementation**:\n// in triple backticks\n// Example code\n\n**Why**: Rationale for this pattern\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_2","level":3,"title":"Guidelines","text":"<ul> <li>Include concrete examples</li> <li>Explain the \"why\" not just the \"what\"</li> <li>Keep patterns minimal—only document what's non-obvious</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#architecturemd","level":2,"title":"ARCHITECTURE.md","text":"<p>Purpose: Provide system overview and component relationships.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_5","level":3,"title":"Structure","text":"<pre><code># Architecture\n\n## Overview\n\nBrief description of what the system does and how it's organized.\n\n## Components\n\n### Component Name\n\n**Responsibility**: What this component does\n\n**Dependencies**: What it depends on\n\n**Dependents**: What depends on it\n\n**Key Files**:\n- path/to/file.ts — Description\n\n## Data Flow\n\nDescription or diagram of how data moves through the system.\n\n## Boundaries\n\nWhat's in scope vs out of scope for this codebase.\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_3","level":3,"title":"Guidelines","text":"<ul> <li>Keep diagrams simple (Mermaid works well)</li> <li>Focus on boundaries and interfaces</li> <li>Update when major structural changes occur</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#glossarymd","level":2,"title":"GLOSSARY.md","text":"<p>Purpose: Define domain terms, abbreviations, and project vocabulary.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_6","level":3,"title":"Structure","text":"<pre><code># Glossary\n\n## Domain Terms\n\n### Term Name\n\n**Definition**: What it means in this project's context\n\n**Not to be confused with**: Similar terms that mean different things\n\n**Example**: How it's used\n\n## Abbreviations\n\n| Abbrev | Expansion                     | Context                |\n|--------|-------------------------------|------------------------|\n| ADR    | Architectural Decision Record | Decision documentation |\n| SUT    | System Under Test             | Testing                |\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_4","level":3,"title":"Guidelines","text":"<ul> <li>Define project-specific meanings</li> <li>Clarify potentially ambiguous terms</li> <li>Include abbreviations used in code or docs</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#driftmd","level":2,"title":"DRIFT.md","text":"<p>Purpose: Define signals that the context is stale and needs updating.</p> <p>Used by <code>ctx drift</code> command to detect staleness.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_7","level":3,"title":"Structure","text":"<pre><code># Drift Detection\n\n## Automatic Checks\n\nThese are checked by `ctx drift`:\n\n### Path References\n\n- [ ] All paths in ARCHITECTURE.md exist in filesystem\n- [ ] All paths in CONVENTIONS.md exist\n- [ ] All file references in DECISIONS.md are valid\n\n### Task References\n\n- [ ] All issues referenced in TASKS.md exist\n- [ ] No tasks older than 30 days without update\n\n### Constitution Violations\n\n- [ ] No secrets patterns detected in committed files\n\n## Manual Review Triggers\n\nUpdate context when:\n\n- [ ] New team member joins (review CONVENTIONS.md)\n- [ ] Major dependency upgraded (review ARCHITECTURE.md)\n- [ ] Sprint/milestone completed (archive old tasks)\n\n## Staleness Indicators\n\n| File            | Stale If       | Action                 |\n|-----------------|----------------|------------------------|\n| ARCHITECTURE.md | &gt;30 days old   | Review component list  |\n| TASKS.md        | &gt;50% completed | Archive and refresh    |\n| LEARNINGS.md    | &gt;20 items      | Consolidate or archive |\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#agent_playbookmd","level":2,"title":"AGENT_PLAYBOOK.md","text":"<p>Purpose: Explicit instructions for how AI tools should read, apply,  and update context.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#key-sections","level":3,"title":"Key Sections","text":"<p>Read Order: Priority order for loading context files</p> <p>When to Update: Events that trigger context updates</p> <p>How to Avoid Hallucinating Memory: Critical rules:</p> <ol> <li>Never assume—if not in files, you don't know it</li> <li>Never invent history—don't claim \"we discussed\" without evidence</li> <li>Verify before referencing—search files before citing</li> <li>When uncertain, say so</li> <li>Trust files over intuition</li> </ol> <p>Context Update Commands: Format for automated updates via <code>ctx watch</code>:</p> <pre><code>&lt;context-update type=\"learning\"&gt;Key takeaway from today's work&lt;/context-update&gt;\n&lt;context-update type=\"decision\"&gt;Use Redis for caching&lt;/context-update&gt;\n&lt;context-update type=\"complete\"&gt;user auth&lt;/context-update&gt;\n</code></pre> <p>See Integrations for full documentation.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#parsing-rules","level":2,"title":"Parsing Rules","text":"<p>All context files follow these conventions:</p> <ol> <li>Headers define structure — <code>#</code> for title, <code>##</code> for sections, <code>###</code> for     items</li> <li>Bold keys for fields — <code>**Key**:</code> followed by value</li> <li>Code blocks are literal — Never parse code block content as structure</li> <li>Lists are ordered — Items appear in priority/chronological order</li> <li>Tags are inline — Backtick-wrapped tags like <code>#priority:high</code></li> </ol>","path":["Context Files"],"tags":[]},{"location":"context-files/#token-efficiency","level":2,"title":"Token Efficiency","text":"<p>Keep context files concise:</p> <ul> <li>Use abbreviations in tags, not prose</li> <li>Omit obvious words (\"The\", \"This\")</li> <li>Prefer bullet points over paragraphs</li> <li>Keep examples minimal but illustrative</li> <li>Archive old completed items periodically</li> </ul>","path":["Context Files"],"tags":[]},{"location":"integrations/","level":1,"title":"AI Tool Integrations","text":"","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#ai-tool-integrations","level":2,"title":"AI Tool Integrations","text":"<p>Context works with any AI tool that can read files. This guide covers setup  for popular AI coding assistants.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#claude-code-full-integration","level":2,"title":"Claude Code (Full Integration)","text":"<p>Claude Code has the deepest integration with automatic context loading and  session persistence.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#automatic-setup","level":3,"title":"Automatic Setup","text":"<p>Running <code>ctx init</code> automatically configures Claude Code:</p> <pre><code>ctx init\n</code></pre> <p>This creates:</p> File/Directory Purpose <code>.context/</code> All context files <code>.claude/hooks/</code> Auto-save scripts <code>.claude/settings.local.json</code> Hook configuration <code>CLAUDE.md</code> Bootstrap instructions","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#how-it-works","level":3,"title":"How It Works","text":"<pre><code>graph TD\n    A[Session Start] --&gt; B[Claude reads CLAUDE.md]\n    B --&gt; C[PreToolUse hook runs]\n    C --&gt; D[ctx agent loads context]\n    D --&gt; E[Work happens]\n    E --&gt; F[Session End]\n    F --&gt; G[SessionEnd hook saves snapshot]</code></pre> <ol> <li>Session start: Claude reads <code>CLAUDE.md</code>, which tells it to check <code>.context/</code></li> <li>During session: <code>PreToolUse</code> hook runs <code>ctx agent --budget 4000</code>     before each tool use</li> <li>Session end: <code>SessionEnd</code> hook saves context snapshot to <code>.context/sessions/</code></li> <li>Next session: Claude sees previous sessions and continues with context</li> </ol>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#generated-configuration","level":3,"title":"Generated Configuration","text":"<p><code>.claude/settings.local.json</code>:</p> <pre><code>{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \".*\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"ctx agent --budget 4000 2&gt;/dev/null || true\"\n          }\n        ]\n      }\n    ],\n    \"SessionEnd\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \".claude/hooks/auto-save-session.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#customizing-token-budget","level":3,"title":"Customizing Token Budget","text":"<p>Edit the PreToolUse command to change the token budget:</p> <pre><code>\"command\": \"ctx agent --budget 8000 2&gt;/dev/null || true\"\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#verifying-setup","level":3,"title":"Verifying Setup","text":"<ol> <li>Start a new Claude Code session</li> <li>Ask: \"Do you remember?\"</li> <li>Claude should cite specific context:</li> <li>Current tasks from <code>.context/TASKS.md</code></li> <li>Recent decisions or learnings</li> <li>Previous session topics from <code>.context/sessions/</code></li> </ol>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#troubleshooting","level":3,"title":"Troubleshooting","text":"Issue Solution Context not loading Check <code>ctx</code> is in PATH: <code>which ctx</code> No sessions saved Verify <code>.claude/settings.local.json</code> has <code>SessionEnd</code> hook Hook errors Check script permissions: <code>chmod +x .claude/hooks/*.sh</code> Missing sessions dir Create it: <code>mkdir -p .context/sessions</code>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#manual-context-load","level":3,"title":"Manual Context Load","text":"<p>If hooks aren't working, manually load context:</p> <pre><code># Get context packet\nctx agent --budget 4000\n\n# Or paste into conversation\ncat .context/TASKS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#cursor-ide","level":2,"title":"Cursor IDE","text":"<p>Cursor can use context files through its system prompt or by reading  files directly.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup","level":3,"title":"Setup","text":"<pre><code># Generate Cursor configuration\nctx hook cursor\n\n# Initialize context\nctx init --minimal\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#configuration","level":3,"title":"Configuration","text":"<p>Add to Cursor settings (<code>.cursor/settings.json</code>):</p> <pre><code>// split to multiple lines for readability\n{\n  \"ai.systemPrompt\": \"Read .context/TASKS.md and \n  .context/CONVENTIONS.md before responding. \n  Follow rules in .context/CONSTITUTION.md.\",\n}\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage","level":3,"title":"Usage","text":"<ol> <li>Open your project in Cursor</li> <li>Context files are available in the file tree</li> <li>Reference them in prompts:     \"Check .context/DECISIONS.md for our approach to...\"</li> </ol>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#manual-context-injection","level":3,"title":"Manual Context Injection","text":"<p>For more control, paste context directly:</p> <pre><code># Get AI-ready packet\nctx agent --budget 4000 | pbcopy  # macOS\nctx agent --budget 4000 | xclip  # Linux\n</code></pre> <p>Paste into Cursor's chat.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#aider","level":2,"title":"Aider","text":"<p>Aider works well with context files through its <code>--read</code> flag.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup_1","level":3,"title":"Setup","text":"<pre><code># Generate Aider configuration\nctx hook aider\n\n# Initialize context\nctx init\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#configuration_1","level":3,"title":"Configuration","text":"<p>Create <code>.aider.conf.yml</code>:</p> <pre><code>read:\n  - .context/CONSTITUTION.md\n  - .context/TASKS.md\n  - .context/CONVENTIONS.md\n  - .context/DECISIONS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage_1","level":3,"title":"Usage","text":"<pre><code># Start Aider (reads context files automatically)\naider\n\n# Or specify files explicitly\naider --read .context/TASKS.md --read .context/CONVENTIONS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#with-watch-mode","level":3,"title":"With Watch Mode","text":"<p>Run <code>ctx watch</code> alongside Aider to capture context updates:</p> <pre><code># Terminal 1: Run Aider\naider 2&gt;&amp;1 | tee /tmp/aider.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/aider.log\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#github-copilot","level":2,"title":"GitHub Copilot","text":"<p>Copilot reads open files for context. Keep context files open or reference  them in comments.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup_2","level":3,"title":"Setup","text":"<pre><code># Generate Copilot tips\nctx hook copilot\n\n# Initialize context\nctx init --minimal\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage-patterns","level":3,"title":"Usage Patterns","text":"<p>Pattern 1: Keep context files open</p> <p>Open <code>.context/CONVENTIONS.md</code> in a split pane. Copilot will reference it.</p> <p>Pattern 2: Reference in comments</p> <pre><code>// See .context/CONVENTIONS.md for naming patterns\n// Following decision in .context/DECISIONS.md: Use PostgreSQL\n\nfunction getUserById(id: string) {\n  // Copilot now has context\n}\n</code></pre> <p>Pattern 3: Paste context into Copilot Chat</p> <pre><code>ctx agent --budget 2000\n</code></pre> <p>Paste output into Copilot Chat for context-aware responses.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#windsurf-ide","level":2,"title":"Windsurf IDE","text":"<p>Windsurf supports custom instructions and file-based context.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup_3","level":3,"title":"Setup","text":"<pre><code># Generate Windsurf configuration\nctx hook windsurf\n\n# Initialize context\nctx init\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#configuration_2","level":3,"title":"Configuration","text":"<p>Add to Windsurf settings:</p> <pre><code>// Split to multiple lines for readability\n{\n  \"ai.customInstructions\": \"Always read .context/CONSTITUTION.md first. \n  Check .context/TASKS.md for current work. \n  Follow patterns in .context/CONVENTIONS.md.\"\n}\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage_2","level":3,"title":"Usage","text":"<p>Context files appear in the file tree. Reference them when chatting:</p> <ul> <li>\"What's in our task list?\" → AI reads <code>.context/TASKS.md</code></li> <li>\"What convention do we use for naming?\" → AI reads <code>.context/CONVENTIONS.md</code></li> </ul>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#generic-integration","level":2,"title":"Generic Integration","text":"<p>For any AI tool that can read files, use these patterns:</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#manual-context-loading","level":3,"title":"Manual Context Loading","text":"<pre><code># Get full context\nctx load\n\n# Get AI-optimized packet\nctx agent --budget 8000\n\n# Get specific file\ncat .context/TASKS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#system-prompt-template","level":3,"title":"System Prompt Template","text":"<pre><code>You are working on a project with persistent context in .context/\n\nBefore responding:\n1. Read .context/CONSTITUTION.md - NEVER violate these rules\n2. Check .context/TASKS.md for current work\n3. Follow .context/CONVENTIONS.md patterns\n4. Reference .context/DECISIONS.md for architectural choices\n\nWhen you learn something new, note it for .context/LEARNINGS.md\nWhen you make a decision, document it for .context/DECISIONS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#automated-updates","level":3,"title":"Automated Updates","text":"<p>If your AI tool outputs to a log, use <code>ctx watch</code>:</p> <pre><code># Watch log file for context-update commands\nyour-ai-tool 2&gt;&amp;1 | tee /tmp/ai.log &amp;\nctx watch --log /tmp/ai.log\n</code></pre> <p>The AI can emit updates like:</p> <pre><code>&lt;context-update type=\"learning\"&gt;Important thing learned today&lt;/context-update&gt;\n&lt;context-update type=\"complete\"&gt;implement caching&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#context-update-commands","level":2,"title":"Context Update Commands","text":"<p>The <code>ctx watch</code> command parses update commands from AI output. Use this format:</p> <pre><code>&lt;context-update type=\"TYPE\" [attributes]&gt;Content&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#supported-types","level":3,"title":"Supported Types","text":"Type Target File Required Attributes <code>task</code> TASKS.md None <code>decision</code> DECISIONS.md <code>context</code>, <code>rationale</code>, <code>consequences</code> <code>learning</code> LEARNINGS.md <code>context</code>, <code>lesson</code>, <code>application</code> <code>convention</code> CONVENTIONS.md None <code>complete</code> TASKS.md None","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#simple-format-tasks-conventions-complete","level":3,"title":"Simple Format (tasks, conventions, complete)","text":"<pre><code>&lt;context-update type=\"task\"&gt;Implement rate limiting&lt;/context-update&gt;\n&lt;context-update type=\"convention\"&gt;Use kebab-case for files&lt;/context-update&gt;\n&lt;context-update type=\"complete\"&gt;rate limiting&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#structured-format-learnings-decisions","level":3,"title":"Structured Format (learnings, decisions)","text":"<p>Learnings and decisions support structured attributes for better documentation:</p> <p>Learning with full structure:</p> <pre><code>&lt;context-update type=\"learning\"\n  context=\"Debugging Claude Code hooks\"\n  lesson=\"Hooks receive JSON via stdin, not environment variables\"\n  application=\"Use jq to parse: COMMAND=$(echo $INPUT | jq -r .tool_input.command)\"\n&gt;Hook Input Format&lt;/context-update&gt;\n</code></pre> <p>Decision with full structure:</p> <pre><code>&lt;context-update type=\"decision\"\n  context=\"Need a caching layer for API responses\"\n  rationale=\"Redis is fast, well-supported, and team has experience\"\n  consequences=\"Must provision Redis infrastructure; team training on Redis patterns\"\n&gt;Use Redis for caching&lt;/context-update&gt;\n</code></pre> <p>If attributes are omitted, placeholders are inserted that should be updated manually.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#legacy-format-still-supported","level":3,"title":"Legacy Format (still supported)","text":"<p>Simple format without attributes still works but creates placeholder text:</p> <pre><code>&lt;context-update type=\"learning\"&gt;Mock functions must be hoisted&lt;/context-update&gt;\n&lt;context-update type=\"decision\"&gt;Use PostgreSQL for primary database&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage-with-ctx-watch","level":3,"title":"Usage with ctx watch","text":"<pre><code># Pipe AI output through watch\nyour-ai-tool | ctx watch\n\n# Or watch a log file\nctx watch --log /tmp/ai-output.log\n\n# Preview without applying\nctx watch --dry-run\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"prompting-guide/","level":1,"title":"Prompting Guide","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#prompting-guide","level":2,"title":"Prompting Guide","text":"<p>Effective prompts for working with AI assistants in <code>ctx</code>-enabled projects.</p> <p>Tip</p> <p>AI assistants may not automatically read context files.</p> <p>The right prompt triggers the right behavior. </p> <p>This guide documents prompts that reliably produce good results.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#session-start","level":2,"title":"Session Start","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#do-you-remember","level":3,"title":"\"Do you remember?\"","text":"<p>Triggers the AI to read <code>AGENT_PLAYBOOK</code>, <code>CONSTITUTION</code>,  <code>sessions/</code>, and other context files before responding.</p> <p>Use this during the start of every important session.</p> <pre><code>Do you remember what we were working on?\n</code></pre> <p>This question implies prior context exists. So, the AI checks files rather than admitting ignorance.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#whats-the-current-state","level":3,"title":"\"What's the current state?\"","text":"<p>Prompts reading of <code>TASKS.md</code>, recent sessions, and status overview.</p> <p>Use this when resuming work after a break.</p> <p>Variants:</p> <ul> <li>\"Where did we leave off?\"</li> <li>\"What's in progress?\"</li> <li>\"Show me the open tasks\"</li> </ul>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#during-work","level":2,"title":"During Work","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#why-doesnt-x-work","level":3,"title":"\"Why doesn't X work?\"","text":"<p>This triggers root cause analysis rather than surface-level fixes.</p> <p>Use this when something fails unexpectedly.</p> <p>Framing as \"why\" encourages investigation before action. The AI will trace  through code, check configurations, and identify the actual cause.</p> <p>Real Example</p> <p>\"Why can't I run /ctx-save?\" led to discovering missing permissions in settings.local.json bootstrapping—a fix that benefited all users.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#is-this-consistent-with-our-decisions","level":3,"title":"\"Is this consistent with our decisions?\"","text":"<p>This prompts checking <code>DECISIONS.md</code> before implementing.</p> <p>Use this before making architectural choices.</p> <p>Variants:</p> <ul> <li>\"Check if we've decided on this before\"</li> <li>\"Does this align with our conventions?\"</li> </ul>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-would-break-if-we","level":3,"title":"\"What would break if we...\"","text":"<p>This triggers defensive thinking and impact analysis.</p> <p>Use this before making significant changes.</p> <pre><code>What would break if we change the Settings struct?\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#before-you-start-read-x","level":3,"title":"\"Before you start, read X\"","text":"<p>This ensures specific context is loaded before work begins.</p> <p>Use this when you know the relevant context exists in a specific file.</p> <pre><code>Before you start, read .context/sessions/2026-01-20-auth-discussion.md\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#reflection-and-persistence","level":2,"title":"Reflection and Persistence","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-did-we-learn","level":3,"title":"\"What did we learn?\"","text":"<p>This prompts reflection on the session and often triggers adding learnings to <code>LEARNINGS.md</code>.</p> <p>Use this after completing a task or debugging session.</p> <p>This is an explicit reflection prompt. The AI will summarize insights and often offer to persist them.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#add-this-as-a-learningdecision","level":3,"title":"\"Add this as a learning/decision\"","text":"<p>This is an explicit persistence request.</p> <p>Use this when you have discovered something worth remembering.</p> <pre><code>Add this as a learning: \"JSON marshal escapes angle brackets by default\"\n\n# or simply.\nAdd this as a learning.\n# and let the AI autonomously infer and summarize.\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#save-context-before-we-end","level":3,"title":"\"Save context before we end\"","text":"<p>This triggers context persistence before the session closes.</p> <p>Use it at the end of the session or before switching topics.</p> <p>Variants:</p> <ul> <li>\"Let's persist what we did\"</li> <li>\"Update the context files\"</li> <li><code>/ctx-save</code> (slash command in Claude Code)</li> </ul>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#exploration-and-research","level":2,"title":"Exploration and Research","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#explore-the-codebase-for-x","level":3,"title":"\"Explore the codebase for X\"","text":"<p>This triggers thorough codebase search rather than guessing.</p> <p>Use this when you need to understand how something works.</p> <p>This works because \"Explore\" signals that investigation is needed,  not immediate action.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#how-does-x-work-in-this-codebase","level":3,"title":"\"How does X work in this codebase?\"","text":"<p>This prompts reading actual code rather than explaining general concepts.</p> <p>Use this to understand the existing implementation.</p> <pre><code>How does session saving work in this codebase?\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#find-all-places-where-x","level":3,"title":"\"Find all places where X\"","text":"<p>This triggers a comprehensive search across the codebase.</p> <p>Use this before refactoring or understanding the impact.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#meta-and-process","level":2,"title":"Meta and Process","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-should-we-document-from-this","level":3,"title":"\"What should we document from this?\"","text":"<p>This prompts identifying learnings, decisions, and conventions worth persisting.</p> <p>Use this after complex discussions or implementations.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#is-this-the-right-approach","level":3,"title":"\"Is this the right approach?\"","text":"<p>This invites the AI to challenge the current direction.</p> <p>Use this when you want a sanity check.</p> <p>This works because it allows AI to disagree.  AIs often default to agreeing; this prompt signals you want an  honest assessment.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-am-i-missing","level":3,"title":"\"What am I missing?\"","text":"<p>This prompts thinking about edge cases, overlooked requirements, or unconsidered approaches.</p> <p>Use this before finalizing a design or implementation.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#anti-patterns","level":2,"title":"Anti-Patterns","text":"<p>Based on our <code>ctx</code> development experience (i.e., \"sipping our own champagne\") so far, here are some prompts that tend to produce poor results:</p> Prompt Problem Better Alternative \"Fix this\" Too vague, may patch symptoms \"Why is this failing?\" \"Make it work\" Encourages quick hacks \"What's the right way to solve this?\" \"Just do it\" Skips planning \"Plan this, then implement\" \"You should remember\" Confrontational \"Do you remember?\" \"Obviously...\" Discourages questions State the requirement directly","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#quick-reference","level":2,"title":"Quick Reference","text":"Goal Prompt Load context \"Do you remember?\" Resume work \"What's the current state?\" Debug \"Why doesn't X work?\" Validate \"Is this consistent with our decisions?\" Impact analysis \"What would break if we...\" Reflect \"What did we learn?\" Persist \"Add this as a learning\" Explore \"How does X work in this codebase?\" Sanity check \"Is this the right approach?\" Completeness \"What am I missing?\"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#writing-tasks-as-prompts","level":2,"title":"Writing Tasks as Prompts","text":"<p>Tasks in <code>TASKS.md</code> are indirect prompts to the AI. How you write them shapes how the AI approaches the work.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#state-the-deliverable-not-just-steps","level":3,"title":"State the Deliverable, Not Just Steps","text":"<p>Bad task (implementation-focused): <pre><code>- [ ] T1.1.0: Parser system\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n</code></pre></p> <p>The AI may complete all subtasks but miss the actual goal. What does \"Parser system\" deliver to the user?</p> <p>Good task (deliverable-focused): <pre><code>- [ ] T1.1.0: Parser CLI command\n  **Deliverable**: `ctx recall list` command that shows parsed sessions\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n</code></pre></p> <p>Now the AI knows the subtasks serve a specific user-facing deliverable.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#use-acceptance-criteria","level":3,"title":"Use Acceptance Criteria","text":"<p>For complex tasks, add explicit \"done when\" criteria:</p> <pre><code>- [ ] T2.0: Authentication system\n  **Done when**:\n  - [ ] User can register with email\n  - [ ] User can log in and get a token\n  - [ ] Protected routes reject unauthenticated requests\n</code></pre> <p>This prevents premature \"task complete\" when only the implementation details are done but the feature doesn't actually work.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#subtasks-parent-task","level":3,"title":"Subtasks ≠ Parent Task","text":"<p>Completing all subtasks does not mean the parent task is complete.</p> <p>The parent task describes what the user gets. Subtasks describe how to build it.</p> <p>Always re-read the parent task description before marking it complete. Verify the stated deliverable exists and works.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#contributing","level":2,"title":"Contributing","text":"<p>Found a prompt that works well? Open an issue or PR with:</p> <ol> <li>The prompt text</li> <li>What behavior it triggers</li> <li>When to use it</li> <li>Why it works (optional but helpful)</li> </ol>","path":["Prompting Guide"],"tags":[]},{"location":"ralph-loop/","level":1,"title":"Ralph and Context","text":"","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#ralph-ctx","level":2,"title":"<code>ralph</code> + <code>ctx</code>","text":"<p>Like peanut butter and jelly: better together.</p> <p>The Ralph Wiggum technique is an iterative AI development workflow where  an agent works autonomously on tasks until completion. Context (<code>ctx</code>) and  Ralph complement each other perfectly:</p> <ul> <li><code>ctx</code> provides the memory: persistent context that survives across sessions</li> <li><code>ralph</code> provides the loop: autonomous iteration that runs until done</li> </ul> <p>Together, they enable fully autonomous AI development where the agent remembers  everything across iterations.</p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#how-it-works","level":2,"title":"How It Works","text":"<pre><code>graph TD\n    A[Start Loop] --&gt; B[Load PROMPT.md]\n    B --&gt; C[AI reads .context/]\n    C --&gt; D[AI picks task from TASKS.md]\n    D --&gt; E[AI completes task]\n    E --&gt; F[AI updates context files]\n    F --&gt; G[AI commits changes]\n    G --&gt; H{Check signals}\n    H --&gt;|SYSTEM_CONVERGED| I[Done - all tasks complete]\n    H --&gt;|SYSTEM_BLOCKED| J[Done - needs human input]\n    H --&gt;|Continue| B</code></pre> <ol> <li>Loop reads <code>PROMPT.md</code> and invokes AI</li> <li>AI loads context from <code>.context/</code></li> <li>AI picks one task and completes it</li> <li>AI updates context files (mark task done, add learnings)</li> <li>AI commits changes</li> <li>Loop checks for completion signals</li> <li>Repeat until converged or blocked</li> </ol>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#quick-start-with-claude-code","level":2,"title":"Quick Start with Claude Code","text":"<p>Claude Code has a built-in Ralph Loop plugin:</p> <pre><code># Start autonomous loop\n/ralph-loop\n\n# Cancel running loop\n/cancel-ralph\n</code></pre> <p>That's it. The loop will:</p> <ol> <li>Read your <code>PROMPT.md</code> for instructions</li> <li>Pick tasks from <code>.context/TASKS.md</code></li> <li>Work until <code>SYSTEM_CONVERGED</code> or <code>SYSTEM_BLOCKED</code></li> </ol>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#manual-loop-setup","level":2,"title":"Manual Loop Setup","text":"<p>For other AI tools, create a <code>loop.sh</code>:</p> <pre><code>#!/bin/bash\n# loop.sh — a minimal Ralph loop\n\nPROMPT_FILE=\"${1:-PROMPT.md}\"\nMAX_ITERATIONS=\"${2:-10}\"\nOUTPUT_FILE=\"/tmp/ralph_output.txt\"\n\nfor i in $(seq 1 $MAX_ITERATIONS); do\n  echo \"=== Iteration $i ===\"\n\n  # Invoke AI with prompt\n  cat \"$PROMPT_FILE\" | claude --print &gt; \"$OUTPUT_FILE\" 2&gt;&amp;1\n\n  # Display output\n  cat \"$OUTPUT_FILE\"\n\n  # Check for completion signals\n  if grep -q \"SYSTEM_CONVERGED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop complete: All tasks done\"\n    break\n  fi\n\n  if grep -q \"SYSTEM_BLOCKED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop blocked: Needs human input\"\n    break\n  fi\n\n  sleep 2\ndone\n</code></pre> <p>Make it executable and run:</p> <pre><code>chmod +x loop.sh\n./loop.sh\n</code></pre>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#the-promptmd-file","level":2,"title":"The PROMPT.md File","text":"<p>The prompt file instructs the AI on how to work autonomously. Here's a template:</p> <pre><code># Autonomous Development Prompt\n\nYou are working on this project autonomously. Follow these steps:\n\n## 1. Load Context\n\nRead these files in order:\n1. `.context/CONSTITUTION.md` — NEVER violate these rules\n2. `.context/TASKS.md` — Find work to do\n3. `.context/CONVENTIONS.md` — Follow these patterns\n4. `.context/DECISIONS.md` — Understand past choices\n\n## 2. Pick One Task\n\nFrom `.context/TASKS.md`, select ONE task that is:\n- Not blocked\n- Highest priority available\n- Within your capabilities\n\n## 3. Complete the Task\n\n- Write code following conventions\n- Run tests if applicable\n- Keep changes focused and minimal\n\n## 4. Update Context\n\nAfter completing work:\n- Mark task complete in TASKS.md\n- Add any learnings to LEARNINGS.md\n- Add any decisions to DECISIONS.md\n\n## 5. Commit Changes\n\nCreate a focused commit with clear message.\n\n## 6. Signal Status\n\nEnd your response with exactly ONE of:\n\n- `SYSTEM_CONVERGED` — All tasks in TASKS.md are complete\n- `SYSTEM_BLOCKED` — Cannot proceed, need human input (explain why)\n- (no signal) — More work remains, continue to next iteration\n\n## Rules\n\n- ONE task per iteration\n- NEVER skip tests\n- NEVER violate CONSTITUTION.md\n- Commit after each task\n</code></pre>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#completion-signals","level":2,"title":"Completion Signals","text":"<p>The loop watches for these signals in AI output:</p> Signal Meaning When to Use <code>SYSTEM_CONVERGED</code> All tasks complete No pending tasks in TASKS.md <code>SYSTEM_BLOCKED</code> Cannot proceed Needs clarification, access, or decision <code>BOOTSTRAP_COMPLETE</code> Initial setup done Project scaffolding finished","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#example-usage","level":3,"title":"Example Usage","text":"<pre><code>I've completed all tasks in TASKS.md:\n- [x] Set up project structure\n- [x] Implement core API\n- [x] Add authentication\n- [x] Write tests\n\nNo pending tasks remain.\n\nSYSTEM_CONVERGED\n</code></pre> <pre><code>I cannot proceed with the \"Deploy to production\" task because:\n- Missing AWS credentials\n- Need confirmation on region selection\n\nPlease provide credentials and confirm deployment region.\n\nSYSTEM_BLOCKED\n</code></pre>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#context-integration","level":2,"title":"Context Integration","text":"","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#why-ctx-ralph-work-well-together","level":3,"title":"Why ctx + Ralph Work Well Together","text":"Without ctx With ctx Each iteration starts fresh Each iteration has full history Decisions get re-made Decisions persist in DECISIONS.md Learnings are lost Learnings accumulate in LEARNINGS.md Tasks can be forgotten Tasks tracked in TASKS.md","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#automatic-context-updates","level":3,"title":"Automatic Context Updates","text":"<p>During the loop, the AI should update context files:</p> <p>Mark task complete: <pre><code>ctx complete \"implement user auth\"\n</code></pre></p> <p>Or emit an update command (parsed by <code>ctx watch</code>): <pre><code>&lt;context-update type=\"complete\"&gt;user auth&lt;/context-update&gt;\n</code></pre></p> <p>Add learning: <pre><code>ctx add learning \"Rate limiting requires Redis connection\"\n</code></pre></p> <p>Or via update command: <pre><code>&lt;context-update type=\"learning\"&gt;Rate limiting requires Redis connection&lt;/context-update&gt;\n</code></pre></p> <p>Record decision: <pre><code>ctx add decision \"Use JWT tokens for API authentication\"\n</code></pre></p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#advanced-watch-mode","level":2,"title":"Advanced: Watch Mode","text":"<p>Run <code>ctx watch</code> alongside the loop to automatically process context updates:</p> <pre><code># Terminal 1: Run the loop\n./loop.sh 2&gt;&amp;1 | tee /tmp/loop.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/loop.log --auto-save\n</code></pre> <p>The <code>--auto-save</code> flag periodically saves session snapshots, creating a  history of the loop's progress.</p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#example-project-setup","level":2,"title":"Example Project Setup","text":"<pre><code>my-project/\n├── .context/\n│   ├── CONSTITUTION.md\n│   ├── TASKS.md          # Work items for the loop\n│   ├── DECISIONS.md\n│   ├── LEARNINGS.md\n│   ├── CONVENTIONS.md\n│   └── sessions/         # Loop iteration history\n├── PROMPT.md             # Instructions for the AI\n├── loop.sh               # Loop script (if not using Claude Code)\n└── src/                  # Your code\n</code></pre>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#sample-tasksmd-for-ralph","level":3,"title":"Sample TASKS.md for Ralph","text":"<pre><code># Tasks\n\n## Phase 1: Setup\n\n- [x] Initialize project structure\n- [x] Set up testing framework\n\n## Phase 2: Core Features\n\n- [ ] Implement user registration `#priority:high`\n- [ ] Add email verification `#priority:high`\n- [ ] Create password reset flow `#priority:medium`\n\n## Phase 3: Polish\n\n- [ ] Add rate limiting `#priority:medium`\n- [ ] Improve error messages `#priority:low`\n</code></pre> <p>The loop will work through these systematically, marking each complete.</p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#troubleshooting","level":2,"title":"Troubleshooting","text":"","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#loop-runs-forever","level":3,"title":"Loop Runs Forever","text":"<p>Cause: AI not emitting completion signals</p> <p>Fix: Ensure PROMPT.md explicitly instructs signaling: <pre><code>End EVERY response with one of:\n- SYSTEM_CONVERGED (if all tasks done)\n- SYSTEM_BLOCKED (if stuck)\n</code></pre></p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#context-not-persisting","level":3,"title":"Context Not Persisting","text":"<p>Cause: AI not updating context files</p> <p>Fix: Add explicit instructions to PROMPT.md: <pre><code>After completing a task, you MUST:\n1. Run: ctx complete \"&lt;task&gt;\"\n2. Add learnings: ctx add learning \"...\"\n</code></pre></p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#tasks-getting-repeated","level":3,"title":"Tasks Getting Repeated","text":"<p>Cause: Task not marked complete before next iteration</p> <p>Fix: Ensure commit happens after context update: <pre><code>Order of operations:\n1. Complete coding work\n2. Update context files (ctx complete, ctx add)\n3. Commit ALL changes including .context/\n4. Then signal status\n</code></pre></p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#ai-violating-constitution","level":3,"title":"AI Violating Constitution","text":"<p>Cause: Constitution not read first</p> <p>Fix: Make constitution check explicit in PROMPT.md: <pre><code>BEFORE any work:\n1. Read .context/CONSTITUTION.md\n2. If task would violate ANY rule, emit SYSTEM_BLOCKED\n3. Explain which rule prevents the work\n</code></pre></p>","path":["Ralph and Context"],"tags":[]},{"location":"ralph-loop/#resources","level":2,"title":"Resources","text":"<ul> <li>Ralph Wiggum Technique — Original blog post</li> <li>Context CLI — Command reference</li> <li>Integrations — Tool-specific setup</li> </ul>","path":["Ralph and Context"],"tags":[]},{"location":"security/","level":1,"title":"Security","text":"","path":["Security"],"tags":[]},{"location":"security/#reporting-vulnerabilities","level":2,"title":"Reporting Vulnerabilities","text":"<p>At <code>ctx</code> we take security very seriously.</p> <p>If you discover a security vulnerability in <code>ctx</code>, please report it responsibly.</p> <p>Do NOT open a public issue for security vulnerabilities.</p>","path":["Security"],"tags":[]},{"location":"security/#email","level":3,"title":"Email","text":"<p>Send details to security@ctx.ist</p>","path":["Security"],"tags":[]},{"location":"security/#github-private-reporting","level":3,"title":"GitHub Private Reporting","text":"<ol> <li>Go to the Security tab</li> <li>Click \"Report a vulnerability\"</li> <li>Provide a detailed description</li> </ol>","path":["Security"],"tags":[]},{"location":"security/#what-to-include","level":3,"title":"What to Include","text":"<ul> <li>Description of the vulnerability</li> <li>Steps to reproduce</li> <li>Potential impact</li> <li>Suggested fix (if any)</li> </ul>","path":["Security"],"tags":[]},{"location":"security/#response-timeline","level":3,"title":"Response Timeline","text":"Stage Timeframe Acknowledgment Within 48 hours Initial assessment Within 7 days Resolution target Within 30 days (depending on severity)","path":["Security"],"tags":[]},{"location":"security/#security-design","level":2,"title":"Security Design","text":"<p><code>ctx</code> is designed with security in mind:</p> <ul> <li>No secrets in context: The constitution explicitly forbids storing   secrets, tokens, API keys, or credentials in <code>.context/</code> files</li> <li>Local only: ctx runs entirely locally with no external network calls</li> <li>No code execution: ctx reads and writes Markdown files only; it does    not execute arbitrary code</li> <li>Git-tracked: All context files are meant to be committed, so they should   never contain sensitive data</li> </ul>","path":["Security"],"tags":[]},{"location":"security/#best-practices","level":2,"title":"Best Practices","text":"<ol> <li>Review before committing: Always review <code>.context/</code> files before committing</li> <li>Use .gitignore: If you must store sensitive notes locally,    add them to <code>.gitignore</code></li> <li>Drift detection: Run <code>ctx drift</code> to check for potential issues</li> </ol>","path":["Security"],"tags":[]},{"location":"security/#attribution","level":2,"title":"Attribution","text":"<p>We appreciate responsible disclosure and will acknowledge security researchers who report valid vulnerabilities (unless they prefer to remain anonymous).</p>","path":["Security"],"tags":[]},{"location":"versions/","level":1,"title":"Version History","text":"<p>Documentation snapshots for each release. Click a version to view the  docs as they were at that release.</p>","path":["Version History"],"tags":[]},{"location":"versions/#releases","level":2,"title":"Releases","text":"Version Release Date Documentation v0.1.2 2026-01-27 View docs v0.1.1 2026-01-26 View docs v0.1.0 2026-01-25 View docs","path":["Version History"],"tags":[]},{"location":"versions/#latest","level":2,"title":"Latest","text":"<p>The main documentation always reflects the latest development version.</p> <p>For the most recent stable release, see  v0.1.2.</p>","path":["Version History"],"tags":[]},{"location":"versions/#changelog","level":2,"title":"Changelog","text":"<p>For detailed changes between versions, see the  GitHub Releases page.</p>","path":["Version History"],"tags":[]},{"location":"blog/","level":1,"title":"Blog","text":"<p>Stories, insights, and lessons learned from building and using ctx.</p>","path":["Blog"],"tags":[]},{"location":"blog/#posts","level":2,"title":"Posts","text":"","path":["Blog"],"tags":[]},{"location":"blog/#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development","level":3,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"<p>January 27, 2026</p> <p>What happens when you build a tool designed to give AI memory, using that very same tool to remember what you're building? This is the story of ctx—how it evolved from a hasty \"YOLO mode\" experiment to a disciplined system for persistent AI context, and what we learned along the way.</p> <p>Topics: dogfooding, AI-assisted development, Ralph Loop, session persistence, architectural decisions</p> <p>More posts coming soon.</p>","path":["Blog"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/","level":1,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"<p>Jose Alekhinne / 2026-01-27</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development","level":1,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"<p>What happens when you build a tool designed to give AI memory, using that very  same tool to remember what you are building? </p> <p>This is the story of <code>ctx</code>, how it evolved from a hasty \"YOLO mode\" experiment  to a disciplined system for persistent AI context, and what I have  learned along the way.</p> <p>Context is a Record</p> <p>Context is a persistent record.</p> <p>By \"context\", I don’t mean model memory or stored thoughts: </p> <p>I mean the durable record of decisions, learnings, and intent  that normally evaporates between sessions.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#ai-amnesia","level":2,"title":"AI Amnesia","text":"<p>Every developer who works with AI code generators knows the frustration:  you have a deep, productive session where the AI understands your codebase,  your conventions, your decisions. And then you close the terminal. </p> <p>Tomorrow it's a blank slate. The AI has forgotten everything.</p> <p>That is \"reset amnesia\", and it's not just annoying: it's expensive. </p> <p>Every session starts with re-explaining context, re-reading files,  re-discovering decisions that were already made.</p> <p>\"I don't want to lose this discussion...  I am a brain-dead developer YOLO'ing my way out\"</p> <p>That's exactly what I said to Claude when I first started working on <code>ctx</code>.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-genesis","level":2,"title":"The Genesis","text":"<p>The project started as \"Active Memory\" (<code>amem</code>): a CLI tool to persist AI  context across sessions. </p> <p>The core idea was simple: create a <code>.context/</code> directory with structured  Markdown files for decisions, learnings, tasks, and conventions.  The AI reads these at session start and writes to them before the session ends.</p> <p>The first commit was just scaffolding. But within hours, the  Ralph Loop—an iterative AI development workflow—had produced a working CLI:</p> <pre><code>feat(cli): implement amem init command\nfeat(cli): implement amem status command\nfeat(cli): implement amem add command\nfeat(cli): implement amem agent command\n...\n</code></pre> <p>Fourteen core commands shipped in rapid succession. </p> <p>I was YOLO'ing like there was no tomorrow: auto-accept every change, let the AI run free, ship features fast.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-meta-experiment-using-amem-to-build-amem","level":2,"title":"The Meta-Experiment: Using <code>amem</code> to Build <code>amem</code>","text":"<p>Here's where it gets interesting: On January 20<sup>th</sup>, I asked: </p> <p>\"Can I use <code>amem</code> to help you remember this context when I restart?\"</p> <p>The answer was yes—but with a gap: </p> <p>Auto-load worked (via Claude Code's <code>PreToolUse</code> hook), but auto-save was  missing. If the user quit with Ctrl+C, everything since the last manual save  was lost.</p> <p>That session became the first real test of the system. </p> <p>Here is the first session file we recorded:</p> <pre><code>## Key Discussion Points\n\n### 1. amem vs Ralph Loop - They're Separate Systems\n\n**User's question**: \"How do I use the binary to recreate this project?\"\n\n**Answer discovered**: amem is for context management, Ralph Loop is for \ndevelopment workflow. They're complementary but separate.\n\n### 2. Two Tiers of Context Persistence\n\n| Tier      | What                        | Why                           | Where                  |\n|-----------|-----------------------------|-------------------------------|------------------------|\n| Curated   | Learnings, decisions, tasks | Quick reload, token-efficient | .context/*.md          |\n| Full dump | Entire conversation         | Safety net, nothing lost      | .context/sessions/*.md |\n</code></pre> <p>This session file—written by the AI to preserve its own context—became the  template for how <code>ctx</code> handles session persistence.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-rename","level":2,"title":"The Rename","text":"<p>By January 21<sup>st</sup>, I realized \"Active Memory\" was too generic, and (arguably) too marketing-smelly. </p> <p>Besides, the binary was already called <code>ctx</code> (short for Context),  the directory was <code>.context/</code>, and the slash commands would be <code>/ctx-*</code>. </p> <p>So it followed that the project should be renamed to <code>ctx</code> to make things  make sense.</p> <p>The rename touched 100+ files but was clean—a find-and-replace with Go's  type system catching any misses.</p> <p>The git history tells the story:</p> <pre><code>0e8f6bb feat: rename amem to ctx and add Claude Code integration\n87dcfa1 README.\n4f0e195 feat: separate orchestrator directive from agent tasks\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#yolo-mode-fast-but-dangerous","level":2,"title":"YOLO Mode: Fast, But Dangerous","text":"<p>The Ralph Loop made feature development incredibly fast. </p> <p>But it created technical debt that I didn't notice until later.</p> <p>A comparison session on January 25<sup>th</sup> revealed the patterns:</p> YOLO Pattern What We Found <code>\"TASKS.md\"</code> scattered in 10 files Same string literal everywhere, no constants <code>dir + \"/\" + file</code> Should be <code>filepath.Join()</code> Monolithic <code>cli_test.go</code> (1500+ lines) Tests disconnected from implementations <code>package initcmd</code> in <code>init/</code> folder Go's \"init\" is reserved—subtle naming collision <p>Here is another analysis made by <code>ctx</code>:</p> <pre><code>● Based on my analysis, here are the key differences:\n\nYOLO Mode (Pre-040ce99)\n- Feature-first: Added slash commands, tests, templates rapidly\n- Scattered magic strings: \"TASKS.md\", \"decision\", \".context\" spread across files\n- Quick file creation: New files without organizational patterns\n- Working but inconsistent: Code functioned but lacked systematic structure\n\nHuman-Guided Mode (Post-040ce99)\n- Consolidation focus: Centralized constants in config package\n- Consistent naming: Dir, File, Filename, UpdateType prefixes\n- Self-referential constants: FileType map uses constants as keys, not literals\n- Proper path construction: filepath.Join() instead of +\"/\"+\n- Colocated tests: Tests next to implementations\n- Canonical naming: Package name = folder name\n</code></pre> <p>The fix required a human-guided refactoring session.</p> <p>We introduced <code>internal/config/config.go</code> with semantic prefixes:</p> <pre><code>const (\n    DirContext     = \".context\"\n    DirArchive     = \"archive\"\n    DirSessions    = \"sessions\"\n    FilenameTask   = \"TASKS.md\"\n    UpdateTypeTask = \"task\"\n)\n</code></pre> <p>What I begrudgingly learned was:  YOLO mode is effective for velocity but accumulates debt. </p> <p>So I took a mental note to schedule periodic consolidation sessions  from that point onward.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-dogfooding-test-that-failed","level":2,"title":"The Dogfooding Test That Failed","text":"<p>On January 21<sup>st</sup>, I ran an experiment: have another Claude instance rebuild  <code>ctx</code> from scratch using only the specs and <code>PROMPT.md</code>. </p> <p>The Ralph Loop ran, all tasks got checked off, the loop exited successfully.</p> <p>But the binary was broken!</p> <p>Commands just printed help text instead of executing. </p> <p>All tasks were marked \"complete\" but the implementation didn't work.</p> <p>Here's what <code>ctx</code> discovered:</p> <pre><code>## Key Findings\n\n### Dogfooding Binary Is Broken\n- Commands don't execute — they just print root help text\n- All tasks were marked complete but binary doesn't work\n- Lesson: \"tasks checked off\" ≠ \"implementation works\"\n</code></pre> <p>This was humbling—to say the least.</p> <p>I realized, I had the same blind spot in my own codebase: no integration tests that actually invoked the binary. </p> <p>So I added:</p> <ul> <li>Integration tests for all commands</li> <li>Coverage targets (60-80% per package)</li> <li>Smoke tests in CI</li> <li>A constitution rule: \"All code must pass tests before commit\"</li> </ul>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-constitution-versus-conventions","level":2,"title":"The Constitution versus Conventions","text":"<p>As lessons accumulated, there was the temptation to add everything to  <code>CONSTITUTION.md</code> as \"inviolable rules\". </p> <p>But I resisted.</p> <p>The constitution should contain only truly inviolable invariants:</p> <ul> <li>Security (no secrets, no customer data)</li> <li>Quality (tests must pass)</li> <li>Process (decisions need records)</li> <li><code>ctx</code> invocation (always use <code>PATH</code>, never fallback)</li> </ul> <p>Everything else—coding style, file organization, naming  conventions—should go in to <code>CONVENTIONS.md</code>. </p> <p>Here's how <code>ctx</code> explained why the distinction was important: </p> <p>\"Overly strict constitution creates friction and gets ignored.  Conventions can be bent; constitution cannot.\" — Decision record, 2026-01-25</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#hooks-harder-than-they-look","level":2,"title":"Hooks: Harder Than They Look","text":"<p>Claude Code hooks seemed simple: run a script before/after certain events. </p> <p>But I hit multiple gotchas:</p> <p>1. Key names matter</p> <pre><code>// WRONG - \"Invalid key in record\" error\n\"PreToolUseHooks\": [...]\n\n// RIGHT\n\"PreToolUse\": [...]\n</code></pre> <p>2. Blocking requires specific output</p> <pre><code># WRONG - just exits, doesn't block\nexit 1\n\n# RIGHT - JSON output + exit 0\necho '{\"decision\": \"block\", \"reason\": \"Use ctx from PATH\"}'\nexit 0\n</code></pre> <p>3. Go's JSON escaping</p> <p><code>json.Marshal</code> escapes <code>&gt;</code>, <code>&lt;</code>, <code>&amp;</code> as unicode (<code>\\u003e</code>) by default. </p> <p>When generating shell commands in JSON:</p> <pre><code>encoder := json.NewEncoder(file)\nencoder.SetEscapeHTML(false) // Prevent 2&gt;/dev/null → 2\\u003e/dev/null\n</code></pre> <p>4. Regex overfitting</p> <p>Our hook to block non-PATH <code>ctx</code> invocations initially matched too broadly:</p> <pre><code># WRONG - matches /home/user/ctx/internal/file.go (ctx as directory)\n(/home/|/tmp/|/var/)[^ ]*ctx[^ ]*\n\n# RIGHT - matches ctx as binary only\n(/home/|/tmp/|/var/)[^ ]*/ctx( |$)\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-session-files","level":2,"title":"The Session Files","text":"<p>By the time of this writing this project's <code>ctx</code> sessions (<code>.context/sessions/</code>)  contains 40+ files from this project's development.</p> <p>They are not part of the source code due to security, privacy, and size concerns.</p> <p>However, they are invaluable for the project's progress.</p> <p>Each session file is a timestamped Markdown with:</p> <ul> <li>Summary of what has been accomplished</li> <li>Key decisions made</li> <li>Learnings discovered</li> <li>Tasks for the next session</li> <li>Technical context (platform, versions)</li> </ul> <p>These files are not auto-loaded (that would bust the token budget). </p> <p>They are what I see as the \"archaeological record\" of <code>ctx</code>: When the AI needs deeper information about why something was done, it digs into the sessions.</p> <p>Auto-generated session files use a naming convention:</p> <pre><code>2026-01-23-115432-session-prompt_input_exit-summary.md\n2026-01-25-220244-manual-save.md\n2026-01-27-052107-session-other-summary.md\n</code></pre> <p>Also, the <code>SessionEnd</code> hook captures transcripts automatically.  Even <code>Ctrl+C</code>is caught.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-decision-log-18-architectural-decisions","level":2,"title":"The Decision Log: 18 Architectural Decisions","text":"<p><code>ctx</code> helps record every significant architectural choice in  <code>.context/DECISIONS.md</code>. </p> <p>Here are some highlights:</p> <p>Reverse-chronological order (2026-01-27)</p> <pre><code>**Context**: With chronological order, oldest items consume tokens first, and\nnewest (most relevant) items risk being truncated.\n\n**Decision**: Use reverse-chronological order (newest first) for DECISIONS.md\nand LEARNINGS.md.\n</code></pre> <p>PATH over hardcoded paths (2026-01-21)</p> <pre><code>**Context**: Original implementation hardcoded absolute paths in hooks.\nThis breaks when sharing configs with other developers.\n\n**Decision**: Hooks use `ctx` from PATH. `ctx init` checks PATH before proceeding.\n</code></pre> <p>Generic core with Claude enhancements (2026-01-20)</p> <pre><code>**Context**: ctx should work with any AI tool, but Claude Code users could\nbenefit from deeper integration.\n\n**Decision**: Keep ctx generic as the core tool, but provide optional\nClaude Code-specific enhancements.\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-learning-log-24-gotchas-and-insights","level":2,"title":"The Learning Log: 24 Gotchas and Insights","text":"<p>The <code>.context/LEARNINGS.md</code> file captures gotchas that would otherwise be  forgotten. Each has Context, Lesson, and Application sections:</p> <p>CGO on ARM64</p> <pre><code>**Context**: `go test` failed with `gcc: error: unrecognized command-line option '-m64'`\n**Lesson**: On ARM64 Linux, CGO causes cross-compilation issues. Always use `CGO_ENABLED=0`.\n</code></pre> <p>Claude Code skills format</p> <pre><code>**Lesson**: Claude Code skills are Markdown files in .claude/commands/ with `YAML`\nfrontmatter (*description, argument-hint, allowed-tools*). Body is the prompt.\n</code></pre> <p>\"Do you remember?\" handling</p> <pre><code>**Lesson**: In a `ctx`-enabled project, \"*do you remember?*\" has an obvious meaning:\ncheck the `.context/` files. Don't ask for clarification—just do it.\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#task-archives-the-completed-work","level":2,"title":"Task Archives: The Completed Work","text":"<p>Completed tasks are archived to <code>.context/archive/</code> with timestamps. </p> <p>The archive from January 23<sup>rd</sup> shows 13 phases of work:</p> <ul> <li>Phase 1: Project Scaffolding (Go module, Cobra CLI)</li> <li>Phase 2-4: Core Commands    (init, status, agent, add, complete, drift, sync, compact, watch, hook)</li> <li>Phase 5: Session Management (save, list, load, parse, --extract)</li> <li>Phase 6: Claude Code Integration (hooks, settings, CLAUDE.md handling)</li> <li>Phase 7: Testing &amp; Verification</li> <li>Phase 8: Task Archival</li> <li>Phase 9: Slash Commands</li> <li>Phase 9b: Ralph Loop Integration</li> <li>Phase 10: Project Rename</li> <li>Phase 11: Documentation</li> <li>Phase 12: Timestamp Correlation</li> <li>Phase 13: Rich Context Entries</li> </ul> <p>That's an impressive 173 commits across 8 days of development.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#what-i-learned-about-ai-assisted-development","level":2,"title":"What I Learned About AI-Assisted Development","text":"<p>1. Memory changes everything</p> <p>When the AI remembers decisions, it doesn't repeat mistakes. When it knows  your conventions, it follows them. </p> <p><code>ctx</code> makes the AI a better collaborator because it's not starting from zero.</p> <p>2. Two-tier persistence works</p> <p>Curated context (<code>DECISIONS.md</code>, <code>LEARNINGS.md</code>, <code>TASKS.md</code>) is for  quick reload. </p> <p>Full session dumps are for archaeology. </p> <p>It's a futile effort to try to fit everything in the token budget.</p> <p>Persist more, load less.</p> <p>3. YOLO mode has its place</p> <p>For rapid prototyping, letting the AI run free is effective. </p> <p>But I had to schedule consolidation sessions. </p> <p>Technical debt accumulates silently.</p> <p>4. The constitution should be small</p> <p>Only truly inviolable rules go in <code>CONSTITUTION.md</code>.  Everything else is a convention. </p> <p>If you put too much in the constitution, it will get ignored.</p> <p>5. Verification is non-negotiable</p> <p>\"All tasks complete\" means nothing if you haven't run the tests. </p> <p>Integration tests that invoke the actual binary caught bugs that  the unit tests missed.</p> <p>6. Session files are underrated</p> <p>The ability to grep through 40 session files and find exactly when and why a  decision was made helped me a lot. </p> <p>It's not about loading them into context: It is about having them when you  need them.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-future-recall-system","level":2,"title":"The Future: Recall System","text":"<p>The next phase of <code>ctx</code> is the Recall System:</p> <ul> <li>Parser: Parse session capture markdowns, enrich with JSONL data</li> <li>Renderer: Goldmark + Chroma for syntax highlighting, dark mode UI</li> <li>Server: Local HTTP server for browsing sessions</li> <li>Search: Inverted index for searching across sessions</li> <li>CLI: <code>ctx recall serve &lt;path&gt;</code> to start the server</li> </ul> <p>The goal is to make the archaeological record browsable—not just <code>grep</code>-able.</p> <p>Because not everyone always lives in the terminal—me included.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#conclusion","level":2,"title":"Conclusion","text":"<p>Building <code>ctx</code> using ctx was a meta-experiment in AI-assisted development. </p> <p>I learned that memory isn't just convenient—it's transformative:</p> <ul> <li>An AI that remembers your decisions doesn't repeat mistakes.</li> <li>An AI that knows your conventions doesn't need them re-explained.</li> </ul> <p>If you are reading this, chances are that you already have heard about <code>ctx</code>.</p> <ul> <li><code>ctx</code> is open source at  github.com/ActiveMemory/ctx,</li> <li>and the documentation lives at ctx.ist.</li> </ul> <p>If you're a mere mortal tired of reset amnesia, give <code>ctx</code> a try. </p> <p>And when you do, check <code>.context/sessions/</code> sometime. </p> <p>The archaeological record might surprise you.</p> <p>This blog post was written with the help of <code>ctx</code> with full access to the  <code>ctx</code> session files, decision log, learning log, task archives, and  git history of <code>ctx</code>—The meta continues.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]}]}
\ No newline at end of file
+{"config":{"separator":"[\\s\\-_,:!=\\[\\]()\\\\\"`/]+|\\.(?!\\d)"},"items":[{"location":"","level":1,"title":"Getting Started","text":"","path":["Getting Started"],"tags":[]},{"location":"#ctx","level":2,"title":"<code>ctx</code>","text":"<p><code>ctx</code> (Context) is a file-based system that enables AI coding assistants to persist project knowledge across sessions. Instead of re-explaining your codebase every time, context files let AI tools remember decisions, conventions, and learnings:</p> <ul> <li>A session is interactive.</li> <li><code>ctx</code> enables cognitive continuity.</li> <li>Cognitive continuity enables durable, symbiotic-like human–AI workflows.</li> </ul>","path":["Getting Started"],"tags":[]},{"location":"#community","level":2,"title":"Community","text":"<p>Open source is better together.</p> <p>⭐️ If the idea behind <code>ctx</code> resonates, a star helps it reach engineers who run into context drift every day.</p> <p>→ https://github.com/ActiveMemory/ctx</p> <p>Join the community to ask questions, share feedback, and connect with other users:</p> <ul> <li> Discord:   Chat, get help, share your workflows</li> <li> GitHub:   Star the repo, report issues, contribute</li> </ul>","path":["Getting Started"],"tags":[]},{"location":"#why","level":2,"title":"Why?","text":"<p>Most AI-driven development fails not because models are weak—they fail because  context is ephemeral. Every new session starts near zero:</p> <ul> <li>You re-explain architecture</li> <li>The AI repeats past mistakes</li> <li>Decisions get rediscovered instead of remembered</li> </ul> <p><code>ctx</code> solves this by treating context as infrastructure:  files that version with your code and persist across sessions.</p>","path":["Getting Started"],"tags":[]},{"location":"#installation","level":2,"title":"Installation","text":"","path":["Getting Started"],"tags":[]},{"location":"#binary-downloads-recommended","level":3,"title":"Binary Downloads (Recommended)","text":"<p>Download pre-built binaries from the  releases page.</p> Linux (x86_64)Linux (ARM64)macOS (Apple Silicon)macOS (Intel)Windows <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-linux-amd64\nchmod +x ctx-0.1.2-linux-amd64\nsudo mv ctx-0.1.2-linux-amd64 /usr/local/bin/ctx\n</code></pre> <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-linux-arm64\nchmod +x ctx-0.1.2-linux-arm64\nsudo mv ctx-0.1.2-linux-arm64 /usr/local/bin/ctx\n</code></pre> <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-darwin-arm64\nchmod +x ctx-0.1.2-darwin-arm64\nsudo mv ctx-0.1.2-darwin-arm64 /usr/local/bin/ctx\n</code></pre> <pre><code>curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-darwin-amd64\nchmod +x ctx-0.1.2-darwin-amd64\nsudo mv ctx-0.1.2-darwin-amd64 /usr/local/bin/ctx\n</code></pre> <p>Download <code>ctx-0.1.2-windows-amd64.exe</code> from the releases page and add it to your <code>PATH</code>.</p>","path":["Getting Started"],"tags":[]},{"location":"#verifying-checksums","level":3,"title":"Verifying Checksums","text":"<p>Each binary has a corresponding <code>.sha256</code> checksum file. To verify your download:</p> <pre><code># Download the checksum file\ncurl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.2/ctx-0.1.2-linux-amd64.sha256\n\n# Verify the binary\nsha256sum -c ctx-0.1.2-linux-amd64.sha256\n</code></pre> <p>On macOS, use <code>shasum -a 256 -c</code> instead of <code>sha256sum -c</code>.</p>","path":["Getting Started"],"tags":[]},{"location":"#build-from-source","level":3,"title":"Build from Source","text":"<p>Building from the source gives you the latest features and bug fixes; however, it also means you will be using an unreleased version of <code>ctx</code> that has not been fully tested.</p> <p>Want to help test the latest features?</p> <p>If you like living on the edge and want to test the latest features  before they are released, then building from source is the way to go.</p> <p>Requires Go 1.25+:</p> <pre><code>git clone https://github.com/ActiveMemory/ctx.git\ncd ctx\nmake build\nsudo make install\n# or:\n# sudo mv ctx /usr/local/bin/\n</code></pre> <p>Verify installation:</p> <pre><code>ctx --version\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#quick-start","level":2,"title":"Quick Start","text":"","path":["Getting Started"],"tags":[]},{"location":"#1-initialize-context","level":3,"title":"1. Initialize Context","text":"<pre><code>cd your-project\nctx init\n</code></pre> <p>This creates a <code>.context/</code> directory with template files and configures  AI tool hooks (for Claude Code).</p>","path":["Getting Started"],"tags":[]},{"location":"#2-check-status","level":3,"title":"2. Check Status","text":"<pre><code>ctx status\n</code></pre> <p>Shows context summary: files present, token estimate, and recent activity.</p>","path":["Getting Started"],"tags":[]},{"location":"#3-start-using-with-ai","level":3,"title":"3. Start Using with AI","text":"<p>With Claude Code, context loads automatically via hooks. For other tools, paste the output of:</p> <pre><code>ctx agent --budget 8000\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#4-verify-it-works","level":3,"title":"4. Verify It Works","text":"<p>Ask your AI: \"Do you remember?\"</p> <p>It should cite specific context: current tasks, recent decisions,  or previous session topics.</p>","path":["Getting Started"],"tags":[]},{"location":"#what-gets-created","level":2,"title":"What Gets Created","text":"<pre><code>.context/\n├── CONSTITUTION.md     # Hard rules — NEVER violate these\n├── TASKS.md            # Current and planned work\n├── CONVENTIONS.md      # Project patterns and standards\n├── ARCHITECTURE.md     # System overview\n├── DECISIONS.md        # Architectural decisions with rationale\n├── LEARNINGS.md        # Lessons learned, gotchas, tips\n├── GLOSSARY.md         # Domain terms and abbreviations\n├── DRIFT.md            # Staleness signals\n├── AGENT_PLAYBOOK.md   # How AI tools should use this\n└── sessions/           # Session snapshots\n\n.claude/                # Claude Code integration (if detected)\n├── hooks/              # Auto-save and enforcement scripts\n├── commands/           # ctx slash command definitions\n└── settings.local.json # Hook configuration\n</code></pre> <p>See Context Files for detailed documentation of each file.</p>","path":["Getting Started"],"tags":[]},{"location":"#common-workflows","level":2,"title":"Common Workflows","text":"","path":["Getting Started"],"tags":[]},{"location":"#add-a-task","level":3,"title":"Add a Task","text":"<pre><code>ctx add task \"Implement user authentication\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#record-a-decision","level":3,"title":"Record a Decision","text":"<pre><code>ctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequences \"Team needs PostgreSQL training\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#note-a-learning","level":3,"title":"Note a Learning","text":"<pre><code>ctx add learning \"Mock functions must be hoisted in Jest\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Jest hoists mock calls to top of file\" \\\n  --application \"Place jest.mock() before imports\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#mark-task-complete","level":3,"title":"Mark Task Complete","text":"<pre><code>ctx complete \"user auth\"\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#check-for-stale-context","level":3,"title":"Check for Stale Context","text":"<pre><code>ctx drift\n</code></pre>","path":["Getting Started"],"tags":[]},{"location":"#next-steps","level":2,"title":"Next Steps","text":"<ul> <li>Prompting Guide — Effective prompts for AI sessions</li> <li>CLI Reference — All commands and options</li> <li>Context Files — File formats and structure</li> <li>Autonomous Loops — Iterative AI development workflows</li> <li>Integrations — Setup for Claude Code, Cursor, Aider</li> </ul>","path":["Getting Started"],"tags":[]},{"location":"autonomous-loop/","level":1,"title":"Autonomous Loops","text":"","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#autonomous-ai-development","level":2,"title":"Autonomous AI Development","text":"<p>Iterate until done.</p> <p>An autonomous loop is an iterative AI development workflow where an agent works on tasks until completion—without constant human intervention. Context (<code>ctx</code>) provides the memory that makes this possible:</p> <ul> <li><code>ctx</code> provides the memory: persistent context that survives across iterations</li> <li>The loop provides the automation: continuous execution until done</li> </ul> <p>Together, they enable fully autonomous AI development where the agent remembers everything across iterations.</p> <p>Origin</p> <p>This pattern is inspired by Geoffrey Huntley's Ralph Wiggum technique. We use generic terminology here so the concepts remain clear regardless of trends.</p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#how-it-works","level":2,"title":"How It Works","text":"<pre><code>graph TD\n    A[Start Loop] --&gt; B[Load PROMPT.md]\n    B --&gt; C[AI reads .context/]\n    C --&gt; D[AI picks task from TASKS.md]\n    D --&gt; E[AI completes task]\n    E --&gt; F[AI updates context files]\n    F --&gt; G[AI commits changes]\n    G --&gt; H{Check signals}\n    H --&gt;|SYSTEM_CONVERGED| I[Done - all tasks complete]\n    H --&gt;|SYSTEM_BLOCKED| J[Done - needs human input]\n    H --&gt;|Continue| B</code></pre> <ol> <li>Loop reads <code>PROMPT.md</code> and invokes AI</li> <li>AI loads context from <code>.context/</code></li> <li>AI picks one task and completes it</li> <li>AI updates context files (mark task done, add learnings)</li> <li>AI commits changes</li> <li>Loop checks for completion signals</li> <li>Repeat until converged or blocked</li> </ol>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#quick-start-with-claude-code","level":2,"title":"Quick Start with Claude Code","text":"<p>Claude Code has built-in loop support:</p> <pre><code># Start autonomous loop\n/loop\n\n# Cancel running loop\n/cancel-loop\n</code></pre> <p>That's it. The loop will:</p> <ol> <li>Read your <code>PROMPT.md</code> for instructions</li> <li>Pick tasks from <code>.context/TASKS.md</code></li> <li>Work until <code>SYSTEM_CONVERGED</code> or <code>SYSTEM_BLOCKED</code></li> </ol>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#manual-loop-setup","level":2,"title":"Manual Loop Setup","text":"<p>For other AI tools, create a <code>loop.sh</code>:</p> <pre><code>#!/bin/bash\n# loop.sh — an autonomous iteration loop\n\nPROMPT_FILE=\"${1:-PROMPT.md}\"\nMAX_ITERATIONS=\"${2:-10}\"\nOUTPUT_FILE=\"/tmp/loop_output.txt\"\n\nfor i in $(seq 1 $MAX_ITERATIONS); do\n  echo \"=== Iteration $i ===\"\n\n  # Invoke AI with prompt\n  cat \"$PROMPT_FILE\" | claude --print &gt; \"$OUTPUT_FILE\" 2&gt;&amp;1\n\n  # Display output\n  cat \"$OUTPUT_FILE\"\n\n  # Check for completion signals\n  if grep -q \"SYSTEM_CONVERGED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop complete: All tasks done\"\n    break\n  fi\n\n  if grep -q \"SYSTEM_BLOCKED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop blocked: Needs human input\"\n    break\n  fi\n\n  sleep 2\ndone\n</code></pre> <p>Make it executable and run:</p> <pre><code>chmod +x loop.sh\n./loop.sh\n</code></pre> <p>You can also generate this script with <code>ctx loop</code> (see CLI Reference).</p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#the-promptmd-file","level":2,"title":"The PROMPT.md File","text":"<p>The prompt file instructs the AI on how to work autonomously. Here's a template:</p> <pre><code># Autonomous Development Prompt\n\nYou are working on this project autonomously. Follow these steps:\n\n## 1. Load Context\n\nRead these files in order:\n1. `.context/CONSTITUTION.md` — NEVER violate these rules\n2. `.context/TASKS.md` — Find work to do\n3. `.context/CONVENTIONS.md` — Follow these patterns\n4. `.context/DECISIONS.md` — Understand past choices\n\n## 2. Pick One Task\n\nFrom `.context/TASKS.md`, select ONE task that is:\n- Not blocked\n- Highest priority available\n- Within your capabilities\n\n## 3. Complete the Task\n\n- Write code following conventions\n- Run tests if applicable\n- Keep changes focused and minimal\n\n## 4. Update Context\n\nAfter completing work:\n- Mark task complete in TASKS.md\n- Add any learnings to LEARNINGS.md\n- Add any decisions to DECISIONS.md\n\n## 5. Commit Changes\n\nCreate a focused commit with clear message.\n\n## 6. Signal Status\n\nEnd your response with exactly ONE of:\n\n- `SYSTEM_CONVERGED` — All tasks in TASKS.md are complete\n- `SYSTEM_BLOCKED` — Cannot proceed, need human input (explain why)\n- (no signal) — More work remains, continue to next iteration\n\n## Rules\n\n- ONE task per iteration\n- NEVER skip tests\n- NEVER violate CONSTITUTION.md\n- Commit after each task\n</code></pre>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#completion-signals","level":2,"title":"Completion Signals","text":"<p>The loop watches for these signals in AI output:</p> Signal Meaning When to Use <code>SYSTEM_CONVERGED</code> All tasks complete No pending tasks in TASKS.md <code>SYSTEM_BLOCKED</code> Cannot proceed Needs clarification, access, or decision <code>BOOTSTRAP_COMPLETE</code> Initial setup done Project scaffolding finished","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#example-usage","level":3,"title":"Example Usage","text":"<pre><code>I've completed all tasks in TASKS.md:\n- [x] Set up project structure\n- [x] Implement core API\n- [x] Add authentication\n- [x] Write tests\n\nNo pending tasks remain.\n\nSYSTEM_CONVERGED\n</code></pre> <pre><code>I cannot proceed with the \"Deploy to production\" task because:\n- Missing AWS credentials\n- Need confirmation on region selection\n\nPlease provide credentials and confirm deployment region.\n\nSYSTEM_BLOCKED\n</code></pre>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#why-context-loops-work-well-together","level":2,"title":"Why Context + Loops Work Well Together","text":"Without ctx With ctx Each iteration starts fresh Each iteration has full history Decisions get re-made Decisions persist in DECISIONS.md Learnings are lost Learnings accumulate in LEARNINGS.md Tasks can be forgotten Tasks tracked in TASKS.md","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#automatic-context-updates","level":3,"title":"Automatic Context Updates","text":"<p>During the loop, the AI should update context files:</p> <p>Mark task complete: <pre><code>ctx complete \"implement user auth\"\n</code></pre></p> <p>Or emit an update command (parsed by <code>ctx watch</code>): <pre><code>&lt;context-update type=\"complete\"&gt;user auth&lt;/context-update&gt;\n</code></pre></p> <p>Add learning: <pre><code>ctx add learning \"Rate limiting requires Redis connection\"\n</code></pre></p> <p>Or via update command: <pre><code>&lt;context-update type=\"learning\"&gt;Rate limiting requires Redis connection&lt;/context-update&gt;\n</code></pre></p> <p>Record decision: <pre><code>ctx add decision \"Use JWT tokens for API authentication\"\n</code></pre></p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#advanced-watch-mode","level":2,"title":"Advanced: Watch Mode","text":"<p>Run <code>ctx watch</code> alongside the loop to automatically process context updates:</p> <pre><code># Terminal 1: Run the loop\n./loop.sh 2&gt;&amp;1 | tee /tmp/loop.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/loop.log --auto-save\n</code></pre> <p>The <code>--auto-save</code> flag periodically saves session snapshots, creating a history of the loop's progress.</p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#example-project-setup","level":2,"title":"Example Project Setup","text":"<pre><code>my-project/\n├── .context/\n│   ├── CONSTITUTION.md\n│   ├── TASKS.md          # Work items for the loop\n│   ├── DECISIONS.md\n│   ├── LEARNINGS.md\n│   ├── CONVENTIONS.md\n│   └── sessions/         # Loop iteration history\n├── PROMPT.md             # Instructions for the AI\n├── loop.sh               # Loop script (if not using Claude Code)\n└── src/                  # Your code\n</code></pre>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#sample-tasksmd-for-autonomous-loops","level":3,"title":"Sample TASKS.md for Autonomous Loops","text":"<pre><code># Tasks\n\n## Phase 1: Setup\n\n- [x] Initialize project structure\n- [x] Set up testing framework\n\n## Phase 2: Core Features\n\n- [ ] Implement user registration `#priority:high`\n- [ ] Add email verification `#priority:high`\n- [ ] Create password reset flow `#priority:medium`\n\n## Phase 3: Polish\n\n- [ ] Add rate limiting `#priority:medium`\n- [ ] Improve error messages `#priority:low`\n</code></pre> <p>The loop will work through these systematically, marking each complete.</p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#troubleshooting","level":2,"title":"Troubleshooting","text":"","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#loop-runs-forever","level":3,"title":"Loop Runs Forever","text":"<p>Cause: AI not emitting completion signals</p> <p>Fix: Ensure PROMPT.md explicitly instructs signaling: <pre><code>End EVERY response with one of:\n- SYSTEM_CONVERGED (if all tasks done)\n- SYSTEM_BLOCKED (if stuck)\n</code></pre></p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#context-not-persisting","level":3,"title":"Context Not Persisting","text":"<p>Cause: AI not updating context files</p> <p>Fix: Add explicit instructions to PROMPT.md: <pre><code>After completing a task, you MUST:\n1. Run: ctx complete \"&lt;task&gt;\"\n2. Add learnings: ctx add learning \"...\"\n</code></pre></p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#tasks-getting-repeated","level":3,"title":"Tasks Getting Repeated","text":"<p>Cause: Task not marked complete before next iteration</p> <p>Fix: Ensure commit happens after context update: <pre><code>Order of operations:\n1. Complete coding work\n2. Update context files (ctx complete, ctx add)\n3. Commit ALL changes including .context/\n4. Then signal status\n</code></pre></p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#ai-violating-constitution","level":3,"title":"AI Violating Constitution","text":"<p>Cause: Constitution not read first</p> <p>Fix: Make constitution check explicit in PROMPT.md: <pre><code>BEFORE any work:\n1. Read .context/CONSTITUTION.md\n2. If task would violate ANY rule, emit SYSTEM_BLOCKED\n3. Explain which rule prevents the work\n</code></pre></p>","path":["Autonomous Loops"],"tags":[]},{"location":"autonomous-loop/#resources","level":2,"title":"Resources","text":"<ul> <li>Geoffrey Huntley's Ralph Wiggum Technique — Original inspiration</li> <li>Context CLI — Command reference</li> <li>Integrations — Tool-specific setup</li> </ul>","path":["Autonomous Loops"],"tags":[]},{"location":"cli-reference/","level":1,"title":"CLI Reference","text":"","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-cli","level":2,"title":"<code>ctx</code> CLI","text":"<p>This is a complete reference for all <code>ctx</code> commands.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#global-options","level":2,"title":"Global Options","text":"<p>All commands support these flags:</p> Flag Description <code>--help</code> Show command help <code>--version</code> Show version <code>--context-dir &lt;path&gt;</code> Override context directory (default: <code>.context/</code>) <code>--no-color</code> Disable colored output <p>The <code>NO_COLOR=1</code> environment variable also disables colored output.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#commands","level":2,"title":"Commands","text":"","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-init","level":3,"title":"<code>ctx init</code>","text":"<p>Initialize a new <code>.context/</code> directory with template files.</p> <pre><code>ctx init [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--force</code> <code>-f</code> Overwrite existing context files <code>--minimal</code> <code>-m</code> Only create essential files (TASKS.md, DECISIONS.md, CONSTITUTION.md) <code>--merge</code> Auto-merge ctx content into existing CLAUDE.md <p>Creates:</p> <ul> <li><code>.context/</code> directory with all template files</li> <li><code>.claude/hooks/</code> with auto-save and enforcement scripts (for Claude Code)</li> <li><code>.claude/commands/</code> with ctx slash command definitions</li> <li><code>.claude/settings.local.json</code> with hook configuration and pre-approved ctx permissions</li> <li><code>CLAUDE.md</code> with bootstrap instructions (or merges into existing)</li> </ul> <p>Example:</p> <pre><code># Standard initialization\nctx init\n\n# Minimal setup (just core files)\nctx init --minimal\n\n# Force overwrite existing\nctx init --force\n\n# Merge into existing CLAUDE.md\nctx init --merge\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-status","level":3,"title":"<code>ctx status</code>","text":"<p>Show the current context summary.</p> <pre><code>ctx status [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--json</code> Output as JSON <code>--verbose</code> <code>-v</code> Include file contents summary <p>Output:</p> <ul> <li>Context directory path</li> <li>Total files and token estimate</li> <li>Status of each file (loaded, empty, missing)</li> <li>Recent activity (modification times)</li> <li>Drift warnings if any</li> </ul> <p>Example:</p> <pre><code>ctx status\nctx status --json\nctx status --verbose\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-agent","level":3,"title":"<code>ctx agent</code>","text":"<p>Print an AI-ready context packet optimized for LLM consumption.</p> <pre><code>ctx agent [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--budget &lt;tokens&gt;</code> Token budget (default: 8000) <code>--format md\\|json</code> Output format (default: md) <p>Output:</p> <ul> <li>Read order for context files</li> <li>Constitution rules (never truncated)</li> <li>Current tasks</li> <li>Key conventions</li> <li>Recent decisions</li> </ul> <p>Example:</p> <pre><code># Default (8000 tokens, markdown)\nctx agent\n\n# Custom budget\nctx agent --budget 4000\n\n# JSON format\nctx agent --format json\n</code></pre> <p>Use case: Copy-paste into AI chat, pipe to system prompt, or use in hooks.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-load","level":3,"title":"<code>ctx load</code>","text":"<p>Load and display assembled context as AI would see it.</p> <pre><code>ctx load [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--budget &lt;tokens&gt;</code> Token budget for assembly (default: 8000) <code>--raw</code> Output raw file contents without assembly <p>Example:</p> <pre><code>ctx load\nctx load --budget 16000\nctx load --raw\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-add","level":3,"title":"<code>ctx add</code>","text":"<p>Add a new item to a context file.</p> <pre><code>ctx add &lt;type&gt; &lt;content&gt; [flags]\n</code></pre> <p>Types:</p> Type Target File <code>task</code> TASKS.md <code>decision</code> DECISIONS.md <code>learning</code> LEARNINGS.md <code>convention</code> CONVENTIONS.md <p>Flags:</p> Flag Short Description <code>--priority &lt;level&gt;</code> Priority for tasks: <code>high</code>, <code>medium</code>, <code>low</code> <code>--section &lt;name&gt;</code> <code>-s</code> Target section within file <code>--context</code> <code>-c</code> Context (required for decisions and learnings) <code>--rationale</code> <code>-r</code> Rationale for decisions (required for decisions) <code>--consequences</code> Consequences for decisions (required for decisions) <code>--lesson</code> <code>-l</code> Key insight (required for learnings) <code>--application</code> <code>-a</code> How to apply going forward (required for learnings) <code>--file</code> <code>-f</code> Read content from file instead of argument <p>Examples:</p> <pre><code># Add a task\nctx add task \"Implement user authentication\"\nctx add task \"Fix login bug\" --priority high\n\n# Record a decision (requires all ADR—Architectural Decision Record—fields)\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequences \"Team needs PostgreSQL training\"\n\n# Note a learning (requires context, lesson, and application)\nctx add learning \"Vitest mocks must be hoisted\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Vitest hoists vi.mock() calls to top of file\" \\\n  --application \"Always place vi.mock() before imports in test files\"\n\n# Add to specific section\nctx add convention \"Use kebab-case for filenames\" --section \"Naming\"\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-complete","level":3,"title":"<code>ctx complete</code>","text":"<p>Mark a task as completed.</p> <pre><code>ctx complete &lt;task-id-or-text&gt;\n</code></pre> <p>Arguments:</p> <ul> <li><code>task-id-or-text</code>: Task number or partial text match</li> </ul> <p>Examples:</p> <pre><code># By text (partial match)\nctx complete \"user auth\"\n\n# By task number\nctx complete 3\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-drift","level":3,"title":"<code>ctx drift</code>","text":"<p>Detect stale or invalid context.</p> <pre><code>ctx drift [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--json</code> Output machine-readable JSON <code>--fix</code> Auto-fix simple issues <p>Checks:</p> <ul> <li>Path references in ARCHITECTURE.md and CONVENTIONS.md exist</li> <li>Task references are valid</li> <li>Constitution rules aren't violated (heuristic)</li> <li>Staleness indicators (old files, many completed tasks)</li> </ul> <p>Example:</p> <pre><code>ctx drift\nctx drift --json\nctx drift --fix\n</code></pre> <p>Exit codes:</p> Code Meaning 0 All checks passed 1 Warnings found 3 Violations found","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-sync","level":3,"title":"<code>ctx sync</code>","text":"<p>Reconcile context with the current codebase state.</p> <pre><code>ctx sync [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--dry-run</code> Show what would change without modifying <p>What it does:</p> <ul> <li>Scans codebase for structural changes</li> <li>Compares with ARCHITECTURE.md</li> <li>Suggests documenting dependencies if package files exist</li> <li>Identifies stale or outdated context</li> </ul> <p>Example:</p> <pre><code>ctx sync\nctx sync --dry-run\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-compact","level":3,"title":"<code>ctx compact</code>","text":"<p>Consolidate and clean up context files.</p> <ul> <li>Moves completed tasks older than 7 days to the archive</li> <li>Deduplicates the \"learning\"s with similar content</li> <li>Removes empty sections</li> </ul> <pre><code>ctx compact [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--archive</code> Create <code>.context/archive/</code> for old content <code>--no-auto-save</code> Skip auto-saving session before compact <p>Example:</p> <pre><code>ctx compact\nctx compact --archive\nctx compact --no-auto-save\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-tasks","level":3,"title":"<code>ctx tasks</code>","text":"<p>Manage task archival and snapshots.</p> <pre><code>ctx tasks &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-tasks-archive","level":4,"title":"<code>ctx tasks archive</code>","text":"<p>Move completed tasks from TASKS.md to a timestamped archive file.</p> <pre><code>ctx tasks archive [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--dry-run</code> Preview changes without modifying files <p>Archive files are stored in <code>.context/archive/</code> with timestamped names (<code>tasks-YYYY-MM-DD.md</code>). Completed tasks (marked with <code>[x]</code>) are moved; pending tasks (<code>[ ]</code>) remain in TASKS.md.</p> <p>Example:</p> <pre><code>ctx tasks archive\nctx tasks archive --dry-run\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-tasks-snapshot","level":4,"title":"<code>ctx tasks snapshot</code>","text":"<p>Create a point-in-time snapshot of TASKS.md without modifying the original.</p> <pre><code>ctx tasks snapshot [name]\n</code></pre> <p>Arguments:</p> <ul> <li><code>name</code>: Optional name for the snapshot (defaults to \"snapshot\")</li> </ul> <p>Snapshots are stored in <code>.context/archive/</code> with timestamped names (<code>tasks-&lt;name&gt;-YYYY-MM-DD-HHMM.md</code>).</p> <p>Example:</p> <pre><code>ctx tasks snapshot\nctx tasks snapshot \"before-refactor\"\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-decisions","level":3,"title":"<code>ctx decisions</code>","text":"<p>Manage the DECISIONS.md file.</p> <pre><code>ctx decisions &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-decisions-reindex","level":4,"title":"<code>ctx decisions reindex</code>","text":"<p>Regenerate the quick-reference index at the top of DECISIONS.md.</p> <pre><code>ctx decisions reindex\n</code></pre> <p>The index is a compact table showing date and title for each decision, allowing AI tools to quickly scan entries without reading the full file.</p> <p>Use this after manual edits to DECISIONS.md or when migrating existing files to use the index format.</p> <p>Example:</p> <pre><code>ctx decisions reindex\n# ✓ Index regenerated with 12 entries\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-learnings","level":3,"title":"<code>ctx learnings</code>","text":"<p>Manage the LEARNINGS.md file.</p> <pre><code>ctx learnings &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-learnings-reindex","level":4,"title":"<code>ctx learnings reindex</code>","text":"<p>Regenerate the quick-reference index at the top of LEARNINGS.md.</p> <pre><code>ctx learnings reindex\n</code></pre> <p>The index is a compact table showing date and title for each learning, allowing AI tools to quickly scan entries without reading the full file.</p> <p>Use this after manual edits to LEARNINGS.md or when migrating existing files to use the index format.</p> <p>Example:</p> <pre><code>ctx learnings reindex\n# ✓ Index regenerated with 8 entries\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall","level":3,"title":"<code>ctx recall</code>","text":"<p>Browse and search AI session history from Claude Code and other tools.</p> <pre><code>ctx recall &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall-list","level":4,"title":"<code>ctx recall list</code>","text":"<p>List all parsed sessions.</p> <pre><code>ctx recall list [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--limit</code> <code>-n</code> Maximum sessions to display (default: 20) <code>--project</code> <code>-p</code> Filter by project name <code>--tool</code> <code>-t</code> Filter by tool (e.g., <code>claude-code</code>) <p>Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.</p> <p>Example:</p> <pre><code>ctx recall list\nctx recall list --limit 5\nctx recall list --project ctx\nctx recall list --tool claude-code\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall-show","level":4,"title":"<code>ctx recall show</code>","text":"<p>Show details of a specific session.</p> <pre><code>ctx recall show [session-id] [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--latest</code> Show the most recent session <code>--full</code> Show full message content <p>The session ID can be a full UUID, partial match, or session slug name.</p> <p>Example:</p> <pre><code>ctx recall show abc123\nctx recall show gleaming-wobbling-sutherland\nctx recall show --latest\nctx recall show --latest --full\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-recall-export","level":4,"title":"<code>ctx recall export</code>","text":"<p>Export sessions to editable journal files in <code>.context/journal/</code>.</p> <pre><code>ctx recall export [session-id] [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--all</code> Export all sessions <code>--force</code> Overwrite existing files <p>Exported files include session metadata, tool usage summary, and the full conversation. Existing files are skipped by default to preserve your edits.</p> <p>The <code>journal/</code> directory should be gitignored (like <code>sessions/</code>) since it contains raw conversation data.</p> <p>Example:</p> <pre><code>ctx recall export abc123          # Export one session\nctx recall export --all           # Export all sessions\nctx recall export --all --force   # Overwrite existing exports\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-journal","level":3,"title":"<code>ctx journal</code>","text":"<p>Analyze and synthesize exported session files.</p> <pre><code>ctx journal &lt;subcommand&gt;\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-journal-site","level":4,"title":"<code>ctx journal site</code>","text":"<p>Generate a static site from journal entries in <code>.context/journal/</code>.</p> <pre><code>ctx journal site [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--output</code> <code>-o</code> Output directory (default: .context/journal-site) <code>--build</code> Run zensical build after generating <code>--serve</code> Run zensical serve after generating <p>Creates a zensical-compatible site structure with an index page listing all sessions by date, and individual pages for each journal entry.</p> <p>Requires zensical to be installed for <code>--build</code> or <code>--serve</code>: <pre><code>pip install zensical\n</code></pre></p> <p>Example:</p> <pre><code>ctx journal site                    # Generate in .context/journal-site/\nctx journal site --output ~/public  # Custom output directory\nctx journal site --build            # Generate and build HTML\nctx journal site --serve            # Generate and serve locally\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-serve","level":3,"title":"<code>ctx serve</code>","text":"<p>Serve a static site locally via zensical.</p> <pre><code>ctx serve [directory]\n</code></pre> <p>If no directory is specified, serves the journal site (<code>.context/journal-site</code>).</p> <p>Requires zensical to be installed: <pre><code>pip install zensical\n</code></pre></p> <p>Example:</p> <pre><code>ctx serve                           # Serve journal site\nctx serve .context/journal-site     # Serve specific directory\nctx serve ./docs                    # Serve docs folder\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-watch","level":3,"title":"<code>ctx watch</code>","text":"<p>Watch for AI output and auto-apply context updates.</p> <p>Parses <code>&lt;context-update&gt;</code> XML commands from AI output and applies them to context files.</p> <pre><code>ctx watch [flags]\n</code></pre> <p>Flags:</p> Flag Description <code>--log &lt;file&gt;</code> Log file to watch (default: stdin) <code>--dry-run</code> Preview updates without applying <code>--auto-save</code> Periodically save session snapshots <p>Example:</p> <pre><code># Watch stdin\nai-tool | ctx watch\n\n# Watch a log file\nctx watch --log /path/to/ai-output.log\n\n# Preview without applying\nctx watch --dry-run\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-hook","level":3,"title":"<code>ctx hook</code>","text":"<p>Generate AI tool integration configuration.</p> <pre><code>ctx hook &lt;tool&gt;\n</code></pre> <p>Supported tools:</p> Tool Description <code>claude-code</code> Claude Code CLI <code>cursor</code> Cursor IDE <code>aider</code> Aider CLI <code>copilot</code> GitHub Copilot <code>windsurf</code> Windsurf IDE <p>Example:</p> <pre><code>ctx hook claude-code\nctx hook cursor\nctx hook aider\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session","level":3,"title":"<code>ctx session</code>","text":"<p>Manage session snapshots.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-save","level":4,"title":"ctx session save","text":"<p>Save the current context snapshot.</p> <pre><code>ctx session save [topic] [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--type &lt;type&gt;</code> <code>-t</code> Session type: <code>feature</code>, <code>bugfix</code>, <code>refactor</code>, <code>session</code> <p>Example:</p> <pre><code>ctx session save\nctx session save \"feature-auth\"\nctx session save \"bugfix\" --type bugfix\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-list","level":4,"title":"<code>ctx session list</code>","text":"<p>List saved sessions.</p> <pre><code>ctx session list [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--limit</code> <code>-n</code> Maximum sessions to display (default: 10) <p>Output: Table of sessions with index, date, topic, and type.</p> <p>Example:</p> <pre><code>ctx session list\nctx session list --limit 5\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-load","level":4,"title":"<code>ctx session load</code>","text":"<p>Load and display a previous session.</p> <pre><code>ctx session load &lt;index|date|topic&gt;\n</code></pre> <p>Arguments:</p> <ul> <li><code>index</code>: Numeric index from <code>session list</code></li> <li><code>date</code>: Date pattern (e.g., <code>2026-01-21</code>)</li> <li><code>topic</code>: Topic keyword match</li> </ul> <p>Example:</p> <pre><code>ctx session load 1           # by index\nctx session load 2026-01-21  # by date\nctx session load auth        # by topic\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-session-parse","level":4,"title":"<code>ctx session parse</code>","text":"<p>Parse JSONL transcript to readable markdown.</p> <pre><code>ctx session parse &lt;file&gt; [flags]\n</code></pre> <p>Flags:</p> Flag Short Description <code>--output</code> <code>-o</code> Output file (default: stdout) <code>--extract</code> Extract decisions and learnings from transcript <p>Example:</p> <pre><code>ctx session parse ~/.claude/projects/.../transcript.jsonl\nctx session parse transcript.jsonl --extract\nctx session parse transcript.jsonl -o conversation.md\n</code></pre>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#ctx-loop","level":3,"title":"<code>ctx loop</code>","text":"<p>Generate a shell script for running an autonomous loop.</p> <p>An autonomous loop continuously runs an AI assistant with the same prompt until a completion signal is detected, enabling iterative development where the AI builds on its previous work.</p> <pre><code>ctx loop [flags]\n</code></pre> <p>Flags:</p> Flag Short Description Default <code>--tool &lt;tool&gt;</code> <code>-t</code> AI tool: <code>claude</code>, <code>aider</code>, or <code>generic</code> <code>claude</code> <code>--prompt &lt;file&gt;</code> <code>-p</code> Prompt file to use <code>PROMPT.md</code> <code>--max-iterations &lt;n&gt;</code> <code>-n</code> Maximum iterations (0 = unlimited) <code>0</code> <code>--completion &lt;signal&gt;</code> <code>-c</code> Completion signal to detect <code>SYSTEM_CONVERGED</code> <code>--output &lt;file&gt;</code> <code>-o</code> Output script filename <code>loop.sh</code> <p>Example:</p> <pre><code># Generate loop.sh for Claude Code\nctx loop\n\n# Generate for Aider with custom prompt\nctx loop --tool aider --prompt TASKS.md\n\n# Limit to 10 iterations\nctx loop --max-iterations 10\n\n# Output to custom file\nctx loop -o my-loop.sh\n</code></pre> <p>Usage:</p> <pre><code># Generate and run the loop\nctx loop\nchmod +x loop.sh\n./loop.sh\n</code></pre> <p>See Autonomous Loops for detailed workflow documentation.</p>","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#exit-codes","level":2,"title":"Exit Codes","text":"Code Meaning 0 Success 1 General error 2 Context not found 3 Invalid arguments 4 File operation error","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#environment-variables","level":2,"title":"Environment Variables","text":"Variable Description <code>CTX_DIR</code> Override default context directory path <code>CTX_TOKEN_BUDGET</code> Override default token budget <code>NO_COLOR</code> Disable colored output when set","path":["CLI Reference"],"tags":[]},{"location":"cli-reference/#configuration-file","level":2,"title":"Configuration File","text":"<p>Optional <code>.contextrc</code> (YAML format) at project root:</p> <pre><code># .contextrc\ncontext_dir: .context # Context directory name\ntoken_budget: 8000    # Default token budget\npriority_order:       # File loading priority\n  - TASKS.md\n  - DECISIONS.md\n  - CONVENTIONS.md\nauto_archive: true    # Auto-archive old items\narchive_after_days: 7 # Days before archiving\n</code></pre> <p>Priority order: CLI flags &gt; Environment variables &gt; <code>.contextrc</code> &gt; Defaults</p> <p>All settings are optional. Missing values use defaults.</p>","path":["CLI Reference"],"tags":[]},{"location":"comparison/","level":1,"title":"ctx and Similar Tools","text":"","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#high-level-mental-model","level":2,"title":"High-Level Mental Model","text":"<p>Many tools help AI think.</p> <p><code>ctx</code> helps AI remember.</p> <p>Not by storing thoughts, but by preserving intent.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#how-ctx-differs-from-similar-tools","level":2,"title":"How <code>ctx</code> Differs from Similar Tools","text":"<p>There are many tools in the AI ecosystem that touch parts of the context problem:</p> <ul> <li>Some manage prompts.  </li> <li>Some retrieve data.  </li> <li>Some provide runtime context objects.  </li> <li>Some offer enterprise platforms.</li> </ul> <p><code>ctx</code> focuses on a different layer entirely.</p> <p>This page explains where <code>ctx</code> fits, and where it intentionally does not.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#the-core-distinction","level":2,"title":"The Core Distinction","text":"<p>Most tools treat context as input.</p> <p><code>ctx</code> treats context as infrastructure.</p> <p>That single difference explains nearly all of <code>ctx</code>'s design choices.</p> Question Most tools ctx Where does context live? In prompts or APIs In files How long does it last? One request / one session Across time Who can read it? The model Humans and tools How is it updated? Implicitly Explicitly Is it inspectable? Rarely Always","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#prompt-management-tools","level":2,"title":"Prompt Management Tools","text":"<p>Examples include:</p> <ul> <li>prompt templates</li> <li>reusable system prompts</li> <li>prompt libraries</li> <li>prompt versioning tools</li> </ul> <p>These tools help you start a session.</p> <p>They do not help you continue one.</p> <p>Prompt tools:</p> <ul> <li>inject text at session start</li> <li>are ephemeral by design</li> <li>do not evolve with the project</li> </ul> <p><code>ctx</code>:</p> <ul> <li>persists knowledge over time</li> <li>accumulates decisions and learnings</li> <li>makes the context part of the repository itself</li> </ul> <p>Prompt tooling and <code>ctx</code> are complementary; not competing.  Yet, they operate at different layers.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#retrieval-augmented-generation-rag","level":2,"title":"Retrieval-Augmented Generation (RAG)","text":"<p>RAG systems typically:</p> <ul> <li>index documents</li> <li>embed text</li> <li>retrieve chunks dynamically at runtime</li> </ul> <p>They are excellent for:</p> <ul> <li>large knowledge bases</li> <li>static documentation</li> <li>reference material</li> </ul> <p>RAG answers questions like:</p> <p>\"What information might be relevant right now?\"</p> <p><code>ctx</code> answers a different question:</p> <p>\"What have we already decided, learned, or committed to?\"</p> <p>Here are some key differences:</p> RAG ctx Statistical relevance Intentional relevance Embedding-based File-based Opaque retrieval Explicit structure Runtime query Persistent memory <p><code>ctx</code> does not replace RAG. Instead, it defines a persistent context layer that RAG can optionally augment.</p> <p>RAG belongs to the data plane; ctx defines the context control plane.</p> <p>It focuses on project memory, not knowledge search.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#agent-frameworks","level":2,"title":"Agent Frameworks","text":"<p>Agent frameworks often provide:</p> <ul> <li>task loops</li> <li>tool orchestration</li> <li>planner/executor patterns</li> <li>autonomous iteration</li> </ul> <p>These systems are powerful, but they typically assume that:</p> <ul> <li>memory is external</li> <li>context is injected</li> <li>state is transient</li> </ul> <p>Agent frameworks answer:</p> <p>\"How should the agent act?\"</p> <p><code>ctx</code> answers:</p> <p>\"What should the agent remember?\"</p> <p>Without persistent context, agents tend to:</p> <ul> <li>rediscover decisions</li> <li>repeat mistakes</li> <li>lose architectural intent</li> </ul> <p>This is why <code>ctx</code> pairs well with autonomous loop workflows:</p> <ul> <li>The loop provides iteration</li> <li><code>ctx</code> provides continuity</li> </ul> <p>Together, loops become cumulative instead of forgetful.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#sdk-level-context-objects","level":2,"title":"SDK-Level Context Objects","text":"<p>Some SDKs expose \"context\" objects that exist:</p> <ul> <li>inside a process</li> <li>during a request</li> <li>for the lifetime of a call chain</li> </ul> <p>These are extremely useful and completely different.</p> <p>SDK context objects:</p> <ul> <li>are in-memory</li> <li>disappear when the process ends</li> <li>are not shared across sessions</li> </ul> <p><code>ctx</code>:</p> <ul> <li>survives process restarts</li> <li>survives new chats</li> <li>survives new days</li> </ul> <p>They share a name, not a purpose.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#enterprise-context-platforms","level":2,"title":"Enterprise Context Platforms","text":"<p>Enterprise platforms often provide:</p> <ul> <li>centralized context services</li> <li>dashboards</li> <li>access control</li> <li>organizational knowledge layers</li> </ul> <p>These tools are designed for:</p> <ul> <li>teams</li> <li>governance</li> <li>compliance</li> <li>managed environments</li> </ul> <p><code>ctx</code> is intentionally:</p> <ul> <li>local-first</li> <li>file-based</li> <li>dependency-free</li> <li>CLI-driven</li> <li>developer-controlled</li> </ul> <p>It does not require:</p> <ul> <li>a server</li> <li>a database</li> <li>an account</li> <li>a SaaS backend</li> </ul> <p><code>ctx</code> optimizes for individual and small-team workflows where context should live next to code; not behind a service boundary.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#when-ctx-is-a-good-fit","level":2,"title":"When <code>ctx</code> Is a Good Fit","text":"<p><code>ctx</code> works best when:</p> <ul> <li>you want AI work to compound over time</li> <li>architectural decisions matter</li> <li>context must be inspectable</li> <li>humans and AI must share the same source of truth</li> <li>Git history should include why, not just what</li> </ul>","path":["ctx and Similar Tools"],"tags":[]},{"location":"comparison/#when-ctx-is-not-the-right-tool","level":2,"title":"When <code>ctx</code> Is Not the Right Tool","text":"<p><code>ctx</code> is probably not what you want if:</p> <ul> <li>you only need one-off prompts</li> <li>you rely exclusively on RAG</li> <li>you want autonomous agents without a human-readable state</li> <li>you require centralized enterprise control</li> <li>you want black-box memory systems</li> </ul> <p>These are valid goals; just different ones.</p>","path":["ctx and Similar Tools"],"tags":[]},{"location":"context-files/","level":1,"title":"Context Files","text":"","path":["Context Files"],"tags":[]},{"location":"context-files/#context","level":2,"title":"<code>.context/</code>","text":"<p>Each context file in <code>.context/</code> serves a specific purpose. </p> <p>Files are designed to be human-readable, AI-parseable, and token-efficient.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#file-overview","level":2,"title":"File Overview","text":"File Purpose Priority CONSTITUTION.md Hard rules that must NEVER be violated 1 (highest) TASKS.md Current and planned work 2 CONVENTIONS.md Project patterns and standards 3 ARCHITECTURE.md System overview and components 4 DECISIONS.md Architectural decisions with rationale 5 LEARNINGS.md Lessons learned, gotchas, tips 6 GLOSSARY.md Domain terms and abbreviations 7 DRIFT.md Staleness signals and update triggers 8 AGENT_PLAYBOOK.md Instructions for AI tools 9 (lowest)","path":["Context Files"],"tags":[]},{"location":"context-files/#read-order-rationale","level":2,"title":"Read Order Rationale","text":"<p>The priority order follows a logical progression for AI tools:</p> <ol> <li> <p>CONSTITUTION — Inviolable rules first. The AI tool must know what it    cannot do before attempting anything.</p> </li> <li> <p>TASKS — Current work items. What the AI tool should focus on.</p> </li> <li> <p>CONVENTIONS — How to write code. Patterns and standards to follow    when implementing tasks.</p> </li> <li> <p>ARCHITECTURE — System structure. Understanding of components and    boundaries before making changes.</p> </li> <li> <p>DECISIONS — Historical context. Why things are the way they are,    to avoid re-debating settled decisions.</p> </li> <li> <p>LEARNINGS — Gotchas and tips. Lessons from past work that inform    current implementation.</p> </li> <li> <p>GLOSSARY — Reference material. Domain terms and abbreviations for    lookup as needed.</p> </li> <li> <p>DRIFT — Staleness indicators. Lower priority since it's primarily    for maintenance workflows, not active development.</p> </li> <li> <p>AGENT_PLAYBOOK — Meta instructions last. How to use this context    system itself. Loaded last because the agent should understand the    content (rules, tasks, patterns) before the operating manual.</p> </li> </ol>","path":["Context Files"],"tags":[]},{"location":"context-files/#constitutionmd","level":2,"title":"CONSTITUTION.md","text":"<p>Purpose: Define hard invariants—rules that must NEVER be violated,  regardless of the task.</p> <p>AI tools read this first and should refuse tasks that violate these rules.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure","level":3,"title":"Structure","text":"<pre><code># Constitution\n\nThese rules are INVIOLABLE. If a task requires violating these, the task \nis wrong.\n\n## Security Invariants\n\n- [ ] Never commit secrets, tokens, API keys, or credentials\n- [ ] Never store customer/user data in context files\n- [ ] Never disable security linters without documented exception\n\n## Quality Invariants\n\n- [ ] All code must pass tests before commit\n- [ ] No `any` types in TypeScript without documented reason\n- [ ] No TODO comments in main branch (move to TASKS.md)\n\n## Process Invariants\n\n- [ ] All architectural changes require a decision record\n- [ ] Breaking changes require version bump\n- [ ] Generated files are never committed\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines","level":3,"title":"Guidelines","text":"<ul> <li>Keep rules minimal and absolute</li> <li>Each rule should be enforceable (can verify compliance)</li> <li>Use checkbox format for clarity</li> <li>Never compromise on these rules</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#tasksmd","level":2,"title":"TASKS.md","text":"<p>Purpose: Track current work, planned work, and blockers.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_1","level":3,"title":"Structure","text":"<p>Tasks are organized by Phase — logical groupings that preserve order and enable replay. Tasks stay in their Phase permanently; status is tracked via checkboxes and inline tags.</p> <pre><code># Tasks\n\n## Phase 1: Initial Setup\n\n- [x] Set up project structure\n- [x] Configure linting and formatting\n- [ ] Add CI/CD pipeline `#in-progress`\n\n## Phase 2: Core Features\n\n- [ ] Implement user authentication `#priority:high`\n- [ ] Add API rate limiting `#priority:medium`\n  - Blocked by: Need to finalize auth first\n\n## Backlog\n\n- [ ] Performance optimization `#priority:low`\n- [ ] Add metrics dashboard `#priority:deferred`\n</code></pre> <p>Key principles: - Tasks never move between sections — mark as <code>[x]</code> or <code>[-]</code> in place - Use <code>#in-progress</code> inline tag to indicate current work - Phase headers provide structure and replay order - Backlog section for unscheduled work</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#tags","level":3,"title":"Tags","text":"<p>Use inline backtick-wrapped tags for metadata:</p> Tag Values Purpose <code>#priority</code> <code>high</code>, <code>medium</code>, <code>low</code> Task urgency <code>#area</code> <code>core</code>, <code>cli</code>, <code>docs</code>, <code>tests</code> Codebase area <code>#estimate</code> <code>1h</code>, <code>4h</code>, <code>1d</code> Time estimate (optional) <code>#in-progress</code> (none) Currently being worked on <p>Lifecycle tags (for session correlation):</p> Tag Format When to add <code>#added</code> <code>YYYY-MM-DD-HHMMSS</code> Auto-added by <code>ctx add task</code> <code>#started</code> <code>YYYY-MM-DD-HHMMSS</code> When beginning work on the task <code>#done</code> <code>YYYY-MM-DD-HHMMSS</code> When marking the task <code>[x]</code> <p>These timestamps help correlate tasks with session files and track which session started vs completed work.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#status-markers","level":3,"title":"Status Markers","text":"Marker Meaning <code>[ ]</code> Pending <code>[x]</code> Completed <code>[-]</code> Skipped (include reason)","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_1","level":3,"title":"Guidelines","text":"<ul> <li>Never delete tasks — mark as <code>[x]</code> completed or <code>[-]</code> skipped</li> <li>Never move tasks between sections — use inline tags for status</li> <li>Use <code>ctx tasks archive</code> periodically to move completed tasks to archive</li> <li>Mark current work with <code>#in-progress</code> inline tag</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#decisionsmd","level":2,"title":"DECISIONS.md","text":"<p>Purpose: Record architectural decisions with rationale so they don't get re-debated.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_2","level":3,"title":"Structure","text":"<pre><code># Decisions\n\n## [YYYY-MM-DD] Decision Title\n\n**Status**: Accepted | Superseded | Deprecated\n\n**Context**: What situation prompted this decision?\n\n**Decision**: What was decided?\n\n**Rationale**: Why was this the right choice?\n\n**Consequences**: What are the implications?\n\n**Alternatives Considered**:\n- Alternative A: Why rejected\n- Alternative B: Why rejected\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#example","level":3,"title":"Example","text":"<pre><code>## [2025-01-15] Use TypeScript Strict Mode\n\n**Status**: Accepted\n\n**Context**: Starting new project, need to choose type checking level.\n\n**Decision**: Enable TypeScript strict mode with all strict flags.\n\n**Rationale**: Catches more bugs at compile time. Team has experience\nwith strict mode. Upfront cost pays off in reduced runtime errors.\n\n**Consequences**: More verbose type annotations required. Some\nthird-party libraries need type assertions.\n\n**Alternatives Considered**:\n- Basic TypeScript: Rejected because it misses null checks\n- JavaScript with JSDoc: Rejected because tooling support is weaker\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#status-values","level":3,"title":"Status Values","text":"Status Meaning Accepted Current, active decision Superseded Replaced by newer decision (link to it) Deprecated No longer relevant","path":["Context Files"],"tags":[]},{"location":"context-files/#learningsmd","level":2,"title":"LEARNINGS.md","text":"<p>Purpose: Capture lessons learned, gotchas, and tips that shouldn't be forgotten.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_3","level":3,"title":"Structure","text":"<pre><code># Learnings\n\n## Category Name\n\n### Learning Title\n\n**Discovered**: YYYY-MM-DD\n\n**Context**: When/how was this learned?\n\n**Lesson**: What's the takeaway?\n\n**Application**: How should this inform future work?\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#example_1","level":3,"title":"Example","text":"<pre><code>## Testing\n\n### Vitest Mocks Must Be Hoisted\n\n**Discovered**: 2025-01-15\n\n**Context**: Tests were failing intermittently when mocking fs module.\n\n**Lesson**: Vitest requires `vi.mock()` calls to be hoisted to the\ntop of the file. Dynamic mocks need `vi.doMock()` instead.\n\n**Application**: Always use `vi.mock()` at file top. Use `vi.doMock()`\nonly when mock needs runtime values.\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#categories","level":3,"title":"Categories","text":"<p>Organize learnings by topic:</p> <ul> <li>Testing</li> <li>Build &amp; Deploy</li> <li>Performance</li> <li>Security</li> <li>Third-Party Libraries</li> <li>Git &amp; Workflow</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#conventionsmd","level":2,"title":"CONVENTIONS.md","text":"<p>Purpose: Document project patterns, naming conventions, and standards.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_4","level":3,"title":"Structure","text":"<pre><code># Conventions\n\n## Naming\n\n- **Files**: kebab-case for all source files\n- **Components**: PascalCase for React components\n- **Functions**: camelCase, verb-first (getUser, parseConfig)\n- **Constants**: SCREAMING_SNAKE_CASE\n\n## Patterns\n\n### Pattern Name\n\n**When to use**: Situation description\n\n**Implementation**:\n// in triple backticks\n// Example code\n\n**Why**: Rationale for this pattern\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_2","level":3,"title":"Guidelines","text":"<ul> <li>Include concrete examples</li> <li>Explain the \"why\" not just the \"what\"</li> <li>Keep patterns minimal—only document what's non-obvious</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#architecturemd","level":2,"title":"ARCHITECTURE.md","text":"<p>Purpose: Provide system overview and component relationships.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_5","level":3,"title":"Structure","text":"<pre><code># Architecture\n\n## Overview\n\nBrief description of what the system does and how it's organized.\n\n## Components\n\n### Component Name\n\n**Responsibility**: What this component does\n\n**Dependencies**: What it depends on\n\n**Dependents**: What depends on it\n\n**Key Files**:\n- path/to/file.ts — Description\n\n## Data Flow\n\nDescription or diagram of how data moves through the system.\n\n## Boundaries\n\nWhat's in scope vs out of scope for this codebase.\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_3","level":3,"title":"Guidelines","text":"<ul> <li>Keep diagrams simple (Mermaid works well)</li> <li>Focus on boundaries and interfaces</li> <li>Update when major structural changes occur</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#glossarymd","level":2,"title":"GLOSSARY.md","text":"<p>Purpose: Define domain terms, abbreviations, and project vocabulary.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_6","level":3,"title":"Structure","text":"<pre><code># Glossary\n\n## Domain Terms\n\n### Term Name\n\n**Definition**: What it means in this project's context\n\n**Not to be confused with**: Similar terms that mean different things\n\n**Example**: How it's used\n\n## Abbreviations\n\n| Abbrev | Expansion                     | Context                |\n|--------|-------------------------------|------------------------|\n| ADR    | Architectural Decision Record | Decision documentation |\n| SUT    | System Under Test             | Testing                |\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#guidelines_4","level":3,"title":"Guidelines","text":"<ul> <li>Define project-specific meanings</li> <li>Clarify potentially ambiguous terms</li> <li>Include abbreviations used in code or docs</li> </ul>","path":["Context Files"],"tags":[]},{"location":"context-files/#driftmd","level":2,"title":"DRIFT.md","text":"<p>Purpose: Define signals that the context is stale and needs updating.</p> <p>Used by <code>ctx drift</code> command to detect staleness.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#structure_7","level":3,"title":"Structure","text":"<pre><code># Drift Detection\n\n## Automatic Checks\n\nThese are checked by `ctx drift`:\n\n### Path References\n\n- [ ] All paths in ARCHITECTURE.md exist in filesystem\n- [ ] All paths in CONVENTIONS.md exist\n- [ ] All file references in DECISIONS.md are valid\n\n### Task References\n\n- [ ] All issues referenced in TASKS.md exist\n- [ ] No tasks older than 30 days without update\n\n### Constitution Violations\n\n- [ ] No secrets patterns detected in committed files\n\n## Manual Review Triggers\n\nUpdate context when:\n\n- [ ] New team member joins (review CONVENTIONS.md)\n- [ ] Major dependency upgraded (review ARCHITECTURE.md)\n- [ ] Sprint/milestone completed (archive old tasks)\n\n## Staleness Indicators\n\n| File            | Stale If       | Action                 |\n|-----------------|----------------|------------------------|\n| ARCHITECTURE.md | &gt;30 days old   | Review component list  |\n| TASKS.md        | &gt;50% completed | Archive and refresh    |\n| LEARNINGS.md    | &gt;20 items      | Consolidate or archive |\n</code></pre>","path":["Context Files"],"tags":[]},{"location":"context-files/#agent_playbookmd","level":2,"title":"AGENT_PLAYBOOK.md","text":"<p>Purpose: Explicit instructions for how AI tools should read, apply,  and update context.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#key-sections","level":3,"title":"Key Sections","text":"<p>Read Order: Priority order for loading context files</p> <p>When to Update: Events that trigger context updates</p> <p>How to Avoid Hallucinating Memory: Critical rules:</p> <ol> <li>Never assume—if not in files, you don't know it</li> <li>Never invent history—don't claim \"we discussed\" without evidence</li> <li>Verify before referencing—search files before citing</li> <li>When uncertain, say so</li> <li>Trust files over intuition</li> </ol> <p>Context Update Commands: Format for automated updates via <code>ctx watch</code>:</p> <pre><code>&lt;context-update type=\"learning\"&gt;Key takeaway from today's work&lt;/context-update&gt;\n&lt;context-update type=\"decision\"&gt;Use Redis for caching&lt;/context-update&gt;\n&lt;context-update type=\"complete\"&gt;user auth&lt;/context-update&gt;\n</code></pre> <p>See Integrations for full documentation.</p>","path":["Context Files"],"tags":[]},{"location":"context-files/#parsing-rules","level":2,"title":"Parsing Rules","text":"<p>All context files follow these conventions:</p> <ol> <li>Headers define structure — <code>#</code> for title, <code>##</code> for sections, <code>###</code> for     items</li> <li>Bold keys for fields — <code>**Key**:</code> followed by value</li> <li>Code blocks are literal — Never parse code block content as structure</li> <li>Lists are ordered — Items appear in priority/chronological order</li> <li>Tags are inline — Backtick-wrapped tags like <code>#priority:high</code></li> </ol>","path":["Context Files"],"tags":[]},{"location":"context-files/#token-efficiency","level":2,"title":"Token Efficiency","text":"<p>Keep context files concise:</p> <ul> <li>Use abbreviations in tags, not prose</li> <li>Omit obvious words (\"The\", \"This\")</li> <li>Prefer bullet points over paragraphs</li> <li>Keep examples minimal but illustrative</li> <li>Archive old completed items periodically</li> </ul>","path":["Context Files"],"tags":[]},{"location":"integrations/","level":1,"title":"AI Tool Integrations","text":"","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#ai-tool-integrations","level":2,"title":"AI Tool Integrations","text":"<p>Context works with any AI tool that can read files. This guide covers setup  for popular AI coding assistants.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#claude-code-full-integration","level":2,"title":"Claude Code (Full Integration)","text":"<p>Claude Code has the deepest integration with automatic context loading and  session persistence.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#automatic-setup","level":3,"title":"Automatic Setup","text":"<p>Running <code>ctx init</code> automatically configures Claude Code:</p> <pre><code>ctx init\n</code></pre> <p>This creates:</p> File/Directory Purpose <code>.context/</code> All context files <code>.claude/hooks/</code> Auto-save scripts <code>.claude/settings.local.json</code> Hook configuration <code>CLAUDE.md</code> Bootstrap instructions","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#how-it-works","level":3,"title":"How It Works","text":"<pre><code>graph TD\n    A[Session Start] --&gt; B[Claude reads CLAUDE.md]\n    B --&gt; C[PreToolUse hook runs]\n    C --&gt; D[ctx agent loads context]\n    D --&gt; E[Work happens]\n    E --&gt; F[Session End]\n    F --&gt; G[SessionEnd hook saves snapshot]</code></pre> <ol> <li>Session start: Claude reads <code>CLAUDE.md</code>, which tells it to check <code>.context/</code></li> <li>During session: <code>PreToolUse</code> hook runs <code>ctx agent --budget 4000</code>     before each tool use</li> <li>Session end: <code>SessionEnd</code> hook saves context snapshot to <code>.context/sessions/</code></li> <li>Next session: Claude sees previous sessions and continues with context</li> </ol>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#generated-configuration","level":3,"title":"Generated Configuration","text":"<p><code>.claude/settings.local.json</code>:</p> <pre><code>{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \".*\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"ctx agent --budget 4000 2&gt;/dev/null || true\"\n          }\n        ]\n      }\n    ],\n    \"SessionEnd\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \".claude/hooks/auto-save-session.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#customizing-token-budget","level":3,"title":"Customizing Token Budget","text":"<p>Edit the PreToolUse command to change the token budget:</p> <pre><code>\"command\": \"ctx agent --budget 8000 2&gt;/dev/null || true\"\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#verifying-setup","level":3,"title":"Verifying Setup","text":"<ol> <li>Start a new Claude Code session</li> <li>Ask: \"Do you remember?\"</li> <li>Claude should cite specific context:</li> <li>Current tasks from <code>.context/TASKS.md</code></li> <li>Recent decisions or learnings</li> <li>Previous session topics from <code>.context/sessions/</code></li> </ol>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#troubleshooting","level":3,"title":"Troubleshooting","text":"Issue Solution Context not loading Check <code>ctx</code> is in PATH: <code>which ctx</code> No sessions saved Verify <code>.claude/settings.local.json</code> has <code>SessionEnd</code> hook Hook errors Check script permissions: <code>chmod +x .claude/hooks/*.sh</code> Missing sessions dir Create it: <code>mkdir -p .context/sessions</code>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#manual-context-load","level":3,"title":"Manual Context Load","text":"<p>If hooks aren't working, manually load context:</p> <pre><code># Get context packet\nctx agent --budget 4000\n\n# Or paste into conversation\ncat .context/TASKS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#slash-commands","level":3,"title":"Slash Commands","text":"<p><code>ctx init</code> installs slash commands to <code>.claude/commands/</code>. These are shortcuts you can invoke in Claude Code with <code>/command-name</code>.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#context-commands","level":4,"title":"Context Commands","text":"Command Description <code>/ctx-status</code> Show context summary (tasks, decisions, learnings) <code>/ctx-agent</code> Get AI-optimized context packet <code>/ctx-save</code> Save current session to <code>.context/sessions/</code> <code>/ctx-reflect</code> Review session and suggest what to persist","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#adding-context","level":4,"title":"Adding Context","text":"Command Description <code>/ctx-add-task</code> Add a task to TASKS.md <code>/ctx-add-learning</code> Add a learning to LEARNINGS.md <code>/ctx-add-decision</code> Add a decision with context/rationale/consequences <code>/ctx-archive</code> Archive completed tasks","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#session-history","level":4,"title":"Session History","text":"Command Description <code>/ctx-recall</code> Browse AI session history <code>/ctx-journal-enrich</code> Enrich a journal entry with frontmatter/tags <code>/ctx-journal-summarize</code> Generate summary of sessions over a time period","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#blogging","level":4,"title":"Blogging","text":"Command Description <code>/ctx-blog</code> Generate blog post from recent activity <code>/ctx-blog-changelog</code> Generate blog post from commit range with theme","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#development","level":4,"title":"Development","text":"Command Description <code>/ctx-loop</code> Generate a Ralph Loop iteration script <code>/ctx-prompt-audit</code> Analyze session logs for vague prompts","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage-examples","level":4,"title":"Usage Examples","text":"<pre><code>/ctx-status\n/ctx-add-learning \"Token refresh requires explicit cache invalidation\"\n/ctx-journal-enrich twinkly-stirring-kettle\n/ctx-journal-summarize last week\n</code></pre> <p>Slash commands support partial matching where applicable (e.g., session slugs).</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#cursor-ide","level":2,"title":"Cursor IDE","text":"<p>Cursor can use context files through its system prompt or by reading  files directly.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup","level":3,"title":"Setup","text":"<pre><code># Generate Cursor configuration\nctx hook cursor\n\n# Initialize context\nctx init --minimal\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#configuration","level":3,"title":"Configuration","text":"<p>Add to Cursor settings (<code>.cursor/settings.json</code>):</p> <pre><code>// split to multiple lines for readability\n{\n  \"ai.systemPrompt\": \"Read .context/TASKS.md and \n  .context/CONVENTIONS.md before responding. \n  Follow rules in .context/CONSTITUTION.md.\",\n}\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage","level":3,"title":"Usage","text":"<ol> <li>Open your project in Cursor</li> <li>Context files are available in the file tree</li> <li>Reference them in prompts:     \"Check .context/DECISIONS.md for our approach to...\"</li> </ol>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#manual-context-injection","level":3,"title":"Manual Context Injection","text":"<p>For more control, paste context directly:</p> <pre><code># Get AI-ready packet\nctx agent --budget 4000 | pbcopy  # macOS\nctx agent --budget 4000 | xclip  # Linux\n</code></pre> <p>Paste into Cursor's chat.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#aider","level":2,"title":"Aider","text":"<p>Aider works well with context files through its <code>--read</code> flag.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup_1","level":3,"title":"Setup","text":"<pre><code># Generate Aider configuration\nctx hook aider\n\n# Initialize context\nctx init\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#configuration_1","level":3,"title":"Configuration","text":"<p>Create <code>.aider.conf.yml</code>:</p> <pre><code>read:\n  - .context/CONSTITUTION.md\n  - .context/TASKS.md\n  - .context/CONVENTIONS.md\n  - .context/DECISIONS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage_1","level":3,"title":"Usage","text":"<pre><code># Start Aider (reads context files automatically)\naider\n\n# Or specify files explicitly\naider --read .context/TASKS.md --read .context/CONVENTIONS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#with-watch-mode","level":3,"title":"With Watch Mode","text":"<p>Run <code>ctx watch</code> alongside Aider to capture context updates:</p> <pre><code># Terminal 1: Run Aider\naider 2&gt;&amp;1 | tee /tmp/aider.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/aider.log\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#github-copilot","level":2,"title":"GitHub Copilot","text":"<p>Copilot reads open files for context. Keep context files open or reference  them in comments.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup_2","level":3,"title":"Setup","text":"<pre><code># Generate Copilot tips\nctx hook copilot\n\n# Initialize context\nctx init --minimal\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage-patterns","level":3,"title":"Usage Patterns","text":"<p>Pattern 1: Keep context files open</p> <p>Open <code>.context/CONVENTIONS.md</code> in a split pane. Copilot will reference it.</p> <p>Pattern 2: Reference in comments</p> <pre><code>// See .context/CONVENTIONS.md for naming patterns\n// Following decision in .context/DECISIONS.md: Use PostgreSQL\n\nfunction getUserById(id: string) {\n  // Copilot now has context\n}\n</code></pre> <p>Pattern 3: Paste context into Copilot Chat</p> <pre><code>ctx agent --budget 2000\n</code></pre> <p>Paste output into Copilot Chat for context-aware responses.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#windsurf-ide","level":2,"title":"Windsurf IDE","text":"<p>Windsurf supports custom instructions and file-based context.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#setup_3","level":3,"title":"Setup","text":"<pre><code># Generate Windsurf configuration\nctx hook windsurf\n\n# Initialize context\nctx init\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#configuration_2","level":3,"title":"Configuration","text":"<p>Add to Windsurf settings:</p> <pre><code>// Split to multiple lines for readability\n{\n  \"ai.customInstructions\": \"Always read .context/CONSTITUTION.md first. \n  Check .context/TASKS.md for current work. \n  Follow patterns in .context/CONVENTIONS.md.\"\n}\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage_2","level":3,"title":"Usage","text":"<p>Context files appear in the file tree. Reference them when chatting:</p> <ul> <li>\"What's in our task list?\" → AI reads <code>.context/TASKS.md</code></li> <li>\"What convention do we use for naming?\" → AI reads <code>.context/CONVENTIONS.md</code></li> </ul>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#generic-integration","level":2,"title":"Generic Integration","text":"<p>For any AI tool that can read files, use these patterns:</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#manual-context-loading","level":3,"title":"Manual Context Loading","text":"<pre><code># Get full context\nctx load\n\n# Get AI-optimized packet\nctx agent --budget 8000\n\n# Get specific file\ncat .context/TASKS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#system-prompt-template","level":3,"title":"System Prompt Template","text":"<pre><code>You are working on a project with persistent context in .context/\n\nBefore responding:\n1. Read .context/CONSTITUTION.md - NEVER violate these rules\n2. Check .context/TASKS.md for current work\n3. Follow .context/CONVENTIONS.md patterns\n4. Reference .context/DECISIONS.md for architectural choices\n\nWhen you learn something new, note it for .context/LEARNINGS.md\nWhen you make a decision, document it for .context/DECISIONS.md\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#automated-updates","level":3,"title":"Automated Updates","text":"<p>If your AI tool outputs to a log, use <code>ctx watch</code>:</p> <pre><code># Watch log file for context-update commands\nyour-ai-tool 2&gt;&amp;1 | tee /tmp/ai.log &amp;\nctx watch --log /tmp/ai.log\n</code></pre> <p>The AI can emit updates like:</p> <pre><code>&lt;context-update type=\"learning\"&gt;Important thing learned today&lt;/context-update&gt;\n&lt;context-update type=\"complete\"&gt;implement caching&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#context-update-commands","level":2,"title":"Context Update Commands","text":"<p>The <code>ctx watch</code> command parses update commands from AI output. Use this format:</p> <pre><code>&lt;context-update type=\"TYPE\" [attributes]&gt;Content&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#supported-types","level":3,"title":"Supported Types","text":"Type Target File Required Attributes <code>task</code> TASKS.md None <code>decision</code> DECISIONS.md <code>context</code>, <code>rationale</code>, <code>consequences</code> <code>learning</code> LEARNINGS.md <code>context</code>, <code>lesson</code>, <code>application</code> <code>convention</code> CONVENTIONS.md None <code>complete</code> TASKS.md None","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#simple-format-tasks-conventions-complete","level":3,"title":"Simple Format (tasks, conventions, complete)","text":"<pre><code>&lt;context-update type=\"task\"&gt;Implement rate limiting&lt;/context-update&gt;\n&lt;context-update type=\"convention\"&gt;Use kebab-case for files&lt;/context-update&gt;\n&lt;context-update type=\"complete\"&gt;rate limiting&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#structured-format-learnings-decisions","level":3,"title":"Structured Format (learnings, decisions)","text":"<p>Learnings and decisions support structured attributes for better documentation:</p> <p>Learning with full structure:</p> <pre><code>&lt;context-update type=\"learning\"\n  context=\"Debugging Claude Code hooks\"\n  lesson=\"Hooks receive JSON via stdin, not environment variables\"\n  application=\"Use jq to parse: COMMAND=$(echo $INPUT | jq -r .tool_input.command)\"\n&gt;Hook Input Format&lt;/context-update&gt;\n</code></pre> <p>Decision with full structure:</p> <pre><code>&lt;context-update type=\"decision\"\n  context=\"Need a caching layer for API responses\"\n  rationale=\"Redis is fast, well-supported, and team has experience\"\n  consequences=\"Must provision Redis infrastructure; team training on Redis patterns\"\n&gt;Use Redis for caching&lt;/context-update&gt;\n</code></pre> <p>If attributes are omitted, placeholders are inserted that should be updated manually.</p>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#legacy-format-still-supported","level":3,"title":"Legacy Format (still supported)","text":"<p>Simple format without attributes still works but creates placeholder text:</p> <pre><code>&lt;context-update type=\"learning\"&gt;Mock functions must be hoisted&lt;/context-update&gt;\n&lt;context-update type=\"decision\"&gt;Use PostgreSQL for primary database&lt;/context-update&gt;\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"integrations/#usage-with-ctx-watch","level":3,"title":"Usage with ctx watch","text":"<pre><code># Pipe AI output through watch\nyour-ai-tool | ctx watch\n\n# Or watch a log file\nctx watch --log /tmp/ai-output.log\n\n# Preview without applying\nctx watch --dry-run\n</code></pre>","path":["AI Tool Integrations"],"tags":[]},{"location":"prompting-guide/","level":1,"title":"Prompting Guide","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#prompting-guide","level":2,"title":"Prompting Guide","text":"<p>Effective prompts for working with AI assistants in <code>ctx</code>-enabled projects.</p> <p>Tip</p> <p>AI assistants may not automatically read context files.</p> <p>The right prompt triggers the right behavior. </p> <p>This guide documents prompts that reliably produce good results.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#session-start","level":2,"title":"Session Start","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#do-you-remember","level":3,"title":"\"Do you remember?\"","text":"<p>Triggers the AI to read <code>AGENT_PLAYBOOK</code>, <code>CONSTITUTION</code>,  <code>sessions/</code>, and other context files before responding.</p> <p>Use this during the start of every important session.</p> <pre><code>Do you remember what we were working on?\n</code></pre> <p>This question implies prior context exists. So, the AI checks files rather than admitting ignorance.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#whats-the-current-state","level":3,"title":"\"What's the current state?\"","text":"<p>Prompts reading of <code>TASKS.md</code>, recent sessions, and status overview.</p> <p>Use this when resuming work after a break.</p> <p>Variants:</p> <ul> <li>\"Where did we leave off?\"</li> <li>\"What's in progress?\"</li> <li>\"Show me the open tasks\"</li> </ul>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#during-work","level":2,"title":"During Work","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#why-doesnt-x-work","level":3,"title":"\"Why doesn't X work?\"","text":"<p>This triggers root cause analysis rather than surface-level fixes.</p> <p>Use this when something fails unexpectedly.</p> <p>Framing as \"why\" encourages investigation before action. The AI will trace  through code, check configurations, and identify the actual cause.</p> <p>Real Example</p> <p>\"Why can't I run /ctx-save?\" led to discovering missing permissions in settings.local.json bootstrapping—a fix that benefited all users.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#is-this-consistent-with-our-decisions","level":3,"title":"\"Is this consistent with our decisions?\"","text":"<p>This prompts checking <code>DECISIONS.md</code> before implementing.</p> <p>Use this before making architectural choices.</p> <p>Variants:</p> <ul> <li>\"Check if we've decided on this before\"</li> <li>\"Does this align with our conventions?\"</li> </ul>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-would-break-if-we","level":3,"title":"\"What would break if we...\"","text":"<p>This triggers defensive thinking and impact analysis.</p> <p>Use this before making significant changes.</p> <pre><code>What would break if we change the Settings struct?\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#before-you-start-read-x","level":3,"title":"\"Before you start, read X\"","text":"<p>This ensures specific context is loaded before work begins.</p> <p>Use this when you know the relevant context exists in a specific file.</p> <pre><code>Before you start, read .context/sessions/2026-01-20-auth-discussion.md\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#reflection-and-persistence","level":2,"title":"Reflection and Persistence","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-did-we-learn","level":3,"title":"\"What did we learn?\"","text":"<p>This prompts reflection on the session and often triggers adding learnings to <code>LEARNINGS.md</code>.</p> <p>Use this after completing a task or debugging session.</p> <p>This is an explicit reflection prompt. The AI will summarize insights and often offer to persist them.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#add-this-as-a-learningdecision","level":3,"title":"\"Add this as a learning/decision\"","text":"<p>This is an explicit persistence request.</p> <p>Use this when you have discovered something worth remembering.</p> <pre><code>Add this as a learning: \"JSON marshal escapes angle brackets by default\"\n\n# or simply.\nAdd this as a learning.\n# and let the AI autonomously infer and summarize.\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#save-context-before-we-end","level":3,"title":"\"Save context before we end\"","text":"<p>This triggers context persistence before the session closes.</p> <p>Use it at the end of the session or before switching topics.</p> <p>Variants:</p> <ul> <li>\"Let's persist what we did\"</li> <li>\"Update the context files\"</li> <li><code>/ctx-save</code> (slash command in Claude Code)</li> </ul>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#exploration-and-research","level":2,"title":"Exploration and Research","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#explore-the-codebase-for-x","level":3,"title":"\"Explore the codebase for X\"","text":"<p>This triggers thorough codebase search rather than guessing.</p> <p>Use this when you need to understand how something works.</p> <p>This works because \"Explore\" signals that investigation is needed,  not immediate action.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#how-does-x-work-in-this-codebase","level":3,"title":"\"How does X work in this codebase?\"","text":"<p>This prompts reading actual code rather than explaining general concepts.</p> <p>Use this to understand the existing implementation.</p> <pre><code>How does session saving work in this codebase?\n</code></pre>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#find-all-places-where-x","level":3,"title":"\"Find all places where X\"","text":"<p>This triggers a comprehensive search across the codebase.</p> <p>Use this before refactoring or understanding the impact.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#meta-and-process","level":2,"title":"Meta and Process","text":"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-should-we-document-from-this","level":3,"title":"\"What should we document from this?\"","text":"<p>This prompts identifying learnings, decisions, and conventions worth persisting.</p> <p>Use this after complex discussions or implementations.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#is-this-the-right-approach","level":3,"title":"\"Is this the right approach?\"","text":"<p>This invites the AI to challenge the current direction.</p> <p>Use this when you want a sanity check.</p> <p>This works because it allows AI to disagree.  AIs often default to agreeing; this prompt signals you want an  honest assessment.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#what-am-i-missing","level":3,"title":"\"What am I missing?\"","text":"<p>This prompts thinking about edge cases, overlooked requirements, or unconsidered approaches.</p> <p>Use this before finalizing a design or implementation.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#anti-patterns","level":2,"title":"Anti-Patterns","text":"<p>Based on our <code>ctx</code> development experience (i.e., \"sipping our own champagne\") so far, here are some prompts that tend to produce poor results:</p> Prompt Problem Better Alternative \"Fix this\" Too vague, may patch symptoms \"Why is this failing?\" \"Make it work\" Encourages quick hacks \"What's the right way to solve this?\" \"Just do it\" Skips planning \"Plan this, then implement\" \"You should remember\" Confrontational \"Do you remember?\" \"Obviously...\" Discourages questions State the requirement directly \"Idiomatic X\" Triggers language priors \"Follow project conventions\"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#quick-reference","level":2,"title":"Quick Reference","text":"Goal Prompt Load context \"Do you remember?\" Resume work \"What's the current state?\" Debug \"Why doesn't X work?\" Validate \"Is this consistent with our decisions?\" Impact analysis \"What would break if we...\" Reflect \"What did we learn?\" Persist \"Add this as a learning\" Explore \"How does X work in this codebase?\" Sanity check \"Is this the right approach?\" Completeness \"What am I missing?\"","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#writing-tasks-as-prompts","level":2,"title":"Writing Tasks as Prompts","text":"<p>Tasks in <code>TASKS.md</code> are indirect prompts to the AI. How you write them shapes how the AI approaches the work.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#state-the-deliverable-not-just-steps","level":3,"title":"State the Deliverable, Not Just Steps","text":"<p>Bad task (implementation-focused): <pre><code>- [ ] T1.1.0: Parser system\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n</code></pre></p> <p>The AI may complete all subtasks but miss the actual goal. What does \"Parser system\" deliver to the user?</p> <p>Good task (deliverable-focused): <pre><code>- [ ] T1.1.0: Parser CLI command\n  **Deliverable**: `ctx recall list` command that shows parsed sessions\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n</code></pre></p> <p>Now the AI knows the subtasks serve a specific user-facing deliverable.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#use-acceptance-criteria","level":3,"title":"Use Acceptance Criteria","text":"<p>For complex tasks, add explicit \"done when\" criteria:</p> <pre><code>- [ ] T2.0: Authentication system\n  **Done when**:\n  - [ ] User can register with email\n  - [ ] User can log in and get a token\n  - [ ] Protected routes reject unauthenticated requests\n</code></pre> <p>This prevents premature \"task complete\" when only the implementation details are done but the feature doesn't actually work.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#subtasks-parent-task","level":3,"title":"Subtasks ≠ Parent Task","text":"<p>Completing all subtasks does not mean the parent task is complete.</p> <p>The parent task describes what the user gets. Subtasks describe how to build it.</p> <p>Always re-read the parent task description before marking it complete. Verify the stated deliverable exists and works.</p>","path":["Prompting Guide"],"tags":[]},{"location":"prompting-guide/#contributing","level":2,"title":"Contributing","text":"<p>Found a prompt that works well? Open an issue or PR with:</p> <ol> <li>The prompt text</li> <li>What behavior it triggers</li> <li>When to use it</li> <li>Why it works (optional but helpful)</li> </ol>","path":["Prompting Guide"],"tags":[]},{"location":"security/","level":1,"title":"Security","text":"","path":["Security"],"tags":[]},{"location":"security/#reporting-vulnerabilities","level":2,"title":"Reporting Vulnerabilities","text":"<p>At <code>ctx</code> we take security very seriously.</p> <p>If you discover a security vulnerability in <code>ctx</code>, please report it responsibly.</p> <p>Do NOT open a public issue for security vulnerabilities.</p>","path":["Security"],"tags":[]},{"location":"security/#email","level":3,"title":"Email","text":"<p>Send details to security@ctx.ist</p>","path":["Security"],"tags":[]},{"location":"security/#github-private-reporting","level":3,"title":"GitHub Private Reporting","text":"<ol> <li>Go to the Security tab</li> <li>Click \"Report a vulnerability\"</li> <li>Provide a detailed description</li> </ol>","path":["Security"],"tags":[]},{"location":"security/#what-to-include","level":3,"title":"What to Include","text":"<ul> <li>Description of the vulnerability</li> <li>Steps to reproduce</li> <li>Potential impact</li> <li>Suggested fix (if any)</li> </ul>","path":["Security"],"tags":[]},{"location":"security/#response-timeline","level":3,"title":"Response Timeline","text":"Stage Timeframe Acknowledgment Within 48 hours Initial assessment Within 7 days Resolution target Within 30 days (depending on severity)","path":["Security"],"tags":[]},{"location":"security/#security-design","level":2,"title":"Security Design","text":"<p><code>ctx</code> is designed with security in mind:</p> <ul> <li>No secrets in context: The constitution explicitly forbids storing   secrets, tokens, API keys, or credentials in <code>.context/</code> files</li> <li>Local only: ctx runs entirely locally with no external network calls</li> <li>No code execution: ctx reads and writes Markdown files only; it does    not execute arbitrary code</li> <li>Git-tracked: Core context files are meant to be committed, so they should   never contain sensitive data. Exception: <code>sessions/</code> and <code>journal/</code> contain   raw conversation data and should be gitignored</li> </ul>","path":["Security"],"tags":[]},{"location":"security/#best-practices","level":2,"title":"Best Practices","text":"<ol> <li>Review before committing: Always review <code>.context/</code> files before committing</li> <li>Use .gitignore: If you must store sensitive notes locally,    add them to <code>.gitignore</code></li> <li>Drift detection: Run <code>ctx drift</code> to check for potential issues</li> </ol>","path":["Security"],"tags":[]},{"location":"security/#attribution","level":2,"title":"Attribution","text":"<p>We appreciate responsible disclosure and will acknowledge security researchers who report valid vulnerabilities (unless they prefer to remain anonymous).</p>","path":["Security"],"tags":[]},{"location":"versions/","level":1,"title":"Version History","text":"<p>Documentation snapshots for each release. Click a version to view the  docs as they were at that release.</p>","path":["Version History"],"tags":[]},{"location":"versions/#releases","level":2,"title":"Releases","text":"Version Release Date Documentation v0.1.2 2026-01-27 View docs v0.1.1 2026-01-26 View docs v0.1.0 2026-01-25 View docs","path":["Version History"],"tags":[]},{"location":"versions/#latest","level":2,"title":"Latest","text":"<p>The main documentation always reflects the latest development version.</p> <p>For the most recent stable release, see  v0.1.2.</p>","path":["Version History"],"tags":[]},{"location":"versions/#changelog","level":2,"title":"Changelog","text":"<p>For detailed changes between versions, see the  GitHub Releases page.</p>","path":["Version History"],"tags":[]},{"location":"blog/","level":1,"title":"Blog","text":"<p>Stories, insights, and lessons learned from building and using ctx.</p>","path":["Blog"],"tags":[]},{"location":"blog/#posts","level":2,"title":"Posts","text":"","path":["Blog"],"tags":[]},{"location":"blog/#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development","level":3,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"<p>Jose Alekhinne / January 27, 2026</p> <p>What happens when you build a tool designed to give AI memory, using that very  same tool to remember what you're building? This is the story of ctx—how it  evolved from a hasty \"YOLO mode\" experiment to a disciplined system for  persistent AI context, and what we learned along the way.</p> <p>Topics: dogfooding, AI-assisted development, Ralph Loop, session  persistence, architectural decisions</p> <p>More posts coming soon.</p>","path":["Blog"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/","level":1,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"<p>Jose Alekhinne / 2026-01-27</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development","level":1,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"<p>What happens when you build a tool designed to give AI memory, using that very  same tool to remember what you are building? </p> <p>This is the story of <code>ctx</code>, how it evolved from a hasty \"YOLO mode\" experiment  to a disciplined system for persistent AI context, and what I have  learned along the way.</p> <p>Context is a Record</p> <p>Context is a persistent record.</p> <p>By \"context\", I don’t mean model memory or stored thoughts: </p> <p>I mean the durable record of decisions, learnings, and intent  that normally evaporates between sessions.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#ai-amnesia","level":2,"title":"AI Amnesia","text":"<p>Every developer who works with AI code generators knows the frustration:  you have a deep, productive session where the AI understands your codebase,  your conventions, your decisions. And then you close the terminal. </p> <p>Tomorrow it's a blank slate. The AI has forgotten everything.</p> <p>That is \"reset amnesia\", and it's not just annoying: it's expensive. </p> <p>Every session starts with re-explaining context, re-reading files,  re-discovering decisions that were already made.</p> <p>I Needed Context</p> <p>I don't want to lose this discussion...  I am a brain-dead developer YOLO'ing my way out</p> <p>☝️ that's exactly what I said to Claude when I first started working on <code>ctx</code>.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-genesis","level":2,"title":"The Genesis","text":"<p>The project started as \"Active Memory\" (<code>amem</code>): a CLI tool to persist AI  context across sessions. </p> <p>The core idea was simple: create a <code>.context/</code> directory with structured  Markdown files for decisions, learnings, tasks, and conventions.  The AI reads these at session start and writes to them before the session ends.</p> <p>The first commit was just scaffolding. But within hours, the  Ralph Loop—an iterative AI development workflow—had produced a working CLI:</p> <pre><code>feat(cli): implement amem init command\nfeat(cli): implement amem status command\nfeat(cli): implement amem add command\nfeat(cli): implement amem agent command\n...\n</code></pre> <p>Fourteen core commands shipped in rapid succession. </p> <p>I was YOLO'ing like there was no tomorrow: auto-accept every change, let the AI run free, ship features fast.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-meta-experiment-using-amem-to-build-amem","level":2,"title":"The Meta-Experiment: Using <code>amem</code> to Build <code>amem</code>","text":"<p>Here's where it gets interesting: On January 20<sup>th</sup>, I asked: </p> <p>\"Can I use <code>amem</code> to help you remember this context when I restart?\"</p> <p>The answer was yes—but with a gap: </p> <p>Auto-load worked (via Claude Code's <code>PreToolUse</code> hook), but auto-save was  missing. If the user quit with Ctrl+C, everything since the last manual save  was lost.</p> <p>That session became the first real test of the system. </p> <p>Here is the first session file we recorded:</p> <pre><code>## Key Discussion Points\n\n### 1. amem vs Ralph Loop - They're Separate Systems\n\n**User's question**: \"How do I use the binary to recreate this project?\"\n\n**Answer discovered**: amem is for context management, Ralph Loop is for \ndevelopment workflow. They're complementary but separate.\n\n### 2. Two Tiers of Context Persistence\n\n| Tier      | What                        | Why                           | Where                  |\n|-----------|-----------------------------|-------------------------------|------------------------|\n| Curated   | Learnings, decisions, tasks | Quick reload, token-efficient | .context/*.md          |\n| Full dump | Entire conversation         | Safety net, nothing lost      | .context/sessions/*.md |\n</code></pre> <p>This session file—written by the AI to preserve its own context—became the  template for how <code>ctx</code> handles session persistence.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-rename","level":2,"title":"The Rename","text":"<p>By January 21<sup>st</sup>, I realized \"Active Memory\" was too generic, and (arguably) too marketing-smelly. </p> <p>Besides, the binary was already called <code>ctx</code> (short for Context),  the directory was <code>.context/</code>, and the slash commands would be <code>/ctx-*</code>. </p> <p>So it followed that the project should be renamed to <code>ctx</code> to make things  make sense.</p> <p>The rename touched 100+ files but was clean—a find-and-replace with Go's  type system catching any misses.</p> <p>The git history tells the story:</p> <pre><code>0e8f6bb feat: rename amem to ctx and add Claude Code integration\n87dcfa1 README.\n4f0e195 feat: separate orchestrator directive from agent tasks\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#yolo-mode-fast-but-dangerous","level":2,"title":"YOLO Mode: Fast, But Dangerous","text":"<p>The Ralph Loop made feature development incredibly fast. </p> <p>But it created technical debt that I didn't notice until later.</p> <p>A comparison session on January 25<sup>th</sup> revealed the patterns:</p> YOLO Pattern What We Found <code>\"TASKS.md\"</code> scattered in 10 files Same string literal everywhere, no constants <code>dir + \"/\" + file</code> Should be <code>filepath.Join()</code> Monolithic <code>cli_test.go</code> (1500+ lines) Tests disconnected from implementations <code>package initcmd</code> in <code>init/</code> folder Go's \"init\" is reserved—subtle naming collision <p>Here is another analysis made by <code>ctx</code>:</p> <pre><code>● Based on my analysis, here are the key differences:\n\nYOLO Mode (Pre-040ce99)\n- Feature-first: Added slash commands, tests, templates rapidly\n- Scattered magic strings: \"TASKS.md\", \"decision\", \".context\" spread across files\n- Quick file creation: New files without organizational patterns\n- Working but inconsistent: Code functioned but lacked systematic structure\n\nHuman-Guided Mode (Post-040ce99)\n- Consolidation focus: Centralized constants in config package\n- Consistent naming: Dir, File, Filename, UpdateType prefixes\n- Self-referential constants: FileType map uses constants as keys, not literals\n- Proper path construction: filepath.Join() instead of +\"/\"+\n- Colocated tests: Tests next to implementations\n- Canonical naming: Package name = folder name\n</code></pre> <p>The fix required a human-guided refactoring session.</p> <p>We introduced <code>internal/config/config.go</code> with semantic prefixes:</p> <pre><code>const (\n    DirContext     = \".context\"\n    DirArchive     = \"archive\"\n    DirSessions    = \"sessions\"\n    FilenameTask   = \"TASKS.md\"\n    UpdateTypeTask = \"task\"\n)\n</code></pre> <p>What I begrudgingly learned was:  YOLO mode is effective for velocity but accumulates debt. </p> <p>So I took a mental note to schedule periodic consolidation sessions  from that point onward.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-dogfooding-test-that-failed","level":2,"title":"The Dogfooding Test That Failed","text":"<p>On January 21<sup>st</sup>, I ran an experiment: have another Claude instance rebuild  <code>ctx</code> from scratch using only the specs and <code>PROMPT.md</code>. </p> <p>The Ralph Loop ran, all tasks got checked off, the loop exited successfully.</p> <p>But the binary was broken!</p> <p>Commands just printed help text instead of executing. </p> <p>All tasks were marked \"complete\" but the implementation didn't work.</p> <p>Here's what <code>ctx</code> discovered:</p> <pre><code>## Key Findings\n\n### Dogfooding Binary Is Broken\n- Commands don't execute — they just print root help text\n- All tasks were marked complete but binary doesn't work\n- Lesson: \"tasks checked off\" ≠ \"implementation works\"\n</code></pre> <p>This was humbling—to say the least.</p> <p>I realized, I had the same blind spot in my own codebase: no integration tests that actually invoked the binary. </p> <p>So I added:</p> <ul> <li>Integration tests for all commands</li> <li>Coverage targets (60-80% per package)</li> <li>Smoke tests in CI</li> <li>A constitution rule: \"All code must pass tests before commit\"</li> </ul>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-constitution-versus-conventions","level":2,"title":"The Constitution versus Conventions","text":"<p>As lessons accumulated, there was the temptation to add everything to  <code>CONSTITUTION.md</code> as \"inviolable rules\". </p> <p>But I resisted.</p> <p>The constitution should contain only truly inviolable invariants:</p> <ul> <li>Security (no secrets, no customer data)</li> <li>Quality (tests must pass)</li> <li>Process (decisions need records)</li> <li><code>ctx</code> invocation (always use <code>PATH</code>, never fallback)</li> </ul> <p>Everything else—coding style, file organization, naming  conventions—should go in to <code>CONVENTIONS.md</code>. </p> <p>Here's how <code>ctx</code> explained why the distinction was important: </p> <p>\"Overly strict constitution creates friction and gets ignored.  Conventions can be bent; constitution cannot.\" — Decision record, 2026-01-25</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#hooks-harder-than-they-look","level":2,"title":"Hooks: Harder Than They Look","text":"<p>Claude Code hooks seemed simple: run a script before/after certain events. </p> <p>But I hit multiple gotchas:</p> <p>1. Key names matter</p> <pre><code>// WRONG - \"Invalid key in record\" error\n\"PreToolUseHooks\": [...]\n\n// RIGHT\n\"PreToolUse\": [...]\n</code></pre> <p>2. Blocking requires specific output</p> <pre><code># WRONG - just exits, doesn't block\nexit 1\n\n# RIGHT - JSON output + exit 0\necho '{\"decision\": \"block\", \"reason\": \"Use ctx from PATH\"}'\nexit 0\n</code></pre> <p>3. Go's JSON escaping</p> <p><code>json.Marshal</code> escapes <code>&gt;</code>, <code>&lt;</code>, <code>&amp;</code> as unicode (<code>\\u003e</code>) by default. </p> <p>When generating shell commands in JSON:</p> <pre><code>encoder := json.NewEncoder(file)\nencoder.SetEscapeHTML(false) // Prevent 2&gt;/dev/null → 2\\u003e/dev/null\n</code></pre> <p>4. Regex overfitting</p> <p>Our hook to block non-PATH <code>ctx</code> invocations initially matched too broadly:</p> <pre><code># WRONG - matches /home/user/ctx/internal/file.go (ctx as directory)\n(/home/|/tmp/|/var/)[^ ]*ctx[^ ]*\n\n# RIGHT - matches ctx as binary only\n(/home/|/tmp/|/var/)[^ ]*/ctx( |$)\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-session-files","level":2,"title":"The Session Files","text":"<p>By the time of this writing this project's <code>ctx</code> sessions (<code>.context/sessions/</code>)  contains 40+ files from this project's development.</p> <p>They are not part of the source code due to security, privacy, and size concerns.</p> <p>However, they are invaluable for the project's progress.</p> <p>Each session file is a timestamped Markdown with:</p> <ul> <li>Summary of what has been accomplished</li> <li>Key decisions made</li> <li>Learnings discovered</li> <li>Tasks for the next session</li> <li>Technical context (platform, versions)</li> </ul> <p>These files are not auto-loaded (that would bust the token budget). </p> <p>They are what I see as the \"archaeological record\" of <code>ctx</code>: When the AI needs deeper information about why something was done, it digs into the sessions.</p> <p>Auto-generated session files use a naming convention:</p> <pre><code>2026-01-23-115432-session-prompt_input_exit-summary.md\n2026-01-25-220244-manual-save.md\n2026-01-27-052107-session-other-summary.md\n</code></pre> <p>Also, the <code>SessionEnd</code> hook captures transcripts automatically.  Even <code>Ctrl+C</code>is caught.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-decision-log-18-architectural-decisions","level":2,"title":"The Decision Log: 18 Architectural Decisions","text":"<p><code>ctx</code> helps record every significant architectural choice in  <code>.context/DECISIONS.md</code>. </p> <p>Here are some highlights:</p> <p>Reverse-chronological order (2026-01-27)</p> <pre><code>**Context**: With chronological order, oldest items consume tokens first, and\nnewest (most relevant) items risk being truncated.\n\n**Decision**: Use reverse-chronological order (newest first) for DECISIONS.md\nand LEARNINGS.md.\n</code></pre> <p>PATH over hardcoded paths (2026-01-21)</p> <pre><code>**Context**: Original implementation hardcoded absolute paths in hooks.\nThis breaks when sharing configs with other developers.\n\n**Decision**: Hooks use `ctx` from PATH. `ctx init` checks PATH before proceeding.\n</code></pre> <p>Generic core with Claude enhancements (2026-01-20)</p> <pre><code>**Context**: ctx should work with any AI tool, but Claude Code users could\nbenefit from deeper integration.\n\n**Decision**: Keep ctx generic as the core tool, but provide optional\nClaude Code-specific enhancements.\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-learning-log-24-gotchas-and-insights","level":2,"title":"The Learning Log: 24 Gotchas and Insights","text":"<p>The <code>.context/LEARNINGS.md</code> file captures gotchas that would otherwise be  forgotten. Each has Context, Lesson, and Application sections:</p> <p>CGO on ARM64</p> <pre><code>**Context**: `go test` failed with `gcc: error: unrecognized command-line option '-m64'`\n**Lesson**: On ARM64 Linux, CGO causes cross-compilation issues. Always use `CGO_ENABLED=0`.\n</code></pre> <p>Claude Code skills format</p> <pre><code>**Lesson**: Claude Code skills are Markdown files in .claude/commands/ with `YAML`\nfrontmatter (*description, argument-hint, allowed-tools*). Body is the prompt.\n</code></pre> <p>\"Do you remember?\" handling</p> <pre><code>**Lesson**: In a `ctx`-enabled project, \"*do you remember?*\" has an obvious meaning:\ncheck the `.context/` files. Don't ask for clarification—just do it.\n</code></pre>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#task-archives-the-completed-work","level":2,"title":"Task Archives: The Completed Work","text":"<p>Completed tasks are archived to <code>.context/archive/</code> with timestamps. </p> <p>The archive from January 23<sup>rd</sup> shows 13 phases of work:</p> <ul> <li>Phase 1: Project Scaffolding (Go module, Cobra CLI)</li> <li>Phase 2-4: Core Commands    (init, status, agent, add, complete, drift, sync, compact, watch, hook)</li> <li>Phase 5: Session Management (save, list, load, parse, --extract)</li> <li>Phase 6: Claude Code Integration (hooks, settings, CLAUDE.md handling)</li> <li>Phase 7: Testing &amp; Verification</li> <li>Phase 8: Task Archival</li> <li>Phase 9: Slash Commands</li> <li>Phase 9b: Ralph Loop Integration</li> <li>Phase 10: Project Rename</li> <li>Phase 11: Documentation</li> <li>Phase 12: Timestamp Correlation</li> <li>Phase 13: Rich Context Entries</li> </ul> <p>That's an impressive 173 commits across 8 days of development.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#what-i-learned-about-ai-assisted-development","level":2,"title":"What I Learned About AI-Assisted Development","text":"<p>1. Memory changes everything</p> <p>When the AI remembers decisions, it doesn't repeat mistakes. When it knows  your conventions, it follows them. </p> <p><code>ctx</code> makes the AI a better collaborator because it's not starting from zero.</p> <p>2. Two-tier persistence works</p> <p>Curated context (<code>DECISIONS.md</code>, <code>LEARNINGS.md</code>, <code>TASKS.md</code>) is for  quick reload. </p> <p>Full session dumps are for archaeology. </p> <p>It's a futile effort to try to fit everything in the token budget.</p> <p>Persist more, load less.</p> <p>3. YOLO mode has its place</p> <p>For rapid prototyping, letting the AI run free is effective. </p> <p>But I had to schedule consolidation sessions. </p> <p>Technical debt accumulates silently.</p> <p>4. The constitution should be small</p> <p>Only truly inviolable rules go in <code>CONSTITUTION.md</code>.  Everything else is a convention. </p> <p>If you put too much in the constitution, it will get ignored.</p> <p>5. Verification is non-negotiable</p> <p>\"All tasks complete\" means nothing if you haven't run the tests. </p> <p>Integration tests that invoke the actual binary caught bugs that  the unit tests missed.</p> <p>6. Session files are underrated</p> <p>The ability to grep through 40 session files and find exactly when and why a  decision was made helped me a lot. </p> <p>It's not about loading them into context: It is about having them when you  need them.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-future-recall-system","level":2,"title":"The Future: Recall System","text":"<p>The next phase of <code>ctx</code> is the Recall System:</p> <ul> <li>Parser: Parse session capture markdowns, enrich with JSONL data</li> <li>Renderer: Goldmark + Chroma for syntax highlighting, dark mode UI</li> <li>Server: Local HTTP server for browsing sessions</li> <li>Search: Inverted index for searching across sessions</li> <li>CLI: <code>ctx recall serve &lt;path&gt;</code> to start the server</li> </ul> <p>The goal is to make the archaeological record browsable—not just <code>grep</code>-able.</p> <p>Because not everyone always lives in the terminal—me included.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#conclusion","level":2,"title":"Conclusion","text":"<p>Building <code>ctx</code> using ctx was a meta-experiment in AI-assisted development. </p> <p>I learned that memory isn't just convenient—it's transformative:</p> <ul> <li>An AI that remembers your decisions doesn't repeat mistakes.</li> <li>An AI that knows your conventions doesn't need them re-explained.</li> </ul> <p>If you are reading this, chances are that you already have heard about <code>ctx</code>.</p> <ul> <li><code>ctx</code> is open source at  github.com/ActiveMemory/ctx,</li> <li>and the documentation lives at ctx.ist.</li> </ul> <p>If you're a mere mortal tired of reset amnesia, give <code>ctx</code> a try. </p> <p>And when you do, check <code>.context/sessions/</code> sometime. </p> <p>The archaeological record might surprise you.</p> <p>This blog post was written with the help of <code>ctx</code> with full access to the  <code>ctx</code> session files, decision log, learning log, task archives, and  git history of <code>ctx</code>—The meta continues.</p>","path":["Blog","Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]}]}
\ No newline at end of file
diff --git a/site/security/index.html b/site/security/index.html
index 15da3bd50..35eb049ad 100644
--- a/site/security/index.html
+++ b/site/security/index.html
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -383,7 +383,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -392,7 +392,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
@@ -935,8 +935,9 @@ <h2 id="security-design">Security Design<a class="headerlink" href="#security-de
 <li><strong>Local only</strong>: ctx runs entirely locally with no external network calls</li>
 <li><strong>No code execution</strong>: ctx reads and writes Markdown files only; it does 
   not execute arbitrary code</li>
-<li><strong>Git-tracked</strong>: All context files are meant to be committed, so they should
-  never contain sensitive data</li>
+<li><strong>Git-tracked</strong>: Core context files are meant to be committed, so they should
+  never contain sensitive data. Exception: <code>sessions/</code> and <code>journal/</code> contain
+  raw conversation data and should be gitignored</li>
 </ul>
 <h2 id="best-practices">Best Practices<a class="headerlink" href="#best-practices" title="Permanent link">&para;</a></h2>
 <ol>
diff --git a/site/sitemap.xml b/site/sitemap.xml
index 0b477acfa..24f3941fb 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -16,7 +16,7 @@
         <loc>https://ctx.ist/context-files/</loc>
       </url>
       <url>
-        <loc>https://ctx.ist/ralph-loop/</loc>
+        <loc>https://ctx.ist/autonomous-loop/</loc>
       </url>
       <url>
         <loc>https://ctx.ist/integrations/</loc>
diff --git a/site/versions/index.html b/site/versions/index.html
index 46371b0b4..352b48396 100644
--- a/site/versions/index.html
+++ b/site/versions/index.html
@@ -25,7 +25,7 @@
       
       
       <link rel="icon" href="../images/favicon-32.png">
-      <meta name="generator" content="zensical-0.0.17">
+      <meta name="generator" content="zensical-0.0.20">
     
     
       
@@ -383,7 +383,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../ralph-loop/" class="md-nav__link">
+      <a href="../autonomous-loop/" class="md-nav__link">
         
   
   
@@ -392,7 +392,7 @@
   <span class="md-ellipsis">
     
   
-    ralph + ctx
+    Autonomous Loops
   
 
     
diff --git a/zensical.toml b/zensical.toml
index 66065aa07..4eccea801 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -26,7 +26,7 @@ nav = [
   { "ctx and Similar Tools" = "comparison.md"},
   { "CLI Reference" = "cli-reference.md" },
   { "Context Files" = "context-files.md" },
-  { "ralph + ctx" = "ralph-loop.md" },
+  { "Autonomous Loops" = "autonomous-loop.md" },
   { "Integrations" = "integrations.md" },
   { "Version History" = "versions.md" },
   { "Security" = "security.md" },