diff --git a/docs/user-guide/analyze.md b/docs/user-guide/analyze.md
new file mode 100644
index 0000000..9107178
--- /dev/null
+++ b/docs/user-guide/analyze.md
@@ -0,0 +1,112 @@
+# 🔎 Analyze Guide
+
+The `analyze` command performs a deep investigation of a codebase and produces a clean, educational Markdown report. It is designed as a **didactic training tool** for learning developers, hobbyists, and anyone onboarding to a new project.
+
+### Why use Analyze?
+
+- **Educational Focus**: Explains not just *what* the code does, but *how* each function/method works and *why* it was included.
+- **Polyglot Support**: Works for Go, Python, Java, C90, Rexx, Perl, JavaScript/TypeScript, and more via custom prompts.
+- **Project-Aware**: Includes tech stack, module relationships, object ↔ data flow, and suggested learning paths.
+- **Transactional**: Always shows a preview and requires explicit confirmation before writing (unless `--yes`).
+
+### Usage
+
+```bash
+# Analyze current directory (preview + confirmation)
+grokkit analyze
+
+# Analyze a specific directory
+grokkit analyze --dir ./legacy-c90-project
+
+# Write to custom file or stdout
+grokkit analyze --output my-analysis.md
+grokkit analyze --output -          # stdout only
+
+# Skip confirmation (useful in scripts/CI)
+grokkit analyze --yes
+
+# Use a different model
+grokkit analyze --model grok-4
+```
+
+
+### Options
+
+| Flag     | Short | Description                | Default           |
+|----------|-------|----------------------------|-------------------|
+| --dir    |       | Repository root to analyze | Current directory |
+| --output | -o    | Output file (- for stdout) | analyze.md        |
+| --yes    | -y    | Skip confirmation prompt   | false             |
+| --model  | -m    | Override model             | from config       |
+
+
+### Prompt Discovery (Automatic & Developer-First)
+
+Grokkit automatically locates a language-specific system prompt using this exact order:
+
+1. `{PROJECT_ROOT}/.grokkit/prompts/{language}.md` ← preferred (project-specific)
+2. `~/.config/grokkit/prompts/{language}.md` ← global fallback
+
+Language is detected automatically via `internal/linter`.
+
+If no prompt is found for the detected language, Grokkit prints a clear, actionable error message with exact paths where to create the file and exits without running analysis.
+
+Supported languages (out of the box via the linter): `go`, `python`, `javascript`, `typescript`, `java`, `c`, `cpp`, `rust`, `ruby`, `perl`, `shell`, and others.
+
+### Adding Support for New Languages (C90, Rexx, Perl, etc.)
+
+1. Create a new prompt file in .grokkit/prompts/ (or globally in ~/.config/grokkit/prompts/).
+2. Name it after the language: `c90.md`, `rexx.md`, `perl.md`, etc.
+3. Make it educational and specific to the language’s idioms.
+
+Example starter for c90.md:
+
+```
+You are an expert C90 educator helping a hobbyist or learning developer understand legacy C code.
+
+Generate a single, clean, educational Markdown report with these exact sections:
+
+# Project Analysis: [Inferred Project Name]
+
+## Tech Stack & Layout
+...
+
+## Function & Method Reference
+For every function:
+- What it does
+- How it works (memory management, K&R vs ANSI style, etc.)
+- Why it exists
+
+## Learning Path & Gotchas
+...
+Be precise, encouraging, and focus on C90 constraints and common pitfalls.
+```
+
+### Safety Features
+
+* Preview: Shows the first ~60 lines of the generated report before writing.
+* Confirmation: Requires explicit y/N unless --yes is used.
+* No Auto-Write: Nothing is saved to disk without user approval.
+* Git-Friendly: The generated analyze.md can be reviewed with git diff, reverted with git restore, or committed as documentation.
+
+### Best Practices
+
+* Run grokkit analyze early when exploring a new codebase.
+* Customize the prompt in `.grokkit/prompts/` for your specific learning goals (e.g., focus on security for C, concurrency for Go, or monadic patterns for Rexx/Perl).
+* Combine with other commands: use `analyze` for high-level understanding, then `review` for deeper logic critique, or `lint` for style issues.
+* Commit the generated report if it helps team onboarding or personal reference.
+* For very large projects, consider running with a faster model (--model grok-4-mini) or limiting scope with a project-specific prompt.
+
+### Example Workflow
+
+```
+# 1. Analyze the project
+grokkit analyze
+
+# 2. Review the generated report
+less analyze.md
+
+# 3. Commit as documentation (optional)
+git add analyze.md
+grokkit commit
+```
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
index 5c503b7..bf77e00 100644
--- a/docs/user-guide/index.md
+++ b/docs/user-guide/index.md
@@ -29,6 +29,7 @@ Welcome to the full user documentation for **Grokkit** — a fast, native Go CLI
 - **[🤖 Query](query.md)** — One-shot programming-focused queries
 - **[🔍 Review](review.md)** — AI code review of the current repo/directory
 - **[🔧 Lint](lint.md)** — Lint + AI-suggested fixes
+- - **[🔎 Analyze](analyze.md)** — Deep educational analysis of any codebase with custom language prompts.
 - **[📖 Docs](docs.md)** — Generate documentation comments
 - **[Completion](completion.md)** — Generate shell completion scripts
 - **[🏷️ Version](version.md)** — Print version information