@relipa/ai-flow-kit 0.0.6 → 0.0.7-beta.1

package/docs/common/AIFLOW.md

@@ -28,7 +28,7 @@ PM writes ticket on Backlog/Jira
         ▼
 ⛩️ GATE 3 — Code Generation (TDD)           [AI]
   AI writes tests first → implement → tests pass
-  Commit each small step
+  Verify implementation works
         │ Code done
         ▼
 ⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
@@ -65,6 +65,10 @@ AI Flow Kit allows you to manage multiple tasks in the same repository without l
 - **`aiflow task pause`**: Save current context and gate progress to `.aiflow/tasks/<taskId>/`.
 - **`aiflow task switch <id>`**: Pause current task and switch to another.
 - **`aiflow task resume <id>`**: Restore context and gate state. AI auto-resumes from the correct gate.
+- **`aiflow task next`**: Approve the current gate, generate `task-summary.md`, clear active context, and prepare the task for a fresh session (Recommended to avoid context pollution).
+
+### Pro-Tip: Fresh Session Workflow
+For the best AI performance, run `aiflow task next` after every gate approval, then open a **new chatbox** and type "continue". This clears out long chat history that might confuse the AI.
 
 ---
 
@@ -182,7 +186,7 @@ Summary:
 1. Read the approved requirement document
 2. **Invoke** `superpowers:writing-plans` → create detailed implementation plan
 3. Break down into TDD tasks: test first → implement → verify
-4. Define commit strategy (small, focused commits)
+4. Define verification strategy (evidence before claims)
 5. Present plan and wait for APPROVED
 
 **Implementation Plan Structure:**
@@ -193,7 +197,6 @@ Summary:
 │   ├── Task 2: Implement [component]
 │   ├── Task 3: Write test for [next scenario]
 │   └── ...
-├── Commit Strategy
 └── Test Commands
 ```
 
@@ -202,7 +205,7 @@ Summary:
 ```
 ⏸️ GATE 2: IMPLEMENTATION PLAN READY
 
-Tasks: [N] | Commits: [N] | Test-first tasks: [N]
+Tasks: [N] | Verification: [N] | Test-first tasks: [N]
 
 → Type APPROVED to start coding
 → Or provide feedback to adjust
@@ -227,7 +230,7 @@ Tasks: [N] | Commits: [N] | Test-first tasks: [N]
 2. `superpowers:test-driven-development` — write tests FIRST
 3. Run tests → confirm FAIL
 4. Implement code → tests PASS
-5. Commit each small step
+5. Verify implementation works
 
 #### Bug fix task (extra):
 1. `superpowers:systematic-debugging` — trace root cause, NO guessing
@@ -238,10 +241,16 @@ Tasks: [N] | Commits: [N] | Test-first tasks: [N]
 1. Ensure tests cover current behavior
 2. Refactor in small steps — keep tests green continuously
 
+**Fast Mode (tdd-lean):**
+In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massive token costs:
+1. **Batch Red:** Write ALL tests at once. Run once. (Confirm all fail).
+2. **Batch Green:** Implement ALL code at once. Run once. (Confirm all pass).
+3. **Discipline:** After every run, discard full stack traces and keep ONLY the summary line.
+
 **Gate 3 Output:**
 - Code implementation finished
 - All tests PASS
-- Committed
+- Verified (evidence provided)
 
 ---
 
