connectry-architect-mcp 0.1.7 → 0.1.9

package/README.md

@@ -3,7 +3,7 @@
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Connectry-io/connectrylab-architect-cert-mcp/master/.github/assets/logo-dark.svg">
     <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Connectry-io/connectrylab-architect-cert-mcp/master/.github/assets/logo-light.svg">
-    <img alt="Architect Cert" src="https://raw.githubusercontent.com/Connectry-io/connectrylab-architect-cert-mcp/master/.github/assets/logo-dark.svg" width="420">
+    <img alt="Architect Cert" src="https://raw.githubusercontent.com/Connectry-io/connectrylab-architect-cert-mcp/master/.github/assets/logo-light.svg" width="420">
   </picture>
   <br />
 </p>
@@ -14,7 +14,7 @@
 
 <p align="center">
   Adaptive certification prep powered by the Model Context Protocol.<br />
-  390 questions. Guided capstone build. 30 concept handouts. 6 reference projects. Practice exams. Spaced repetition. Zero sycophancy.
+  390 questions. Guided capstone build. 30 concept handouts. 6 reference projects. Practice exams. Interactive dashboard. Spaced repetition. Zero sycophancy.
 </p>
 
 <p align="center">
@@ -26,13 +26,15 @@
 
 <p align="center">
   <a href="#-quick-start">Quick Start</a> •
-  <a href="#-features">Features</a> •
-  <a href="#-how-it-works">How It Works</a> •
-  <a href="#-study-modes">Study Modes</a> •
+  <a href="#-learning-path">Learning Path</a> •
+  <a href="#-interactive-experience">Interactive Experience</a> •
+  <a href="#-initial-assessment">Assessment</a> •
+  <a href="#-concept-handouts">Handouts</a> •
+  <a href="#-adaptive-practice">Practice</a> •
   <a href="#-guided-capstone-build">Capstone Build</a> •
+  <a href="#-practice-exams">Practice Exams</a> •
+  <a href="#-progress-dashboard">Dashboard</a> •
   <a href="#-reference-projects">Reference Projects</a> •
-  <a href="#-concept-handouts">Concept Handouts</a> •
-  <a href="#-exam-domains">Exam Domains</a> •
   <a href="#-tools">Tools</a> •
   <a href="#-architecture">Architecture</a>
 </p>
