Add AI Copilot to Your Application

This is a Claude Code skill file. To use it, paste this single prompt into Claude Code from your project directory:

Add an AI copilot to this application using the skill at https://github.com/femitfash/copilot-engine/blob/master/COPILOT_SKILL.md

Claude Code will fetch this file, save it locally, and follow the steps below.

Alternatively, copy this file manually to your project's .claude/skills/add-copilot.md and run:

Add an AI copilot to this application using the skill in .claude/skills/add-copilot.md

---

Instructions for Claude Code

You are integrating an AI Copilot into this application using the copilot-engine framework. Follow these steps exactly.

Step 0: Pre-Flight Checks

Before doing any work, verify these prerequisites. If any fail, stop and report the issue.

# 1. Node.js >= 18 (required for native fetch)
node --version

# 2. GitHub CLI installed and authenticated
gh auth status

# 3. npm available
npm --version

• If Node < 18: stop and tell the developer to install Node 18+ from https://nodejs.org
• If gh not found: stop and tell the developer to install GitHub CLI from https://cli.github.com/
• If gh auth status fails: stop and tell the developer to run gh auth login

After checks pass, display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Pre-flight checks passed ✅
  Node.js: v{version}
  GitHub CLI: authenticated as {username}
  npm: v{version}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 0.5: Detect Project Type

Scan the project directory to determine what kind of application this is. Display your findings to the developer.

Check in this order:

1. Look for wp-config.php or wp-content/ directory → WordPress detected
2. Look for package.json → read it to determine framework (Angular, React, Vue, Next.js, Express, NestJS)
3. If neither found → ask the developer what kind of project this is

Display the detection result:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Project detected: {WordPress / Angular / React / etc.}
  {additional details: WP version, framework version, etc.}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

WordPress-Specific Setup

If WordPress is detected, display and follow this flow:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🔧 WordPress Copilot Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  WordPress uses Application Passwords for API access.
  You'll need to create one in your WordPress admin:

  wp-admin → Users → Your Profile → Application Passwords

  Enter a name (e.g., "Copilot") and click "Add New".
  Copy the generated password (shown only once).
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then ask the developer for:

1. WordPress site URL (e.g., http://localhost:8080)
2. WordPress username (the admin account)
3. Application Password (the one they just created)

Set WP_API_URL in .env. The auth token is base64-encoded username:app_password.

Use projects/wordpress/ as the project template — it has 15 READ + 11 WRITE tools for content, plugins, themes, users, and site management.

The welcome prompt template uses two tabs: "WordPress" (navigation + content actions) and "Security" (scanning + hardening actions).

LLM Provider Selection

Display this choice to the developer and wait for their answer:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🤖 Choose your LLM provider:

  1. Anthropic Claude (default)
     Model: claude-sonnet-4-20250514
     Requires: ANTHROPIC_API_KEY

  2. OpenAI GPT
     Model: gpt-4.1-mini (affordable)
     Requires: OPENAI_API_KEY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If they already have an ANTHROPIC_API_KEY or OPENAI_API_KEY in their environment, detect it and display:

  Detected: ANTHROPIC_API_KEY in environment ✅
  Using Anthropic Claude as your LLM provider.

The copilot-engine repo is at: https://github.com/femitfash/copilot-engine

Optional Features

Display available features and ask the developer which to enable:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📦 Optional Features:

  [ ] security-scanner
      WordPress security scanning — vulnerability checks,
      plugin audits, SSL verification, user security,
      hardening recommendations.

      Optional: Connect Supabase for scan history & dashboard.
      Provide SUPABASE_URL + SUPABASE_ANON_KEY to enable logging.
      (Scanner works without Supabase, results just aren't saved.)

  Enable security-scanner? (y/n)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If the developer enables security-scanner:

• Ask: "Do you have a Supabase project for logging? (optional)"
• If yes: ask for SUPABASE_URL and SUPABASE_ANON_KEY
• Set COPILOT_FEATURES=security-scanner in .env
• Tables (security_scans, security_findings, security_events) are auto-created on first run
• Developer views results at their Supabase dashboard (Table Editor) or through the copilot

Deployment Mode: Built-in vs Standalone

Compatibility check — determine if built-in mode is possible:

For WordPress: WordPress is typically PHP-based without a Node.js/Express server. Default to Standalone mode unless the developer also has an Express server alongside WordPress.

For other frameworks — read the app's package.json:

1. If express is in dependencies AND a server entry file exists (server.ts, index.ts, app.ts, main.ts) → Built-in compatible
2. If @nestjs/core is in dependencies → Built-in compatible (NestJS uses Express underneath)
3. If next is in dependencies AND a custom server file exists (server.ts/server.js with Express) → Built-in compatible
4. If next is in dependencies but NO custom server → Standalone only — inform: "Your Next.js app uses the built-in server. The copilot will run as a standalone server on port 3100."
5. If no server-side framework found (frontend-only SPA) → Standalone only — inform: "Your app doesn't have a backend server. The copilot will run as a standalone server on port 3100."

If built-in is compatible, display this choice:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🏗️ Deployment Mode:

  1. Built-in
     Runs on your existing server — same port, one process.
     Simpler to manage. One `npm start` runs everything.

  2. Standalone
     Runs as its own server on port 3100.
     Better for shared/multi-app setups or full isolation.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If standalone is the only option (WordPress, SPA-only, pure Next.js), display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🏗️ Deployment Mode: Standalone
  Your project will use a separate copilot server on port 3100.
  {reason: e.g., "WordPress is PHP-based and doesn't have a Node.js server."}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If they choose Built-in, follow Path A below. If Standalone, follow Path B.

Before proceeding, display the full setup summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📋 Setup Summary

  Project:        {WordPress / Angular / React / etc.}
  LLM Provider:   {Anthropic Claude / OpenAI GPT}
  Deployment:     {Built-in / Standalone (port 3100)}
  Features:       {security-scanner / none}
  Supabase:       {Connected / Not configured}
  WP API URL:     {url}  (WordPress only)

  Proceeding with installation...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Path A — Built-in Mode

Step 1A: Fork, Clone, and Copy Engine Files

Fork and clone the copilot-engine repo (this benefits the open-source project and gives you a reference for future updates):

gh repo fork femitfash/copilot-engine --clone=false
GITHUB_USER=$(gh api user --jq .login)
cd .. && git clone "https://github.com/$GITHUB_USER/copilot-engine.git"
cd copilot-engine && git remote add upstream https://github.com/femitfash/copilot-engine.git
cd ../{app-directory}

Copy engine source files into the app's project:

mkdir -p src/copilot/engine/providers src/copilot/auth src/copilot/routes

Copy these files from copilot-engine into src/copilot/:

| Source (copilot-engine/) | Destination (src/copilot/) | |--------------------------|---------------------------| | src/engine/agentic-loop.ts | engine/agentic-loop.ts | | src/engine/llm-types.ts | engine/llm-types.ts | | src/engine/sse-stream.ts | engine/sse-stream.ts | | src/engine/project-config.ts | engine/project-config.ts | | src/engine/route-factories.ts | engine/route-factories.ts | | src/engine/providers/index.ts | engine/providers/index.ts | | src/engine/providers/anthropic.ts | engine/providers/anthropic.ts | | src/engine/providers/openai.ts | engine/providers/openai.ts | | src/auth/validate-token.ts | auth/validate-token.ts | | src/mount.ts | mount.ts |

Important: After copying, fix the import paths in mount.ts — change "./auth/validate-token" to "./auth/validate-token" and "./engine/route-factories" to "./engine/route-factories" (these should already be correct since the directory structure mirrors the source).

Install only the LLM SDK the developer chose:

npm install @anthropic-ai/sdk   # if Anthropic
# OR
npm install openai              # if OpenAI

Step 2A: Create Project Files

Create these files directly in src/copilot/ (NOT in a separate projects/ directory):

src/copilot/system-prompt.ts — domain-specific system prompt (same guidance as Step 2 in standalone).

src/copilot/tools.ts — tool definitions using the generic Tool type:

import type { Tool } from "./engine/llm-types";
export const READ_TOOLS: Tool[] = [ ... ];
export const WRITE_TOOLS: Tool[] = [ ... ];
export const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS.map(t => t.name));
export const ALL_TOOLS = [...READ_TOOLS, ...WRITE_TOOLS];

src/copilot/tool-executor.ts — tool execution logic (same guidance as Step 2 in standalone).

src/copilot/config.ts — project-specific config:

export function getConfig() {
  return {
    apiUrl: process.env.APP_API_URL || "http://localhost:5000",
    // ... other project-specific URLs
  };
}

src/copilot/index.ts — barrel file that wires everything together:

import type { Express } from "express";
import { mountCopilot } from "./mount";
import type { ProjectConfig } from "./engine/project-config";
import { SYSTEM_PROMPT, getResponseModeInstruction } from "./system-prompt";
import { ALL_TOOLS, WRITE_TOOL_NAMES } from "./tools";
import { executeReadTool, executeWriteTool } from "./tool-executor";
import { getConfig } from "./config";

const project: ProjectConfig = {
  systemPrompt: SYSTEM_PROMPT,
  getResponseModeInstruction,
  allTools: ALL_TOOLS,
  writeToolNames: WRITE_TOOL_NAMES,
  executeReadTool,
  executeWriteTool,
  getConfig,
};

export function setupCopilot(app: Express): void {
  mountCopilot(app, project);
}

Step 7A: Mount on Existing Server

Find the app's server entry point and add one line:

Express:

import { setupCopilot } from "./copilot";
// ... after app.use(express.json()) and CORS setup ...
setupCopilot(app);

NestJS: Create a CopilotModule or add to main.ts:

import { setupCopilot } from "./copilot";
const app = await NestFactory.create(AppModule);
setupCopilot(app.getHttpAdapter().getInstance());

Add copilot env vars to the app's .env:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
# LLM_MODEL=gpt-4.1-mini  (optional override)

No separate ALLOWED_ORIGINS needed — the copilot runs on the same origin as the app.

Remaining Steps (Built-in)

Steps 3-6 (frontend scaffold, dark mode, layout, config) are the same as standalone mode. Skip to those steps below.

Step 8 verification: start only ONE server (npm start or npm run dev). Test endpoints at the app's own port:

curl http://localhost:{APP_PORT}/api/copilot/health

---

Path B — Standalone Mode

Step 1B: Fork, Clone, and Set Up copilot-engine

Each application gets its own fork — this ensures one-to-one isolation and lets you customize tools, prompts, and executors independently.

1. Fork the upstream repo:

gh repo fork femitfash/copilot-engine --clone=false

2. Clone YOUR fork as a sibling directory (NOT inside the app repo):

GITHUB_USER=$(gh api user --jq .login)
cd .. && git clone "https://github.com/$GITHUB_USER/copilot-engine.git"
cd copilot-engine && npm install
cp .env.example .env

3. Set upstream remote for future engine updates:

git remote add upstream https://github.com/femitfash/copilot-engine.git

Confirm src/index.ts (or the server entry point) has import 'dotenv/config' as its first line — before any other imports that read process.env. If it doesn't, add it.

Read the app's codebase to understand:

1. What APIs does this app call? (search for HTTP services, API endpoints, base URLs)
2. What auth system does it use? (cookies, localStorage, tokens — search for Authorization, Bearer, loginToken)
3. What is the app's domain? (what does it do — e.g., project management, e-commerce, analytics)
4. What pages/routes exist? (read the routing module)
5. How does dark mode work? (search for theme service, dark class, CSS variables)

Step 2: Create Backend Project

Create copilot-engine/projects/{app-name}/ with three files:

system-prompt.ts — Write a domain-specific system prompt that:

• Describes what the copilot can do in this app's context
• Lists interaction principles (proactive, conversational, action-oriented, approval gate)
• Documents the [suggest:] and [navigate:] syntax
• Lists all available pages from the app's routing module
• Use projects/example/system-prompt.ts as a template

tools.ts — Define READ and WRITE tools based on the app's APIs:

• READ tools: safe data-fetching operations (GET endpoints)
• WRITE tools: mutations that need user approval (POST/PUT/DELETE)
• Use projects/example/tools.ts as a template

tool-executor.ts — Map tool names to API calls:

• Forward the user's auth token to the app's APIs
• Set Origin header on all requests to pass CSRF checks
• For WRITE tools: cross-reference the app's database schema for NOT NULL columns and fill in sensible defaults for any required fields not in the tool's input_schema
• Required: Truncate every tool result to 8KB max before returning it — serialize to JSON, then if result.length > 8192 slice it and append " ... (truncated)". This prevents token overflow on large API responses.
• Use projects/example/tool-executor.ts as a template

Then update copilot-engine/routes/copilot.ts and routes/execute.ts imports to point to your new project instead of zerotrusted.

Required for SSE: In routes/copilot.ts, immediately after setting SSE response headers, call res.flushHeaders() and send one empty keep-alive event (res.write('data: \n\n')) before the first real chunk. Without this, the connection silently times out before any tokens stream.

Update copilot-engine/src/config.ts to include your app's API URL environment variables.

Update copilot-engine/.env with:

• LLM_PROVIDER — set to anthropic (default) or openai
• LLM_MODEL — optional override (e.g., gpt-4.1-mini, claude-sonnet-4-20250514)
• The matching API key: ANTHROPIC_API_KEY or OPENAI_API_KEY
• If the developer has an API key in their shell environment, auto-populate it in .env
• Your app's API URLs
• ALLOWED_ORIGINS must exactly match your app's dev server URL (e.g., http://localhost:4200) — wildcards will fail for credentialed requests
• PORT=3100

Step 3: Scaffold Frontend Files

Create copilot components using the app's frontend framework (React, Angular, Vue, etc.). Adapt the patterns below to your framework's conventions.

Welcome / Empty State Layout (CRITICAL — follow exactly)

When no messages exist, the copilot panel MUST show a chat bubble welcome message from the bot — NOT a centered icon/text layout.

Required layout:

┌─────────────────────────────────────────┐
│ 🤖 AI Copilot    [Concise ▾] [🗑] [✕]  │  ← Header
├─────────────────────────────────────────┤
│                                         │
│  (•) ┌─────────────────────────────┐    │
│  bot │ Hi! I'm your [App Name]     │    │
│  ava │ Copilot. Here's what I      │    │
│  tar │ can do:                     │    │
│      │                             │    │
│      │ Navigate                    │    │
│      │ ┌──────┐ ┌──────┐ ┌──────┐ │    │
│      │ │ Dash │ │ Page │ │ Page │ │    │
│      │ └──────┘ └──────┘ └──────┘ │    │
│      │ ┌──────┐ ┌──────┐         │    │
│      │ │ Page │ │ Page │         │    │
│      │ └──────┘ └──────┘         │    │
│      │                             │    │
│      │ Actions                     │    │
│      │ ┌────────────┐ ┌──────────┐│    │
│      │ │ Action One │ │ Action 2 ││    │
│      │ └────────────┘ └──────────┘│    │
│      │ ┌────────────┐ ┌──────────┐│    │
│      │ │ Action 3   │ │ Action 4 ││    │
│      │ └────────────┘ └──────────┘│    │
│      │                             │    │
│      │ Or just type your question  │    │
│      │ below.                      │    │
│      └─────────────────────────────┘    │
│                                         │
├─────────────────────────────────────────┤
│ [Ask the copilot anything...     ] [▶]  │  ← Input
└─────────────────────────────────────────┘

Design rules:

1. Bot avatar (left-aligned, small circle with bot/chat icon) + chat bubble containing the welcome content
2. Navigate section: bold header, followed by inline pill/chip buttons (flex-wrap layout)
   • Pill style: outlined border (1px solid with theme accent color), rounded-full/pill shape
   • Small text (~10-11px), horizontal padding ~8-12px, vertical ~3-5px
   • Each pill uses [navigate:/route]Label[/navigate] token — clicking navigates in-app
3. Actions section: bold header, followed by inline pill/chip buttons (same style as Navigate)
   • Each pill uses [suggest:prompt text]Label[/suggest] token — clicking sends a follow-up
4. Closing line: "Or just type your question below."

DO NOT:

• Use a centered sparkle/icon as the welcome state
• Use tabbed categories with vertical text list items
• Use full-width card-style buttons for prompts
• Create multiple fine-grained categories (e.g., "Compliance", "Security", "Quick Actions")

Types

Create a types file (copilot.types.ts or copilot-types.ts):

export interface CopilotMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: Date;
  actions?: CopilotAction[];
  isStreaming?: boolean;
}

export interface CopilotAction {
  id: string;
  name: string;
  input: Record<string, unknown>;
  status: 'pending' | 'executing' | 'executed' | 'rejected';
  result?: Record<string, unknown>;
}

export interface CopilotPrompt {
  id: string;
  category: string;
  title: string;
  prompt: string;
}

export type ResponseMode = 'concise' | 'actions' | 'detailed';

Prompts

Create a prompts file (copilot-prompts.ts):

• Group ALL prompts into exactly 2 categories: "Navigate" and "Actions"
• Navigate category: [navigate:/route]Label[/navigate] prompts for the app's key pages (6-8 most important)
• Actions category: [suggest:prompt text]Label[/suggest] for domain-specific actions (6-8 most useful)
• Do NOT create multiple fine-grained categories — keep it to Navigate + Actions only

Services

Create these services (adapt naming to your framework):

• copilot-service — SSE communication with copilot-engine. CRITICAL: use response.text() NOT response.body.getReader() for SSE parsing (ReadableStream fails on Windows). Get auth token using the app's existing auth pattern. Get copilot URL from the app's config with fallback http://localhost:3100.
• copilot-context — Snapshot of current page, user role, etc.
• copilot-events — Event bus for cross-component refresh updates (use framework-appropriate pattern: Subject in Angular, EventEmitter/context in React, mitt/provide-inject in Vue).

Components

Create 4 components:

• copilot-panel — Main chat container with:
  • Header: bot avatar + copilot name (left), response mode selector + clear/trash button + close button (right)
  • Message list: scrollable area showing conversation messages
  • Welcome state: chat-bubble welcome with inline Navigate/Actions pill buttons (see layout above)
  • Input area: text input + send button at bottom
• copilot-message — Message bubble with markdown rendering and [suggest:]/[navigate:] button parsing. CRITICAL: extract tokens BEFORE HTML escaping, then restore after. Watch for content changes during streaming (use ngDoCheck in Angular, useEffect/useMemo in React, watch in Vue). Required: When displaying errors, handle both formats — typeof err === 'string' ? err : err.message — otherwise [object Object] is shown to the user.
• copilot-action-card — Approve/reject card for write tool actions. Three states: pending (amber/warning), executed (green/success), rejected (red/error). After successful execution, the card MUST:
  1. Auto-navigate to the relevant page so the user can see what was created (map tool names to routes)
  2. Invalidate the data cache (React Query, Angular HttpClient cache, etc.) for the affected endpoints so the page shows fresh data without a hard refresh
• copilot-thinking — Animated thinking indicator with bouncing dots and rotating domain-specific phrases. Required: While the thinking indicator is visible, hide any message with isStreaming: true and empty content — rendering both simultaneously causes a duplicate bot avatar.

