@velt-js/mcp-installer 0.1.0 → 0.2.0

package/src/utils/plan-formatter.js

@@ -1,8 +1,11 @@
 /**
  * Plan Formatter
  *
- * Formats installation instructions as a sequential plan (similar to Cursor's plan mode)
- * that the AI can follow to complete the implementation.
+ * Formats installation instructions as a sequential plan that the AI follows.
+ *
+ * ARCHITECTURE: This formatter generates ORCHESTRATION steps only.
+ * Implementation details (code patterns, CSS, configuration) live in agent-skills.
+ * The plan tells the AI WHAT to do and WHICH skill rule to follow for HOW.
  */
 
 import { getDocUrl, getDocMarkdownUrl } from './velt-docs-urls.js';
@@ -10,11 +13,6 @@ import { getSkillReferences } from './velt-docs-fetcher.js';
 
 /**
  * Generates a "Skills & Sources" section for the plan output.
- * Skills-covered features get a skill reference; others get docs URLs.
- *
- * @param {string[]} features - Features being installed
- * @param {Object} [options] - Options (commentType, crdtEditorType)
- * @returns {string} Markdown section
  */
 function formatSkillsSourceSection(features, options = {}) {
   const refs = getSkillReferences(features, options);
@@ -28,13 +26,12 @@ function formatSkillsSourceSection(features, options = {}) {
 
   if (skillRefs.length > 0) {
     section += `### Primary: Agent Skills (use these first)\n\n`;
-    // Deduplicate skill names
     const seen = new Set();
     for (const ref of skillRefs) {
       if (!seen.has(ref.skillName)) {
         seen.add(ref.skillName);
-        const features = skillRefs.filter(r => r.skillName === ref.skillName).map(r => r.feature);
-        section += `- **${ref.skillName}** — covers: ${features.join(', ')}${ref.description ? ` (${ref.description})` : ''}\n`;
+        const feats = skillRefs.filter(r => r.skillName === ref.skillName).map(r => r.feature);
+        section += `- **${ref.skillName}** — covers: ${feats.join(', ')}${ref.description ? ` (${ref.description})` : ''}\n`;
       }
     }
     section += `\n`;
@@ -56,29 +53,18 @@ function formatSkillsSourceSection(features, options = {}) {
 }
 
 /**
- * Formats a plan with numbered steps, details, and a to-do checklist
- *
- * @param {Object} options - Plan options
- * @param {string} options.title - Plan title (e.g., "Plan for Velt Freestyle Comments Installation")
- * @param {Array} options.steps - Array of step objects
- * @param {string} options.steps[].title - Step title
- * @param {string} options.steps[].details - Step details/instructions
- * @param {string[]} [options.steps[].codeExamples] - Optional code examples
- * @param {Array} [options.additionalInfo] - Additional information sections
- * @returns {string} Formatted plan as markdown
+ * Formats a plan with numbered steps, details, and a to-do checklist.
  */
 export function formatInstallationPlan(options) {
   const { title, steps, additionalInfo = [] } = options;
 
   let plan = `# ${title}\n\n`;
 
-  // Add numbered steps with details
   steps.forEach((step, index) => {
     const stepNumber = index + 1;
     plan += `## ${stepNumber}. ${step.title}\n`;
     plan += `*   **Details:** ${step.details}\n`;
 
-    // Add code examples if provided
     if (step.codeExamples && step.codeExamples.length > 0) {
       step.codeExamples.forEach((example) => {
         plan += `\n${example.description ? `*   ${example.description}:` : ''}
@@ -91,7 +77,6 @@ ${example.code}
     plan += '\n';
   });
 
-  // Add additional information sections
   if (additionalInfo.length > 0) {
     additionalInfo.forEach((info) => {
       plan += `## ${info.title}\n`;
@@ -99,7 +84,6 @@ ${example.code}
     });
   }
 
-  // Add To-Do checklist
   plan += `## To-Do List\n`;
   steps.forEach((step, index) => {
     const checkbox = index === 0 ? '[✓]' : '[ ]';
@@ -107,21 +91,31 @@ ${example.code}
   });
 
   plan += '\n';
-
   return plan;
 }
 
 /**
- * Creates a plan for Velt Comments installation
+ * Gets test instructions for a comment type.
+ */
+function getTestInstructions(commentType) {
+  const instructions = {
+    freestyle: 'Click the Comment Tool button, then click anywhere on the page to add a comment.',
+    popover: 'Click the Comment Tool button next to an element to attach a comment to it.',
+    page: 'Open the Comments Sidebar and add a page-level comment at the bottom.',
+    stream: 'Select text to see comments appear in the stream column on the right.',
+    text: 'Highlight any text to see the Comment Tool button appear, then click it to add a comment.',
+    inline: 'Navigate to your content area and test adding inline comments.',
+    tiptap: 'Open your Tiptap editor, select text, and use the comment button in the bubble menu.',
+    lexical: 'Open your Lexical editor, select text, and add comments using the Velt comment integration.',
+    slate: 'Open your Slate.js editor, select text, and add comments using the Velt comment integration.',
+  };
+  return instructions[commentType] || 'Test adding comments in your application.';
+}
+
+/**
+ * Creates a plan for Velt Comments installation (single-feature).
  *
  * @param {Object} options - Installation options
- * @param {string} options.commentType - Type of comments (freestyle, popover, page, stream, text)
- * @param {Object} options.implementation - Implementation details from Velt Docs
- * @param {Array} options.detectedFiles - Files detected for modification
- * @param {string} options.apiKey - API key preview
- * @param {string} options.headerPosition - Header position
- * @param {string} options.veltProviderLocation - Where to install VeltProvider
- * @param {string} options.crdtEditorType - CRDT editor type (tiptap, codemirror, blocknote)
  * @returns {string} Formatted installation plan
  */
 export function createVeltCommentsPlan(options) {
@@ -133,564 +127,113 @@ export function createVeltCommentsPlan(options) {
     headerPosition,
     veltProviderLocation = 'app/page.tsx',
     crdtEditorType,
+    frameworkInfo,
+    wiring,
   } = options;
 
   const commentTypeTitle = commentType.charAt(0).toUpperCase() + commentType.slice(1);
-
   const steps = [];
 
-  // Add warning about only implementing requested features
-  steps.push({
-    title: `⚠️ CRITICAL: Only implement ${commentTypeTitle} Comments`,
-    details: `You are ONLY installing ${commentTypeTitle} Comments. DO NOT implement: VeltNotificationsTool, VeltPresence, VeltCursor, VeltRecorder, or any other components unless the user specifically requested them. Only use authentication, user setup, and document setup from CLI. Get ${commentTypeTitle} Comments implementation from: ${implementation?.mdUrl || getDocMarkdownUrl('comments', commentType)}`,
-  });
-
-  // Step 2: Use CLI-generated Velt components
   const locationText = veltProviderLocation === 'auto-detect'
-    ? 'the appropriate layout file (analyze the project structure to determine the best location)'
+    ? 'the appropriate layout file'
     : veltProviderLocation;
 
+  // Step 1: Scope warning
   steps.push({
-    title: `Import and use CLI-generated Velt components in ${locationText}`,
-    details: `The Velt CLI has generated the necessary component files in \`components/velt/\`. DO NOT create new files. Use the existing files:
-
-**CLI-Generated Files:**
-- \`components/velt/VeltInitializeUser.tsx\` - Exports \`useVeltAuthProvider\` hook (NOT a wrapper component)
-- \`components/velt/VeltInitializeDocument.tsx\` - Exports \`useCurrentDocument\` hook for document context
-- \`components/velt/VeltCollaboration.tsx\` - Velt feature components (comments, presence, etc.)
-- \`app/userAuth/AppUserContext.tsx\` - User context provider wrapper
-- \`app/userAuth/useAppUser.tsx\` - User data hook (add TODOs here)
-- \`app/api/velt/token/route.ts\` - Token generation API
-
-⚠️ **CRITICAL ARCHITECTURE (Sample App Pattern):**
-
-**1. app/layout.tsx - Wrap with AppUserProvider:**
-\`\`\`tsx
-import { AppUserProvider } from './userAuth/AppUserContext'
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <AppUserProvider>
-          {children}
-        </AppUserProvider>
-      </body>
-    </html>
-  )
-}
-\`\`\`
-**Why**: AppUserProvider provides user context to all components including Velt auth.
-
-**2. app/page.tsx (or root page) - VeltProvider with authProvider hook:**
-\`\`\`tsx
-"use client";
-import { VeltProvider } from '@veltdev/react';
-import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
-import { useCurrentDocument } from '@/components/velt/VeltInitializeDocument';
-import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
-
-const VELT_API_KEY = process.env.NEXT_PUBLIC_VELT_API_KEY!;
-
-export default function Page() {
-  const { authProvider } = useVeltAuthProvider();
-  const { documentId } = useCurrentDocument();
-
-  return (
-    <VeltProvider apiKey={VELT_API_KEY} authProvider={authProvider}>
-      <VeltCollaboration documentId={documentId} />
-      {/* Your page content */}
-    </VeltProvider>
-  );
-}
-\`\`\`
-**Why**: VeltProvider must be in page.tsx with authProvider from hook, NOT nested wrapper components.
-
-**What to do:**
-1. Add AppUserProvider wrapper to app/layout.tsx
-2. Add VeltProvider to ${locationText} using useVeltAuthProvider hook
-3. Import VeltCollaboration for feature components
-4. Follow the markdown documentation for ${commentType} comment-specific implementation: ${implementation?.mdUrl || getDocMarkdownUrl('comments', commentType)}
-
-**CRITICAL - For Tiptap/Lexical/Slate Comments:**
-- ✅ **FIND EXISTING EDITOR** - Search the project for existing Tiptap/Lexical/Slate editor components
-- ✅ **INTEGRATE INTO EXISTING EDITOR** - Add Velt comments to the existing editor, DO NOT create a new editor
-- ✅ **USE BUBBLE MENU PATTERN** - Add comment button to bubble menu (appears on text selection), NOT a fixed toolbar
-- ✅ Use ONLY the comment-specific package: @veltdev/tiptap-velt-comments, @veltdev/lexical-velt-comments, or @veltdev/slate-velt-comments
-- ❌ DO NOT create a new editor component if one already exists
-- ❌ DO NOT create a fixed toolbar with Bold/Italic/Comment buttons
-- ❌ DO NOT use CRDT packages (@veltdev/tiptap-velt-collaboration or similar)
-- ❌ DO NOT implement real-time collaborative editing - only comments on the editor
-
-**Tiptap Pattern:**
-\`\`\`tsx
-import { BubbleMenu } from '@tiptap/react'
-import { TiptapVeltComments, addComment, renderComments } from '@veltdev/tiptap-velt-comments'
-import { useCommentAnnotations } from '@veltdev/react'
-
-// Add to editor extensions: TiptapVeltComments
-// Use BubbleMenu component with comment button
-<BubbleMenu editor={editor}>
-  <button onClick={() => addComment({ editor })}>💬 Comment</button>
-</BubbleMenu>
-\`\`\`
-
-**Lexical Pattern:**
-- Add VeltCommentsPlugin to editor plugins
-- Use custom bubble menu that appears on selection
-- Trigger addComment() from bubble menu button
-
-**Slate Pattern:**
-- Wrap editor with withVeltComments()
-- Implement bubble menu with position tracking on selection
-- Trigger addComment({ editor }) from bubble menu button
-
-**If NO existing editor found:** Provide minimal integration example with bubble menu, but recommend user add to their existing editor.
-
-**IMPORTANT:** All Velt-related files should remain in \`components/velt/\`. Do not create new Velt files outside this folder.`,
-    codeExamples: [
-      {
-        description: `Correct pattern: VeltProvider in page.tsx with authProvider hook`,
-        language: 'tsx',
-        code: `// app/page.tsx (or your root page component)
-"use client";
-import { VeltProvider } from '@veltdev/react';
-import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
-import { useCurrentDocument } from '@/components/velt/VeltInitializeDocument';
-import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
-
-const VELT_API_KEY = process.env.NEXT_PUBLIC_VELT_API_KEY!;
-
-export default function Page() {
-  const { authProvider } = useVeltAuthProvider();
-  const { documentId } = useCurrentDocument();
-
-  return (
-    <VeltProvider apiKey={VELT_API_KEY} authProvider={authProvider}>
-      <VeltCollaboration documentId={documentId} />
-      {/* Your page content here */}
-    </VeltProvider>
-  );
-}
-
-// For ${commentType} comments: Follow implementation at ${implementation?.mdUrl || getDocMarkdownUrl('comments', commentType)}`,
-      },
-    ],
+    title: `⚠️ CRITICAL: Only implement ${commentTypeTitle} Comments`,
+    details: `You are ONLY installing ${commentTypeTitle} Comments. DO NOT implement other components unless requested.`,
   });
 
-  // Step 3: Add TODO comments to CLI-generated auth files
+  // Step 2: Wire VeltProvider + CLI components
   steps.push({
-    title: `Add TODO comments to CLI-generated authentication files`,
-    details: `The Velt CLI has generated authentication files in specific locations. Add TODO comments to these existing files (DO NOT create new files):
-
-**1. User Hook: \`app/userAuth/useAppUser.tsx\`**
-   - This file already exists from CLI
-   - Add TODO: Connect to your existing authentication system
-   - Add TODO: Replace mock user data with actual user from your auth provider
-   - Examples: Next-auth useSession(), Clerk useUser(), Auth0, etc.
-
-**2. Auth Provider: \`components/velt/VeltInitializeUser.tsx\`**
-   - This file already exists from CLI (references useAppUser)
-   - Contains \`useVeltAuthProvider\` hook
-   - File location may vary, look for useVeltAuthProvider hook
-
-**3. Document Hook: Check for \`app/document/useCurrentDocument.tsx\`**
-   - May be in CLI-generated files or needs to be created
-   - Add TODO: Implement document identification logic
-   - Add TODO: Return unique document ID based on current page/route
-   - Examples: router.query.id, pathname, page slug
-
-**4. Token API: \`app/api/velt/token/route.ts\`**
-   - This file already exists from CLI
-   - Add TODO: Connect to your backend authentication
-   - Add TODO: Validate user session before generating token
-
-**IMPORTANT:** Only modify CLI-generated files. Do not create new files. Keep all Velt code in \`components/velt/\` and the specified locations.
-
-**FOR TESTING PRESENCE/CURSORS:** Add logic to test with multiple users:
-1. Hardcode a fixed document ID (e.g., "demo-document") so all tabs use the same document
-2. Provide 2 hardcoded users (user-1 and user-2) with different names/avatars
-3. Allow switching users via URL parameter (?user=1 or ?user=2) to test presence/cursors
-4. Open multiple browser tabs with different user parameters to see live presence and cursors`,
-    codeExamples: [
-      {
-        description: 'Example: Hardcoded document ID and multiple users for testing',
-        language: 'typescript',
-        code: `// In useCurrentDocument.tsx - Hardcode document ID for testing:
-export function useCurrentDocument() {
-  // [Velt] HARDCODED for testing presence/cursors
-  // TODO: Replace with dynamic document ID based on your routing
-  const documentId = "demo-document"; // Fixed ID so all tabs see same document
-
-  return { documentId, documentName: "Demo Document" };
-}
-
-// In useAppUser.tsx - Multiple users for testing:
-export function useAppUser() {
-  // [Velt] HARDCODED USERS for testing presence/cursors
-  // TODO: Replace with actual user from your auth provider
-
-  // Get user from URL parameter (?user=1 or ?user=2)
-  const searchParams = typeof window !== 'undefined'
-    ? new URLSearchParams(window.location.search)
-    : null;
-  const userParam = searchParams?.get('user') || '1';
-
-  const users = {
-    '1': {
-      userId: "user-1",
-      name: "Demo User 1",
-      email: "user1@example.com",
-      photoUrl: "https://i.pravatar.cc/150?img=1",
-      organizationId: "demo-org",
-    },
-    '2': {
-      userId: "user-2",
-      name: "Demo User 2",
-      email: "user2@example.com",
-      photoUrl: "https://i.pravatar.cc/150?img=2",
-      organizationId: "demo-org",
-    }
-  };
-
-  const user = users[userParam] || users['1'];
-
-  return { user, isUserLoggedIn: true };
-}
-
-// TESTING INSTRUCTIONS:
-// 1. Open http://localhost:3000?user=1 in one tab
-// 2. Open http://localhost:3000?user=2 in another tab
-// 3. You should see 2 different avatars in presence
-// 4. Move mouse in one tab to see cursor in the other tab`,
-      },
-      {
-        description: 'Example TODO comments to add',
-        language: 'typescript',
-        code: `// In useAppUser.tsx:
-// TODO: Connect to your authentication system
-// TODO: Replace this mock user data with actual user from your auth provider
-// Example: const user = useAuth(); // Your auth hook
-// Example: const user = useSession(); // Next-auth
-// Example: const user = useUser(); // Clerk, Auth0, etc.
-
-// In useCurrentDocument.tsx:
-// TODO: Implement document identification logic
-// TODO: Return a unique document ID based on your app's routing
-// Example: Use route params, URL, page ID, etc.
-// Example: const documentId = router.query.id;
-// Example: const documentId = \`page-\${pathname}\`;
-
-// In app/api/velt/auth/route.ts:
-// TODO: SECURITY - Validate user session before generating token
-// TODO: Connect to your backend authentication
-// TODO: Verify user is authenticated and authorized
-
-// If JWT generation is present:
-// TODO: SECURITY - Replace 'your-secret-key' with actual secret
-// TODO: Store secret in environment variables (process.env.JWT_SECRET)
-// TODO: NEVER commit secrets to version control
-// TODO: Implement token expiration (expiresIn: '24h')`,
-      },
-    ],
+    title: `Wire VeltProvider and CLI-generated components in ${locationText}`,
+    details: `**Skill reference:** \`velt-setup-best-practices\` → provider-wiring rules
+
+Use the CLI-generated files in \`components/velt/\`. Wire them following the skill patterns:
+- Import \`useVeltAuthProvider\` from \`components/velt/VeltInitializeUser.tsx\`
+- Import \`VeltCollaboration\` from \`components/velt/VeltCollaboration.tsx\`
+- Wrap your page content with \`<VeltProvider apiKey={...} authProvider={authProvider}>\`
+- Place \`<VeltCollaboration />\` inside the VeltProvider
+- The page file MUST have \`"use client"\` directive (Next.js)
+- VeltProvider goes in \`${locationText}\`, NOT in layout.tsx (layout.tsx exports metadata, which is server-only)
+
+**IMPORTANT:** Do NOT create new Velt files. Use the CLI-generated files in \`components/velt/\`.`,
   });
 
-  // Step 4: Implement JWT token generation (Production Pattern)
+  // Step 3: Configure authentication
   steps.push({
-    title: `Implement JWT token generation via Velt API (Production Pattern)`,
-    details: `The CLI generates a placeholder JWT route. Replace it with the production pattern that calls Velt's token API.
-
-**Production Pattern (FireHydrant Reference):**
-Server-side API calls Velt's token endpoint to generate secure JWT tokens.
+    title: `Set up authentication and JWT token generation`,
+    details: `**Skill reference:** \`velt-setup-best-practices\` → identity-jwt-generation, identity-user-object-shape rules
 
-**Velt Token API:**
-\`\`\`
-POST https://api.velt.dev/v2/auth/token/get
-Headers:
-  x-velt-api-key: YOUR_VELT_PUBLIC_API_KEY
-  x-velt-auth-token: YOUR_VELT_AUTH_TOKEN (keep secret!)
-Body:
-  { "data": { "userId": "...", "userProperties": { "organizationId": "...", "email": "..." } } }
-Response:
-  { "result": { "data": { "token": "eyJ..." } } }
-\`\`\`
-
-**Environment Variables to Set:**
-\`\`\`
-VELT_PUBLIC_API_KEY=your_api_key_here
-VELT_AUTH_TOKEN=your_auth_token_here  # NEVER expose to client!
-\`\`\`
-
-**Security Requirements:**
-- Keep VELT_AUTH_TOKEN server-side only (never expose to client)
-- Validate user session before generating tokens
-- The auth token should only be used in API routes, not client components`,
-    codeExamples: [
-      {
-        description: 'Production API Route: app/api/velt/token/route.ts',
-        language: 'typescript',
-        code: `import { NextRequest, NextResponse } from 'next/server';
-
-// [Velt] JWT Token Generation - Production Pattern
-const VELT_API_KEY = process.env.VELT_PUBLIC_API_KEY;
-const VELT_AUTH_TOKEN = process.env.VELT_AUTH_TOKEN;
-
-export async function POST(request: NextRequest) {
-  try {
-    // [Velt] TODO: Add user session validation here
-    // const session = await getServerSession(authOptions);
-    // if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-
-    const body = await request.json();
-    const { userId, organizationId, email } = body;
-
-    if (!userId) {
-      return NextResponse.json({ error: 'userId is required' }, { status: 400 });
-    }
-
-    if (!VELT_API_KEY || !VELT_AUTH_TOKEN) {
-      console.error('[Velt] Missing VELT_PUBLIC_API_KEY or VELT_AUTH_TOKEN');
-      return NextResponse.json({ error: 'Velt credentials not configured' }, { status: 500 });
-    }
-
-    // [Velt] Call Velt Token API
-    const response = await fetch('https://api.velt.dev/v2/auth/token/get', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-velt-api-key': VELT_API_KEY,
-        'x-velt-auth-token': VELT_AUTH_TOKEN,
-      },
-      body: JSON.stringify({
-        data: {
-          userId,
-          userProperties: { organizationId: organizationId || 'default-org', email: email || '' },
-        },
-      }),
-    });
+Follow the skill patterns to:
+- Configure \`app/api/velt/token/route.ts\` for server-side JWT generation
+- Set up user identification with required fields (userId, name, email, organizationId)
+- Ensure auth token is server-only (VELT_AUTH_TOKEN in .env.local, NOT in client bundle)`,
+  });
 
-    if (!response.ok) {
-      console.error('[Velt] Token API error:', await response.text());
-      return NextResponse.json({ error: 'Failed to generate token' }, { status: 500 });
-    }
+  // Step 4: Configure .env.local
+  steps.push({
+    title: `Set up environment variables`,
+    details: `Create or update \`.env.local\` with your Velt credentials (API key: ${apiKey}).
+Required variables: NEXT_PUBLIC_VELT_API_KEY, VELT_API_KEY, VELT_AUTH_TOKEN.`,
+  });
 
-    const json = await response.json();
-    const token = json?.result?.data?.token;
-    if (!token) {
-      return NextResponse.json({ error: 'Invalid token response' }, { status: 500 });
-    }
+  // Step 5: Set up two-user testing
+  steps.push({
+    title: `Set up two-user testing`,
+    details: `**Skill reference:** \`velt-setup-best-practices\` → debug-multi-user-testing rule
 
-    return NextResponse.json({ token });
-  } catch (error) {
-    console.error('[Velt] Token generation error:', error);
-    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
-  }
-}`,
-      },
-      {
-        description: 'Client-side auth provider with backend token fetch',
-        language: 'typescript',
-        code: `// In VeltInitializeUser.tsx - useVeltAuthProvider hook
-export function useVeltAuthProvider() {
-  const { user } = useAppUser();
-
-  // [Velt] Token generation - calls backend API
-  const generateToken = useCallback(async (): Promise<string> => {
-    const response = await fetch('/api/velt/token', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        userId: user?.userId,
-        organizationId: user?.organizationId,
-        email: user?.email,
-      }),
-    });
-    if (!response.ok) throw new Error('Token fetch failed');
-    const data = await response.json();
-    return data.token;
-  }, [user]);
-
-  const authProvider: VeltAuthProvider | undefined = useMemo(() => {
-    if (!user?.userId) return undefined;
-    return {
-      user: { userId: user.userId, name: user.name, email: user.email, organizationId: user.organizationId },
-      generateToken,
-      retryConfig: { retryCount: 3, retryDelay: 1000 },
-    };
-  }, [user, generateToken]);
-
-  return { authProvider };
-}`,
-      },
-    ],
+The app MUST support testing with two different users. Follow the skill pattern:
+- Provide sign-in buttons for both Alice and Bob
+- Do NOT auto-login with a default user — let the sign-in page render
+- Support \`?user=user-1\` and \`?user=user-2\` URL params for quick switching`,
   });
 
-  // Step 5: Replace API key placeholders
+  // Step 6: Clear .next cache
   steps.push({
-    title: `Replace API key with actual value`,
-    details: `Update all instances of "YOUR_VELT_API_KEY" and "YOUR_VELT_AUTH_TOKEN" with your actual values: ${apiKey}. Make sure to replace in VeltProvider configuration.`,
+    title: `Clear .next build cache before first run`,
+    details: `Run \`rm -rf .next\` before starting the dev server. This prevents stale cache issues after changing imports.`,
   });
 
-  // Step 6: Test the installation
+  // Step 7: Test
   steps.push({
     title: `Test the ${commentTypeTitle} comments functionality`,
-    details: `Start your development server and test ONLY the ${commentType} comments feature. ${getTestInstructions(commentType)} DO NOT test or implement other features.`,
+    details: `Start your development server and test. ${getTestInstructions(commentType)} DO NOT test or implement other features.`,
   });
 
-  // Step 7: Check dev console for errors
+  // Step 8: Check console
   steps.push({
     title: `Check browser console for Velt errors/warnings`,
-    details: `Open browser DevTools Console (Press F12 or Cmd+Option+I on Mac) and look for any Velt errors or warnings. Common errors include: "Please set document id to continue", "Velt API key not found", "Failed to authenticate user". If you find any errors, use the Velt Docs MCP to query for solutions. Example query: "How do I fix 'Please set document id to continue' error in Velt?"`,
+    details: `Open browser DevTools Console and look for Velt errors. Common: "Please set document id", "Velt API key not found", "Failed to authenticate user". If errors occur, consult \`velt-setup-best-practices\` → debug-common-issues rule.`,
   });
 
-  // Additional information
+  // Additional info
   const additionalInfo = [
     {
       title: '🚨 CRITICAL IMPLEMENTATION RULES',
-      content: `**WHAT TO USE FROM CLI:**
-- ✅ Authentication setup (user identification)
-- ✅ Document setup (document context)
-- ✅ API key configuration
-
-**PRIMARY SOURCE: Agent Skills (installed via \`npx skills add velt-js/agent-skills\`):**
-- ✅ **velt-setup-best-practices** — VeltProvider setup, auth, document identity, project structure
-- ✅ **velt-comments-best-practices** — ${commentType} comments implementation patterns and best practices
-- Use skills as your FIRST reference for implementation details
-
-**SECONDARY SOURCE: Docs URLs (only if skills don't cover it):**
-- ${implementation?.mdUrl || getDocMarkdownUrl('comments', commentType)}
-
-**TERTIARY SOURCE: Velt Docs MCP:**
-- Only use for user follow-up questions AFTER implementation
-
-**WHAT NOT TO IMPLEMENT:**
-- ❌ VeltTools component
-- ❌ ui-customization folder (unless user asks)
-- ❌ Components user didn't request
-- ❌ DO NOT copy code from CLI-generated files in components/velt/*`,
-    },
-    {
-      title: 'Additional Features Available',
-      content: `After completing the comments installation, you can add more Velt features:
-
-**Presence (Live Users):**
-- Setup: ${getDocMarkdownUrl('presence', null, 'setup')}
-- Add \`<VeltPresence />\` to show online users with avatars
-- Customize behavior: ${getDocMarkdownUrl('presence', null, 'customizeBehavior')}
-
-**Cursors (Real-time Tracking):**
-- Setup: ${getDocMarkdownUrl('cursors', null, 'setup')}
-- Add \`<VeltCursor />\` to show live cursor positions
-- Customize behavior: ${getDocMarkdownUrl('cursors', null, 'customizeBehavior')}
-
-**Notifications:**
-- Setup: ${getDocMarkdownUrl('notifications', null, 'setup')}
-- Add \`<VeltNotificationsTool />\` for notification bell
-- Customize behavior: ${getDocMarkdownUrl('notifications', null, 'customizeBehavior')}
-
-**Recorder:**
-- Setup: ${getDocMarkdownUrl('recorder', null, 'setup')}
-- Add \`<VeltRecorder />\` for screen/audio recording
-- Customize behavior: ${getDocMarkdownUrl('recorder', null, 'customizeBehavior')}`,
-    },
-    {
-      title: 'Post-Installation: Dev Tools & Troubleshooting',
-      content: `**Check Browser Console:**
-After installation, open your browser DevTools Console (Press F12 or Cmd+Option+I on Mac):
-1. Look for Velt SDK messages (usually prefixed with "[Velt]")
-2. Check for warnings about configuration issues
-3. Verify API key is loaded correctly
-4. Watch for authentication errors or document ID issues
-
-**Common Console Warnings:**
-- "Velt API key not found" - Check that YOUR_VELT_API_KEY was replaced
-- "Failed to authenticate user" - Verify auth token and user setup
-- "Document ID missing" - Ensure document context is initialized
-
-**Get Help:**
-- For questions or issues AFTER installation, use the Velt Docs MCP server
-- Query example: "How do I fix authentication errors in Velt?"
-- The Velt Docs MCP has up-to-date solutions for common issues`,
-    },
-    {
-      title: 'Documentation Reference',
-      content: `**Primary: Agent Skills (installed via \`npx skills add velt-js/agent-skills\`)**
-- **velt-setup-best-practices** — VeltProvider, auth, document identity, project structure
-- **velt-comments-best-practices** — ${commentType} comments implementation patterns
-
-**Secondary: Docs URLs**
-- This feature: ${implementation?.mdUrl || getDocMarkdownUrl('comments', commentType)}
-- Pattern: https://docs.velt.dev/[feature]/[page].md
-
-**Tertiary: Velt Docs MCP**
-After installation, query the Velt Docs MCP server for:
-- Feature customization
-- Troubleshooting
-- Advanced configuration
-- Integration patterns
-Do NOT query during initial implementation — use Agent Skills first.`,
+      content: `**Source priority:** Agent Skills > Embedded Rules > Docs URLs
+- ✅ **velt-setup-best-practices** — VeltProvider, auth, document identity, project structure
+- ✅ **velt-comments-best-practices** — ${commentType} comments implementation patterns
+- Do NOT reimplement patterns from scratch — follow the skill rules exactly`,
     },
   ];
 
-  // Generate skills source section
-  const skillsSection = formatSkillsSourceSection(['comments'], { commentType });
-
-  const basePlan = formatInstallationPlan({
+  // Format and add skills section
+  const plan = formatInstallationPlan({
     title: `Plan for Velt ${commentTypeTitle} Comments Installation`,
     steps,
     additionalInfo,
   });
 
-  // Insert skills section right after the title line
-  const titleEnd = basePlan.indexOf('\n\n') + 2;
-  return basePlan.slice(0, titleEnd) + skillsSection + basePlan.slice(titleEnd);
+  const skillsSection = formatSkillsSourceSection(['comments'], { commentType });
+  return plan + '\n' + skillsSection;
 }
 
-/**
- * Gets CSS position styles for header positioning
- */
-function getPositionStyles(position) {
-  const styles = {
-    'top-left': 'top: \'20px\',\n    left: \'20px\',',
-    'top-right': 'top: \'20px\',\n    right: \'20px\',',
-    'bottom-left': 'bottom: \'20px\',\n    left: \'20px\',',
-    'bottom-right': 'bottom: \'20px\',\n    right: \'20px\',',
-  };
-  return styles[position] || styles['top-right'];
-}
 
 /**
- * Gets test instructions for a comment type
- */
-function getTestInstructions(commentType) {
-  const instructions = {
-    freestyle: 'Click the Comment Tool button, then click anywhere on the page to add a comment.',
-    popover: 'Click the Comment Tool button next to an element to attach a comment to it.',
-    page: 'Open the Comments Sidebar and add a page-level comment at the bottom.',
-    stream: 'Select text to see comments appear in the stream column on the right.',
-    text: 'Highlight any text to see the Comment Tool button appear, then click it to add a comment.',
-    inline: 'Navigate to your content area and test adding inline comments.',
-    tiptap: 'Open your Tiptap editor, select text, and add comments using the Velt comment integration.',
-    lexical: 'Open your Lexical editor, select text, and add comments using the Velt comment integration.',
-    slate: 'Open your Slate.js editor, select text, and add comments using the Velt comment integration.',
-  };
-  return instructions[commentType] || 'Test adding comments in your application.';
-}
-
-/**
- * Creates a comprehensive plan for multiple Velt features
+ * Creates a comprehensive plan for multiple Velt features.
  *
  * @param {Object} options - Installation options
- * @param {string[]} options.features - Features to install (comments, presence, cursors, notifications, recorder, crdt)
- * @param {string} options.commentType - Type of comments (if comments feature is included)
- * @param {string} options.crdtEditorType - CRDT editor type (tiptap, codemirror, blocknote)
- * @param {Object} options.implementation - Comment implementation details from Velt Docs
- * @param {Object} options.crdtImplementation - CRDT implementation details from Velt Docs
- * @param {Object} options.featureImplementations - Other feature implementations from Velt Docs
- * @param {Array} options.detectedFiles - Files detected for modification
- * @param {string} options.apiKey - API key preview
- * @param {string} options.headerPosition - Header position
- * @param {string} options.veltProviderLocation - Where to install VeltProvider
  * @returns {string} Formatted installation plan
  */
 export function createMultiFeaturePlan(options) {
@@ -705,6 +248,8 @@ export function createMultiFeaturePlan(options) {
     apiKey,
     headerPosition,
     veltProviderLocation = 'app/page.tsx',
+    frameworkInfo,
+    wiring,
   } = options;
 
   const steps = [];
@@ -723,753 +268,205 @@ export function createMultiFeaturePlan(options) {
   if (hasRecorder) featureList.push('Recorder');
   if (hasCRDT) featureList.push(`CRDT (${crdtEditorType ? crdtEditorType.charAt(0).toUpperCase() + crdtEditorType.slice(1) : 'Collaborative Editing'})`);
 
-  // Add warning about only implementing requested features
-  steps.push({
-    title: `⚠️ CRITICAL: Only implement ${featureList.join(', ')}`,
-    details: `You are ONLY installing: ${featureList.join(', ')}. DO NOT implement any other components unless the user specifically requested them. Only use authentication, user setup, and document setup from CLI. Get implementation details from markdown URLs at docs.velt.dev.`,
-  });
-
-  // Step 2: Add VeltProvider
-  const componentsToAdd = [];
-  if (hasComments) componentsToAdd.push('VeltComments');
-  if (hasPresence) componentsToAdd.push('VeltPresence');
-  if (hasCursors) componentsToAdd.push('VeltCursor');
-  if (hasNotifications) componentsToAdd.push('VeltNotificationsTool');
-  if (hasRecorder) componentsToAdd.push('VeltRecorder');
-
   const locationText = veltProviderLocation === 'auto-detect'
-    ? 'the appropriate layout file (analyze the project structure to determine the best location)'
+    ? 'the appropriate page file'
     : veltProviderLocation;
 
+  // Step 1: Scope warning
   steps.push({
-    title: `Import and use CLI-generated Velt components in ${locationText}`,
-    details: `The Velt CLI has generated the necessary component files in \`components/velt/\`. DO NOT create new files. Use the existing files:
-
-**CLI-Generated Files:**
-- \`components/velt/VeltInitializeUser.tsx\` - Exports \`useVeltAuthProvider\` hook (NOT a wrapper component)
-- \`components/velt/VeltInitializeDocument.tsx\` - Exports \`useCurrentDocument\` hook for document context
-- \`components/velt/VeltCollaboration.tsx\` - Velt feature components (comments, presence, etc.)
-- \`app/userAuth/AppUserContext.tsx\` - User context provider wrapper
-- \`app/userAuth/useAppUser.tsx\` - User data hook (add TODOs here)
-- \`app/api/velt/token/route.ts\` - Token generation API
-
-⚠️ **CRITICAL ARCHITECTURE (Sample App Pattern):**
-
-**1. app/layout.tsx - Wrap with AppUserProvider:**
-\`\`\`tsx
-import { AppUserProvider } from './userAuth/AppUserContext'
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <AppUserProvider>
-          {children}
-        </AppUserProvider>
-      </body>
-    </html>
-  )
-}
-\`\`\`
-**Why**: AppUserProvider provides user context to all components including Velt auth.
-
-**2. app/page.tsx (or root page) - VeltProvider with authProvider hook:**
-\`\`\`tsx
-"use client";
-import { VeltProvider } from '@veltdev/react';
-import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
-import { useCurrentDocument } from '@/components/velt/VeltInitializeDocument';
-import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
-
-const VELT_API_KEY = process.env.NEXT_PUBLIC_VELT_API_KEY!;
-
-export default function Page() {
-  const { authProvider } = useVeltAuthProvider();
-  const { documentId } = useCurrentDocument();
-
-  return (
-    <VeltProvider apiKey={VELT_API_KEY} authProvider={authProvider}>
-      <VeltCollaboration documentId={documentId} />
-      {/* Your page content */}
-    </VeltProvider>
-  );
-}
-\`\`\`
-**Why**: VeltProvider must be in page.tsx with authProvider from hook, NOT nested wrapper components.
-
-**What to do:**
-1. Add AppUserProvider wrapper to app/layout.tsx
-2. Add VeltProvider to ${locationText} using useVeltAuthProvider hook
-3. Import VeltCollaboration for feature components
-4. Follow the markdown documentation for feature-specific implementation
-
-⚠️ **CRITICAL: Position ALL Velt Components in User's Chosen Corner:**
-All Velt feature components (presence, notifications, comments sidebar, etc.) should be placed in the SAME corner that the user specified. This creates a consistent, grouped UI.
-
-**Position based on user's chosen corner:**
-- **top-left**: \`fixed top-4 left-4\`
-- **top-right**: \`fixed top-4 right-4\`
-- **bottom-left**: \`fixed bottom-4 left-4\`
-- **bottom-right**: \`fixed bottom-4 right-4\`
-
-\`\`\`tsx
-// VeltCollaboration.tsx - Place ALL Velt components in the chosen corner
-export function VeltCollaboration({ documentId }: { documentId: string }) {
-  return (
-    <>
-      {/* [Velt] ALL features grouped in user's chosen corner */}
-      <div className="fixed [POSITION] z-50 flex flex-col gap-2">
-        {/* Presence avatars */}
-        <VeltPresence flockMode={false} maxUsers={5} />
-
-        {/* Notifications bell */}
-        <VeltNotificationsTool />
-
-        {/* Comments sidebar trigger (if using comments) */}
-        <VeltCommentsSidebar />
-      </div>
-
-      {/* Cursors render across the whole page */}
-      <VeltCursor />
-
-      {/* Comments tool for freestyle comments */}
-      <VeltCommentTool />
-    </>
-  );
-}
-\`\`\`
-
-**Replace [POSITION] with user's choice:**
-- top-left → \`top-4 left-4\`
-- top-right → \`top-4 right-4\`
-- bottom-left → \`bottom-4 left-4\`
-- bottom-right → \`bottom-4 right-4\`
-
-**Why**: Grouping all Velt features in one corner creates a clean, consistent UI. Without positioned containers, Velt components create a white bar at the top of the page.
-
-Also add to globals.css or VeltCustomization.css:
-\`\`\`css
-/* Remove default white background from Velt components */
-velt-presence-container,
-velt-presence-container *,
-velt-notifications-tool-container,
-velt-notifications-tool-container *,
-velt-comments-sidebar-container,
-velt-comments-sidebar-container * {
-  background: transparent !important;
-}
-\`\`\`
-
-**CRITICAL - For Tiptap/Lexical/Slate Comments:**
-- ✅ **FIND EXISTING EDITOR** - Search the project for existing Tiptap/Lexical/Slate editor components
-- ✅ **INTEGRATE INTO EXISTING EDITOR** - Add Velt comments to the existing editor, DO NOT create a new editor
-- ✅ **USE BUBBLE MENU PATTERN** - Add comment button to bubble menu (appears on text selection), NOT a fixed toolbar
-- ✅ Use ONLY the comment-specific package: @veltdev/tiptap-velt-comments, @veltdev/lexical-velt-comments, or @veltdev/slate-velt-comments
-- ❌ DO NOT create a new editor component if one already exists
-- ❌ DO NOT create a fixed toolbar with Bold/Italic/Comment buttons
-- ❌ DO NOT use CRDT packages (@veltdev/tiptap-velt-collaboration or similar)
-- ❌ DO NOT implement real-time collaborative editing - only comments on the editor
-
-**Tiptap Pattern:**
-\`\`\`tsx
-import { BubbleMenu } from '@tiptap/react'
-import { TiptapVeltComments, addComment, renderComments } from '@veltdev/tiptap-velt-comments'
-import { useCommentAnnotations } from '@veltdev/react'
-
-// Add to editor extensions: TiptapVeltComments
-// Use BubbleMenu component with comment button
-<BubbleMenu editor={editor}>
-  <button onClick={() => addComment({ editor })}>💬 Comment</button>
-</BubbleMenu>
-\`\`\`
-
-**Lexical Pattern:**
-- Add VeltCommentsPlugin to editor plugins
-- Use custom bubble menu that appears on selection
-- Trigger addComment() from bubble menu button
-
-**Slate Pattern:**
-- Wrap editor with withVeltComments()
-- Implement bubble menu with position tracking on selection
-- Trigger addComment({ editor }) from bubble menu button
-
-**If NO existing editor found:** Provide minimal integration example with bubble menu, but recommend user add to their existing editor.
-
-**IMPORTANT:** All Velt-related files should remain in \`components/velt/\`. Do not create new Velt files outside this folder.
-
-${hasCRDT && crdtEditorType ? `
-**CRITICAL - For ${crdtEditorType.charAt(0).toUpperCase() + crdtEditorType.slice(1)} CRDT (Collaborative Real-Time Document Editing):**
-${crdtEditorType === 'tiptap' ? `- ✅ **Required Packages:**
-  - @veltdev/tiptap-crdt-react (exact version: 4.5.8)
-  - @veltdev/tiptap-crdt (exact version: 4.5.8)
-  - @tiptap/y-tiptap (for Yjs integration)
-  - yjs (CRDT framework)
-  - y-prosemirror (ProseMirror bindings for Yjs)
-
-⚠️ **CRITICAL: ID MAPPING PATTERN (FireHydrant Pattern):**
-- **documentId**: Set via VeltInitializeDocument - one per page/resource (e.g., \`retrospective-123\`)
-- **editorId**: Unique per editor instance - use format \`\${documentId}/\${fieldId}\` (e.g., \`retrospective-123/question-456\`)
-- **Why**: This allows multiple editors per document, each with independent CRDT state
-
-⚠️ **CRITICAL STARTERKIT CONFIGURATION:**
-- ❌ **WRONG**: \`StarterKit.configure({ history: false })\` - DO NOT USE "history"
-- ✅ **CORRECT**: \`StarterKit.configure({ undoRedo: false })\`
-- **Why**: StarterKit doesn't have a "history" option. Use "undoRedo" instead. CRDT handles undo/redo.
-
-⚠️ **CRITICAL INITIAL CONTENT:**
-- ❌ **WRONG**: \`content: initialContent\` in useEditor
-- ✅ **CORRECT**: \`// content: initialContent\` (comment it out)
-- **Why**: Let CRDT handle initial content loading. Seed from backend only when CRDT doc is empty.
-
-⚠️ **CRITICAL AUTO-SAVE PATTERN (FireHydrant Pattern):**
-- ✅ Use 2-second debounce to avoid excessive backend saves
-- ✅ Detect remote syncs: check \`transaction.getMeta('y-sync$')\`, \`transaction.getMeta('remote')\`, \`transaction.getMeta('velt-sync')\`, \`transaction.getMeta('isRemote')\`
-- ✅ Skip saving for remote syncs (these are changes from other users)
-- ✅ Only save local changes to backend
-
-⚠️ **CRITICAL BACKEND CONTENT SEEDING:**
-- ✅ When CRDT doc is empty AND backend has content, seed once
-- ✅ Use \`useServerConnectionStateChangeHandler()\` to check connection is 'online' before seeding
-- ✅ Track seeding state with ref to avoid double-seeding
-
-⚠️ **CRITICAL COMMENTS EXTENSION (if adding comments to CRDT editor):**
-- ❌ **WRONG**: \`TiptapVeltComments.configure({ editorId, HTMLAttributes })\`
-- ✅ **CORRECT**: \`TiptapVeltComments\` (no .configure())
-- **Why**: The extension works without configuration
-
-**Tiptap CRDT Pattern (PRODUCTION CODE - FireHydrant Pattern):**
-\`\`\`tsx
-import { useEffect, useRef, useMemo } from 'react';
-import { useEditor, EditorContent } from '@tiptap/react';
-import StarterKit from '@tiptap/starter-kit';
-import { useVeltTiptapCrdtExtension } from '@veltdev/tiptap-crdt-react';
-import { useServerConnectionStateChangeHandler } from '@veltdev/react';
-
-interface TipTapCollabEditorProps {
-  documentId: string;  // From VeltInitializeDocument context
-  fieldId: string;     // Unique field ID within document
-  backendfallbackContent?: any;  // Backend content for seeding
-  onUpdate?: (params: { fieldId: string; value: any }) => void;
-}
-
-export function TipTapCollabEditor({
-  documentId,
-  fieldId,
-  backendfallbackContent,
-  onUpdate,
-}: TipTapCollabEditorProps) {
-  const saveTimeoutRef = useRef<NodeJS.Timeout | null>(null);
-  const hasSeededContentRef = useRef(false);
-  const isEditorReadyRef = useRef(false);
-
-  // [Velt] CRITICAL: Combine documentId and fieldId for unique editorId
-  const editorId = \`\${documentId}/\${fieldId}\`;
-
-  // [Velt] Format initial content for CRDT
-  const veltInitialContent = useMemo(() => {
-    if (!backendfallbackContent) return undefined;
-    if (Array.isArray(backendfallbackContent)) {
-      return { type: 'doc', content: backendfallbackContent };
-    }
-    return backendfallbackContent;
-  }, [backendfallbackContent]);
+    title: `⚠️ CRITICAL: Only implement ${featureList.join(', ')}`,
+    details: `You are ONLY installing: ${featureList.join(', ')}. DO NOT implement any other components unless the user specifically requested them.`,
+  });
 
-  // [Velt] Initialize CRDT extension with unique editorId
-  const { VeltCrdt, isLoading } = useVeltTiptapCrdtExtension({
-    editorId,
-    initialContent: veltInitialContent,
+  // Step 2: Wire VeltProvider + CLI components
+  steps.push({
+    title: `Wire VeltProvider and CLI-generated components in ${locationText}`,
+    details: `**Skill reference:** \`velt-setup-best-practices\` → provider-wiring, identity rules
+
+Use the CLI-generated files in \`components/velt/\`. Wire them following the skill patterns:
+- Import \`useVeltAuthProvider\` from \`components/velt/VeltInitializeUser.tsx\`
+- Import \`VeltCollaboration\` from \`components/velt/VeltCollaboration.tsx\`
+- Wrap your page content with \`<VeltProvider apiKey={...} authProvider={authProvider}>\`
+- Place \`<VeltCollaboration />\` inside the VeltProvider
+- The page file MUST have \`"use client"\` directive (Next.js)
+- VeltProvider goes in \`${locationText}\`, NOT in layout.tsx (layout.tsx exports metadata)
+- Position Velt UI components (presence, notifications, sidebar) in the ${headerPosition} corner
+
+**IMPORTANT:** Do NOT create new Velt files. Use the CLI-generated files in \`components/velt/\`.`,
   });
 
-  // [Velt] Monitor server connection state
-  const serverConnectionState = useServerConnectionStateChangeHandler();
-
-  const editor = useEditor({
-    extensions: [
-      StarterKit.configure({
-        undoRedo: false,  // CRITICAL: CRDT handles undo/redo
-      }),
-      ...(VeltCrdt ? [VeltCrdt] : []),
-    ],
-    // content: initialContent,  // CRITICAL: comment out - CRDT manages content
-    immediatelyRender: false,
-    onUpdate: ({ editor, transaction }) => {
-      // [Velt] CRITICAL: Detect remote syncs - skip saving these
-      const isRemoteSync =
-        transaction.getMeta('y-sync$') ||
-        transaction.getMeta('remote') ||
-        transaction.getMeta('velt-sync') ||
-        transaction.getMeta('isRemote');
-      if (isRemoteSync) return;
-
-      // [Velt] Debounced auto-save (2 seconds)
-      if (saveTimeoutRef.current) clearTimeout(saveTimeoutRef.current);
-      if (transaction.docChanged && isEditorReadyRef.current) {
-        saveTimeoutRef.current = setTimeout(() => {
-          const content = editor.getJSON()?.content || [];
-          onUpdate?.({ fieldId, value: content });
-        }, 2000);
-      }
-    },
-  }, [VeltCrdt]);
-
-  // [Velt] Seed from backend when CRDT doc is empty
-  useEffect(() => {
-    if (
-      editor && !isLoading &&
-      serverConnectionState === 'online' &&
-      !hasSeededContentRef.current &&
-      isEditorEmpty(editor) &&
-      hasBackendContent(backendfallbackContent)
-    ) {
-      hasSeededContentRef.current = true;
-      setTimeout(() => {
-        if (editor && !editor.isDestroyed) {
-          editor.commands.setContent(backendfallbackContent);
-          isEditorReadyRef.current = true;
-        }
-      }, 100);
-    } else if (editor && !isLoading && serverConnectionState === 'online') {
-      isEditorReadyRef.current = true;
+  // Step 3: CRDT editor setup (conditional)
+  if (hasCRDT && crdtEditorType) {
+    const editorName = crdtEditorType.charAt(0).toUpperCase() + crdtEditorType.slice(1);
+
+    let skillRules = '';
+    let requirements = '';
+
+    if (crdtEditorType === 'tiptap') {
+      skillRules = 'tiptap-setup-react, tiptap-editor-id, tiptap-disable-history, tiptap-initial-content';
+      requirements = `- Use \`useVeltTiptapCrdtExtension\` hook with editorId = \`\${documentId}/\${fieldId}\`
+- Disable \`undoRedo\` in StarterKit (NOT \`history\` — StarterKit has no "history" option)
+- Use HTML strings for initialContent, NOT JSON objects (see tiptap-initial-content rule)
+- Set \`immediatelyRender: false\` in useEditor options
+- CRDT extension should be LAST in the extensions array`;
+    } else if (crdtEditorType === 'codemirror') {
+      skillRules = 'codemirror-setup-react, codemirror-ycollab, codemirror-editor-id';
+      requirements = `- Use \`useVeltCodeMirrorCrdtExtension\` hook
+- Wire yCollab extension with store.getYText() and store.getAwareness()
+- Use store.getUndoManager() for undo/redo`;
+    } else if (crdtEditorType === 'blocknote') {
+      skillRules = 'blocknote-setup-react, blocknote-editor-id';
+      requirements = `- Use \`useVeltBlockNoteCrdtExtension\` hook
+- Pass collaborationConfig to useCreateBlockNote
+- BlockNote handles CRDT automatically with the config`;
     }
-  }, [editor, isLoading, serverConnectionState, backendfallbackContent]);
 
-  if (isLoading) return <div>Loading...</div>;
-  return <EditorContent editor={editor} />;
-}
-
-// Helper functions
-const isEditorEmpty = (editor) => {
-  const json = editor?.getJSON();
-  if (!json?.content?.length) return true;
-  if (json.content.length === 1 && json.content[0].type === 'paragraph' && !json.content[0].content?.length) return true;
-  return false;
-};
-const hasBackendContent = (content) => content && !(Array.isArray(content) && content.length === 0);
-\`\`\`
-` : ''}${crdtEditorType === 'codemirror' ? `- ✅ Package: @veltdev/codemirror-crdt-react
-- ✅ Hook: useVeltCodeMirrorCrdtExtension({ editorId, initialContent })
-- ✅ Returns: { store, isLoading }
-- ✅ Use store.getYText(), store.getAwareness(), store.getUndoManager()
-- ✅ Requires y-codemirror.next package for yCollab
-
-**CodeMirror CRDT Pattern:**
-\`\`\`tsx
-import { useVeltCodeMirrorCrdtExtension } from '@veltdev/codemirror-crdt-react'
-import { yCollab } from 'y-codemirror.next'
-import { EditorState } from '@codemirror/state'
-import { EditorView } from 'codemirror'
-
-const { store, isLoading } = useVeltCodeMirrorCrdtExtension({
-  editorId: 'codemirror-editor-1',
-  initialContent: yourInitialContent
-})
-
-// In useEffect:
-const startState = EditorState.create({
-  doc: store.getYText()?.toString() ?? '',
-  extensions: [
-    // ... other extensions
-    yCollab(store.getYText()!, store.getAwareness(), {
-      undoManager: store.getUndoManager()
-    }),
-  ],
-})
-
-const view = new EditorView({ state: startState, parent: editorRef.current })
-\`\`\`
-` : ''}${crdtEditorType === 'blocknote' ? `- ✅ Package: @veltdev/blocknote-crdt-react
-- ✅ Hook: useVeltBlockNoteCrdtExtension({ editorId, initialContent })
-- ✅ Returns: { collaborationConfig, isLoading }
-- ✅ Pass collaborationConfig to useCreateBlockNote
-- ✅ BlockNote handles CRDT automatically with the config
-
-**BlockNote CRDT Pattern:**
-\`\`\`tsx
-import { useVeltBlockNoteCrdtExtension } from '@veltdev/blocknote-crdt-react'
-import { useCreateBlockNote } from '@blocknote/react'
-import { BlockNoteView } from '@blocknote/mantine'
-
-const { collaborationConfig, isLoading } = useVeltBlockNoteCrdtExtension({
-  editorId: 'blocknote-editor-1',
-  initialContent: JSON.stringify([{ type: "paragraph", content: "" }])
-})
-
-const editor = useCreateBlockNote({
-  collaboration: collaborationConfig,
-}, [collaborationConfig])
-
-return <BlockNoteView editor={editor} />
-\`\`\`
-` : ''}
-` : ''}
-**Get implementation details from markdown docs:**
-${hasComments ? `- Comments (${commentType}): ${implementation?.mdUrl || getDocMarkdownUrl('comments', commentType)}${implementation?.source ? ` (fetched from ${implementation.source})` : ''}\n` : ''}${hasPresence ? `- Presence: ${featureImplementations.presence?.mdUrl || getDocMarkdownUrl('presence')}${featureImplementations.presence?.source ? ` (fetched from ${featureImplementations.presence.source})` : ''}\n` : ''}${hasCursors ? `- Cursors: ${featureImplementations.cursors?.mdUrl || getDocMarkdownUrl('cursors')}${featureImplementations.cursors?.source ? ` (fetched from ${featureImplementations.cursors.source})` : ''}\n` : ''}${hasNotifications ? `- Notifications: ${featureImplementations.notifications?.mdUrl || getDocMarkdownUrl('notifications')}${featureImplementations.notifications?.source ? ` (fetched from ${featureImplementations.notifications.source})` : ''}\n` : ''}${hasRecorder ? `- Recorder: ${featureImplementations.recorder?.mdUrl || getDocMarkdownUrl('recorder')}${featureImplementations.recorder?.source ? ` (fetched from ${featureImplementations.recorder.source})` : ''}\n` : ''}${hasCRDT && crdtEditorType ? `- CRDT (${crdtEditorType}): ${crdtImplementation?.mdUrl || getDocMarkdownUrl('crdt', crdtEditorType)}${crdtImplementation?.source ? ` (fetched from ${crdtImplementation.source})` : ''}\n` : ''}`,
-    codeExamples: [
-      {
-        description: `Correct pattern: VeltProvider in page.tsx with authProvider hook`,
-        language: 'tsx',
-        code: `// app/page.tsx (or your root page component)
-"use client";
-import { VeltProvider } from '@veltdev/react';
-import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
-import { useCurrentDocument } from '@/components/velt/VeltInitializeDocument';
-import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
-
-const VELT_API_KEY = process.env.NEXT_PUBLIC_VELT_API_KEY!;
-
-export default function Page() {
-  const { authProvider } = useVeltAuthProvider();
-  const { documentId } = useCurrentDocument();
-
-  return (
-    <VeltProvider apiKey={VELT_API_KEY} authProvider={authProvider}>
-      <VeltCollaboration documentId={documentId} />
-      {/* Your page content here */}
-    </VeltProvider>
-  );
-}
+    steps.push({
+      title: `Create ${editorName} CRDT editor component`,
+      details: `**Skill reference:** \`velt-crdt-best-practices\` → ${skillRules}
 
-// Get component implementations from markdown docs above`,
-      },
-    ],
-  });
+Create \`components/velt/${editorName}CollabEditor.tsx\` following the skill patterns.
 
-  // Step 3: Set up authentication and user identification with TODOs
-  steps.push({
-    title: `Add TODO comments to CLI-generated authentication files`,
-    details: `The Velt CLI has generated authentication files in specific locations. Add TODO comments to these existing files (DO NOT create new files):
-
-**1. User Hook: \`app/userAuth/useAppUser.tsx\`**
-   - This file already exists from CLI
-   - Add TODO: Connect to your existing authentication system
-   - Add TODO: Replace mock user data with actual user from your auth provider
-   - Examples: Next-auth useSession(), Clerk useUser(), Auth0, etc.
-
-**2. Auth Provider: \`components/velt/VeltInitializeUser.tsx\`**
-   - This file already exists from CLI (references useAppUser)
-   - Contains \`useVeltAuthProvider\` hook
-   - File location may vary, look for useVeltAuthProvider hook
-
-**3. Document Hook: Check for \`app/document/useCurrentDocument.tsx\`**
-   - May be in CLI-generated files or needs to be created
-   - Add TODO: Implement document identification logic
-   - Add TODO: Return unique document ID based on current page/route
-   - Examples: router.query.id, pathname, page slug
-
-**4. Token API: \`app/api/velt/token/route.ts\`**
-   - This file already exists from CLI
-   - Add TODO: Connect to your backend authentication
-   - Add TODO: Validate user session before generating token
-
-**IMPORTANT:** Only modify CLI-generated files. Do not create new files. Keep all Velt code in \`components/velt/\` and the specified locations.
-
-**FOR TESTING PRESENCE/CURSORS:** Add logic to test with multiple users:
-1. Hardcode a fixed document ID (e.g., "demo-document") so all tabs use the same document
-2. Provide 2 hardcoded users (user-1 and user-2) with different names/avatars
-3. Allow switching users via URL parameter (?user=1 or ?user=2) to test presence/cursors
-4. Open multiple browser tabs with different user parameters to see live presence and cursors`,
-    codeExamples: [
-      {
-        description: 'Example: Hardcoded document ID and multiple users for testing',
-        language: 'typescript',
-        code: `// In useCurrentDocument.tsx - Hardcode document ID for testing:
-export function useCurrentDocument() {
-  // [Velt] HARDCODED for testing presence/cursors
-  // TODO: Replace with dynamic document ID based on your routing
-  const documentId = "demo-document"; // Fixed ID so all tabs see same document
-
-  return { documentId, documentName: "Demo Document" };
-}
+Requirements:
+${requirements}`,
+    });
+  }
 
-// In useAppUser.tsx - Multiple users for testing:
-export function useAppUser() {
-  // [Velt] HARDCODED USERS for testing presence/cursors
-  // TODO: Replace with actual user from your auth provider
-
-  // Get user from URL parameter (?user=1 or ?user=2)
-  const searchParams = typeof window !== 'undefined'
-    ? new URLSearchParams(window.location.search)
-    : null;
-  const userParam = searchParams?.get('user') || '1';
-
-  const users = {
-    '1': {
-      userId: "user-1",
-      name: "Demo User 1",
-      email: "user1@example.com",
-      photoUrl: "https://i.pravatar.cc/150?img=1",
-      organizationId: "demo-org",
-    },
-    '2': {
-      userId: "user-2",
-      name: "Demo User 2",
-      email: "user2@example.com",
-      photoUrl: "https://i.pravatar.cc/150?img=2",
-      organizationId: "demo-org",
-    }
-  };
+  // Step 4: Comments integration with editor (conditional)
+  if (hasComments && hasCRDT && crdtEditorType) {
+    steps.push({
+      title: `MANDATORY: Integrate TiptapVeltComments extension in editor`,
+      details: `**Skill reference:** \`velt-crdt-best-practices\` → tiptap-comments-integration rule
 
-  const user = users[userParam] || users['1'];
+⚠️ WITHOUT THIS, THE APP WILL FREEZE WHEN COMMENTS ARE TRIGGERED.
 
-  return { user, isUserLoggedIn: true };
-}
+The global \`<VeltComments>\` component is necessary but NOT sufficient for editor comments.
+You MUST also:
+- Add \`TiptapVeltComments\` to the editor's extensions array (BEFORE the CRDT extension)
+- Import and call \`highlightComments(editor, commentAnnotations)\` in a useEffect (v4 API)
+- Import and use \`triggerAddComment(editor)\` for the comment button (v4 API)
+- Import \`useCommentAnnotations\` from \`@veltdev/react\` to subscribe to comment data
 
-// TESTING INSTRUCTIONS:
-// 1. Open http://localhost:3000?user=1 in one tab
-// 2. Open http://localhost:3000?user=2 in another tab
-// 3. You should see 2 different avatars in presence
-// 4. Move mouse in one tab to see cursor in the other tab`,
-      },
-      {
-        description: 'Example TODO comments to add',
-        language: 'typescript',
-        code: `// In useAppUser.tsx:
-// TODO: Connect to your authentication system
-// TODO: Replace this mock user data with actual user from your auth provider
-// Example: const user = useAuth(); // Your auth hook
-// Example: const user = useSession(); // Next-auth
-// Example: const user = useUser(); // Clerk, Auth0, etc.
-
-// In useCurrentDocument.tsx:
-// TODO: Implement document identification logic
-// TODO: Return a unique document ID based on your app's routing
-// Example: Use route params, URL, page ID, etc.
-// Example: const documentId = router.query.id;
-// Example: const documentId = \`page-\${pathname}\`;
-
-// In app/api/velt/auth/route.ts:
-// TODO: SECURITY - Validate user session before generating token
-// TODO: Connect to your backend authentication
-// TODO: Verify user is authenticated and authorized
-
-// If JWT generation is present:
-// TODO: SECURITY - Replace 'your-secret-key' with actual secret
-// TODO: Store secret in environment variables (process.env.JWT_SECRET)
-// TODO: NEVER commit secrets to version control
-// TODO: Implement token expiration (expiresIn: '24h')`,
-      },
-    ],
-  });
+Check your installed package version — v4 uses \`triggerAddComment\`/\`highlightComments\`, v5 uses \`addComment\`/\`renderComments\`.`,
+    });
+  }
 
-  // Step 4: Implement JWT token generation (Production Pattern)
-  steps.push({
-    title: `Implement JWT token generation via Velt API (Production Pattern)`,
-    details: `The CLI generates a placeholder JWT route. Replace it with the production pattern that calls Velt's token API.
+  // Step 5: SSR safety (conditional, Next.js + Tiptap)
+  if (hasCRDT && crdtEditorType === 'tiptap') {
+    steps.push({
+      title: `MANDATORY: Load editor with next/dynamic (SSR safety)`,
+      details: `**Skill reference:** \`velt-crdt-best-practices\` → tiptap-nextjs-ssr rule
 
-**Production Pattern (FireHydrant Reference):**
-Server-side API calls Velt's token endpoint to generate secure JWT tokens.
+Tiptap and @veltdev/tiptap-velt-comments use browser-only APIs. In Next.js, the editor component MUST be loaded with \`next/dynamic\` and \`ssr: false\` in the page that renders it. Without this, the app will crash with a \`g.catch is not a function\` error.
 
-**Velt Token API:**
-\`\`\`
-POST https://api.velt.dev/v2/auth/token/get
-Headers:
-  x-velt-api-key: YOUR_VELT_PUBLIC_API_KEY
-  x-velt-auth-token: YOUR_VELT_AUTH_TOKEN (keep secret!)
-Body:
-  { "data": { "userId": "...", "userProperties": { "organizationId": "...", "email": "..." } } }
-Response:
-  { "result": { "data": { "token": "eyJ..." } } }
-\`\`\`
+In your page file, use \`dynamic(() => import(...), { ssr: false })\` — do NOT import the editor component directly.`,
+    });
+  }
 
-**Environment Variables to Set:**
-\`\`\`
-VELT_PUBLIC_API_KEY=your_api_key_here
-VELT_AUTH_TOKEN=your_auth_token_here  # NEVER expose to client!
-\`\`\`
+  // Step 6: Cursor CSS (conditional)
+  if (hasCRDT && crdtEditorType === 'tiptap') {
+    steps.push({
+      title: `MANDATORY: Add collaboration cursor CSS to globals.css`,
+      details: `**Skill reference:** \`velt-crdt-best-practices\` → tiptap-cursor-css rule
 
-**Security Requirements:**
-- Keep VELT_AUTH_TOKEN server-side only (never expose to client)
-- Validate user session before generating tokens
-- The auth token should only be used in API routes, not client components`,
-    codeExamples: [
-      {
-        description: 'Production API Route: app/api/velt/token/route.ts',
-        language: 'typescript',
-        code: `import { NextRequest, NextResponse } from 'next/server';
-
-// [Velt] JWT Token Generation - Production Pattern
-const VELT_API_KEY = process.env.VELT_PUBLIC_API_KEY;
-const VELT_AUTH_TOKEN = process.env.VELT_AUTH_TOKEN;
-
-export async function POST(request: NextRequest) {
-  try {
-    // [Velt] TODO: Add user session validation here
-    // const session = await getServerSession(authOptions);
-    // if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-
-    const body = await request.json();
-    const { userId, organizationId, email } = body;
-
-    if (!userId) {
-      return NextResponse.json({ error: 'userId is required' }, { status: 400 });
-    }
+Without this CSS, remote user cursors appear as thick full-width blocks instead of thin carets.
 
-    if (!VELT_API_KEY || !VELT_AUTH_TOKEN) {
-      console.error('[Velt] Missing VELT_PUBLIC_API_KEY or VELT_AUTH_TOKEN');
-      return NextResponse.json({ error: 'Velt credentials not configured' }, { status: 500 });
-    }
+Follow the skill rule exactly — it targets BOTH:
+- \`.ProseMirror-yjs-cursor\` classes (from y-prosemirror, used by Velt CRDT)
+- \`.collaboration-cursor__caret\` classes (from @tiptap/extension-collaboration-cursor)
 
-    // [Velt] Call Velt Token API
-    const response = await fetch('https://api.velt.dev/v2/auth/token/get', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-velt-api-key': VELT_API_KEY,
-        'x-velt-auth-token': VELT_AUTH_TOKEN,
-      },
-      body: JSON.stringify({
-        data: {
-          userId,
-          userProperties: { organizationId: organizationId || 'default-org', email: email || '' },
-        },
-      }),
+Critical: the \`> span { display: inline !important }\` rule is required to prevent block-level rendering.`,
     });
+  }
 
-    if (!response.ok) {
-      console.error('[Velt] Token API error:', await response.text());
-      return NextResponse.json({ error: 'Failed to generate token' }, { status: 500 });
-    }
+  // Step 7: Authentication setup
+  steps.push({
+    title: `Set up authentication and JWT token generation`,
+    details: `**Skill reference:** \`velt-setup-best-practices\` → identity-jwt-generation, identity-user-object-shape rules
 
-    const json = await response.json();
-    const token = json?.result?.data?.token;
-    if (!token) {
-      return NextResponse.json({ error: 'Invalid token response' }, { status: 500 });
-    }
+Follow the skill patterns to:
+- Configure \`app/api/velt/token/route.ts\` for server-side JWT generation
+- Set up user identification with required fields (userId, name, email, organizationId)
+- Ensure auth token is server-only (VELT_AUTH_TOKEN in .env.local, NOT in client bundle)`,
+  });
 
-    return NextResponse.json({ token });
-  } catch (error) {
-    console.error('[Velt] Token generation error:', error);
-    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
-  }
-}`,
-      },
-      {
-        description: 'Client-side auth provider with backend token fetch',
-        language: 'typescript',
-        code: `// In VeltInitializeUser.tsx - useVeltAuthProvider hook
-export function useVeltAuthProvider() {
-  const { user } = useAppUser();
-
-  // [Velt] Token generation - calls backend API
-  const generateToken = useCallback(async (): Promise<string> => {
-    const response = await fetch('/api/velt/token', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        userId: user?.userId,
-        organizationId: user?.organizationId,
-        email: user?.email,
-      }),
-    });
-    if (!response.ok) throw new Error('Token fetch failed');
-    const data = await response.json();
-    return data.token;
-  }, [user]);
-
-  const authProvider: VeltAuthProvider | undefined = useMemo(() => {
-    if (!user?.userId) return undefined;
-    return {
-      user: { userId: user.userId, name: user.name, email: user.email, organizationId: user.organizationId },
-      generateToken,
-      retryConfig: { retryCount: 3, retryDelay: 1000 },
-    };
-  }, [user, generateToken]);
-
-  return { authProvider };
-}`,
-      },
-    ],
+  // Step 8: Environment variables
+  steps.push({
+    title: `Set up environment variables`,
+    details: `Create or update \`.env.local\` with your Velt credentials (API key: ${apiKey}).
+Required variables: NEXT_PUBLIC_VELT_API_KEY, VELT_API_KEY, VELT_AUTH_TOKEN.`,
   });
 
