prjct-cli 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -1,10 +1,39 @@
 # Changelog
 
-## [0.48.0] - 2026-01-30
+## [0.50.0] - 2026-01-30
 
 ### Features
 
-- Read-before-write enforcement for templates - PRJ-108 (#74)
+- Unified output system with new methods - PRJ-130 (#76)
+
+
+## [0.50.0] - 2026-01-30
+
+### Added
+
+- **Unified output system with new methods** (PRJ-130)
+  - Added `ICONS` constant for centralized icon definitions
+  - New methods: `info()`, `debug()`, `success()`, `list()`, `table()`, `box()`
+  - `debug()` only shows output when `DEBUG=1`
+  - Refactored existing methods to use `ICONS` for consistency
+
+
+## [0.49.0] - 2026-01-30
+
+### Features
+
+- Error messages with context and recovery hints - PRJ-131 (#75)
+
+
+## [0.49.1] - 2026-01-30
+
+### Improved
+
+- **Error messages with context and recovery hints** (PRJ-131)
+  - Created error catalog with 15+ error types
+  - Added `out.failWithHint()` for rich error output
+  - Errors now show file path and recovery hints
+  - Example: `✗ Project ID not found` → `💡 Run 'prjct init'`
 
 
 ## [0.49.0] - 2026-01-30

package/core/commands/analytics.ts

@@ -39,7 +39,7 @@ export class AnalyticsCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

package/core/commands/cleanup.ts

@@ -79,7 +79,7 @@ export async function cleanup(
 
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 

package/core/commands/planning.ts

@@ -254,7 +254,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -325,7 +325,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -485,7 +485,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -562,7 +562,7 @@ Generated: ${new Date().toLocaleString()}
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

package/core/commands/shipping.ts

@@ -60,7 +60,7 @@ export class ShippingCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

package/core/commands/snapshots.ts

@@ -28,7 +28,7 @@ export async function recover(projectPath: string = process.cwd()): Promise<Comm
   try {
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 
@@ -85,7 +85,7 @@ export async function undo(projectPath: string = process.cwd()): Promise<Command
 
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 
@@ -147,7 +147,7 @@ export async function undo(projectPath: string = process.cwd()): Promise<Command
       out.done('changes stashed (use /p:redo to restore)')
       return { success: true, snapshotId: stashMessage }
     } catch (gitError) {
-      out.fail('git operation failed')
+      out.failWithHint('GIT_OPERATION_FAILED')
       return { success: false, error: (gitError as Error).message }
     }
   } catch (error) {
@@ -165,7 +165,7 @@ export async function redo(projectPath: string = process.cwd()): Promise<Command
 
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 
@@ -231,7 +231,7 @@ export async function redo(projectPath: string = process.cwd()): Promise<Command
       out.done('changes restored')
       return { success: true }
     } catch (gitError) {
-      out.fail('git operation failed')
+      out.failWithHint('GIT_OPERATION_FAILED')
       return { success: false, error: (gitError as Error).message }
     }
   } catch (error) {
@@ -247,7 +247,7 @@ export async function history(projectPath: string = process.cwd()): Promise<Comm
   try {
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 

package/core/commands/workflow.ts

@@ -43,7 +43,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -163,7 +163,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -246,7 +246,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -278,7 +278,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -323,7 +323,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -374,7 +374,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

package/core/utils/error-messages.ts

@@ -0,0 +1,161 @@
+/**
+ * Error Messages Catalog
+ *
+ * Centralized error messages with context and recovery hints.
+ * Provides consistent, helpful error output across the CLI.
+ *
+ * @see PRJ-131
+ * @module utils/error-messages
+ */
+
+export interface ErrorWithHint {
+  message: string
+  hint?: string
+  file?: string
+  docs?: string
+  code?: string
+}
+
+/**
+ * Common error messages with recovery hints
+ */
+export const ERRORS = {
+  // Project errors
+  NO_PROJECT: {
+    message: 'No prjct project found in this directory',
+    hint: "Run 'prjct init' to set up a new project",
+    file: '.prjct/prjct.config.json',
+  },
+
+  NO_PROJECT_ID: {
+    message: 'Project ID not found',
+    hint: "Run 'prjct init' or check .prjct/prjct.config.json",
+    file: '.prjct/prjct.config.json',
+  },
+
+  CONFIG_NOT_FOUND: {
+    message: 'Configuration file not found',
+    hint: "Run 'prjct init' to create project configuration",
+    file: '.prjct/prjct.config.json',
+  },
+
+  CONFIG_INVALID: {
+    message: 'Invalid configuration file',
+    hint: 'Check JSON syntax or delete .prjct/ and run init again',
+    file: '.prjct/prjct.config.json',
+  },
+
+  // Git errors
+  GIT_NOT_FOUND: {
+    message: 'Git repository not detected',
+    hint: "Run 'git init' first, then 'prjct init'",
+  },
+
+  GIT_NO_COMMITS: {
+    message: 'No commits in repository',
+    hint: 'Make an initial commit before using prjct',
+  },
+
+  GIT_DIRTY: {
+    message: 'Working directory has uncommitted changes',
+    hint: "Commit or stash changes, or use '--force' to override",
+  },
+
+  GIT_ON_MAIN: {
+    message: 'Cannot ship from main/master branch',
+    hint: 'Create a feature branch first: git checkout -b feature/your-feature',
+  },
+
+  GIT_OPERATION_FAILED: {
+    message: 'Git operation failed',
+    hint: 'Check git status and resolve any conflicts',
+  },
+
+  // Auth errors
+  GH_NOT_AUTHENTICATED: {
+    message: 'GitHub CLI not authenticated',
+    hint: "Run 'gh auth login' to authenticate",
+    docs: 'https://cli.github.com/manual/gh_auth_login',
+  },
+
+  LINEAR_NOT_CONFIGURED: {
+    message: 'Linear integration not configured',
+    hint: "Run 'p. linear setup' to configure Linear",
+  },
+
+  LINEAR_API_ERROR: {
+    message: 'Linear API error',
+    hint: 'Check your API key or network connection',
+  },
+
+  // Task errors
+  NO_ACTIVE_TASK: {
+    message: 'No active task',
+    hint: 'Start a task with \'p. task "description"\'',
+  },
+
+  TASK_ALREADY_ACTIVE: {
+    message: 'A task is already in progress',
+    hint: "Complete it with 'p. done' or pause with 'p. pause'",
+  },
+
+  // Sync errors
+  SYNC_FAILED: {
+    message: 'Project sync failed',
+    hint: 'Check file permissions and try again',
+  },
+
+  // Ship errors
+  NOTHING_TO_SHIP: {
+    message: 'Nothing to ship',
+    hint: 'Make some changes first, then run ship',
+  },
+
+  PR_CREATE_FAILED: {
+    message: 'Failed to create pull request',
+    hint: 'Check GitHub auth and remote configuration',
+  },
+
+  // Provider errors
+  NO_AI_PROVIDER: {
+    message: 'No AI provider detected',
+    hint: "Install Claude Code or Gemini CLI, then run 'prjct start'",
+    docs: 'https://prjct.app/docs',
+  },
+
+  PROVIDER_NOT_CONFIGURED: {
+    message: 'AI provider not configured for prjct',
+    hint: "Run 'prjct start' to configure your provider",
+  },
+
+  // Generic
+  UNKNOWN: {
+    message: 'An unexpected error occurred',
+    hint: 'Check the error details and try again',
+  },
+} as const
+
+export type ErrorCode = keyof typeof ERRORS
+
+/**
+ * Get error with optional overrides
+ */
+export function getError(code: ErrorCode, overrides?: Partial<ErrorWithHint>): ErrorWithHint {
+  const base = ERRORS[code]
+  return { ...base, ...overrides }
+}
+
+/**
+ * Create a custom error with hint
+ */
+export function createError(
+  message: string,
+  hint?: string,
+  options?: { file?: string; docs?: string }
+): ErrorWithHint {
+  return {
+    message,
+    hint,
+    ...options,
+  }
+}

package/core/utils/output.ts

@@ -1,17 +1,37 @@
 /**
- * Minimal Output System for prjct-cli
+ * Unified Output System for prjct-cli
  * Spinner while working → Single line result
  * With prjct branding
  *
  * Supports --quiet mode for CI/CD and scripting
+ *
+ * @see PRJ-130
  */
 
 import chalk from 'chalk'
 import branding from './branding'
+import type { ErrorCode, ErrorWithHint } from './error-messages'
+import { getError } from './error-messages'
 
 const _FRAMES = branding.spinner.frames
 const SPEED = branding.spinner.speed
 
+/**
+ * Centralized icons for consistent output
+ */
+export const ICONS = {
+  success: chalk.green('✓'),
+  fail: chalk.red('✗'),
+  warn: chalk.yellow('⚠'),
+  info: chalk.blue('ℹ'),
+  debug: chalk.dim('🔧'),
+  bullet: chalk.dim('•'),
+  arrow: chalk.dim('→'),
+  check: chalk.green('✓'),
+  cross: chalk.red('✗'),
+  spinner: chalk.cyan('◐'),
+} as const
+
 let interval: ReturnType<typeof setInterval> | null = null
 let frame = 0
 
@@ -53,7 +73,14 @@ interface Output {
   spin(msg: string): Output
   done(msg: string, metrics?: OutputMetrics): Output
   fail(msg: string): Output
+  failWithHint(error: ErrorWithHint | ErrorCode): Output
   warn(msg: string): Output
+  info(msg: string): Output
+  debug(msg: string): Output
+  success(msg: string, metrics?: OutputMetrics): Output
+  list(items: string[], options?: { bullet?: string; indent?: number }): Output
+  table(rows: Array<Record<string, string | number>>, options?: { header?: boolean }): Output
+  box(title: string, content: string): Output
   stop(): Output
   step(current: number, total: number, msg: string): Output
   progress(current: number, total: number, msg?: string): Output
@@ -96,7 +123,7 @@ const out: Output = {
           suffix = chalk.dim(` [${parts.join(' | ')}]`)
         }
       }
-      console.log(`${chalk.green('✓')} ${truncate(msg, 50)}${suffix}`)
+      console.log(`${ICONS.success} ${truncate(msg, 50)}${suffix}`)
     }
     return this
   },
@@ -104,13 +131,116 @@ const out: Output = {
   // Errors go to stderr even in quiet mode
   fail(msg: string) {
     this.stop()
-    console.error(`${chalk.red('✗')} ${truncate(msg, 65)}`)
+    console.error(`${ICONS.fail} ${truncate(msg, 65)}`)
+    return this
+  },
+
+  // Rich error with context and recovery hint
+  failWithHint(error: ErrorWithHint | ErrorCode) {
+    this.stop()
+    const err = typeof error === 'string' ? getError(error) : error
+    console.error()
+    console.error(`${ICONS.fail} ${err.message}`)
+    if (err.file) {
+      console.error(chalk.dim(`  File: ${err.file}`))
+    }
+    if (err.hint) {
+      console.error(chalk.yellow(`  💡 ${err.hint}`))
+    }
+    if (err.docs) {
+      console.error(chalk.dim(`  Docs: ${err.docs}`))
+    }
+    console.error()
     return this
   },
 
   warn(msg: string) {
     this.stop()
-    if (!quietMode) console.log(`${chalk.yellow('⚠')} ${truncate(msg, 65)}`)
+    if (!quietMode) console.log(`${ICONS.warn} ${truncate(msg, 65)}`)
+    return this
+  },
+
+  // Informational message
+  info(msg: string) {
+    this.stop()
+    if (!quietMode) console.log(`${ICONS.info} ${msg}`)
+    return this
+  },
+
+  // Debug message (only if DEBUG=1 or DEBUG=true)
+  debug(msg: string) {
+    this.stop()
+    const debugEnabled = process.env.DEBUG === '1' || process.env.DEBUG === 'true'
+    if (!quietMode && debugEnabled) {
+      console.log(`${ICONS.debug} ${chalk.dim(msg)}`)
+    }
+    return this
+  },
+
+  // Alias for done - explicit success indicator
+  success(msg: string, metrics?: OutputMetrics) {
+    return this.done(msg, metrics)
+  },
+
+  // Bulleted list
+  list(items: string[], options: { bullet?: string; indent?: number } = {}) {
+    this.stop()
+    if (quietMode) return this
+    const bullet = options.bullet || ICONS.bullet
+    const indent = ' '.repeat(options.indent || 0)
+    for (const item of items) {
+      console.log(`${indent}${bullet} ${item}`)
+    }
+    return this
+  },
+
+  // Simple table output
+  table(rows: Array<Record<string, string | number>>, options: { header?: boolean } = {}) {
+    this.stop()
+    if (quietMode || rows.length === 0) return this
+
+    const keys = Object.keys(rows[0])
+    const colWidths: Record<string, number> = {}
+
+    // Calculate column widths
+    for (const key of keys) {
+      colWidths[key] = key.length
+      for (const row of rows) {
+        const val = String(row[key] ?? '')
+        if (val.length > colWidths[key]) colWidths[key] = val.length
+      }
+    }
+
+    // Print header if requested
+    if (options.header !== false) {
+      const headerLine = keys.map((k) => k.padEnd(colWidths[k])).join('  ')
+      console.log(chalk.dim(headerLine))
+      console.log(chalk.dim('─'.repeat(headerLine.length)))
+    }
+
+    // Print rows
+    for (const row of rows) {
+      const line = keys.map((k) => String(row[k] ?? '').padEnd(colWidths[k])).join('  ')
+      console.log(line)
+    }
+    return this
+  },
+
+  // Boxed content
+  box(title: string, content: string) {
+    this.stop()
+    if (quietMode) return this
+    const lines = content.split('\n')
+    const maxLen = Math.max(title.length, ...lines.map((l) => l.length))
+    const border = '─'.repeat(maxLen + 2)
+
+    console.log(chalk.dim(`┌${border}┐`))
+    console.log(chalk.dim('│') + ` ${chalk.bold(title.padEnd(maxLen))} ` + chalk.dim('│'))
+    console.log(chalk.dim(`├${border}┤`))
+    for (const line of lines) {
+      console.log(chalk.dim('│') + ` ${line.padEnd(maxLen)} ` + chalk.dim('│'))
+    }
+    console.log(chalk.dim(`└${border}┘`))
     return this
   },
 
@@ -151,4 +281,6 @@ const out: Output = {
 }
 
 export type { OutputMetrics }
+export type { ErrorCode, ErrorWithHint } from './error-messages'
+export { createError, ERRORS, getError } from './error-messages'
 export default out

package/dist/bin/prjct.mjs

@@ -1944,10 +1944,131 @@ var init_branding = __esm({
   }
 });
 
+// core/utils/error-messages.ts
+function getError(code, overrides) {
+  const base = ERRORS[code];
+  return { ...base, ...overrides };
+}
+function createError(message, hint, options) {
+  return {
+    message,
+    hint,
+    ...options
+  };
+}
+var ERRORS;
+var init_error_messages = __esm({
+  "core/utils/error-messages.ts"() {
+    "use strict";
+    ERRORS = {
+      // Project errors
+      NO_PROJECT: {
+        message: "No prjct project found in this directory",
+        hint: "Run 'prjct init' to set up a new project",
+        file: ".prjct/prjct.config.json"
+      },
+      NO_PROJECT_ID: {
+        message: "Project ID not found",
+        hint: "Run 'prjct init' or check .prjct/prjct.config.json",
+        file: ".prjct/prjct.config.json"
+      },
+      CONFIG_NOT_FOUND: {
+        message: "Configuration file not found",
+        hint: "Run 'prjct init' to create project configuration",
+        file: ".prjct/prjct.config.json"
+      },
+      CONFIG_INVALID: {
+        message: "Invalid configuration file",
+        hint: "Check JSON syntax or delete .prjct/ and run init again",
+        file: ".prjct/prjct.config.json"
+      },
+      // Git errors
+      GIT_NOT_FOUND: {
+        message: "Git repository not detected",
+        hint: "Run 'git init' first, then 'prjct init'"
+      },
+      GIT_NO_COMMITS: {
+        message: "No commits in repository",
+        hint: "Make an initial commit before using prjct"
+      },
+      GIT_DIRTY: {
+        message: "Working directory has uncommitted changes",
+        hint: "Commit or stash changes, or use '--force' to override"
+      },
+      GIT_ON_MAIN: {
+        message: "Cannot ship from main/master branch",
+        hint: "Create a feature branch first: git checkout -b feature/your-feature"
+      },
+      GIT_OPERATION_FAILED: {
+        message: "Git operation failed",
+        hint: "Check git status and resolve any conflicts"
+      },
+      // Auth errors
+      GH_NOT_AUTHENTICATED: {
+        message: "GitHub CLI not authenticated",
+        hint: "Run 'gh auth login' to authenticate",
+        docs: "https://cli.github.com/manual/gh_auth_login"
+      },
+      LINEAR_NOT_CONFIGURED: {
+        message: "Linear integration not configured",
+        hint: "Run 'p. linear setup' to configure Linear"
+      },
+      LINEAR_API_ERROR: {
+        message: "Linear API error",
+        hint: "Check your API key or network connection"
+      },
+      // Task errors
+      NO_ACTIVE_TASK: {
+        message: "No active task",
+        hint: `Start a task with 'p. task "description"'`
+      },
+      TASK_ALREADY_ACTIVE: {
+        message: "A task is already in progress",
+        hint: "Complete it with 'p. done' or pause with 'p. pause'"
+      },
+      // Sync errors
+      SYNC_FAILED: {
+        message: "Project sync failed",
+        hint: "Check file permissions and try again"
+      },
+      // Ship errors
+      NOTHING_TO_SHIP: {
+        message: "Nothing to ship",
+        hint: "Make some changes first, then run ship"
+      },
+      PR_CREATE_FAILED: {
+        message: "Failed to create pull request",
+        hint: "Check GitHub auth and remote configuration"
+      },
+      // Provider errors
+      NO_AI_PROVIDER: {
+        message: "No AI provider detected",
+        hint: "Install Claude Code or Gemini CLI, then run 'prjct start'",
+        docs: "https://prjct.app/docs"
+      },
+      PROVIDER_NOT_CONFIGURED: {
+        message: "AI provider not configured for prjct",
+        hint: "Run 'prjct start' to configure your provider"
+      },
+      // Generic
+      UNKNOWN: {
+        message: "An unexpected error occurred",
+        hint: "Check the error details and try again"
+      }
+    };
+    __name(getError, "getError");
+    __name(createError, "createError");
+  }
+});
+
 // core/utils/output.ts
 var output_exports = {};
 __export(output_exports, {
+  ERRORS: () => ERRORS,
+  ICONS: () => ICONS,
+  createError: () => createError,
   default: () => output_default,
+  getError: () => getError,
   isQuietMode: () => isQuietMode,
   setQuietMode: () => setQuietMode
 });
@@ -1958,13 +2079,27 @@ function setQuietMode(enabled) {
 function isQuietMode() {
   return quietMode;
 }
-var _FRAMES, SPEED, interval, frame, quietMode, truncate, clear, out, output_default;
+var _FRAMES, SPEED, ICONS, interval, frame, quietMode, truncate, clear, out, output_default;
 var init_output = __esm({
   "core/utils/output.ts"() {
     "use strict";
     init_branding();
+    init_error_messages();
+    init_error_messages();
     _FRAMES = branding_default.spinner.frames;
     SPEED = branding_default.spinner.speed;
+    ICONS = {
+      success: chalk2.green("\u2713"),
+      fail: chalk2.red("\u2717"),
+      warn: chalk2.yellow("\u26A0"),
+      info: chalk2.blue("\u2139"),
+      debug: chalk2.dim("\u{1F527}"),
+      bullet: chalk2.dim("\u2022"),
+      arrow: chalk2.dim("\u2192"),
+      check: chalk2.green("\u2713"),
+      cross: chalk2.red("\u2717"),
+      spinner: chalk2.cyan("\u25D0")
+    };
     interval = null;
     frame = 0;
     quietMode = false;
@@ -2005,19 +2140,107 @@ var init_output = __esm({
               suffix = chalk2.dim(` [${parts.join(" | ")}]`);
             }
           }
-          console.log(`${chalk2.green("\u2713")} ${truncate(msg, 50)}${suffix}`);
+          console.log(`${ICONS.success} ${truncate(msg, 50)}${suffix}`);
         }
         return this;
       },
       // Errors go to stderr even in quiet mode
       fail(msg) {
         this.stop();
-        console.error(`${chalk2.red("\u2717")} ${truncate(msg, 65)}`);
+        console.error(`${ICONS.fail} ${truncate(msg, 65)}`);
+        return this;
+      },
+      // Rich error with context and recovery hint
+      failWithHint(error) {
+        this.stop();
+        const err = typeof error === "string" ? getError(error) : error;
+        console.error();
+        console.error(`${ICONS.fail} ${err.message}`);
+        if (err.file) {
+          console.error(chalk2.dim(`  File: ${err.file}`));
+        }
+        if (err.hint) {
+          console.error(chalk2.yellow(`  \u{1F4A1} ${err.hint}`));
+        }
+        if (err.docs) {
+          console.error(chalk2.dim(`  Docs: ${err.docs}`));
+        }
+        console.error();
         return this;
       },
       warn(msg) {
         this.stop();
-        if (!quietMode) console.log(`${chalk2.yellow("\u26A0")} ${truncate(msg, 65)}`);
+        if (!quietMode) console.log(`${ICONS.warn} ${truncate(msg, 65)}`);
+        return this;
+      },
+      // Informational message
+      info(msg) {
+        this.stop();
+        if (!quietMode) console.log(`${ICONS.info} ${msg}`);
+        return this;
+      },
+      // Debug message (only if DEBUG=1 or DEBUG=true)
+      debug(msg) {
+        this.stop();
+        const debugEnabled = process.env.DEBUG === "1" || process.env.DEBUG === "true";
+        if (!quietMode && debugEnabled) {
+          console.log(`${ICONS.debug} ${chalk2.dim(msg)}`);
+        }
+        return this;
+      },
+      // Alias for done - explicit success indicator
+      success(msg, metrics) {
+        return this.done(msg, metrics);
+      },
+      // Bulleted list
+      list(items, options = {}) {
+        this.stop();
+        if (quietMode) return this;
+        const bullet = options.bullet || ICONS.bullet;
+        const indent = " ".repeat(options.indent || 0);
+        for (const item of items) {
+          console.log(`${indent}${bullet} ${item}`);
+        }
+        return this;
+      },
+      // Simple table output
+      table(rows, options = {}) {
+        this.stop();
+        if (quietMode || rows.length === 0) return this;
+        const keys = Object.keys(rows[0]);
+        const colWidths = {};
+        for (const key of keys) {
+          colWidths[key] = key.length;
+          for (const row of rows) {
+            const val = String(row[key] ?? "");
+            if (val.length > colWidths[key]) colWidths[key] = val.length;
+          }
+        }
+        if (options.header !== false) {
+          const headerLine = keys.map((k) => k.padEnd(colWidths[k])).join("  ");
+          console.log(chalk2.dim(headerLine));
+          console.log(chalk2.dim("\u2500".repeat(headerLine.length)));
+        }
+        for (const row of rows) {
+          const line = keys.map((k) => String(row[k] ?? "").padEnd(colWidths[k])).join("  ");
+          console.log(line);
+        }
+        return this;
+      },
+      // Boxed content
+      box(title, content) {
+        this.stop();
+        if (quietMode) return this;
+        const lines = content.split("\n");
+        const maxLen = Math.max(title.length, ...lines.map((l) => l.length));
+        const border = "\u2500".repeat(maxLen + 2);
+        console.log(chalk2.dim(`\u250C${border}\u2510`));
+        console.log(chalk2.dim("\u2502") + ` ${chalk2.bold(title.padEnd(maxLen))} ` + chalk2.dim("\u2502"));
+        console.log(chalk2.dim(`\u251C${border}\u2524`));
+        for (const line of lines) {
+          console.log(chalk2.dim("\u2502") + ` ${line.padEnd(maxLen)} ` + chalk2.dim("\u2502"));
+        }
+        console.log(chalk2.dim(`\u2514${border}\u2518`));
         return this;
       },
       stop() {
@@ -16738,7 +16961,7 @@ Generated: ${(/* @__PURE__ */ new Date()).toLocaleString()}
           }
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           output_default.spin(`planning ${description}...`);
@@ -16795,7 +17018,7 @@ Generated: ${(/* @__PURE__ */ new Date()).toLocaleString()}
           }
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           output_default.spin("tracking bug...");
@@ -16918,7 +17141,7 @@ ${"=".repeat(60)}`);
           }
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           const wordCount = description.split(/\s+/).length;
@@ -16976,7 +17199,7 @@ Generated: ${(/* @__PURE__ */ new Date()).toLocaleString()}
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           if (!featureName) {
@@ -21067,7 +21290,7 @@ var init_analytics = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           const projectName = path45.basename(projectPath);
@@ -21507,7 +21730,7 @@ async function cleanup(options = {}, projectPath = process.cwd()) {
     output_default.spin("cleaning up...");
     const projectId = await config_manager_default.getProjectId(projectPath);
     if (!projectId) {
-      output_default.fail("no project ID");
+      output_default.failWithHint("NO_PROJECT_ID");
       return { success: false, error: "No project ID found" };
     }
     const cleaned = [];
@@ -21666,7 +21889,7 @@ async function recover(projectPath = process.cwd()) {
   try {
     const projectId = await config_manager_default.getProjectId(projectPath);
     if (!projectId) {
-      output_default.fail("no project ID");
+      output_default.failWithHint("NO_PROJECT_ID");
       return { success: false, error: "No project ID found" };
     }
     output_default.spin("checking for abandoned sessions...");
@@ -21710,7 +21933,7 @@ async function undo(projectPath = process.cwd()) {
     output_default.spin("creating undo point...");
     const projectId = await config_manager_default.getProjectId(projectPath);
     if (!projectId) {
-      output_default.fail("no project ID");
+      output_default.failWithHint("NO_PROJECT_ID");
       return { success: false, error: "No project ID found" };
     }
     const snapshotsPath = path49.join(path_manager_default.getGlobalProjectPath(projectId), "snapshots");
@@ -21755,7 +21978,7 @@ async function undo(projectPath = process.cwd()) {
       output_default.done("changes stashed (use /p:redo to restore)");
       return { success: true, snapshotId: stashMessage };
     } catch (gitError) {
-      output_default.fail("git operation failed");
+      output_default.failWithHint("GIT_OPERATION_FAILED");
       return { success: false, error: gitError.message };
     }
   } catch (error) {
@@ -21768,7 +21991,7 @@ async function redo(projectPath = process.cwd()) {
     output_default.spin("restoring changes...");
     const projectId = await config_manager_default.getProjectId(projectPath);
     if (!projectId) {
-      output_default.fail("no project ID");
+      output_default.failWithHint("NO_PROJECT_ID");
       return { success: false, error: "No project ID found" };
     }
     const snapshotsPath = path49.join(path_manager_default.getGlobalProjectPath(projectId), "snapshots");
@@ -21816,7 +22039,7 @@ async function redo(projectPath = process.cwd()) {
       output_default.done("changes restored");
       return { success: true };
     } catch (gitError) {
-      output_default.fail("git operation failed");
+      output_default.failWithHint("GIT_OPERATION_FAILED");
       return { success: false, error: gitError.message };
     }
   } catch (error) {
@@ -21828,7 +22051,7 @@ async function history(projectPath = process.cwd()) {
   try {
     const projectId = await config_manager_default.getProjectId(projectPath);
     if (!projectId) {
-      output_default.fail("no project ID");
+      output_default.failWithHint("NO_PROJECT_ID");
       return { success: false, error: "No project ID found" };
     }
     const snapshotsPath = path49.join(path_manager_default.getGlobalProjectPath(projectId), "snapshots");
@@ -22483,7 +22706,7 @@ ${result.stderr}`.trim();
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           let featureName = feature;
@@ -23557,7 +23780,7 @@ var init_workflow = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           if (task) {
@@ -23649,7 +23872,7 @@ var init_workflow = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           const currentTask = await stateStorage.getCurrentTask(projectId);
@@ -23715,7 +23938,7 @@ var init_workflow = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           const tasks = await queueStorage.getActiveTasks(projectId);
@@ -23740,7 +23963,7 @@ var init_workflow = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           const currentTask = await stateStorage.getCurrentTask(projectId);
@@ -23773,7 +23996,7 @@ var init_workflow = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           const currentTask = await stateStorage.getCurrentTask(projectId);
@@ -23811,7 +24034,7 @@ var init_workflow = __esm({
           if (!initResult.success) return initResult;
           const projectId = await config_manager_default.getProjectId(projectPath);
           if (!projectId) {
-            output_default.fail("no project ID");
+            output_default.failWithHint("NO_PROJECT_ID");
             return { success: false, error: "No project ID found" };
           }
           if (!input) {
@@ -24080,7 +24303,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.48.0",
+      version: "0.50.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {