@compilr-dev/cli 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to `@compilr-dev/cli` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Beta notice:** versions in the `0.x` range may contain breaking changes
+> between minors. Read each release entry before upgrading.
+
+---
+
+## [Unreleased]
+
+## [0.6.2] — 2026-04-25
+
+### Fixed
+- Respect the [`NO_COLOR`](https://no-color.org) standard — `NO_COLOR=1 compilr ...`
+  now produces uncolored output instead of being silently overridden by
+  `FORCE_COLOR=3`. Restores accessibility for screen readers, low-contrast
+  terminals, log redirection, and CI environments.
+
+### Changed
+- Lower minimum supported Node from `>=22.0.0` to `>=20.0.0` — Node 20 is the
+  active LTS line and the codebase uses no v22-only APIs. Restores compatibility
+  for users still on Node 20 LTS.
+
+### Added
+- Documented opt-outs for the npm registry update check. Set any of the
+  following to skip the network call on startup:
+  - `COMPILR_NO_UPDATE_CHECK=1` (project-specific)
+  - `NO_UPDATE_NOTIFIER=1` (de-facto standard from `update-notifier`)
+  - `CI=true` (auto-respected in CI)
+- `CHANGELOG.md` shipped in the published tarball (this file).
+
+### Removed
+- TypeScript incremental build caches (`*.tsbuildinfo`) no longer ship in the
+  npm tarball. Tarball is now ~760 KB compressed (previously ~1 MB) — about
+  ~660 KB lighter on disk after install.
+
+---
+
+## [0.6.1] — 2026-04-21
+
+### Fixed
+- Resolved `npm audit` vulnerabilities in transitive deps (`hono`, `protobufjs`).
+
+## [0.6.0] — 2026-04-19
+
+### Changed
+- **Major:** CLI now builds on `createCompilrAgent` from `@compilr-dev/sdk`
+  (universal agent runtime). All agent setup, tool assembly, capability
+  loading, and team coordination flow through the SDK. CLI source dropped
+  from ~3.5 K LOC of agent wiring to a thin adapter.
+- Logging is now structured JSON via `@compilr-dev/logger` (Pino) — no more
+  raw `console.log` from diagnostic paths. Logs are scrubbed for secrets.
+
+### Added
+- Plan Mode V2 — permission-blocking + tool-based transitions for safer
+  multi-step planning workflows. Plan can now be approved/edited from
+  inside the CLI.
+- `/app` command — terminal app model viewer overlay (entities, fields,
+  relationships, layout, config). Aligned columns, no emojis.
+- Custom agent wizard Step 5 — free-text custom instructions added per agent.
+- Template support in custom agent wizard — `Ctrl+T` to save as template,
+  list UI to load existing templates.
+- Guide tool migrated to SDK (`createGuideTool({ environment, additionalEntries })`).
+- Removed two-repo and guided-workflow options from the wizard — both are
+  always single-repo + flexible now.
+
+### Fixed
+- Credential encryption now survives container restarts (master key
+  derivation hardened).
+- `/app` overlay — aligned columns, layout/config in summary, no emojis.
+- Agent IDs may contain dashes.
+
+## [0.5.x] — 2026-03 → 2026-04
+
+Highlights from the 0.5 line:
+
+- Migrated more code paths to `@compilr-dev/sdk` (anchors, MCP, permissions,
+  SQLite repositories, capability loading).
+- Pin API replaces the older anchor API for project state injection.
+- Multi-terminal session awareness, dynamic capability loading with
+  auto-load on filtered tool use, observation masking, tool input
+  compaction, and tool result auto-delegation.
+- Multi-LLM support across 9 providers (Claude, OpenAI, Gemini, Groq,
+  Fireworks, Together, Perplexity, OpenRouter, Ollama).
+- Multi-agent teams (delegate, delegate_background, $mention routing,
+  /team dashboard, background queues).
+
+For commit-level detail of the 0.5 line, see git log between v0.5.0 and v0.6.0.
+
+---
+
+## Earlier versions
+
+The `0.4.x` and prior series were rapid pre-MVP iterations. See the git
+history for details.
+
+[Unreleased]: https://github.com/compilr-dev/cli/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/compilr-dev/cli/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/compilr-dev/cli/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/compilr-dev/cli/compare/v0.5.17...v0.6.0

package/README.md

@@ -217,6 +217,18 @@ export GOOGLE_API_KEY="..."             # Google Gemini
 
 Environment variables take priority over stored keys.
 
+### Behavior Environment Variables
+
+The CLI honors several standard environment variables for accessibility,
+privacy, and CI use:
+
+| Variable | Effect |
+|---|---|
+| `NO_COLOR=1` | Disable all ANSI colors. Honors the [no-color.org](https://no-color.org) standard. |
+| `COMPILR_NO_UPDATE_CHECK=1` | Skip the npm registry update check at startup. |
+| `NO_UPDATE_NOTIFIER=1` | Same as above. De-facto standard from `update-notifier`. |
+| `CI=true` | Auto-skips the update check (no nag in CI environments). |
+
 ### Project Configuration
 
 Create a `COMPILR.md` file in your project root to provide context:

package/dist/agent.d.ts

@@ -57,6 +57,8 @@ export interface AgentOptions {
     guidedModeContext?: string;
     /** Plan mode context */
     planModeContext?: string;
+    /** Plan mode callbacks for plan_submit and plan_mode_exit tools */
+    planModeCallbacks?: import('@compilr-dev/sdk').PlanModeCallbacks;
     /** Enable anchors (critical info that survives compaction) */
     enableAnchors?: boolean;
     /** Pre-loaded anchors to add at startup */

package/dist/agent.js

@@ -17,6 +17,59 @@ import { setStaticEstimates, estimateTokens, estimateJsonTokens, } from './utils
 import { createFileLockCheckHook, createFileLockAcquireHook } from './multi-agent/file-lock-hook.js';
 import { getActiveProject } from './tools/project-db.js';
 import { allDbTools, allFactoryTools } from './tools/db-tools.js';
+import { createGuideTool } from '@compilr-dev/sdk';
+import { CLI_GUIDE_ENTRIES } from './guide/cli-guide-entries.js';
+const cliGuideTool = createGuideTool({
+    environment: 'cli',
+    additionalEntries: CLI_GUIDE_ENTRIES,
+});
+import { defineTool, createSuccessResult } from '@compilr-dev/agents';
+/** Create plan_submit and plan_mode_exit tools if callbacks are provided */
+function buildPlanModeTools(callbacks) {
+    if (!callbacks || !callbacks.onPlanSubmit || !callbacks.onPlanModeExit)
+        return [];
+    const onSubmit = callbacks.onPlanSubmit;
+    const onExit = callbacks.onPlanModeExit;
+    const planSubmitTool = defineTool({
+        name: 'plan_submit',
+        description: 'Submit a plan for user approval. Call when your plan is ready for review. ' +
+            'The user will choose to approve, revise, or reject. On approval, write tools are unlocked.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                plan_id: { type: 'number', description: 'ID of the plan to submit' },
+                summary: { type: 'string', description: 'One-line summary of the plan' },
+            },
+            required: ['plan_id'],
+        },
+        execute: async (input) => {
+            const result = await onSubmit({ planId: input.plan_id, summary: input.summary });
+            const messages = {
+                'approve-auto': 'Plan approved. Auto-accept mode enabled. Proceed with implementation.',
+                approve: 'Plan approved. Proceed with implementation.',
+                revise: `Plan needs revision. Feedback: ${result.feedback ?? 'No specific feedback.'}`,
+                reject: 'Plan rejected.',
+            };
+            return createSuccessResult({ action: result.action, message: messages[result.action] });
+        },
+    });
+    const planModeExitTool = defineTool({
+        name: 'plan_mode_exit',
+        description: 'Exit plan mode without a plan. Use when the task is simple enough to implement directly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                reason: { type: 'string', description: 'Brief reason for exiting plan mode' },
+            },
+            required: ['reason'],
+        },
+        execute: async (input) => {
+            await onExit({ reason: input.reason });
+            return createSuccessResult({ message: `Exited plan mode: ${input.reason}. Full tools now available.` });
+        },
+    });
+    return [planSubmitTool, planModeExitTool];
+}
 /**
  * Default permission rules for potentially dangerous operations
  */