-  // Step 5: Replace API key placeholders
+  // Step 9: Two-user testing
   steps.push({
-    title: `Replace API keys with actual values`,
-    details: `Update all instances of "YOUR_VELT_API_KEY" and "YOUR_VELT_AUTH_TOKEN" with your actual values: ${apiKey}. Make sure to replace in VeltProvider configuration.`,
+    title: `Set up two-user testing`,
+    details: `**Skill reference:** \`velt-setup-best-practices\` → debug-multi-user-testing rule
+
+The app MUST support testing with two different users. Follow the skill pattern:
+- Provide sign-in buttons for both Alice and Bob
+- Do NOT auto-login with a default user — if the scaffolding has \`params.get("user") || "user-1"\`, remove the \`|| "user-1"\` default
+- Support \`?user=user-1\` and \`?user=user-2\` URL params for quick switching`,
   });
 
-  // Step 6: Test the installation
+  // Step 10: Clear .next cache
+  steps.push({
+    title: `Clear .next build cache before first run`,
+    details: `Run \`rm -rf .next\` before starting the dev server. This prevents stale cache issues, especially after changing SSR patterns (adding \`next/dynamic\`).`,
+  });
+
+  // Step 11: Test
   const testInstructions = [];
   if (hasComments) testInstructions.push(`${commentType} comments: ${getTestInstructions(commentType)}`);
   if (hasPresence) testInstructions.push('Presence: Check that user avatars appear in the presence component');
