@compilr-dev/cli 0.6.0 → 0.6.2

package/dist/guide/shared-content.js

@@ -258,9 +258,10 @@ export const CONTENT_TOPICS = [
             {
                 title: 'After /design completes:',
                 items: [
-                    'PRD is saved to the project database (via project_document_add)',
+                    'PRD is saved to the project database',
+                    'Application Model is created (entities, fields, relationships)',
                     'Work items are added to your backlog',
-                    'Use /backlog to view and prioritize items',
+                    'Use /backlog to view items, /app to view the model',
                 ],
             },
             {
@@ -429,35 +430,41 @@ export const CONTENT_TOPICS = [
     {
         id: 'command-scaffold',
         title: '/scaffold Command',
-        keywords: ['/scaffold', 'scaffold', 'project setup', 'foundation', 'boilerplate'],
+        keywords: ['/scaffold', 'scaffold', 'project setup', 'foundation', 'boilerplate', 'factory', 'generate'],
         sections: [
             {
-                items: ['/scaffold - Create the base project structure (folders, config, dependencies, initial code).'],
+                items: ['/scaffold - Generate a full project from the Application Model or create a base structure.'],
             },
             {
-                title: 'When to use:',
+                title: 'Two modes:',
                 items: [
-                    'After /design or /sketch has created your backlog',
-                    'When starting from scratch (empty project directory)',
-                    'When you need a working foundation before building features',
+                    'Factory mode: If an Application Model exists (from /design), scaffolds using the factory',
+                    'Manual mode: If no model, the agent creates structure from scratch',
                 ],
             },
             {
-                title: 'What it produces:',
+                title: 'Factory toolkits:',
                 items: [
-                    'Folder structure (src, tests, config)',
-                    'Package manager setup (package.json, dependencies)',
-                    'Configuration files (TypeScript, ESLint, etc.)',
-                    'Initial code (entry points, basic routes)',
-                    'Git commit with the scaffolded project',
+                    'react-node - React 18 + Vite + Tailwind + Express + PostgreSQL',
+                    'next-prisma - Next.js 14 App Router + Prisma ORM + Tailwind',
+                    'static-landing - HTML + Tailwind CSS landing page',
+                    'react-fastapi - React 18 + Vite + Tailwind + FastAPI (Python)',
+                    'react-go - React 18 + Vite + Tailwind + Go (net/http)',
                 ],
             },
             {
+                title: 'What factory mode produces:',
                 items: [
-                    'Requires a large model tier (Sonnet/Opus recommended).',
-                    'After scaffolding, use /build to implement features.',
+                    'Full CRUD pages for each entity (list, create, edit, detail)',
+                    'API routes and data layer',
+                    'Seed data from the model',
+                    'Navigation, dashboard, theme, auth (if enabled)',
+                    'Ready to run: npm install && npm run dev',
                 ],
             },
+            {
+                items: ['Use /app to view the Application Model before scaffolding.'],
+            },
         ],
     },
     // ===========================================================================
@@ -509,15 +516,19 @@ export const CONTENT_TOPICS = [
                 items: ['Team agents are specialized AI assistants with different expertise, tools, and model tiers.'],
             },
             {
-                title: 'Predefined roles (7):',
+                title: 'Predefined roles (11):',
                 items: [
+                    '$dev - Developer: Implementation, coding, debugging',
                     '$pm - PM: Planning, task tracking, timeline estimation',
                     '$arch - Architect: System design, patterns, tech decisions',
                     '$qa - QA Engineer: Testing, quality, code review',
-                    '$dev - Developer: Implementation, coding, debugging',
-                    '$ops - DevOps: Deployment, CI/CD, infrastructure',
-                    '$docs - Technical Writer: Documentation, guides',
-                    '$ba - Business Analyst: Requirements, metrics',
+                    '$writer - Technical Writer: Documentation, guides',
+                    '$researcher - Researcher: Literature review, analysis',
+                    '$reviewer - Reviewer: Code and content review',
+                    '$editor - Editor: Content editing, prose, structure',
+                    '$analyst - Analyst: Data and business analysis',
+                    '$strategist - Strategist: Strategy and planning',
+                    '$instructor - Instructor: Teaching, course design',
                 ],
             },
             {
@@ -1225,6 +1236,162 @@ export const CONTENT_TOPICS = [
             },
         ],
     },
+    // ===========================================================================
+    // /app Command (Application Model Viewer)
+    // ===========================================================================
+    {
+        id: 'command-app',
+        title: '/app Command',
+        keywords: ['/app', 'app', 'model', 'entities', 'fields', 'relationships', 'application model'],
+        sections: [
+            {
+                items: ['/app - View the Application Model for the current project.'],
+            },
+            {
+                title: 'Three tabs:',
+                items: [
+                    'Entities - List of all entities with field and relationship counts',
+                    'Relationships - Map of all entity relationships (hasMany/belongsTo)',
+                    'Summary - App identity, data model stats, configuration (layout, toolkit, features)',
+                ],
+            },
+            {
+                title: 'Navigation:',
+                items: [
+                    '↑/↓ - Navigate items',
+                    'Enter - View entity detail (full field table + relationship map)',
+                    'Tab or 1-3 - Switch tabs',
+                    '/ - Search',
+                    'q/Esc - Close',
+                ],
+            },
+            {
+                items: [
+                    'The Application Model is created by /design and used by /scaffold to generate code.',
+                    'The agent can also modify the model via app_model_update tool.',
+                ],
+            },
+        ],
+    },
+    // ===========================================================================
+    // Image Support
+    // ===========================================================================
+    {
+        id: 'image-support',
+        title: 'Image Support',
+        keywords: ['image', 'screenshot', 'picture', 'paste', 'attach', 'vision', 'view_image'],
+        sections: [
+            {
+                items: ['You can send images to the agent for visual analysis (screenshots, diagrams, mockups).'],
+            },
+            {
+                title: 'Supported formats:',
+                items: [
+                    'PNG, JPEG, GIF, WebP',
+                ],
+            },
+            {
+                title: 'How it works:',
+                items: [
+                    'Images are resized to max 1568px to save tokens',
+                    'After a few turns, old images are replaced with text placeholders',
+                    'The agent can also view image files on disk via the view_image tool',
+                    'All major providers support vision: Claude, GPT-4o, Gemini',
+                ],
+            },
+        ],
+    },
+    // ===========================================================================
+    // Context Management (Compressors, Observation Masking)
+    // ===========================================================================
+    {
+        id: 'context-management',
+        title: 'Context Management',
+        keywords: ['context', 'tokens', 'compressor', 'observation', 'masking', 'token saving'],
+        sections: [
+            {
+                items: ['The agent automatically manages its context window to stay within limits.'],
+            },
+            {
+                title: 'Automatic optimizations:',
+                items: [
+                    'Observation masking - Old tool results replaced with compact summaries after a few turns',
+                    'Image masking - Old images replaced with text placeholders (saves 1000+ tokens per image)',
+                    'Tool output compression - Large outputs compressed 60-90% (git, npm, file listings)',
+                    'Smart windowing - Oldest messages compacted when context fills up',
+                    'Dead message pruning - Removed permission exchanges and superseded errors',
+                ],
+            },
+            {
+                title: 'Manual controls:',
+                items: [
+                    '/context - View current token usage and breakdown',
+                    '/compact - Force summarization of old messages',
+                ],
+            },
+        ],
+    },
+    // ===========================================================================
+    // Knowledge Base
+    // ===========================================================================
+    {
+        id: 'knowledge-base',
+        title: 'Knowledge Base',
+        keywords: ['knowledge', 'kb', 'reference', 'documents', 'pin'],
+        sections: [
+            {
+                items: ['The knowledge base stores reference documents and images for your project.'],
+            },
+            {
+                title: 'Adding content:',
+                items: [
+                    'Files are added via the project_document_add tool or the desktop KB panel',
+                    'Supported: markdown, text, PDF, code files, images (PNG/JPEG/GIF/WebP)',
+                    'URLs can be imported (web page content fetched and stored)',
+                ],
+            },
+            {
+                title: 'Pinning:',
+                items: [
+                    'Pinned files are included in every agent conversation',
+                    'Unpinned files are available on-demand (agent reads them when needed)',
+                    'Pin important reference docs to keep the agent informed',
+                ],
+            },
+        ],
+    },
+    // ===========================================================================
+    // Capability Packs
+    // ===========================================================================
+    {
+        id: 'capability-packs',
+        title: 'Capability Packs',
+        keywords: ['capability', 'pack', 'tools', 'auto-load', 'dynamic', 'loading'],
+        sections: [
+            {
+                items: ['Tools are organized into capability packs that load on demand.'],
+            },
+            {
+                title: 'How it works:',
+                items: [
+                    'Only essential tools are loaded upfront (file read, shell, interaction)',
+                    'Additional packs load automatically when the agent needs them',
+                    'Reduces token cost by ~60% compared to loading all tools at once',
+                ],
+            },
+            {
+                title: 'Tool profiles control which packs are available:',
+                items: [
+                    'full - All packs (default for primary agent)',
+                    'developer - Coding-focused packs',
+                    'read-only - Safe exploration only',
+                    'planner - Planning and documentation packs',
+                    'analyst - Analysis and research packs',
+                    'docs - Documentation packs',
+                ],
+            },
+        ],
+    },
 ];
 // =============================================================================
 // Helper Functions

package/dist/handlers/permission-handler.js

@@ -27,10 +27,17 @@ export function createPermissionHandler(deps) {
         if (permissionMode === 'auto-accept') {
             return true;
         }
-        // "Plan" mode: always prompt (no auto-approval based on rules)
+        // "Plan" mode: block write/execute tools, allow read/plan tools
+        if (permissionMode === 'plan') {
+            const { isToolAllowedInPlanMode } = await import('@compilr-dev/sdk');
+            if (!isToolAllowedInPlanMode(request.toolName)) {
+                return false; // Blocked — agent gets denial in tool result
+            }
+            // Read/plan tools pass through without prompting
+            return true;
+        }
         // "Default" mode: use rule-based checking
-        // Check custom permission rules (for non-plan mode)
-        if (permissionMode !== 'plan') {
+        {
             const rule = findMatchingRule(request.toolName);
             if (rule) {
                 if (rule.level === 'always') {

package/dist/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 // Force color output for all chalk-based libraries (cli-highlight, marked-terminal, etc.)
-// This must be set BEFORE any imports that use chalk
-process.env.FORCE_COLOR = '3';
+// This must be set BEFORE any imports that use chalk.
+// Respect the NO_COLOR standard (https://no-color.org) — never override an explicit user opt-out.
+if (!process.env.NO_COLOR) {
+    process.env.FORCE_COLOR = '3';
+}
 /**
  * @compilr-dev/cli
  *
@@ -560,6 +563,19 @@ async function main() {
         // MCP tools injected later via agent.registerTools() when background init completes
         // Episode recorder for work history tracking
         episodeRecorder: defaultEpisodeRecorder,
+        // Plan mode callbacks — wired to ReplV2's handlePlanApproval
+        planModeCallbacks: {
+            onPlanSubmit: async (info) => {
+                // Delegate to ReplV2's existing plan approval flow
+                if (sharedState.onPlanSubmit)
+                    return sharedState.onPlanSubmit(info);
+                return { action: 'reject' }; // Fallback if repl not ready
+            },
+            onPlanModeExit: async (info) => {
+                if (sharedState.onPlanModeExit)
+                    return sharedState.onPlanModeExit(info);
+            },
+        },
     });
     perf('create-agent-done');
     // Mutable ref so grantSession and onDefaultAgentSwapped closures track the current default agent
@@ -731,6 +747,11 @@ async function main() {
         onBackgroundDelegationReady: (runDelegation) => {
             sharedState.runBackgroundDelegation = runDelegation;
         },
+        // Plan mode: wire approval and exit callbacks to ReplV2
+        onPlanModeReady: (callbacks) => {
+            sharedState.onPlanSubmit = callbacks.onPlanSubmit;
+            sharedState.onPlanModeExit = callbacks.onPlanModeExit;
+        },
         // Update sharedState.team when session restore replaces the team object
         // (so delegation handlers see restored agents, not just 'default')
         onTeamReplaced: (newTeam) => {

package/dist/repl-v2.d.ts

@@ -149,6 +149,21 @@ export interface ReplV2Options {
      * Phase 3d-beta: Coordinator Mode
      */
     onBackgroundDelegationReady?: (runDelegation: (agentId: string, message: string) => 'running' | 'queued' | null) => void;
+    /**
+     * Plan mode: wire plan_submit and plan_mode_exit callbacks to the approval overlay.
+     */
+    onPlanModeReady?: (callbacks: {
+        onPlanSubmit: (info: {
+            planId: number;
+            summary?: string;
+        }) => Promise<{
+            action: 'approve-auto' | 'approve' | 'revise' | 'reject';
+            feedback?: string;
+        }>;
+        onPlanModeExit: (info: {
+            reason: string;
+        }) => Promise<void>;
+    }) => void;
     /**
      * Callback invoked when terminal session is registered.
      * Passes the session ID so index.ts can set sessionPrefix for IPC.
@@ -234,6 +249,7 @@ export declare class ReplV2 {
     private readonly onPendingDelegation?;
     private readonly onBackgroundAgentReady?;
     private readonly onBackgroundDelegationReady?;
+    private readonly onPlanModeReady?;
     private readonly onSessionRegistered?;
     private readonly onTeamReplaced?;
     private readonly onProjectStateUpdate?;

package/dist/repl-v2.js

@@ -31,7 +31,7 @@ import { renderMascotWithLogo } from './ui/mascot/renderer.js';
 import { getStartupHighlights } from './changelog/index.js';
 import { registerCommands, executeCommand, allCommands, getAutocompleteCommands, saveCurrentSession, saveCurrentTeam, loadProjectSession, archiveCurrentSession, convertMessagesToItems, } from './commands-v2/index.js';
 import { getCustomCommandRegistry } from './commands/custom-registry.js';
-import { getPlanModePrompt } from './prompts/plan-mode-prompt.js';
+import { getPlanModePrompt } from '@compilr-dev/sdk';
 import { planRepository } from './db/repositories/index.js';
 import { PlanApprovalOverlayV2, } from './ui/overlay/impl/plan-approval-overlay-v2.js';
 import { PermissionOverlayV2, } from './ui/overlay/impl/permission-overlay-v2.js';
@@ -197,6 +197,7 @@ export class ReplV2 {
     onPendingDelegation;
     onBackgroundAgentReady;
     onBackgroundDelegationReady;
+    onPlanModeReady;
     onSessionRegistered;
     onTeamReplaced;
     onProjectStateUpdate;
@@ -245,6 +246,7 @@ export class ReplV2 {
         this.onPendingDelegation = options.onPendingDelegation;
         this.onBackgroundAgentReady = options.onBackgroundAgentReady;
         this.onBackgroundDelegationReady = options.onBackgroundDelegationReady;
+        this.onPlanModeReady = options.onPlanModeReady;
         this.onSessionRegistered = options.onSessionRegistered;
         this.onTeamReplaced = options.onTeamReplaced;
         this.onProjectStateUpdate = options.onProjectStateUpdate;
@@ -987,6 +989,26 @@ export class ReplV2 {
                 return 'running';
             });
         }
+        // Plan mode: wire plan_submit and plan_mode_exit to handlePlanApproval
+        if (this.onPlanModeReady) {
+            this.onPlanModeReady({
+                onPlanSubmit: async (info) => {
+                    await this.handlePlanApproval(info.planId, info.summary ?? 'Plan');
+                    // Map the internal action to PlanSubmitResult
+                    // handlePlanApproval already updates DB and mode — return a simplified result
+                    const mode = this.ui.getMode();
+                    if (mode === 'auto-accept')
+                        return { action: 'approve-auto' };
+                    return { action: 'approve' };
+                },
+                onPlanModeExit: (info) => {
+                    this.ui.setMode('normal');
+                    this.ui.clearActivePlan();
+                    this.ui.print({ type: 'info', message: `Agent exited plan mode: ${info.reason}` });
+                    return Promise.resolve();
+                },
+            });
+        }
         // Event handlers
         this.ui.on('submit', (input) => {
             void this.processInput(input);
@@ -1547,6 +1569,12 @@ export class ReplV2 {
         // Start session heartbeat in background (don't block UI)
         const auth = getAuthManager();
         void auth.startSession();
+        // Warm entitlement cache in background (non-blocking)
+        if (await auth.isAuthenticated()) {
+            import('./entitlements/index.js').then(({ warmEntitlementCache }) => {
+                void warmEntitlementCache(() => auth.getAccessToken());
+            }).catch(() => { });
+        }
         const startupMode = getStartupMode();
         if (startupMode === 'menu') {
             await this.handleCommand('menu', '');
@@ -2209,6 +2237,25 @@ export class ReplV2 {
     async runAgentReal(userMessage) {
         if (!this.agent)
             return;
+        // Entitlement check: daily message limit
+        try {
+            const { dailyMessageCounter, getEntitlementCache } = await import('./entitlements/index.js');
+            const auth = (await import('./auth/index.js')).getAuthManager();
+            if (await auth.isAuthenticated()) {
+                const cache = getEntitlementCache(() => auth.getAccessToken());
+                const msgCount = dailyMessageCounter.increment();
+                const check = cache.checkLimit('maxAgentMessagesPerDay', msgCount);
+                if (!check.allowed) {
+                    const { formatTimeUntilReset } = await import('@compilr-dev/sdk');
+                    this.ui.print({
+                        type: 'warning',
+                        message: `Daily message limit reached (${String(check.current)}/${String(check.limit)}). ${formatTimeUntilReset()}.`,
+                    });
+                    return;
+                }
+            }
+        }
+        catch { /* allow if entitlements unavailable */ }
         const abortController = new AbortController();
         const signal = abortController.signal;
         const setAction = (action) => {
@@ -2252,7 +2299,7 @@ export class ReplV2 {
                     let messageToSend = userMessage;
                     if (this.ui.getMode() === 'plan') {
                         const activePlan = this.ui.getActivePlan();
-                        const planModePrompt = getPlanModePrompt(activePlan.id ?? undefined, activePlan.name ?? undefined);
+                        const planModePrompt = getPlanModePrompt(activePlan.id && activePlan.name ? { id: activePlan.id, name: activePlan.name } : undefined);
                         messageToSend = `${planModePrompt}\n\n---\n\nUser request: ${userMessage}`;
                     }
                     // Inject delegation completion notifications (deferred delivery)
@@ -2687,22 +2734,9 @@ export class ReplV2 {
                             });
                         }
                     }
-                    // Flush remaining text and check for PLAN_READY marker
+                    // Flush remaining text (PLAN_READY marker detection removed — plan_submit tool handles approval)
                     if (this.textAccumulator.trim()) {
-                        const text = this.textAccumulator.trim();
-                        // Check for PLAN_READY marker
-                        const planReadyInfo = this.detectPlanReady(text);
-                        // Print the text (remove the marker from display if present)
-                        const displayText = planReadyInfo
-                            ? text.replace(ReplV2.PLAN_READY_REGEX, '').trim()
-                            : text;
-                        if (displayText) {
-                            this.ui.print({ type: 'agent-text', text: displayText, expression: this.getActiveAgentMascot(), agentId: activeAgentId });
-                        }
-                        // If PLAN_READY marker found, show approval overlay
-                        if (planReadyInfo) {
-                            await this.handlePlanApproval(planReadyInfo.planId, planReadyInfo.planName);
-                        }
+                        this.ui.print({ type: 'agent-text', text: this.textAccumulator.trim(), expression: this.getActiveAgentMascot(), agentId: activeAgentId });
                     }
                     // Print per-turn summary before stopping agent
                     this.printTurnSummary();

package/dist/tools/db-tools.d.ts

@@ -10,7 +10,7 @@ export { getActiveProject, setActiveProject } from './project-db.js';
 /**
  * All database tools combined (32 tools from SDK)
  */
-export declare const allDbTools: import("@compilr-dev/sdk").Tool<never>[];
+export declare const allDbTools: import("@compilr-dev/agents").Tool<never>[];
 /**
  * All factory tools (5 tools from @compilr-dev/factory)
  */

package/dist/tools/platform-adapter.d.ts

@@ -22,4 +22,4 @@ export declare const allPlatformTools: import("@compilr-dev/sdk").Tool<never>[];
  * - 3 model tools (app_model_get, app_model_update, app_model_validate)
  * - 2 factory tools (factory_scaffold, factory_list_toolkits)
  */
-export declare const allFactoryTools: import("@compilr-dev/agents").Tool<never>[];
+export declare const allFactoryTools: import('@compilr-dev/agents').Tool<never>[];

package/dist/tools/platform-adapter.js

@@ -9,6 +9,7 @@ import { createPlatformTools, createSQLiteRepositories, ProjectAnchorStore, } fr
 import { createFactoryTools } from '@compilr-dev/factory';
 import { getDb } from '../db/index.js';
 import { getDataPath, getSessionsPath } from '../settings/paths.js';
+import { getPermissionMode } from '../settings/index.js';
 import { existsSync, rmSync } from 'fs';
 import { join } from 'path';
 import { getCurrentProject, setCurrentProject } from './project-db.js';
@@ -273,7 +274,11 @@ const config = {
  * - 4 artifact tools (artifact_save, artifact_get, artifact_list, artifact_delete)
  * - 1 episode tool (recall_work)
  */
-export const allPlatformTools = createPlatformTools(config);
+export const allPlatformTools = createPlatformTools(config, {
+    planModeCallbacks: {
+        isPlanModeActive: () => getPermissionMode() === 'plan',
+    },
+});
 /**
  * All 5 factory tools from @compilr-dev/factory:
  * - 3 model tools (app_model_get, app_model_update, app_model_validate)

package/dist/tools.js

@@ -125,7 +125,12 @@ import { delegateTool } from './tools/delegate.js';
 import { delegateBackgroundTool } from './tools/delegate-background.js';
 import { delegationStatusTool } from './tools/delegation-status.js';
 import { handoffTool } from './tools/handoff.js';
-import { guideTool } from './tools/guide-tool.js';
+import { createGuideTool } from '@compilr-dev/sdk';
+import { CLI_GUIDE_ENTRIES } from './guide/cli-guide-entries.js';
+const guideTool = createGuideTool({
+    environment: 'cli',
+    additionalEntries: CLI_GUIDE_ENTRIES,
+});
 // DB tools for project, work item, document, plan, backlog, anchor, artifact, and episode management
 import { allDbTools, allFactoryTools } from './tools/db-tools.js';
 // Meta-tools for dynamic tool loading

package/dist/ui/overlay/impl/app-model-overlay-v2.d.ts

@@ -0,0 +1,57 @@
+/**
+ * App Model Overlay V2
+ *
+ * Terminal visualization of the ApplicationModel (from @compilr-dev/factory).
+ * Three tabs: Entities (list with detail), Relationships (map), Summary (stats).
+ *
+ * Not a replacement for the desktop SVG viewer — text-based tables and lists
+ * for CLI users who want to inspect the model structure.
+ */
+import { TabbedListOverlayV2, BaseScreen } from '../../base/index.js';
+interface ModelField {
+    name: string;
+    label: string;
+    type: string;
+    required: boolean;
+    enumValues?: readonly string[];
+    defaultValue?: string | number | boolean;
+}
+interface ModelRelationship {
+    type: 'belongsTo' | 'hasMany';
+    target: string;
+    fieldName?: string;
+}
+interface ModelEntity {
+    name: string;
+    pluralName: string;
+    description?: string;
+    icon: string;
+    fields: readonly ModelField[];
+    views: readonly string[];
+    relationships: readonly ModelRelationship[];
+}
+export interface AppModelOverlayV2Options {
+    /** Raw JSON content from the document store */
+    modelJson: string;
+    /** Project display name */
+    projectName: string;
+}
+export interface AppModelOverlayV2Result {
+    dismissed: boolean;
+}
+interface ModelListItem {
+    id: string;
+    tab: string;
+    label: string;
+    detail: string;
+    entity?: ModelEntity;
+}
+export declare class AppModelOverlayV2 extends TabbedListOverlayV2<ModelListItem, AppModelOverlayV2Result> {
+    readonly type: "inline";
+    readonly id = "app-model-viewer";
+    private readonly model;
+    private readonly parseError;
+    constructor(options: AppModelOverlayV2Options);
+    protected createDetailScreen(item: ModelListItem): BaseScreen | null;
+}
+export {};