feat(02-01): rewrite setup.sh with dependency checker, OS detection, color output, CLI args

.dev/notes.md

@@ -0,0 +1,81 @@
+## /gsd:discuss-phase — “vision decision” checklist
+
+These phases need your input because the plans had to assume UX/presentation details.
+
+### Discuss first (highest risk / most UX ambiguity)
+
+- **Phase 3 — Onboarding Wizard** (`/gsd:discuss-phase 3`)
+  - **Why**: user-facing interactive CLI
+  - **Decide**: question flow, presentation style, validation behavior, help text, branching vs linear
+
+- **Phase 8 — Rolling Tracker & Hedge Sizer** (`/gsd:discuss-phase 8`)
+  - **Why**: most complex phase (6 plans); CLI design heavy
+  - **Decide**: subcommand naming, output format (`status` / `suggest-roll` / `history`), how roll suggestions display
+
+- **Phase 10 — Template Engine** (`/gsd:discuss-phase 10`)
+  - **Why**: visual interactive product
+  - **Decide**: explorer layout, node appearance, interaction patterns (click / hover / drag), color scheme
+
+- **Phase 11 — Self-Assessment & Topics** (`/gsd:discuss-phase 11`)
+  - **Why**: interactive UX choices
+  - **Decide**: 4-state cycling behavior, guided vs standard vs YOLO differences, topic content depth
+
+- **Phase 12 — Maya / CLI / Landing** (`/gsd:discuss-phase 12`)
+  - Landing page design + CLI ergonomics (templates exist; builds on phases 10–11)
+- **Phase 9 — SQQQ vs Puts** (`/gsd:discuss-phase 9`)
+  - Mostly presentation (math/formulas fixed by research)
+- **Phase 7 — Total Return** (`/gsd:discuss-phase 7`)
+  - Mainly CLI output formatting (narrow scope; follows existing patterns)
+
+### Skip (infrastructure; minimal gray areas)
+
+- **Phase 1 — Git Scrub**: tool-dictated (git-filter-repo, gitleaks)
+- **Phase 2 — Setup Automation**: scripts/automation, minimal UX
+- **Phase 4 — Polish & Hooks**: mostly technical (SIGINT, Bun migration)
+- **Phase 5 — Agent Readiness**: needs planning, but scope is lint/templates/coverage (low UX ambiguity)
+- **Phase 6 — Config & Models**: internal infrastructure for downstream CLIs
+
+---
+
+## PR #8 status
+
+**Status:** Ready to merge (pending checks)
+
+| Item | Status |
+| --- | --- |
+| Merge conflicts | Resolved — rebased clean branch with only Phase 11 commits |
+| Mergeable | Yes |
+| CodeRabbit | Re-reviewing (triggered by force push) |
+| GitGuardian | In progress |
+| Claude Review | Queued |
+
+### Codex GPT-5.2 review findings
+
+#### Good
+
+- All prior CodeRabbit issues addressed
+- Plan docs are well-structured with consistent frontmatter and verification blocks
+- Persistence architecture is sound (per-topic keying, version-aware, migration-aware)
+
+#### Issues to note (non-blocking; plan docs, not code)
+
+- **"7 knowledge values" but only 6 listed** (low)
+  - Detail: Plan says 7, but the enum lists 6: `know`, `fuzzy`, `unknown`, `familiar`, `confident`, `mastered`. Fix during execution.
+- **"Yolo" vs "YOLO" casing mismatch** (low)
+  - Detail: Context says "Yolo", plans use "YOLO". Cosmetic — resolve at implementation.
+- **Color mapping inconsistency** (low)
+  - Detail: Context says gray/blue/green/gold; plans hardcode red/amber/blue/green. Plans are more specific; context is aspirational.
+- **`src/explorer/` doesn’t exist on branch** (expected)
+  - Detail: Phase 10 creates those files. Plans reference future paths correctly.
+- **localStorage fallback is export-only** (noted)
+  - Detail: No import path — acceptable for v1; can add in a later phase.
+
+None of these block merge. They’re plan-level inconsistencies that get resolved during Phase 11 execution.
+
+### Learn (7/7)
+
+**Summary:** PR #8 merge conflicts resolved via branch rebase. Now mergeable, awaiting automated checks (CodeRabbit, GitGuardian, Claude Review). Codex review found no blocking issues.
+
+**Next:** Wait for checks to pass, then merge. You can resume Codex with `codex resume` for follow-up analysis.
+
+**Obi:** PR #8 is now mergeable. Checks are running — once they pass, it’s ready to merge. Codex found only cosmetic plan-doc inconsistencies, nothing blocking.

.planning/phases/02-setup-automation/02-02-SUMMARY.md

@@ -77,7 +77,7 @@ Each task was committed atomically:
 3. **Task 3: Update integration test for new setup.sh behavior** - `1ef6a53` (test)
 
 ## Files Created/Modified