@@ -496,6 +505,8 @@ A: Yes. Use `aiflow task pause` to save your current progress, then `aiflow use
 
 **Q: If I resume a task, will Claude know which gate to start at?**
 A: Yes. The SessionStart hook reads `.aiflow/tasks/<taskId>/task-state.json` and injects gate-aware instructions. If Gate 1 was already approved, Claude will skip to Gate 2, and so on.
+**Q: Can I resume a Gate 3 (Code Generation) task in a new chatbox?**
+A: Yes. Gate 3 progress is saved via `[x]` checkboxes in `plan/[id]/plan.md`. If you open a new chatbox and say "continue", the AI will automatically skip completed tasks and pick up exactly where it left off.
 
 **Q: How does AI estimate effort?**
 A: AI analyzes the scope of changes (files affected, complexity, test requirements) and categorizes: S (< 1h), M (1-4h), L (4-8h), XL (8h+, should split).

package/docs/common/CHANGELOG.md

@@ -1,15 +1,56 @@
 # Changelog
 
-All notable changes to **@relipa/ai-flow-kit** will be documented in this file.
+All notable changes to **ai-flow-kit** will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.0.7] - 2026-05-08
+
+### Added
+
+- **`aiflow use --file` enhancements**:
+  - Automatic `taskId` generation from filename (up to 5 words).
+  - Full filename used as task `title`.
+  - Interactive `taskType` selection prompt during file loading for better context.
+- **`documentation` task type** — Added support for documentation-specific tasks in `aiflow use` and task detection.
+- **Automatic `task-summary.md` generation** — `aiflow task next` now generates a cumulative progress report in `plan/[ticket-id]/task-summary.md` at each gate finish.
+- **Session Continuity Instructions** — Added explicit instructions on how to switch to a fresh chat session and resume tasks (including Gate 3 sub-tasks) to both CLI output and AI skill prompts.
+- **NestJS framework support** — Added `nestjs` to the framework selector (`aiflow init`), language rule mapping (`javascript`), and AI instruction template (`custom/templates/nestjs.md`).
+- **PHP Plain (no framework) support** — Added `php-plain` as a new framework option with a dedicated AI system prompt template covering strict types, PSR-12, PDO prepared statements, security best practices, Repository/Service/Controller layering, and PHPUnit testing.
+- **`investigate-bug` skill: NestJS and PHP plain data flows** — Added framework-specific data flow traces for NestJS (`Controller → Service → Repository → DB`) and PHP Plain (`index.php → Controller → Service → Repository/PDO → DB`).
+- **Intelligent AI Instruction Synchronization** — Marker-based (`<!-- aiflow-kit-start -->`) block updates for `CLAUDE.md`, `GEMINI.md`, and `.cursorrules`.
+- **Interactive Instruction Safety** — Granular confirmation prompts for all instruction file modifications (update block, overwrite, or create new).
+- **Automated Repository Hygiene** — Generated files and folders (`.aiflow/`, `plan/`, `.claude/`, `.rules/`, `.mcp.json`, and instruction files) are now automatically managed in `.gitignore`.
+- **`aiflow sync-skills` command** — Lightweight command to synchronize Skill Registry and Instruction files without a full version upgrade.
+- **Enhanced `aiflow guide --flow`** — Now dynamically displays the `## Workflow Overview` section directly from `AIFLOW.md` for up-to-date documentation.
+- **Token savings dashboard in `aiflow doctor`** — new "Token savings" section shows RTK status and estimated 60–90% reduction on bash outputs.
+
+### Changed
+
+- **Robust Gate Detection** — Refactored `detectCurrentGate` to prioritize `task-state.json` as the source of truth for task progress.
+- **`aiflow gate approved` CLI output** — Now prints a session-refresh tip to help users maintain clean AI contexts.
+- **`aiflow update` efficiency** — Now automatically performs skill and instruction synchronization even if the version is unchanged (removes the need for `--force`).
+- **Safety First Development** — Removed all automatic `git commit` instructions from AI skills (`subagent-driven-development`, `using-git-worktrees`, `writing-plans`) to ensure developer-led commit management.
+- **Localized CLI** — All interactive prompts and confirmation messages translated to English for consistency.
+- **`aiflow init` RTK entry** — flag description updated to clarify RTK saves bash output tokens (60–90%).
+- **`aiflow doctor`** — RTK section merged into new "Token savings" section.
+- **README.md / QUICK_START.md** — Updated to reflect `sync-skills` and improved update flow.
+
+### Fixed
+
+- **NestJS auto-detection** — `@nestjs/core` in `package.json` was incorrectly detected as `nodejs-express`; now correctly resolves to `nestjs`.
+- **PHP project auto-detection** — Projects with `composer.json` but no Laravel dependency now correctly auto-detect as `php-plain` instead of being skipped.
+- Fixed `.github/copilot-instructions.md` not being included in automated `.gitignore` rules.
+
+---
+
 ## [0.0.6] - 2026-04-29
 
 ### Added
+
 - **Global Fast Mode (Default)** — Optimize AI efficiency by prioritizing speed and minimizing token usage.
   - Gate 1: Fast track scan with max 1 clarifying question.
   - Gate 3: Disable subagents by default; implement all tasks in a single session.
