@ariacode/cli 0.2.2 → 0.2.3

package/dist/actions.js

@@ -19,12 +19,15 @@ import { getConfig } from "./config.js";
 import { detectProjectType } from "./repo.js";
 import { createProvider, ProviderError } from "./provider.js";
 import { initializeDatabase, createSession, updateSessionStatus, getSession, logMessage, listSessions, } from "./storage.js";
-import { readFileTool, listDirectoryTool, searchCodeTool, readPackageJsonTool, readPrismaSchemaTool, proposeDiffTool, applyDiffTool, } from "./tools.js";
+import { searchSessions, filterSessions, exportSessionMarkdown, } from "./storage/queries.js";
+import { readFileTool, listDirectoryTool, searchCodeTool, readPackageJsonTool, readPrismaSchemaTool, proposeDiffTool, applyDiffTool, setDiffRenderOptions, } from "./tools.js";
 import { agentLoop, UserCancelledError } from "./agent.js";
 import prompts from "prompts";
-import { initUI, info, print, error as uiError, bold, yellow, green, dim, cyan, red, renderTable, generateAndRenderDiff, confirm, ConfirmCancelledError, } from "./ui.js";
+import { initUI, info, print, error as uiError, bold, yellow, green, dim, cyan, red, stripAnsi, renderTable, generateAndRenderDiff, confirm, ConfirmCancelledError, } from "./ui.js";
+import { renderDiff as renderDiffEnhanced } from "./ui/diff-renderer.js";
+import { formatOutput, AskOutputSchema, PlanOutputSchema, ReviewOutputSchema, ExploreOutputSchema, HistoryOutputSchema, DoctorOutputSchema, } from "./output/schemas.js";
 import { loadConfig, validateConfig } from "./config.js";
-import { getShellRcPath } from "./fs-helpers.js";
+import { getShellRcPath, writeFileAtomic } from "./fs-helpers.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // ---------------------------------------------------------------------------
 // Provider resolution with interactive setup
