@compilr-dev/sdk 0.9.7 → 0.9.9

package/dist/guide/shared-content.js

@@ -0,0 +1,267 @@
+/**
+ * Shared Guide Content — environment-agnostic topics.
+ *
+ * These apply to both CLI and Desktop. Each entry describes a feature
+ * that works the same way regardless of the host application.
+ */
+export const SHARED_GUIDE_ENTRIES = [
+    // ── Projects ────────────────────────────────────────────────────────────
+    {
+        id: 'creating-project',
+        title: 'Creating a New Project',
+        keywords: ['create', 'new', 'project', 'start'],
+        content: `To create a new project, use the project creation flow.
+
+You'll specify:
+- Project name and display name
+- Project type (software, research, book, business-plan, etc.)
+- Project path (where files live on disk)
+
+After creation, the project is set as active and agents can start working in it.
+
+7 project types are available:
+- software — Full-stack web apps, APIs, libraries
+- research — Academic papers, literature reviews
+- book — Books, chapters, outlines
+- course — Courses, curricula, lessons
+- business-plan — Business plans, pitch decks, financials
+- content-marketing — Content calendars, articles
+- tech-docs — Documentation, API references, tutorials`,
+    },
+    {
+        id: 'project-types',
+        title: 'Project Types',
+        keywords: [
+            'project type',
+            'software',
+            'research',
+            'book',
+            'business',
+            'course',
+            'content',
+            'tech-docs',
+        ],
+        content: `Each project type determines which agent roles, skills, and tools are most relevant:
+
+**software** — Agent roles: dev, pm, qa, arch. Skills: /design, /prd, /architecture, /scaffold, /build
+**research** — Agent roles: researcher, reviewer, writer. Skills: /outline, /literature-review, /methodology, /abstract
+**book** — Agent roles: editor, writer, reviewer. Skills: /outline, /chapter
+**course** — Agent roles: instructor, writer, reviewer. Skills: /outline, /lesson
+**business-plan** — Agent roles: analyst, strategist, writer. Skills: /business-vision, /market-analysis, /financial-model, /pitch
+**content-marketing** — Agent roles: writer, editor, strategist. Skills: /editorial-calendar, /article
+**tech-docs** — Agent roles: writer, dev, reviewer. Skills: /getting-started, /api-reference, /tutorial
+
+All project types support: teams, backlog, documents, knowledge base, file references, anchors.`,
+    },
+    {
+        id: 'importing-project',
+        title: 'Importing an Existing Project',
+        keywords: ['import', 'existing', 'project', 'folder'],
+        content: `You can import an existing project directory. The system will:
+1. Detect the project type from its contents
+2. Create a project entry in the database
+3. Read COMPILR.md if present (project context for the agent)
+4. Set it as the active project
+
+The agent then has context about your project and can help immediately.`,
+    },
+    {
+        id: 'switching-projects',
+        title: 'Switching Projects',
+        keywords: ['switch', 'change', 'project', 'select'],
+        content: `You can switch between projects at any time. When you switch:
+- The active project changes
+- Agents get the new project's context (COMPILR.md, anchors, KB)
+- Existing conversations are preserved (per-project)`,
+    },
+    // ── Teams & Agents ──────────────────────────────────────────────────────
+    {
+        id: 'team-agents',
+        title: 'Team Agents',
+        keywords: ['team', 'agents', '$agent', 'mention', 'role', 'specialist'],
+        content: `Team agents are specialized AI assistants with different roles and expertise.
+
+Use $agent to mention an agent (e.g., "$arch review this design", "$qa write tests").
+
+Available roles:
+- $dev — Software developer (coding, debugging)
+- $pm — Product manager (requirements, priorities)
+- $qa — QA engineer (testing, quality)
+- $arch — Architect (design, patterns, decisions)
+- $writer — Technical writer (docs, README)
+- $researcher — Research assistant (literature, analysis)
+- $reviewer — Code/content reviewer
+- $editor — Content editor (prose, structure)
+- $analyst — Data/business analyst
+- $strategist — Strategy and planning
+- $instructor — Teaching and course design
+
+Each role has a tailored system prompt and tool set.`,
+    },
+    {
+        id: 'coordinator-mode',
+        title: 'Coordinator Mode',
+        keywords: ['coordinator', 'delegation', 'delegate', 'background', 'multi-agent'],
+        content: `Coordinator mode allows one agent to delegate tasks to others.
+
+The coordinator can:
+- delegate_background: Send a task to another agent to run in background
+- delegation_status: Check on running delegations
+- Receive results when delegated tasks complete
+
+Useful for: code review ($qa), documentation ($writer), architecture analysis ($arch).
+
+The delegated agent runs independently and returns results to the coordinator.`,
+    },
+    // ── Skills ──────────────────────────────────────────────────────────────
+    {
+        id: 'skills-overview',
+        title: 'Skills Overview',
+        keywords: ['skills', 'slash', 'command', '/'],
+        content: `Skills are pre-built prompts that guide the agent through specific workflows.
+
+Use them by typing / followed by the skill name (e.g., /design, /build).
+
+Skills vary by project type. Software projects have: /design, /prd, /architecture, /scaffold, /build, /backlog, /session-notes.
+
+Research projects have: /outline, /literature-review, /methodology, /abstract.
+
+Business projects have: /business-vision, /market-analysis, /financial-model, /pitch.
+
+Skills can be combined with your own instructions: type /design then add context.`,
+    },
+    // ── Models & Providers ──────────────────────────────────────────────────
+    {
+        id: 'models',
+        title: 'Models and Providers',
+        keywords: ['model', 'provider', 'claude', 'openai', 'gemini', 'ollama', 'llm'],
+        content: `Compilr Dev supports multiple LLM providers:
+
+- Claude (Anthropic) — Claude Opus, Sonnet, Haiku
+- OpenAI — GPT-4o, GPT-4o-mini
+- Gemini (Google) — Gemini 2.5 Pro, Flash
+- Ollama — Local models (llama, codellama, etc.)
+- Together, Groq, Fireworks, Perplexity, OpenRouter
+
+Each provider requires an API key (except Ollama which runs locally).
+Models are organized by tier: premium, balanced, fast.`,
+    },
+    // ── Context & Memory ────────────────────────────────────────────────────
+    {
+        id: 'file-references',
+        title: 'File References (@file)',
+        keywords: ['file', 'reference', '@', 'attach', 'mention'],
+        content: `Reference files in your messages with @filename.
+
+Examples:
+  @src/index.ts — Agent reads this file for context
+  @package.json — Agent checks dependencies
+
+The agent will use its tools to read the referenced files.`,
+    },
+    {
+        id: 'compilr-md',
+        title: 'COMPILR.md — Project Context',
+        keywords: ['compilr.md', 'context', 'project', 'instructions'],
+        content: `COMPILR.md is a markdown file in your project root that gives the agent context.
+
+It can include:
+- Project description and goals
+- Tech stack and dependencies
+- Coding conventions
+- Build/test commands
+- Important file locations
+
+The agent reads this on every conversation to understand your project.
+Create one manually or let the agent generate it.`,
+    },
+    {
+        id: 'knowledge-base',
+        title: 'Knowledge Base',
+        keywords: ['knowledge', 'kb', 'reference', 'docs', 'upload', 'pin'],
+        content: `The knowledge base stores reference documents for your project.
+
+You can add:
+- Files (code, markdown, text, PDF, images)
+- Pasted text snippets
+- URLs (web page content imported)
+
+Pin important files to include them in every agent conversation.
+Unpinned files are available on-demand (agent uses view tools).
+
+Images in the KB can be viewed by the agent using the view_image tool.`,
+    },
+    {
+        id: 'context-management',
+        title: 'Context Management',
+        keywords: ['context', 'tokens', 'compaction', 'observation', 'masking', 'window'],
+        content: `The agent manages its context window automatically:
+
+- 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 by 60-90% (git, npm, file listings)
+- Smart windowing: Oldest messages compacted when context fills up
+
+You can see context utilization in the status bar or via /context.`,
+    },
+    // ── Permissions ─────────────────────────────────────────────────────────
+    {
+        id: 'permissions',
+        title: 'Permissions',
+        keywords: ['permission', 'approve', 'deny', 'auto-accept', 'security'],
+        content: `Agents ask permission before running potentially dangerous tools.
+
+Permission modes:
+- Normal — Agent asks before bash, edit, write operations
+- Auto-accept — Automatically approve all tool calls (faster, less safe)
+
+You can set per-tool rules (always allow, always deny, always ask).
+
+In restricted mode (untrusted workspace), bash/edit/write are blocked entirely.`,
+    },
+    // ── Images ──────────────────────────────────────────────────────────────
+    {
+        id: 'image-support',
+        title: 'Image Support',
+        keywords: ['image', 'screenshot', 'picture', 'paste', 'vision', 'multimodal'],
+        content: `You can send images to agents for visual analysis.
+
+Supported formats: PNG, JPEG, GIF, WebP.
+
+Images are automatically resized to max 1568px (Claude's recommended max) to save tokens.
+After a few turns, images are replaced with text placeholders to further reduce token cost.
+
+The agent can also view image files from disk using the view_image tool.
+
+All major providers support images: Claude, OpenAI GPT-4o, Gemini.`,
+    },
+    // ── Workspace Trust ─────────────────────────────────────────────────────
+    {
+        id: 'workspace-trust',
+        title: 'Workspace Trust',
+        keywords: ['trust', 'restricted', 'security', 'untrusted', 'safe'],
+        content: `When you open a project for the first time, you're asked to trust it.
+
+Trusted projects: Full agent capabilities — bash, file editing, terminal.
+Restricted projects: Read-only — agents can read files and answer questions but cannot run commands or modify files.
+
+You can change trust status by clicking the "Restricted" badge in the status bar.
+
+Trust is inherited: if you trust /projects/myapp, all subdirectories are also trusted.`,
+    },
+    // ── Anchors ─────────────────────────────────────────────────────────────
+    {
+        id: 'anchors',
+        title: 'Anchors — Persistent Context',
+        keywords: ['anchor', 'pin', 'persistent', 'important', 'remember'],
+        content: `Anchors are persistent notes that stay in the agent's context across conversations.
+
+Use them for:
+- Architecture decisions ("We chose PostgreSQL because...")
+- Important conventions ("All API routes use camelCase")
+- Work-in-progress notes ("Auth module is half-done, don't touch")
+
+Anchors survive session restarts and project switches.
+The agent sees them in every conversation.`,
+    },
+];