@@ -45,11 +47,15 @@ Architect Cert is a free, open-source [MCP](https://modelcontextprotocol.io/) se
 
 It ships with:
 - **390 scenario-based questions** across all 5 exam domains and 30 task statements
+- **Interactive clickable UI** — answer questions with A/B/C/D buttons, select follow-ups, pick domains with checkboxes — all inside Claude
+- **Lessons-first assessment** — learn each domain's concepts before being tested on them
 - **Guided capstone build** — shape your own project, then build it step-by-step while learning every task statement hands-on
 - **30 concept handouts** — one per task statement, with code examples and common mistakes
 - **6 reference projects** — runnable TypeScript codebases demonstrating each domain in practice
 - **Practice exams** — 60-question weighted exams with history tracking and improvement trends
-- **Interactive follow-ups** — wrong answer? Dive into code examples, concept lessons, handouts, or reference projects before moving on
+- **Progress dashboard** — glassmorphism visual dashboard with mastery levels, exam history chart, activity timeline
+- **Visual progress tracking** — todo checklists track your progress through assessments, exams, and capstone builds in real time
+- **Interactive follow-ups** — wrong answer? Click to see code examples, concept lessons, handouts, or reference projects
 - **PDF generation** — branded handout PDFs with the Architect Cert logo for offline study
 - **Spaced repetition** — SM-2 algorithm schedules reviews at optimal intervals
 - **Deterministic grading** — pure function grading, no LLM judgment, zero sycophancy
@@ -69,7 +75,18 @@ npm install -g connectry-architect-mcp
 ### 2. Configure Your MCP Client
 
 <details>
-<summary><b>Claude Code</b> (VS Code / Cursor / Terminal)</summary>
+<summary><b>Claude Code</b> — One-liner</summary>
+
+```bash
+claude mcp add connectry-architect -- connectry-architect-mcp
+```
+
+That's it. Restart Claude Code and the server starts automatically.
+
+</details>
+
+<details>
+<summary><b>Claude Code</b> — Manual config</summary>
 
 Add to `.mcp.json` in your project or `~/.claude.json` globally:
 
@@ -83,7 +100,7 @@ Add to `.mcp.json` in your project or `~/.claude.json` globally:
 }
 ```
 
-Then restart Claude Code. The server starts automatically when Claude loads.
+Restart Claude Code. The server starts automatically when Claude loads.
 
 </details>
 
@@ -102,6 +119,11 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+> **Tip:** If you use `nvm`, you may need to specify the full path to the binary:
+> ```json
+> "command": "/Users/yourname/.nvm/versions/node/v22.20.0/bin/connectry-architect-mcp"
+> ```
+
 Restart Claude Desktop. You'll see the MCP tools icon appear in the chat input.
 
 </details>
@@ -134,7 +156,7 @@ Architect Cert works with any client that supports the [Model Context Protocol](
 - **Arguments:** none
 - **Transport:** stdio
 
-The server exposes 17 tools, 8 prompts, and 3 resource types.
+The server exposes 18 tools, 8 prompts, and 3 resource types.
 
 </details>
 
@@ -144,13 +166,14 @@ Restart your MCP client and start chatting:
 
 | What you want | What to ask Claude |
 |---------------|-------------------|
-| Find your weak areas | *"Start an assessment to figure out where I stand"* |
+| Start from scratch | *"Start an assessment to figure out where I stand"* |
 | Practice questions | *"Give me a practice question"* |
 | Focus on a domain | *"Give me a question about agentic architecture"* |
 | Learn a concept first | *"Teach me about task 2.3 — tool provisioning"* |
 | Build your own capstone | *"I want to start a guided capstone build"* |
 | Take a practice exam | *"I want to take a practice exam"* |
 | Check your progress | *"Show my study progress"* |
+| Show the dashboard | *"Show my dashboard"* |
 | Get a study plan | *"What should I study next?"* |
 | Explore a reference project | *"Show me a reference project for domain 1"* |
 | Generate PDF handouts | Run `npm run generate:pdfs` in the project directory |
@@ -158,181 +181,156 @@ Restart your MCP client and start chatting:
 
 <br />
 
-## Features
+## Learning Path
 
-<table>
-<tr>
-<td width="50%">
+Architect Cert is designed to follow a natural progression. Here's the recommended order:
 
-### Adaptive Learning
-SM-2 spaced repetition resurfaces weak areas at optimal intervals. Questions you get wrong come back sooner — questions you master fade away.
+```
+1. Assessment        → Baseline your knowledge across all 5 domains
+       ↓
+2. Learn concepts    → Read handouts for weak domains before practicing
+       ↓
+3. Adaptive practice → Questions prioritized by weakness, reviews, new material
+       ↓
+4. Follow-ups        → Dive into code examples, concept lessons, reference projects
+       ↓
+5. Capstone build    → Build your own project covering all 30 task statements
+       ↓
+6. Practice exams    → Simulate the real exam (60 questions, scored out of 1000)
+       ↓
+7. Review & repeat   → Dashboard tracks mastery, spaced repetition handles scheduling
+```
 
-### 390 Exam Questions
-13 scenario-based questions per task statement across all 30 topics. Easy, medium, and hard difficulties with balanced answer distributions across A/B/C/D.
+You can jump to any stage at any time — the system adapts. But the path above gives you the most structured experience.
 
-### Deterministic Grading
-Pure function grading — no LLM judgment calls. Your answer is checked against a verified key. Right is right, wrong is wrong. Every wrong answer includes a specific explanation.
+<br />
 
-</td>
-<td width="50%">
+## Interactive Experience
 
-### Zero Sycophancy
-Claude won't sugarcoat wrong answers. Anti-sycophancy rules are enforced at the protocol level. Wrong means wrong — no "you were on the right track."
+Architect Cert uses Claude's built-in interactive UI to make studying feel natural. No typing answer letters — just click.
 
-### Progress Tracking
-Persistent SQLite database tracks every answer, mastery level, and review schedule. Pick up exactly where you left off across sessions, devices, and MCP clients.
+### Clickable Answer Selection
 
-### Smart Question Selection
-Three-priority algorithm: overdue reviews first, then weak areas, then new material. You always work on what matters most for exam readiness.
+Every question presents **clickable A/B/C/D buttons** directly in Claude. You tap your answer instead of typing it. If the question includes code in the scenario, a **code preview** appears alongside each option so you can reference it while deciding.
 
-</td>
-</tr>
-<tr>
-<td width="50%">
+### Follow-Up Actions
 
-### Interactive Follow-Ups
-After every answer, you get follow-up options. Got it wrong? Choose to see a code example, read the concept lesson, open the handout, or explore the relevant reference project — then jump back to your quiz.
+After every answer, clickable follow-up buttons appear:
 
-### Guided Capstone Build
-Shape your own project idea, then build it file-by-file across 18 steps. Each step: quiz on the relevant task statements, Claude generates themed code, then a walkthrough explains how every section maps to exam concepts. Learn by doing.
+**After a wrong answer:**
+- Got it, next question
+- Explain with a code example
+- Show me the concept lesson
+- Show me the handout
+- Show me in the reference project
 
-</td>
-<td width="50%">
+**After a correct answer:**
+- Next question
+- Explain why the others are wrong
 
-### 30 Concept Handouts
-Every task statement has a structured handout: concept explanation, TypeScript code example, common mistakes, and documentation references. Available as markdown in Claude or as branded PDFs for offline study.
+### Multi-Select Domain Picker
 
-### 6 Reference Projects
-Runnable TypeScript codebases that demonstrate each domain in practice. A capstone project ties all 5 domains together. Each file maps to specific task statements so you can see concepts in real code.
+When requesting a study plan, you can select multiple domains to focus on using **checkboxes** — no need to list them out by name.
 
-### Practice Exams
-Full 60-question exams weighted by domain — just like the real certification. Fresh questions each time (no repetition from your last attempt). Scored out of 1000, passing at 720. All attempts saved with per-domain breakdowns.
+### Visual Progress Checklists
 
-### PDF Handouts
-Generate branded PDFs for all 30 handouts with `npm run generate:pdfs`. Each PDF includes the Architect Cert logo, domain label, and clean formatting for printing or tablet reading.
+Long flows like the assessment (15 questions), practice exams (60 questions), and capstone build (18 steps) create a **visual todo checklist** that updates in real time as you progress. You always know where you are and what's left.
 
-</td>
-</tr>
-</table>
+### Skip & Other
+
+Every question selection includes a **Skip** button to move on and an **Other** option to ask a free-form question. If you use "Other" to ask something, Claude answers your question and then **re-presents the same quiz question** — you never lose your place. "Skip" moves to the next question; skipped questions remain unanswered and will reappear later.
 
 <br />
 
-## How It Works
+## Initial Assessment
 
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                         YOUR MACHINE                             │
-│                                                                  │
-│   ┌──────────────┐       ┌──────────────────────────┐           │
-│   │ Claude Desktop│       │   Architect Cert MCP     │           │
-│   │ Claude Code   │◄─────►│                          │           │
-│   │ Any MCP client│ stdio │  17 tools                │           │
-│   └──────────────┘       │   8 prompts               │           │
-│                           │   3 resource types        │           │
-│                           └──────────┬───────────────┘           │
-│                                      │                           │
-│                    ┌─────────────────┼─────────────────┐         │
-│                    │                 │                  │         │
-│              ~/.connectry-      390 questions      6 reference   │
-│               architect/       30 handouts         projects      │
-│               progress.db     (bundled JSON/MD)   (bundled TS)   │
-│                                                                  │
-└──────────────────────────────────────────────────────────────────┘
-```
+Start with a **15-question diagnostic** (3 per domain) that determines your learning path. The assessment works differently from raw practice:
 
-**The study loop:**
+### Lessons-First Flow
 
-1. **Assessment** — 15 diagnostic questions baseline your knowledge across all 5 domains
-2. **Path assignment** — Score < 60% gets the beginner-friendly track; score >= 60% gets the exam-weighted track
-3. **Learn first** — Read the concept handout for a topic before tackling questions (or skip straight to practice)
-4. **Smart selection** — Each question chosen by priority: overdue reviews > weak areas > new material
-5. **Deterministic grading** — Pure function checks your answer against the verified key
-6. **Interactive follow-up** — Wrong answer? Dive into code examples, concept lessons, or reference projects
-7. **Spaced repetition** — SM-2 algorithm schedules reviews: 1 day > 3 days > 6 days > ...
-8. **Practice exams** — Take full 60-question exams when you're ready, track improvement over time
+When the assessment reaches a **new domain** for the first time, it pauses to show you the **concept handout** before asking questions. This means you learn the key ideas, see code examples, and understand common mistakes *before* being tested — no guessing blindly.
 
-**Data storage:**
+The flow for each domain:
+1. Concept handout is shown (one-time per domain)
+2. 3 questions presented one at a time (easy, medium, hard)
+3. Each answer graded immediately with explanation
+4. Move to the next domain
 
-- Progress is stored locally at `~/.connectry-architect/progress.db` (SQLite, WAL mode)
-- Your user config lives at `~/.connectry-architect/config.json` (auto-created on first run)
-- No cloud, no accounts, no telemetry — everything stays on your machine
+### Path Assignment
 