-  if (hasCursors) testInstructions.push('Cursors: Open in two browser windows and move your mouse to see cursors');
+  if (hasCursors) testInstructions.push('Cursors: Open in two browser windows and verify thin caret cursors with name labels');
   if (hasNotifications) testInstructions.push('Notifications: Check the notification bell icon appears');
   if (hasRecorder) testInstructions.push('Recorder: Check the recorder controls appear');
 
   steps.push({
     title: `Test all requested features`,
-    details: `Start your development server and test ONLY the features you requested:\n${testInstructions.map(t => `- ${t}`).join('\n')}\n\nDO NOT test or implement other features.`,
+    details: `Start your development server and test:\n${testInstructions.map(t => `- ${t}`).join('\n')}\n\nDO NOT test or implement other features.`,
   });
 
-  // Step 7: Check dev console for errors
+  // Step 12: Check console
   steps.push({
     title: `Check browser console for Velt errors/warnings`,
-    details: `Open browser DevTools Console (Press F12 or Cmd+Option+I on Mac) and look for any Velt errors or warnings. Common errors include: "Please set document id to continue", "Velt API key not found", "Failed to authenticate user". If you find any errors, use the Velt Docs MCP to query for solutions.`,
+    details: `Open browser DevTools Console and look for Velt errors. Common: "Please set document id", "Velt API key not found", "Failed to authenticate user". If errors occur, consult \`velt-setup-best-practices\` → debug-common-issues rule.`,
   });
 