package/dist/guide/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Guide types — shared across SDK, CLI, and Desktop.
+ */
+/**
+ * A single guide entry the agent can return to the user.
+ */
+export interface GuideEntry {
+    id: string;
+    title: string;
+    keywords: string[];
+    content: string;
+}
+/**
+ * Structured content topic (used for tutorials in CLI, converted to GuideEntry for the tool).
+ */
+export interface ContentSection {
+    title?: string;
+    items: string[];
+}
+export interface ContentTopic {
+    id: string;
+    title: string;
+    keywords: string[];
+    sections: ContentSection[];
+}
+/**
+ * Configuration for the guide tool factory.
+ */
+export interface GuideToolConfig {
+    /** Which environment the tool is running in */
+    environment: 'cli' | 'desktop';
+    /** Additional environment-specific content to merge with shared content */
+    additionalEntries?: GuideEntry[];
+}

package/dist/guide/types.js

@@ -0,0 +1,4 @@
+/**
+ * Guide types — shared across SDK, CLI, and Desktop.
+ */
+export {};

package/dist/index.d.ts

@@ -58,6 +58,10 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './platform/index.js';
 export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './tools/index.js';
+export { detectProject, suggestProjectType, detectCommon } from './detection/index.js';
+export type { DetectProjectOptions, DetectionResult, ContentSummary } from './detection/index.js';
+export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
+export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './guide/index.js';
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, ImageToolsConfig, ImageResizer } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';

package/dist/index.js

@@ -129,6 +129,14 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 // =============================================================================
 export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 // =============================================================================
+// Project Detection (universal project content detection)
+// =============================================================================
+export { detectProject, suggestProjectType, detectCommon } from './detection/index.js';
+// =============================================================================
+// Guide Tool (environment-aware documentation)
+// =============================================================================
+export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
+// =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",