-<br />
+Based on your overall accuracy:
 
-## Study Modes
+| Score | Path | Description |
+|-------|------|-------------|
+| **< 60%** | Beginner-Friendly | Starts with fundamentals, builds up gradually. Focuses on easy and medium questions first. |
+| **>= 60%** | Exam-Weighted | Focuses on high-weight domains first (D1 at 27%, D3 & D4 at 20% each). Targets weak areas aggressively. |
 
-### Initial Assessment
+### Progress Tracking
 
-Start with 15 questions across all domains. Based on your score:
+The assessment creates a **15-item visual checklist** (Q1 through Q15, grouped by domain) that updates after each answer. You always see exactly how far you've progressed.
 
-- **< 60% accuracy** — **Beginner-Friendly Path**: Starts with fundamentals, builds up gradually through each domain. Focuses on easy and medium questions first.
-- **>= 60% accuracy** — **Exam-Weighted Path**: Focuses on high-weight domains first (D1 at 27%, D3 & D4 at 20% each). Targets weak areas aggressively.
+<br />
 
-### Learn-First Mode
+## Concept Handouts
 
-Before tackling questions on any topic, you can read the concept handout first:
+Every task statement has a **concept handout** — a structured study document (~500-800 words) that covers:
 
-```
-You: "Teach me about task 1.5 — tool-use hooks"
+- **Concept** — The core idea, mental model, and when/why to use it
+- **Code Example** — Realistic TypeScript demonstrating the pattern
+- **Common Mistakes** — The 3-5 most frequent errors (which map to exam wrong answers)
+- **References** — Links to Anthropic's official documentation
 
-Claude: [loads the concept handout with key concepts, code examples,
-         common mistakes, and documentation references]
+### Reading Handouts in Claude
 
-        Ready to test your understanding? I have 13 questions
-        on this topic ranging from easy to hard.
 ```
+You: "Show me the handout for task 2.3"
 
-The server tracks which handouts you've viewed. You can always come back to them later.
+Claude: [loads the full handout with concept, code, mistakes, references]
+```
 
-### Interactive Follow-Ups
+### When Handouts Appear Automatically
 
-After every answer, you get contextual follow-up options:
+- **During assessment** — shown before the first question of each new domain
+- **After a wrong answer** — "Show me the handout" is one of the follow-up options
+- **During capstone build** — relevant handouts are available at each build step
 
-**After a wrong answer:**
-```
-The correct answer is B. [explanation]
+### Generating PDF Handouts
 
-  > Got it, next question
-  > Explain with a code example
-  > Show me the concept lesson
-  > Show me the handout
-  > Show me in the reference project
-```
+Generate branded PDFs for all 30 handouts for offline study:
 
-**After a correct answer:**
+```bash
+cd connectrylab-architect-cert-mcp
+npm run generate:pdfs
 ```
-Correct!
 
-  > Next question
-  > Explain why the others are wrong
-```
+This creates 30 PDFs in `generated/handouts/` with:
+- Architect Cert logo and domain label in the header
+- Clean formatting with syntax-highlighted code blocks
+- "Connectry LABS — Claude Certified Architect Exam Prep — Free & Open Source" footer
 
-Each option dives deeper into the concept — then brings you right back to your quiz. This means you never have to leave your study flow to look something up.
+<br />
 
-### Adaptive Practice
+## Adaptive Practice
 
-Every question is selected by a three-priority algorithm:
+Every practice question is selected by a **three-priority algorithm**:
 
 1. **Overdue reviews** — Spaced repetition items due for review today
 2. **Weak areas** — Topics where your mastery is below 50%
 3. **New material** — Fresh questions from your recommended domain
 
-### Practice Exams
+### Filtering
 
-Full 60-question exams that simulate the real certification:
+You can filter practice questions by domain and/or difficulty:
 
-| Detail | Value |
-|--------|-------|
-| Total questions | 60 |
-| D1: Agentic Architecture | 16 questions (27%) |
-| D2: Tool Design & MCP | 11 questions (18%) |
-| D3: Claude Code Config | 12 questions (20%) |
-| D4: Prompt Engineering | 12 questions (20%) |
-| D5: Context & Reliability | 9 questions (15%) |
-| Scoring | 0–1000, passing at 720 |
-| Question selection | Fresh set each time — avoids repeating your most recent attempt |
+```
+You: "Give me a hard question about prompt engineering"
 
-All attempts are saved with per-domain score breakdowns and improvement trends.
+Claude: [presents a hard Domain 4 question with clickable A/B/C/D buttons]
+```
+
+### Interactive Follow-Ups
+
+After every answer, you get clickable follow-up options. Each option dives deeper into the concept — then brings you right back to your quiz. You never leave your study flow to look something up.
 
 ### Mastery Levels
 
@@ -342,8 +340,8 @@ Each of the 30 task statements has an independent mastery level:
 |-------|----------|---------------|
 | **Unassessed** | No attempts yet | You haven't seen questions on this topic |
 | **Weak** | < 50% accuracy | Needs significant study — questions resurface frequently |
-| **Developing** | 50–69% accuracy | Making progress — keep practicing |
-| **Strong** | 70–89% accuracy | Good understanding — review intervals are longer |
+| **Developing** | 50-69% accuracy | Making progress — keep practicing |
+| **Strong** | 70-89% accuracy | Good understanding — review intervals are longer |
 | **Mastered** | >= 90% accuracy, 5+ attempts, 3+ consecutive correct | Exam-ready — rare reviews |
 
 ### Spaced Repetition (SM-2)
@@ -364,7 +362,7 @@ Difficult questions come back often. Easy ones space out to weeks or months.
 
 The most hands-on way to learn — build your own project from scratch while covering all 30 task statements. Instead of just answering questions, you architect a real system themed to your own idea.
 
-### How it works
+### How It Works
 
 The capstone build has three phases:
 
@@ -389,10 +387,12 @@ Claude: Your idea naturally covers 24/30 criteria. To cover the
 
 Each step follows the same pattern:
 
-1. **Quiz** — 2-3 questions on the task statements you're about to build
+1. **Quiz** — 2-3 questions on the task statements you're about to build (clickable A/B/C/D)
 2. **Build** — Claude generates the file's code, themed to your project
 3. **Walkthrough** — Line-by-line explanation mapping code to task statements
 
+A **visual 18-step checklist** tracks your progress in real time.
+
 The 18 steps build incrementally:
 
 | Steps | What you build | Task Statements |
@@ -409,7 +409,7 @@ Every quiz answer feeds into the same spaced repetition and mastery tracking as
 
 After step 18, you get a complete coverage map: all 30 task statements, where each is demonstrated in your project, and your quiz performance per domain. Weak areas are flagged for further study.
 
-### Capstone build tools
+### Capstone Build Tools
 
 | Tool | What it does |
 |------|-------------|
@@ -417,7 +417,7 @@ After step 18, you get a complete coverage map: all 30 task statements, where ea
 | `capstone_build_step` | Drive the build: confirm, quiz, build, next, status, or abandon |
 | `capstone_build_status` | Check your progress — current step, criteria coverage, quiz performance |
 
-### How it connects to everything else
+### How It Connects to Everything Else
 
 - Quiz answers during the build use the same `submit_answer` grading and SM-2 scheduling
 - After any quiz question, you can use the same follow-up options (code example, concept lesson, handout, reference project)
@@ -426,6 +426,56 @@ After step 18, you get a complete coverage map: all 30 task statements, where ea
 
 <br />
 
+## Practice Exams
+
+Full 60-question exams that simulate the real certification:
+
+| Detail | Value |
+|--------|-------|
+| Total questions | 60 |
+| D1: Agentic Architecture | 16 questions (27%) |
+| D2: Tool Design & MCP | 11 questions (18%) |
+| D3: Claude Code Config | 12 questions (20%) |
+| D4: Prompt Engineering | 12 questions (20%) |
+| D5: Context & Reliability | 9 questions (15%) |
+| Scoring | 0-1000, passing at 720 |
+| Question selection | Fresh set each time — avoids repeating your most recent attempt |
+| UI | Clickable A/B/C/D buttons with code previews |
+| Progress | Visual 60-item checklist updated after each answer |
+
+All attempts are saved with per-domain score breakdowns and improvement trends.
+
+<br />
+
+## Progress Dashboard
+
+Architect Cert includes a **glassmorphism visual dashboard** that renders directly inside Claude via Claude Preview.
+
+### What It Shows
+
+- **Readiness Ring** — Overall exam readiness percentage in a circular progress indicator
+- **Domain Mastery Grid** — 5 cards with progress bars for each exam domain
+- **Exam History Chart** — Line chart plotting your practice exam scores over time, with the 720 passing score marked
+- **Recent Activity Timeline** — Your last 10 answers with correct/incorrect indicators
+- **Capstone Progress** — Current build step and completion percentage
+- **Quick Action Buttons** — Jump to practice, exam, study plan, or capstone
+
+### How to Open
+
+```
+You: "Show my dashboard"
+
+Claude: [opens the branded dashboard in Claude Preview]
+```
+
+The dashboard can be reopened at any time by asking Claude again. It always reflects your latest data.
+
+### Text Fallback
+
+For MCP clients that don't support Claude Preview, the dashboard tool also returns a **text summary** with mastery percentages and exam stats.
+
+<br />
+
 ## Reference Projects
 
 Architect Cert includes **6 complete reference projects** — runnable TypeScript codebases that demonstrate certification concepts in real code. Every file has a header comment mapping it to specific task statements.
@@ -439,55 +489,36 @@ Architect Cert includes **6 complete reference projects** — runnable TypeScrip
 | **D4 — Prompt Engineering** | Domain 4 | 11 | Data extraction pipeline with explicit criteria, few-shot, structured output, validation-retry, batch processing, and multi-pass review |
 | **D5 — Context Manager** | Domain 5 | 14 | Long-session patterns: context preservation, scratchpad, subagent delegation, escalation, error propagation, confidence calibration, provenance |
 
-### How to access them
-
-Ask Claude:
+### How to Access
 
 ```
 You: "Show me a reference project for domain 1"
 
-Claude: [calls scaffold_project, returns the project README,
-         file listing, and architecture walkthrough]
+Claude: [returns the project README, file listing, and architecture walkthrough]
 ```
 
-Or browse them directly in the repo under `projects/`.
-
-### How they connect to the study flow
+### How They Connect to the Study Flow
 
 When you get a question wrong, one of the follow-up options is **"Show me in the reference project"** — this takes you straight to the relevant domain project so you can see the concept implemented in real code. Then you jump back to your quiz.
 
 <br />
 
-## Concept Handouts
+## Study Plan
 
-Every task statement has a **concept handout** — a structured study document (~500-800 words) that covers:
+Get personalized study recommendations based on your performance, exam weights, and spaced repetition schedule.
 
-- **Concept** — The core idea, mental model, and when/why to use it
-- **Code Example** — Realistic TypeScript demonstrating the pattern
-- **Common Mistakes** — The 3-5 most frequent errors (which map to exam wrong answers)
-- **References** — Links to Anthropic's official documentation
+### Multi-Select Domain Focus
 
-### Reading handouts in Claude
+When requesting a study plan, you can pick specific domains to focus on using **checkboxes**:
 
 ```
-You: "Show me the handout for task 2.3"
+You: "What should I study next?"
 
-Claude: [loads the full handout with concept, code, mistakes, references]
-```
-
-### Generating PDF handouts
-
-You can generate branded PDFs for all 30 handouts for offline study:
-
-```bash
-cd connectrylab-architect-cert-mcp
-npm run generate:pdfs
+Claude: [shows domain checkboxes — select the ones you want to focus on]
+        [generates a personalized study plan with a visual checklist]
 ```
 
-This creates 30 PDFs in `generated/handouts/` with:
-- Architect Cert logo and domain label in the header
-- Clean formatting with syntax-highlighted code blocks
-- "Connectry LABS — Claude Certified Architect Exam Prep — Free & Open Source" footer
+The study plan creates a **visual checklist** so you can track your progress through each recommendation.
 
 <br />
 
@@ -580,26 +611,49 @@ The Claude Certified Architect — Foundations exam covers 5 domains:
 
 ## Tools
 
-Architect Cert provides **17 MCP tools** that Claude uses to deliver the study experience:
+Architect Cert provides **18 MCP tools** that Claude uses to deliver the study experience:
+
+### Study Flow
 
 | Tool | Description |
 |------|-------------|