@@ -25,6 +66,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Spring Boot code examples extracted** — Java code examples moved to separate files to reduce `CLAUDE.md` size.
 
 ### Changed
+
 - **Default mode** for all new tasks is now `fast` instead of `auto`.
 - **`aiflow init` improvements** — Supports multi-select framework and protects existing instruction files from being overwritten.
 - **CLAUDE.md Optimization** — Reduced Spring Boot template size by ~70%, saving ~3-5k tokens per session.
@@ -32,18 +74,20 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Automatic Task Pausing** — When loading a new ticket, the current task is automatically paused and its state is saved.
 
 ### Fixed
-- Broken 404 documentation links on the npmjs.com page.
 
+- Broken 404 documentation links on the npmjs.com page.
 
 ---
 
 ## [0.0.4-beta.5] - 2026-04-21
 
 ### Added
+
 - Created a dedicated `docs/` folder to house all developer-facing documentation.
 - Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
 
 ### Changed
+
 - Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
 - Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
 - Updated `scripts/init.js` to source documentation from the new `docs/` location.
@@ -54,11 +98,13 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [0.0.5-beta.0] - 2026-04-23
 
 ### Added
+
 - **`aiflow gate <n> <action>` command** — Called automatically by AI during gate transitions. Supports `start` and `approved` actions for gates 1-5. Options: `--ticket <id>`, `--ai-tool <tool>`.
 - **Telemetry gate logging** — Gate workflow templates now emit `aiflow gate N start/approved --ticket [id]` telemetry calls at each gate transition for usage metrics.
 - **`aiflow telemetry flush` command** — Force-sends buffered telemetry events immediately.
 
 ### Changed
+
 - **`aiflow init` safe overwrite flow** — When a project already has `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc., `aiflow init` now prompts before overwriting:
   - **No (default):** keeps existing file untouched; saves the aiflow template to `.aiflow/reference/<file>` for manual comparison/merge.
   - **Yes:** backs up the existing file to `.aiflow/backup/<file>` before overwriting — nothing is permanently lost.
@@ -73,7 +119,8 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [0.0.5] - 2026-04-23
 
 ### Added
-- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption. 
+
+- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption.
   - `aiflow telemetry enable/disable/status` commands to easily opt-in or opt-out.
   - Automatically captures environment metadata and Git email via `git config --global user.email`.
   - Secure payload signing natively using Node `crypto` HMAC-SHA256 to ensure data authenticity.
@@ -81,6 +128,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Support tracking for multiple AI platforms including Cursor and Gemini via Command Execution events and the new Telemetry SDK.
 
 ### Security
+
 - **Strict Privacy**: Explicitly removed all prompt content and chat history tracking to ensure 100% confidentiality of company code and PII.
 
 ---
@@ -88,14 +136,18 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ## [0.0.3-beta.0] - 2026-04-13
+
 ### Security
+
 - Removed internal GitLab repository links and tracking information.
 - Cleaned `.npmrc` configuration.
 - Added helper scripts for beta and stable releases.
 
 ## [0.0.2] - 2026-04-13
+
 ### Changed
-- Updated package to scoped name `@relipa/ai-flow-kit` in documentation and configuration.
+
+- Updated package name in documentation and configuration.
 - Fixed installation guides in README and QUICK_START.
 
 ## [0.0.1] - 2026-04-13 — Initial Release
@@ -103,6 +155,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### Added
 
 #### CLI (`aiflow`)
+
 - `aiflow init` — scaffold AI workflow config into any project
   (supports `--framework` spring-boot/reactjs, `--adapter` jira/backlog)
 - `aiflow use <skill>` — activate a custom skill in the current project
@@ -113,6 +166,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `aiflow --version` — print installed version
 
 #### 5-Gate AI Workflow
+
 - **Gate 1 — AI Analyze Requirement**: Auto-starts when a ticket context exists
   in `.aiflow/context/current.json`; outputs `plan/[ticket-id]/requirement.md`
 - **Gate 2 — Implementation Plan**: TDD plan generation, gated by `APPROVED`
@@ -121,6 +175,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Gate 5 — Peer Review & PR**: Guided PR creation via `requesting-code-review` skill
 
 #### Custom Skills (7 skills)
+
 - `read-study-requirement` — Gate 1 requirement analysis with clarifying Q&A loop
 - `generate-spec` — Gate 2 TDD implementation spec generator
 - `impact-analysis` — breaking-change and dependency impact assessment
@@ -130,17 +185,20 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `figma-to-component` — Figma design → UI component code generator
 
 #### Multi-AI Support
+
 - **Claude Code** integration via `CLAUDE.md` + `.claude/` directory structure
 - **Gemini CLI** integration via `GEMINI.md`
 - **GitHub Copilot** integration via agents config
 - Superpowers skill library bundled as `upstream/` (pinned to v5.0.5)
 
 #### Project Templates
+
 - `AIFLOW.md` — team workflow reference document
 - `QUICK_START.md` — 5-minute setup guide
 - `.aiflowrc.json.example` — configuration file reference
 
 ### Architecture Notes
+
 - Stateless per-ticket design — no persistent memory across sessions (planned: v0.1.x)
 - Manual skill sync model via `aiflow use` (managed `aiflow skill` CLI planned: v0.1.x)
 - Spring Boot (Java 17+) used as the reference framework in `CLAUDE.md` coding rules
@@ -150,7 +208,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## How to upgrade
 
 ```bash
