@simonfestl/husky-cli 1.8.2 → 1.9.2

package/dist/commands/biz/tickets.js

@@ -8,6 +8,7 @@ import { ZendeskClient } from "../../lib/biz/index.js";
 import { AgentBrain } from "../../lib/biz/agent-brain.js";
 import * as fs from "fs";
 import * as path from "path";
+import { errorWithAutoHint } from "../../lib/error-hints.js";
 export const ticketsCommand = new Command("tickets")
     .description("Manage support tickets (Zendesk)");
 // husky biz tickets list
@@ -159,8 +160,7 @@ ticketsCommand
             });
         }
         if (Object.keys(updates).length === 0) {
-            console.error("Error: Provide --status, --priority, or --field");
-            process.exit(1);
+            errorWithAutoHint("Provide --status, --priority, or --field. Use --help for options.");
         }
         const ticket = await client.updateTicket(parseInt(id, 10), updates);
         if (options.json) {

package/dist/commands/config.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { ErrorHelpers, errorWithHint, ExplainTopic } from "../lib/error-hints.js";
 const CONFIG_DIR = join(homedir(), ".husky");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 // API Key validation - must be at least 16 characters, alphanumeric + common key chars (base64, JWT, etc.)
@@ -180,21 +181,20 @@ configCommand
         console.log("  Gemini:   gemini-api-key");
         console.log("  NocoDB:   nocodb-api-token, nocodb-base-url, nocodb-workspace-id");
         console.log("  Brain:    agent-type");
+        console.error("\n💡 For configuration help: husky explain config");
         process.exit(1);
     }
     // Validation for specific keys
     if (key === "api-url" || key === "billbee-base-url") {
         const validation = validateApiUrl(value);
         if (!validation.valid) {
-            console.error(`Error: ${validation.error}`);
-            process.exit(1);
+            errorWithHint(validation.error || "Invalid URL", ExplainTopic.CONFIG, "Learn about proper URL format");
         }
     }
     if (key === "agent-type") {
         const validTypes = ["support", "claude", "gotess", "supervisor", "worker"];
         if (!validTypes.includes(value)) {
-            console.error(`Error: Invalid agent type. Must be one of: ${validTypes.join(", ")}`);
-            process.exit(1);
+            errorWithHint(`Invalid agent type. Must be one of: ${validTypes.join(", ")}`, ExplainTopic.CONFIG, "See available configuration options");
         }
     }
     // Set the value