-- `setup.sh` - Added 8 new functions: is_step_complete, mark_step_complete, show_progress, create_dir, create_directory_structure, verify_directory_structure, scaffold_file, scaffold_config_files, install_python_deps, print_summary. Updated main flow with step-based execution.
+- `setup.sh` - Added 10 new functions: is_step_complete, mark_step_complete, show_progress, create_dir, create_directory_structure, verify_directory_structure, scaffold_file, scaffold_config_files, install_python_deps, print_summary. Updated main flow with step-based execution.
 - `.gitignore` - Added .setup-progress exclusion in Family Office section
 - `tests/integration/test_setup_onboarding_integration.sh` - Complete rewrite: 46 assertions across 5 test groups, removed all old onboarding/symlink/MCP references
 

.planning/phases/10-template-engine-dividend-topic-port/10-CONTEXT.md

@@ -0,0 +1,82 @@
+# Phase 10: Template Engine & Dividend Topic Port - Context
+
+**Gathered:** 2026-02-03
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Build a pipeline that converts topic JSON + HTML template into standalone interactive knowledge explorers using Cytoscape.js, with the dividend strategy topic as the first output. Feature parity with the existing prototype (`.dev/playgrounds/dividend-strategy-explorer.html`). Knowledge state persistence, learning modes, additional topics, and Maya integration are Phases 11-12.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Graph visualization engine
+- Use Cytoscape.js library instead of the prototype's custom canvas renderer
+- Force-directed layout (Cytoscape's `cose` or similar) to match the prototype's organic feel
+- Dark theme as default with a light mode toggle (both themes)
+- Node colors based on category (Foundation=blue, Strategy=purple, etc.) — knowledge state shown via badge or border indicator, not node fill color
+- Template defines a global color palette for category slots; topics assign category names and the template maps them to colors by order
+
+### Explorer interaction model
+- Clicking a node opens a bottom drawer detail panel (slides up from bottom, graph stays full width)
+- Bottom drawer shows: concept description, related concepts, generated learning prompt, and a "Copy prompt" button
+- Knowledge state cycling available via a button inside the detail panel (not by clicking the node directly)
+- Preset category filter buttons that highlight/dim nodes by category group
+- Text search box to find specific concepts by name (in addition to preset filters)
+- Hovering a node highlights its connected edges and adjacent nodes (Cytoscape built-in)
+
+### Topic data structure
+- Full topic envelope: JSON includes topic title, description, version, author, categories array, concepts array, edges array
+- Each concept: id, name, category, description, difficulty (beginner/intermediate/advanced), prerequisites (array of concept IDs)
+- Edges use typed relationships: each edge has {source, target, type, label?} where type is one of (enables, requires, protects, funds, etc.) — type determines edge styling (color, dash pattern)
+- Zod schema validates the entire topic JSON structure at build time
+- Category colors defined in the template as a global palette, not in topic JSON — topics name their categories, template assigns colors by order
+
+### Build pipeline output
+- HTML + separate JS bundle per topic (not single-file inline)
+- Cytoscape.js bundled into the JS output during build (works offline, no CDN dependency)
+- Bun as the build tool (consistent with project's existing Bun usage)
+- Strict Zod validation before build — malformed JSON fails with specific error messages, no broken HTML output
+- Output directory: `fin-guru-private/explorers/` (private output, consistent with existing conventions)
+- Build command produces: `{topic-slug}.html` + `{topic-slug}.js` per topic
+
+### Claude's Discretion
+- Exact Cytoscape.js layout parameters and animation settings
+- Bottom drawer animation and sizing details
+- Edge type-to-style mapping (which colors/dashes for each relationship type)
+- Search implementation details (fuzzy vs exact matching)
+- Bun build script internals and file watching for dev mode
+- Dark/light theme color palettes and toggle mechanism
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- The existing prototype at `.dev/playgrounds/dividend-strategy-explorer.html` is the authoritative reference for feature parity — 21 concepts, 6 categories, 22 edges, same graph structure
+- The prototype uses a GitHub-dark aesthetic — the dark theme should feel similar
+- Generated learning prompts should be concept-specific and useful when pasted into an AI chatbot
+- The detail panel should feel contextual but not obstructive — bottom drawer keeps the graph visible above it
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Knowledge state persistence via localStorage — Phase 11 (EXPL-05)
+- Learning mode selector (guided/standard/yolo) — Phase 11 (EXPL-06)
+- Options-greeks and risk-management topic content — Phase 11 (EXPL-09a, EXPL-09b)
+- Mobile/touch polish — Phase 11 (EXPL-08)
+- Maya learner profile export — Phase 12 (EXPL-07)
+- Topic selector landing page — Phase 12 (EXPL-10)
+- CLI launcher (`fin_guru.py explore`) — Phase 12 (EXPL-12)
+
+</deferred>
+
+---
+
+*Phase: 10-template-engine-dividend-topic-port*
+*Context gathered: 2026-02-03*