-npm install -g @relipa/ai-flow-kit@latest
+npm install -g ai-flow-kit@latest
 aiflow --version
 ```
 

package/docs/common/QUICK_START.md

@@ -7,17 +7,16 @@
 ## Installation
 
 ```bash
-# Stable version
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 
 # Beta version (recommend for newest features)
-npm install -g @relipa/ai-flow-kit@beta
+npm install -g ai-flow-kit@beta
 
 # Verification
 aiflow --version
 
 # Uninstall
-npm uninstall -g @relipa/ai-flow-kit
+npm uninstall -g ai-flow-kit
 ```
 
 ---
@@ -146,7 +145,7 @@ APPROVED
 
 AI outputs:
 - TDD task breakdown (test first → implement → verify)
-- Commit strategy (small, focused commits)
+- Verification strategy (evidence before claims)
 - Test commands
 
 **Your action:**
@@ -166,7 +165,7 @@ APPROVED
 
 - Writes tests FIRST → runs → confirms FAIL
 - Implements code → tests PASS
-- Commits each small step
+- Verifies implementation works
 
 **Your action:** Monitor. No action needed unless AI asks a question.
 
@@ -217,9 +216,9 @@ Ask a teammate to review. They can use `superpowers:receiving-code-review` skill
 
 After peer reviewer approves → merge → task complete.
 
-### Step 9: Task Management (Context Switching)
+### Step 9: Task Management & Session Continuity
 
-If you need to switch to another task mid-flow:
+Manage multiple tasks and ensure clean transitions between gates to prevent "context pollution" in long AI sessions.
 
 ```bash
 # Pause current task (saves gate progress)
@@ -230,8 +229,26 @@ aiflow task list
 
 # Resume a previously paused task
 aiflow task resume PROJ-33
+
+# Approve gate and prepare for fresh session (Recommended)
+aiflow task next
 ```
 
+#### Best Practice: Refreshing Sessions
+To keep the AI focused and avoid context pollution (where the AI gets confused by long chat history), it is recommended to start a **fresh chat session** after completing each gate.
+
+1. Run `aiflow task next` in your terminal to approve the current gate.
+2. Open a **NEW chatbox** (Claude UI, Cursor, etc.).
+3. Run `aiflow task resume [ticket-id]` (if not already active).
+4. Type **"continue"** — the AI will read the latest state and start the next gate with a clean slate.
+
+#### Resuming Gate 3 (Code Generation)
+If you need to switch chatboxes in the middle of a complex coding task (Gate 3):
+- Gate 3 progress is saved via `[x]` checkboxes in the plan file (`plan/[id]/plan.md`).
+- Simply open a new chatbox, run `aiflow task resume`, and tell the AI to **"continue executing the plan"**.
+- The AI will automatically skip finished tasks and pick up exactly where you left off.
+
+
 ---
 
 ## Workflow Summary Diagram
@@ -256,7 +273,7 @@ Developer                          AI                              Peer
    │  "APPROVED" ──────────────────►│                                │
    │                                │                                │
    │        GATE 3                  │  Write tests → implement       │
-   │        (monitor)               │  Commit each step              │
+   │        (monitor)               │  Verify implementation works   │
    │                                │                                │
    │  ─── GATE 4 ──────────────────►│                                │
    │                                │  Self-review + summary         │
@@ -317,10 +334,13 @@ claude                                # AI auto-starts: map dependencies → ass
 ```bash
 # Setup
 aiflow init --framework nestjs --adapter backlog