-  // Additional information
+  // Additional info
+  const skillsList = [];
+  skillsList.push('- ✅ **velt-setup-best-practices** — VeltProvider, auth, document identity, project structure');
+  if (hasComments) skillsList.push(`- ✅ **velt-comments-best-practices** — ${commentType} comments implementation patterns`);
+  if (hasCRDT) skillsList.push(`- ✅ **velt-crdt-best-practices** — ${crdtEditorType || 'collaborative editing'} CRDT patterns`);
+  if (hasNotifications) skillsList.push('- ✅ **velt-notifications-best-practices** — notifications setup and customization');
+
   const additionalInfo = [
     {
       title: '🚨 CRITICAL IMPLEMENTATION RULES',
-      content: `**WHAT TO USE FROM CLI:**
-- ✅ Authentication setup (user identification)
-- ✅ Document setup (document context)
-- ✅ API key configuration
-
-**PRIMARY SOURCE: Agent Skills (installed via \`npx skills add velt-js/agent-skills\`):**
-- ✅ **velt-setup-best-practices** — VeltProvider setup, auth, document identity, project structure
-${hasComments ? `- ✅ **velt-comments-best-practices** — ${commentType} comments implementation patterns\n` : ''}${hasCRDT ? `- ✅ **velt-crdt-best-practices** — ${crdtEditorType || 'collaborative editing'} CRDT patterns\n` : ''}${hasNotifications ? `- ✅ **velt-notifications-best-practices** — notifications setup and customization\n` : ''}- Use skills as your FIRST reference for implementation details
-
-**SECONDARY SOURCE: Docs URLs (for features without skills coverage):**
-${hasPresence ? `- Presence: ${featureImplementations.presence?.mdUrl || getDocMarkdownUrl('presence')}\n` : ''}${hasCursors ? `- Cursors: ${featureImplementations.cursors?.mdUrl || getDocMarkdownUrl('cursors')}\n` : ''}${hasRecorder ? `- Recorder: ${featureImplementations.recorder?.mdUrl || getDocMarkdownUrl('recorder')}\n` : ''}${!hasPresence && !hasCursors && !hasRecorder ? `- All selected features are covered by Agent Skills\n` : ''}
-**TERTIARY SOURCE: Velt Docs MCP:**
-- Only use for user follow-up questions AFTER implementation
-
-**WHAT NOT TO IMPLEMENT:**
-- ❌ VeltTools component (unless explicitly requested)
-- ❌ ui-customization folder (unless user asks)
-- ❌ Components user didn't request
-- ❌ DO NOT copy code from CLI-generated files in components/velt/*`,
-    },
-    {
-      title: 'Documentation References',
-      content: `**Primary: Agent Skills (installed via \`npx skills add velt-js/agent-skills\`)**
-- velt-setup-best-practices — setup, provider, auth, document
-${hasComments ? `- velt-comments-best-practices — ${commentType} comments\n` : ''}${hasCRDT ? `- velt-crdt-best-practices — ${crdtEditorType || 'collaborative editing'}\n` : ''}${hasNotifications ? `- velt-notifications-best-practices — notifications\n` : ''}
-**Secondary: Docs URLs (for features without skills)**
-${hasPresence ? `- Presence: ${featureImplementations.presence?.mdUrl || getDocMarkdownUrl('presence')}\n` : ''}${hasCursors ? `- Cursors: ${featureImplementations.cursors?.mdUrl || getDocMarkdownUrl('cursors')}\n` : ''}${hasRecorder ? `- Recorder: ${featureImplementations.recorder?.mdUrl || getDocMarkdownUrl('recorder')}\n` : ''}All Velt docs available as markdown at: https://docs.velt.dev/[feature]/[page].md
-${hasCRDT && crdtImplementation?.data?.markdown ? `\n**CRDT Implementation Details (from ${crdtImplementation.source}):**\n${crdtImplementation.data.markdown.substring(0, 2000)}${crdtImplementation.data.markdown.length > 2000 ? '...\n\n[See full documentation at: ' + crdtImplementation.mdUrl + ']' : ''}\n` : ''}
-**Tertiary: Velt Docs MCP**
-After installation, query the Velt Docs MCP server for customization, troubleshooting, and advanced configuration. Do NOT use during initial implementation if skills cover the feature.`,
+      content: `**Source priority:** Agent Skills > Embedded Rules > Docs URLs
+
+${skillsList.join('\n')}
+
+- Do NOT reimplement patterns from scratch — follow the skill rules exactly
+- If a skill rule and this plan conflict, the skill rule is correct
+- Do NOT create files outside \`components/velt/\` unless necessary for app-specific wiring`,
     },
   ];
 