@@ -190,6 +243,14 @@ function createContextPressureHook() {
 export function createAgent(options = {}) {
     const { provider, model, apiKey } = resolveProviderConfig(options);
     const systemPrompt = buildSystemPrompt(options);
+    log.info({
+        component: 'agent',
+        provider,
+        model: model ?? 'default',
+        quiet: options.quiet ?? false,
+        metaTools: options.enableMetaTools ?? false,
+        projectName: options.projectName,
+    }, 'Creating agent');
     // ── Create agent via SDK ──────────────────────────────────────────────────
     const compilrAgent = createCompilrAgent({
         provider,
@@ -236,7 +297,7 @@ export function createAgent(options = {}) {
             }
             : undefined,
         // Capability loading (replaces CLI's manual meta-tools wiring)
-        // Platform tools (DB, factory) + MCP tools are passed as additionalTools
+        // Platform tools (DB, factory) + MCP + guide + plan mode tools
         capabilities: (options.enableMetaTools && !options.minimal && !options.noTools)
             ? {
                 enabled: true,
@@ -245,6 +306,8 @@ export function createAgent(options = {}) {
                     ...allDbTools,
                     ...allFactoryTools,
                     ...(options.mcpTools ?? []),
+                    cliGuideTool,
+                    ...buildPlanModeTools(options.planModeCallbacks),
                 ],
             }
             : {
@@ -253,6 +316,8 @@ export function createAgent(options = {}) {
                     ...allDbTools,
                     ...allFactoryTools,
                     ...(options.mcpTools ?? []),
+                    cliGuideTool,
+                    ...buildPlanModeTools(options.planModeCallbacks),
                 ],
             },
         // CLI-specific hooks

package/dist/commands-v2/handlers/index.js

@@ -11,7 +11,7 @@ import { debugCommands } from './debug.js';
 import { sessionCommands } from './session.js';
 import { resetCommands } from './reset.js';
 import { teamCommands } from './team.js';
-import { gamesCommand } from './games.js';
+// import { gamesCommand } from './games.js'; // Temporarily disabled — Tetris copyright concerns
 import { tasksCommand } from './tasks.js';
 import { backgroundCommands } from './background.js';
 import { filterCommands } from './filter.js';
@@ -50,7 +50,7 @@ export const allCommands = [
     ...sessionCommands,
     ...resetCommands,
     ...teamCommands,
-    gamesCommand,
+    // gamesCommand, // Temporarily disabled — Tetris copyright concerns
     tasksCommand,
     ...backgroundCommands,
     ...filterCommands,

package/dist/commands-v2/handlers/project.d.ts

@@ -19,4 +19,5 @@ export declare const scaffoldCommand: CommandHandlerV2;
 export declare const archCommand: CommandHandlerV2;
 export declare const docsCommand: CommandHandlerV2;
 export declare const projectsCommand: CommandHandlerV2;
+export declare const appCommand: CommandHandlerV2;
 export declare const projectCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/project.js

@@ -4,7 +4,7 @@
  * Commands for project management: init, backlog, workflow, anchors, design, sketch, refine
  */
 import { executeCommand } from '../registry.js';
-import { BacklogOverlayV2, WorkflowOverlayV2, DocsOverlayV2, DocumentDetailOverlayV2, AnchorsOverlayV2, ProjectsOverlayV2, NewProjectOverlayV2, OnboardingWizardOverlayV2, KeysOverlayV2, ArchTypeOverlayV2, ModelWarningOverlayV2 } from '../../ui/overlay/index.js';
+import { BacklogOverlayV2, WorkflowOverlayV2, DocsOverlayV2, DocumentDetailOverlayV2, AnchorsOverlayV2, ProjectsOverlayV2, NewProjectOverlayV2, OnboardingWizardOverlayV2, KeysOverlayV2, ArchTypeOverlayV2, ModelWarningOverlayV2, AppModelOverlayV2 } from '../../ui/overlay/index.js';
 import { projectRepository, workItemRepository, documentRepository } from '../../db/repositories/index.js';
 import { setCurrentProject, getCurrentProject } from '../../tools/project-db.js';
 import { getSkillPrompt } from '../../repl-helpers.js';
@@ -85,7 +85,7 @@ export const newCommand = {
                     display_name: displayName,
                     description: result.description,
                     path: result.projectPath,
-                    type: 'general',
+                    type: 'general', // TODO: wizard should let user pick project type (web/cli/library/api/research/etc.)
                     workflow_mode: result.workflowMode ?? 'flexible',
                     git_remote: result.gitRemote,
                     // For imports, include detected language and framework
@@ -1120,6 +1120,39 @@ export const projectsCommand = {
     },
 };
 // =============================================================================
+// App Model Command
+// =============================================================================
+export const appCommand = {
+    name: 'app',
+    description: 'View the application model (entities, relationships, features)',
+    details: 'Opens an interactive overlay showing the ApplicationModel for the current project. Browse entities with their fields and relationships, see the relationship map, and review model summary stats.',
+    examples: [{ code: '/app' }],
+    interactions: [
+        'Tab cycles: Entities → Relationships → Summary',
+        '↑/↓ to navigate, Enter for entity detail',
+        '/ to search, q/Esc to close',
+    ],
+    async execute(_args, ctx) {
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'warning', message: 'No active project. Use /new or /projects first.' });
+            return true;
+        }
+        // Load app model from document store
+        const appModelDoc = documentRepository.getByType(currentProject.id, 'app-model');
+        if (!appModelDoc) {
+            ctx.ui.print({ type: 'warning', message: 'No application model found for this project.' });
+            return true;
+        }
+        const overlay = new AppModelOverlayV2({
+            modelJson: appModelDoc.content,
+            projectName: currentProject.displayName,
+        });
+        await ctx.ui.showOverlay(overlay);
+        return true;
+    },
+};
+// =============================================================================
 // Export All Project Commands
 // =============================================================================
 export const projectCommands = [
@@ -1138,4 +1171,5 @@ export const projectCommands = [
     archCommand,
     docsCommand,
     projectsCommand,
+    appCommand,
 ];

package/dist/commands-v2/handlers/team.js

@@ -10,6 +10,7 @@ import { ArtifactOverlayV2, ArtifactDetailOverlayV2 } from '../../ui/overlay/ind
 import { ROLE_METADATA, PREDEFINED_ROLE_IDS } from '../../multi-agent/index.js';
 import { loadCustomAgents, createCustomAgentDefinition, addCustomAgent, removeCustomAgent, } from '../../multi-agent/custom-agents.js';
 import { getCurrentProject } from '../../tools/project-db.js';
+import { listTemplates, saveTemplate } from '@compilr-dev/sdk';
 import { getSessionRegistry } from '../../multi-agent/session-registry.js';
 import { saveCurrentTeam, saveCurrentSession } from './session.js';
 // =============================================================================
@@ -291,19 +292,38 @@ async function handleCreateCustomAgent(ctx, team) {
     // Load existing custom agents for duplicate check
     const existingCustomAgents = loadCustomAgents(projectPath);
     const teamAgentIds = team.getAgentIds();
-    // Show custom agent form
+    // Load templates for pre-population
+    const templates = listTemplates();
+    // Show custom agent form (with template support)
     const formOverlay = new CustomAgentFormOverlayV2({
         existingCustomAgents,
         teamAgentIds,
+        templates: templates.length > 0 ? templates : undefined,
     });
     const formResult = await ctx.ui.showOverlay(formOverlay);
     // User cancelled
     if (!formResult || formResult.cancelled || !formResult.agent) {
         return;
     }
-    // Create the custom agent definition
+    // Save as template if user chose to
     const agentData = formResult.agent;
-    const agentDef = createCustomAgentDefinition(agentData.id, agentData.displayName, agentData.specialty, agentData.personality, existingCustomAgents, agentData.toolConfig, agentData.enabledSkills, agentData.modelTier);
+    if (formResult.saveAsTemplate) {
+        saveTemplate(formResult.saveAsTemplate, {
+            id: agentData.id,
+            displayName: agentData.displayName,
+            specialty: agentData.specialty,
+            personality: agentData.personality,
+            systemPromptAddition: agentData.systemPromptAddition,
+            mascot: '',
+            createdAt: new Date().toISOString(),
+            toolConfig: agentData.toolConfig,
+            enabledSkills: agentData.enabledSkills,
+            modelTier: agentData.modelTier,
+        });
+        ctx.ui.print({ type: 'success', message: `Template "${formResult.saveAsTemplate}" saved.` });
+    }
+    // Create the custom agent definition
+    const agentDef = createCustomAgentDefinition(agentData.id, agentData.displayName, agentData.specialty, agentData.personality, existingCustomAgents, agentData.toolConfig, agentData.enabledSkills, agentData.modelTier, agentData.systemPromptAddition);
     // Save to project
     try {
         addCustomAgent(projectPath, agentDef);

package/dist/entitlements/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * EntitlementService — Server-driven tier management for the CLI.
+ *
+ * Wraps the SDK's EntitlementCache with CLI-specific concerns:
+ * - Fetches from compilr.dev backend using the user's API token
+ * - Uses encrypted file for offline backup
+ * - Warms cache on startup
+ */
+import { EntitlementCache } from '@compilr-dev/sdk';
+import { DailyCounter } from '@compilr-dev/sdk';
+/** Daily message counter — tracks agent LLM calls per day */
+export declare const dailyMessageCounter: DailyCounter;
+/** Daily conversation counter */
+export declare const dailyConversationCounter: DailyCounter;
+/**
+ * Get or create the entitlement cache singleton.
+ * @param getToken — async function that returns the current auth token
+ */
+export declare function getEntitlementCache(getToken: () => Promise<string>): EntitlementCache;
+/**
+ * Warm the cache on startup. Non-blocking — logs but doesn't throw.
+ */
+export declare function warmEntitlementCache(getToken: () => Promise<string>): Promise<void>;

package/dist/entitlements/index.js

@@ -0,0 +1,110 @@
+/**
+ * EntitlementService — Server-driven tier management for the CLI.
+ *
+ * Wraps the SDK's EntitlementCache with CLI-specific concerns:
+ * - Fetches from compilr.dev backend using the user's API token
+ * - Uses encrypted file for offline backup
+ * - Warms cache on startup
+ */
+import { EntitlementCache } from '@compilr-dev/sdk';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createCipheriv, createDecipheriv, randomBytes, createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+// ─── Encrypted File Store ───────────────────────────────────────────────────
+function getEntitlementPath() {
+    return join(homedir(), '.compilr-dev', 'entitlements.enc');
+}
+/**
+ * Derive a machine-specific encryption key from hostname + username.
+ * Not cryptographically strong against targeted attacks, but prevents
+ * casual file copying between machines.
+ */
+function deriveKey() {
+    const material = `compilr-entitlements:${homedir()}:${String(process.pid)}`;
+    return createHash('sha256').update(material).digest();
+}
+const cliStore = {
+    save(data) {
+        try {
+            const dir = join(homedir(), '.compilr-dev');
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            const key = deriveKey();
+            const iv = randomBytes(16);
+            const cipher = createCipheriv('aes-256-cbc', key, iv);
+            const encrypted = Buffer.concat([cipher.update(data, 'utf-8'), cipher.final()]);
+            const payload = Buffer.concat([iv, encrypted]);
+            writeFileSync(getEntitlementPath(), payload);
+        }
+        catch {
+            // Best effort — don't crash on write failure
+        }
+        return Promise.resolve();
+    },
+    load() {
+        const path = getEntitlementPath();
+        if (!existsSync(path))
+            return Promise.resolve(null);
+        try {
+            const payload = readFileSync(path);
+            const iv = payload.subarray(0, 16);
+            const encrypted = payload.subarray(16);
+            const key = deriveKey();
+            const decipher = createDecipheriv('aes-256-cbc', key, iv);
+            const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+            return Promise.resolve(decrypted.toString('utf-8'));
+        }
+        catch {
+            return Promise.resolve(null);
+        }
+    },
+};
+// ─── Fetch Function ─────────────────────────────────────────────────────────
+async function fetchEntitlements(getToken) {
+    const token = await getToken();
+    const apiUrl = process.env['COMPILR_API_URL'] ?? 'https://compilr.dev/.netlify/functions';
+    const resp = await fetch(`${apiUrl}/cli-entitlements`, {
+        method: 'GET',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+    });
+    if (!resp.ok) {
+        throw new Error(`Entitlements fetch failed: ${String(resp.status)}`);
+    }
+    return await resp.json();
+}
+// ─── Singleton ──────────────────────────────────────────────────────────────
+import { DailyCounter } from '@compilr-dev/sdk';
+let cacheInstance = null;
+/** Daily message counter — tracks agent LLM calls per day */
+export const dailyMessageCounter = new DailyCounter();
+/** Daily conversation counter */
+export const dailyConversationCounter = new DailyCounter();
+/**
+ * Get or create the entitlement cache singleton.
+ * @param getToken — async function that returns the current auth token
+ */
+export function getEntitlementCache(getToken) {
+    if (!cacheInstance) {
+        cacheInstance = new EntitlementCache({
+            fetchFn: () => fetchEntitlements(getToken),
+            store: cliStore,
+        });
+    }
+    return cacheInstance;
+}
+/**
+ * Warm the cache on startup. Non-blocking — logs but doesn't throw.
+ */
+export async function warmEntitlementCache(getToken) {
+    try {
+        const cache = getEntitlementCache(getToken);
+        await cache.get();
+    }
+    catch {
+        // Not critical — will retry on next access
+    }
+}

package/dist/guide/cli-guide-entries.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI-Specific Guide Entries
+ *
+ * These entries are only relevant for the CLI environment.
+ * Combined with SDK shared content via createGuideTool({ additionalEntries }).
+ *
+ * The shared-content.ts file is still used by the /tutorial overlay (CLI UI).
+ * This file converts those topics + CLI-only entries for the SDK guide tool.
+ */
+import type { GuideEntry } from '@compilr-dev/sdk';
+/**
+ * All CLI-specific guide entries.
+ * Includes CLI-only topics + converted shared-content topics (used by /tutorial).
+ */
+export declare const CLI_GUIDE_ENTRIES: GuideEntry[];

package/dist/guide/cli-guide-entries.js

@@ -0,0 +1,99 @@
+/**
+ * CLI-Specific Guide Entries
+ *
+ * These entries are only relevant for the CLI environment.
+ * Combined with SDK shared content via createGuideTool({ additionalEntries }).
+ *
+ * The shared-content.ts file is still used by the /tutorial overlay (CLI UI).
+ * This file converts those topics + CLI-only entries for the SDK guide tool.
+ */
+import { topicToGuideEntry } from '@compilr-dev/sdk';
+import { CONTENT_TOPICS } from './shared-content.js';
+// =============================================================================
+// CLI-Only Entries (not in shared SDK content, not in tutorials)
+// =============================================================================
+const CLI_ONLY_ENTRIES = [
+    {
+        id: 'cli-overview',
+        title: 'Compilr Dev CLI Overview',
+        keywords: ['overview', 'what is', 'introduction', 'about', 'compilr', 'cli'],
+        content: `Compilr Dev CLI is an AI-powered coding assistant for your terminal.
+
+Key features:
+- Multi-LLM support (Claude, OpenAI, Gemini, Ollama)
+- Project management with structured workflows
+- Requirements gathering with /design command
+- Backlog tracking with /backlog command
+- Team agents for specialized assistance ($arch, $pm, $qa, etc.)
+- Session persistence and context management
+- Image support (paste screenshots into chat)
+
+The CLI has two main interfaces:
+1. Dashboard — A menu-based interface for project management
+2. REPL — A command-line interface for chatting with the AI
+
+Run "compilr" to start. Use /help to see all commands.`,
+    },
+    {
+        id: 'workflow-modes',
+        title: 'Workflow',
+        keywords: ['workflow', 'flexible', 'mode'],
+        content: `The agent works in flexible mode — it responds to your requests and adapts to your workflow.
+
+The agent checks your project state and suggests next steps:
+- Does the project have a PRD? If not, suggests /design
+- Are there backlog items? Suggests /build
+- Is architecture documented? Suggests /arch
+
+Use /workflow to see project status and recommended next actions.`,
+    },
+    {
+        id: 'workflow-recommended',
+        title: 'Recommended Workflow',
+        keywords: ['workflow', 'how to', 'best practice', 'process'],
+        content: `Recommended workflow for new projects:
+
+1. Create project with /new — choose tech stack, set up git
+2. Plan with /design — describe what you want, AI generates PRD + backlog
+3. Review backlog with /backlog — prioritize tasks
+4. Build features — "Build REQ-001: User authentication"
+5. Manage context — /compact when context fills up, /anchors for decisions, /resume to continue later`,
+    },
+    {
+        id: 'command-resume',
+        title: '/resume Command',
+        keywords: ['/resume', 'resume', 'session', 'continue', 'previous'],
+        content: `/resume — Continue a previous session.
+
+Sessions are auto-saved after each AI response.
+
+Navigation: j/k (up/down), / (search), Enter (resume), d (delete), q/Esc (close)
+
+Saved per session: conversation history, todo list, workflow state, token usage.
+Saved per project (not session): anchors, team agents, documents.`,
+    },
+    {
+        id: 'command-team',
+        title: '/team Command',
+        keywords: ['/team', 'team', 'agents', 'manage'],
+        content: `/team — View and manage team agents.
+
+Shows all available agents with status and context usage.
+Tabs: Agents (list) | Context (token usage per agent)
+
+Switch agents: select + Enter, or use $ prefix in REPL ($arch, $pm, $qa).`,
+    },
+];
+// =============================================================================
+// Combined CLI Entries (CLI-only + shared-content topics)
+// =============================================================================
+/**
+ * All CLI-specific guide entries.
+ * Includes CLI-only topics + converted shared-content topics (used by /tutorial).
+ */
+export const CLI_GUIDE_ENTRIES = [
+    ...CLI_ONLY_ENTRIES,
+    // Convert shared ContentTopics to GuideEntries (these are CLI-specific
+    // topics like overlay navigation, REPL, dashboard, /commands)
+    ...CONTENT_TOPICS.map(topicToGuideEntry),
+];

package/dist/guide/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * Compilr Guide Module
  *
- * Provides documentation for the AI agent to answer user questions
- * about how to use the CLI.
+ * CLI-specific guide entries for the SDK's compilr_guide tool.
+ * shared-content.ts is still used by the /tutorial overlay.
  */
-export { searchGuide, getGuideTopics, guideEntries } from './guide-content.js';
-export type { GuideEntry } from './guide-content.js';
+export { CLI_GUIDE_ENTRIES } from './cli-guide-entries.js';
+export { CONTENT_TOPICS, topicToPlainText, searchContentTopics, getAllTopicIds } from './shared-content.js';
+export type { ContentTopic, ContentSection } from './shared-content.js';

package/dist/guide/index.js

@@ -1,7 +1,8 @@
 /**
  * Compilr Guide Module
  *
- * Provides documentation for the AI agent to answer user questions
- * about how to use the CLI.
+ * CLI-specific guide entries for the SDK's compilr_guide tool.
+ * shared-content.ts is still used by the /tutorial overlay.
  */
-export { searchGuide, getGuideTopics, guideEntries } from './guide-content.js';
+export { CLI_GUIDE_ENTRIES } from './cli-guide-entries.js';
+export { CONTENT_TOPICS, topicToPlainText, searchContentTopics, getAllTopicIds } from './shared-content.js';