-aiflow init --framework spring-boot --with-rtk   # force enable RTK compression
-aiflow init --no-rtk                            # skip RTK setup
+aiflow init --framework spring-boot --with-rtk        # RTK: bash output compression (60–90%)
+# aiflow init --framework spring-boot --with-gitnexus          # GitNexus: waits for index to complete
+# aiflow init --framework spring-boot --with-gitnexus --no-wait # GitNexus: index in background
+aiflow init --no-rtk                                 # skip RTK setup
 aiflow doctor                                   # health check
 aiflow guide                                    # multi-tool guide
+aiflow sync-skills                              # manually sync AI instruction files
 
 # Per task
 aiflow use PROJ-33                              # load context (Fast Mode, default)
@@ -366,7 +386,7 @@ aiflow guide --commands               # command reference
 aiflow remove                         # remove from project
 aiflow remove --global                # uninstall globally (npm uninstall -g)
 aiflow remove --version 1.0.0         # remove cached version from .aiflow/
-npm uninstall -g @relipa/ai-flow-kit  # standard npm uninstall
+npm uninstall -g ai-flow-kit  # standard npm uninstall
 ```
 
 ---
@@ -405,7 +425,7 @@ aiflow guide
 
 **`aiflow` not found:**
 ```bash
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 ```
 
 **Incorrect credentials:**

package/docs/common/cli-reference.md

@@ -399,6 +399,29 @@ You can switch back with: aiflow use 1.0.0
 ✨ Update completed!
 ```
 
+## sync-skills
+
+Manually synchronize AI Instruction files with local custom skills.
+
+```bash
+# Sync AI Instruction files
+aiflow sync-skills
+```
+
+**What it does:**
+1. Reads all active local skills and upstream skills
+2. Generates the updated AI Skill Registry table
+3. Safely updates the AI Instruction blocks (`<!-- aiflow-kit-start -->`) in your project's `CLAUDE.md`, `GEMINI.md`, or `.cursorrules` without wiping your custom rules
+4. If no marker blocks are found, it asks for confirmation to overwrite with the correct structure
+
+**Example:**
+```bash
+$ aiflow sync-skills
+⟳ Syncing AI Instruction files...
+  ✓ Updated AI Flow block in CLAUDE.md
+✨ Sync completed!
+```
+
 ## doctor
 
 Health check for your setup.

package/package.json

@@ -1,13 +1,8 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.6",
+  "version": "0.0.7-beta.1",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
-  "author": "Relipa AI Team",
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.relipa.vn/ai/ai-flow-kit.git"
-  },
-  "homepage": "https://gitlab.relipa.vn/ai/ai-flow-kit#readme",
+  "author": "Example Team",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.com/"

package/scripts/checkpoint.js

@@ -0,0 +1,46 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const PROJECT_DIR  = process.cwd();
+const AIFLOW_DIR   = path.join(PROJECT_DIR, '.aiflow');
+const CONTEXT_FILE = path.join(AIFLOW_DIR, 'context', 'current.json');
+
+const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+
+module.exports = async function checkpoint(options = {}) {
+    const { gate, step, tokens, ticket: ticketOpt } = options;
+
+    if (!gate || !step || tokens === undefined) {
+        console.log(chalk.yellow('Usage: aiflow checkpoint --gate <N> --step <name> --tokens <N>'));
+        console.log(chalk.gray('  Example: aiflow checkpoint --gate 3 --step "tests-written" --tokens 3200'));
+        return;
+    }
+
+    // Resolve ticket ID
+    let ticketId = ticketOpt;
+    if (!ticketId) {
+        const ctx = await fs.readJson(CONTEXT_FILE).catch(() => null);
+        ticketId = ctx && ctx.taskId ? ctx.taskId : 'unknown';
+    }
+
+    const taskDir = path.join(AIFLOW_DIR, 'tasks', ticketId);
+    await fs.ensureDir(taskDir);
+
+    const checkpointPath = path.join(taskDir, 'checkpoints.json');
+    const existing = (await fs.pathExists(checkpointPath))
+        ? await fs.readJson(checkpointPath).catch(() => ({ checkpoints: [] }))
+        : { checkpoints: [] };
+
+    const entry = {
+        gate:      parseInt(gate),
+        step,
+        tokens:    parseInt(tokens),
+        timestamp: new Date().toISOString(),
+    };
+    existing.checkpoints.push(entry);
+    await fs.writeJson(checkpointPath, existing, { spaces: 2 });
+
+    const label = GATE_LABELS[parseInt(gate)] || `Gate ${gate}`;
+    console.log(chalk.green(`✓ Checkpoint: Gate ${gate} (${label}) — ${step} — ~${parseInt(tokens).toLocaleString()} tokens`));
+};