@@ -240,41 +240,41 @@ configCommand
     const config = getConfig();
     // Check if configuration is complete
     if (!config.apiUrl) {
-        console.error("Error: API URL not configured. Run: husky config set api-url <url>");
-        process.exit(1);
+        ErrorHelpers.missingApiUrl();
     }
     if (!config.apiKey) {
-        console.error("Error: API key not configured. Run: husky config set api-key <key>");
-        process.exit(1);
+        ErrorHelpers.missingApiKey();
     }
     console.log("Testing API connection...");
     try {
         // First test basic connectivity with /api/tasks
         const tasksUrl = new URL("/api/tasks", config.apiUrl);
+        const apiKey = config.apiKey; // We already checked it's defined above
         const tasksRes = await fetch(tasksUrl.toString(), {
-            headers: { "x-api-key": config.apiKey },
+            headers: { "x-api-key": apiKey },
         });
         if (!tasksRes.ok) {
             if (tasksRes.status === 401) {
                 console.error(`API connection failed: Unauthorized (HTTP 401)`);
                 console.error("  Check your API key with: husky config set api-key <key>");
+                console.error("\n💡 For configuration help: husky explain config");
                 process.exit(1);
             }
             else if (tasksRes.status === 403) {
                 console.error(`API connection failed: Forbidden (HTTP 403)`);
                 console.error("  Your API key may not have the required permissions");
+                console.error("\n💡 For configuration help: husky explain config");
                 process.exit(1);
             }
             else {
-                console.error(`API connection failed: HTTP ${tasksRes.status}`);
-                process.exit(1);
+                errorWithHint(`API connection failed: HTTP ${tasksRes.status}`, ExplainTopic.CONFIG, "Check your API configuration");
             }
         }
         console.log(`API connection successful (API URL: ${config.apiUrl})`);
         // Now fetch role/permissions from whoami
         const whoamiUrl = new URL("/api/auth/whoami", config.apiUrl);
         const whoamiRes = await fetch(whoamiUrl.toString(), {
-            headers: { "x-api-key": config.apiKey },
+            headers: { "x-api-key": apiKey },
         });
         if (whoamiRes.ok) {
             const data = await whoamiRes.json();
@@ -298,9 +298,11 @@ configCommand
         if (error instanceof TypeError && error.message.includes("fetch")) {
             console.error(`API connection failed: Could not connect to ${config.apiUrl}`);
             console.error("  Check your API URL with: husky config set api-url <url>");
+            console.error("\n💡 For configuration help: husky explain config");
         }
         else {
             console.error(`API connection failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            console.error("\n💡 For configuration help: husky explain config");
         }
         process.exit(1);
     }

package/dist/commands/task.js

@@ -8,14 +8,16 @@ import { WorktreeManager } from "../lib/worktree.js";
 import { execSync } from "child_process";
 import { resolveProject, fetchProjects, formatProjectList } from "../lib/project-resolver.js";
 import { requirePermission } from "../lib/permissions.js";
+import { ErrorHelpers, errorWithHint, ExplainTopic } from "../lib/error-hints.js";
 export const taskCommand = new Command("task")
     .description("Manage tasks");
 // Helper: Get task ID from --id flag or HUSKY_TASK_ID env var
 function getTaskId(options) {
     const id = options.id || process.env.HUSKY_TASK_ID;
     if (!id) {
-        console.error("Error: Task ID required. Use --id or set HUSKY_TASK_ID environment variable.");
-        process.exit(1);
+        ErrorHelpers.missingTaskId();
+        // TypeScript doesn't know that ErrorHelpers.missingTaskId() never returns
+        throw new Error("unreachable");
     }
     return id;
 }
@@ -23,8 +25,9 @@ function getTaskId(options) {
 function ensureConfig() {
     const config = getConfig();
     if (!config.apiUrl) {
-        console.error("Error: API URL not configured. Run: husky config set api-url <url>");
-        process.exit(1);
+        ErrorHelpers.missingApiUrl();
+        // TypeScript doesn't know that ErrorHelpers.missingApiUrl() never returns
+        throw new Error("unreachable");
     }
     return config;
 }
@@ -128,8 +131,7 @@ taskCommand
     .action(async (options) => {
     const config = getConfig();
     if (!config.apiUrl) {
-        console.error("Error: API URL not configured. Run: husky config set api-url <url>");
-        process.exit(1);
+        ErrorHelpers.missingApiUrl();
     }
     try {
         const url = new URL("/api/tasks", config.apiUrl);
@@ -141,7 +143,7 @@ taskCommand
         let filterProjectId = null;
         if (!options.all && !options.project) {
             const repoIdentifier = getGitRepoIdentifier();
-            if (repoIdentifier) {
+            if (repoIdentifier && config.apiUrl) {
                 autoDetectedProject = await findProjectByRepo(config.apiUrl, config.apiKey, repoIdentifier);
                 if (autoDetectedProject) {
                     filterProjectId = autoDetectedProject.id;
@@ -215,8 +217,7 @@ taskCommand
         printTasks(tasks);
     }
     catch (error) {
-        console.error("Error fetching tasks:", error);
-        process.exit(1);
+        errorWithHint(`Error fetching tasks: ${error instanceof Error ? error.message : error}`, ExplainTopic.TASK, "Learn about task listing and management");
     }
 });
 // husky task start <id>
@@ -227,14 +228,16 @@ taskCommand
     .action(async (id, options) => {
     const config = getConfig();
     if (!config.apiUrl) {
-        console.error("Error: API URL not configured.");
-        process.exit(1);
+        ErrorHelpers.missingApiUrl();
+        throw new Error("unreachable");
     }
+    const apiUrl = config.apiUrl; // Type narrowing
+    const apiKey = config.apiKey || "";
     try {
         // Ensure worker is registered and create a session
-        const workerId = await ensureWorkerRegistered(config.apiUrl, config.apiKey || "");
+        const workerId = await ensureWorkerRegistered(apiUrl, apiKey);
         const sessionId = generateSessionId();
-        await registerSession(config.apiUrl, config.apiKey || "", workerId, sessionId);
+        await registerSession(apiUrl, apiKey, workerId, sessionId);
         // Create worktree for isolation (unless --no-worktree)
         let worktreeInfo = null;
         if (options.worktree !== false) {
@@ -515,8 +518,7 @@ taskCommand
         updates.projectId = resolved.projectId;
     }
     if (Object.keys(updates).length === 0) {
-        console.error("Error: No update options provided. Use --help for available options.");
-        process.exit(1);
+        errorWithHint("No update options provided. Use --help for available options.", ExplainTopic.TASK, "See all available update options");
     }
     // Auto-create worktree when starting a task (unless --no-worktree)
     let worktreeInfo = null;
@@ -715,12 +717,10 @@ taskCommand
     const taskId = idArg || options.id || process.env.HUSKY_TASK_ID;
     const message = messageArg || options.message;
     if (!taskId) {
-        console.error("Error: Task ID required. Use positional arg, --id, or set HUSKY_TASK_ID");
-        process.exit(1);
+        errorWithHint("Task ID required. Use positional arg, --id, or set HUSKY_TASK_ID", ExplainTopic.TASK, "Learn about task ID usage");
     }
     if (!message) {
-        console.error("Error: Message required. Use positional arg or -m/--message");
-        process.exit(1);
+        errorWithHint("Message required. Use positional arg or -m/--message", ExplainTopic.TASK, "See message command examples");
     }
     try {
         const res = await fetch(`${config.apiUrl}/api/tasks/${taskId}/status`, {

package/dist/lib/biz/agent-brain.d.ts

@@ -1,4 +1,4 @@
-export declare const AGENT_TYPES: readonly ["support", "claude", "gotess", "supervisor", "worker"];
+export declare const AGENT_TYPES: readonly ["support", "claude", "gotess", "supervisor", "worker", "reviewer", "e2e_agent", "pr_agent"];
 export type AgentType = typeof AGENT_TYPES[number];
 export type MemoryVisibility = 'private' | 'team' | 'public';
 export interface Memory {
@@ -42,7 +42,9 @@ export declare class AgentBrain {
     getDatabaseInfo(): {
         agentType?: AgentType;
         databaseName: string;
+        collectionName: string;
     };
+    private getCollectionName;
     private ensureCollection;
     remember(content: string, tags?: string[], metadata?: Record<string, unknown>, visibility?: MemoryVisibility, allowPii?: boolean): Promise<string>;
     recall(query: string, limit?: number, minScore?: number): Promise<RecallResult[]>;

package/dist/lib/biz/agent-brain.js

@@ -3,9 +3,9 @@ import { EmbeddingService } from './embeddings.js';
 import { getConfig } from '../../commands/config.js';
 import { randomUUID } from 'crypto';
 import { sanitizeForEmbedding } from './pii-filter.js';
-const MEMORIES_COLLECTION = 'agent-memories';
+const DEFAULT_COLLECTION = 'agent-memories';
 const VECTOR_SIZE = 768;
-export const AGENT_TYPES = ['support', 'claude', 'gotess', 'supervisor', 'worker'];
+export const AGENT_TYPES = ['support', 'claude', 'gotess', 'supervisor', 'worker', 'reviewer', 'e2e_agent', 'pr_agent'];
 export function isValidAgentType(value) {
     return value !== undefined && AGENT_TYPES.includes(value);
 }
@@ -45,17 +45,25 @@ export class AgentBrain {
         });
     }
     getDatabaseInfo() {
+        const collectionName = this.getCollectionName();
         return {
             agentType: this.agentType,
-            databaseName: `qdrant:${MEMORIES_COLLECTION}`,
+            databaseName: `qdrant:${collectionName}`,
+            collectionName,
         };
     }
+    getCollectionName() {
+        if (!this.agentType)
+            return DEFAULT_COLLECTION;
+        return `${this.agentType}-memories`;
+    }
     async ensureCollection() {
+        const collection = this.getCollectionName();
         try {
-            await this.qdrant.getCollection(MEMORIES_COLLECTION);
+            await this.qdrant.getCollection(collection);
         }
         catch {
-            await this.qdrant.createCollection(MEMORIES_COLLECTION, VECTOR_SIZE);
+            await this.qdrant.createCollection(collection, VECTOR_SIZE);
         }
     }
     async remember(content, tags = [], metadata, visibility = 'private', allowPii = false) {
@@ -69,7 +77,7 @@ export class AgentBrain {
         const embedding = await this.embeddings.embed(sanitizeResult.sanitized);
         const id = randomUUID();
         const now = new Date().toISOString();
-        await this.qdrant.upsertOne(MEMORIES_COLLECTION, id, embedding, {
+        await this.qdrant.upsertOne(this.getCollectionName(), id, embedding, {
             agent: this.agentId,
             agentType: this.agentType || 'default',
             content: sanitizeResult.sanitized, // Store sanitized content
@@ -108,7 +116,7 @@ export class AgentBrain {
         if (this.agentType) {
             filter.must.push({ key: 'agentType', match: { value: this.agentType } });
         }
-        const results = await this.qdrant.search(MEMORIES_COLLECTION, queryEmbedding, limit, {
+        const results = await this.qdrant.search(this.getCollectionName(), queryEmbedding, limit, {
             filter,
             scoreThreshold: minScore,
         });
@@ -142,7 +150,7 @@ export class AgentBrain {
                 }
             ]
         };
-        const results = await this.qdrant.scroll(MEMORIES_COLLECTION, {
+        const results = await this.qdrant.scroll(this.getCollectionName(), {
             filter,
             limit,
             with_payload: true,
@@ -162,7 +170,7 @@ export class AgentBrain {
     }
     async forget(memoryId) {
         await this.ensureCollection();
-        await this.qdrant.deletePoints(MEMORIES_COLLECTION, [memoryId]);
+        await this.qdrant.deletePoints(this.getCollectionName(), [memoryId]);
     }
     async listMemories(limit = 20) {
         await this.ensureCollection();
@@ -174,7 +182,7 @@ export class AgentBrain {
         if (this.agentType) {
             filter.must.push({ key: 'agentType', match: { value: this.agentType } });
         }
-        const results = await this.qdrant.scroll(MEMORIES_COLLECTION, {
+        const results = await this.qdrant.scroll(this.getCollectionName(), {
             filter,
             limit,
             with_payload: true,
@@ -202,7 +210,7 @@ export class AgentBrain {
         if (this.agentType) {
             filter.must.push({ key: 'agentType', match: { value: this.agentType } });
         }
-        const results = await this.qdrant.scroll(MEMORIES_COLLECTION, {
+        const results = await this.qdrant.scroll(this.getCollectionName(), {
             filter,
             limit: 1000,
             with_payload: true,
@@ -228,7 +236,7 @@ export class AgentBrain {
     async publish(memoryId, visibility) {
         await this.ensureCollection();
         const now = new Date().toISOString();
-        await this.qdrant.setPayload(MEMORIES_COLLECTION, memoryId, {
+        await this.qdrant.setPayload(this.getCollectionName(), memoryId, {
             visibility,
             publishedBy: this.agentId,
             publishedAt: now,
@@ -241,7 +249,7 @@ export class AgentBrain {
     async unpublish(memoryId) {
         await this.ensureCollection();
         const now = new Date().toISOString();
-        await this.qdrant.setPayload(MEMORIES_COLLECTION, memoryId, {
+        await this.qdrant.setPayload(this.getCollectionName(), memoryId, {
             visibility: 'private',
             publishedBy: undefined,
             publishedAt: undefined,
@@ -269,7 +277,7 @@ export class AgentBrain {
                 { key: 'status', match: { value: 'active' } },
             ],
         };
-        const results = await this.qdrant.search(MEMORIES_COLLECTION, queryEmbedding, limit * 3, {
+        const results = await this.qdrant.search(this.getCollectionName(), queryEmbedding, limit * 3, {
             filter,
             scoreThreshold: minScore,
         });
@@ -312,7 +320,7 @@ export class AgentBrain {
                 { key: 'status', match: { value: 'active' } },
             ],
         };
-        const results = await this.qdrant.scroll(MEMORIES_COLLECTION, {
+        const results = await this.qdrant.scroll(this.getCollectionName(), {
             filter,
             limit,
             with_payload: true,
@@ -340,13 +348,13 @@ export class AgentBrain {
      */
     async boost(memoryId) {
         await this.ensureCollection();
-        const point = await this.qdrant.getPoint(MEMORIES_COLLECTION, memoryId);
+        const point = await this.qdrant.getPoint(this.getCollectionName(), memoryId);
         if (!point)
             throw new Error('Memory not found');
         const boostCount = Number(point.payload?.boostCount || 0) + 1;
         const downvoteCount = Number(point.payload?.downvoteCount || 0);
         const qualityScore = this.calculateQualityScore(boostCount, downvoteCount);
-        await this.qdrant.setPayload(MEMORIES_COLLECTION, memoryId, {
+        await this.qdrant.setPayload(this.getCollectionName(), memoryId, {
             boostCount,
             qualityScore,
             updatedAt: new Date().toISOString(),
@@ -357,13 +365,13 @@ export class AgentBrain {
      */
     async downvote(memoryId) {
         await this.ensureCollection();
-        const point = await this.qdrant.getPoint(MEMORIES_COLLECTION, memoryId);
+        const point = await this.qdrant.getPoint(this.getCollectionName(), memoryId);
         if (!point)
             throw new Error('Memory not found');
         const boostCount = Number(point.payload?.boostCount || 0);
         const downvoteCount = Number(point.payload?.downvoteCount || 0) + 1;
         const qualityScore = this.calculateQualityScore(boostCount, downvoteCount);
-        await this.qdrant.setPayload(MEMORIES_COLLECTION, memoryId, {
+        await this.qdrant.setPayload(this.getCollectionName(), memoryId, {
             downvoteCount,
             qualityScore,
             updatedAt: new Date().toISOString(),
@@ -374,7 +382,7 @@ export class AgentBrain {
      */
     async getQuality(memoryId) {
         await this.ensureCollection();
-        const point = await this.qdrant.getPoint(MEMORIES_COLLECTION, memoryId);
+        const point = await this.qdrant.getPoint(this.getCollectionName(), memoryId);
         if (!point)
             throw new Error('Memory not found');
         return {
@@ -434,7 +442,7 @@ export class AgentBrain {
                 }))
             });
         }
-        const results = await this.qdrant.scroll(MEMORIES_COLLECTION, {
+        const results = await this.qdrant.scroll(this.getCollectionName(), {
             filter,
             limit: 1000,
             with_payload: true,
@@ -468,7 +476,7 @@ export class AgentBrain {
                     boostCount,
                 });
                 if (!dryRun) {
-                    await this.qdrant.setPayload(MEMORIES_COLLECTION, String(r.id), {
+                    await this.qdrant.setPayload(this.getCollectionName(), String(r.id), {
                         status: 'archived',
                         updatedAt: new Date().toISOString(),
                     });
@@ -488,7 +496,7 @@ export class AgentBrain {
                 { key: 'status', match: { value: 'archived' } },
             ],
         };
-        const results = await this.qdrant.scroll(MEMORIES_COLLECTION, {
+        const results = await this.qdrant.scroll(this.getCollectionName(), {
             filter,
             limit: 1000,
             with_payload: true,
@@ -503,7 +511,7 @@ export class AgentBrain {
             }
         }
         if (toPurge.length > 0) {
-            await this.qdrant.deletePoints(MEMORIES_COLLECTION, toPurge);
+            await this.qdrant.deletePoints(this.getCollectionName(), toPurge);
         }
         return toPurge.length;
     }

package/dist/lib/biz/qdrant.d.ts

@@ -48,6 +48,7 @@ export declare class QdrantClient {
     upsertOne(collectionName: string, id: string | number, vector: number[], payload?: Record<string, unknown>): Promise<void>;
     getPoint(collectionName: string, id: string | number): Promise<Point | null>;
     deletePoints(collectionName: string, ids: (string | number)[]): Promise<void>;
+    setPayload(collectionName: string, pointId: string | number, payload: Record<string, unknown>): Promise<void>;
     count(collectionName: string): Promise<number>;
     scroll(collectionName: string, options?: {
         filter?: Record<string, unknown>;
@@ -57,9 +58,5 @@ export declare class QdrantClient {
         id: string | number;
         payload: Record<string, unknown>;
     }>>;
-    /**
-     * Update payload for a specific point (for quality/visibility updates)
-     */
-    setPayload(collectionName: string, id: string | number, payload: Record<string, unknown>): Promise<void>;
 }
 export default QdrantClient;

package/dist/lib/biz/qdrant.js

@@ -155,6 +155,15 @@ export class QdrantClient {
             body: JSON.stringify({ points: ids }),
         });
     }
+    async setPayload(collectionName, pointId, payload) {
+        await this.request(`/collections/${collectionName}/points/payload?wait=true`, {
+            method: 'POST',
+            body: JSON.stringify({
+                points: [pointId],
+                payload,
+            }),
+        });
+    }
     async count(collectionName) {
         const info = await this.getCollection(collectionName);
         return info.pointsCount;
@@ -173,17 +182,5 @@ export class QdrantClient {
             payload: p.payload || {},
         }));
     }
-    /**
-     * Update payload for a specific point (for quality/visibility updates)
-     */
-    async setPayload(collectionName, id, payload) {
-        await this.request(`/collections/${collectionName}/points/payload?wait=true`, {
-            method: 'POST',
-            body: JSON.stringify({
-                points: [id],
-                payload,
-            }),
-        });
-    }
 }
 export default QdrantClient;

package/dist/lib/error-hints.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Error Hints System
+ *
+ * Provides helpful hints and references to `husky explain` when users encounter errors.
+ * This makes the CLI more user-friendly by guiding users to relevant documentation.
+ */
+/**
+ * Map of error categories to their corresponding `husky explain` topics
+ */
+export declare enum ExplainTopic {
+    TASK = "task",
+    CONFIG = "config",
+    ROADMAP = "roadmap",
+    CHANGELOG = "changelog",
+    AGENT = "agent"
+}
+/**
+ * Print an error message with an automatic hint based on content
+ */
+export declare function errorWithAutoHint(message: string, exitCode?: number): never;
+/**
+ * Print an error message with a specific hint topic
+ */
+export declare function errorWithHint(message: string, topic: ExplainTopic, customHint?: string, exitCode?: number): never;
+/**
+ * Print an error message with no hint (for errors where no help is available)
+ */
+export declare function errorWithoutHint(message: string, exitCode?: number): never;
+/**
+ * Predefined error helpers for common scenarios
+ */
+export declare const ErrorHelpers: {
+    /**
+     * Error: Task ID not provided
+     */
+    missingTaskId: () => never;
+    /**
+     * Error: API URL not configured
+     */
+    missingApiUrl: () => never;
+    /**
+     * Error: API key not configured
+     */
+    missingApiKey: () => never;
+    /**
+     * Error: Both API URL and key not configured
+     */
+    missingConfig: () => never;
+    /**
+     * Error: Permission denied
+     */
+    permissionDenied: (operation: string) => never;
+    /**
+     * Error: Invalid task status
+     */
+    invalidTaskStatus: (status: string) => never;
+    /**
+     * Error: Task operation failed
+     */
+    taskOperationFailed: (operation: string, reason: string) => never;
+    /**
+     * Error: API request failed
+     */
+    apiRequestFailed: (status: number, message: string) => never;
+};
+/**
+ * Format a warning message with a hint (non-fatal)
+ */
+export declare function warningWithHint(message: string, topic: ExplainTopic, customHint?: string): void;

package/dist/lib/error-hints.js

@@ -0,0 +1,164 @@
+/**
+ * Error Hints System
+ *
+ * Provides helpful hints and references to `husky explain` when users encounter errors.
+ * This makes the CLI more user-friendly by guiding users to relevant documentation.
+ */
+/**
+ * Map of error categories to their corresponding `husky explain` topics
+ */
+export var ExplainTopic;
+(function (ExplainTopic) {
+    ExplainTopic["TASK"] = "task";
+    ExplainTopic["CONFIG"] = "config";
+    ExplainTopic["ROADMAP"] = "roadmap";
+    ExplainTopic["CHANGELOG"] = "changelog";
+    ExplainTopic["AGENT"] = "agent";
+})(ExplainTopic || (ExplainTopic = {}));
+const ERROR_PATTERNS = [
+    {
+        keywords: ["task id", "HUSKY_TASK_ID", "task status", "task complete", "task start"],
+        topic: ExplainTopic.TASK,
+    },
+    {
+        keywords: ["api url", "api key", "not configured", "config set", "authentication"],
+        topic: ExplainTopic.CONFIG,
+    },
+    {
+        keywords: ["roadmap", "phase", "feature"],
+        topic: ExplainTopic.ROADMAP,
+    },
+    {
+        keywords: ["changelog", "version", "commits"],
+        topic: ExplainTopic.CHANGELOG,
+    },
+    {
+        keywords: ["workflow", "agent", "session"],
+        topic: ExplainTopic.AGENT,
+    },
+];
+/**
+ * Detect which explain topic is most relevant based on error message
+ */
+function detectExplainTopic(message) {
+    const lowerMessage = message.toLowerCase();
+    for (const pattern of ERROR_PATTERNS) {
+        if (pattern.keywords.some(keyword => lowerMessage.includes(keyword))) {
+            return pattern.topic;
+        }
+    }
+    return null;
+}
+/**
+ * Format a hint message for a specific explain topic
+ */
+function formatHint(topic, customHint) {
+    if (customHint) {
+        return `\n💡 Hint: ${customHint}\n   Run: husky explain ${topic}`;
+    }
+    const hints = {
+        [ExplainTopic.TASK]: "For task workflow help",
+        [ExplainTopic.CONFIG]: "For configuration help",
+        [ExplainTopic.ROADMAP]: "For roadmap commands help",
+        [ExplainTopic.CHANGELOG]: "For changelog commands help",
+        [ExplainTopic.AGENT]: "For agent workflow examples",
+    };
+    return `\n💡 ${hints[topic]}: husky explain ${topic}`;
+}
+/**
+ * Print an error message with an automatic hint based on content
+ */
+export function errorWithAutoHint(message, exitCode = 1) {
+    console.error(`Error: ${message}`);
+    const topic = detectExplainTopic(message);
+    if (topic) {
+        console.error(formatHint(topic));
+    }
+    process.exit(exitCode);
+}
+/**
+ * Print an error message with a specific hint topic
+ */
+export function errorWithHint(message, topic, customHint, exitCode = 1) {
+    console.error(`Error: ${message}`);
+    console.error(formatHint(topic, customHint));
+    process.exit(exitCode);
+}
+/**
+ * Print an error message with no hint (for errors where no help is available)
+ */
+export function errorWithoutHint(message, exitCode = 1) {
+    console.error(`Error: ${message}`);
+    process.exit(exitCode);
+}
+/**
+ * Predefined error helpers for common scenarios
+ */
+export const ErrorHelpers = {
+    /**
+     * Error: Task ID not provided
+     */
+    missingTaskId: () => {
+        errorWithHint("Task ID required. Use --id or set HUSKY_TASK_ID environment variable.", ExplainTopic.TASK, "Learn about task ID usage and environment variables");
+    },
+    /**
+     * Error: API URL not configured
+     */
+    missingApiUrl: () => {
+        errorWithHint("API URL not configured. Run: husky config set api-url <url>", ExplainTopic.CONFIG, "Learn how to configure the CLI");
+    },
+    /**
+     * Error: API key not configured
+     */
+    missingApiKey: () => {
+        errorWithHint("API key not configured. Run: husky config set api-key <key>", ExplainTopic.CONFIG, "Learn how to configure authentication");
+    },
+    /**
+     * Error: Both API URL and key not configured
+     */
+    missingConfig: () => {
+        errorWithHint("API URL and key required. Run: husky config test", ExplainTopic.CONFIG, "Learn about CLI configuration");
+    },
+    /**
+     * Error: Permission denied
+     */
+    permissionDenied: (operation) => {
+        errorWithAutoHint(`Permission denied: ${operation}`);
+    },
+    /**
+     * Error: Invalid task status
+     */
+    invalidTaskStatus: (status) => {
+        errorWithHint(`Invalid status: ${status}. Valid statuses: backlog, in_progress, review, done`, ExplainTopic.TASK, "See all available task statuses");
+    },
+    /**
+     * Error: Task operation failed
+     */
+    taskOperationFailed: (operation, reason) => {
+        errorWithHint(`Failed to ${operation}: ${reason}`, ExplainTopic.TASK, "Learn about task management");
+    },
+    /**
+     * Error: API request failed
+     */
+    apiRequestFailed: (status, message) => {
+        if (status === 401) {
+            errorWithHint("Authentication failed. Check your API key.", ExplainTopic.CONFIG, "Learn how to configure authentication");
+        }
+        else if (status === 403) {
+            errorWithAutoHint(`Permission denied: ${message}`);
+        }
+        else if (status === 404) {
+            errorWithoutHint(`Resource not found: ${message}`);
+        }
+        else {
+            errorWithAutoHint(`API error (${status}): ${message}`);
+        }
+    },
+};
+/**
+ * Format a warning message with a hint (non-fatal)
+ */
+export function warningWithHint(message, topic, customHint) {
+    console.warn(`⚠ Warning: ${message}`);
+    console.warn(formatHint(topic, customHint).replace("💡", "ℹ️"));
+}

package/dist/lib/permissions.js

@@ -5,6 +5,7 @@
  * Permissions are fetched from the API and cached locally.
  */
 import { getConfig, hasPermission, getRole, fetchAndCacheRole, clearRoleCache } from "../commands/config.js";
+import { ExplainTopic } from "./error-hints.js";
 /**
  * Check if current user has a specific permission.
  * Uses cached permissions from config.
@@ -27,6 +28,7 @@ export function requirePermission(permission) {
         else {
             console.error("Run 'husky config test' to refresh your role and permissions.");
         }
+        console.error(`\n💡 For configuration help: husky explain ${ExplainTopic.CONFIG}`);
         process.exit(1);
     }
 }
@@ -43,6 +45,7 @@ export function requireAnyPermission(permissions) {
         if (config.role) {
             console.error(`Your role (${config.role}) does not have these permissions.`);
         }
+        console.error(`\n💡 For configuration help: husky explain ${ExplainTopic.CONFIG}`);
         process.exit(1);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonfestl/husky-cli",
-  "version": "1.8.2",
+  "version": "1.9.2",
   "description": "CLI for Huskyv0 Task Orchestration with Claude Agent SDK",
   "type": "module",
   "bin": {