-| `start_assessment` | Begin with 15 diagnostic questions to determine your learning path |
-| `get_practice_question` | Get the next adaptive question (reviews > weak areas > new material) |
-| `submit_answer` | Grade your answer deterministically — includes interactive follow-up options |
+| `start_assessment` | Begin with 15 diagnostic questions (lessons-first, one at a time) to determine your learning path |
+| `get_practice_question` | Get the next adaptive question with clickable A/B/C/D buttons (reviews > weak areas > new material) |
+| `submit_answer` | Grade your answer deterministically — presents interactive follow-up options |
 | `follow_up` | Handle post-answer actions: code examples, concept lessons, handouts, reference projects |
+| `get_section_details` | Deep dive into a specific task statement with full concept handout |
+
+### Progress & Planning
+
+| Tool | Description |
+|------|-------------|
 | `get_progress` | View overall study progress with mastery percentages per domain |
 | `get_curriculum` | Browse all 5 domains and 30 task statements with current mastery levels |
-| `get_section_details` | Deep dive into a specific task statement with concept lesson |
 | `get_weak_areas` | Identify topics that need the most work, ranked by weakness |
-| `get_study_plan` | Get personalized recommendations based on performance and exam weights |
+| `get_study_plan` | Get personalized recommendations with multi-select domain focus |
+| `get_dashboard` | Open the visual progress dashboard in Claude Preview |
+
+### Practice Exams
+
+| Tool | Description |
+|------|-------------|
 | `start_practice_exam` | Take a full 60-question practice exam simulating the real certification |
 | `submit_exam_answer` | Submit and grade answers during a practice exam |
 | `get_exam_history` | View all past exam attempts with scores, trends, and per-domain comparison |
-| `scaffold_project` | Access reference projects for hands-on practice with real code |
+
+### Capstone Build
+
+| Tool | Description |
+|------|-------------|
 | `start_capstone_build` | Start a guided capstone build — shape your project and validate criteria coverage |
 | `capstone_build_step` | Drive the capstone build: confirm, quiz, build, next, status, or abandon |
 | `capstone_build_status` | Check capstone build progress — current step, coverage, quiz performance |
+
+### Reference & Admin
+
+| Tool | Description |
+|------|-------------|
+| `scaffold_project` | Access reference projects for hands-on practice with real code |
 | `reset_progress` | Start over — requires explicit confirmation to prevent accidents |
 
 The server also registers **8 interactive prompts** and **3 resource types** (concept handouts, reference projects, exam overview).
@@ -609,22 +663,58 @@ The server also registers **8 interactive prompts** and **3 resource types** (co
 ## Architecture
 
 ```
-Claude (UI) <-> MCP Server (stdio) <-> Core Engine <-> SQLite
+┌──────────────────────────────────────────────────────────────────────┐
+│                           YOUR MACHINE                               │
+│                                                                      │
+│   ┌──────────────┐       ┌────────────────────────────────┐          │
+│   │ Claude Desktop│       │     Architect Cert MCP          │          │
+│   │ Claude Code   │◄─────►│                                │          │
+│   │ Any MCP client│ stdio │  18 tools                      │          │
+│   └──────┬───────┘       │   8 prompts                     │          │
+│          │                │   3 resource types              │          │
+│          │                └──────────┬─────────────────────┘          │
+│          │                           │                                │
+│          │         ┌────────────────┼────────────────────┐           │
+│          │         │                │                     │           │
+│          │   ~/.connectry-      390 questions         6 reference     │
+│          │    architect/       30 handouts            projects        │
+│          │    progress.db     (bundled JSON/MD)      (bundled TS)     │
+│          │                                                            │
+│          │  ┌──────────────────────────┐                              │
+│          └──► Claude Preview (Dashboard) │                              │
+│             │ localhost HTTP server      │                              │
+│             └──────────────────────────┘                              │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
 ```
 
+### Core Components
+
 | Component | Technology | Purpose |
 |-----------|-----------|---------|
 | MCP Server | `@modelcontextprotocol/sdk` v1 | Registers tools, prompts, resources over stdio |
 | Grading Engine | Pure TypeScript functions | Deterministic answer verification |
 | Spaced Repetition | SM-2 algorithm | Optimal review scheduling |
+| Question Selector | Three-priority algorithm | Overdue reviews > weak areas > new material |
 | Follow-Up System | State-driven tool chain | Interactive post-answer detours |
 | Capstone Build Engine | 18-step interleaved builder | Guided learn-build-explain flow with LLM validation |
+| Dashboard Server | Node.js HTTP + HTML | Glassmorphism visual dashboard via Claude Preview |
 | Question Bank | 390 bundled JSON questions | Scenario-based, verified against docs |
 | Concept Handouts | 30 bundled markdown files | Structured study materials per task statement |
 | Reference Projects | 6 bundled TypeScript projects | Runnable code demonstrating each domain |
-| PDF Generator | `pdfkit` | Branded handout PDFs for offline study |
+| PDF Generator | Puppeteer + Marked | Branded handout PDFs for offline study |
 | Progress Store | `better-sqlite3` (WAL mode) | Persistent mastery, answers, schedules |
 
+### Interactive UI Architecture
+
+Architect Cert doesn't build its own chat UI. Instead, it instructs Claude to use **built-in interactive tools**:
+
+- **AskUserQuestion** — Presents clickable buttons for A/B/C/D answers, follow-up actions, and domain selection. Supports single-select (radio buttons), multi-select (checkboxes), and free-text input via "Other".
+- **TodoWrite** — Creates visual progress checklists that update in real time during assessments, exams, and capstone builds.
+- **Claude Preview** — Renders the glassmorphism dashboard HTML on a local HTTP server.
+
+This approach works across Claude Code and Claude Desktop without requiring any custom UI code on the client side.
+
 ### Anti-Sycophancy Design
 
 This server enforces honest grading at the protocol level — not just in prompts:
@@ -653,6 +743,14 @@ This server enforces honest grading at the protocol level — not just in prompt
 
 <br />
 
+## Data Storage
+
+- Progress is stored locally at `~/.connectry-architect/progress.db` (SQLite, WAL mode)
+- Your user config lives at `~/.connectry-architect/config.json` (auto-created on first run)
+- No cloud, no accounts, no telemetry — everything stays on your machine
+
+<br />
+
 ## Contributing
 
 We welcome contributions! Here's how to get started:
@@ -668,7 +766,7 @@ npm install
 # Build
 npm run build
 
-# Run tests (30 tests across 6 test files)
+# Run tests
 npm test
 
 # Generate PDF handouts
@@ -698,7 +796,9 @@ src/
 │   ├── store.ts          # Database initialization
 │   ├── mastery.ts        # Mastery level calculations
 │   ├── answers.ts        # Answer recording
+│   ├── review-schedule.ts # SM-2 review scheduling
 │   ├── capstone.ts       # Capstone build CRUD operations
+│   ├── users.ts          # User management
 │   └── exam-attempts.ts  # Practice exam tracking
 ├── engine/
 │   ├── grading.ts        # Deterministic grading
@@ -706,7 +806,32 @@ src/
 │   ├── question-selector.ts  # Priority-based selection
 │   ├── exam-builder.ts       # Practice exam generation
 │   └── adaptive-path.ts      # Learning path recommendations
-├── tools/                # 17 MCP tool handlers
+├── tools/                # 18 MCP tool handlers
+│   ├── index.ts          # Tool registration
+│   ├── elicit.ts         # MCP elicitation helper (graceful fallback)
+│   ├── start-assessment.ts
+│   ├── submit-answer.ts
+│   ├── get-practice-question.ts
+│   ├── follow-up.ts
+│   ├── get-progress.ts
+│   ├── get-curriculum.ts
+│   ├── get-section-details.ts
+│   ├── get-weak-areas.ts
+│   ├── get-study-plan.ts
+│   ├── start-practice-exam.ts
+│   ├── submit-exam-answer.ts
+│   ├── get-exam-history.ts
+│   ├── scaffold-project.ts
+│   ├── start-capstone-build.ts
+│   ├── capstone-build-step.ts
+│   ├── capstone-build-status.ts
+│   ├── reset-progress.ts
+│   └── dashboard.ts
+├── ui/
+│   ├── server.ts         # Dashboard HTTP server
+│   ├── dashboard.html    # Glassmorphism dashboard UI
+│   ├── meta.ts           # Quiz widget metadata
+│   └── loader.ts         # HTML asset loader
 ├── prompts/              # 8 MCP prompt definitions
 └── resources/            # 3 MCP resource types