-  // Generate skills source section
-  const skillsSection = formatSkillsSourceSection(features, { commentType, crdtEditorType });
-
-  const basePlan = formatInstallationPlan({
-    title: `Plan for Velt Installation: ${featureList.join(', ')}`,
+  // Format and add skills section
+  const plan = formatInstallationPlan({
+    title: `Plan for Velt ${featureList.join(' + ')} Installation`,
     steps,
     additionalInfo,
   });
 
-  // Insert skills section right after the title line
-  const titleEnd = basePlan.indexOf('\n\n') + 2;
-  return basePlan.slice(0, titleEnd) + skillsSection + basePlan.slice(titleEnd);
+  const skillsSection = formatSkillsSourceSection(features, { commentType, crdtEditorType });
+  return plan + '\n' + skillsSection;
 }
 
+
 /**
- * Creates CLI-only installation report with TODO checklist
- *
- * Used when user types SKIP at feature selection.
- * Returns a checklist of what was created and what user needs to do.
- *
- * @param {Object} options
- * @param {Object} options.cliResult - Result from Velt CLI execution
- * @param {Object} options.qaResult - Basic QA validation results
- * @param {string} options.apiKey - API key (masked)
- * @param {string} [options.cliMethod] - CLI execution method ('linked' or 'direct')
- * @param {Object} [options.frameworkInfo] - Framework detection info
- * @returns {string} Markdown report
+ * Creates a CLI-only installation report (SKIP mode).
  */
 export function createCliOnlyReport({ cliResult, qaResult, apiKey, cliMethod, frameworkInfo }) {
   const validationLines = qaResult.checks.map(c => {
@@ -1477,12 +474,8 @@ export function createCliOnlyReport({ cliResult, qaResult, apiKey, cliMethod, fr
     return `- ${icon} **${c.name}**: ${c.message}`;
   }).join('\n');
 
-  // CLI execution method info
-  const cliMethodInfo = cliMethod
-    ? '**CLI Method:** npx @velt-js/add-velt'
-    : '';
+  const cliMethodInfo = cliMethod ? '**CLI Method:** npx @velt-js/add-velt' : '';
 
-  // Framework info
   const frameworkInfoSection = frameworkInfo
     ? `**Framework:** ${frameworkInfo.projectType}${frameworkInfo.needsUseClient ? ' (with "use client" enforcement)' : ''}`
     : '';
@@ -1520,168 +513,24 @@ ${validationLines}
 
 ---
 
-## 📋 TODO Checklist (You Need To Complete)
-
-### 1. Verify @veltdev/react is installed
-
-The CLI should have installed \`@veltdev/react\`. If not, run:
-\`\`\`bash
-npm install @veltdev/react
-\`\`\`
-
-### 2. Configure environment variables
-
-Create or update \`.env.local\`:
-
-\`\`\`env
-NEXT_PUBLIC_VELT_API_KEY=${apiKey}
-\`\`\`
-
-### 3. Set up app/layout.tsx with AppUserProvider
-
-Wrap your app with AppUserProvider for user context:
-
-\`\`\`tsx
-// app/layout.tsx
-import { AppUserProvider } from './userAuth/AppUserContext';
+## 📋 Next Steps
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <AppUserProvider>
-          {children}
-        </AppUserProvider>
-      </body>
-    </html>
-  );
-}
-\`\`\`
-
-### 4. Set up app/page.tsx with VeltProvider
-
-Add VeltProvider to your root page using the authProvider hook:
-
-\`\`\`tsx
-// app/page.tsx
-"use client";
-import { VeltProvider } from '@veltdev/react';
-import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
-import { useCurrentDocument } from '@/components/velt/VeltInitializeDocument';
-import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
-
-const VELT_API_KEY = process.env.NEXT_PUBLIC_VELT_API_KEY!;
-
-export default function Page() {
-  const { authProvider } = useVeltAuthProvider();
-  const { documentId } = useCurrentDocument();
+**Skill reference:** Install agent-skills via \`npx skills add velt-js/agent-skills\`, then follow:
+- \`velt-setup-best-practices\` — for VeltProvider wiring, auth, document setup
+- \`velt-comments-best-practices\` — for comments integration
+- \`velt-crdt-best-practices\` — for CRDT/collaborative editing
+- \`velt-notifications-best-practices\` — for notifications
 
-  return (
-    <VeltProvider apiKey={VELT_API_KEY} authProvider={authProvider}>
-      <VeltCollaboration documentId={documentId} />
-      {/* Your page content */}
-    </VeltProvider>
-  );
-}
-\`\`\`
-
-### 5. Configure user authentication
-
-Edit \`app/userAuth/useAppUser.tsx\` to connect your auth:
-
-\`\`\`tsx
-// TODO: Replace hardcoded user with your auth provider
-// Examples:
-// - Next-Auth: const { data: session } = useSession();
-// - Clerk: const { user } = useUser();
-// - Auth0: const { user } = useAuth0();
-
-const user = {
-  userId: "your-user-id",       // Required: unique user ID
-  name: "User Name",            // Required: display name
-  email: "user@example.com",    // Required: email
-  photoUrl: "https://...",      // Optional: avatar URL
-  organizationId: "your-org",   // Optional: for multi-tenant apps
-};
-\`\`\`
-
-### 6. Configure document identification
-
-Edit \`components/velt/VeltInitializeDocument.tsx\` to set document ID in the useCurrentDocument hook:
-
-\`\`\`tsx
-// TODO: Replace with your document ID logic
-// The document ID determines which users see each other's comments/cursors
-// Examples:
-// - Page-based: const documentId = pathname;
-// - Route param: const documentId = params.id;
-// - Custom: const documentId = getCurrentProjectId();
-
-const documentId = "your-document-id";
-\`\`\`
-
-### 6. Add Velt feature components
-
-Add specific features where needed in your app:
-
-\`\`\`tsx
-import { VeltComments, VeltPresence, VeltCursor } from '@veltdev/react';
-
-// Comments - add where you want commenting
-<VeltComments />
-
-// Presence - shows online users
-<VeltPresence />
-
-// Cursors - shows live cursor positions
-<VeltCursor />
-\`\`\`
-
----
-
-## 🔗 Documentation
-
-- **Quick Start:** https://docs.velt.dev/get-started/quickstart
-- **Authentication:** https://docs.velt.dev/get-started/quickstart#step-5-authenticate-users
-- **Document Setup:** https://docs.velt.dev/get-started/quickstart#step-6-initialize-document
-- **Comments:** https://docs.velt.dev/async-collaboration/comments/setup
-- **Presence:** https://docs.velt.dev/realtime-collaboration/presence/setup
-- **Cursors:** https://docs.velt.dev/realtime-collaboration/cursors/setup
-
----
-
-## 🚀 Next Steps
-
-**Option A: Manual Setup**
-Follow the TODO checklist above to wire up Velt features yourself.
-
-**Option B: Guided Setup**
-Re-run the installer and select specific features (don't type SKIP):
-\`\`\`
-@velt-installer install
-\`\`\`
-
-The guided mode will:
-- Generate a detailed implementation plan for your selected features
-- Detect your project structure and recommend file placements
-- Provide feature-specific code examples from Velt docs
-- Apply changes only after your approval
+Or re-run the installer with specific features (don't type SKIP) for guided setup.
 
 ---
 
 ## ⚠️ Common Issues
 
-**"Velt API key not found"**
-- Make sure \`NEXT_PUBLIC_VELT_API_KEY\` is in your \`.env.local\`
-- Restart your dev server after adding environment variables
-
-**"Please set document id to continue"**
-- Ensure \`VeltInitializeDocument\` is properly configured with a document ID
-- The document ID should be unique per collaborative context
-
-**"Failed to authenticate user"**
-- Check that your user data includes required fields: \`userId\`, \`name\`, \`email\`
-- Verify the auth token is correct in your environment variables
+Consult \`velt-setup-best-practices\` → debug-common-issues rule for:
+- "Velt API key not found" — check .env.local
+- "Please set document id" — check VeltInitializeDocument
+- "Failed to authenticate user" — check user object fields
 
 ---