@@ -212,7 +215,6 @@ function saveProviderChoice(config) {
 // ---------------------------------------------------------------------------
 /**
  * The five read-only tools exposed to the ask command.
- * Requirements: 9.4
  */
 const READ_ONLY_TOOLS = [
     readFileTool,
@@ -340,19 +342,18 @@ function buildSystemPrompt(templateName, ctx, extraVars = {}) {
  * Execute the ask command.
  *
  * Flow:
- * 1. Load configuration and detect project type          (Req 9.1)
- * 2. Create or resume session with mode: "plan"          (Req 9.2, 9.9)
- * 3. Build system prompt from ask.md template            (Req 9.3)
- * 4. Expose only read-only tools                         (Req 9.4)
- * 5. Execute agent loop                                  (Req 9.5, 9.6)
- * 6. Render response to terminal                         (Req 9.7)
- * 7. Persist session to database                         (Req 9.8)
+ * 1. Load configuration and detect project type
+ * 2. Create or resume session with mode: "plan"
+ * 3. Build system prompt from ask.md template
+ * 4. Expose only read-only tools
+ * 5. Execute agent loop
+ * 6. Render response to terminal
+ * 7. Persist session to database
  *
- * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 9.9
  */
 export async function runAsk(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
-    // 1. Load configuration (Req 9.1)
+    // 1. Load configuration 
     const config = getConfig(projectRoot, {
         quiet: options.quiet,
         maxTokens: options.maxTokens,
@@ -360,15 +361,15 @@ export async function runAsk(options) {
         model: options.model,
     });
     // Initialize UI with config settings
-    initUI(config.ui.color, config.ui.quiet);
-    // Detect project type early to fail fast if package.json is missing (Req 9.1)
+    initUI(config.ui.color, config.ui.quiet || (options.format === 'json' || options.format === 'ndjson'));
+    // Detect project type early to fail fast if package.json is missing 
     detectProjectType(projectRoot);
-    // 2. Initialize database and create/resume session (Req 9.2, 9.8, 9.9)
+    // 2. Initialize database and create/resume session 
     const db = initializeDatabase();
     let sessionId;
     let resumedMessages = [];
     if (options.session) {
-        // Resume existing session (Req 9.9)
+        // Resume existing session 
         const existing = getSession(db, options.session);
         if (!existing) {
             uiError(`Session not found: ${options.session}`);
@@ -383,7 +384,7 @@ export async function runAsk(options) {
         resumedMessages = rows;
     }
     else {
-        // Create new session (Req 9.2)
+        // Create new session 
         sessionId = randomUUID();
         createSession(db, {
             id: sessionId,
@@ -408,7 +409,7 @@ export async function runAsk(options) {
         updateSessionStatus(db, sessionId, "failed", String(err));
         process.exit(4);
     }
-    // 4. Build execution context with mode: "plan" (Req 9.2)
+    // 4. Build execution context with mode: "plan" 
     const ctx = {
         projectRoot,
         sessionId,
@@ -424,7 +425,7 @@ export async function runAsk(options) {
     if (options.maxTokens !== undefined) {
         config.provider.maxTokens = options.maxTokens;
     }
-    // 5. Build system prompt from ask.md template (Req 9.3)
+    // 5. Build system prompt from ask.md template 
     const systemPrompt = buildSystemPrompt("ask", ctx);
     // Log system prompt as a system message
     logMessage(db, sessionId, "system", systemPrompt);
@@ -441,15 +442,34 @@ export async function runAsk(options) {
             .join("\n\n");
         userRequest = `[Resumed session context]\n${priorContext}\n\n[New question]: ${options.question}`;
     }
-    // 6. Execute agent loop (Req 9.5, 9.6)
-    // agentLoop streams the response to stdout as it arrives (Req 9.7)
+    // 6. Execute agent loop 
+    // agentLoop streams the response to stdout as it arrives 
     try {
-        await agentLoop(ctx, userRequest, READ_ONLY_TOOLS, provider, config, "ask", db, systemPrompt);
-        // 7. Mark session as completed (Req 9.8)
+        const answer = await agentLoop(ctx, userRequest, READ_ONLY_TOOLS, provider, config, "ask", db, systemPrompt);
+        // v0.2.3: structured output
+        if (options.format === 'json' || options.format === 'ndjson') {
+            process.stdout.write(formatOutput({ version: '1', answer, sessionId }, options.format, AskOutputSchema));
+        }
+        else if (options.format === 'plain') {
+            // Strip ANSI codes and write plain text
+            process.stdout.write(stripAnsi(answer) + '\n');
+        }
+        // 7. Mark session as completed
         updateSessionStatus(db, sessionId, "completed");
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        // v0.2.3: structured error output
+        if (options.format === 'json') {
+            process.stderr.write(JSON.stringify({ version: '1', error: message, exitCode: 1 }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
+        else if (options.format === 'ndjson') {
+            process.stderr.write(JSON.stringify({ version: '1', event: 'error', error: message }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
         uiError(message);
         updateSessionStatus(db, sessionId, "failed", message);
         process.exit(1);
@@ -459,35 +479,34 @@ export async function runAsk(options) {
  * Execute the plan command.
  *
  * Flow:
- * 1. Load configuration and detect project type          (Req 10.1)
- * 2. Create or resume session with mode: "plan"          (Req 10.2, 10.8)
- * 3. Build system prompt from plan.md template           (Req 10.3)
- * 4. Expose only read-only tools                         (Req 10.4)
- * 5. Execute agent loop                                  (Req 10.5)
- * 6. Render structured plan to terminal                  (Req 10.6)
- * 7. Save to file if --output flag provided              (Req 10.7)
- * 8. Persist session to database                         (Req 10.8)
+ * 1. Load configuration and detect project type
+ * 2. Create or resume session with mode: "plan"
+ * 3. Build system prompt from plan.md template
+ * 4. Expose only read-only tools
+ * 5. Execute agent loop
+ * 6. Render structured plan to terminal
+ * 7. Save to file if --output flag provided
+ * 8. Persist session to database
  *
- * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5, 10.6, 10.7, 10.8
  */
 export async function runPlan(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
-    // 1. Load configuration (Req 10.1)
+    // 1. Load configuration 
     const config = getConfig(projectRoot, {
         quiet: options.quiet,
         provider: options.provider,
         model: options.model,
     });
     // Initialize UI with config settings
-    initUI(config.ui.color, config.ui.quiet);
-    // Detect project type early to fail fast if package.json is missing (Req 10.1)
+    initUI(config.ui.color, config.ui.quiet || (options.format === 'json' || options.format === 'ndjson'));
+    // Detect project type early to fail fast if package.json is missing 
     detectProjectType(projectRoot);
-    // 2. Initialize database and create/resume session (Req 10.2, 10.8)
+    // 2. Initialize database and create/resume session 
     const db = initializeDatabase();
     let sessionId;
     let resumedMessages = [];
     if (options.session) {
-        // Resume existing session (Req 10.8)
+        // Resume existing session 
         const existing = getSession(db, options.session);
         if (!existing) {
             uiError(`Session not found: ${options.session}`);
@@ -502,7 +521,7 @@ export async function runPlan(options) {
         resumedMessages = rows;
     }
     else {
-        // Create new session (Req 10.2)
+        // Create new session 
         sessionId = randomUUID();
         createSession(db, {
             id: sessionId,
@@ -527,7 +546,7 @@ export async function runPlan(options) {
         updateSessionStatus(db, sessionId, "failed", String(err));
         process.exit(4);
     }
-    // 4. Build execution context with mode: "plan" (Req 10.2)
+    // 4. Build execution context with mode: "plan" 
     const ctx = {
         projectRoot,
         sessionId,
@@ -539,7 +558,7 @@ export async function runPlan(options) {
         maxIterations: config.agent.maxIterations,
         timeoutSeconds: config.agent.timeoutSeconds,
     };
-    // 5. Build system prompt from plan.md template (Req 10.3)
+    // 5. Build system prompt from plan.md template 
     const systemPrompt = buildSystemPrompt("plan", ctx, { userGoal: options.goal });
     // Log system prompt as a system message
     logMessage(db, sessionId, "system", systemPrompt);
@@ -553,17 +572,21 @@ export async function runPlan(options) {
             .join("\n\n");
         userRequest = `[Resumed session context]\n${priorContext}\n\n[New goal]: ${options.goal}`;
     }
-    // 6. Execute agent loop — streams response to stdout (Req 10.5, 10.6)
+    // 6. Execute agent loop — streams response to stdout 
     try {
         const planContent = await agentLoop(ctx, userRequest, READ_ONLY_TOOLS, provider, config, "plan", db, systemPrompt);
-        // 7. Save to file if --output flag provided (Req 10.7)
+        // v0.2.3: structured output 
+        if (options.format === 'json' || options.format === 'ndjson') {
+            process.stdout.write(formatOutput({ version: '1', plan: planContent, sessionId, outputPath: options.output }, options.format, PlanOutputSchema));
+        }
+        // 7. Save to file if --output flag provided
         if (options.output) {
             const outputPath = path.resolve(options.output);
             const outputDir = path.dirname(outputPath);
             if (!existsSync(outputDir)) {
                 mkdirSync(outputDir, { recursive: true });
             }
-            writeFileSync(outputPath, planContent, "utf-8");
+            writeFileAtomic(outputPath, planContent);
             info(`Plan saved to ${options.output}`);
         }
         // 8. Mark session as completed (Req 10.8)
@@ -571,6 +594,17 @@ export async function runPlan(options) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        // v0.2.3: structured error output 
+        if (options.format === 'json') {
+            process.stderr.write(JSON.stringify({ version: '1', error: message, exitCode: 1 }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
+        else if (options.format === 'ndjson') {
+            process.stderr.write(JSON.stringify({ version: '1', event: 'error', error: message }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
         uiError(message);
         updateSessionStatus(db, sessionId, "failed", message);
         process.exit(1);
@@ -580,25 +614,24 @@ export async function runPlan(options) {
  * Execute the patch command.
  *
  * Flow:
- * 1. Load configuration and detect project type          (Req 11.1)
- * 2. Create session with mode: "build"                   (Req 11.2)
- * 3. Build system prompt from patch.md template          (Req 11.3)
- * 4. Expose read-only + mutation tools                   (Req 11.4)
- * 5. Execute agent loop — agent calls propose_diff       (Req 11.4, 11.5)
- * 6. Render diff preview with syntax highlighting        (Req 11.6)
- * 7. Render mutation summary                             (Req 11.7)
- * 8. If --dry-run, exit with code 0                      (Req 11.8, 17.3, 17.4)
- * 9. If not --yes, prompt for confirmation               (Req 11.9, 17.5)
- * 10. Agent calls apply_diff atomically                  (Req 11.10, 11.11, 11.12)
- * 11. Log mutation to database                           (Req 11.11)
- * 12. Display rollback hints                             (Req 11.12, 17.9)
- * 13. Persist session to database                        (Req 11.13)
+ * 1. Load configuration and detect project type
+ * 2. Create session with mode: "build"
+ * 3. Build system prompt from patch.md template
+ * 4. Expose read-only + mutation tools
+ * 5. Execute agent loop — agent calls propose_diff
+ * 6. Render diff preview with syntax highlighting
+ * 7. Render mutation summary
+ * 8. If --dry-run, exit with code 0
+ * 9. If not --yes, prompt for confirmation
+ * 10. Agent calls apply_diff atomically
+ * 11. Log mutation to database
+ * 12. Display rollback hints
+ * 13. Persist session to database
  *
- * Requirements: 11.1–11.13, 17.1–17.9
  */
 export async function runPatch(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
-    // 1. Load configuration (Req 11.1)
+    // 1. Load configuration 
     const config = getConfig(projectRoot, {
         quiet: options.quiet,
         provider: options.provider,
@@ -609,9 +642,14 @@ export async function runPatch(options) {
         config.agent.mode = "build"; // keep build mode, dryRun handled via ctx
     // Initialize UI with config settings
     initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet));
-    // Detect project type early to fail fast (Req 11.1)
+    // Plain format guard: require --yes for mutation commands 
+    if (options.format === 'plain' && !options.yes) {
+        process.stdout.write('plain format requires --yes for mutation commands\n');
+        process.exit(2);
+    }
+    // Detect project type early to fail fast 
     detectProjectType(projectRoot);
-    // 2. Initialize database and create session (Req 11.13)
+    // 2. Initialize database and create session 
     const db = initializeDatabase();
     let sessionId;
     if (options.session) {
@@ -648,7 +686,7 @@ export async function runPatch(options) {
         updateSessionStatus(db, sessionId, "failed", String(err));
         process.exit(4);
     }
-    // 4. Build execution context with mode: "build" (Req 11.2, 17.1, 17.2)
+    // 4. Build execution context with mode: "build" 
     const ctx = {
         projectRoot,
         sessionId,
@@ -660,10 +698,10 @@ export async function runPatch(options) {
         maxIterations: config.agent.maxIterations,
         timeoutSeconds: config.agent.timeoutSeconds,
     };
-    // 5. Build system prompt from patch.md template (Req 11.3)
+    // 5. Build system prompt from patch.md template 
     const systemPrompt = buildSystemPrompt("patch", ctx);
     logMessage(db, sessionId, "system", systemPrompt);
-    // Expose read-only tools + mutation tools (Req 11.4)
+    // Expose read-only tools + mutation tools
     const patchTools = [
         readFileTool,
         listDirectoryTool,
@@ -676,15 +714,25 @@ export async function runPatch(options) {
     if (options.dryRun) {
         info(bold("Dry-run mode — changes will be previewed but not applied."));
     }
-    // 6. Execute agent loop (Req 11.4, 11.5, 11.6, 11.7, 11.8, 11.9, 11.10)
+    // Configure enhanced diff renderer
+    const terminalWidth = process.stdout.columns ?? 80;
+    const diffRenderOptions = {
+        split: options.split ?? false,
+        lineNumbers: options.format !== 'plain',
+        collapseThreshold: 5,
+        terminalWidth,
+        ...(options.format === 'plain' ? { language: undefined } : {}),
+    };
+    setDiffRenderOptions((diffText) => renderDiffEnhanced(diffText, diffRenderOptions));
+    // 6. Execute agent loop 
     // The agent loop handles:
-    //   - propose_diff: generates diff + MutationSummary (Req 11.4, 11.5)
-    //   - dry-run enforcement: skips apply_diff (Req 11.8, 17.3, 17.4)
-    //   - confirmation prompt before apply_diff (Req 11.9, 17.5, 17.6)
-    //   - atomic application via apply_diff (Req 11.10, 11.11, 11.12)
+    //   - propose_diff: generates diff + MutationSummary
+    //   - dry-run enforcement: skips apply_diff
+    //   - confirmation prompt before apply_diff 
+    //   - atomic application via apply_diff 
     try {
         await agentLoop(ctx, options.description, patchTools, provider, config, "patch", db, systemPrompt);
-        // 12. Display rollback hints after successful application (Req 11.12, 17.9)
+        // 12. Display rollback hints after successful application
         // The agent loop streams the response which includes rollback hints from
         // the apply_diff result. We add a final summary line here.
         if (!options.dryRun) {
@@ -696,22 +744,37 @@ export async function runPatch(options) {
             info("");
             info(yellow("Dry-run complete — no files were modified."));
         }
-        // 13. Mark session as completed (Req 11.13)
+        // 13. Mark session as completed
         updateSessionStatus(db, sessionId, "completed");
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        // Handle user cancellation (Req 17.6, exit code 130)
+        // Handle user cancellation
         if (err instanceof UserCancelledError || err instanceof ConfirmCancelledError) {
             info("");
             info(yellow("Operation cancelled."));
             updateSessionStatus(db, sessionId, "cancelled");
             process.exit(130);
         }
+        // v0.2.3: structured error output
+        if (options.format === 'json') {
+            process.stderr.write(JSON.stringify({ version: '1', error: message, exitCode: 1 }) + '\n');
+            updateSessionStatus(db, sessionId, "failed", message);
+            process.exit(1);
+        }
+        else if (options.format === 'ndjson') {
+            process.stderr.write(JSON.stringify({ version: '1', event: 'error', error: message }) + '\n');
+            updateSessionStatus(db, sessionId, "failed", message);
+            process.exit(1);
+        }
         uiError(message);
         updateSessionStatus(db, sessionId, "failed", message);
         process.exit(1);
     }
+    finally {
+        // Clear diff render options after patch completes
+        setDiffRenderOptions(null);
+    }
 }
 /**
  * Read git diff based on the provided options.
@@ -720,21 +783,20 @@ export async function runPatch(options) {
  * - --unstaged: unstaged changes (`git diff`)
  * - --branch <base>: compare to base branch (`git diff <base>...HEAD`)
  *
- * Requirements: 12.3, 12.4, 12.5
  */
 function readGitDiff(options, projectRoot) {
     try {
         let args;
         if (options.branch) {
-            // Compare current branch to specified base (Req 12.5)
+            // Compare current branch to specified base 
             args = ["diff", `${options.branch}...HEAD`];
         }
         else if (options.unstaged) {
-            // Unstaged changes (Req 12.4)
+            // Unstaged changes 
             args = ["diff"];
         }
         else {
-            // Staged changes — default (Req 12.3)
+            // Staged changes — default 
             args = ["diff", "--cached"];
         }
         const output = execFileSync("git", args, {
@@ -754,7 +816,6 @@ function readGitDiff(options, projectRoot) {
  * Extracts summary, issues (with severity), and suggestions from the
  * "# Code Review" markdown format defined in review.md.
  *
- * Requirements: 12.7
  */
 function parseReviewResponse(content) {
     const result = {
@@ -805,7 +866,6 @@ function parseReviewResponse(content) {
 /**
  * Render the structured review to the terminal in readable format.
  *
- * Requirements: 12.8
  */
 function renderReview(review) {
     info("");
@@ -844,32 +904,31 @@ function renderReview(review) {
  * Execute the review command.
  *
  * Flow:
- * 1. Parse flags and load configuration                  (Req 12.1)
- * 2. Detect project type                                 (Req 12.1)
- * 3. Create session with mode: "plan"                    (Req 12.2)
- * 4. Read git diff (staged / unstaged / branch)          (Req 12.3, 12.4, 12.5)
- * 5. Build system prompt from review.md template         (Req 12.6)
- * 6. Send diff + project context to provider             (Req 12.6)
- * 7. Parse structured review (summary, issues, suggestions) (Req 12.7)
- * 8. Render review to terminal                           (Req 12.8)
- * 9. Output JSON if --format json                        (Req 12.9)
- * 10. Persist session to database                        (Req 12.10)
+ * 1. Parse flags and load configuration
+ * 2. Detect project type
+ * 3. Create session with mode: "plan"
+ * 4. Read git diff (staged / unstaged / branch)
+ * 5. Build system prompt from review.md template
+ * 6. Send diff + project context to provider
+ * 7. Parse structured review (summary, issues, suggestions)
+ * 8. Render review to terminal
+ * 9. Output JSON if --format json
+ * 10. Persist session to database
  *
- * Requirements: 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, 12.10
  */
 export async function runReview(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
-    // 1. Load configuration (Req 12.1)
+    // 1. Load configuration 
     const config = getConfig(projectRoot, {
         quiet: options.quiet,
         provider: options.provider,
         model: options.model,
     });
     // Initialize UI with config settings
-    initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet));
-    // 2. Detect project type early to fail fast (Req 12.1)
+    initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet) || (options.format === 'json' || options.format === 'ndjson'));
+    // 2. Detect project type early to fail fast 
     detectProjectType(projectRoot);
-    // 3. Initialize database and create session (Req 12.10)
+    // 3. Initialize database and create session 
     const db = initializeDatabase();
     const sessionId = randomUUID();
     createSession(db, {
@@ -894,7 +953,7 @@ export async function runReview(options) {
         updateSessionStatus(db, sessionId, "failed", String(err));
         process.exit(4);
     }
-    // Build execution context with mode: "plan" (Req 12.2)
+    // Build execution context with mode: "plan" 
     const ctx = {
         projectRoot,
         sessionId,
@@ -906,7 +965,7 @@ export async function runReview(options) {
         maxIterations: config.agent.maxIterations,
         timeoutSeconds: config.agent.timeoutSeconds,
     };
-    // 4. Read git diff (Req 12.3, 12.4, 12.5)
+    // 4. Read git diff 
     let diff;
     try {
         diff = readGitDiff(options, projectRoot);
@@ -927,10 +986,10 @@ export async function runReview(options) {
         updateSessionStatus(db, sessionId, "completed");
         return;
     }
-    // 5. Build system prompt from review.md template (Req 12.6)
+    // 5. Build system prompt from review.md template 
     const systemPrompt = buildSystemPrompt("review", ctx);
     logMessage(db, sessionId, "system", systemPrompt);
-    // 6. Build user request: diff + project context (Req 12.6)
+    // 6. Build user request: diff + project context 
     const project = detectProjectType(projectRoot);
     const diffSource = options.branch
         ? `branch diff (current vs ${options.branch})`
@@ -950,23 +1009,28 @@ export async function runReview(options) {
     ]
         .filter((l) => l !== null)
         .join("\n");
-    // Execute agent loop — streams response to stdout (Req 12.6, 12.7, 12.8)
+    // Execute agent loop — streams response to stdout 
     try {
         const reviewContent = await agentLoop(ctx, userRequest, READ_ONLY_TOOLS, provider, config, "review", db, systemPrompt);
-        // 7. Parse structured review (Req 12.7)
+        // 7. Parse structured review 
         const review = parseReviewResponse(reviewContent);
-        // 8 & 9. Render or output JSON (Req 12.8, 12.9)
-        if (options.format === "json") {
-            // JSON output to stdout (Req 12.9)
-            process.stdout.write(JSON.stringify(review, null, 2) + "\n");
+        // 8 & 9. Render or output 
+        if (options.format === 'json' || options.format === 'ndjson') {
+            // v0.2.3: structured output via formatOutput
+            process.stdout.write(formatOutput({ version: '1', review: reviewContent, sessionId, branch: options.branch }, options.format, ReviewOutputSchema));
+        }
+        else if (options.format === 'plain') {
+            // Strip ANSI codes for plain output
+            const plainReview = stripAnsi(reviewContent);
+            process.stdout.write(plainReview + '\n');
         }
         else {
-            // Render to terminal in readable format (Req 12.8)
+            // Render to terminal in readable format 
             // Note: agentLoop already streamed the raw response; renderReview
             // provides a structured re-render for clarity.
             renderReview(review);
         }
-        // 10. Mark session as completed (Req 12.10)
+        // 10. Mark session as completed 
         updateSessionStatus(db, sessionId, "completed");
     }
     catch (err) {
@@ -978,6 +1042,17 @@ export async function runReview(options) {
             updateSessionStatus(db, sessionId, "cancelled");
             process.exit(130);
         }
+        // v0.2.3: structured error output 
+        if (options.format === 'json') {
+            process.stderr.write(JSON.stringify({ version: '1', error: message, exitCode: 1 }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
+        else if (options.format === 'ndjson') {
+            process.stderr.write(JSON.stringify({ version: '1', event: 'error', error: message }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
         uiError(message);
         updateSessionStatus(db, sessionId, "failed", message);
         process.exit(1);
@@ -987,33 +1062,32 @@ export async function runReview(options) {
  * Execute the explore command.
  *
  * Flow:
- * 1. Parse flags and load configuration                  (Req 13.1)
- * 2. Detect project type                                 (Req 13.1)
- * 3. Create session with mode: "plan"                    (Req 13.2)
- * 4. Scan repository structure respecting .gitignore     (Req 13.3)
- * 5. Detect frameworks and key configuration files       (Req 13.4)
- * 6. Identify entry points based on project type         (Req 13.5)
- * 7. Build system prompt from explore.md template        (Req 13.3–13.6)
- * 8. Execute agent loop to summarize structure/patterns  (Req 13.6)
- * 9. Render exploration summary to terminal              (Req 13.7)
- * 10. Save to ./.aria/explore.md if --save flag          (Req 13.8)
- * 11. Persist session to database                        (Req 13.10)
+ * 1. Parse flags and load configuration
+ * 2. Detect project type
+ * 3. Create session with mode: "plan"
+ * 4. Scan repository structure respecting .gitignore
+ * 5. Detect frameworks and key configuration files
+ * 6. Identify entry points based on project type
+ * 7. Build system prompt from explore.md template
+ * 8. Execute agent loop to summarize structure/patterns
+ * 9. Render exploration summary to terminal
+ * 10. Save to ./.aria/explore.md if --save flag
+ * 11. Persist session to database
  *
- * Requirements: 13.1, 13.2, 13.3, 13.4, 13.5, 13.6, 13.7, 13.8, 13.9, 13.10
  */
 export async function runExplore(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
-    // 1. Load configuration (Req 13.1)
+    // 1. Load configuration 
     const config = getConfig(projectRoot, {
         quiet: options.quiet,
         provider: options.provider,
         model: options.model,
     });
     // Initialize UI with config settings
-    initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet));
-    // Detect project type early to fail fast (Req 13.1)
+    initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet) || (options.format === 'json' || options.format === 'ndjson'));
+    // Detect project type early to fail fast 
     const project = detectProjectType(projectRoot);
-    // 2. Initialize database and create session (Req 13.10)
+    // 2. Initialize database and create session 
     const db = initializeDatabase();
     const sessionId = randomUUID();
     createSession(db, {
@@ -1038,7 +1112,7 @@ export async function runExplore(options) {
         updateSessionStatus(db, sessionId, "failed", String(err));
         process.exit(4);
     }
-    // 4. Build execution context with mode: "plan" (Req 13.2)
+    // 4. Build execution context with mode: "plan" 
     const ctx = {
         projectRoot,
         sessionId,
@@ -1050,10 +1124,10 @@ export async function runExplore(options) {
         maxIterations: config.agent.maxIterations,
         timeoutSeconds: config.agent.timeoutSeconds,
     };
-    // 5. Build system prompt from explore.md template (Req 13.3–13.6)
+    // 5. Build system prompt from explore.md template 
     const systemPrompt = buildSystemPrompt("explore", ctx);
     logMessage(db, sessionId, "system", systemPrompt);
-    // 6. Build user request with project context and depth hint (Req 13.9)
+    // 6. Build user request with project context and depth hint 
     const frameworkInfo = project.framework
         ? `${project.framework.name}${project.framework.version ? ` ${project.framework.version}` : ""}${project.framework.router ? ` (${project.framework.router} router)` : ""}`
         : "none";
@@ -1077,20 +1151,24 @@ export async function runExplore(options) {
     ]
         .filter((l) => l !== null)
         .join("\n");
-    // 7. Execute agent loop — streams response to stdout (Req 13.6, 13.7)
+    // 7. Execute agent loop — streams response to stdout 
     try {
         const exploreContent = await agentLoop(ctx, userRequest, READ_ONLY_TOOLS, provider, config, "explore", db, systemPrompt);
-        // 8. Save to ./.aria/explore.md if --save flag provided (Req 13.8)
+        // v0.2.3: structured output 
+        if (options.format === 'json' || options.format === 'ndjson') {
+            process.stdout.write(formatOutput({ version: '1', summary: exploreContent, sessionId }, options.format, ExploreOutputSchema));
+        }
+        // 8. Save to ./.aria/explore.md if --save flag provided 
         if (options.save) {
             const ariaDir = path.join(projectRoot, ".aria");
             const savePath = path.join(ariaDir, "explore.md");
             if (!existsSync(ariaDir)) {
                 mkdirSync(ariaDir, { recursive: true });
             }
-            writeFileSync(savePath, exploreContent, "utf-8");
+            writeFileAtomic(savePath, exploreContent);
             info(`Exploration summary saved to .aria/explore.md`);
         }
-        // 9. Mark session as completed (Req 13.10)
+        // 9. Mark session as completed 
         updateSessionStatus(db, sessionId, "completed");
     }
     catch (err) {
@@ -1101,6 +1179,17 @@ export async function runExplore(options) {
             updateSessionStatus(db, sessionId, "cancelled");
             process.exit(130);
         }
+        // v0.2.3: structured error output 
+        if (options.format === 'json') {
+            process.stderr.write(JSON.stringify({ version: '1', error: message, exitCode: 1 }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
+        else if (options.format === 'ndjson') {
+            process.stderr.write(JSON.stringify({ version: '1', event: 'error', error: message }) + '\n');
+            updateSessionStatus(db, sessionId, 'failed', message);
+            process.exit(1);
+        }
         uiError(message);
         updateSessionStatus(db, sessionId, "failed", message);
         process.exit(1);
@@ -1110,7 +1199,6 @@ export async function runExplore(options) {
  * Format a SQLite timestamp string into a human-readable relative time.
  * e.g. "2 hours ago", "3 days ago", "just now"
  *
- * Requirements: 14.7
  */
 function formatTimestamp(timestamp) {
     // SQLite CURRENT_TIMESTAMP returns "YYYY-MM-DD HH:MM:SS" (space, no T, no Z).
@@ -1162,8 +1250,20 @@ function colorizeStatus(status) {
  * Render a tool execution tree for a session.
  * Shows tool calls in chronological order with input/output summaries.
  *
- * Requirements: 14.6
  */
+// Tool type icon sets 
+const READ_TOOLS = new Set(['read_file', 'read_package_json', 'read_prisma_schema']);
+const SEARCH_TOOLS = new Set(['search_code', 'list_directory']);
+const MUTATION_TOOLS = new Set(['propose_diff', 'apply_diff', 'apply_schema_change']);
+function toolIcon(toolName) {
+    if (READ_TOOLS.has(toolName))
+        return '[R]';
+    if (SEARCH_TOOLS.has(toolName))
+        return '[S]';
+    if (MUTATION_TOOLS.has(toolName))
+        return '[W]';
+    return '[.]';
+}
 function renderToolTree(db, sessionId) {
     const executions = db
         .prepare(`SELECT tool_name, input, output, error, created_at
@@ -1181,7 +1281,8 @@ function renderToolTree(db, sessionId) {
         const prefix = isLast ? "└─" : "├─";
         const childPrefix = isLast ? "   " : "│  ";
         const statusIcon = exec.error ? red("✗") : green("✓");
-        info(`  ${prefix} ${statusIcon} ${bold(exec.tool_name)} ${dim(formatTimestamp(exec.created_at))}`);
+        const typeIcon = toolIcon(exec.tool_name);
+        info(`  ${prefix} ${typeIcon} ${statusIcon} ${bold(exec.tool_name)} ${dim(formatTimestamp(exec.created_at))}`);
         // Show a brief summary of the input
         try {
             const inputObj = JSON.parse(exec.input);
@@ -1214,23 +1315,88 @@ function renderToolTree(db, sessionId) {
  * Execute the history command.
  *
  * Flow:
- * 1. If no --session flag: list recent sessions in a table  (Req 14.2, 14.3, 14.4)
- * 2. If --session flag: display full session log            (Req 14.5)
- * 3. If --tree flag: render tool execution tree             (Req 14.6)
- * 4. Format timestamps in human-readable format             (Req 14.7)
- * 5. Support pagination for large result sets               (Req 14.8)
+ * 1. If no --session flag: list recent sessions in a table
+ * 2. If --session flag: display full session log
+ * 3. If --tree flag: render tool execution tree
+ * 4. Format timestamps in human-readable format
+ * 5. Support pagination for large result sets
  *
- * Requirements: 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 14.7, 14.8
  */
 export async function runHistory(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
     // Load configuration and initialize UI
     const config = getConfig(projectRoot, { quiet: options.quiet });
-    initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet));
+    initUI(config.ui.color, config.ui.quiet || Boolean(options.quiet) || (options.format === 'json' || options.format === 'ndjson'));
     // Initialize database
     const db = initializeDatabase();
     // ---------------------------------------------------------------------------
-    // Case 1: --session flag — show full session log (Req 14.5)
+    // v0.2.3: Structured output for json/ndjson/plain — applies to session listing
+    // ---------------------------------------------------------------------------
+    const isStructuredFormat = options.format === 'json' || options.format === 'ndjson';
+    const isPlainFormat = options.format === 'plain';
+    // ---------------------------------------------------------------------------
+    // v0.2.3: Search path — full-text search across session content 
+    // ---------------------------------------------------------------------------
+    if (options.search) {
+        const results = searchSessions(db, options.search, { limit: options.limit });
+        if (results.length === 0) {
+            info("No sessions found matching query.");
+            return;
+        }
+        const rows = results.map(({ session, matchedInMessages }) => [
+            dim(session.id.slice(0, 8)),
+            cyan(session.command),
+            colorizeStatus(session.status),
+            formatTimestamp(session.createdAt),
+            matchedInMessages ? dim("message") : dim("metadata"),
+        ]);
+        const table = renderTable({ head: ["ID", "Command", "Status", "Started", "Match"], colWidths: [12, 12, 12, 20, 12] }, rows);
+        info(table);
+        return;
+    }
+    // ---------------------------------------------------------------------------
+    // v0.2.3: Filter path — filter by command, since, status 
+    // ---------------------------------------------------------------------------
+    if (options.command || options.since || options.status) {
+        const sessions = filterSessions(db, {
+            command: options.command,
+            since: options.since,
+            status: options.status,
+            limit: options.limit,
+        });
+        if (sessions.length === 0) {
+            info("No sessions found.");
+            return;
+        }
+        const rows = sessions.map((s) => [
+            dim(s.id.slice(0, 8)),
+            cyan(s.command),
+            formatTimestamp(s.createdAt),
+            colorizeStatus(s.status),
+        ]);
+        const table = renderTable({ head: ["ID", "Command", "When", "Status"], colWidths: [12, 12, 20, 12] }, rows);
+        info(table);
+        return;
+    }
+    // ---------------------------------------------------------------------------
+    // v0.2.3: Export path — export session transcript to markdown 
+    // ---------------------------------------------------------------------------
+    if (options.export && options.session) {
+        // Validate export path is within project root to prevent path traversal
+        try {
+            const { validatePath } = await import('./safety.js');
+            validatePath(path.resolve(options.export), projectRoot);
+        }
+        catch {
+            uiError(`Export path must be within the project root: ${options.export}`);
+            process.exit(2);
+        }
+        exportSessionMarkdown(db, options.session, options.export);
+        info(`Session exported to ${path.resolve(options.export)}`);
+        return;
+    }
+    // ---------------------------------------------------------------------------
+    // Case 1: --session flag — show full session log 
     // ---------------------------------------------------------------------------
     if (options.session) {
         const session = getSession(db, options.session);
@@ -1288,7 +1454,7 @@ export async function runHistory(options) {
         if (toolCount > 0) {
             info(bold(`Tool Executions (${toolCount}):`));
             if (options.tree) {
-                // Render as tree (Req 14.6)
+                // Render as tree 
                 renderToolTree(db, options.session);
             }
             else {
@@ -1309,30 +1475,55 @@ export async function runHistory(options) {
         return;
     }
     // ---------------------------------------------------------------------------
-    // Case 2: No --session flag — list recent sessions (Req 14.2, 14.3, 14.4)
+    // Case 2: No --session flag — list recent sessions 
     // ---------------------------------------------------------------------------
     const PAGE_SIZE = 20;
     const limit = options.limit ?? PAGE_SIZE;
-    // Fetch sessions with pagination support (Req 14.8)
+    // Fetch sessions with pagination support
     const sessions = listSessions(db, { limit });
     if (sessions.length === 0) {
-        info("No sessions found. Run a command to create your first session.");
+        if (!isStructuredFormat) {
+            info("No sessions found. Run a command to create your first session.");
+        }
+        if (isStructuredFormat) {
+            process.stdout.write(formatOutput({ version: '1', sessions: [], total: 0 }, options.format, HistoryOutputSchema));
+        }
+        return;
+    }
+    // v0.2.3: structured output 
+    if (isStructuredFormat) {
+        const outputSessions = sessions.map((s) => ({
+            id: s.id,
+            command: s.command,
+            status: s.status,
+            createdAt: s.createdAt,
+            completedAt: s.completedAt ?? null,
+        }));
+        process.stdout.write(formatOutput({ version: '1', sessions: outputSessions, total: sessions.length }, options.format, HistoryOutputSchema));
+        return;
+    }
+    // v0.2.3: plain format — tab-separated, no cli-table3 borders
+    if (isPlainFormat) {
+        process.stdout.write('ID\tCommand\tWhen\tStatus\n');
+        for (const s of sessions) {
+            process.stdout.write(`${s.id.slice(0, 8)}\t${s.command}\t${s.createdAt}\t${s.status}\n`);
+        }
         return;
     }
-    // Build table rows (Req 14.3)
+    // Build table rows 
     const rows = sessions.map((s) => [
         dim(s.id.slice(0, 8)), // abbreviated ID
         cyan(s.command),
-        formatTimestamp(s.createdAt), // human-readable timestamp (Req 14.7)
+        formatTimestamp(s.createdAt), // human-readable timestamp 
         colorizeStatus(s.status),
     ]);
-    // Render table with cli-table3 (Req 14.3, 20.4)
+    // Render table with cli-table3 
     const table = renderTable({
         head: ["ID", "Command", "When", "Status"],
         colWidths: [12, 12, 20, 12],
     }, rows);
     info(table);
-    // Show pagination hint if there may be more results (Req 14.8)
+    // Show pagination hint if there may be more results 
     if (sessions.length === limit && !options.limit) {
         info(dim(`\nShowing ${limit} most recent sessions. Use --limit <n> to see more.`));
     }
@@ -1423,7 +1614,6 @@ function parseConfigValue(value) {
 }
 /**
  * Display the effective configuration with precedence sources.
- * Requirements: 15.2
  */
 function displayEffectiveConfig(projectRoot, config) {
     const userConfigPath = path.join(os.homedir(), ".aria", "config.toml");
@@ -1464,13 +1654,12 @@ function displayEffectiveConfig(projectRoot, config) {
  * Execute the config command.
  *
  * Subcommands:
- * - (none): Display effective configuration with precedence sources  (Req 15.2)
- * - get <key>: Display value for specified key                       (Req 15.3)
- * - set <key> <value>: Write key-value to ~/.aria/config.toml        (Req 15.4–15.6, 15.10)
- * - path: Display configuration file resolution paths               (Req 15.7)
- * - init: Create ./.aria.toml with default values                   (Req 15.8, 15.9)
+ * - (none): Display effective configuration with precedence sources
+ * - get <key>: Display value for specified key
+ * - set <key> <value>: Write key-value to ~/.aria/config.toml
+ * - path: Display configuration file resolution paths
+ * - init: Create ./.aria.toml with default values
  *
- * Requirements: 15.1–15.10
  */
 export async function runConfig(options) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
@@ -1480,14 +1669,14 @@ export async function runConfig(options) {
     const userConfigPath = path.join(os.homedir(), ".aria", "config.toml");
     const projectConfigPath = path.join(projectRoot, ".aria.toml");
     // ---------------------------------------------------------------------------
-    // No subcommand: display effective configuration (Req 15.2)
+    // No subcommand: display effective configuration 
     // ---------------------------------------------------------------------------
     if (!options.subcommand) {
         displayEffectiveConfig(projectRoot, config);
         return;
     }
     // ---------------------------------------------------------------------------
-    // config path: display config file resolution paths (Req 15.7)
+    // config path: display config file resolution paths 
     // ---------------------------------------------------------------------------
     if (options.subcommand === "path") {
         info(bold("Configuration file paths:"));
@@ -1500,7 +1689,7 @@ export async function runConfig(options) {
         return;
     }
     // ---------------------------------------------------------------------------
-    // config get <key>: display value for key (Req 15.3)
+    // config get <key>: display value for key 
     // ---------------------------------------------------------------------------
     if (options.subcommand === "get") {
         const key = options.key;
@@ -1513,14 +1702,14 @@ export async function runConfig(options) {
         return;
     }
     // ---------------------------------------------------------------------------
-    // config set <key> <value>: write to user config (Req 15.4–15.6, 15.10)
+    // config set <key> <value>: write to user config
     // ---------------------------------------------------------------------------
     if (options.subcommand === "set") {
         const key = options.key;
         const rawValue = options.value;
         // Parse the value to the appropriate type
         const parsedValue = parseConfigValue(rawValue);
-        // Validate by applying to current config and re-validating (Req 15.10)
+        // Validate by applying to current config and re-validating 
         const currentMerged = loadConfig(projectRoot);
         const updatedMerged = setNestedValue(currentMerged, key, parsedValue);
         let validatedConfig;
@@ -1536,16 +1725,16 @@ export async function runConfig(options) {
             ? readFileSync(userConfigPath, "utf-8")
             : "";
         const newContent = serializeConfigToToml(validatedConfig);
-        // Preview the diff (Req 15.5, 15.6)
+        // Preview the diff 
         const diffOutput = generateAndRenderDiff(userConfigPath, oldContent, newContent);
         info(bold("Preview:"));
         info(diffOutput);
-        // If --dry-run, exit without writing (Req 15.6)
+        // If --dry-run, exit without writing
         if (options.dryRun) {
             info(yellow("Dry-run mode — no changes written."));
             return;
         }
-        // If not --yes, prompt for confirmation (Req 15.5)
+        // If not --yes, prompt for confirmation 
         if (!options.yes) {
             let confirmed;
             try {
@@ -1563,7 +1752,7 @@ export async function runConfig(options) {
                 process.exit(130);
             }
         }
-        // Write to ~/.aria/config.toml (Req 15.4)
+        // Write to ~/.aria/config.toml 
         const ariaDir = path.join(os.homedir(), ".aria");
         if (!existsSync(ariaDir)) {
             mkdirSync(ariaDir, { recursive: true });
@@ -1573,7 +1762,7 @@ export async function runConfig(options) {
         return;
     }
     // ---------------------------------------------------------------------------
-    // config init: create ./.aria.toml with defaults (Req 15.8, 15.9)
+    // config init: create ./.aria.toml with defaults 
     // ---------------------------------------------------------------------------
     if (options.subcommand === "init") {
         // Generate default config content
@@ -1586,12 +1775,12 @@ export async function runConfig(options) {
         const diffOutput = generateAndRenderDiff(projectConfigPath, oldContent, defaultContent);
         info(bold("Preview (.aria.toml):"));
         info(diffOutput);
-        // If --dry-run, exit without writing (Req 17.4)
+        // If --dry-run, exit without writing 
         if (options.dryRun) {
             info(yellow("Dry-run mode — no file created."));
             return;
         }
-        // If not --yes, prompt for confirmation (Req 15.9)
+        // If not --yes, prompt for confirmation 
         if (!options.yes) {
             let confirmed;
             try {
@@ -1609,7 +1798,7 @@ export async function runConfig(options) {
                 process.exit(130);
             }
         }
-        // Write ./.aria.toml (Req 15.8)
+        // Write ./.aria.toml
         writeFileSync(projectConfigPath, defaultContent, "utf-8");
         info(green(`✓ Created ${projectConfigPath}`));
         return;
@@ -1621,7 +1810,6 @@ export async function runConfig(options) {
  * Runs a series of environment diagnostic checks and reports results.
  * Exits with code 1 if any critical check fails.
  *
- * Requirements: 16.1–16.13
  */
 export async function runDoctor(options = {}) {
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
@@ -1636,7 +1824,7 @@ export async function runDoctor(options = {}) {
     }
     const checks = [];
     // -------------------------------------------------------------------------
-    // 1. Node.js version >= 20 (Req 16.2) — CRITICAL
+    // 1. Node.js version >= 20 
     // -------------------------------------------------------------------------
     {
         const nodeVersion = process.version; // e.g. "v20.11.0"
@@ -1653,7 +1841,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 2. git availability (Req 16.3) — WARN only
+    // 2. git availability — WARN only
     // -------------------------------------------------------------------------
     {
         try {
@@ -1665,7 +1853,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 3. ripgrep (rg) availability (Req 16.4) — WARN only
+    // 3. ripgrep (rg) availability — WARN only
     // -------------------------------------------------------------------------
     {
         try {
@@ -1677,7 +1865,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 4. Config file syntax and schema validation (Req 16.5) — CRITICAL
+    // 4. Config file syntax and schema validation — CRITICAL
     // -------------------------------------------------------------------------
     {
         const userConfigPath = path.join(os.homedir(), ".aria", "config.toml");
@@ -1704,7 +1892,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 5. History DB accessibility and schema version (Req 16.6) — CRITICAL
+    // 5. History DB accessibility and schema version — CRITICAL
     // -------------------------------------------------------------------------
     {
         try {
@@ -1722,7 +1910,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 6. Provider readiness — API key presence (Req 16.7) — CRITICAL for default
+    // 6. Provider readiness — API key presence — CRITICAL for default
     // v0.2.2: report all configured providers, fail only if default key is missing
     // -------------------------------------------------------------------------
     {
@@ -1759,7 +1947,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 7. Project type detection (Req 16.8)
+    // 7. Project type detection 
     // -------------------------------------------------------------------------
     {
         try {
@@ -1778,7 +1966,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 8. Prisma schema existence and model count (Req 16.9 + v0.2.0)
+    // 8. Prisma schema existence and model count 
     // -------------------------------------------------------------------------
     {
         try {
@@ -1818,7 +2006,7 @@ export async function runDoctor(options = {}) {
         }
     }
     // -------------------------------------------------------------------------
-    // 9. Ollama reachability if Ollama provider selected (Req 16.10) — WARN
+    // 9. Ollama reachability if Ollama provider selected — WARN
     // -------------------------------------------------------------------------
     {
         const provider = config?.provider.default ?? "anthropic";
@@ -1841,10 +2029,22 @@ export async function runDoctor(options = {}) {
     // -------------------------------------------------------------------------
     const criticalNames = new Set(["nodejs", "config", "history_db", "provider"]);
     const hasCriticalFailure = checks.some((c) => c.status === "fail" && criticalNames.has(c.name));
-    if (options.format === "json") {
-        // JSON output (Req 16.12)
-        const allPassed = !checks.some((c) => c.status === "fail");
-        process.stdout.write(JSON.stringify({ checks, allPassed }, null, 2) + "\n");
+    const allPassed = !checks.some((c) => c.status === "fail");
+    if (options.format === 'json' || options.format === 'ndjson') {
+        // v0.2.3: structured output via formatOutput
+        const doctorChecks = checks.map((c) => ({
+            name: c.name,
+            passed: c.status !== 'fail',
+            message: c.message,
+        }));
+        process.stdout.write(formatOutput({ version: '1', checks: doctorChecks, allPassed }, options.format, DoctorOutputSchema));
+    }
+    else if (options.format === 'plain') {
+        // Plain text — no ANSI codes, tab-separated
+        for (const check of checks) {
+            const icon = check.status === 'pass' ? 'OK' : check.status === 'warn' ? 'WARN' : 'FAIL';
+            process.stdout.write(`${icon}\t${check.name}\t${check.message}\n`);
+        }
     }
     else {
         // Text output (Req 16.11)
@@ -1870,7 +2070,7 @@ export async function runDoctor(options = {}) {
             info(green("All critical checks passed."));
         }
     }
-    // Exit with code 1 if any critical check fails (Req 16.13)
+    // Exit with code 1 if any critical check fails
     if (hasCriticalFailure) {
         process.exit(1);
     }