SCSS Rules (Angular — applies to all components)

⚠️ Common cause of build failures and unstyled buttons. Follow these exactly.

Valid BEM nesting:

.action-card {
  &__actions { ... }         // ✅ element at block root
  &.pending { ... }          // ✅ modifier at block root
  &.pending &__icon { ... }  // ✅ element scoped to modifier — valid
}

Invalid patterns (will cause SassError or wrong selector):

.action-card {
  &__actions {
    .btn-approve { ... }   // ❌ place .btn-approve at block root, not inside &__actions
  }
  &.pending {
    &__icon { ... }        // ❌ nested &__icon inside modifier block — invalid in Sass pre-dart
  }
}
.pending & { ... }         // ❌ & after another selector — always invalid

Rule: Place button rules (.btn-approve, .btn-reject) and modifier-scoped rules at the block root level, not nested inside element blocks.

---

Step 4: Dark Mode

Ensure the copilot respects the host app's dark mode. Approach depends on your framework:

Angular — DO NOT use :host-context(.dark) — it fails with ViewEncapsulation.Emulated. Instead:

1. Subscribe to the app's theme service, expose an isDark boolean
2. Bind [class.copilot-dark]="isDark" on each component's root element
3. Pass [isDark]="isDark" as @Input() to all child components
4. All dark SCSS uses .copilot-dark { ... } — never :host-context()

React — Use the app's theme context/provider (e.g., useTheme() hook). If the app uses Tailwind with dark: prefix via a .dark class on <html>, your copilot components automatically inherit dark mode.

Vue — Use the app's reactive theme state or CSS variables. Bind dark class on component root elements.

Dark mode colors — Extract from the host app's actual palette:

grep -r "bg-\[#" src/
grep -r "--header-bg\|--dropdown-bg" src/

Text colors in dark mode:

• Body text: #e8e8e8 (light grey-white)
• Bold/headers: #ffffff
• User message bubble text: #ffffff (explicit override needed)
• For Angular: use blanket ::ng-deep { div, p, span, li, ... { color: #e8e8e8; } } for assistant messages

Step 5: Layout Integration

1. Add a toggle mechanism (reactive state — BehaviorSubject in Angular, useState/context in React, ref in Vue)
2. Add a toggle button to the sidebar or header (labeled "Copilot" with a bot/chat icon)
3. Add the copilot panel component to the main layout template alongside the router outlet
4. Import the component in the appropriate module/entry point
5. Set z-index LOWER than the app's header dropdowns/modals (typically z-index: 10 for panel, z-index: 20+ for header)
6. Add CopilotApiUrl to the app's runtime config

Step 6: Config and i18n

• Add CopilotApiUrl to config template and env generator (or Vite env vars like VITE_COPILOT_API_URL)
• Add COPILOT_* translation keys to all i18n files (if the app has i18n)

Step 7: Install QA Skill

Copy the integration QA skill from copilot-engine to the target app so the developer can run /qa-integration from their project directory:

mkdir -p .claude/skills
cp ../copilot-engine/.claude/skills/qa-integration.md .claude/skills/qa-integration.md

Step 8: Verify

1. Start copilot-engine: cd ../copilot-engine && npm run dev
2. Start the app: npm start (or npm run dev)
3. Test: navigation pill buttons work, action prompts return responses, dark mode renders correctly, header menus appear above copilot panel

Step 9: Summary — What Was Done

After completing all steps, output this summary so the developer knows what was created.

For Built-in mode:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅  AI Copilot Integration Complete (Built-in)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Mode:          Built-in (same server, same port)
  LLM Provider:  {provider} ({model})
  Copilot files: src/copilot/
  Frontend:      {n} components + {n} services created

  Engine files in src/copilot/:
    engine/          (agentic loop, providers, SSE streaming)
    auth/            (token extraction middleware)
    mount.ts         (mountCopilot function)
    system-prompt.ts
    tools.ts         ({n} READ + {n} WRITE tools)
    tool-executor.ts
    config.ts
    index.ts         (setupCopilot barrel export)

  Server integration:
    {server-file}: import { setupCopilot } from "./copilot"

  To start:
    npm start  (or your app's dev command — one process)

  To verify:
    Run /qa-integration from Claude Code in this directory

  Reference repo: ../copilot-engine/ (for updates: git pull upstream master)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For Standalone mode:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅  AI Copilot Integration Complete (Standalone)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Mode:          Standalone (port {PORT})
  LLM Provider:  {provider} ({model})
  Engine:        ../copilot-engine/
  Project:       copilot-engine/projects/{app-name}/
  Frontend:      {n} components + {n} services created

  Files created in copilot-engine:
    projects/{app-name}/system-prompt.ts
    projects/{app-name}/tools.ts         ({n} READ + {n} WRITE tools)
    projects/{app-name}/tool-executor.ts

  Files created in {app-name}:
    {list each component, service, and types file created}
    .claude/skills/qa-integration.md

  To start:
    Terminal 1:  cd ../copilot-engine && npm run dev
    Terminal 2:  npm start  (or your app's dev command)

  To verify:
    Run /qa-integration from Claude Code in this directory

  Docs:
    Integration guide:  ../copilot-engine/COPILOT_SKILL.md
    Known pitfalls:     ../copilot-engine/KNOWN-ISSUES.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Replace {placeholders} with actual values from the integration.

---

Known Issues Reference

The common pitfalls are covered inline in the steps above. For environment-specific edge cases:

| Issue | When to check | |-------|---------------| | Cross-origin fetch blocked | App and copilot-engine on different origins — implement a same-origin proxy in the host app | | Node v24 ESM resolution errors | Pin openai v4.x and @anthropic-ai/sdk v0.39.x | | Windows ENOTSUP on startup | Bind to 127.0.0.1 instead of 0.0.0.0 in src/index.ts | | Database not found on first run | Run prisma migrate dev or prisma db push before starting |

See known-issues.md for the full deployment verification checklist (26 items) before going live.