# Feature: grokkit analyze — Deep project investigation & didactic report

**Description**
New command `grokkit analyze` that takes a repository root (default: `.`), performs a full static + semantic analysis, and outputs a single, readable Markdown report.

The report is educational: it explains the tech stack, how every public function/method works, why it exists, module inter-relationships, and (when relevant) object ↔ DB schema mappings.

**Acceptance Criteria**
- [ ] Cobra command `analyze` in `cmd/analyze.go`
- [ ] Supports `--dir`, `--output` (stdout / file), `--model`, `--yes` (skip confirmation)
- [ ] Uses existing `internal/linter` for language detection + file discovery
- [ ] Uses `internal/grok` (StreamSilent + structured prompt) for the heavy lifting
- [ ] Transactional: always shows preview of the generated report + `y/N` confirmation before writing to disk (unless `--yes`)
- [ ] Full user-guide doc: `docs/user-guide/analyze.md` (usage, safety, best practices, example output)
- [ ] Updates to `docs/user-guide/index.md`, main README, and `docs/index.md`
- [ ] Unit tests + integration test that runs on a temp test repo
- [ ] Follows architecture: thin cmd layer, structured logging, Git safety, no new heavy deps
- [ ] Report sections (enforced by system prompt):
  - Tech Stack & Project Layout
  - Module / Package Overview + inter-relationships
  - Function/Method Reference (how it works + why it was included)
  - Object ↔ DB Schema Mappings (if applicable)
  - Suggested Learning Path / Gotchas

**Implementation Plan**
1. Add command skeleton + flags (model after `review.go` + `pr-describe.go`)
2. File discovery + language batching (reuse `internal/linter`)
3. Build rich context prompt (project tree + key files + git metadata)
4. Single Grok call (or smart multi-call if project is huge) → clean Markdown
5. Diff-style preview + confirmation (even for stdout, show first ~50 lines)
6. Write / print report
7. Docs + tests

**Priority**  
High — this is the exact “didactic training tool” the project has been missing.