package/scripts/doctor.js

@@ -1,15 +1,71 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
-const { detectRtk, isRtkHookConfigured } = require('./init');
+const { detectRtk, isRtkHookConfigured, isGitNexusConfigured } = require('./init');
 
-module.exports = async function doctor() {
+function formatAgo(isoString) {
+    const ms = Date.now() - new Date(isoString).getTime();
+    const mins = Math.floor(ms / 60000);
+    if (mins < 1)   return 'just now';
+    if (mins < 60)  return `${mins}m ago`;
+    const hrs = Math.floor(mins / 60);
+    if (hrs < 24)   return `${hrs}h ago`;
+    return `${Math.floor(hrs / 24)}d ago`;
+}
+
+async function showTokenBreakdown(ticketId) {
+    const tasksDir = path.join(process.cwd(), '.aiflow', 'tasks');
+    const checkpointsFile = path.join(tasksDir, ticketId, 'checkpoints.json');
+    if (!(await fs.pathExists(checkpointsFile))) return;
+
+    const data = await fs.readJson(checkpointsFile).catch(() => ({ checkpoints: [] }));
+    if (!data.checkpoints || data.checkpoints.length === 0) return;
+
+    // Aggregate tokens per gate (taking the max/latest)
+    const gateTokens = {};
+    for (const cp of data.checkpoints) {
+        if (!gateTokens[cp.gate] || cp.tokens > gateTokens[cp.gate]) {
+            gateTokens[cp.gate] = cp.tokens;
+        }
+    }
+
+    const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+    const gates = Object.keys(gateTokens).sort();
+    const total = gates.reduce((sum, g) => sum + gateTokens[g], 0);
+
+    console.log('');
+    console.log(chalk.bold(`Token usage for task ${ticketId}:`));
+    for (const g of gates) {
+        const label = GATE_LABELS[parseInt(g)] || `Gate ${g}`;
+        const t = gateTokens[g];
+        const bar = '█'.repeat(Math.round((t / total) * 20)).padEnd(20, '░');
+        const pct = Math.round((t / total) * 100);
+        console.log(`  Gate ${g}  ${label.padEnd(8)}  ~${t.toLocaleString().padStart(6)}  ${chalk.gray(bar)}  ${pct}%`);
+    }
+    console.log(`  Total estimated: ~${total.toLocaleString()} tokens`);
+}
+
+module.exports = async function doctor(options = {}) {
     const projectDir = process.cwd();
     const errors = [];
     const warnings = [];
 
     console.log(chalk.blue('Running health check for AI Flow Kit...\n'));
 
+    // ── Token breakdown ────────────────────────────────────────
+    let ticketId = options.ticket;
+    if (!ticketId) {
+        const contextFile = path.join(projectDir, '.aiflow', 'context', 'current.json');
+        if (await fs.pathExists(contextFile)) {
+            const ctx = await fs.readJson(contextFile).catch(() => ({}));
+            ticketId = ctx.taskId;
+        }
+    }
+
+    if (ticketId) {
+        await showTokenBreakdown(ticketId);
+    }
+
     // ── Core setup ─────────────────────────────────────────────
     if (!(await fs.pathExists(path.join(projectDir, '.claude', 'skills')))) {
         errors.push('Missing `.claude/skills` directory. Did you run `aiflow init`?');
@@ -55,20 +111,67 @@ module.exports = async function doctor() {
         warnings.push('Missing .claude/settings.json — run `aiflow init`.');
     }
 
-    // ── RTK token compression ──────────────────────────────────
+    // ── Token savings tools ────────────────────────────────────
     console.log('');
+    console.log(chalk.bold('Token savings:'));
+
+    // RTK
     const rtk = await detectRtk();
     if (rtk.installed) {
         const hookOk = await isRtkHookConfigured(projectDir);
         if (hookOk) {
-            console.log(chalk.green(`✓ RTK installed (${rtk.version}) — token compression active`));
+            console.log(chalk.green(`  ✓ RTK (${rtk.version}) — bash output compression active`));
+            console.log(chalk.gray('    Estimated: 60–90% reduction on bash command outputs (test runs, git, npm...)'));
         } else {
-            console.log(chalk.green(`✓ RTK installed (${rtk.version})`));
-            warnings.push('RTK is installed but hook not configured. Run `aiflow init` to enable token compression.');
+            console.log(chalk.yellow(`  ⚠ RTK installed (${rtk.version}) but hook not configured`));
+            warnings.push('RTK hook not configured. Run `aiflow init` to enable token compression.');
+        }
+    } else {
+        console.log(chalk.gray('  ○ RTK not installed — bash output compression inactive'));
+        console.log(chalk.gray('    Install: cargo install rtk  |  Enable: aiflow init --with-rtk'));
+    }
+
+    // GitNexus
+    const gnConfigured = await isGitNexusConfigured(projectDir);
+    const gnStatusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
+    if (gnConfigured) {
+        let statusLine = chalk.green('  ✓ GitNexus MCP configured');
+        try {
+            if (await fs.pathExists(gnStatusPath)) {
+                const gn = await fs.readJson(gnStatusPath);
+                const GITNEXUS_STALE_MS = 3 * 60 * 60 * 1000; // 3 hours
+                if (gn.status === 'done') {
+                    const ago = gn.completedAt
+                        ? chalk.gray(` — indexed ${formatAgo(gn.completedAt)}`)
+                        : '';
+                    statusLine = chalk.green(`  ✓ GitNexus MCP configured — index ready${ago}`);
+                    console.log(statusLine);
+                    console.log(chalk.gray('    Estimated: ~50% fewer tokens at Gate 1 (context queries vs file reads)'));
+                    console.log(chalk.gray('    Estimated: ~70% fewer tokens at Gate 4 (impact() vs grep codebase)'));
+                } else if (gn.status === 'running') {
+                    const age = Date.now() - new Date(gn.startedAt).getTime();
+                    if (age > GITNEXUS_STALE_MS) {
+                        console.log(chalk.red('  ✗ GitNexus MCP configured — indexing timed out (stale)'));
+                        console.log(chalk.gray(`    Started ${formatAgo(gn.startedAt)} but never finished. Process may have crashed.`));
+                        // console.log(chalk.gray('    Retry: aiflow init --with-gitnexus --wait  |  Log: .aiflow/gitnexus-analyze.log'));
+                    } else {
+                        console.log(chalk.yellow('  ⟳ GitNexus MCP configured — indexing in progress...'));
+                        console.log(chalk.gray('    Log: .aiflow/gitnexus-analyze.log'));
+                    }
+                } else if (gn.status === 'error') {
+                    console.log(chalk.red('  ✗ GitNexus MCP configured — last index failed'));
+                    console.log(chalk.gray('    Retry: npx gitnexus analyze  |  Log: .aiflow/gitnexus-analyze.log'));
+                }
+            } else {
+                console.log(chalk.yellow('  ⚠ GitNexus MCP configured but not yet indexed'));
+                console.log(chalk.gray('    Run: npx gitnexus analyze'));
+            }
+        } catch (_) {
+            console.log(statusLine);
         }
     } else {
-        console.log(chalk.gray('○ RTK not installed (optional) — token compression inactive'));
-        console.log(chalk.gray('  Install: cargo install rtk  |  More: https://github.com/rtk-ai/rtk'));
+        console.log(chalk.gray('  ○ GitNexus not configured — code intelligence inactive'));
+        // console.log(chalk.gray('    Enable: aiflow init --with-gitnexus'));
     }
 
     // ── Summary ────────────────────────────────────────────────