From 0e42cc73c7dd62684750d47d6d8f64046a55ed3c Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 09:56:11 -0300
Subject: [PATCH 1/7] feat: Add animated command showcase with working tabs to
 homepage

- Replace static command showcase with animated session visualization
- Add 5 interactive command scenarios (/ask, /ticket/plan, /pr/create, /review, /dev)
- Each scenario shows agent type, thinking process, tool calls, and output
- Implement typewriter effect and step-by-step animations
- Add visual effects: drifting grid, rotating orbits, pulsing glows
- Include TUI-style navigation hints (Parent/Prev/Next)
---
 .../web/src/components/CommandShowcase.astro  | 1189 +++++++++++++----
 .../web/src/layouts/MarketingLayout.astro     |    2 +-
 packages/web/src/pages/index.astro            |    2 +-
 3 files changed, 895 insertions(+), 298 deletions(-)

diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index c914fa9..bac48ea 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -1,273 +1,218 @@
 ---
-const scenarios = [
-  {
-    id: "ask",
-    label: "/ask",
-    prompt: "/ask how does command config merging work?",
-    notes: [
-      "# load only the relevant project context",
-      "# answer directly without drifting into implementation"
-    ],
-    tools: ["read", "grep", "task(explore)"],
-    output: [
-      "> loaded config and command registry context",
-      "> returned a concise project-grounded answer"
-    ]
-  },
-  {
-    id: "branch",
-    label: "/branch",
-    prompt: "/branch docs site refresh",
-    notes: [
-      "# summarize uncommitted work",
-      "# create a categorized branch name from the change themes"
-    ],
-    tools: ["changes_load", "bash(git checkout -b)"],
-    output: [
-      "> created branch: docs/site-refresh",
-      "> switched from main to the new work branch"
-    ]
-  },
-  {
-    id: "commit",
-    label: "/commit",
-    prompt: "/commit",
-    notes: [
-      "# inspect staged and unstaged changes",
-      "# generate a why-focused commit message"
-    ],
-    tools: ["changes_load(uncommitted)", "bash(git add)", "bash(git commit)"],
-    output: [
-      "> staged relevant files",
-      "> created a new commit with generated message"
-    ]
-  },
-  {
-    id: "commit-and-push",
-    label: "/commit-and-push",
-    prompt: "/commit-and-push",
-    notes: [
-      "# commit the current work",
-      "# push the branch upstream in one pass"
-    ],
-    tools: ["changes_load(uncommitted)", "bash(git add)", "bash(git commit)", "bash(git push)"],
-    output: [
-      "> committed current changes",
-      "> pushed branch to origin"
-    ]
-  },
-  {
-    id: "dev",
-    label: "/dev",
-    prompt: "/dev implement the approved workflow in packages/core",
-    notes: [
-      "# load ticket context only when the request looks like a ticket source",
-      "# edit only the relevant files and validate the result"
-    ],
-    tools: ["read", "apply_patch", "bash(validation)", "task(worker)"],
-    output: [
-      "> implemented focused code changes",
-      "> returned validation results and PR handoff notes"
-    ]
-  },
-  {
-    id: "learn",
-    label: "/learn",
-    prompt: "/learn how AGENTS.md conventions are used here",
-    notes: [
-      "# inspect existing patterns in the repo",
-      "# extract reusable guidance into AGENTS.md targets"
-    ],
-    tools: ["read(AGENTS.md)", "grep", "apply_patch"],
-    output: [
-      "> summarized established conventions",
-      "> updated agent guidance where the pattern belongs"
-    ]
-  },
-  {
-    id: "reload",
-    label: "/reload",
-    prompt: "/reload",
-    notes: [
-      "# refresh config, commands, agents, and tools",
-      "# use after changing kompass config or templates"
-    ],
-    tools: ["reload"],
-    output: [
-      "> refreshed the active OpenCode project cache",
-      "> new config is ready without restarting"
-    ]
-  },
-  {
-    id: "pr-create",
-    label: "/pr/create",
-    prompt: "/pr/create",
-    notes: [
-      "# summarize branch work and resolve ticket handling",
-      "# push if needed, then publish a structured PR"
-    ],
-    tools: ["changes_load", "question", "ticket_sync", "bash(git push)", "pr_sync"],
-    output: [
-      "> created PR body with ticket, description, and checklist",
-      "> returned the PR URL and push status"
-    ]
-  },
-  {
-    id: "pr-fix",
-    label: "/pr/fix",
-    prompt: "/pr/fix",
-    notes: [
-      "# load PR history and outstanding feedback",
-      "# review proposed fixes with the user unless auto mode was requested"
-    ],
-    tools: ["pr_load", "apply_patch", "bash(validation)", "question", "bash(git push)", "pr_sync"],
-    output: [
-      "> fixed requested issues on the branch",
-      "> posted replies to the relevant review threads"
-    ]
-  },
-  {
-    id: "pr-review",
-    label: "/pr/review",
-    prompt: "/pr/review",
-    notes: [
-      "# load pr, reviews, comments, files, and diff context",
-      "# if the pr references a ticket, load that ticket too before reviewing"
-    ],
-    tools: ["pr_load", "ticket_load", "changes_load", "task(reviewer)", "pr_sync"],
-    output: [
-      "> added inline comments and review summary",
-      "> approved or requested changes based on the findings"
-    ]
-  },
-  {
-    id: "review",
-    label: "/review",
-    prompt: "/review",
-    notes: [
-      "# auto-discover uncommitted or branch comparison scope",
-      "# return findings without mutating the working tree"
-    ],
-    tools: ["changes_load", "read(changed files)", "task(reviewer)"],
-    output: [
-      "> produced a concise branch review",
-      "> highlighted issues, risks, and follow-ups"
-    ]
-  },
-  {
-    id: "ship",
-    label: "/ship",
-    prompt: "/ship",
-    notes: [
-      "# create a work branch when current changes are still on the base branch",
-      "# delegate commit and pr creation as a fast path to shipping"
-    ],
-    tools: ["dispatch(/branch)", "dispatch(/commit)", "dispatch(/pr/create)"],
-    output: [
-      "> moved the branch through commit and PR creation",
-      "> returned the final PR handoff"
-    ]
-  },
-  {
-    id: "rmslop",
-    label: "/rmslop",
-    prompt: "/rmslop",
-    notes: [
-      "# inspect the branch for unnecessary complexity",
-      "# simplify code, prompts, and workflow glue where possible"
-    ],
-    tools: ["changes_load", "read(changed files)", "apply_patch", "bash(validation)", "bash(git commit)"],
-    output: [
-      "> removed unnecessary code and duplication",
-      "> left a smaller, clearer diff"
-    ]
-  },
+// Command showcase with working tabs - each command shows its own scenario
+interface ToolCall {
+  tool: string;
+  args: string;
+  status: 'pending' | 'running' | 'complete';
+}
+
+interface SessionStep {
+  id: string;
+  phase: 'thinking' | 'tool_calls' | 'output';
+  content?: string;
+  toolCalls?: ToolCall[];
+  output?: string[];
+}
+
+interface CommandScenario {
+  id: string;
+  label: string;
+  command: string;
+  agentName: string;
+  task: string;
+  steps: SessionStep[];
+}
+
+const scenarios: CommandScenario[] = [
   {
-    id: "todo",
-    label: "/todo",
-    prompt: "/todo @TODO.md",
-    notes: [
-      "# load the todo list and keep orchestration local",
-      "# ask for plan approval before implementation starts"
-    ],
-    tools: ["read", "dispatch(/ticket/plan)", "question", "dispatch(/dev)", "dispatch(/commit)"],
-    output: [
-      "> completed the current todo item",
-      "> reported what is done, blocked, or next"
+    id: 'ask',
+    label: '/ask',
+    command: '/ask is this project cool?',
+    agentName: 'Build Agent',
+    task: 'Answer questions about the current project or code',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Evaluating project appeal — need to determine if this project is cool by inspecting repository structure, README, and command architecture. Will check relevant files and keep analysis concise.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'glob', args: 'README* in . (5 matches)', status: 'complete' },
+          { tool: 'read', args: 'package.json', status: 'complete' },
+          { tool: 'read', args: 'README.md [limit=220]', status: 'complete' },
+          { tool: 'read', args: 'packages/core/README.md [limit=220]', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'It has a clear point of view: keep AI coding agents "on course" with token-efficient, composable workflows instead of giant ad-hoc prompts.',
+          'The repo is structured thoughtfully: shared logic lives in packages/core, adapter-specific wiring in packages/opencode.',
+          'The command surface is unusually coherent — /ask, /review, /pr/create, /ticket/plan all fit the same workflow philosophy.',
+          'No additional steps are required.'
+        ]
+      }
     ]
   },
   {
-    id: "ticket-ask",
-    label: "/ticket/ask",
-    prompt: "/ticket/ask #128 what changed since the first draft?",
-    notes: [
-      "# load the ticket plus discussion history",
-      "# answer with repo-aware context and post back to the ticket"
-    ],
-    tools: ["ticket_load", "read", "grep", "ticket_sync"],
-    output: [
-      "> generated a contextual answer",
-      "> posted the response as a ticket comment"
+    id: 'ticket-plan',
+    label: '/ticket/plan',
+    command: '/ticket/plan #128 rollout the new review workflow',
+    agentName: 'Planner',
+    task: 'Turn a request or ticket into a scoped implementation plan',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Planning the rollout — need to break down the review workflow into actionable steps. Will examine existing patterns and create a scoped plan with clear milestones.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'ticket_load', args: '#128', status: 'complete' },
+          { tool: 'read', args: 'packages/core/commands/pr/review.md', status: 'complete' },
+          { tool: 'glob', args: 'packages/core/components/*.md', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Phase 1: Extract reusable review components from existing commands',
+          'Phase 2: Update navigator agent to coordinate review workflows',
+          'Phase 3: Add checklist generation and feedback threading',
+          'Plan ready for implementation. No additional steps required.'
+        ]
+      }
     ]
   },
   {
-    id: "ticket-create",
-    label: "/ticket/create",
-    prompt: "/ticket/create",
-    notes: [
-      "# auto-discover current change comparison when no base was passed",
-      "# create a structured issue with checklist sections"
-    ],
-    tools: ["changes_load", "ticket_sync"],
-    output: [
-      "> created a GitHub issue with scoped checklist items",
-      "> returned the new ticket reference"
+    id: 'pr-create',
+    label: '/pr/create',
+    command: '/pr/create',
+    agentName: 'Navigator',
+    task: 'Summarize branch work and publish a structured PR',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Creating PR — need to load branch changes, check for linked tickets, and generate a structured PR description with checklist sections.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'changes_load', args: 'HEAD...main', status: 'complete' },
+          { tool: 'ticket_load', args: '#42', status: 'complete' },
+          { tool: 'bash', args: 'git push origin HEAD', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Created PR #47: Add workflow visualization to homepage',
+          'Linked to ticket #42 with structured checklist',
+          'PR body includes summary, changes, and testing notes',
+          'No additional steps are required.'
+        ]
+      }
     ]
   },
   {
-    id: "ticket-dev",
-    label: "/ticket/dev",
-    prompt: "/ticket/dev #128",
-    notes: [
-      "# load the ticket, create a plan, then execute the work",
-      "# keep ticket context attached throughout implementation"
-    ],
-    tools: ["ticket_load", "dispatch(/dev)", "dispatch(/branch)", "dispatch(/commit-and-push)", "dispatch(/pr/create)"],
-    output: [
-      "> produced an implementation plan and finished the requested work",
-      "> returned validation notes and PR-ready context"
+    id: 'review',
+    label: '/review',
+    command: '/review',
+    agentName: 'Reviewer',
+    task: 'Review branch changes without editing files',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Reviewing changes — need to load the diff context and examine modified files for potential issues, risks, and improvements without making edits.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'changes_load', args: 'uncommitted', status: 'complete' },
+          { tool: 'read', args: 'packages/web/src/components/CommandShowcase.astro', status: 'complete' },
+          { tool: 'task', args: 'reviewer analysis', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Strong separation of concerns between scenarios and rendering',
+          'Consider adding error handling for failed tool calls',
+          'Animation timing is appropriate for the UX flow',
+          'No additional steps are required.'
+        ]
+      }
     ]
   },
   {
-    id: "ticket-plan",
-    label: "/ticket/plan",
-    prompt: "/ticket/plan #128 rollout the new review workflow",
-    notes: [
-      "# load ticket context, comments, and attached constraints",
-      "# draft a scoped plan before any code changes happen"
-    ],
-    tools: ["ticket_load", "changes_load", "task(planner)"],
-    output: [
-      "> created a detailed implementation plan",
-      "> stored the result as a reusable handoff"
+    id: 'dev',
+    label: '/dev',
+    command: '/dev implement the approved workflow in packages/core',
+    agentName: 'Worker',
+    task: 'Implement approved plans with validation',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Implementing workflow — loading ticket context and executing the approved plan. Will edit only relevant files and validate changes as I go.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'ticket_load', args: '#128', status: 'complete' },
+          { tool: 'apply_patch', args: 'packages/core/commands/pr/review.md', status: 'complete' },
+          { tool: 'bash', args: 'npm run typecheck', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Implemented review workflow in packages/core/commands/pr/',
+          'Added navigator coordination and feedback threading',
+          'All validation checks passed successfully',
+          'No additional steps are required.'
+        ]
+      }
     ]
   }
 ];
+
+const allCommands = [
+  "/ask", "/branch", "/commit", "/commit-and-push", "/dev", "/learn", 
+  "/reload", "/pr/create", "/pr/fix", "/pr/review", "/review", "/ship",
+  "/rmslop", "/todo", "/ticket/ask", "/ticket/create", "/ticket/dev", "/ticket/plan"
+];
 ---
 
 <div class="command-showcase" data-command-showcase>
-  <div class="command-showcase__ambient" aria-hidden="true">
-    <div class="command-showcase__glow"></div>
+  <div class="command-showcase__background" aria-hidden="true">
     <div class="command-showcase__grid"></div>
+    <div class="command-showcase__glow command-showcase__glow--top"></div>
+    <div class="command-showcase__glow command-showcase__glow--bottom"></div>
     <div class="command-showcase__orbit command-showcase__orbit--outer"></div>
     <div class="command-showcase__orbit command-showcase__orbit--inner"></div>
-    <div class="command-showcase__beam"></div>
   </div>
 
-  <div class="command-showcase__panel">
-      <div class="command-showcase__tabs" role="tablist" aria-label="Command examples">
-        {scenarios.map((scenario, index) => (
-        <button
+  <div class="command-showcase__main">
+    <!-- Tab navigation -->
+    <div class="command-strip" role="tablist" aria-label="Command examples">
+      {scenarios.map((scenario, index) => (
+        <button 
           type="button"
           class:list={{ "command-tab": true, "is-active": index === 0 }}
           role="tab"
@@ -281,69 +226,721 @@ const scenarios = [
       ))}
     </div>
 
-    <div class="command-terminal">
-      <div class="command-terminal__head">
-        <span></span>
-        <span></span>
-        <span></span>
-        <p>expected run</p>
-      </div>
-
-      {scenarios.map((scenario, index) => (
-        <section
-          class:list={{ "command-terminal__view": true, "is-active": index === 0 }}
-          role="tabpanel"
-          aria-labelledby={`tab-${scenario.id}`}
-          id={`panel-${scenario.id}`}
-          data-command-panel={scenario.id}
-          hidden={index === 0 ? undefined : true}
-        >
-          <p class="command-terminal__prompt"><span>$</span> {scenario.prompt}</p>
-          <div class="command-terminal__notes">
-            {scenario.notes.map((item) => <p>{item}</p>)}
-          </div>
-          <div class="command-terminal__meta">
-            <div>
-              <p class="command-terminal__label">Tool calls</p>
-              <ul class="command-terminal__tool-list">
-                {scenario.tools.map((tool) => <li>{tool}</li>)}
-              </ul>
+    <!-- All scenario panels -->
+    {scenarios.map((scenario, index) => (
+      <div 
+        class:list={{ "scenario-panel": true, "is-active": index === 0 }}
+        role="tabpanel"
+        aria-labelledby={`tab-${scenario.id}`}
+        id={`panel-${scenario.id}`}
+        data-scenario-panel={scenario.id}
+        hidden={index !== 0}
+      >
+        <div class="session-terminal">
+          <div class="session-terminal__header">
+            <div class="session-terminal__window-controls">
+              <span></span>
+              <span></span>
+              <span></span>
+            </div>
+            <div class="session-terminal__title">
+              <span class="session-terminal__status" data-status-dot></span>
+              <span data-session-title>{scenario.agentName}</span>
+            </div>
+            <div class="session-terminal__meta">
+              <span data-tool-count>0 toolcalls</span>
+              <span data-session-time>0.0s</span>
             </div>
           </div>
-          <div class="command-terminal__output">
-            {scenario.output.map((item) => <p>{item}</p>)}
+
+          <div class="session-terminal__body">
+            <!-- Command Input -->
+            <div class="session-line session-line--input">
+              <span class="session-line__prompt">$</span>
+              <span class="session-line__command" data-typewriter>{scenario.command}</span>
+            </div>
+
+            <!-- Task Description -->
+            <div class="session-line session-line--task">
+              <span class="session-line__icon">◆</span>
+              <span>{scenario.task}</span>
+            </div>
+
+            <!-- Session Steps -->
+            <div class="session-steps" data-session-steps>
+              {scenario.steps.map((step) => (
+                <div class="session-step" data-step={step.id}>
+                  {step.phase === 'thinking' && step.content && (
+                    <div class="thinking-block">
+                      <div class="thinking-block__header">
+                        <span class="thinking-block__indicator">
+                          <span class="thinking-block__pulse"></span>
+                        </span>
+                        <span class="thinking-block__label">Thinking</span>
+                      </div>
+                      <p class="thinking-block__content">{step.content}</p>
+                    </div>
+                  )}
+
+                  {step.phase === 'tool_calls' && step.toolCalls && (
+                    <div class="tool-calls-block">
+                      <div class="tool-calls-block__header">
+                        <span class="tool-calls-block__icon">▸</span>
+                        <span class="tool-calls-block__label">Explored</span>
+                        <span class="tool-calls-block__count">{step.toolCalls.length} reads, 1 search</span>
+                      </div>
+                      <div class="tool-calls-block__list">
+                        {step.toolCalls.map((tool) => (
+                          <div class="tool-call" data-tool-status={tool.status}>
+                            <span class="tool-call__arrow">→</span>
+                            <span class="tool-call__name">{tool.tool}</span>
+                            <span class="tool-call__args">{tool.args}</span>
+                          </div>
+                        ))}
+                      </div>
+                    </div>
+                  )}
+
+                  {step.phase === 'output' && step.output && (
+                    <div class="output-block">
+                      {step.output.map((line) => (
+                        <p class="output-block__line">{line}</p>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              ))}
+            </div>
+
+            <!-- Navigation hint -->
+            <div class="session-nav-hint">
+              <span>Parent <kbd>↑</kbd></span>
+              <span>Prev <kbd>←</kbd></span>
+              <span>Next <kbd>→</kbd></span>
+            </div>
           </div>
-        </section>
+        </div>
+      </div>
+    ))}
+
+    <!-- All commands strip (decorative) -->
+    <div class="all-commands" aria-hidden="true">
+      {allCommands.map((cmd) => (
+        <span class="command-pill-decorative">{cmd}</span>
       ))}
     </div>
   </div>
 </div>
 
 <script>
-  const root = document.querySelector<HTMLElement>("[data-command-showcase]");
-
-  if (root) {
-    const tabs = Array.from(root.querySelectorAll<HTMLElement>("[data-command-tab]"));
-    const panels = Array.from(root.querySelectorAll<HTMLElement>("[data-command-panel]"));
-
-    const activate = (id: string | undefined) => {
-      if (!id) return;
+  // Typewriter effect
+  function typewriter(element: HTMLElement, text: string, speed: number = 30) {
+    let i = 0;
+    element.textContent = '';
+    return new Promise<void>((resolve) => {
+      const timer = setInterval(() => {
+        if (i < text.length) {
+          element.textContent += text.charAt(i);
+          i++;
+        } else {
+          clearInterval(timer);
+          resolve();
+        }
+      }, speed);
+    });
+  }
 
-      tabs.forEach((tab) => {
-        const active = tab.dataset.commandTab === id;
-        tab.classList.toggle("is-active", active);
-        tab.setAttribute("aria-selected", active ? "true" : "false");
-      });
+  // Reset and animate a scenario panel
+  async function animateScenario(panel: HTMLElement) {
+    const typewriterEl = panel.querySelector('[data-typewriter]') as HTMLElement;
+    const steps = panel.querySelectorAll('[data-step]');
+    const statusDot = panel.querySelector('[data-status-dot]') as HTMLElement;
+    const toolCount = panel.querySelector('[data-tool-count]') as HTMLElement;
+    const sessionTime = panel.querySelector('[data-session-time]') as HTMLElement;
+    const navHint = panel.querySelector('.session-nav-hint') as HTMLElement;
+    
+    // Reset all animations
+    steps.forEach(step => step.classList.remove('is-visible'));
+    panel.querySelectorAll('.tool-call').forEach(tool => tool.classList.remove('is-visible'));
+    panel.querySelectorAll('.output-block__line').forEach(line => line.classList.remove('is-visible'));
+    if (statusDot) statusDot.classList.remove('is-complete');
+    if (navHint) navHint.style.opacity = '0';
+    
+    let toolcallCounter = 0;
+    let startTime = Date.now();
+    
+    function updateTimer() {
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      if (sessionTime) sessionTime.textContent = `${elapsed}s`;
+    }
+    
+    const timerInterval = window.setInterval(updateTimer, 100);
+    
+    // Type the command
+    if (typewriterEl) {
+      await typewriter(typewriterEl, typewriterEl.textContent || '', 35);
+    }
+    
+    // Animate through each step
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i] as HTMLElement;
+      await new Promise(resolve => setTimeout(resolve, 350));
+      step.classList.add('is-visible');
+      
+      if (step.dataset.step === 'tools') {
+        const tools = step.querySelectorAll('.tool-call');
+        for (let j = 0; j < tools.length; j++) {
+          await new Promise(resolve => setTimeout(resolve, 250));
+          tools[j].classList.add('is-visible');
+          toolcallCounter++;
+          if (toolCount) toolCount.textContent = `${toolcallCounter} toolcalls`;
+        }
+        await new Promise(resolve => setTimeout(resolve, 400));
+      }
+      
+      if (step.dataset.step === 'output') {
+        const lines = step.querySelectorAll('.output-block__line');
+        for (let j = 0; j < lines.length; j++) {
+          await new Promise(resolve => setTimeout(resolve, 180));
+          lines[j].classList.add('is-visible');
+        }
+      }
+    }
+    
+    clearInterval(timerInterval);
+    if (statusDot) statusDot.classList.add('is-complete');
+    if (navHint) navHint.style.opacity = '1';
+  }
 
-      panels.forEach((panel) => {
-        const active = panel.dataset.commandPanel === id;
-        panel.classList.toggle("is-active", active);
-        panel.toggleAttribute("hidden", !active);
+  // Initialize showcase
+  function initShowcase() {
+    const showcase = document.querySelector('[data-command-showcase]');
+    if (!showcase) return;
+    
+    const tabs = showcase.querySelectorAll('[data-command-tab]');
+    const panels = showcase.querySelectorAll('[data-scenario-panel]');
+    
+    // Tab switching
+    tabs.forEach(tab => {
+      tab.addEventListener('click', () => {
+        const targetId = tab.getAttribute('data-command-tab');
+        if (!targetId) return;
+        
+        // Update tab states
+        tabs.forEach(t => {
+          const isActive = t.getAttribute('data-command-tab') === targetId;
+          t.classList.toggle('is-active', isActive);
+          t.setAttribute('aria-selected', isActive ? 'true' : 'false');
+        });
+        
+        // Update panel visibility
+        panels.forEach(panel => {
+          const isActive = panel.getAttribute('data-scenario-panel') === targetId;
+          panel.classList.toggle('is-active', isActive);
+          panel.toggleAttribute('hidden', !isActive);
+          
+          if (isActive) {
+            animateScenario(panel as HTMLElement);
+          }
+        });
       });
-    };
-
-    tabs.forEach((tab) => {
-      tab.addEventListener("click", () => activate(tab.dataset.commandTab));
     });
+    
+    // Animate first panel on load
+    const firstPanel = showcase.querySelector('[data-scenario-panel]') as HTMLElement;
+    if (firstPanel) {
+      const observer = new IntersectionObserver((entries) => {
+        entries.forEach(entry => {
+          if (entry.isIntersecting) {
+            animateScenario(firstPanel);
+            observer.disconnect();
+          }
+        });
+      }, { threshold: 0.2 });
+      observer.observe(showcase);
+    }
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initShowcase);
+  } else {
+    initShowcase();
   }
 </script>
+
+<style>
+  .command-showcase {
+    position: relative;
+    width: 100%;
+    min-height: 32rem;
+    padding: 2rem 0;
+  }
+
+  .command-showcase__background {
+    position: absolute;
+    inset: 0;
+    overflow: hidden;
+    pointer-events: none;
+  }
+
+  .command-showcase__grid {
+    position: absolute;
+    inset: 5% 4%;
+    background-image:
+      linear-gradient(rgba(159, 179, 195, 0.06) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(159, 179, 195, 0.06) 1px, transparent 1px);
+    background-size: 2.4rem 2.4rem;
+    mask-image: radial-gradient(ellipse at center, black 40%, transparent 80%);
+    animation: gridDrift 20s ease-in-out infinite;
+  }
+
+  @keyframes gridDrift {
+    0%, 100% { transform: translateY(0) rotate(0deg); }
+    50% { transform: translateY(8px) rotate(0.5deg); }
+  }
+
+  .command-showcase__glow {
+    position: absolute;
+    border-radius: 50%;
+    filter: blur(40px);
+    opacity: 0.4;
+    animation: glowPulse 8s ease-in-out infinite;
+  }
+
+  .command-showcase__glow--top {
+    inset: -10% 60% auto auto;
+    width: 20rem;
+    height: 20rem;
+    background: radial-gradient(circle, rgba(248, 184, 78, 0.3), transparent 70%);
+  }
+
+  .command-showcase__glow--bottom {
+    inset: auto auto -10% 40%;
+    width: 16rem;
+    height: 16rem;
+    background: radial-gradient(circle, rgba(95, 158, 197, 0.25), transparent 70%);
+    animation-delay: -4s;
+  }
+
+  @keyframes glowPulse {
+    0%, 100% { opacity: 0.3; transform: scale(1); }
+    50% { opacity: 0.5; transform: scale(1.1); }
+  }
+
+  .command-showcase__orbit {
+    position: absolute;
+    border: 1px solid rgba(125, 166, 196, 0.1);
+    border-radius: 50%;
+  }
+
+  .command-showcase__orbit--outer {
+    inset: 5% 10% 20% 15%;
+    animation: orbitRotate 30s linear infinite;
+  }
+
+  .command-showcase__orbit--inner {
+    inset: 20% 20% 10% 10%;
+    animation: orbitRotate 20s linear infinite reverse;
+  }
+
+  @keyframes orbitRotate {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+  }
+
+  .command-showcase__main {
+    position: relative;
+    z-index: 1;
+  }
+
+  /* Tabs */
+  .command-strip {
+    display: flex;
+    flex-wrap: nowrap;
+    gap: 0.6rem;
+    justify-content: center;
+    margin-bottom: 1.5rem;
+    padding: 0 1rem;
+    overflow-x: auto;
+    scrollbar-width: none;
+  }
+
+  .command-strip::-webkit-scrollbar {
+    display: none;
+  }
+
+  .command-tab {
+    flex-shrink: 0;
+    padding: 0.55rem 0.9rem;
+    border: 1px solid rgba(125, 166, 196, 0.15);
+    border-radius: 999px;
+    background: rgba(8, 18, 29, 0.6);
+    color: var(--muted);
+    font-family: var(--font-mono);
+    font-size: 0.82rem;
+    cursor: pointer;
+    transition: all 0.25s ease;
+    white-space: nowrap;
+  }
+
+  .command-tab:hover {
+    border-color: rgba(248, 184, 78, 0.35);
+    background: rgba(248, 184, 78, 0.12);
+    color: var(--text);
+    transform: translateY(-1px);
+  }
+
+  .command-tab.is-active {
+    border-color: rgba(248, 184, 78, 0.45);
+    background: rgba(248, 184, 78, 0.18);
+    color: var(--text);
+  }
+
+  /* Scenario panels */
+  .scenario-panel {
+    display: none;
+  }
+
+  .scenario-panel.is-active {
+    display: block;
+  }
+
+  /* Decorative command strip */
+  .all-commands {
+    display: flex;
+    flex-wrap: nowrap;
+    gap: 0.5rem;
+    justify-content: center;
+    margin-top: 2rem;
+    padding: 0 1rem;
+    overflow-x: auto;
+    opacity: 0.5;
+    scrollbar-width: none;
+  }
+
+  .all-commands::-webkit-scrollbar {
+    display: none;
+  }
+
+  .command-pill-decorative {
+    flex-shrink: 0;
+    padding: 0.4rem 0.7rem;
+    border: 1px solid rgba(125, 166, 196, 0.1);
+    border-radius: 999px;
+    background: rgba(8, 18, 29, 0.4);
+    color: var(--muted);
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+  }
+
+  /* Terminal styles */
+  .session-terminal {
+    max-width: 900px;
+    margin: 0 auto;
+    border: 1px solid rgba(125, 166, 196, 0.12);
+    border-radius: 1rem;
+    background:
+      radial-gradient(circle at 80% 5%, rgba(248, 184, 78, 0.05), transparent 25%),
+      linear-gradient(180deg, rgba(5, 12, 20, 0.9), rgba(7, 17, 28, 0.85));
+    box-shadow: 
+      0 24px 80px rgba(0, 0, 0, 0.35),
+      inset 0 1px 0 rgba(255, 255, 255, 0.03);
+    overflow: hidden;
+  }
+
+  .session-terminal__header {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 0.9rem 1.2rem;
+    border-bottom: 1px solid rgba(125, 166, 196, 0.08);
+    background: rgba(0, 0, 0, 0.2);
+  }
+
+  .session-terminal__window-controls {
+    display: flex;
+    gap: 0.4rem;
+  }
+
+  .session-terminal__window-controls span {
+    width: 0.7rem;
+    height: 0.7rem;
+    border-radius: 50%;
+    background: rgba(159, 179, 195, 0.4);
+  }
+
+  .session-terminal__title {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    flex: 1;
+    font-family: var(--font-mono);
+    font-size: 0.85rem;
+    color: var(--text);
+  }
+
+  .session-terminal__status {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    background: #f8b84e;
+    box-shadow: 0 0 8px rgba(248, 184, 78, 0.6);
+    animation: statusPulse 2s ease-in-out infinite;
+  }
+
+  .session-terminal__status.is-complete {
+    background: #4ade80;
+    box-shadow: 0 0 8px rgba(74, 222, 128, 0.6);
+    animation: none;
+  }
+
+  @keyframes statusPulse {
+    0%, 100% { opacity: 1; transform: scale(1); }
+    50% { opacity: 0.6; transform: scale(0.9); }
+  }
+
+  .session-terminal__meta {
+    display: flex;
+    gap: 1rem;
+    font-family: var(--font-mono);
+    font-size: 0.78rem;
+    color: var(--muted);
+  }
+
+  .session-terminal__body {
+    padding: 1.2rem;
+    font-family: var(--font-mono);
+    font-size: 0.9rem;
+    line-height: 1.6;
+  }
+
+  .session-line {
+    margin-bottom: 0.8rem;
+  }
+
+  .session-line--input {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    color: var(--text);
+  }
+
+  .session-line__prompt {
+    color: var(--accent);
+    font-weight: 500;
+  }
+
+  .session-line__command {
+    color: #d8e5ee;
+  }
+
+  .session-line--task {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--muted);
+    font-size: 0.85rem;
+  }
+
+  .session-line__icon {
+    color: var(--accent);
+  }
+
+  .session-steps {
+    margin-top: 1rem;
+  }
+
+  .session-step {
+    opacity: 0;
+    transform: translateY(12px);
+    transition: all 0.4s ease;
+  }
+
+  .session-step.is-visible {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  .thinking-block {
+    margin-bottom: 1rem;
+    padding: 1rem;
+    border-left: 2px solid rgba(248, 184, 78, 0.4);
+    background: rgba(248, 184, 78, 0.05);
+  }
+
+  .thinking-block__header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 0.6rem;
+  }
+
+  .thinking-block__indicator {
+    position: relative;
+    width: 0.6rem;
+    height: 0.6rem;
+  }
+
+  .thinking-block__pulse {
+    position: absolute;
+    inset: 0;
+    border-radius: 50%;
+    background: var(--accent);
+    animation: thinkingPulse 1.5s ease-in-out infinite;
+  }
+
+  @keyframes thinkingPulse {
+    0%, 100% { transform: scale(1); opacity: 1; }
+    50% { transform: scale(1.5); opacity: 0.5; }
+  }
+
+  .thinking-block__label {
+    color: var(--accent);
+    font-size: 0.75rem;
+    font-weight: 500;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+  }
+
+  .thinking-block__content {
+    margin: 0;
+    color: var(--muted);
+    font-size: 0.88rem;
+    line-height: 1.7;
+    font-style: italic;
+  }
+
+  .tool-calls-block {
+    margin-bottom: 1rem;
+  }
+
+  .tool-calls-block__header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 0.6rem;
+    color: var(--accent);
+    font-size: 0.8rem;
+  }
+
+  .tool-calls-block__icon {
+    color: var(--accent);
+  }
+
+  .tool-calls-block__label {
+    font-weight: 500;
+  }
+
+  .tool-calls-block__count {
+    margin-left: auto;
+    color: var(--muted);
+    font-size: 0.75rem;
+  }
+
+  .tool-calls-block__list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+  }
+
+  .tool-call {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.5rem 0.7rem;
+    border-radius: 0.4rem;
+    background: rgba(125, 166, 196, 0.08);
+    font-size: 0.85rem;
+    opacity: 0;
+    transform: translateX(-10px);
+    transition: all 0.3s ease;
+  }
+
+  .tool-call.is-visible {
+    opacity: 1;
+    transform: translateX(0);
+  }
+
+  .tool-call__arrow {
+    color: var(--accent);
+    font-size: 0.75rem;
+  }
+
+  .tool-call__name {
+    color: #7ab8d9;
+    font-weight: 500;
+  }
+
+  .tool-call__args {
+    color: var(--muted);
+    font-size: 0.8rem;
+  }
+
+  .output-block {
+    margin-top: 1rem;
+    padding-top: 1rem;
+    border-top: 1px solid rgba(125, 166, 196, 0.15);
+  }
+
+  .output-block__line {
+    margin: 0.5rem 0;
+    color: var(--text);
+    line-height: 1.7;
+    opacity: 0;
+    transform: translateY(8px);
+    transition: all 0.35s ease;
+  }
+
+  .output-block__line.is-visible {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  .output-block__line:last-child {
+    color: var(--muted);
+    font-size: 0.85rem;
+    margin-top: 1rem;
+  }
+
+  .session-nav-hint {
+    display: flex;
+    gap: 1.5rem;
+    margin-top: 1.5rem;
+    padding-top: 1rem;
+    border-top: 1px solid rgba(125, 166, 196, 0.1);
+    color: var(--muted);
+    font-size: 0.8rem;
+    opacity: 0;
+    transition: opacity 0.5s ease 0.3s;
+  }
+
+  .session-nav-hint kbd {
+    padding: 0.15rem 0.4rem;
+    border: 1px solid rgba(125, 166, 196, 0.25);
+    border-radius: 0.3rem;
+    background: rgba(125, 166, 196, 0.1);
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+  }
+
+  @media (max-width: 640px) {
+    .session-terminal {
+      margin: 0 0.5rem;
+    }
+
+    .session-terminal__body {
+      padding: 1rem;
+      font-size: 0.85rem;
+    }
+
+    .command-tab {
+      padding: 0.45rem 0.7rem;
+      font-size: 0.78rem;
+    }
+
+    .session-nav-hint {
+      gap: 0.8rem;
+      font-size: 0.75rem;
+    }
+  }
+</style>
\ No newline at end of file
diff --git a/packages/web/src/layouts/MarketingLayout.astro b/packages/web/src/layouts/MarketingLayout.astro
index 70c5980..237e641 100644
--- a/packages/web/src/layouts/MarketingLayout.astro
+++ b/packages/web/src/layouts/MarketingLayout.astro
@@ -32,4 +32,4 @@ const {
 
 <style is:global>
   @import "../styles/site.css";
-</style>
+</style>
\ No newline at end of file
diff --git a/packages/web/src/pages/index.astro b/packages/web/src/pages/index.astro
index 3fb5127..cb0a64d 100644
--- a/packages/web/src/pages/index.astro
+++ b/packages/web/src/pages/index.astro
@@ -173,4 +173,4 @@ const heroHighlights = [
       </div>
     </footer>
   </main>
-</MarketingLayout>
+</MarketingLayout>
\ No newline at end of file

From 44a3946058b6766c97a54c1c183645bb55d19b91 Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 10:15:26 -0300
Subject: [PATCH 2/7] feat: Add 4 more command scenarios to showcase

- Add /ship scenario showing fast path from changes to PR
- Add /rmslop scenario for removing unnecessary complexity
- Add /todo scenario for working through todo lists
- Add /commit-and-push scenario for one-pass commits
- Total: 9 interactive command tabs with unique agent workflows
---
 .../web/src/components/CommandShowcase.astro  | 134 ++++++++++++++++++
 1 file changed, 134 insertions(+)

diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index bac48ea..2375a49 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -189,6 +189,140 @@ const scenarios: CommandScenario[] = [
         ]
       }
     ]
+  },
+  {
+    id: 'ship',
+    label: '/ship',
+    command: '/ship',
+    agentName: 'Navigator',
+    task: 'Fast path from changes to PR',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Shipping — need to create a work branch, commit changes, and publish a PR. Will orchestrate the full workflow from current state to pull request.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'dispatch', args: '/branch feature/new-workflow', status: 'complete' },
+          { tool: 'dispatch', args: '/commit', status: 'complete' },
+          { tool: 'dispatch', args: '/pr/create', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Created branch: feature/new-workflow',
+          'Committed 3 files with generated message',
+          'Published PR #48: Add new workflow command',
+          'No additional steps are required.'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'rmslop',
+    label: '/rmslop',
+    command: '/rmslop',
+    agentName: 'Worker',
+    task: 'Remove unnecessary complexity and duplication',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Inspecting for slop — need to examine the branch for unnecessary complexity, duplicate code, and workflow glue that can be simplified or removed.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'changes_load', args: 'HEAD~3...HEAD', status: 'complete' },
+          { tool: 'read', args: 'packages/core/commands/*.md', status: 'complete' },
+          { tool: 'grep', args: 'TODO|FIXME|XXX', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Removed 47 lines of duplicate validation logic',
+          'Simplified 3 overly-abstract helper functions',
+          'Consolidated similar command patterns into shared components',
+          'No additional steps are required.'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'todo',
+    label: '/todo',
+    command: '/todo @TODO.md',
+    agentName: 'Navigator',
+    task: 'Work through a todo list with checkpoint reviews',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Processing todo — loading the todo list and keeping orchestration local. Will ask for plan approval before implementation starts.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'read', args: 'TODO.md', status: 'complete' },
+          { tool: 'dispatch', args: '/ticket/plan #42', status: 'complete' },
+          { tool: 'dispatch', args: '/dev', status: 'complete' },
+          { tool: 'dispatch', args: '/commit', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Completed: Update command showcase with more examples',
+          'Blocked: Waiting for review on PR #47',
+          'Next: Add mobile responsive styling',
+          'No additional steps are required.'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'commit-and-push',
+    label: '/commit-and-push',
+    command: '/commit-and-push',
+    agentName: 'Worker',
+    task: 'Commit and push in one pass',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Committing and pushing — need to stage relevant files, generate a commit message, and push the branch upstream in a single operation.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'changes_load', args: 'uncommitted', status: 'complete' },
+          { tool: 'bash', args: 'git add packages/web/src/', status: 'complete' },
+          { tool: 'bash', args: 'git commit -m "feat: add command showcase"', status: 'complete' },
+          { tool: 'bash', args: 'git push origin HEAD', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Staged 3 modified files',
+          'Created commit: feat: add command showcase with animations',
+          'Pushed to origin/feature/showcase',
+          'No additional steps are required.'
+        ]
+      }
+    ]
   }
 ];
 

From 60251c5990ba05b24a8c4cde6de5fe3d5ea31cf7 Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 10:26:44 -0300
Subject: [PATCH 3/7] feat: Redesign command showcase with parent/child session
 hierarchy

- Add clear parent/child visual hierarchy with subagent session styling
- Parent level shows command input with status and timer
- Subagent session has yellow left border and navigation hints (Parent/Prev/Next)
- Subagent header shows agent name, task description, and tool call count
- Improved visual separation between parent command and child session
- Mix of desktop UI and TUI aesthetics for better hierarchy clarity
---
 .../web/src/components/CommandShowcase.astro  | 386 ++++++++++--------
 1 file changed, 208 insertions(+), 178 deletions(-)

diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index 2375a49..5de4f0e 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -1,5 +1,5 @@
 ---
-// Command showcase with working tabs - each command shows its own scenario
+// Command showcase with parent/child session hierarchy
 interface ToolCall {
   tool: string;
   args: string;
@@ -371,86 +371,85 @@ const allCommands = [
         hidden={index !== 0}
       >
         <div class="session-terminal">
-          <div class="session-terminal__header">
-            <div class="session-terminal__window-controls">
-              <span></span>
-              <span></span>
-              <span></span>
-            </div>
-            <div class="session-terminal__title">
-              <span class="session-terminal__status" data-status-dot></span>
-              <span data-session-title>{scenario.agentName}</span>
+          <!-- Parent Session Header -->
+          <div class="session-terminal__header session-terminal__header--parent">
+            <div class="session-terminal__parent-info">
+              <span class="session-terminal__prompt">$</span>
+              <span class="session-terminal__command" data-typewriter>{scenario.command}</span>
             </div>
             <div class="session-terminal__meta">
-              <span data-tool-count>0 toolcalls</span>
+              <span class="session-terminal__status" data-status-dot></span>
               <span data-session-time>0.0s</span>
             </div>
           </div>
 
-          <div class="session-terminal__body">
-            <!-- Command Input -->
-            <div class="session-line session-line--input">
-              <span class="session-line__prompt">$</span>
-              <span class="session-line__command" data-typewriter>{scenario.command}</span>
-            </div>
-
-            <!-- Task Description -->
-            <div class="session-line session-line--task">
-              <span class="session-line__icon">◆</span>
-              <span>{scenario.task}</span>
+          <!-- Subagent Session -->
+          <div class="subagent-session">
+            <!-- Subagent Header -->
+            <div class="subagent-session__header">
+              <div class="subagent-session__nav">
+                <span>Parent <kbd>↑</kbd></span>
+                <span>Prev <kbd>←</kbd></span>
+                <span>Next <kbd>→</kbd></span>
+              </div>
+              <div class="subagent-session__title">
+                <span class="subagent-session__indicator"></span>
+                <span class="subagent-session__agent">{scenario.agentName}</span>
+                <span class="subagent-session__divider">—</span>
+                <span class="subagent-session__task">{scenario.task}</span>
+              </div>
+              <div class="subagent-session__stats">
+                <span data-tool-count>0 toolcalls</span>
+              </div>
             </div>
 
-            <!-- Session Steps -->
-            <div class="session-steps" data-session-steps>
-              {scenario.steps.map((step) => (
-                <div class="session-step" data-step={step.id}>
-                  {step.phase === 'thinking' && step.content && (
-                    <div class="thinking-block">
-                      <div class="thinking-block__header">
-                        <span class="thinking-block__indicator">
-                          <span class="thinking-block__pulse"></span>
-                        </span>
-                        <span class="thinking-block__label">Thinking</span>
+            <!-- Subagent Body -->
+            <div class="subagent-session__body">
+              <!-- Session Steps -->
+              <div class="session-steps" data-session-steps>
+                {scenario.steps.map((step) => (
+                  <div class="session-step" data-step={step.id}>
+                    {step.phase === 'thinking' && step.content && (
+                      <div class="thinking-block">
+                        <div class="thinking-block__header">
+                          <span class="thinking-block__indicator">
+                            <span class="thinking-block__pulse"></span>
+                          </span>
+                          <span class="thinking-block__label">Thinking</span>
+                        </div>
+                        <p class="thinking-block__content">{step.content}</p>
                       </div>
-                      <p class="thinking-block__content">{step.content}</p>
-                    </div>
-                  )}
-
-                  {step.phase === 'tool_calls' && step.toolCalls && (
-                    <div class="tool-calls-block">
-                      <div class="tool-calls-block__header">
-                        <span class="tool-calls-block__icon">▸</span>
-                        <span class="tool-calls-block__label">Explored</span>
-                        <span class="tool-calls-block__count">{step.toolCalls.length} reads, 1 search</span>
+                    )}
+
+                    {step.phase === 'tool_calls' && step.toolCalls && (
+                      <div class="tool-calls-block">
+                        <div class="tool-calls-block__header">
+                          <span class="tool-calls-block__icon">▸</span>
+                          <span class="tool-calls-block__label">Explored</span>
+                          <span class="tool-calls-block__count">{step.toolCalls.length} reads, 1 search</span>
+                        </div>
+                        <div class="tool-calls-block__list">
+                          {step.toolCalls.map((tool) => (
+                            <div class="tool-call" data-tool-status={tool.status}>
+                              <span class="tool-call__arrow">→</span>
+                              <span class="tool-call__name">{tool.tool}</span>
+                              <span class="tool-call__args">{tool.args}</span>
+                            </div>
+                          ))}
+                        </div>
                       </div>
-                      <div class="tool-calls-block__list">
-                        {step.toolCalls.map((tool) => (
-                          <div class="tool-call" data-tool-status={tool.status}>
-                            <span class="tool-call__arrow">→</span>
-                            <span class="tool-call__name">{tool.tool}</span>
-                            <span class="tool-call__args">{tool.args}</span>
-                          </div>
+                    )}
+
+                    {step.phase === 'output' && step.output && (
+                      <div class="output-block">
+                        {step.output.map((line) => (
+                          <p class="output-block__line">{line}</p>
                         ))}
                       </div>
-                    </div>
-                  )}
-
-                  {step.phase === 'output' && step.output && (
-                    <div class="output-block">
-                      {step.output.map((line) => (
-                        <p class="output-block__line">{line}</p>
-                      ))}
-                    </div>
-                  )}
-                </div>
-              ))}
-            </div>
-
-            <!-- Navigation hint -->
-            <div class="session-nav-hint">
-              <span>Parent <kbd>↑</kbd></span>
-              <span>Prev <kbd>←</kbd></span>
-              <span>Next <kbd>→</kbd></span>
+                    )}
+                  </div>
+                ))}
+              </div>
             </div>
           </div>
         </div>
@@ -491,14 +490,12 @@ const allCommands = [
     const statusDot = panel.querySelector('[data-status-dot]') as HTMLElement;
     const toolCount = panel.querySelector('[data-tool-count]') as HTMLElement;
     const sessionTime = panel.querySelector('[data-session-time]') as HTMLElement;
-    const navHint = panel.querySelector('.session-nav-hint') as HTMLElement;
     
     // Reset all animations
     steps.forEach(step => step.classList.remove('is-visible'));
     panel.querySelectorAll('.tool-call').forEach(tool => tool.classList.remove('is-visible'));
     panel.querySelectorAll('.output-block__line').forEach(line => line.classList.remove('is-visible'));
     if (statusDot) statusDot.classList.remove('is-complete');
-    if (navHint) navHint.style.opacity = '0';
     
     let toolcallCounter = 0;
     let startTime = Date.now();
@@ -543,7 +540,6 @@ const allCommands = [
     
     clearInterval(timerInterval);
     if (statusDot) statusDot.classList.add('is-complete');
-    if (navHint) navHint.style.opacity = '1';
   }
 
   // Initialize showcase
@@ -739,35 +735,7 @@ const allCommands = [
     display: block;
   }
 
-  /* Decorative command strip */
-  .all-commands {
-    display: flex;
-    flex-wrap: nowrap;
-    gap: 0.5rem;
-    justify-content: center;
-    margin-top: 2rem;
-    padding: 0 1rem;
-    overflow-x: auto;
-    opacity: 0.5;
-    scrollbar-width: none;
-  }
-
-  .all-commands::-webkit-scrollbar {
-    display: none;
-  }
-
-  .command-pill-decorative {
-    flex-shrink: 0;
-    padding: 0.4rem 0.7rem;
-    border: 1px solid rgba(125, 166, 196, 0.1);
-    border-radius: 999px;
-    background: rgba(8, 18, 29, 0.4);
-    color: var(--muted);
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-  }
-
-  /* Terminal styles */
+  /* Terminal container */
   .session-terminal {
     max-width: 900px;
     margin: 0 auto;
@@ -775,42 +743,48 @@ const allCommands = [
     border-radius: 1rem;
     background:
       radial-gradient(circle at 80% 5%, rgba(248, 184, 78, 0.05), transparent 25%),
-      linear-gradient(180deg, rgba(5, 12, 20, 0.9), rgba(7, 17, 28, 0.85));
+      linear-gradient(180deg, rgba(5, 12, 20, 0.95), rgba(7, 17, 28, 0.9));
     box-shadow: 
-      0 24px 80px rgba(0, 0, 0, 0.35),
+      0 24px 80px rgba(0, 0, 0, 0.4),
       inset 0 1px 0 rgba(255, 255, 255, 0.03);
     overflow: hidden;
   }
 
-  .session-terminal__header {
+  /* Parent Session Header */
+  .session-terminal__header--parent {
     display: flex;
     align-items: center;
+    justify-content: space-between;
     gap: 1rem;
-    padding: 0.9rem 1.2rem;
-    border-bottom: 1px solid rgba(125, 166, 196, 0.08);
-    background: rgba(0, 0, 0, 0.2);
+    padding: 1rem 1.2rem;
+    border-bottom: 1px solid rgba(125, 166, 196, 0.1);
+    background: rgba(0, 0, 0, 0.3);
   }
 
-  .session-terminal__window-controls {
+  .session-terminal__parent-info {
     display: flex;
-    gap: 0.4rem;
+    align-items: center;
+    gap: 0.6rem;
+    font-family: var(--font-mono);
+    font-size: 1rem;
   }
 
-  .session-terminal__window-controls span {
-    width: 0.7rem;
-    height: 0.7rem;
-    border-radius: 50%;
-    background: rgba(159, 179, 195, 0.4);
+  .session-terminal__prompt {
+    color: var(--accent);
+    font-weight: 500;
   }
 
-  .session-terminal__title {
+  .session-terminal__command {
+    color: var(--text);
+  }
+
+  .session-terminal__meta {
     display: flex;
     align-items: center;
-    gap: 0.6rem;
-    flex: 1;
+    gap: 0.8rem;
     font-family: var(--font-mono);
-    font-size: 0.85rem;
-    color: var(--text);
+    font-size: 0.8rem;
+    color: var(--muted);
   }
 
   .session-terminal__status {
@@ -833,55 +807,94 @@ const allCommands = [
     50% { opacity: 0.6; transform: scale(0.9); }
   }
 
-  .session-terminal__meta {
+  /* Subagent Session */
+  .subagent-session {
+    background: rgba(0, 0, 0, 0.2);
+    border-left: 2px solid rgba(248, 184, 78, 0.3);
+    margin: 0.5rem;
+    border-radius: 0 0.5rem 0.5rem 0;
+  }
+
+  .subagent-session__header {
     display: flex;
+    align-items: center;
+    justify-content: space-between;
     gap: 1rem;
-    font-family: var(--font-mono);
-    font-size: 0.78rem;
-    color: var(--muted);
+    padding: 0.75rem 1rem;
+    border-bottom: 1px solid rgba(125, 166, 196, 0.08);
+    background: rgba(248, 184, 78, 0.05);
   }
 
-  .session-terminal__body {
-    padding: 1.2rem;
+  .subagent-session__nav {
+    display: flex;
+    gap: 1rem;
     font-family: var(--font-mono);
-    font-size: 0.9rem;
-    line-height: 1.6;
+    font-size: 0.75rem;
+    color: var(--muted);
   }
 
-  .session-line {
-    margin-bottom: 0.8rem;
+  .subagent-session__nav kbd {
+    padding: 0.1rem 0.35rem;
+    border: 1px solid rgba(125, 166, 196, 0.25);
+    border-radius: 0.25rem;
+    background: rgba(125, 166, 196, 0.1);
+    font-family: var(--font-mono);
+    font-size: 0.7rem;
   }
 
-  .session-line--input {
+  .subagent-session__title {
     display: flex;
     align-items: center;
-    gap: 0.6rem;
-    color: var(--text);
+    gap: 0.5rem;
+    font-family: var(--font-mono);
+    font-size: 0.85rem;
+  }
+
+  .subagent-session__indicator {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    background: var(--accent);
+    animation: subagentPulse 1.5s ease-in-out infinite;
+  }
+
+  @keyframes subagentPulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.4; }
   }
 
-  .session-line__prompt {
+  .subagent-session__agent {
     color: var(--accent);
     font-weight: 500;
   }
 
-  .session-line__command {
-    color: #d8e5ee;
+  .subagent-session__divider {
+    color: var(--muted);
+    opacity: 0.5;
   }
 
-  .session-line--task {
-    display: flex;
-    align-items: center;
-    gap: 0.5rem;
+  .subagent-session__task {
     color: var(--muted);
-    font-size: 0.85rem;
+    font-size: 0.8rem;
   }
 
-  .session-line__icon {
-    color: var(--accent);
+  .subagent-session__stats {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    color: var(--muted);
+  }
+
+  .subagent-session__body {
+    padding: 1rem;
+    font-family: var(--font-mono);
+    font-size: 0.9rem;
+    line-height: 1.6;
   }
 
   .session-steps {
-    margin-top: 1rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
   }
 
   .session-step {
@@ -896,17 +909,17 @@ const allCommands = [
   }
 
   .thinking-block {
-    margin-bottom: 1rem;
-    padding: 1rem;
+    padding: 0.75rem 1rem;
     border-left: 2px solid rgba(248, 184, 78, 0.4);
     background: rgba(248, 184, 78, 0.05);
+    border-radius: 0 0.25rem 0.25rem 0;
   }
 
   .thinking-block__header {
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    margin-bottom: 0.6rem;
+    margin-bottom: 0.5rem;
   }
 
   .thinking-block__indicator {
@@ -945,14 +958,15 @@ const allCommands = [
   }
 
   .tool-calls-block {
-    margin-bottom: 1rem;
+    padding: 0.5rem 0;
   }
 
   .tool-calls-block__header {
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    margin-bottom: 0.6rem;
+    margin-bottom: 0.5rem;
+    padding-left: 0.5rem;
     color: var(--accent);
     font-size: 0.8rem;
   }
@@ -974,16 +988,17 @@ const allCommands = [
   .tool-calls-block__list {
     display: flex;
     flex-direction: column;
-    gap: 0.4rem;
+    gap: 0.3rem;
+    padding-left: 0.5rem;
   }
 
   .tool-call {
     display: flex;
     align-items: center;
     gap: 0.6rem;
-    padding: 0.5rem 0.7rem;
-    border-radius: 0.4rem;
-    background: rgba(125, 166, 196, 0.08);
+    padding: 0.4rem 0.6rem;
+    border-radius: 0.3rem;
+    background: rgba(125, 166, 196, 0.06);
     font-size: 0.85rem;
     opacity: 0;
     transform: translateX(-10px);
@@ -1011,13 +1026,13 @@ const allCommands = [
   }
 
   .output-block {
-    margin-top: 1rem;
-    padding-top: 1rem;
-    border-top: 1px solid rgba(125, 166, 196, 0.15);
+    margin-top: 0.5rem;
+    padding: 0.75rem 1rem;
+    border-top: 1px solid rgba(125, 166, 196, 0.1);
   }
 
   .output-block__line {
-    margin: 0.5rem 0;
+    margin: 0.4rem 0;
     color: var(--text);
     line-height: 1.7;
     opacity: 0;
@@ -1033,26 +1048,35 @@ const allCommands = [
   .output-block__line:last-child {
     color: var(--muted);
     font-size: 0.85rem;
-    margin-top: 1rem;
+    margin-top: 0.75rem;
+    padding-top: 0.5rem;
+    border-top: 1px solid rgba(125, 166, 196, 0.08);
   }
 
-  .session-nav-hint {
+  /* Decorative commands */
+  .all-commands {
     display: flex;
-    gap: 1.5rem;
-    margin-top: 1.5rem;
-    padding-top: 1rem;
-    border-top: 1px solid rgba(125, 166, 196, 0.1);
-    color: var(--muted);
-    font-size: 0.8rem;
-    opacity: 0;
-    transition: opacity 0.5s ease 0.3s;
+    flex-wrap: nowrap;
+    gap: 0.5rem;
+    justify-content: center;
+    margin-top: 2rem;
+    padding: 0 1rem;
+    overflow-x: auto;
+    opacity: 0.5;
+    scrollbar-width: none;
   }
 
-  .session-nav-hint kbd {
-    padding: 0.15rem 0.4rem;
-    border: 1px solid rgba(125, 166, 196, 0.25);
-    border-radius: 0.3rem;
-    background: rgba(125, 166, 196, 0.1);
+  .all-commands::-webkit-scrollbar {
+    display: none;
+  }
+
+  .command-pill-decorative {
+    flex-shrink: 0;
+    padding: 0.4rem 0.7rem;
+    border: 1px solid rgba(125, 166, 196, 0.1);
+    border-radius: 999px;
+    background: rgba(8, 18, 29, 0.4);
+    color: var(--muted);
     font-family: var(--font-mono);
     font-size: 0.75rem;
   }
@@ -1062,8 +1086,19 @@ const allCommands = [
       margin: 0 0.5rem;
     }
 
-    .session-terminal__body {
-      padding: 1rem;
+    .subagent-session__header {
+      flex-wrap: wrap;
+      gap: 0.5rem;
+    }
+
+    .subagent-session__nav {
+      order: 3;
+      width: 100%;
+      font-size: 0.7rem;
+    }
+
+    .subagent-session__body {
+      padding: 0.75rem;
       font-size: 0.85rem;
     }
 
@@ -1071,10 +1106,5 @@ const allCommands = [
       padding: 0.45rem 0.7rem;
       font-size: 0.78rem;
     }
-
-    .session-nav-hint {
-      gap: 0.8rem;
-      font-size: 0.75rem;
-    }
   }
 </style>
\ No newline at end of file

From c905ffb4948c7c341bac6e6e017c77c2d7d9ddc7 Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 10:31:17 -0300
Subject: [PATCH 4/7] style: Make terminal full-width and remove decorative
 command strip

- Remove max-width constraint from terminal to fit container
- Remove all-commands decorative strip from bottom
- Terminal now takes full available width for better visual impact
---
 .../web/src/components/CommandShowcase.astro  | 45 ++-----------------
 1 file changed, 3 insertions(+), 42 deletions(-)

diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index 5de4f0e..09f1206 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -326,11 +326,7 @@ const scenarios: CommandScenario[] = [
   }
 ];
 
-const allCommands = [
-  "/ask", "/branch", "/commit", "/commit-and-push", "/dev", "/learn", 
-  "/reload", "/pr/create", "/pr/fix", "/pr/review", "/review", "/ship",
-  "/rmslop", "/todo", "/ticket/ask", "/ticket/create", "/ticket/dev", "/ticket/plan"
-];
+
 ---
 
 <div class="command-showcase" data-command-showcase>
@@ -456,13 +452,7 @@ const allCommands = [
       </div>
     ))}
 
-    <!-- All commands strip (decorative) -->
-    <div class="all-commands" aria-hidden="true">
-      {allCommands.map((cmd) => (
-        <span class="command-pill-decorative">{cmd}</span>
-      ))}
     </div>
-  </div>
 </div>
 
 <script>
@@ -737,14 +727,13 @@ const allCommands = [
 
   /* Terminal container */
   .session-terminal {
-    max-width: 900px;
-    margin: 0 auto;
+    width: 100%;
     border: 1px solid rgba(125, 166, 196, 0.12);
     border-radius: 1rem;
     background:
       radial-gradient(circle at 80% 5%, rgba(248, 184, 78, 0.05), transparent 25%),
       linear-gradient(180deg, rgba(5, 12, 20, 0.95), rgba(7, 17, 28, 0.9));
-    box-shadow: 
+    box-shadow:
       0 24px 80px rgba(0, 0, 0, 0.4),
       inset 0 1px 0 rgba(255, 255, 255, 0.03);
     overflow: hidden;
@@ -1053,34 +1042,6 @@ const allCommands = [
     border-top: 1px solid rgba(125, 166, 196, 0.08);
   }
 
-  /* Decorative commands */
-  .all-commands {
-    display: flex;
-    flex-wrap: nowrap;
-    gap: 0.5rem;
-    justify-content: center;
-    margin-top: 2rem;
-    padding: 0 1rem;
-    overflow-x: auto;
-    opacity: 0.5;
-    scrollbar-width: none;
-  }
-
-  .all-commands::-webkit-scrollbar {
-    display: none;
-  }
-
-  .command-pill-decorative {
-    flex-shrink: 0;
-    padding: 0.4rem 0.7rem;
-    border: 1px solid rgba(125, 166, 196, 0.1);
-    border-radius: 999px;
-    background: rgba(8, 18, 29, 0.4);
-    color: var(--muted);
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-  }
-
   @media (max-width: 640px) {
     .session-terminal {
       margin: 0 0.5rem;

From 981dcd5da5609da1d8e279f3976f82109ba6968a Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 11:50:32 -0300
Subject: [PATCH 5/7] feat: add agent-browser skill, branch command, and
 ticket/plan-and-sync workflow

- Add agent-browser skill with 11 files (SKILL.md, references, templates)
- Add branch command for branch management operations
- Add ticket/plan-and-sync command separate from ticket/plan
- Update ticket/plan to present plan without syncing to ticket
- Add load-pr and load-ticket components for context loading
- Update kompass.schema.json with new commands and components
- Sync config across all kompass.jsonc files
- Update README to link to external docs site
- Enhance AGENTS.md with sync guidance for multi-source changes
- Update web docs with new command and tool references
- Regenerate OpenCode output packages/opencode/.opencode/
---
 .agents/skills/agent-browser/SKILL.md         | 727 ++++++++++++++++++
 .../references/authentication.md              | 303 ++++++++
 .../agent-browser/references/commands.md      | 292 +++++++
 .../agent-browser/references/profiling.md     | 120 +++
 .../agent-browser/references/proxy-support.md | 194 +++++
 .../references/session-management.md          | 193 +++++
 .../agent-browser/references/snapshot-refs.md | 219 ++++++
 .../references/video-recording.md             | 173 +++++
 .../templates/authenticated-session.sh        | 105 +++
 .../templates/capture-workflow.sh             |  69 ++
 .../templates/form-automation.sh              |  62 ++
 AGENTS.md                                     |   7 +
 README.md                                     | 441 +----------
 kompass.jsonc                                 |   4 +
 kompass.schema.json                           |  38 +-
 packages/core/commands/index.ts               |   7 +-
 .../core/commands/ticket/plan-and-sync.md     | 109 +++
 packages/core/commands/ticket/plan.md         |  19 +-
 packages/core/kompass.jsonc                   |   5 +
 packages/core/lib/config.ts                   |   2 +
 .../skills.todo/kompass-workflows/SKILL.md    |   3 +-
 .../commands/ticket/plan-and-sync.md          | 118 +++
 .../.opencode/commands/ticket/plan.md         |  21 +-
 packages/opencode/.opencode/kompass.jsonc     |   3 +
 packages/opencode/README.md                   | 461 +----------
 packages/opencode/kompass.jsonc               |   5 +
 .../opencode/test/commands-config.test.ts     |  10 +-
 .../web/src/components/CommandShowcase.astro  | 425 ++++++++--
 .../content/docs/docs/adapters/opencode.mdx   |   7 +
 .../src/content/docs/docs/config/overview.mdx |  26 +-
 .../src/content/docs/docs/config/schema.mdx   |   7 +
 .../docs/docs/reference/commands/index.mdx    |  12 +-
 .../docs/reference/commands/ticket-create.mdx |  11 +-
 .../commands/ticket-plan-and-sync.mdx         |  28 +
 .../docs/docs/reference/tools/index.mdx       |   8 +-
 .../docs/docs/reference/tools/pr-sync.mdx     |   4 +
 .../docs/docs/reference/tools/ticket-load.mdx |   1 +
 .../docs/docs/reference/tools/ticket-sync.mdx |   2 +
 .../docs/docs/workspace/development.mdx       |   1 +
 skills-lock.json                              |   5 +
 40 files changed, 3255 insertions(+), 992 deletions(-)
 create mode 100644 .agents/skills/agent-browser/SKILL.md
 create mode 100644 .agents/skills/agent-browser/references/authentication.md
 create mode 100644 .agents/skills/agent-browser/references/commands.md
 create mode 100644 .agents/skills/agent-browser/references/profiling.md
 create mode 100644 .agents/skills/agent-browser/references/proxy-support.md
 create mode 100644 .agents/skills/agent-browser/references/session-management.md
 create mode 100644 .agents/skills/agent-browser/references/snapshot-refs.md
 create mode 100644 .agents/skills/agent-browser/references/video-recording.md
 create mode 100755 .agents/skills/agent-browser/templates/authenticated-session.sh
 create mode 100755 .agents/skills/agent-browser/templates/capture-workflow.sh
 create mode 100755 .agents/skills/agent-browser/templates/form-automation.sh
 create mode 100644 packages/core/commands/ticket/plan-and-sync.md
 create mode 100644 packages/opencode/.opencode/commands/ticket/plan-and-sync.md
 create mode 100644 packages/web/src/content/docs/docs/reference/commands/ticket-plan-and-sync.mdx

diff --git a/.agents/skills/agent-browser/SKILL.md b/.agents/skills/agent-browser/SKILL.md
new file mode 100644
index 0000000..0b86ca2
--- /dev/null
+++ b/.agents/skills/agent-browser/SKILL.md
@@ -0,0 +1,727 @@
+---
+name: agent-browser
+description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
+allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
+---
+
+# Browser Automation with agent-browser
+
+The CLI uses Chrome/Chromium via CDP directly. Install via `npm i -g agent-browser`, `brew install agent-browser`, or `cargo install agent-browser`. Run `agent-browser install` to download Chrome. Run `agent-browser upgrade` to update to the latest version.
+
+## Core Workflow
+
+Every browser automation follows this pattern:
+
+1. **Navigate**: `agent-browser open <url>`
+2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)
+3. **Interact**: Use refs to click, fill, select
+4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Command Chaining
+
+Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls.
+
+```bash
+# Chain open + wait + snapshot in one call
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+
+# Chain multiple interactions
+agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3
+
+# Navigate and capture
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
+```
+
+**When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + wait + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs).
+
+## Handling Authentication
+
+When automating a site that requires login, choose the approach that fits:
+
+**Option 1: Import auth from the user's browser (fastest for one-off tasks)**
+
+```bash
+# Connect to the user's running Chrome (they're already logged in)
+agent-browser --auto-connect state save ./auth.json
+# Use that auth state
+agent-browser --state ./auth.json open https://app.example.com/dashboard
+```
+
+State files contain session tokens in plaintext -- add to `.gitignore` and delete when no longer needed. Set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest.
+
+**Option 2: Persistent profile (simplest for recurring tasks)**
+
+```bash
+# First run: login manually or via automation
+agent-browser --profile ~/.myapp open https://app.example.com/login
+# ... fill credentials, submit ...
+
+# All future runs: already authenticated
+agent-browser --profile ~/.myapp open https://app.example.com/dashboard
+```
+
+**Option 3: Session name (auto-save/restore cookies + localStorage)**
+
+```bash
+agent-browser --session-name myapp open https://app.example.com/login
+# ... login flow ...
+agent-browser close  # State auto-saved
+
+# Next time: state auto-restored
+agent-browser --session-name myapp open https://app.example.com/dashboard
+```
+
+**Option 4: Auth vault (credentials stored encrypted, login by name)**
+
+```bash
+echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
+agent-browser auth login myapp
+```
+
+`auth login` navigates with `load` and then waits for login form selectors to appear before filling/clicking, which is more reliable on delayed SPA login screens.
+
+**Option 5: State file (manual save/load)**
+
+```bash
+# After logging in:
+agent-browser state save ./auth.json
+# In a future session:
+agent-browser state load ./auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+See [references/authentication.md](references/authentication.md) for OAuth, 2FA, cookie-based auth, and token refresh patterns.
+
+## Essential Commands
+
+```bash
+# Navigation
+agent-browser open <url>              # Navigate (aliases: goto, navigate)
+agent-browser close                   # Close browser
+
+# Snapshot
+agent-browser snapshot -i             # Interactive elements with refs (recommended)
+agent-browser snapshot -s "#selector" # Scope to CSS selector
+
+# Interaction (use @refs from snapshot)
+agent-browser click @e1               # Click element
+agent-browser click @e1 --new-tab     # Click and open in new tab
+agent-browser fill @e2 "text"         # Clear and type text
+agent-browser type @e2 "text"         # Type without clearing
+agent-browser select @e1 "option"     # Select dropdown option
+agent-browser check @e1               # Check checkbox
+agent-browser press Enter             # Press key
+agent-browser keyboard type "text"    # Type at current focus (no selector)
+agent-browser keyboard inserttext "text"  # Insert without key events
+agent-browser scroll down 500         # Scroll page
+agent-browser scroll down 500 --selector "div.content"  # Scroll within a specific container
+
+# Get information
+agent-browser get text @e1            # Get element text
+agent-browser get url                 # Get current URL
+agent-browser get title               # Get page title
+agent-browser get cdp-url             # Get CDP WebSocket URL
+
+# Wait
+agent-browser wait @e1                # Wait for element
+agent-browser wait --load networkidle # Wait for network idle
+agent-browser wait --url "**/page"    # Wait for URL pattern
+agent-browser wait 2000               # Wait milliseconds
+agent-browser wait --text "Welcome"    # Wait for text to appear (substring match)
+agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
+agent-browser wait "#spinner" --state hidden  # Wait for element to disappear
+
+# Downloads
+agent-browser download @e1 ./file.pdf          # Click element to trigger download
+agent-browser wait --download ./output.zip     # Wait for any download to complete
+agent-browser --download-path ./downloads open <url>  # Set default download directory
+
+# Network
+agent-browser network requests                 # Inspect tracked requests
+agent-browser network requests --type xhr,fetch  # Filter by resource type
+agent-browser network requests --method POST   # Filter by HTTP method
+agent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)
+agent-browser network request <requestId>      # View full request/response detail
+agent-browser network route "**/api/*" --abort  # Block matching requests
+agent-browser network har start                # Start HAR recording
+agent-browser network har stop ./capture.har   # Stop and save HAR file
+
+# Viewport & Device Emulation
+agent-browser set viewport 1920 1080          # Set viewport size (default: 1280x720)
+agent-browser set viewport 1920 1080 2        # 2x retina (same CSS size, higher res screenshots)
+agent-browser set device "iPhone 14"          # Emulate device (viewport + user agent)
+
+# Capture
+agent-browser screenshot              # Screenshot to temp dir
+agent-browser screenshot --full       # Full page screenshot
+agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
+agent-browser screenshot --screenshot-dir ./shots  # Save to custom directory
+agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
+agent-browser pdf output.pdf          # Save as PDF
+
+# Live preview / streaming
+agent-browser stream enable           # Start runtime WebSocket streaming on an auto-selected port
+agent-browser stream enable --port 9223  # Bind a specific localhost port
+agent-browser stream status           # Inspect enabled state, port, connection, and screencasting
+agent-browser stream disable          # Stop runtime streaming and remove the .stream metadata file
+
+# Clipboard
+agent-browser clipboard read                      # Read text from clipboard
+agent-browser clipboard write "Hello, World!"     # Write text to clipboard
+agent-browser clipboard copy                      # Copy current selection
+agent-browser clipboard paste                     # Paste from clipboard
+
+# Dialogs (alert, confirm, prompt)
+agent-browser dialog accept              # Accept dialog
+agent-browser dialog accept "my input"   # Accept prompt dialog with text
+agent-browser dialog dismiss             # Dismiss/cancel dialog
+agent-browser dialog status              # Check if a dialog is currently open
+
+# Diff (compare page states)
+agent-browser diff snapshot                          # Compare current vs last snapshot
+agent-browser diff snapshot --baseline before.txt    # Compare current vs saved file
+agent-browser diff screenshot --baseline before.png  # Visual pixel diff
+agent-browser diff url <url1> <url2>                 # Compare two pages
+agent-browser diff url <url1> <url2> --wait-until networkidle  # Custom wait strategy
+agent-browser diff url <url1> <url2> --selector "#main"  # Scope to element
+```
+
+## Runtime Streaming
+
+Use `agent-browser stream enable` when you need a live WebSocket preview for an already-running session. This is the preferred runtime path because it does not require restarting the daemon. `stream enable` creates the server, `stream status` reports the bound port and connection state, and `stream disable` tears it down cleanly.
+
+If streaming must be present from the first daemon command, `AGENT_BROWSER_STREAM_PORT` still works at daemon startup, but that environment variable is not retroactive for sessions that are already running.
+
+## Batch Execution
+
+Execute multiple commands in a single invocation by piping a JSON array of string arrays to `batch`. This avoids per-command process startup overhead when running multi-step workflows.
+
+```bash
+echo '[
+  ["open", "https://example.com"],
+  ["snapshot", "-i"],
+  ["click", "@e1"],
+  ["screenshot", "result.png"]
+]' | agent-browser batch --json
+
+# Stop on first error
+agent-browser batch --bail < commands.json
+```
+
+Use `batch` when you have a known sequence of commands that don't depend on intermediate output. Use separate commands or `&&` chaining when you need to parse output between steps (e.g., snapshot to discover refs, then interact).
+
+## Common Patterns
+
+### Form Submission
+
+```bash
+agent-browser open https://example.com/signup
+agent-browser snapshot -i
+agent-browser fill @e1 "Jane Doe"
+agent-browser fill @e2 "jane@example.com"
+agent-browser select @e3 "California"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --load networkidle
+```
+
+### Authentication with Auth Vault (Recommended)
+
+```bash
+# Save credentials once (encrypted with AGENT_BROWSER_ENCRYPTION_KEY)
+# Recommended: pipe password via stdin to avoid shell history exposure
+echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
+
+# Login using saved profile (LLM never sees password)
+agent-browser auth login github
+
+# List/show/delete profiles
+agent-browser auth list
+agent-browser auth show github
+agent-browser auth delete github
+```
+
+`auth login` waits for username/password/submit selectors before interacting, with a timeout tied to the default action timeout.
+
+### Authentication with State Persistence
+
+```bash
+# Login once and save state
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "$USERNAME"
+agent-browser fill @e2 "$PASSWORD"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Reuse in future sessions
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+### Session Persistence
+
+```bash
+# Auto-save/restore cookies and localStorage across browser restarts
+agent-browser --session-name myapp open https://app.example.com/login
+# ... login flow ...
+agent-browser close  # State auto-saved to ~/.agent-browser/sessions/
+
+# Next time, state is auto-loaded
+agent-browser --session-name myapp open https://app.example.com/dashboard
+
+# Encrypt state at rest
+export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
+agent-browser --session-name secure open https://app.example.com
+
+# Manage saved states
+agent-browser state list
+agent-browser state show myapp-default.json
+agent-browser state clear myapp
+agent-browser state clean --older-than 7
+```
+
+### Working with Iframes
+
+Iframe content is automatically inlined in snapshots. Refs inside iframes carry frame context, so you can interact with them directly.
+
+```bash
+agent-browser open https://example.com/checkout
+agent-browser snapshot -i
+# @e1 [heading] "Checkout"
+# @e2 [Iframe] "payment-frame"
+#   @e3 [input] "Card number"
+#   @e4 [input] "Expiry"
+#   @e5 [button] "Pay"
+
+# Interact directly — no frame switch needed
+agent-browser fill @e3 "4111111111111111"
+agent-browser fill @e4 "12/28"
+agent-browser click @e5
+
+# To scope a snapshot to one iframe:
+agent-browser frame @e2
+agent-browser snapshot -i         # Only iframe content
+agent-browser frame main          # Return to main frame
+```
+
+### Data Extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e5           # Get specific element text
+agent-browser get text body > page.txt  # Get all page text
+
+# JSON output for parsing
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+```
+
+### Parallel Sessions
+
+```bash
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
+
+agent-browser --session site1 snapshot -i
+agent-browser --session site2 snapshot -i
+
+agent-browser session list
+```
+
+### Connect to Existing Chrome
+
+```bash
+# Auto-discover running Chrome with remote debugging enabled
+agent-browser --auto-connect open https://example.com
+agent-browser --auto-connect snapshot
+
+# Or with explicit CDP port
+agent-browser --cdp 9222 snapshot
+```
+
+Auto-connect discovers Chrome via `DevToolsActivePort`, common debugging ports (9222, 9229), and falls back to a direct WebSocket connection if HTTP-based CDP discovery fails.
+
+### Color Scheme (Dark Mode)
+
+```bash
+# Persistent dark mode via flag (applies to all pages and new tabs)
+agent-browser --color-scheme dark open https://example.com
+
+# Or via environment variable
+AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
+
+# Or set during session (persists for subsequent commands)
+agent-browser set media dark
+```
+
+### Viewport & Responsive Testing
+
+```bash
+# Set a custom viewport size (default is 1280x720)
+agent-browser set viewport 1920 1080
+agent-browser screenshot desktop.png
+
+# Test mobile-width layout
+agent-browser set viewport 375 812
+agent-browser screenshot mobile.png
+
+# Retina/HiDPI: same CSS layout at 2x pixel density
+# Screenshots stay at logical viewport size, but content renders at higher DPI
+agent-browser set viewport 1920 1080 2
+agent-browser screenshot retina.png
+
+# Device emulation (sets viewport + user agent in one step)
+agent-browser set device "iPhone 14"
+agent-browser screenshot device.png
+```
+
+The `scale` parameter (3rd argument) sets `window.devicePixelRatio` without changing CSS layout. Use it when testing retina rendering or capturing higher-resolution screenshots.
+
+### Visual Browser (Debugging)
+
+```bash
+agent-browser --headed open https://example.com
+agent-browser highlight @e1          # Highlight element
+agent-browser inspect                # Open Chrome DevTools for the active page
+agent-browser record start demo.webm # Record session
+agent-browser profiler start         # Start Chrome DevTools profiling
+agent-browser profiler stop trace.json # Stop and save profile (path optional)
+```
+
+Use `AGENT_BROWSER_HEADED=1` to enable headed mode via environment variable. Browser extensions work in both headed and headless mode.
+
+### Local Files (PDFs, HTML)
+
+```bash
+# Open local files with file:// URLs
+agent-browser --allow-file-access open file:///path/to/document.pdf
+agent-browser --allow-file-access open file:///path/to/page.html
+agent-browser screenshot output.png
+```
+
+### iOS Simulator (Mobile Safari)
+
+```bash
+# List available iOS simulators
+agent-browser device list
+
+# Launch Safari on a specific device
+agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
+
+# Same workflow as desktop - snapshot, interact, re-snapshot
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1          # Tap (alias for click)
+agent-browser -p ios fill @e2 "text"
+agent-browser -p ios swipe up         # Mobile-specific gesture
+
+# Take screenshot
+agent-browser -p ios screenshot mobile.png
+
+# Close session (shuts down simulator)
+agent-browser -p ios close
+```
+
+**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
+
+**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.
+
+## Security
+
+All security features are opt-in. By default, agent-browser imposes no restrictions on navigation, actions, or output.
+
+### Content Boundaries (Recommended for AI Agents)
+
+Enable `--content-boundaries` to wrap page-sourced output in markers that help LLMs distinguish tool output from untrusted page content:
+
+```bash
+export AGENT_BROWSER_CONTENT_BOUNDARIES=1
+agent-browser snapshot
+# Output:
+# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
+# [accessibility tree]
+# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
+```
+
+### Domain Allowlist
+
+Restrict navigation to trusted domains. Wildcards like `*.example.com` also match the bare domain `example.com`. Sub-resource requests, WebSocket, and EventSource connections to non-allowed domains are also blocked. Include CDN domains your target pages depend on:
+
+```bash
+export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"
+agent-browser open https://example.com        # OK
+agent-browser open https://malicious.com       # Blocked
+```
+
+### Action Policy
+
+Use a policy file to gate destructive actions:
+
+```bash
+export AGENT_BROWSER_ACTION_POLICY=./policy.json
+```
+
+Example `policy.json`:
+
+```json
+{ "default": "deny", "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"] }
+```
+
+Auth vault operations (`auth login`, etc.) bypass action policy but domain allowlist still applies.
+
+### Output Limits
+
+Prevent context flooding from large pages:
+
+```bash
+export AGENT_BROWSER_MAX_OUTPUT=50000
+```
+
+## Diffing (Verifying Changes)
+
+Use `diff snapshot` after performing an action to verify it had the intended effect. This compares the current accessibility tree against the last snapshot taken in the session.
+
+```bash
+# Typical workflow: snapshot -> action -> diff
+agent-browser snapshot -i          # Take baseline snapshot
+agent-browser click @e2            # Perform action
+agent-browser diff snapshot        # See what changed (auto-compares to last snapshot)
+```
+
+For visual regression testing or monitoring:
+
+```bash
+# Save a baseline screenshot, then compare later
+agent-browser screenshot baseline.png
+# ... time passes or changes are made ...
+agent-browser diff screenshot --baseline baseline.png
+
+# Compare staging vs production
+agent-browser diff url https://staging.example.com https://prod.example.com --screenshot
+```
+
+`diff snapshot` output uses `+` for additions and `-` for removals, similar to git diff. `diff screenshot` produces a diff image with changed pixels highlighted in red, plus a mismatch percentage.
+
+## Timeouts and Slow Pages
+
+The default timeout is 25 seconds. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
+
+```bash
+# Wait for network activity to settle (best for slow pages)
+agent-browser wait --load networkidle
+
+# Wait for a specific element to appear
+agent-browser wait "#content"
+agent-browser wait @e1
+
+# Wait for a specific URL pattern (useful after redirects)
+agent-browser wait --url "**/dashboard"
+
+# Wait for a JavaScript condition
+agent-browser wait --fn "document.readyState === 'complete'"
+
+# Wait a fixed duration (milliseconds) as a last resort
+agent-browser wait 5000
+```
+
+When dealing with consistently slow websites, use `wait --load networkidle` after `open` to ensure the page is fully loaded before taking a snapshot. If a specific element is slow to render, wait for it directly with `wait <selector>` or `wait @ref`.
+
+## JavaScript Dialogs (alert / confirm / prompt)
+
+When a page opens a JavaScript dialog (`alert()`, `confirm()`, or `prompt()`), it blocks all other browser commands (snapshot, screenshot, click, etc.) until the dialog is dismissed. If commands start timing out unexpectedly, check for a pending dialog:
+
+```bash
+# Check if a dialog is blocking
+agent-browser dialog status
+
+# Accept the dialog (dismiss the alert / click OK)
+agent-browser dialog accept
+
+# Accept a prompt dialog with input text
+agent-browser dialog accept "my input"
+
+# Dismiss the dialog (click Cancel)
+agent-browser dialog dismiss
+```
+
+When a dialog is pending, all command responses include a `warning` field indicating the dialog type and message. In `--json` mode this appears as a `"warning"` key in the response object.
+
+## Session Management and Cleanup
+
+When running multiple agents or automations concurrently, always use named sessions to avoid conflicts:
+
+```bash
+# Each agent gets its own isolated session
+agent-browser --session agent1 open site-a.com
+agent-browser --session agent2 open site-b.com
+
+# Check active sessions
+agent-browser session list
+```
+
+Always close your browser session when done to avoid leaked processes:
+
+```bash
+agent-browser close                    # Close default session
+agent-browser --session agent1 close   # Close specific session
+```
+
+If a previous session was not closed properly, the daemon may still be running. Use `agent-browser close` to clean it up before starting new work.
+
+To auto-shutdown the daemon after a period of inactivity (useful for ephemeral/CI environments):
+
+```bash
+AGENT_BROWSER_IDLE_TIMEOUT_MS=60000 agent-browser open example.com
+```
+
+## Ref Lifecycle (Important)
+
+Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after:
+
+- Clicking links or buttons that navigate
+- Form submissions
+- Dynamic content loading (dropdowns, modals)
+
+```bash
+agent-browser click @e5              # Navigates to new page
+agent-browser snapshot -i            # MUST re-snapshot
+agent-browser click @e1              # Use new refs
+```
+
+## Annotated Screenshots (Vision Mode)
+
+Use `--annotate` to take a screenshot with numbered labels overlaid on interactive elements. Each label `[N]` maps to ref `@eN`. This also caches refs, so you can interact with elements immediately without a separate snapshot.
+
+```bash
+agent-browser screenshot --annotate
+# Output includes the image path and a legend:
+#   [1] @e1 button "Submit"
+#   [2] @e2 link "Home"
+#   [3] @e3 textbox "Email"
+agent-browser click @e2              # Click using ref from annotated screenshot
+```
+
+Use annotated screenshots when:
+
+- The page has unlabeled icon buttons or visual-only elements
+- You need to verify visual layout or styling
+- Canvas or chart elements are present (invisible to text snapshots)
+- You need spatial reasoning about element positions
+
+## Semantic Locators (Alternative to Refs)
+
+When refs are unavailable or unreliable, use semantic locators:
+
+```bash
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+agent-browser find placeholder "Search" type "query"
+agent-browser find testid "submit-btn" click
+```
+
+## JavaScript Evaluation (eval)
+
+Use `eval` to run JavaScript in the browser context. **Shell quoting can corrupt complex expressions** -- use `--stdin` or `-b` to avoid issues.
+
+```bash
+# Simple expressions work with regular quoting
+agent-browser eval 'document.title'
+agent-browser eval 'document.querySelectorAll("img").length'
+
+# Complex JS: use --stdin with heredoc (RECOMMENDED)
+agent-browser eval --stdin <<'EVALEOF'
+JSON.stringify(
+  Array.from(document.querySelectorAll("img"))
+    .filter(i => !i.alt)
+    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
+)
+EVALEOF
+
+# Alternative: base64 encoding (avoids all shell escaping issues)
+agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"
+```
+
+**Why this matters:** When the shell processes your command, inner double quotes, `!` characters (history expansion), backticks, and `$()` can all corrupt the JavaScript before it reaches agent-browser. The `--stdin` and `-b` flags bypass shell interpretation entirely.
+
+**Rules of thumb:**
+
+- Single-line, no nested quotes -> regular `eval 'expression'` with single quotes is fine
+- Nested quotes, arrow functions, template literals, or multiline -> use `eval --stdin <<'EVALEOF'`
+- Programmatic/generated scripts -> use `eval -b` with base64
+
+## Configuration File
+
+Create `agent-browser.json` in the project root for persistent settings:
+
+```json
+{
+  "headed": true,
+  "proxy": "http://localhost:8080",
+  "profile": "./browser-data"
+}
+```
+
+Priority (lowest to highest): `~/.agent-browser/config.json` < `./agent-browser.json` < env vars < CLI flags. Use `--config <path>` or `AGENT_BROWSER_CONFIG` env var for a custom config file (exits with error if missing/invalid). All CLI options map to camelCase keys (e.g., `--executable-path` -> `"executablePath"`). Boolean flags accept `true`/`false` values (e.g., `--headed false` overrides config). Extensions from user and project configs are merged, not replaced.
+
+## Deep-Dive Documentation
+
+| Reference                                                            | When to Use                                               |
+| -------------------------------------------------------------------- | --------------------------------------------------------- |
+| [references/commands.md](references/commands.md)                     | Full command reference with all options                   |
+| [references/snapshot-refs.md](references/snapshot-refs.md)           | Ref lifecycle, invalidation rules, troubleshooting        |
+| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |
+| [references/authentication.md](references/authentication.md)         | Login flows, OAuth, 2FA handling, state reuse             |
+| [references/video-recording.md](references/video-recording.md)       | Recording workflows for debugging and documentation       |
+| [references/profiling.md](references/profiling.md)                   | Chrome DevTools profiling for performance analysis        |
+| [references/proxy-support.md](references/proxy-support.md)           | Proxy configuration, geo-testing, rotating proxies        |
+
+## Browser Engine Selection
+
+Use `--engine` to choose a local browser engine. The default is `chrome`.
+
+```bash
+# Use Lightpanda (fast headless browser, requires separate install)
+agent-browser --engine lightpanda open example.com
+
+# Via environment variable
+export AGENT_BROWSER_ENGINE=lightpanda
+agent-browser open example.com
+
+# With custom binary path
+agent-browser --engine lightpanda --executable-path /path/to/lightpanda open example.com
+```
+
+Supported engines:
+- `chrome` (default) -- Chrome/Chromium via CDP
+- `lightpanda` -- Lightpanda headless browser via CDP (10x faster, 10x less memory than Chrome)
+
+Lightpanda does not support `--extension`, `--profile`, `--state`, or `--allow-file-access`. Install Lightpanda from https://lightpanda.io/docs/open-source/installation.
+
+## Ready-to-Use Templates
+
+| Template                                                                 | Description                         |
+| ------------------------------------------------------------------------ | ----------------------------------- |
+| [templates/form-automation.sh](templates/form-automation.sh)             | Form filling with validation        |
+| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state             |
+| [templates/capture-workflow.sh](templates/capture-workflow.sh)           | Content extraction with screenshots |
+
+```bash
+./templates/form-automation.sh https://example.com/form
+./templates/authenticated-session.sh https://app.example.com/login
+./templates/capture-workflow.sh https://example.com ./output
+```
diff --git a/.agents/skills/agent-browser/references/authentication.md b/.agents/skills/agent-browser/references/authentication.md
new file mode 100644
index 0000000..89f4788
--- /dev/null
+++ b/.agents/skills/agent-browser/references/authentication.md
@@ -0,0 +1,303 @@
+# Authentication Patterns
+
+Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
+
+**Related**: [session-management.md](session-management.md) for state persistence details, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Import Auth from Your Browser](#import-auth-from-your-browser)
+- [Persistent Profiles](#persistent-profiles)
+- [Session Persistence](#session-persistence)
+- [Basic Login Flow](#basic-login-flow)
+- [Saving Authentication State](#saving-authentication-state)
+- [Restoring Authentication](#restoring-authentication)
+- [OAuth / SSO Flows](#oauth--sso-flows)
+- [Two-Factor Authentication](#two-factor-authentication)
+- [HTTP Basic Auth](#http-basic-auth)
+- [Cookie-Based Auth](#cookie-based-auth)
+- [Token Refresh Handling](#token-refresh-handling)
+- [Security Best Practices](#security-best-practices)
+
+## Import Auth from Your Browser
+
+The fastest way to authenticate is to reuse cookies from a Chrome session you are already logged into.
+
+**Step 1: Start Chrome with remote debugging**
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+```
+
+Log in to your target site(s) in this Chrome window as you normally would.
+
+> **Security note:** `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect and read cookies, execute JS, etc. Only use on trusted machines and close Chrome when done.
+
+**Step 2: Grab the auth state**
+
+```bash
+# Auto-discover the running Chrome and save its cookies + localStorage
+agent-browser --auto-connect state save ./my-auth.json
+```
+
+**Step 3: Reuse in automation**
+
+```bash
+# Load auth at launch
+agent-browser --state ./my-auth.json open https://app.example.com/dashboard
+
+# Or load into an existing session
+agent-browser state load ./my-auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+This works for any site, including those with complex OAuth flows, SSO, or 2FA -- as long as Chrome already has valid session cookies.
+
+> **Security note:** State files contain session tokens in plaintext. Add them to `.gitignore`, delete when no longer needed, and set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest. See [Security Best Practices](#security-best-practices).
+
+**Tip:** Combine with `--session-name` so the imported auth auto-persists across restarts:
+
+```bash
+agent-browser --session-name myapp state load ./my-auth.json
+# From now on, state is auto-saved/restored for "myapp"
+```
+
+## Persistent Profiles
+
+Use `--profile` to point agent-browser at a Chrome user data directory. This persists everything (cookies, IndexedDB, service workers, cache) across browser restarts without explicit save/load:
+
+```bash
+# First run: login once
+agent-browser --profile ~/.myapp-profile open https://app.example.com/login
+# ... complete login flow ...
+
+# All subsequent runs: already authenticated
+agent-browser --profile ~/.myapp-profile open https://app.example.com/dashboard
+```
+
+Use different paths for different projects or test users:
+
+```bash
+agent-browser --profile ~/.profiles/admin open https://app.example.com
+agent-browser --profile ~/.profiles/viewer open https://app.example.com
+```
+
+Or set via environment variable:
+
+```bash
+export AGENT_BROWSER_PROFILE=~/.myapp-profile
+agent-browser open https://app.example.com/dashboard
+```
+
+## Session Persistence
+
+Use `--session-name` to auto-save and restore cookies + localStorage by name, without managing files:
+
+```bash
+# Auto-saves state on close, auto-restores on next launch
+agent-browser --session-name twitter open https://twitter.com
+# ... login flow ...
+agent-browser close  # state saved to ~/.agent-browser/sessions/
+
+# Next time: state is automatically restored
+agent-browser --session-name twitter open https://twitter.com
+```
+
+Encrypt state at rest:
+
+```bash
+export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
+agent-browser --session-name secure open https://app.example.com
+```
+
+## Basic Login Flow
+
+```bash
+# Navigate to login page
+agent-browser open https://app.example.com/login
+agent-browser wait --load networkidle
+
+# Get form elements
+agent-browser snapshot -i
+# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"
+
+# Fill credentials
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+
+# Submit
+agent-browser click @e3
+agent-browser wait --load networkidle
+
+# Verify login succeeded
+agent-browser get url  # Should be dashboard, not login
+```
+
+## Saving Authentication State
+
+After logging in, save state for reuse:
+
+```bash
+# Login first (see above)
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+
+# Save authenticated state
+agent-browser state save ./auth-state.json
+```
+
+## Restoring Authentication
+
+Skip login by loading saved state:
+
+```bash
+# Load saved auth state
+agent-browser state load ./auth-state.json
+
+# Navigate directly to protected page
+agent-browser open https://app.example.com/dashboard
+
+# Verify authenticated
+agent-browser snapshot -i
+```
+
+## OAuth / SSO Flows
+
+For OAuth redirects:
+
+```bash
+# Start OAuth flow
+agent-browser open https://app.example.com/auth/google
+
+# Handle redirects automatically
+agent-browser wait --url "**/accounts.google.com**"
+agent-browser snapshot -i
+
+# Fill Google credentials
+agent-browser fill @e1 "user@gmail.com"
+agent-browser click @e2  # Next button
+agent-browser wait 2000
+agent-browser snapshot -i
+agent-browser fill @e3 "password"
+agent-browser click @e4  # Sign in
+
+# Wait for redirect back
+agent-browser wait --url "**/app.example.com**"
+agent-browser state save ./oauth-state.json
+```
+
+## Two-Factor Authentication
+
+Handle 2FA with manual intervention:
+
+```bash
+# Login with credentials
+agent-browser open https://app.example.com/login --headed  # Show browser
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+
+# Wait for user to complete 2FA manually
+echo "Complete 2FA in the browser window..."
+agent-browser wait --url "**/dashboard" --timeout 120000
+
+# Save state after 2FA
+agent-browser state save ./2fa-state.json
+```
+
+## HTTP Basic Auth
+
+For sites using HTTP Basic Authentication:
+
+```bash
+# Set credentials before navigation
+agent-browser set credentials username password
+
+# Navigate to protected resource
+agent-browser open https://protected.example.com/api
+```
+
+## Cookie-Based Auth
+
+Manually set authentication cookies:
+
+```bash
+# Set auth cookie
+agent-browser cookies set session_token "abc123xyz"
+
+# Navigate to protected page
+agent-browser open https://app.example.com/dashboard
+```
+
+## Token Refresh Handling
+
+For sessions with expiring tokens:
+
+```bash
+#!/bin/bash
+# Wrapper that handles token refresh
+
+STATE_FILE="./auth-state.json"
+
+# Try loading existing state
+if [[ -f "$STATE_FILE" ]]; then
+    agent-browser state load "$STATE_FILE"
+    agent-browser open https://app.example.com/dashboard
+
+    # Check if session is still valid
+    URL=$(agent-browser get url)
+    if [[ "$URL" == *"/login"* ]]; then
+        echo "Session expired, re-authenticating..."
+        # Perform fresh login
+        agent-browser snapshot -i
+        agent-browser fill @e1 "$USERNAME"
+        agent-browser fill @e2 "$PASSWORD"
+        agent-browser click @e3
+        agent-browser wait --url "**/dashboard"
+        agent-browser state save "$STATE_FILE"
+    fi
+else
+    # First-time login
+    agent-browser open https://app.example.com/login
+    # ... login flow ...
+fi
+```
+
+## Security Best Practices
+
+1. **Never commit state files** - They contain session tokens
+   ```bash
+   echo "*.auth-state.json" >> .gitignore
+   ```
+
+2. **Use environment variables for credentials**
+   ```bash
+   agent-browser fill @e1 "$APP_USERNAME"
+   agent-browser fill @e2 "$APP_PASSWORD"
+   ```
+
+3. **Clean up after automation**
+   ```bash
+   agent-browser cookies clear
+   rm -f ./auth-state.json
+   ```
+
+4. **Use short-lived sessions for CI/CD**
+   ```bash
+   # Don't persist state in CI
+   agent-browser open https://app.example.com/login
+   # ... login and perform actions ...
+   agent-browser close  # Session ends, nothing persisted
+   ```
diff --git a/.agents/skills/agent-browser/references/commands.md b/.agents/skills/agent-browser/references/commands.md
new file mode 100644
index 0000000..46de5f1
--- /dev/null
+++ b/.agents/skills/agent-browser/references/commands.md
@@ -0,0 +1,292 @@
+# Command Reference
+
+Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md.
+
+## Navigation
+
+```bash
+agent-browser open <url>      # Navigate to URL (aliases: goto, navigate)
+                              # Supports: https://, http://, file://, about:, data://
+                              # Auto-prepends https:// if no protocol given
+agent-browser back            # Go back
+agent-browser forward         # Go forward
+agent-browser reload          # Reload page
+agent-browser close           # Close browser (aliases: quit, exit)
+agent-browser connect 9222    # Connect to browser via CDP port
+```
+
+## Snapshot (page analysis)
+
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (recommended)
+agent-browser snapshot -c         # Compact output
+agent-browser snapshot -d 3       # Limit depth to 3
+agent-browser snapshot -s "#main" # Scope to CSS selector
+```
+
+## Interactions (use @refs from snapshot)
+
+```bash
+agent-browser click @e1           # Click
+agent-browser click @e1 --new-tab # Click and open in new tab
+agent-browser dblclick @e1        # Double-click
+agent-browser focus @e1           # Focus element
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key (alias: key)
+agent-browser press Control+a     # Key combination
+agent-browser keydown Shift       # Hold key down
+agent-browser keyup Shift         # Release key
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown option
+agent-browser select @e1 "a" "b"  # Select multiple options
+agent-browser scroll down 500     # Scroll page (default: down 300px)
+agent-browser scrollintoview @e1  # Scroll element into view (alias: scrollinto)
+agent-browser drag @e1 @e2        # Drag and drop
+agent-browser upload @e1 file.pdf # Upload files
+```
+
+## Get Information
+
+```bash
+agent-browser get text @e1        # Get element text
+agent-browser get html @e1        # Get innerHTML
+agent-browser get value @e1       # Get input value
+agent-browser get attr @e1 href   # Get attribute
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+agent-browser get cdp-url         # Get CDP WebSocket URL
+agent-browser get count ".item"   # Count matching elements
+agent-browser get box @e1         # Get bounding box
+agent-browser get styles @e1      # Get computed styles (font, color, bg, etc.)
+```
+
+## Check State
+
+```bash
+agent-browser is visible @e1      # Check if visible
+agent-browser is enabled @e1      # Check if enabled
+agent-browser is checked @e1      # Check if checked
+```
+
+## Screenshots and PDF
+
+```bash
+agent-browser screenshot          # Save to temporary directory
+agent-browser screenshot path.png # Save to specific path
+agent-browser screenshot --full   # Full page
+agent-browser pdf output.pdf      # Save as PDF
+```
+
+## Video Recording
+
+```bash
+agent-browser record start ./demo.webm    # Start recording
+agent-browser click @e1                   # Perform actions
+agent-browser record stop                 # Stop and save video
+agent-browser record restart ./take2.webm # Stop current + start new
+```
+
+## Wait
+
+```bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text (or -t)
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern (or -u)
+agent-browser wait --load networkidle      # Wait for network idle (or -l)
+agent-browser wait --fn "window.ready"     # Wait for JS condition (or -f)
+```
+
+## Mouse Control
+
+```bash
+agent-browser mouse move 100 200      # Move mouse
+agent-browser mouse down left         # Press button
+agent-browser mouse up left           # Release button
+agent-browser mouse wheel 100         # Scroll wheel
+```
+
+## Semantic Locators (alternative to refs)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find text "Sign In" click --exact      # Exact match only
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find placeholder "Search" type "query"
+agent-browser find alt "Logo" click
+agent-browser find title "Close" click
+agent-browser find testid "submit-btn" click
+agent-browser find first ".item" click
+agent-browser find last ".item" click
+agent-browser find nth 2 "a" hover
+```
+
+## Browser Settings
+
+```bash
+agent-browser set viewport 1920 1080          # Set viewport size
+agent-browser set viewport 1920 1080 2        # 2x retina (same CSS size, higher res screenshots)
+agent-browser set device "iPhone 14"          # Emulate device
+agent-browser set geo 37.7749 -122.4194       # Set geolocation (alias: geolocation)
+agent-browser set offline on                  # Toggle offline mode
+agent-browser set headers '{"X-Key":"v"}'     # Extra HTTP headers
+agent-browser set credentials user pass       # HTTP basic auth (alias: auth)
+agent-browser set media dark                  # Emulate color scheme
+agent-browser set media light reduced-motion  # Light mode + reduced motion
+```
+
+## Cookies and Storage
+
+```bash
+agent-browser cookies                     # Get all cookies
+agent-browser cookies set name value      # Set cookie
+agent-browser cookies clear               # Clear cookies
+agent-browser storage local               # Get all localStorage
+agent-browser storage local key           # Get specific key
+agent-browser storage local set k v       # Set value
+agent-browser storage local clear         # Clear all
+```
+
+## Network
+
+```bash
+agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body '{}'  # Mock response
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests
+agent-browser network requests --filter api    # Filter requests
+```
+
+## Tabs and Windows
+
+```bash
+agent-browser tab                 # List tabs
+agent-browser tab new [url]       # New tab
+agent-browser tab 2               # Switch to tab by index
+agent-browser tab close           # Close current tab
+agent-browser tab close 2         # Close tab by index
+agent-browser window new          # New window
+```
+
+## Frames
+
+```bash
+agent-browser frame "#iframe"     # Switch to iframe by CSS selector
+agent-browser frame @e3           # Switch to iframe by element ref
+agent-browser frame main          # Back to main frame
+```
+
+### Iframe support
+
+Iframes are detected automatically during snapshots. When the main-frame snapshot runs, `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the output (one level of nesting; iframes within iframes are not expanded).
+
+```bash
+agent-browser snapshot -i
+# @e3 [Iframe] "payment-frame"
+#   @e4 [input] "Card number"
+#   @e5 [button] "Pay"
+
+# Interact directly — refs inside iframes already work
+agent-browser fill @e4 "4111111111111111"
+agent-browser click @e5
+
+# Or switch frame context for scoped snapshots
+agent-browser frame @e3               # Switch using element ref
+agent-browser snapshot -i             # Snapshot scoped to that iframe
+agent-browser frame main              # Return to main frame
+```
+
+The `frame` command accepts:
+- **Element refs** — `frame @e3` resolves the ref to an iframe element
+- **CSS selectors** — `frame "#payment-iframe"` finds the iframe by selector
+- **Frame name/URL** — matches against the browser's frame tree
+
+## Dialogs
+
+```bash
+agent-browser dialog accept [text]  # Accept dialog
+agent-browser dialog dismiss        # Dismiss dialog
+```
+
+## JavaScript
+
+```bash
+agent-browser eval "document.title"          # Simple expressions only
+agent-browser eval -b "<base64>"             # Any JavaScript (base64 encoded)
+agent-browser eval --stdin                   # Read script from stdin
+```
+
+Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone.
+
+```bash
+# Base64 encode your script, then:
+agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="
+
+# Or use stdin with heredoc for multiline scripts:
+cat <<'EOF' | agent-browser eval --stdin
+const links = document.querySelectorAll('a');
+Array.from(links).map(a => a.href);
+EOF
+```
+
+## State Management
+
+```bash
+agent-browser state save auth.json    # Save cookies, storage, auth state
+agent-browser state load auth.json    # Restore saved state
+```
+
+## Global Options
+
+```bash
+agent-browser --session <name> ...    # Isolated browser session
+agent-browser --json ...              # JSON output for parsing
+agent-browser --headed ...            # Show browser window (not headless)
+agent-browser --full ...              # Full page screenshot (-f)
+agent-browser --cdp <port> ...        # Connect via Chrome DevTools Protocol
+agent-browser -p <provider> ...       # Cloud browser provider (--provider)
+agent-browser --proxy <url> ...       # Use proxy server
+agent-browser --proxy-bypass <hosts>  # Hosts to bypass proxy
+agent-browser --headers <json> ...    # HTTP headers scoped to URL's origin
+agent-browser --executable-path <p>   # Custom browser executable
+agent-browser --extension <path> ...  # Load browser extension (repeatable)
+agent-browser --ignore-https-errors   # Ignore SSL certificate errors
+agent-browser --help                  # Show help (-h)
+agent-browser --version               # Show version (-V)
+agent-browser <command> --help        # Show detailed help for a command
+```
+
+## Debugging
+
+```bash
+agent-browser --headed open example.com   # Show browser window
+agent-browser --cdp 9222 snapshot         # Connect via CDP port
+agent-browser connect 9222                # Alternative: connect command
+agent-browser console                     # View console messages
+agent-browser console --clear             # Clear console
+agent-browser errors                      # View page errors
+agent-browser errors --clear              # Clear errors
+agent-browser highlight @e1               # Highlight element
+agent-browser inspect                     # Open Chrome DevTools for this session
+agent-browser trace start                 # Start recording trace
+agent-browser trace stop trace.zip        # Stop and save trace
+agent-browser profiler start              # Start Chrome DevTools profiling
+agent-browser profiler stop trace.json    # Stop and save profile
+```
+
+## Environment Variables
+
+```bash
+AGENT_BROWSER_SESSION="mysession"            # Default session name
+AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path
+AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # Comma-separated extension paths
+AGENT_BROWSER_PROVIDER="browserbase"         # Cloud browser provider
+AGENT_BROWSER_STREAM_PORT="9223"             # WebSocket streaming port
+AGENT_BROWSER_HOME="/path/to/agent-browser"  # Custom install location
+```
diff --git a/.agents/skills/agent-browser/references/profiling.md b/.agents/skills/agent-browser/references/profiling.md
new file mode 100644
index 0000000..bd47eaa
--- /dev/null
+++ b/.agents/skills/agent-browser/references/profiling.md
@@ -0,0 +1,120 @@
+# Profiling
+
+Capture Chrome DevTools performance profiles during browser automation for performance analysis.
+
+**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Basic Profiling](#basic-profiling)
+- [Profiler Commands](#profiler-commands)
+- [Categories](#categories)
+- [Use Cases](#use-cases)
+- [Output Format](#output-format)
+- [Viewing Profiles](#viewing-profiles)
+- [Limitations](#limitations)
+
+## Basic Profiling
+
+```bash
+# Start profiling
+agent-browser profiler start
+
+# Perform actions
+agent-browser navigate https://example.com
+agent-browser click "#button"
+agent-browser wait 1000
+
+# Stop and save
+agent-browser profiler stop ./trace.json
+```
+
+## Profiler Commands
+
+```bash
+# Start profiling with default categories
+agent-browser profiler start
+
+# Start with custom trace categories
+agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
+
+# Stop profiling and save to file
+agent-browser profiler stop ./trace.json
+```
+
+## Categories
+
+The `--categories` flag accepts a comma-separated list of Chrome trace categories. Default categories include:
+
+- `devtools.timeline` -- standard DevTools performance traces
+- `v8.execute` -- time spent running JavaScript
+- `blink` -- renderer events
+- `blink.user_timing` -- `performance.mark()` / `performance.measure()` calls
+- `latencyInfo` -- input-to-latency tracking
+- `renderer.scheduler` -- task scheduling and execution
+- `toplevel` -- broad-spectrum basic events
+
+Several `disabled-by-default-*` categories are also included for detailed timeline, call stack, and V8 CPU profiling data.
+
+## Use Cases
+
+### Diagnosing Slow Page Loads
+
+```bash
+agent-browser profiler start
+agent-browser navigate https://app.example.com
+agent-browser wait --load networkidle
+agent-browser profiler stop ./page-load-profile.json
+```
+
+### Profiling User Interactions
+
+```bash
+agent-browser navigate https://app.example.com
+agent-browser profiler start
+agent-browser click "#submit"
+agent-browser wait 2000
+agent-browser profiler stop ./interaction-profile.json
+```
+
+### CI Performance Regression Checks
+
+```bash
+#!/bin/bash
+agent-browser profiler start
+agent-browser navigate https://app.example.com
+agent-browser wait --load networkidle
+agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"
+```
+
+## Output Format
+
+The output is a JSON file in Chrome Trace Event format:
+
+```json
+{
+  "traceEvents": [
+    { "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
+    ...
+  ],
+  "metadata": {
+    "clock-domain": "LINUX_CLOCK_MONOTONIC"
+  }
+}
+```
+
+The `metadata.clock-domain` field is set based on the host platform (Linux or macOS). On Windows it is omitted.
+
+## Viewing Profiles
+
+Load the output JSON file in any of these tools:
+
+- **Chrome DevTools**: Performance panel > Load profile (Ctrl+Shift+I > Performance)
+- **Perfetto UI**: https://ui.perfetto.dev/ -- drag and drop the JSON file
+- **Trace Viewer**: `chrome://tracing` in any Chromium browser
+
+## Limitations
+
+- Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
+- Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
+- Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.
diff --git a/.agents/skills/agent-browser/references/proxy-support.md b/.agents/skills/agent-browser/references/proxy-support.md
new file mode 100644
index 0000000..e86a8fe
--- /dev/null
+++ b/.agents/skills/agent-browser/references/proxy-support.md
@@ -0,0 +1,194 @@
+# Proxy Support
+
+Proxy configuration for geo-testing, rate limiting avoidance, and corporate environments.
+
+**Related**: [commands.md](commands.md) for global options, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Basic Proxy Configuration](#basic-proxy-configuration)
+- [Authenticated Proxy](#authenticated-proxy)
+- [SOCKS Proxy](#socks-proxy)
+- [Proxy Bypass](#proxy-bypass)
+- [Common Use Cases](#common-use-cases)
+- [Verifying Proxy Connection](#verifying-proxy-connection)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+
+## Basic Proxy Configuration
+
+Use the `--proxy` flag or set proxy via environment variable:
+
+```bash
+# Via CLI flag
+agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
+
+# Via environment variable
+export HTTP_PROXY="http://proxy.example.com:8080"
+agent-browser open https://example.com
+
+# HTTPS proxy
+export HTTPS_PROXY="https://proxy.example.com:8080"
+agent-browser open https://example.com
+
+# Both
+export HTTP_PROXY="http://proxy.example.com:8080"
+export HTTPS_PROXY="http://proxy.example.com:8080"
+agent-browser open https://example.com
+```
+
+## Authenticated Proxy
+
+For proxies requiring authentication:
+
+```bash
+# Include credentials in URL
+export HTTP_PROXY="http://username:password@proxy.example.com:8080"
+agent-browser open https://example.com
+```
+
+## SOCKS Proxy
+
+```bash
+# SOCKS5 proxy
+export ALL_PROXY="socks5://proxy.example.com:1080"
+agent-browser open https://example.com
+
+# SOCKS5 with auth
+export ALL_PROXY="socks5://user:pass@proxy.example.com:1080"
+agent-browser open https://example.com
+```
+
+## Proxy Bypass
+
+Skip proxy for specific domains using `--proxy-bypass` or `NO_PROXY`:
+
+```bash
+# Via CLI flag
+agent-browser --proxy "http://proxy.example.com:8080" --proxy-bypass "localhost,*.internal.com" open https://example.com
+
+# Via environment variable
+export NO_PROXY="localhost,127.0.0.1,.internal.company.com"
+agent-browser open https://internal.company.com  # Direct connection
+agent-browser open https://external.com          # Via proxy
+```
+
+## Common Use Cases
+
+### Geo-Location Testing
+
+```bash
+#!/bin/bash
+# Test site from different regions using geo-located proxies
+
+PROXIES=(
+    "http://us-proxy.example.com:8080"
+    "http://eu-proxy.example.com:8080"
+    "http://asia-proxy.example.com:8080"
+)
+
+for proxy in "${PROXIES[@]}"; do
+    export HTTP_PROXY="$proxy"
+    export HTTPS_PROXY="$proxy"
+
+    region=$(echo "$proxy" | grep -oP '^\w+-\w+')
+    echo "Testing from: $region"
+
+    agent-browser --session "$region" open https://example.com
+    agent-browser --session "$region" screenshot "./screenshots/$region.png"
+    agent-browser --session "$region" close
+done
+```
+
+### Rotating Proxies for Scraping
+
+```bash
+#!/bin/bash
+# Rotate through proxy list to avoid rate limiting
+
+PROXY_LIST=(
+    "http://proxy1.example.com:8080"
+    "http://proxy2.example.com:8080"
+    "http://proxy3.example.com:8080"
+)
+
+URLS=(
+    "https://site.com/page1"
+    "https://site.com/page2"
+    "https://site.com/page3"
+)
+
+for i in "${!URLS[@]}"; do
+    proxy_index=$((i % ${#PROXY_LIST[@]}))
+    export HTTP_PROXY="${PROXY_LIST[$proxy_index]}"
+    export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}"
+
+    agent-browser open "${URLS[$i]}"
+    agent-browser get text body > "output-$i.txt"
+    agent-browser close
+
+    sleep 1  # Polite delay
+done
+```
+
+### Corporate Network Access
+
+```bash
+#!/bin/bash
+# Access internal sites via corporate proxy
+
+export HTTP_PROXY="http://corpproxy.company.com:8080"
+export HTTPS_PROXY="http://corpproxy.company.com:8080"
+export NO_PROXY="localhost,127.0.0.1,.company.com"
+
+# External sites go through proxy
+agent-browser open https://external-vendor.com
+
+# Internal sites bypass proxy
+agent-browser open https://intranet.company.com
+```
+
+## Verifying Proxy Connection
+
+```bash
+# Check your apparent IP
+agent-browser open https://httpbin.org/ip
+agent-browser get text body
+# Should show proxy's IP, not your real IP
+```
+
+## Troubleshooting
+
+### Proxy Connection Failed
+
+```bash
+# Test proxy connectivity first
+curl -x http://proxy.example.com:8080 https://httpbin.org/ip
+
+# Check if proxy requires auth
+export HTTP_PROXY="http://user:pass@proxy.example.com:8080"
+```
+
+### SSL/TLS Errors Through Proxy
+
+Some proxies perform SSL inspection. If you encounter certificate errors:
+
+```bash
+# For testing only - not recommended for production
+agent-browser open https://example.com --ignore-https-errors
+```
+
+### Slow Performance
+
+```bash
+# Use proxy only when necessary
+export NO_PROXY="*.cdn.com,*.static.com"  # Direct CDN access
+```
+
+## Best Practices
+
+1. **Use environment variables** - Don't hardcode proxy credentials
+2. **Set NO_PROXY appropriately** - Avoid routing local traffic through proxy
+3. **Test proxy before automation** - Verify connectivity with simple requests
+4. **Handle proxy failures gracefully** - Implement retry logic for unstable proxies
+5. **Rotate proxies for large scraping jobs** - Distribute load and avoid bans
diff --git a/.agents/skills/agent-browser/references/session-management.md b/.agents/skills/agent-browser/references/session-management.md
new file mode 100644
index 0000000..bb5312d
--- /dev/null
+++ b/.agents/skills/agent-browser/references/session-management.md
@@ -0,0 +1,193 @@
+# Session Management
+
+Multiple isolated browser sessions with state persistence and concurrent browsing.
+
+**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Named Sessions](#named-sessions)
+- [Session Isolation Properties](#session-isolation-properties)
+- [Session State Persistence](#session-state-persistence)
+- [Common Patterns](#common-patterns)
+- [Default Session](#default-session)
+- [Session Cleanup](#session-cleanup)
+- [Best Practices](#best-practices)
+
+## Named Sessions
+
+Use `--session` flag to isolate browser contexts:
+
+```bash
+# Session 1: Authentication flow
+agent-browser --session auth open https://app.example.com/login
+
+# Session 2: Public browsing (separate cookies, storage)
+agent-browser --session public open https://example.com
+
+# Commands are isolated by session
+agent-browser --session auth fill @e1 "user@example.com"
+agent-browser --session public get text body
+```
+
+## Session Isolation Properties
+
+Each session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Browsing history
+- Open tabs
+
+## Session State Persistence
+
+### Save Session State
+
+```bash
+# Save cookies, storage, and auth state
+agent-browser state save /path/to/auth-state.json
+```
+
+### Load Session State
+
+```bash
+# Restore saved state
+agent-browser state load /path/to/auth-state.json
+
+# Continue with authenticated session
+agent-browser open https://app.example.com/dashboard
+```
+
+### State File Contents
+
+```json
+{
+  "cookies": [...],
+  "localStorage": {...},
+  "sessionStorage": {...},
+  "origins": [...]
+}
+```
+
+## Common Patterns
+
+### Authenticated Session Reuse
+
+```bash
+#!/bin/bash
+# Save login state once, reuse many times
+
+STATE_FILE="/tmp/auth-state.json"
+
+# Check if we have saved state
+if [[ -f "$STATE_FILE" ]]; then
+    agent-browser state load "$STATE_FILE"
+    agent-browser open https://app.example.com/dashboard
+else
+    # Perform login
+    agent-browser open https://app.example.com/login
+    agent-browser snapshot -i
+    agent-browser fill @e1 "$USERNAME"
+    agent-browser fill @e2 "$PASSWORD"
+    agent-browser click @e3
+    agent-browser wait --load networkidle
+
+    # Save for future use
+    agent-browser state save "$STATE_FILE"
+fi
+```
+
+### Concurrent Scraping
+
+```bash
+#!/bin/bash
+# Scrape multiple sites concurrently
+
+# Start all sessions
+agent-browser --session site1 open https://site1.com &
+agent-browser --session site2 open https://site2.com &
+agent-browser --session site3 open https://site3.com &
+wait
+
+# Extract from each
+agent-browser --session site1 get text body > site1.txt
+agent-browser --session site2 get text body > site2.txt
+agent-browser --session site3 get text body > site3.txt
+
+# Cleanup
+agent-browser --session site1 close
+agent-browser --session site2 close
+agent-browser --session site3 close
+```
+
+### A/B Testing Sessions
+
+```bash
+# Test different user experiences
+agent-browser --session variant-a open "https://app.com?variant=a"
+agent-browser --session variant-b open "https://app.com?variant=b"
+
+# Compare
+agent-browser --session variant-a screenshot /tmp/variant-a.png
+agent-browser --session variant-b screenshot /tmp/variant-b.png
+```
+
+## Default Session
+
+When `--session` is omitted, commands use the default session:
+
+```bash
+# These use the same default session
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser close  # Closes default session
+```
+
+## Session Cleanup
+
+```bash
+# Close specific session
+agent-browser --session auth close
+
+# List active sessions
+agent-browser session list
+```
+
+## Best Practices
+
+### 1. Name Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+agent-browser --session github-auth open https://github.com
+agent-browser --session docs-scrape open https://docs.example.com
+
+# AVOID: Generic names
+agent-browser --session s1 open https://github.com
+```
+
+### 2. Always Clean Up
+
+```bash
+# Close sessions when done
+agent-browser --session auth close
+agent-browser --session scrape close
+```
+
+### 3. Handle State Files Securely
+
+```bash
+# Don't commit state files (contain auth tokens!)
+echo "*.auth-state.json" >> .gitignore
+
+# Delete after use
+rm /tmp/auth-state.json
+```
+
+### 4. Timeout Long Sessions
+
+```bash
+# Set timeout for automated scripts
+timeout 60 agent-browser --session long-task get text body
+```
diff --git a/.agents/skills/agent-browser/references/snapshot-refs.md b/.agents/skills/agent-browser/references/snapshot-refs.md
new file mode 100644
index 0000000..3cc0fea
--- /dev/null
+++ b/.agents/skills/agent-browser/references/snapshot-refs.md
@@ -0,0 +1,219 @@
+# Snapshot and Refs
+
+Compact element references that reduce context usage dramatically for AI agents.
+
+**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [How Refs Work](#how-refs-work)
+- [Snapshot Command](#the-snapshot-command)
+- [Using Refs](#using-refs)
+- [Ref Lifecycle](#ref-lifecycle)
+- [Best Practices](#best-practices)
+- [Ref Notation Details](#ref-notation-details)
+- [Troubleshooting](#troubleshooting)
+
+## How Refs Work
+
+Traditional approach:
+```
+Full DOM/HTML → AI parses → CSS selector → Action (~3000-5000 tokens)
+```
+
+agent-browser approach:
+```
+Compact snapshot → @refs assigned → Direct interaction (~200-400 tokens)
+```
+
+## The Snapshot Command
+
+```bash
+# Basic snapshot (shows page structure)
+agent-browser snapshot
+
+# Interactive snapshot (-i flag) - RECOMMENDED
+agent-browser snapshot -i
+```
+
+### Snapshot Output Format
+
+```
+Page: Example Site - Home
+URL: https://example.com
+
+@e1 [header]
+  @e2 [nav]
+    @e3 [a] "Home"
+    @e4 [a] "Products"
+    @e5 [a] "About"
+  @e6 [button] "Sign In"
+
+@e7 [main]
+  @e8 [h1] "Welcome"
+  @e9 [form]
+    @e10 [input type="email"] placeholder="Email"
+    @e11 [input type="password"] placeholder="Password"
+    @e12 [button type="submit"] "Log In"
+
+@e13 [footer]
+  @e14 [a] "Privacy Policy"
+```
+
+## Using Refs
+
+Once you have refs, interact directly:
+
+```bash
+# Click the "Sign In" button
+agent-browser click @e6
+
+# Fill email input
+agent-browser fill @e10 "user@example.com"
+
+# Fill password
+agent-browser fill @e11 "password123"
+
+# Submit the form
+agent-browser click @e12
+```
+
+## Ref Lifecycle
+
+**IMPORTANT**: Refs are invalidated when the page changes!
+
+```bash
+# Get initial snapshot
+agent-browser snapshot -i
+# @e1 [button] "Next"
+
+# Click triggers page change
+agent-browser click @e1
+
+# MUST re-snapshot to get new refs!
+agent-browser snapshot -i
+# @e1 [h1] "Page 2"  ← Different element now!
+```
+
+## Best Practices
+
+### 1. Always Snapshot Before Interacting
+
+```bash
+# CORRECT
+agent-browser open https://example.com
+agent-browser snapshot -i          # Get refs first
+agent-browser click @e1            # Use ref
+
+# WRONG
+agent-browser open https://example.com
+agent-browser click @e1            # Ref doesn't exist yet!
+```
+
+### 2. Re-Snapshot After Navigation
+
+```bash
+agent-browser click @e5            # Navigates to new page
+agent-browser snapshot -i          # Get new refs
+agent-browser click @e1            # Use new refs
+```
+
+### 3. Re-Snapshot After Dynamic Changes
+
+```bash
+agent-browser click @e1            # Opens dropdown
+agent-browser snapshot -i          # See dropdown items
+agent-browser click @e7            # Select item
+```
+
+### 4. Snapshot Specific Regions
+
+For complex pages, snapshot specific areas:
+
+```bash
+# Snapshot just the form
+agent-browser snapshot @e9
+```
+
+## Ref Notation Details
+
+```
+@e1 [tag type="value"] "text content" placeholder="hint"
+│    │   │             │               │
+│    │   │             │               └─ Additional attributes
+│    │   │             └─ Visible text
+│    │   └─ Key attributes shown
+│    └─ HTML tag name
+└─ Unique ref ID
+```
+
+### Common Patterns
+
+```
+@e1 [button] "Submit"                    # Button with text
+@e2 [input type="email"]                 # Email input
+@e3 [input type="password"]              # Password input
+@e4 [a href="/page"] "Link Text"         # Anchor link
+@e5 [select]                             # Dropdown
+@e6 [textarea] placeholder="Message"     # Text area
+@e7 [div class="modal"]                  # Container (when relevant)
+@e8 [img alt="Logo"]                     # Image
+@e9 [checkbox] checked                   # Checked checkbox
+@e10 [radio] selected                    # Selected radio
+```
+
+## Iframes
+
+Snapshots automatically detect and inline iframe content. When the main-frame snapshot runs, each `Iframe` node is resolved and its child accessibility tree is included directly beneath it in the output. Refs assigned to elements inside iframes carry frame context, so interactions like `click`, `fill`, and `type` work without manually switching frames.
+
+```bash
+agent-browser snapshot -i
+# @e1 [heading] "Checkout"
+# @e2 [Iframe] "payment-frame"
+#   @e3 [input] "Card number"
+#   @e4 [input] "Expiry"
+#   @e5 [button] "Pay"
+# @e6 [button] "Cancel"
+
+# Interact with iframe elements directly using their refs
+agent-browser fill @e3 "4111111111111111"
+agent-browser fill @e4 "12/28"
+agent-browser click @e5
+```
+
+**Key details:**
+- Only one level of iframe nesting is expanded (iframes within iframes are not recursed)
+- Cross-origin iframes that block accessibility tree access are silently skipped
+- Empty iframes or iframes with no interactive content are omitted from the output
+- To scope a snapshot to a single iframe, use `frame @ref` then `snapshot -i`
+
+## Troubleshooting
+
+### "Ref not found" Error
+
+```bash
+# Ref may have changed - re-snapshot
+agent-browser snapshot -i
+```
+
+### Element Not Visible in Snapshot
+
+```bash
+# Scroll down to reveal element
+agent-browser scroll down 1000
+agent-browser snapshot -i
+
+# Or wait for dynamic content
+agent-browser wait 1000
+agent-browser snapshot -i
+```
+
+### Too Many Elements
+
+```bash
+# Snapshot specific container
+agent-browser snapshot @e5
+
+# Or use get text for content-only extraction
+agent-browser get text @e5
+```
diff --git a/.agents/skills/agent-browser/references/video-recording.md b/.agents/skills/agent-browser/references/video-recording.md
new file mode 100644
index 0000000..e6a9fb4
--- /dev/null
+++ b/.agents/skills/agent-browser/references/video-recording.md
@@ -0,0 +1,173 @@
+# Video Recording
+
+Capture browser automation as video for debugging, documentation, or verification.
+
+**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Basic Recording](#basic-recording)
+- [Recording Commands](#recording-commands)
+- [Use Cases](#use-cases)
+- [Best Practices](#best-practices)
+- [Output Format](#output-format)
+- [Limitations](#limitations)
+
+## Basic Recording
+
+```bash
+# Start recording
+agent-browser record start ./demo.webm
+
+# Perform actions
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser fill @e2 "test input"
+
+# Stop and save
+agent-browser record stop
+```
+
+## Recording Commands
+
+```bash
+# Start recording to file
+agent-browser record start ./output.webm
+
+# Stop current recording
+agent-browser record stop
+
+# Restart with new file (stops current + starts new)
+agent-browser record restart ./take2.webm
+```
+
+## Use Cases
+
+### Debugging Failed Automation
+
+```bash
+#!/bin/bash
+# Record automation for debugging
+
+agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm
+
+# Run your automation
+agent-browser open https://app.example.com
+agent-browser snapshot -i
+agent-browser click @e1 || {
+    echo "Click failed - check recording"
+    agent-browser record stop
+    exit 1
+}
+
+agent-browser record stop
+```
+
+### Documentation Generation
+
+```bash
+#!/bin/bash
+# Record workflow for documentation
+
+agent-browser record start ./docs/how-to-login.webm
+
+agent-browser open https://app.example.com/login
+agent-browser wait 1000  # Pause for visibility
+
+agent-browser snapshot -i
+agent-browser fill @e1 "demo@example.com"
+agent-browser wait 500
+
+agent-browser fill @e2 "password"
+agent-browser wait 500
+
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser wait 1000  # Show result
+
+agent-browser record stop
+```
+
+### CI/CD Test Evidence
+
+```bash
+#!/bin/bash
+# Record E2E test runs for CI artifacts
+
+TEST_NAME="${1:-e2e-test}"
+RECORDING_DIR="./test-recordings"
+mkdir -p "$RECORDING_DIR"
+
+agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm"
+
+# Run test
+if run_e2e_test; then
+    echo "Test passed"
+else
+    echo "Test failed - recording saved"
+fi
+
+agent-browser record stop
+```
+
+## Best Practices
+
+### 1. Add Pauses for Clarity
+
+```bash
+# Slow down for human viewing
+agent-browser click @e1
+agent-browser wait 500  # Let viewer see result
+```
+
+### 2. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+agent-browser record start ./recordings/login-flow-2024-01-15.webm
+agent-browser record start ./recordings/checkout-test-run-42.webm
+```
+
+### 3. Handle Recording in Error Cases
+
+```bash
+#!/bin/bash
+set -e
+
+cleanup() {
+    agent-browser record stop 2>/dev/null || true
+    agent-browser close 2>/dev/null || true
+}
+trap cleanup EXIT
+
+agent-browser record start ./automation.webm
+# ... automation steps ...
+```
+
+### 4. Combine with Screenshots
+
+```bash
+# Record video AND capture key frames
+agent-browser record start ./flow.webm
+
+agent-browser open https://example.com
+agent-browser screenshot ./screenshots/step1-homepage.png
+
+agent-browser click @e1
+agent-browser screenshot ./screenshots/step2-after-click.png
+
+agent-browser record stop
+```
+
+## Output Format
+
+- Default format: WebM (VP8/VP9 codec)
+- Compatible with all modern browsers and video players
+- Compressed but high quality
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space
+- Some headless environments may have codec limitations
diff --git a/.agents/skills/agent-browser/templates/authenticated-session.sh b/.agents/skills/agent-browser/templates/authenticated-session.sh
new file mode 100755
index 0000000..b66c928
--- /dev/null
+++ b/.agents/skills/agent-browser/templates/authenticated-session.sh
@@ -0,0 +1,105 @@
+#!/bin/bash
+# Template: Authenticated Session Workflow
+# Purpose: Login once, save state, reuse for subsequent runs
+# Usage: ./authenticated-session.sh <login-url> [state-file]
+#
+# RECOMMENDED: Use the auth vault instead of this template:
+#   echo "<pass>" | agent-browser auth save myapp --url <login-url> --username <user> --password-stdin
+#   agent-browser auth login myapp
+# The auth vault stores credentials securely and the LLM never sees passwords.
+#
+# Environment variables:
+#   APP_USERNAME - Login username/email
+#   APP_PASSWORD - Login password
+#
+# Two modes:
+#   1. Discovery mode (default): Shows form structure so you can identify refs
+#   2. Login mode: Performs actual login after you update the refs
+#
+# Setup steps:
+#   1. Run once to see form structure (discovery mode)
+#   2. Update refs in LOGIN FLOW section below
+#   3. Set APP_USERNAME and APP_PASSWORD
+#   4. Delete the DISCOVERY section
+
+set -euo pipefail
+
+LOGIN_URL="${1:?Usage: $0 <login-url> [state-file]}"
+STATE_FILE="${2:-./auth-state.json}"
+
+echo "Authentication workflow: $LOGIN_URL"
+
+# ================================================================
+# SAVED STATE: Skip login if valid saved state exists
+# ================================================================
+if [[ -f "$STATE_FILE" ]]; then
+    echo "Loading saved state from $STATE_FILE..."
+    if agent-browser --state "$STATE_FILE" open "$LOGIN_URL" 2>/dev/null; then
+        agent-browser wait --load networkidle
+
+        CURRENT_URL=$(agent-browser get url)
+        if [[ "$CURRENT_URL" != *"login"* ]] && [[ "$CURRENT_URL" != *"signin"* ]]; then
+            echo "Session restored successfully"
+            agent-browser snapshot -i
+            exit 0
+        fi
+        echo "Session expired, performing fresh login..."
+        agent-browser close 2>/dev/null || true
+    else
+        echo "Failed to load state, re-authenticating..."
+    fi
+    rm -f "$STATE_FILE"
+fi
+
+# ================================================================
+# DISCOVERY MODE: Shows form structure (delete after setup)
+# ================================================================
+echo "Opening login page..."
+agent-browser open "$LOGIN_URL"
+agent-browser wait --load networkidle
+
+echo ""
+echo "Login form structure:"
+echo "---"
+agent-browser snapshot -i
+echo "---"
+echo ""
+echo "Next steps:"
+echo "  1. Note the refs: username=@e?, password=@e?, submit=@e?"
+echo "  2. Update the LOGIN FLOW section below with your refs"
+echo "  3. Set: export APP_USERNAME='...' APP_PASSWORD='...'"
+echo "  4. Delete this DISCOVERY MODE section"
+echo ""
+agent-browser close
+exit 0
+
+# ================================================================
+# LOGIN FLOW: Uncomment and customize after discovery
+# ================================================================
+# : "${APP_USERNAME:?Set APP_USERNAME environment variable}"
+# : "${APP_PASSWORD:?Set APP_PASSWORD environment variable}"
+#
+# agent-browser open "$LOGIN_URL"
+# agent-browser wait --load networkidle
+# agent-browser snapshot -i
+#
+# # Fill credentials (update refs to match your form)
+# agent-browser fill @e1 "$APP_USERNAME"
+# agent-browser fill @e2 "$APP_PASSWORD"
+# agent-browser click @e3
+# agent-browser wait --load networkidle
+#
+# # Verify login succeeded
+# FINAL_URL=$(agent-browser get url)
+# if [[ "$FINAL_URL" == *"login"* ]] || [[ "$FINAL_URL" == *"signin"* ]]; then
+#     echo "Login failed - still on login page"
+#     agent-browser screenshot /tmp/login-failed.png
+#     agent-browser close
+#     exit 1
+# fi
+#
+# # Save state for future runs
+# echo "Saving state to $STATE_FILE"
+# agent-browser state save "$STATE_FILE"
+# echo "Login successful"
+# agent-browser snapshot -i
diff --git a/.agents/skills/agent-browser/templates/capture-workflow.sh b/.agents/skills/agent-browser/templates/capture-workflow.sh
new file mode 100755
index 0000000..3bc93ad
--- /dev/null
+++ b/.agents/skills/agent-browser/templates/capture-workflow.sh
@@ -0,0 +1,69 @@
+#!/bin/bash
+# Template: Content Capture Workflow
+# Purpose: Extract content from web pages (text, screenshots, PDF)
+# Usage: ./capture-workflow.sh <url> [output-dir]
+#
+# Outputs:
+#   - page-full.png: Full page screenshot
+#   - page-structure.txt: Page element structure with refs
+#   - page-text.txt: All text content
+#   - page.pdf: PDF version
+#
+# Optional: Load auth state for protected pages
+
+set -euo pipefail
+
+TARGET_URL="${1:?Usage: $0 <url> [output-dir]}"
+OUTPUT_DIR="${2:-.}"
+
+echo "Capturing: $TARGET_URL"
+mkdir -p "$OUTPUT_DIR"
+
+# Optional: Load authentication state
+# if [[ -f "./auth-state.json" ]]; then
+#     echo "Loading authentication state..."
+#     agent-browser state load "./auth-state.json"
+# fi
+
+# Navigate to target
+agent-browser open "$TARGET_URL"
+agent-browser wait --load networkidle
+
+# Get metadata
+TITLE=$(agent-browser get title)
+URL=$(agent-browser get url)
+echo "Title: $TITLE"
+echo "URL: $URL"
+
+# Capture full page screenshot
+agent-browser screenshot --full "$OUTPUT_DIR/page-full.png"
+echo "Saved: $OUTPUT_DIR/page-full.png"
+
+# Get page structure with refs
+agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt"
+echo "Saved: $OUTPUT_DIR/page-structure.txt"
+
+# Extract all text content
+agent-browser get text body > "$OUTPUT_DIR/page-text.txt"
+echo "Saved: $OUTPUT_DIR/page-text.txt"
+
+# Save as PDF
+agent-browser pdf "$OUTPUT_DIR/page.pdf"
+echo "Saved: $OUTPUT_DIR/page.pdf"
+
+# Optional: Extract specific elements using refs from structure
+# agent-browser get text @e5 > "$OUTPUT_DIR/main-content.txt"
+
+# Optional: Handle infinite scroll pages
+# for i in {1..5}; do
+#     agent-browser scroll down 1000
+#     agent-browser wait 1000
+# done
+# agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png"
+
+# Cleanup
+agent-browser close
+
+echo ""
+echo "Capture complete:"
+ls -la "$OUTPUT_DIR"
diff --git a/.agents/skills/agent-browser/templates/form-automation.sh b/.agents/skills/agent-browser/templates/form-automation.sh
new file mode 100755
index 0000000..6784fcd
--- /dev/null
+++ b/.agents/skills/agent-browser/templates/form-automation.sh
@@ -0,0 +1,62 @@
+#!/bin/bash
+# Template: Form Automation Workflow
+# Purpose: Fill and submit web forms with validation
+# Usage: ./form-automation.sh <form-url>
+#
+# This template demonstrates the snapshot-interact-verify pattern:
+# 1. Navigate to form
+# 2. Snapshot to get element refs
+# 3. Fill fields using refs
+# 4. Submit and verify result
+#
+# Customize: Update the refs (@e1, @e2, etc.) based on your form's snapshot output
+
+set -euo pipefail
+
+FORM_URL="${1:?Usage: $0 <form-url>}"
+
+echo "Form automation: $FORM_URL"
+
+# Step 1: Navigate to form
+agent-browser open "$FORM_URL"
+agent-browser wait --load networkidle
+
+# Step 2: Snapshot to discover form elements
+echo ""
+echo "Form structure:"
+agent-browser snapshot -i
+
+# Step 3: Fill form fields (customize these refs based on snapshot output)
+#
+# Common field types:
+#   agent-browser fill @e1 "John Doe"           # Text input
+#   agent-browser fill @e2 "user@example.com"   # Email input
+#   agent-browser fill @e3 "SecureP@ss123"      # Password input
+#   agent-browser select @e4 "Option Value"     # Dropdown
+#   agent-browser check @e5                     # Checkbox
+#   agent-browser click @e6                     # Radio button
+#   agent-browser fill @e7 "Multi-line text"   # Textarea
+#   agent-browser upload @e8 /path/to/file.pdf # File upload
+#
+# Uncomment and modify:
+# agent-browser fill @e1 "Test User"
+# agent-browser fill @e2 "test@example.com"
+# agent-browser click @e3  # Submit button
+
+# Step 4: Wait for submission
+# agent-browser wait --load networkidle
+# agent-browser wait --url "**/success"  # Or wait for redirect
+
+# Step 5: Verify result
+echo ""
+echo "Result:"
+agent-browser get url
+agent-browser snapshot -i
+
+# Optional: Capture evidence
+agent-browser screenshot /tmp/form-result.png
+echo "Screenshot saved: /tmp/form-result.png"
+
+# Cleanup
+agent-browser close
+echo "Done"
diff --git a/AGENTS.md b/AGENTS.md
index bf00a62..5eaf868 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,12 @@ bun run test
 - Only run these commands after you edit files in this session.
 - If you are only analyzing an existing branch, reviewing changes, or creating a PR without editing files, do not run them automatically.
 - Do not regenerate `packages/opencode/.opencode/` unless you changed the source that produces it or the user explicitly asked.
+- When you add, remove, or rename commands, agents, components, tools, adapter settings, or bundled config fields, keep every source of truth in sync in the same change:
+  - runtime definitions in `packages/core`
+  - bundled config in `kompass.jsonc`, `packages/core/kompass.jsonc`, and `packages/opencode/kompass.jsonc`
+  - schema in `kompass.schema.json`
+  - user-facing docs in `README.md` and adapter/package docs that describe the changed surface
+  - generated OpenCode output under `packages/opencode/.opencode/` when the source change affects compiled artifacts
 - If no validation was run in the current session, say that clearly instead of implying the branch was tested.
 
 Never edit `packages/opencode/.opencode/` directly.
@@ -45,6 +51,7 @@ packages/opencode/.opencode/ # Generated OpenCode output for review
 ## Command Authoring
 
 - Author command definitions in `packages/core/commands/`; treat `packages/opencode/.opencode/commands/` as generated output only
+- Treat `packages/core/commands/index.ts`, `packages/core/lib/config.ts`, `kompass.schema.json`, the bundled `kompass.jsonc` files, and the relevant docs as a linked surface area; if one changes, verify the others still describe the same command set and config shape
 - Use `packages/core/commands/pr/create.md` as the canonical example for command structure and tone
 - Keep this section order in command docs unless a command has a strong reason not to: `## Goal`, `## Workflow`, `## Additional Context`, `## Output`
 - Start `## Workflow` with a dedicated `### Arguments` subsection that stores the raw `$ARGUMENTS` value inside literal `<arguments>` tags before any normalization
diff --git a/README.md b/README.md
index 899ee4a..3092e59 100644
--- a/README.md
+++ b/README.md
@@ -6,26 +6,15 @@
   <em>Navigate your way - manual steering, steered autonomy, or autonomously.</em>
 </p>
 
-Kompass keeps AI coding agents on course with token-efficient, composable workflows. **Finally, your agent stops wandering.**
+Kompass keeps AI coding agents on course with token-efficient, composable workflows.
 
-Whether you prefer full control, guided collaboration, or hands-off autonomy, Kompass adapts to how you work.
+## Docs
 
-## Choose Your Mode
-
-<p>**🧭 Manual Steering** — You chart the course, the agent follows your lead</p>
-<p>**⚓ Collaborative** — Plan together, develop together, review together</p>
-<p>**🚢 Autonomous** — Let your agent navigate independently, review at checkpoints</p>
-
-## Why Kompass?
-
-| Challenge | How Kompass Helps |
-|-----------|-------------------|
-| Agents wander without direction | 🧭 **Navigation** — structured workflows keep agents on course |
-| Rebuilding prompts for every agent | 🔌 **Plug & Play** — same workflows across OpenCode, Claude Code, and more |
-| Token bloat in long sessions | 🎯 **Token Efficient** — minimal, focused prompts that get to the point |
-| Ad-hoc planning and review | ⚓ **Workflows** — purpose-built flows for plan, dev, and review |
-| Generic tools miss context | 🛠️ **Tailored Tools** — purpose-built for repository work |
-| Complex setup overhead | ⚡ **Easy to Use** — install the plugin, start navigating |
+- Main docs: `https://kompassdev.ai/docs/`
+- Getting started: `https://kompassdev.ai/docs/getting-started/`
+- OpenCode adapter: `https://kompassdev.ai/docs/adapters/opencode/`
+- Config reference: `https://kompassdev.ai/docs/config/overview/`
+- Command, agent, and tool reference: `https://kompassdev.ai/docs/reference/commands/`, `https://kompassdev.ai/docs/reference/agents/`, `https://kompassdev.ai/docs/reference/tools/`
 
 ## Installation
 
@@ -37,430 +26,28 @@ For OpenCode, add the adapter package to your config:
 }
 ```
 
-Config is optional. To publish a project override:
+Project config is optional. To start from the published base config:
 
 ```bash
-# Inside .opencode folder
 curl -fsSL https://raw.githubusercontent.com/kompassdev/kompass/main/kompass.jsonc -o .opencode/kompass.jsonc
-
 ```
 
-Kompass ships a bundled base config, then applies the first matching consumer-project override in this order: `.opencode/kompass.jsonc`, `.opencode/kompass.json`, `kompass.jsonc`, `kompass.json`.
-
-## How To Use
-
-### OpenCode
-
-Use `@kompassdev/opencode` when you want Kompass workflows inside OpenCode.
-
-- install the plugin in your OpenCode config
-- optionally add one project override file to customize commands, agents, tools, skills, and defaults; `.opencode/kompass.jsonc` is preferred
-- bundled Kompass skills are registered automatically when the plugin loads, so users do not need to copy skill files manually
-- use commands like `/ask`, `/review`, `/pr/create`, or `/ticket/plan` inside OpenCode
-- for CLI session debugging, use `opencode session list` to find a session id and `opencode export <sessionID>` to dump the raw session JSON
-
-### Claude Code
-
-Claude Code adapter support is coming soon.
-
-Kompass is being structured as a shared core toolkit with adapter-specific packages, so the same workflows can be reused across agents instead of rebuilt from scratch.
-
-## Agents
-
-### `worker`
-
-Handles generic implementation work and can ask targeted follow-up questions when execution is blocked.
-
-### `navigator`
-
-Coordinates structured multi-step workflows by keeping orchestration local and delegating only focused leaf work to subagents.
-
-### `planner`
-
-Turns a request or ticket into a scoped implementation plan.
-
-### `reviewer`
-
-Reviews branch or PR changes without editing files.
-
-## Commands
-
-### `/ask`
-
-Answers questions about the current project or codebase.
-
-<details>
-
-**Usage:** `/ask <question>`
-
-Loads only the relevant repository context needed to answer a project or code question directly.
-
-</details>
-
-### `/commit`
-
-Stages and commits changes with a generated message.
-
-<details>
-
-**Usage:** `/commit [message]`
-
-If a message is provided, commits with that message. Otherwise, generates an appropriate commit message based on the staged changes.
-
-</details>
-
-### `/commit-and-push`
-
-Stages, commits, and pushes changes in one workflow.
-
-<details>
-
-**Usage:** `/commit-and-push [message]`
-
-Commits changes (generating a message if not provided) and pushes to the remote repository.
-
-</details>
-
-### `/dev`
-
-Implementation mode for focused development work.
-
-<details>
-
-**Usage:** `/dev <description>`
-
-Use for active development tasks. The agent implements the described changes while staying focused on the task.
-
-</details>
-
-### `/learn`
-
-Learns patterns and conventions from existing code.
-
-<details>
-
-**Usage:** `/learn <what-to-learn>`
-
-Analyzes the codebase to understand patterns, conventions, or specific implementations. Useful for understanding how things work before making changes.
-
-</details>
-
-### `/pr/create`
-
-Creates a pull request with structured checklists.
-
-<details>
-
-**Usage:** `/pr/create [title]`
-
-Creates a PR from the current branch. Generates a title if not provided. Includes checklist sections for consistent PR structure.
-
-</details>
-
-### `/pr/fix`
-
-Fixes issues found during PR review.
-
-<details>
-
-**Usage:** `/pr/fix [context]`
-
-Addresses review comments and feedback on an open PR. Loads the PR context and works through requested changes.
-
-</details>
-
-### `/pr/review`
-
-Reviews a pull request and adds structured feedback.
-
-<details>
-
-**Usage:** `/pr/review [pr]`
-
-Reviews the specified PR (or current PR if not specified) and provides feedback using inline comments and review threads.
-
-</details>
-
-### `/reload`
-
-Reloads the OpenCode project cache.
-
-<details>
-
-**Usage:** `/reload`
-
-Refreshes config, commands, agents, and tools without restarting OpenCode. Useful after making changes to `kompass.jsonc`.
-
-</details>
-
-### `/review`
-
-Reviews branch changes for issues and improvements.
-
-<details>
-
-**Usage:** `/review [base]`
-
-Reviews uncommitted changes or changes against a base branch (default: main). Provides feedback on code quality, patterns, and potential issues.
-
-</details>
-
-### `/ship`
-
-Ships the fast path from change summary to commit and PR creation.
-
-<details>
-
-**Usage:** `/ship [base-or-context]`
-
-Summarizes current changes, creates a feature branch when you are still on the base branch, then delegates the commit and PR steps to `/commit` and `/pr/create`.
-
-</details>
-
-### `/todo`
-
-Works through a todo file task by task.
-
-<details>
-
-**Usage:** `/todo [todo-file]`
-
-Loads a todo list, delegates one item at a time, and keeps orchestration local so work can pause and resume cleanly.
-
-</details>
-
-### `/rmslop`
-
-Removes unnecessary code and simplifies.
-
-<details>
-
-**Usage:** `/rmslop`
-
-Analyzes the codebase for unnecessary complexity, unused code, and opportunities for simplification.
-
-</details>
-
-### `/ticket/create`
-
-Creates a GitHub issue from a description.
-
-<details>
-
-**Usage:** `/ticket/create <description>`
-
-Creates a new GitHub issue with the provided description, generating a title and structured body with checklists.
-
-</details>
-
-### `/ticket/ask`
-
-Answers a question on a ticket and posts the response.
-
-<details>
-
-**Usage:** `/ticket/ask <ticket-reference> <question>`
-
-Loads the ticket plus all comments, answers the question using ticket and repository context, and posts the response back to the same ticket.
-
-</details>
-
-### `/ticket/dev`
-
-Implements a ticket with planning and execution.
-
-<details>
-
-**Usage:** `/ticket/dev <ticket-reference>`
-
-Loads the specified ticket (URL, #id, or file path), creates an implementation plan, and executes the work.
-
-</details>
-
-### `/ticket/plan`
-
-Creates an implementation plan for a ticket.
-
-<details>
-
-**Usage:** `/ticket/plan <ticket-reference>`
-
-Loads the specified ticket and creates a detailed implementation plan without executing changes.
-
-</details>
-
-## Tools
-
-### `changes_load`
-
-Load branch changes against a base branch.
-
-<details>
-
-**Parameters:**
-
-- `base` (optional): base branch or ref
-- `head` (optional): head branch, commit, or ref override
-- `depthHint` (optional): shallow-fetch hint such as PR commit count
-- `uncommitted` (optional): only load uncommitted changes (staged and unstaged), never fall back to branch comparison
-
-**Why it helps:**
-
-- keeps branch diff loading focused
-- works well for review and PR workflows
-- handles workspace changes separately from committed branch diffs
-
-</details>
-
-### `pr_load`
-
-Load PR metadata and review history.
-
-<details>
-
-**Parameters:**
-
-- `pr` (optional): PR number or URL
-
-**Why it helps:**
-
-- gives agents normalized PR context before they start reviewing or summarizing
-- keeps review workflows grounded in actual PR state instead of inferred context
-
-</details>
-
-### `pr_sync`
-
-Create, update, or review a GitHub pull request with structured checklists.
-
-<details>
-
-**Parameters:**
-
-- `title` (optional): PR title; required when creating a PR or renaming one
-- `body` (optional): raw PR body override
-- `description` (optional): short PR description rendered above checklist sections
-- `base` (optional): base branch to merge into
-- `head` (optional): head branch to use when creating a PR
-- `checklists` (optional): structured checklist sections (e.g., Testing, Summary)
-- `draft` (optional): create as draft PR
-- `refUrl` (optional): PR URL to update instead of creating new
-- `commitId` (optional): commit SHA to anchor review comments to
-- `review` (optional): structured review submission with optional `body`, inline `comments`, and `approve` flag
-- `replies` (optional): replies to existing review comments
-- `commentBody` (optional): general PR comment body
-
-**Why it helps:**
-
-- consistent PR creation with checklist support
-- create, update, review, approve, and reply with one tool
-- no shell escaping issues
-
-</details>
-
-### `ticket_load`
-
-Load a ticket from GitHub, file, or text.
-
-<details>
-
-**Parameters:**
-
-- `source` (required): issue URL, repo#id, #id, file path, or raw text
-- `comments` (optional): include issue comments
-
-**Why it helps:**
-
-- lets the same workflow start from GitHub, a local file, or pasted text
-- gives planning and implementation flows a consistent input format
-
-</details>
-
-### `ticket_sync`
-
-Create or update a GitHub issue with checklists.
-
-<details>
-
-**Parameters:**
-
-- `title` (optional): issue title; required when creating a new issue or renaming one
-- `body` (optional): raw issue body override
-- `description` (optional): short issue description rendered above checklist sections
-- `labels` (optional): labels to apply when creating or updating the issue
-- `checklists` (optional): structured checklist sections rendered as markdown
-- `refUrl` (optional): issue URL to update instead of creating a new issue
-- `comments` (optional): issue comments to post without replacing the issue body
-
-**Why it helps:**
-
-- lets ticket flows create a new issue, update an existing one, or post a ticket comment with one tool
-- avoids making the agent handcraft raw `gh` issue commands each time
-
-</details>
-
-### `reload`
-
-Refresh the OpenCode project cache.
-
-<details>
-
-**Parameters:** none
-
-**Why it helps:**
-
-- refresh config, commands, and tools without restarting
-- useful after making changes to `kompass.jsonc`
-
-</details>
-
-## Config
-
-Project config is optional.
-
-If you want to customize Kompass, use one of these project override locations in precedence order:
+Kompass loads the bundled base config, then optional home-directory overrides, then optional project overrides. In each location it uses the first file that exists from:
 
 - `.opencode/kompass.jsonc`
 - `.opencode/kompass.json`
 - `kompass.jsonc`
 - `kompass.json`
 
-See `kompass.jsonc` for the published base config, `.opencode/kompass.jsonc` for the preferred consumer-project override shape, and `kompass.schema.json` for the schema.
-
-Tool names can also be remapped per adapter. For example, this keeps `ticket_sync` enabled but exposes it as `custom_ticket_name`, and Kompass command or agent references are rewritten to match:
-
-```jsonc
-{
-  "tools": {
-    "ticket_sync": {
-      "enabled": true,
-      "name": "custom_ticket_name"
-    }
-  }
-}
-```
+The recommended project override path is `.opencode/kompass.jsonc`.
 
 ## Workspace
 
 This repository is the Kompass development workspace.
 
-- `packages/core`: shared Kompass workflows, prompts, components, config loading, and tool definitions
+- `packages/core`: shared workflows, prompts, components, config loading, and tool definitions
 - `packages/opencode`: the OpenCode adapter package, published as `@kompassdev/opencode`
+- `packages/web`: docs site and web content
+- `packages/opencode/.opencode/`: generated OpenCode output for review
 
-The root coordinates workspace scripts, shared config, tests, and compiled review output.
-
-## Workspace Scripts
-
-```bash
-bun run compile
-bun run typecheck
-bun run test
-```
-
-`bun run compile` regenerates `packages/opencode/.opencode/` from the OpenCode package.
-
-## Publishing Direction
-
-- publish `packages/opencode` as `@kompassdev/opencode`
-- keep shared workflow logic in `packages/core`
-- add future adapters as sibling packages, such as `packages/claude-code`
+When changing Kompass itself, keep runtime definitions, bundled config, schema, docs, and generated output in sync in the same change.
diff --git a/kompass.jsonc b/kompass.jsonc
index 2a071d0..85c14f6 100644
--- a/kompass.jsonc
+++ b/kompass.jsonc
@@ -12,6 +12,7 @@
   // Command config is now object-based so each entry can be toggled or customized.
   "commands": {
     "ask": { "enabled": true },
+    "branch": { "enabled": true },
     "commit": { "enabled": true },
     "commit-and-push": { "enabled": true },
     "dev": { "enabled": true },
@@ -28,6 +29,7 @@
     "ticket/create": { "enabled": true },
     "ticket/dev": { "enabled": true },
     "ticket/plan": { "enabled": true },
+    "ticket/plan-and-sync": { "enabled": true },
   },
 
   "agents": {
@@ -51,6 +53,8 @@
     "changes-summary": { "enabled": true },
     "commit": { "enabled": true },
     "dev-flow": { "enabled": true },
+    "load-pr": { "enabled": true },
+    "load-ticket": { "enabled": true },
     "summarize-changes": { "enabled": true },
   },
 
diff --git a/kompass.schema.json b/kompass.schema.json
index 4e0cdf8..d8b22c7 100644
--- a/kompass.schema.json
+++ b/kompass.schema.json
@@ -32,6 +32,12 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "ask": {
+          "$ref": "#/$defs/commandConfig"
+        },
+        "branch": {
+          "$ref": "#/$defs/commandConfig"
+        },
         "commit": {
           "$ref": "#/$defs/commandConfig"
         },
@@ -68,6 +74,9 @@
         "todo": {
           "$ref": "#/$defs/commandConfig"
         },
+        "ticket/ask": {
+          "$ref": "#/$defs/commandConfig"
+        },
         "ticket/create": {
           "$ref": "#/$defs/commandConfig"
         },
@@ -77,11 +86,16 @@
         "ticket/plan": {
           "$ref": "#/$defs/commandConfig"
         },
+        "ticket/plan-and-sync": {
+          "$ref": "#/$defs/commandConfig"
+        },
         "enabled": {
           "type": "array",
           "items": {
             "type": "string",
             "enum": [
+              "ask",
+              "branch",
               "commit",
               "commit-and-push",
               "dev",
@@ -94,9 +108,11 @@
               "ship",
               "rmslop",
               "todo",
+              "ticket/ask",
               "ticket/create",
               "ticket/dev",
-              "ticket/plan"
+              "ticket/plan",
+              "ticket/plan-and-sync"
             ]
           },
           "uniqueItems": true,
@@ -106,6 +122,8 @@
           "type": "object",
           "propertyNames": {
             "enum": [
+              "ask",
+              "branch",
               "commit",
               "commit-and-push",
               "dev",
@@ -118,9 +136,11 @@
               "ship",
               "rmslop",
               "todo",
+              "ticket/ask",
               "ticket/create",
               "ticket/dev",
-              "ticket/plan"
+              "ticket/plan",
+              "ticket/plan-and-sync"
             ]
           },
           "additionalProperties": {
@@ -197,6 +217,12 @@
         "dev-flow": {
           "$ref": "#/$defs/componentConfig"
         },
+        "load-pr": {
+          "$ref": "#/$defs/componentConfig"
+        },
+        "load-ticket": {
+          "$ref": "#/$defs/componentConfig"
+        },
         "summarize-changes": {
           "$ref": "#/$defs/componentConfig"
         },
@@ -204,7 +230,7 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "summarize-changes"]
+            "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "summarize-changes"]
           },
           "uniqueItems": true,
           "deprecated": true
@@ -212,7 +238,7 @@
         "paths": {
           "type": "object",
           "propertyNames": {
-            "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "summarize-changes"]
+            "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "summarize-changes"]
           },
           "additionalProperties": {
             "type": "string"
@@ -306,6 +332,10 @@
             "agentMode": {
               "type": "string",
               "enum": ["subagent", "primary", "all"]
+            },
+            "subtaskCommandMode": {
+              "type": "string",
+              "enum": ["kompass", "all", "off"]
             }
           }
         }
diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts
index b1ea03a..f18751a 100644
--- a/packages/core/commands/index.ts
+++ b/packages/core/commands/index.ts
@@ -99,10 +99,15 @@ export const commandDefinitions: Record<string, CommandDefinition> = {
     templatePath: "commands/ticket/create.md",
   },
   "ticket/plan": {
-    description: "Plan work from a request or ticket and sync the result",
+    description: "Plan work from a request or ticket and display the result",
     agent: "planner",
     templatePath: "commands/ticket/plan.md",
   },
+  "ticket/plan-and-sync": {
+    description: "Plan work from a request or ticket and sync the result",
+    agent: "planner",
+    templatePath: "commands/ticket/plan-and-sync.md",
+  },
 };
 
 export interface ResolvedCommandDefinition
diff --git a/packages/core/commands/ticket/plan-and-sync.md b/packages/core/commands/ticket/plan-and-sync.md
new file mode 100644
index 0000000..e28dc8e
--- /dev/null
+++ b/packages/core/commands/ticket/plan-and-sync.md
@@ -0,0 +1,109 @@
+## Goal
+
+Create a scoped implementation plan from a request or ticket, then capture that plan in the relevant ticket flow without losing important technical context.
+
+## Workflow
+
+### Arguments
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+### Interpret Arguments
+
+- If `<arguments>` looks like a ticket reference or URL, store it as `<ticket-url>`
+- Otherwise, treat `<arguments>` as `<request>`
+- If `<arguments>` includes planning focus areas, constraints, or notes beyond the main request, store them as `<additional-context>`
+- If no `<arguments>` are provided, derive the current request from the conversation and store it as `<request>`
+
+### Load Planning Context
+
+- If `<ticket-url>` is defined:
+<%~ include("@load-ticket", { source: "<ticket-url>", result: "<planning-context>", comments: true }) %>
+- Otherwise, treat the relevant request and conversation context as `<planning-context>`
+- If `<planning-context>` is empty or missing, STOP and report that planning context could not be determined
+
+### Interpret Planning Context
+
+- From `<planning-context>` and `<additional-context>`, derive:
+  - `<planning-objective>` - the current planning task or request
+  - `<operative-constraints>` - earlier context that still applies
+  - `<proposed-technical-direction>` - technical details already proposed in the discussion
+  - `<open-questions>` - only the issues that are still unresolved
+- Use the current request to determine `<planning-objective>`
+- Do not discard earlier comments when they still define constraints, business rules, implementation decisions, migration rules, naming, sequencing, or scoping limits
+
+### Inspect Repo Context
+
+- If the request is technical and repository context is available, perform light targeted reconnaissance before finalizing the plan
+- Inspect the relevant code, schema, config, UI patterns, and tests needed to validate `<proposed-technical-direction>` and ground the plan
+- Confirm current behavior and existing patterns instead of relying on ticket text alone
+- If relevant repo context cannot be found or verified, note that gap and avoid false certainty
+
+### Shape the Plan
+
+- Turn `<planning-objective>`, `<operative-constraints>`, `<proposed-technical-direction>`, `<open-questions>`, and repo findings into:
+  - `<plan-title>` - a short, useful title
+  - `<plan-description>` - a brief description of the intended outcome, scope, important constraints, and material technical direction
+  - `<requirement-items>` - concise requirement checklist items
+  - `<validation-items>` - validation checklist items
+- Preserve good technical details from the ticket or conversation when they are valid
+- Improve incomplete technical details when repo inspection provides a better grounded direction
+- Do not replace material technical guidance with generic outcome language
+- Avoid placeholder-like labels or awkward title formats such as `Ticket`, `Description`, or `Ticket : Description`
+
+### Sync Ticket
+
+- Use `ticket_sync` to store the plan in the ticket flow:
+  - set `title` to `<plan-title>`
+  - set `description` to `<plan-description>`
+  - set `checklists` to two sections:
+    - `Implementation` with `<requirement-items>`
+    - `Validation` with `<validation-items>`
+  - set `refUrl` to `<ticket-url>` when updating an existing ticket
+  - leave `refUrl` unset when creating a new ticket from the request
+- Store the returned ticket URL as `<ticket-url>`
+
+### Present Plan
+
+- Return the generated title, a brief plan summary, and the ticket reference or URL
+- Call out assumptions, risks, or blockers only when they materially matter
+
+## Additional Context
+
+- Treat ticket systems generically. Do not assume GitHub or any specific provider unless the provided context makes it relevant.
+- Use the current request to determine `<planning-objective>`.
+- Earlier comments remain in force when they add operative constraints, business rules, technical decisions, migration rules, exact labels or renames, ordering rules, or scoping rules.
+- Use `<additional-context>` to emphasize the most important constraints, dependencies, or focus areas.
+- For technical tickets, repo inspection is expected unless the request is clearly non-technical or repository context is unavailable.
+- If technical details provided in the conversation are good, keep them.
+- If those details are incomplete, validate and improve them.
+- For existing tickets, update the same ticket instead of creating a replacement.
+- Ask only when blocked by a missing or invalid ticket source, or by ambiguity that prevents a reliable plan.
+
+## Output
+
+If planning context cannot be determined, display:
+```
+Unable to plan: missing request or ticket context
+
+No additional steps are required.
+```
+
+When the plan is ready, display:
+```text
+Title: `<plan-title>`
+URL: `<ticket-url>`
+
+Plan:
+<plan-description>
+
+## Implementation
+- <requirement-item>
+
+## Validation
+- <validation-item>
+
+No additional steps are required.
+```
diff --git a/packages/core/commands/ticket/plan.md b/packages/core/commands/ticket/plan.md
index e28dc8e..ebdfdcd 100644
--- a/packages/core/commands/ticket/plan.md
+++ b/packages/core/commands/ticket/plan.md
@@ -1,6 +1,6 @@
 ## Goal
 
-Create a scoped implementation plan from a request or ticket, then capture that plan in the relevant ticket flow without losing important technical context.
+Create a scoped implementation plan from a request or ticket and present it directly without modifying any ticket state.
 
 ## Workflow
 
@@ -53,21 +53,9 @@ $ARGUMENTS
 - Do not replace material technical guidance with generic outcome language
 - Avoid placeholder-like labels or awkward title formats such as `Ticket`, `Description`, or `Ticket : Description`
 
-### Sync Ticket
-
-- Use `ticket_sync` to store the plan in the ticket flow:
-  - set `title` to `<plan-title>`
-  - set `description` to `<plan-description>`
-  - set `checklists` to two sections:
-    - `Implementation` with `<requirement-items>`
-    - `Validation` with `<validation-items>`
-  - set `refUrl` to `<ticket-url>` when updating an existing ticket
-  - leave `refUrl` unset when creating a new ticket from the request
-- Store the returned ticket URL as `<ticket-url>`
-
 ### Present Plan
 
-- Return the generated title, a brief plan summary, and the ticket reference or URL
+- Return the generated title and plan details without creating or updating a ticket
 - Call out assumptions, risks, or blockers only when they materially matter
 
 ## Additional Context
@@ -79,7 +67,7 @@ $ARGUMENTS
 - For technical tickets, repo inspection is expected unless the request is clearly non-technical or repository context is unavailable.
 - If technical details provided in the conversation are good, keep them.
 - If those details are incomplete, validate and improve them.
-- For existing tickets, update the same ticket instead of creating a replacement.
+- If a ticket source was provided, use it as planning context only; do not sync updates back automatically.
 - Ask only when blocked by a missing or invalid ticket source, or by ambiguity that prevents a reliable plan.
 
 ## Output
@@ -94,7 +82,6 @@ No additional steps are required.
 When the plan is ready, display:
 ```text
 Title: `<plan-title>`
-URL: `<ticket-url>`
 
 Plan:
 <plan-description>
diff --git a/packages/core/kompass.jsonc b/packages/core/kompass.jsonc
index ed33dbe..85c14f6 100644
--- a/packages/core/kompass.jsonc
+++ b/packages/core/kompass.jsonc
@@ -12,6 +12,7 @@
   // Command config is now object-based so each entry can be toggled or customized.
   "commands": {
     "ask": { "enabled": true },
+    "branch": { "enabled": true },
     "commit": { "enabled": true },
     "commit-and-push": { "enabled": true },
     "dev": { "enabled": true },
@@ -28,6 +29,7 @@
     "ticket/create": { "enabled": true },
     "ticket/dev": { "enabled": true },
     "ticket/plan": { "enabled": true },
+    "ticket/plan-and-sync": { "enabled": true },
   },
 
   "agents": {
@@ -51,6 +53,8 @@
     "changes-summary": { "enabled": true },
     "commit": { "enabled": true },
     "dev-flow": { "enabled": true },
+    "load-pr": { "enabled": true },
+    "load-ticket": { "enabled": true },
     "summarize-changes": { "enabled": true },
   },
 
@@ -61,6 +65,7 @@
   "adapters": {
     "opencode": {
       "agentMode": "all",
+      "subtaskCommandMode": "kompass",
     },
   },
 }
diff --git a/packages/core/lib/config.ts b/packages/core/lib/config.ts
index fd48ca4..fb710f0 100644
--- a/packages/core/lib/config.ts
+++ b/packages/core/lib/config.ts
@@ -40,6 +40,7 @@ export const DEFAULT_COMMAND_NAMES = [
   "ticket/create",
   "ticket/dev",
   "ticket/plan",
+  "ticket/plan-and-sync",
 ] as const;
 
 export const DEFAULT_AGENT_NAMES = ["worker", "navigator", "planner", "reviewer"] as const;
@@ -122,6 +123,7 @@ export interface KompassConfig {
     "ticket/create"?: CommandConfig;
     "ticket/dev"?: CommandConfig;
     "ticket/plan"?: CommandConfig;
+    "ticket/plan-and-sync"?: CommandConfig;
     enabled?: string[];
     templates?: Record<string, string>;
   };
diff --git a/packages/core/skills.todo/kompass-workflows/SKILL.md b/packages/core/skills.todo/kompass-workflows/SKILL.md
index 01341e1..67cc997 100644
--- a/packages/core/skills.todo/kompass-workflows/SKILL.md
+++ b/packages/core/skills.todo/kompass-workflows/SKILL.md
@@ -20,7 +20,8 @@ Kompass adds focused repository workflows to OpenCode through built-in commands,
 - Use `/pr/review` for GitHub PR review flows.
 - Use `/pr/create` to summarize work and create a PR.
 - Use `/pr/fix` to address PR feedback.
-- Use `/ticket/plan` to turn a request or ticket into a scoped implementation plan.
+- Use `/ticket/plan` to turn a request or ticket into a scoped implementation plan without syncing it.
+- Use `/ticket/plan-and-sync` to turn a request or ticket into a scoped implementation plan and store it in the ticket flow.
 - Use `/ticket/dev` or `/dev` for focused implementation work.
 - Use `/commit` or `/commit-and-push` when the user explicitly asks to commit.
 
diff --git a/packages/opencode/.opencode/commands/ticket/plan-and-sync.md b/packages/opencode/.opencode/commands/ticket/plan-and-sync.md
new file mode 100644
index 0000000..b72dc77
--- /dev/null
+++ b/packages/opencode/.opencode/commands/ticket/plan-and-sync.md
@@ -0,0 +1,118 @@
+---
+description: Plan work from a request or ticket and sync the result
+agent: planner
+---
+
+## Goal
+
+Create a scoped implementation plan from a request or ticket, then capture that plan in the relevant ticket flow without losing important technical context.
+
+## Workflow
+
+### Arguments
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+### Interpret Arguments
+
+- If `<arguments>` looks like a ticket reference or URL, store it as `<ticket-url>`
+- Otherwise, treat `<arguments>` as `<request>`
+- If `<arguments>` includes planning focus areas, constraints, or notes beyond the main request, store them as `<additional-context>`
+- If no `<arguments>` are provided, derive the current request from the conversation and store it as `<request>`
+
+### Load Planning Context
+
+- If `<ticket-url>` is defined:
+- Use `kompass_ticket_load` with `source: <ticket-url>` and `comments: true`
+- Store the result as `<planning-context>`
+- Treat the loaded ticket body, discussion, and any attachments or linked artifacts returned by the loader as part of the source context
+- Review attached images, PDFs, and other linked files whenever they can affect requirements, acceptance criteria, reproduction steps, design direction, or the requested answer
+- If any relevant attachment cannot be accessed, note that gap and continue only when the remaining ticket context is still sufficient to proceed reliably
+- Otherwise, treat the relevant request and conversation context as `<planning-context>`
+- If `<planning-context>` is empty or missing, STOP and report that planning context could not be determined
+
+### Interpret Planning Context
+
+- From `<planning-context>` and `<additional-context>`, derive:
+  - `<planning-objective>` - the current planning task or request
+  - `<operative-constraints>` - earlier context that still applies
+  - `<proposed-technical-direction>` - technical details already proposed in the discussion
+  - `<open-questions>` - only the issues that are still unresolved
+- Use the current request to determine `<planning-objective>`
+- Do not discard earlier comments when they still define constraints, business rules, implementation decisions, migration rules, naming, sequencing, or scoping limits
+
+### Inspect Repo Context
+
+- If the request is technical and repository context is available, perform light targeted reconnaissance before finalizing the plan
+- Inspect the relevant code, schema, config, UI patterns, and tests needed to validate `<proposed-technical-direction>` and ground the plan
+- Confirm current behavior and existing patterns instead of relying on ticket text alone
+- If relevant repo context cannot be found or verified, note that gap and avoid false certainty
+
+### Shape the Plan
+
+- Turn `<planning-objective>`, `<operative-constraints>`, `<proposed-technical-direction>`, `<open-questions>`, and repo findings into:
+  - `<plan-title>` - a short, useful title
+  - `<plan-description>` - a brief description of the intended outcome, scope, important constraints, and material technical direction
+  - `<requirement-items>` - concise requirement checklist items
+  - `<validation-items>` - validation checklist items
+- Preserve good technical details from the ticket or conversation when they are valid
+- Improve incomplete technical details when repo inspection provides a better grounded direction
+- Do not replace material technical guidance with generic outcome language
+- Avoid placeholder-like labels or awkward title formats such as `Ticket`, `Description`, or `Ticket : Description`
+
+### Sync Ticket
+
+- Use `kompass_ticket_sync` to store the plan in the ticket flow:
+  - set `title` to `<plan-title>`
+  - set `description` to `<plan-description>`
+  - set `checklists` to two sections:
+    - `Implementation` with `<requirement-items>`
+    - `Validation` with `<validation-items>`
+  - set `refUrl` to `<ticket-url>` when updating an existing ticket
+  - leave `refUrl` unset when creating a new ticket from the request
+- Store the returned ticket URL as `<ticket-url>`
+
+### Present Plan
+
+- Return the generated title, a brief plan summary, and the ticket reference or URL
+- Call out assumptions, risks, or blockers only when they materially matter
+
+## Additional Context
+
+- Treat ticket systems generically. Do not assume GitHub or any specific provider unless the provided context makes it relevant.
+- Use the current request to determine `<planning-objective>`.
+- Earlier comments remain in force when they add operative constraints, business rules, technical decisions, migration rules, exact labels or renames, ordering rules, or scoping rules.
+- Use `<additional-context>` to emphasize the most important constraints, dependencies, or focus areas.
+- For technical tickets, repo inspection is expected unless the request is clearly non-technical or repository context is unavailable.
+- If technical details provided in the conversation are good, keep them.
+- If those details are incomplete, validate and improve them.
+- For existing tickets, update the same ticket instead of creating a replacement.
+- Ask only when blocked by a missing or invalid ticket source, or by ambiguity that prevents a reliable plan.
+
+## Output
+
+If planning context cannot be determined, display:
+```
+Unable to plan: missing request or ticket context
+
+No additional steps are required.
+```
+
+When the plan is ready, display:
+```text
+Title: `<plan-title>`
+URL: `<ticket-url>`
+
+Plan:
+<plan-description>
+
+## Implementation
+- <requirement-item>
+
+## Validation
+- <validation-item>
+
+No additional steps are required.
+```
diff --git a/packages/opencode/.opencode/commands/ticket/plan.md b/packages/opencode/.opencode/commands/ticket/plan.md
index b72dc77..5752809 100644
--- a/packages/opencode/.opencode/commands/ticket/plan.md
+++ b/packages/opencode/.opencode/commands/ticket/plan.md
@@ -1,11 +1,11 @@
 ---
-description: Plan work from a request or ticket and sync the result
+description: Plan work from a request or ticket and display the result
 agent: planner
 ---
 
 ## Goal
 
-Create a scoped implementation plan from a request or ticket, then capture that plan in the relevant ticket flow without losing important technical context.
+Create a scoped implementation plan from a request or ticket and present it directly without modifying any ticket state.
 
 ## Workflow
 
@@ -62,21 +62,9 @@ $ARGUMENTS
 - Do not replace material technical guidance with generic outcome language
 - Avoid placeholder-like labels or awkward title formats such as `Ticket`, `Description`, or `Ticket : Description`
 
-### Sync Ticket
-
-- Use `kompass_ticket_sync` to store the plan in the ticket flow:
-  - set `title` to `<plan-title>`
-  - set `description` to `<plan-description>`
-  - set `checklists` to two sections:
-    - `Implementation` with `<requirement-items>`
-    - `Validation` with `<validation-items>`
-  - set `refUrl` to `<ticket-url>` when updating an existing ticket
-  - leave `refUrl` unset when creating a new ticket from the request
-- Store the returned ticket URL as `<ticket-url>`
-
 ### Present Plan
 
-- Return the generated title, a brief plan summary, and the ticket reference or URL
+- Return the generated title and plan details without creating or updating a ticket
 - Call out assumptions, risks, or blockers only when they materially matter
 
 ## Additional Context
@@ -88,7 +76,7 @@ $ARGUMENTS
 - For technical tickets, repo inspection is expected unless the request is clearly non-technical or repository context is unavailable.
 - If technical details provided in the conversation are good, keep them.
 - If those details are incomplete, validate and improve them.
-- For existing tickets, update the same ticket instead of creating a replacement.
+- If a ticket source was provided, use it as planning context only; do not sync updates back automatically.
 - Ask only when blocked by a missing or invalid ticket source, or by ambiguity that prevents a reliable plan.
 
 ## Output
@@ -103,7 +91,6 @@ No additional steps are required.
 When the plan is ready, display:
 ```text
 Title: `<plan-title>`
-URL: `<ticket-url>`
 
 Plan:
 <plan-description>
diff --git a/packages/opencode/.opencode/kompass.jsonc b/packages/opencode/.opencode/kompass.jsonc
index 2b50597..d665225 100644
--- a/packages/opencode/.opencode/kompass.jsonc
+++ b/packages/opencode/.opencode/kompass.jsonc
@@ -60,6 +60,9 @@
     },
     "ticket/plan": {
       "enabled": true
+    },
+    "ticket/plan-and-sync": {
+      "enabled": true
     }
   },
   "agents": {
diff --git a/packages/opencode/README.md b/packages/opencode/README.md
index 899ee4a..c53d3ad 100644
--- a/packages/opencode/README.md
+++ b/packages/opencode/README.md
@@ -1,35 +1,21 @@
-> Kompass is under active development, so workflows, package APIs, and adapter support may keep evolving as the toolkit expands.
+# @kompassdev/opencode
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/kompassdev/kompass/main/assets/kompass.png" alt="Kompass" height="300" />
-  <br>
-  <em>Navigate your way - manual steering, steered autonomy, or autonomously.</em>
-</p>
+OpenCode adapter for Kompass.
 
-Kompass keeps AI coding agents on course with token-efficient, composable workflows. **Finally, your agent stops wandering.**
+Kompass provides structured commands, agents, tools, and skills so AI coding workflows stay reviewable and focused instead of drifting across long sessions.
 
-Whether you prefer full control, guided collaboration, or hands-off autonomy, Kompass adapts to how you work.
+## Docs
 
-## Choose Your Mode
-
-<p>**🧭 Manual Steering** — You chart the course, the agent follows your lead</p>
-<p>**⚓ Collaborative** — Plan together, develop together, review together</p>
-<p>**🚢 Autonomous** — Let your agent navigate independently, review at checkpoints</p>
-
-## Why Kompass?
-
-| Challenge | How Kompass Helps |
-|-----------|-------------------|
-| Agents wander without direction | 🧭 **Navigation** — structured workflows keep agents on course |
-| Rebuilding prompts for every agent | 🔌 **Plug & Play** — same workflows across OpenCode, Claude Code, and more |
-| Token bloat in long sessions | 🎯 **Token Efficient** — minimal, focused prompts that get to the point |
-| Ad-hoc planning and review | ⚓ **Workflows** — purpose-built flows for plan, dev, and review |
-| Generic tools miss context | 🛠️ **Tailored Tools** — purpose-built for repository work |
-| Complex setup overhead | ⚡ **Easy to Use** — install the plugin, start navigating |
+- Main docs: `https://kompassdev.ai/docs/`
+- OpenCode adapter: `https://kompassdev.ai/docs/adapters/opencode/`
+- Config reference: `https://kompassdev.ai/docs/config/overview/`
+- Command reference: `https://kompassdev.ai/docs/reference/commands/`
+- Agent reference: `https://kompassdev.ai/docs/reference/agents/`
+- Tool reference: `https://kompassdev.ai/docs/reference/tools/`
 
 ## Installation
 
-For OpenCode, add the adapter package to your config:
+Add the adapter package to your OpenCode config:
 
 ```json
 {
@@ -37,430 +23,29 @@ For OpenCode, add the adapter package to your config:
 }
 ```
 
-Config is optional. To publish a project override:
+## Optional project config
+
+To start from the published base config:
 
 ```bash
-# Inside .opencode folder
 curl -fsSL https://raw.githubusercontent.com/kompassdev/kompass/main/kompass.jsonc -o .opencode/kompass.jsonc
-
 ```
 
-Kompass ships a bundled base config, then applies the first matching consumer-project override in this order: `.opencode/kompass.jsonc`, `.opencode/kompass.json`, `kompass.jsonc`, `kompass.json`.
-
-## How To Use
-
-### OpenCode
-
-Use `@kompassdev/opencode` when you want Kompass workflows inside OpenCode.
-
-- install the plugin in your OpenCode config
-- optionally add one project override file to customize commands, agents, tools, skills, and defaults; `.opencode/kompass.jsonc` is preferred
-- bundled Kompass skills are registered automatically when the plugin loads, so users do not need to copy skill files manually
-- use commands like `/ask`, `/review`, `/pr/create`, or `/ticket/plan` inside OpenCode
-- for CLI session debugging, use `opencode session list` to find a session id and `opencode export <sessionID>` to dump the raw session JSON
-
-### Claude Code
-
-Claude Code adapter support is coming soon.
-
-Kompass is being structured as a shared core toolkit with adapter-specific packages, so the same workflows can be reused across agents instead of rebuilt from scratch.
-
-## Agents
-
-### `worker`
-
-Handles generic implementation work and can ask targeted follow-up questions when execution is blocked.
-
-### `navigator`
-
-Coordinates structured multi-step workflows by keeping orchestration local and delegating only focused leaf work to subagents.
-
-### `planner`
-
-Turns a request or ticket into a scoped implementation plan.
-
-### `reviewer`
-
-Reviews branch or PR changes without editing files.
-
-## Commands
-
-### `/ask`
-
-Answers questions about the current project or codebase.
-
-<details>
-
-**Usage:** `/ask <question>`
-
-Loads only the relevant repository context needed to answer a project or code question directly.
-
-</details>
-
-### `/commit`
-
-Stages and commits changes with a generated message.
-
-<details>
-
-**Usage:** `/commit [message]`
-
-If a message is provided, commits with that message. Otherwise, generates an appropriate commit message based on the staged changes.
-
-</details>
-
-### `/commit-and-push`
-
-Stages, commits, and pushes changes in one workflow.
-
-<details>
-
-**Usage:** `/commit-and-push [message]`
-
-Commits changes (generating a message if not provided) and pushes to the remote repository.
-
-</details>
-
-### `/dev`
-
-Implementation mode for focused development work.
-
-<details>
-
-**Usage:** `/dev <description>`
-
-Use for active development tasks. The agent implements the described changes while staying focused on the task.
-
-</details>
-
-### `/learn`
-
-Learns patterns and conventions from existing code.
-
-<details>
-
-**Usage:** `/learn <what-to-learn>`
-
-Analyzes the codebase to understand patterns, conventions, or specific implementations. Useful for understanding how things work before making changes.
-
-</details>
-
-### `/pr/create`
-
-Creates a pull request with structured checklists.
-
-<details>
-
-**Usage:** `/pr/create [title]`
-
-Creates a PR from the current branch. Generates a title if not provided. Includes checklist sections for consistent PR structure.
-
-</details>
-
-### `/pr/fix`
-
-Fixes issues found during PR review.
-
-<details>
-
-**Usage:** `/pr/fix [context]`
-
-Addresses review comments and feedback on an open PR. Loads the PR context and works through requested changes.
-
-</details>
-
-### `/pr/review`
-
-Reviews a pull request and adds structured feedback.
-
-<details>
-
-**Usage:** `/pr/review [pr]`
-
-Reviews the specified PR (or current PR if not specified) and provides feedback using inline comments and review threads.
-
-</details>
-
-### `/reload`
-
-Reloads the OpenCode project cache.
-
-<details>
-
-**Usage:** `/reload`
-
-Refreshes config, commands, agents, and tools without restarting OpenCode. Useful after making changes to `kompass.jsonc`.
-
-</details>
-
-### `/review`
-
-Reviews branch changes for issues and improvements.
-
-<details>
-
-**Usage:** `/review [base]`
-
-Reviews uncommitted changes or changes against a base branch (default: main). Provides feedback on code quality, patterns, and potential issues.
-
-</details>
-
-### `/ship`
-
-Ships the fast path from change summary to commit and PR creation.
-
-<details>
-
-**Usage:** `/ship [base-or-context]`
-
-Summarizes current changes, creates a feature branch when you are still on the base branch, then delegates the commit and PR steps to `/commit` and `/pr/create`.
-
-</details>
-
-### `/todo`
-
-Works through a todo file task by task.
-
-<details>
-
-**Usage:** `/todo [todo-file]`
-
-Loads a todo list, delegates one item at a time, and keeps orchestration local so work can pause and resume cleanly.
-
-</details>
-
-### `/rmslop`
-
-Removes unnecessary code and simplifies.
-
-<details>
-
-**Usage:** `/rmslop`
-
-Analyzes the codebase for unnecessary complexity, unused code, and opportunities for simplification.
-
-</details>
-
-### `/ticket/create`
-
-Creates a GitHub issue from a description.
-
-<details>
-
-**Usage:** `/ticket/create <description>`
-
-Creates a new GitHub issue with the provided description, generating a title and structured body with checklists.
-
-</details>
-
-### `/ticket/ask`
-
-Answers a question on a ticket and posts the response.
-
-<details>
-
-**Usage:** `/ticket/ask <ticket-reference> <question>`
-
-Loads the ticket plus all comments, answers the question using ticket and repository context, and posts the response back to the same ticket.
-
-</details>
-
-### `/ticket/dev`
-
-Implements a ticket with planning and execution.
-
-<details>
-
-**Usage:** `/ticket/dev <ticket-reference>`
-
-Loads the specified ticket (URL, #id, or file path), creates an implementation plan, and executes the work.
-
-</details>
-
-### `/ticket/plan`
-
-Creates an implementation plan for a ticket.
-
-<details>
-
-**Usage:** `/ticket/plan <ticket-reference>`
-
-Loads the specified ticket and creates a detailed implementation plan without executing changes.
-
-</details>
-
-## Tools
-
-### `changes_load`
-
-Load branch changes against a base branch.
-
-<details>
-
-**Parameters:**
-
-- `base` (optional): base branch or ref
-- `head` (optional): head branch, commit, or ref override
-- `depthHint` (optional): shallow-fetch hint such as PR commit count
-- `uncommitted` (optional): only load uncommitted changes (staged and unstaged), never fall back to branch comparison
-
-**Why it helps:**
-
-- keeps branch diff loading focused
-- works well for review and PR workflows
-- handles workspace changes separately from committed branch diffs
-
-</details>
-
-### `pr_load`
-
-Load PR metadata and review history.
-
-<details>
-
-**Parameters:**
-
-- `pr` (optional): PR number or URL
-
-**Why it helps:**
-
-- gives agents normalized PR context before they start reviewing or summarizing
-- keeps review workflows grounded in actual PR state instead of inferred context
-
-</details>
-
-### `pr_sync`
-
-Create, update, or review a GitHub pull request with structured checklists.
-
-<details>
-
-**Parameters:**
-
-- `title` (optional): PR title; required when creating a PR or renaming one
-- `body` (optional): raw PR body override
-- `description` (optional): short PR description rendered above checklist sections
-- `base` (optional): base branch to merge into
-- `head` (optional): head branch to use when creating a PR
-- `checklists` (optional): structured checklist sections (e.g., Testing, Summary)
-- `draft` (optional): create as draft PR
-- `refUrl` (optional): PR URL to update instead of creating new
-- `commitId` (optional): commit SHA to anchor review comments to
-- `review` (optional): structured review submission with optional `body`, inline `comments`, and `approve` flag
-- `replies` (optional): replies to existing review comments
-- `commentBody` (optional): general PR comment body
-
-**Why it helps:**
-
-- consistent PR creation with checklist support
-- create, update, review, approve, and reply with one tool
-- no shell escaping issues
-
-</details>
-
-### `ticket_load`
-
-Load a ticket from GitHub, file, or text.
-
-<details>
-
-**Parameters:**
-
-- `source` (required): issue URL, repo#id, #id, file path, or raw text
-- `comments` (optional): include issue comments
-
-**Why it helps:**
-
-- lets the same workflow start from GitHub, a local file, or pasted text
-- gives planning and implementation flows a consistent input format
-
-</details>
-
-### `ticket_sync`
-
-Create or update a GitHub issue with checklists.
-
-<details>
-
-**Parameters:**
-
-- `title` (optional): issue title; required when creating a new issue or renaming one
-- `body` (optional): raw issue body override
-- `description` (optional): short issue description rendered above checklist sections
-- `labels` (optional): labels to apply when creating or updating the issue
-- `checklists` (optional): structured checklist sections rendered as markdown
-- `refUrl` (optional): issue URL to update instead of creating a new issue
-- `comments` (optional): issue comments to post without replacing the issue body
-
-**Why it helps:**
-
-- lets ticket flows create a new issue, update an existing one, or post a ticket comment with one tool
-- avoids making the agent handcraft raw `gh` issue commands each time
-
-</details>
-
-### `reload`
-
-Refresh the OpenCode project cache.
-
-<details>
-
-**Parameters:** none
-
-**Why it helps:**
-
-- refresh config, commands, and tools without restarting
-- useful after making changes to `kompass.jsonc`
-
-</details>
-
-## Config
-
-Project config is optional.
-
-If you want to customize Kompass, use one of these project override locations in precedence order:
+Kompass loads the bundled base config, then optional home-directory overrides, then optional project overrides. In each location it uses the first file that exists from:
 
 - `.opencode/kompass.jsonc`
 - `.opencode/kompass.json`
 - `kompass.jsonc`
 - `kompass.json`
 
-See `kompass.jsonc` for the published base config, `.opencode/kompass.jsonc` for the preferred consumer-project override shape, and `kompass.schema.json` for the schema.
-
-Tool names can also be remapped per adapter. For example, this keeps `ticket_sync` enabled but exposes it as `custom_ticket_name`, and Kompass command or agent references are rewritten to match:
-
-```jsonc
-{
-  "tools": {
-    "ticket_sync": {
-      "enabled": true,
-      "name": "custom_ticket_name"
-    }
-  }
-}
-```
-
-## Workspace
-
-This repository is the Kompass development workspace.
-
-- `packages/core`: shared Kompass workflows, prompts, components, config loading, and tool definitions
-- `packages/opencode`: the OpenCode adapter package, published as `@kompassdev/opencode`
-
-The root coordinates workspace scripts, shared config, tests, and compiled review output.
-
-## Workspace Scripts
-
-```bash
-bun run compile
-bun run typecheck
-bun run test
-```
+The recommended project override path is `.opencode/kompass.jsonc`.
 
-`bun run compile` regenerates `packages/opencode/.opencode/` from the OpenCode package.
+## What the adapter provides
 
-## Publishing Direction
+- Kompass commands
+- Kompass agent roles
+- Kompass tools
+- bundled skill registration
+- project override loading from local config files
 
-- publish `packages/opencode` as `@kompassdev/opencode`
-- keep shared workflow logic in `packages/core`
-- add future adapters as sibling packages, such as `packages/claude-code`
+Most command execution uses OpenCode's built-in `build` agent. Kompass also ships the `worker`, `navigator`, `planner`, and `reviewer` roles for structured subagent workflows.
diff --git a/packages/opencode/kompass.jsonc b/packages/opencode/kompass.jsonc
index ed33dbe..85c14f6 100644
--- a/packages/opencode/kompass.jsonc
+++ b/packages/opencode/kompass.jsonc
@@ -12,6 +12,7 @@
   // Command config is now object-based so each entry can be toggled or customized.
   "commands": {
     "ask": { "enabled": true },
+    "branch": { "enabled": true },
     "commit": { "enabled": true },
     "commit-and-push": { "enabled": true },
     "dev": { "enabled": true },
@@ -28,6 +29,7 @@
     "ticket/create": { "enabled": true },
     "ticket/dev": { "enabled": true },
     "ticket/plan": { "enabled": true },
+    "ticket/plan-and-sync": { "enabled": true },
   },
 
   "agents": {
@@ -51,6 +53,8 @@
     "changes-summary": { "enabled": true },
     "commit": { "enabled": true },
     "dev-flow": { "enabled": true },
+    "load-pr": { "enabled": true },
+    "load-ticket": { "enabled": true },
     "summarize-changes": { "enabled": true },
   },
 
@@ -61,6 +65,7 @@
   "adapters": {
     "opencode": {
       "agentMode": "all",
+      "subtaskCommandMode": "kompass",
     },
   },
 }
diff --git a/packages/opencode/test/commands-config.test.ts b/packages/opencode/test/commands-config.test.ts
index 09e2ab7..db0f44e 100644
--- a/packages/opencode/test/commands-config.test.ts
+++ b/packages/opencode/test/commands-config.test.ts
@@ -42,6 +42,7 @@ describe("applyCommandsConfig", () => {
         "ticket/ask",
         "ticket/create",
         "ticket/plan",
+        "ticket/plan-and-sync",
         "ticket/dev",
         "review",
         "dev",
@@ -64,6 +65,7 @@ describe("applyCommandsConfig", () => {
       assert.equal(cfg.command!["pr/create"]?.agent, "build");
       assert.equal(cfg.command!["ticket/create"]?.agent, "build");
       assert.equal(cfg.command!["ticket/plan"]?.agent, "planner");
+      assert.equal(cfg.command!["ticket/plan-and-sync"]?.agent, "planner");
       assert.equal(cfg.command!["ask"]?.agent, "build");
       assert.equal(cfg.command!["ticket/ask"]?.agent, "build");
       assert.equal(cfg.command!["dev"]?.agent, "build");
@@ -151,14 +153,19 @@ describe("applyCommandsConfig", () => {
         assert.ok(cfg.command);
         const ticketCreateTemplate = cfg.command!["ticket/create"].template;
         const ticketPlanTemplate = cfg.command!["ticket/plan"].template;
+        const ticketPlanAndSyncTemplate = cfg.command!["ticket/plan-and-sync"].template;
 
         assert.match(ticketCreateTemplate, /`custom_ticket_name`/);
         assert.doesNotMatch(ticketCreateTemplate, /`kompass_ticket_sync`/);
         assert.doesNotMatch(ticketCreateTemplate, /`ticket_sync`/);
 
-        assert.match(ticketPlanTemplate, /`custom_ticket_name`/);
+        assert.doesNotMatch(ticketPlanTemplate, /`custom_ticket_name`/);
         assert.doesNotMatch(ticketPlanTemplate, /`kompass_ticket_sync`/);
         assert.doesNotMatch(ticketPlanTemplate, /`ticket_sync`/);
+
+        assert.match(ticketPlanAndSyncTemplate, /`custom_ticket_name`/);
+        assert.doesNotMatch(ticketPlanAndSyncTemplate, /`kompass_ticket_sync`/);
+        assert.doesNotMatch(ticketPlanAndSyncTemplate, /`ticket_sync`/);
       } finally {
         await rm(tempDir, { recursive: true, force: true });
       }
@@ -422,6 +429,7 @@ describe("applyCommandsConfig", () => {
       assert.ok(cfg.command!["pr/review"]?.template);
       assert.ok(cfg.command!["ticket/ask"]?.template);
       assert.ok(cfg.command!["ticket/plan"]?.template);
+      assert.ok(cfg.command!["ticket/plan-and-sync"]?.template);
       assert.ok(cfg.command!["pr/fix"]?.template);
       assert.ok(cfg.command!["ship"]?.template);
       assert.ok(cfg.command!["ticket/dev"]?.template);
diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index 09f1206..0494725 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -52,8 +52,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'It has a clear point of view: keep AI coding agents "on course" with token-efficient, composable workflows instead of giant ad-hoc prompts.',
           'The repo is structured thoughtfully: shared logic lives in packages/core, adapter-specific wiring in packages/opencode.',
-          'The command surface is unusually coherent — /ask, /review, /pr/create, /ticket/plan all fit the same workflow philosophy.',
-          'No additional steps are required.'
+          'The command surface is unusually coherent — /ask, /review, /pr/create, /ticket/plan all fit the same workflow philosophy.'
         ]
       }
     ]
@@ -61,7 +60,7 @@ const scenarios: CommandScenario[] = [
   {
     id: 'ticket-plan',
     label: '/ticket/plan',
-    command: '/ticket/plan #128 rollout the new review workflow',
+    command: '/ticket/plan #128',
     agentName: 'Planner',
     task: 'Turn a request or ticket into a scoped implementation plan',
     steps: [
@@ -85,8 +84,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Phase 1: Extract reusable review components from existing commands',
           'Phase 2: Update navigator agent to coordinate review workflows',
-          'Phase 3: Add checklist generation and feedback threading',
-          'Plan ready for implementation. No additional steps required.'
+          'Phase 3: Add checklist generation and feedback threading'
         ]
       }
     ]
@@ -118,8 +116,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Created PR #47: Add workflow visualization to homepage',
           'Linked to ticket #42 with structured checklist',
-          'PR body includes summary, changes, and testing notes',
-          'No additional steps are required.'
+          'PR body includes summary, changes, and testing notes'
         ]
       }
     ]
@@ -151,8 +148,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Strong separation of concerns between scenarios and rendering',
           'Consider adding error handling for failed tool calls',
-          'Animation timing is appropriate for the UX flow',
-          'No additional steps are required.'
+          'Animation timing is appropriate for the UX flow'
         ]
       }
     ]
@@ -184,8 +180,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Implemented review workflow in packages/core/commands/pr/',
           'Added navigator coordination and feedback threading',
-          'All validation checks passed successfully',
-          'No additional steps are required.'
+          'All validation checks passed successfully'
         ]
       }
     ]
@@ -217,8 +212,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Created branch: feature/new-workflow',
           'Committed 3 files with generated message',
-          'Published PR #48: Add new workflow command',
-          'No additional steps are required.'
+          'Published PR #48: Add new workflow command'
         ]
       }
     ]
@@ -250,8 +244,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Removed 47 lines of duplicate validation logic',
           'Simplified 3 overly-abstract helper functions',
-          'Consolidated similar command patterns into shared components',
-          'No additional steps are required.'
+          'Consolidated similar command patterns into shared components'
         ]
       }
     ]
@@ -284,8 +277,7 @@ const scenarios: CommandScenario[] = [
         output: [
           'Completed: Update command showcase with more examples',
           'Blocked: Waiting for review on PR #47',
-          'Next: Add mobile responsive styling',
-          'No additional steps are required.'
+          'Next: Add mobile responsive styling'
         ]
       }
     ]
@@ -318,14 +310,170 @@ const scenarios: CommandScenario[] = [
         output: [
           'Staged 3 modified files',
           'Created commit: feat: add command showcase with animations',
-          'Pushed to origin/feature/showcase',
-          'No additional steps are required.'
+          'Pushed to origin/feature/showcase'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'branch',
+    label: '/branch',
+    command: '/branch',
+    agentName: 'Worker',
+    task: 'Create categorized branch names',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Creating branch — need to summarize uncommitted work and generate a categorized branch name based on the change themes.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'changes_load', args: 'uncommitted', status: 'complete' },
+          { tool: 'bash', args: 'git checkout -b docs/site-refresh', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Created branch: docs/site-refresh',
+          'Switched from main to the new work branch'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'commit',
+    label: '/commit',
+    command: '/commit',
+    agentName: 'Worker',
+    task: 'Generate why-focused commit messages',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Committing — need to inspect staged and unstaged changes, then generate a commit message focused on why the changes were made.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'changes_load', args: 'uncommitted', status: 'complete' },
+          { tool: 'bash', args: 'git add packages/web/src/', status: 'complete' },
+          { tool: 'bash', args: 'git commit -m "feat: improve command showcase"', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Staged relevant files',
+          'Created a new commit with generated message'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'learn',
+    label: '/learn',
+    command: '/learn',
+    agentName: 'Worker',
+    task: 'Extract patterns into AGENTS.md',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Learning — need to inspect existing patterns in the repo and extract reusable guidance into AGENTS.md targets.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'read', args: 'AGENTS.md', status: 'complete' },
+          { tool: 'grep', args: 'function|const|class', status: 'complete' },
+          { tool: 'apply_patch', args: 'AGENTS.md', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Summarized established conventions',
+          'Updated agent guidance where the pattern belongs'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'pr-fix',
+    label: '/pr/fix',
+    command: '/pr/fix',
+    agentName: 'Navigator',
+    task: 'Fix requested PR changes',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Fixing PR — need to load PR history and outstanding feedback, then review proposed fixes before applying.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'pr_load', args: 'current', status: 'complete' },
+          { tool: 'apply_patch', args: 'requested changes', status: 'complete' },
+          { tool: 'bash', args: 'npm run test', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Fixed requested issues on the branch',
+          'Posted replies to the relevant review threads'
+        ]
+      }
+    ]
+  },
+  {
+    id: 'pr-review',
+    label: '/pr/review',
+    command: '/pr/review',
+    agentName: 'Reviewer',
+    task: 'Review PR with inline comments',
+    steps: [
+      {
+        id: 'thinking',
+        phase: 'thinking',
+        content: 'Reviewing PR — need to load PR, reviews, comments, files, and diff context. Will load linked ticket too before reviewing.'
+      },
+      {
+        id: 'tools',
+        phase: 'tool_calls',
+        toolCalls: [
+          { tool: 'pr_load', args: 'current', status: 'complete' },
+          { tool: 'ticket_load', args: '#42', status: 'complete' },
+          { tool: 'changes_load', args: 'HEAD...main', status: 'complete' }
+        ]
+      },
+      {
+        id: 'output',
+        phase: 'output',
+        output: [
+          'Added inline comments and review summary',
+          'Approved or requested changes based on findings'
         ]
       }
     ]
   }
 ];
 
+// Split scenarios into two groups
+const commandScenarios = scenarios.filter(s => ['ask', 'branch', 'commit', 'commit-and-push', 'dev', 'learn', 'reload', 'review', 'rmslop'].includes(s.id));
+const orchestratorScenarios = scenarios.filter(s => ['pr-create', 'pr-fix', 'pr-review', 'ship', 'todo', 'ticket-plan'].includes(s.id));
 
 ---
 
@@ -339,21 +487,39 @@ const scenarios: CommandScenario[] = [
   </div>
 
   <div class="command-showcase__main">
-    <!-- Tab navigation -->
-    <div class="command-strip" role="tablist" aria-label="Command examples">
-      {scenarios.map((scenario, index) => (
-        <button 
-          type="button"
-          class:list={{ "command-tab": true, "is-active": index === 0 }}
-          role="tab"
-          aria-selected={index === 0 ? "true" : "false"}
-          aria-controls={`panel-${scenario.id}`}
-          id={`tab-${scenario.id}`}
-          data-command-tab={scenario.id}
-        >
-          {scenario.label}
-        </button>
-      ))}
+    <!-- Combined Tab navigation with groups -->
+    <div class="command-strip-wrapper">
+      <div class="command-strip" role="tablist" aria-label="Command examples">
+        <span class="command-group-label">Commands</span>
+        {commandScenarios.map((scenario, index) => (
+          <button 
+            type="button"
+            class:list={{ "command-tab": true, "is-active": index === 0 }}
+            role="tab"
+            aria-selected={index === 0 ? "true" : "false"}
+            aria-controls={`panel-${scenario.id}`}
+            id={`tab-${scenario.id}`}
+            data-command-tab={scenario.id}
+          >
+            {scenario.label}
+          </button>
+        ))}
+        <span class="command-group-divider"></span>
+        <span class="command-group-label command-group-label--orchestrators">Orchestrators</span>
+        {orchestratorScenarios.map((scenario) => (
+          <button 
+            type="button"
+            class:list={{ "command-tab command-tab--orchestrator": true }}
+            role="tab"
+            aria-selected="false"
+            aria-controls={`panel-${scenario.id}`}
+            id={`tab-${scenario.id}`}
+            data-command-tab={scenario.id}
+          >
+            {scenario.label}
+          </button>
+        ))}
+      </div>
     </div>
 
     <!-- All scenario panels -->
@@ -375,19 +541,13 @@ const scenarios: CommandScenario[] = [
             </div>
             <div class="session-terminal__meta">
               <span class="session-terminal__status" data-status-dot></span>
-              <span data-session-time>0.0s</span>
             </div>
           </div>
 
           <!-- Subagent Session -->
-          <div class="subagent-session">
+          <div class="subagent-session" data-subagent-session>
             <!-- Subagent Header -->
             <div class="subagent-session__header">
-              <div class="subagent-session__nav">
-                <span>Parent <kbd>↑</kbd></span>
-                <span>Prev <kbd>←</kbd></span>
-                <span>Next <kbd>→</kbd></span>
-              </div>
               <div class="subagent-session__title">
                 <span class="subagent-session__indicator"></span>
                 <span class="subagent-session__agent">{scenario.agentName}</span>
@@ -421,15 +581,28 @@ const scenarios: CommandScenario[] = [
                       <div class="tool-calls-block">
                         <div class="tool-calls-block__header">
                           <span class="tool-calls-block__icon">▸</span>
-                          <span class="tool-calls-block__label">Explored</span>
-                          <span class="tool-calls-block__count">{step.toolCalls.length} reads, 1 search</span>
+                          <span class="tool-calls-block__label">
+                            {step.toolCalls.some(t => t.tool === 'dispatch') ? 'Delegated' : 'Explored'}
+                          </span>
+                          <span class="tool-calls-block__count">
+                            {step.toolCalls.length} {step.toolCalls.some(t => t.tool === 'dispatch') ? 'subagents' : 'reads, 1 search'}
+                          </span>
                         </div>
                         <div class="tool-calls-block__list">
                           {step.toolCalls.map((tool) => (
-                            <div class="tool-call" data-tool-status={tool.status}>
-                              <span class="tool-call__arrow">→</span>
-                              <span class="tool-call__name">{tool.tool}</span>
-                              <span class="tool-call__args">{tool.args}</span>
+                            <div class:list={{ "tool-call": true, "tool-call--dispatch": tool.tool === 'dispatch' }} data-tool-status={tool.status}>
+                              {tool.tool === 'dispatch' ? (
+                                <>
+                                  <span class="tool-call__indicator"></span>
+                                  <span class="tool-call__dispatch-cmd">{tool.args}</span>
+                                </>
+                              ) : (
+                                <>
+                                  <span class="tool-call__arrow">→</span>
+                                  <span class="tool-call__name">{tool.tool}</span>
+                                  <span class="tool-call__args">{tool.args}</span>
+                                </>
+                              )}
                             </div>
                           ))}
                         </div>
@@ -448,6 +621,13 @@ const scenarios: CommandScenario[] = [
               </div>
             </div>
           </div>
+
+          <!-- Parent Session Output -->
+          <div class="parent-output" data-parent-output>
+            {scenario.steps.find(s => s.phase === 'output')?.output?.map((line) => (
+              <p class="parent-output__line">{line}</p>
+            ))}
+          </div>
         </div>
       </div>
     ))}
@@ -479,30 +659,32 @@ const scenarios: CommandScenario[] = [
     const steps = panel.querySelectorAll('[data-step]');
     const statusDot = panel.querySelector('[data-status-dot]') as HTMLElement;
     const toolCount = panel.querySelector('[data-tool-count]') as HTMLElement;
-    const sessionTime = panel.querySelector('[data-session-time]') as HTMLElement;
+    const parentOutput = panel.querySelector('[data-parent-output]') as HTMLElement;
+    const subagentSession = panel.querySelector('[data-subagent-session]') as HTMLElement;
     
     // Reset all animations
     steps.forEach(step => step.classList.remove('is-visible'));
     panel.querySelectorAll('.tool-call').forEach(tool => tool.classList.remove('is-visible'));
     panel.querySelectorAll('.output-block__line').forEach(line => line.classList.remove('is-visible'));
+    panel.querySelectorAll('.parent-output__line').forEach(line => line.classList.remove('is-visible'));
     if (statusDot) statusDot.classList.remove('is-complete');
+    if (parentOutput) parentOutput.classList.remove('is-visible');
+    if (subagentSession) subagentSession.classList.remove('is-visible');
     
     let toolcallCounter = 0;
-    let startTime = Date.now();
-    
-    function updateTimer() {
-      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-      if (sessionTime) sessionTime.textContent = `${elapsed}s`;
-    }
-    
-    const timerInterval = window.setInterval(updateTimer, 100);
     
     // Type the command
     if (typewriterEl) {
       await typewriter(typewriterEl, typewriterEl.textContent || '', 35);
     }
     
-    // Animate through each step
+    // Delay then show subagent session
+    await new Promise(resolve => setTimeout(resolve, 600));
+    if (subagentSession) {
+      subagentSession.classList.add('is-visible');
+    }
+    
+    // Animate through each subagent step
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i] as HTMLElement;
       await new Promise(resolve => setTimeout(resolve, 350));
@@ -528,7 +710,17 @@ const scenarios: CommandScenario[] = [
       }
     }
     
-    clearInterval(timerInterval);
+    // Show parent output after subagent completes
+    await new Promise(resolve => setTimeout(resolve, 400));
+    if (parentOutput) {
+      parentOutput.classList.add('is-visible');
+      const lines = parentOutput.querySelectorAll('.parent-output__line');
+      for (let j = 0; j < lines.length; j++) {
+        await new Promise(resolve => setTimeout(resolve, 150));
+        lines[j].classList.add('is-visible');
+      }
+    }
+    
     if (statusDot) statusDot.classList.add('is-complete');
   }
 
@@ -673,18 +865,42 @@ const scenarios: CommandScenario[] = [
     z-index: 1;
   }
 
+  /* Tab Groups */
+  .tab-groups {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 1rem;
+    margin-bottom: 0.75rem;
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    color: var(--muted);
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+  }
+
+  .tab-group-divider {
+    width: 1px;
+    height: 1rem;
+    background: rgba(125, 166, 196, 0.3);
+  }
+
   /* Tabs */
   .command-strip {
     display: flex;
     flex-wrap: nowrap;
     gap: 0.6rem;
     justify-content: center;
-    margin-bottom: 1.5rem;
-    padding: 0 1rem;
+    margin-bottom: 0.75rem;
+    padding: 0.25rem 1rem;
     overflow-x: auto;
     scrollbar-width: none;
   }
 
+  .command-strip--orchestrators {
+    margin-bottom: 1.5rem;
+  }
+
   .command-strip::-webkit-scrollbar {
     display: none;
   }
@@ -716,6 +932,18 @@ const scenarios: CommandScenario[] = [
     color: var(--text);
   }
 
+  .command-tab--orchestrator {
+    border-color: rgba(95, 158, 197, 0.25);
+    background: rgba(95, 158, 197, 0.1);
+  }
+
+  .command-tab--orchestrator:hover,
+  .command-tab--orchestrator.is-active {
+    border-color: rgba(95, 158, 197, 0.45);
+    background: rgba(95, 158, 197, 0.18);
+    color: var(--text);
+  }
+
   /* Scenario panels */
   .scenario-panel {
     display: none;
@@ -746,10 +974,38 @@ const scenarios: CommandScenario[] = [
     justify-content: space-between;
     gap: 1rem;
     padding: 1rem 1.2rem;
-    border-bottom: 1px solid rgba(125, 166, 196, 0.1);
     background: rgba(0, 0, 0, 0.3);
   }
 
+  /* Parent Output */
+  .parent-output {
+    padding: 1rem 1.2rem;
+    border-bottom: 1px solid rgba(125, 166, 196, 0.1);
+    background: rgba(0, 0, 0, 0.2);
+    opacity: 0;
+    transition: opacity 0.4s ease;
+  }
+
+  .parent-output.is-visible {
+    opacity: 1;
+  }
+
+  .parent-output__line {
+    margin: 0.4rem 0;
+    color: var(--text);
+    font-family: var(--font-mono);
+    font-size: 0.9rem;
+    line-height: 1.6;
+    opacity: 0;
+    transform: translateY(8px);
+    transition: all 0.35s ease;
+  }
+
+  .parent-output__line.is-visible {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
   .session-terminal__parent-info {
     display: flex;
     align-items: center;
@@ -802,6 +1058,14 @@ const scenarios: CommandScenario[] = [
     border-left: 2px solid rgba(248, 184, 78, 0.3);
     margin: 0.5rem;
     border-radius: 0 0.5rem 0.5rem 0;
+    opacity: 0;
+    transform: translateY(10px);
+    transition: all 0.5s ease;
+  }
+
+  .subagent-session.is-visible {
+    opacity: 1;
+    transform: translateY(0);
   }
 
   .subagent-session__header {
@@ -899,8 +1163,8 @@ const scenarios: CommandScenario[] = [
 
   .thinking-block {
     padding: 0.75rem 1rem;
-    border-left: 2px solid rgba(248, 184, 78, 0.4);
-    background: rgba(248, 184, 78, 0.05);
+    border-left: 2px solid rgba(159, 179, 195, 0.4);
+    background: rgba(159, 179, 195, 0.08);
     border-radius: 0 0.25rem 0.25rem 0;
   }
 
@@ -921,7 +1185,7 @@ const scenarios: CommandScenario[] = [
     position: absolute;
     inset: 0;
     border-radius: 50%;
-    background: var(--accent);
+    background: var(--muted);
     animation: thinkingPulse 1.5s ease-in-out infinite;
   }
 
@@ -931,7 +1195,7 @@ const scenarios: CommandScenario[] = [
   }
 
   .thinking-block__label {
-    color: var(--accent);
+    color: var(--muted);
     font-size: 0.75rem;
     font-weight: 500;
     letter-spacing: 0.05em;
@@ -1014,6 +1278,31 @@ const scenarios: CommandScenario[] = [
     font-size: 0.8rem;
   }
 
+  .tool-call--dispatch {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.5rem 0.75rem;
+    margin: 0.25rem 0;
+    border-left: 2px solid rgba(95, 158, 197, 0.4);
+    background: rgba(95, 158, 197, 0.1);
+    border-radius: 0 0.25rem 0.25rem 0;
+  }
+
+  .tool-call__indicator {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    background: rgba(95, 158, 197, 0.8);
+    animation: subagentPulse 1.5s ease-in-out infinite;
+  }
+
+  .tool-call__dispatch-cmd {
+    color: var(--text);
+    font-family: var(--font-mono);
+    font-size: 0.85rem;
+  }
+
   .output-block {
     margin-top: 0.5rem;
     padding: 0.75rem 1rem;
@@ -1035,11 +1324,7 @@ const scenarios: CommandScenario[] = [
   }
 
   .output-block__line:last-child {
-    color: var(--muted);
-    font-size: 0.85rem;
-    margin-top: 0.75rem;
-    padding-top: 0.5rem;
-    border-top: 1px solid rgba(125, 166, 196, 0.08);
+    color: var(--text);
   }
 
   @media (max-width: 640px) {
diff --git a/packages/web/src/content/docs/docs/adapters/opencode.mdx b/packages/web/src/content/docs/docs/adapters/opencode.mdx
index 91083a8..19355e1 100644
--- a/packages/web/src/content/docs/docs/adapters/opencode.mdx
+++ b/packages/web/src/content/docs/docs/adapters/opencode.mdx
@@ -28,6 +28,13 @@ You can use overrides to:
 - enable or disable agents
 - remap tool names
 - change defaults such as the base branch
+- adjust adapter behavior such as `agentMode` and `subtaskCommandMode`
+
+## Agent model
+
+Most command execution runs on OpenCode's built-in `build` agent.
+
+Kompass also provides the `worker`, `navigator`, `planner`, and `reviewer` agent roles for structured subagent workflows and review-specific execution.
 
 ## Useful OpenCode notes
 
diff --git a/packages/web/src/content/docs/docs/config/overview.mdx b/packages/web/src/content/docs/docs/config/overview.mdx
index 6375916..a92cf90 100644
--- a/packages/web/src/content/docs/docs/config/overview.mdx
+++ b/packages/web/src/content/docs/docs/config/overview.mdx
@@ -1,16 +1,24 @@
 ---
 title: Configuration Overview
-description: Learn how Kompass merges bundled config with a project override and what each section controls.
+description: Learn how Kompass merges bundled config with home and project overrides and what each section controls.
 ---
 
 ## Loading model
 
-Kompass loads:
+Kompass loads configuration in this order:
 
 1. the bundled base config
-2. the first matching project override file
+2. the first matching home-directory override file
+3. the first matching project override file
 
-The project override replaces or augments the bundled configuration depending on the field.
+For both the home directory and the project root, Kompass checks these file names in order:
+
+1. `.opencode/kompass.jsonc`
+2. `.opencode/kompass.json`
+3. `kompass.jsonc`
+4. `kompass.json`
+
+Later layers replace or augment earlier configuration depending on the field.
 
 ## Main sections
 
@@ -25,8 +33,9 @@ Shared render-time guidance, including:
 
 Controls command availability and template overrides.
 
-- `entries.<name>.enabled`
-- `entries.<name>.template`
+- `<name>.enabled`
+- `<name>.template`
+- legacy `enabled` and `templates` fields are still recognized for compatibility
 
 ### `agents`
 
@@ -58,7 +67,10 @@ Shared defaults such as `baseBranch`.
 
 ### `adapters`
 
-Adapter-specific configuration. Today this includes `adapters.opencode.agentMode`.
+Adapter-specific configuration. Today this includes:
+
+- `adapters.opencode.agentMode`
+- `adapters.opencode.subtaskCommandMode`
 
 ## Tool alias example
 
diff --git a/packages/web/src/content/docs/docs/config/schema.mdx b/packages/web/src/content/docs/docs/config/schema.mdx
index d0f604b..ab3766e 100644
--- a/packages/web/src/content/docs/docs/config/schema.mdx
+++ b/packages/web/src/content/docs/docs/config/schema.mdx
@@ -9,6 +9,7 @@ The published schema lives in `kompass.schema.json`.
 
 - default base branch: `main`
 - OpenCode adapter agent mode: `all`
+- OpenCode subtask command mode: `kompass`
 - bundled shared validation guidance is included by default
 
 ## Notable schema types
@@ -48,3 +49,9 @@ Deprecated array fields still exist in the schema for compatibility, but the new
 - `subagent`
 - `primary`
 - `all`
+
+`adapters.opencode.subtaskCommandMode` supports:
+
+- `kompass`
+- `all`
+- `off`
diff --git a/packages/web/src/content/docs/docs/reference/commands/index.mdx b/packages/web/src/content/docs/docs/reference/commands/index.mdx
index e4b5ccb..861faa1 100644
--- a/packages/web/src/content/docs/docs/reference/commands/index.mdx
+++ b/packages/web/src/content/docs/docs/reference/commands/index.mdx
@@ -11,7 +11,7 @@ Kompass ships workflow-oriented commands authored as explicit templates in `pack
 - Development: `/dev`, `/todo`, `/ship`
 - Review: `/review`, `/pr/review`, `/pr/fix`
 - Git: `/commit`, `/commit-and-push`, `/pr/create`
-- Tickets: `/ticket/create`, `/ticket/ask`, `/ticket/dev`, `/ticket/plan`
+- Tickets: `/ticket/create`, `/ticket/ask`, `/ticket/dev`, `/ticket/plan`, `/ticket/plan-and-sync`
 
 ## What makes them different
 
@@ -168,8 +168,16 @@ Implements a ticket by orchestrating development, branching, commit-and-push, an
 
 ### `/ticket/plan`
 
-Creates a scoped implementation plan from a request or ticket and stores that plan in the ticket flow.
+Creates a scoped implementation plan from a request or ticket without modifying ticket state.
 
 - usage: `/ticket/plan <ticket-reference-or-request>`
 - arguments: ticket reference, URL, request text, or planning guidance
+- expected tools: `ticket_load(comments)` when planning from a ticket, light repo reconnaissance tools
+
+### `/ticket/plan-and-sync`
+
+Creates a scoped implementation plan from a request or ticket and stores that plan in the ticket flow.
+
+- usage: `/ticket/plan-and-sync <ticket-reference-or-request>`
+- arguments: ticket reference, URL, request text, or planning guidance
 - expected tools: `ticket_load(comments)` when planning from a ticket, light repo reconnaissance tools, `ticket_sync`
diff --git a/packages/web/src/content/docs/docs/reference/commands/ticket-create.mdx b/packages/web/src/content/docs/docs/reference/commands/ticket-create.mdx
index c126458..a36bbc9 100644
--- a/packages/web/src/content/docs/docs/reference/commands/ticket-create.mdx
+++ b/packages/web/src/content/docs/docs/reference/commands/ticket-create.mdx
@@ -1,24 +1,27 @@
 ---
 title: /ticket/create
-description: Create a structured GitHub issue from a description or completed work summary.
+description: Create a structured GitHub issue from the current change comparison.
 ---
 
 ## Purpose
 
-Use `/ticket/create` to turn a request or work summary into a tracked issue.
+Use `/ticket/create` to turn the current branch or working-tree changes into a tracked issue.
 
 ## Usage
 
 ```text
-/ticket/create <description>
+/ticket/create [base-or-context]
 ```
 
 ## Typical flow
 
-- summarize the request or completed work
+- load the current change comparison
+- stop if there is no work to summarize
 - generate a scoped issue title and body
 - add checklist sections for the work to track
+- create the issue and assign it to the author
 
 ## Common tools
 
+- `changes_load`
 - `ticket_sync`
diff --git a/packages/web/src/content/docs/docs/reference/commands/ticket-plan-and-sync.mdx b/packages/web/src/content/docs/docs/reference/commands/ticket-plan-and-sync.mdx
new file mode 100644
index 0000000..5c27d10
--- /dev/null
+++ b/packages/web/src/content/docs/docs/reference/commands/ticket-plan-and-sync.mdx
@@ -0,0 +1,28 @@
+---
+title: /ticket/plan-and-sync
+description: Create an implementation plan from a ticket or request and sync that plan back to the ticket flow.
+---
+
+## Purpose
+
+Use `/ticket/plan-and-sync` when you want a scoped plan before implementation and you also want that plan captured on the ticket.
+
+## Usage
+
+```text
+/ticket/plan-and-sync <ticket-reference-or-request>
+```
+
+## Typical flow
+
+- load the ticket or request context
+- inspect relevant repository context before finalizing the plan
+- shape the implementation and validation checklist items
+- sync the plan back to the existing ticket or create a new ticket when needed
+
+## Common tools
+
+- `ticket_load`
+- `read`
+- `grep`
+- `ticket_sync`
diff --git a/packages/web/src/content/docs/docs/reference/tools/index.mdx b/packages/web/src/content/docs/docs/reference/tools/index.mdx
index bfa843e..58255eb 100644
--- a/packages/web/src/content/docs/docs/reference/tools/index.mdx
+++ b/packages/web/src/content/docs/docs/reference/tools/index.mdx
@@ -34,7 +34,7 @@ Loads PR metadata, review history, issue comments, and review threads.
 
 Creates, updates, comments on, or reviews a GitHub pull request.
 
-- notable inputs: `title`, `description`, `base`, `head`, `checklists`, `review`, `replies`, `commentBody`
+- notable inputs: `title`, `body`, `description`, `base`, `head`, `assignees`, `checklists`, `draft`, `refUrl`, `commitId`, `review`, `replies`, `commentBody`
 - used by: `/pr/create`, `/pr/review`, `/pr/fix`
 
 ### `ticket_load`
@@ -42,14 +42,14 @@ Creates, updates, comments on, or reviews a GitHub pull request.
 Loads a ticket from GitHub, a file path, or raw text.
 
 - inputs: `source`, `comments`
-- used by: `/ticket/ask`, `/ticket/dev`, `/ticket/plan`, and sometimes `/pr/review`
+- used by: `/ticket/ask`, `/ticket/dev`, `/ticket/plan`, `/ticket/plan-and-sync`, and sometimes `/pr/review`
 
 ### `ticket_sync`
 
 Creates or updates a GitHub issue with checklist support.
 
-- notable inputs: `title`, `description`, `labels`, `assignees`, `checklists`, `refUrl`, `comments`
-- used by: `/ticket/create`, `/ticket/ask`, `/ticket/plan`, and `/pr/create` when ticket auto-creation is needed
+- notable inputs: `title`, `body`, `description`, `labels`, `assignees`, `checklists`, `refUrl`, `comments`
+- used by: `/ticket/create`, `/ticket/ask`, `/ticket/plan-and-sync`, and `/pr/create` when ticket auto-creation is needed
 
 ### `reload`
 
diff --git a/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx b/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx
index 87f08bc..90670dd 100644
--- a/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx
+++ b/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx
@@ -10,11 +10,15 @@ Use one tool surface for PR creation, updates, comments, replies, and formal rev
 ## Notable inputs
 
 - `title`
+- `body`
 - `description`
 - `base`
 - `head`
+- `assignees`
 - `checklists`
 - `draft`
+- `refUrl`
+- `commitId`
 - `review`
 - `replies`
 - `commentBody`
diff --git a/packages/web/src/content/docs/docs/reference/tools/ticket-load.mdx b/packages/web/src/content/docs/docs/reference/tools/ticket-load.mdx
index df15a24..f19f363 100644
--- a/packages/web/src/content/docs/docs/reference/tools/ticket-load.mdx
+++ b/packages/web/src/content/docs/docs/reference/tools/ticket-load.mdx
@@ -17,4 +17,5 @@ Normalize ticket input so planning and implementation flows can start from the s
 - `/ticket/ask`
 - `/ticket/dev`
 - `/ticket/plan`
+- `/ticket/plan-and-sync`
 - `/pr/review` when the PR references a ticket
diff --git a/packages/web/src/content/docs/docs/reference/tools/ticket-sync.mdx b/packages/web/src/content/docs/docs/reference/tools/ticket-sync.mdx
index 3567d94..a5cce69 100644
--- a/packages/web/src/content/docs/docs/reference/tools/ticket-sync.mdx
+++ b/packages/web/src/content/docs/docs/reference/tools/ticket-sync.mdx
@@ -10,6 +10,7 @@ Use one tool surface for issue creation, issue updates, and ticket comments.
 ## Notable inputs
 
 - `title`
+- `body`
 - `description`
 - `labels`
 - `assignees`
@@ -21,4 +22,5 @@ Use one tool surface for issue creation, issue updates, and ticket comments.
 
 - `/ticket/create`
 - `/ticket/ask`
+- `/ticket/plan-and-sync`
 - `/pr/create` when ticket auto-creation is needed
diff --git a/packages/web/src/content/docs/docs/workspace/development.mdx b/packages/web/src/content/docs/docs/workspace/development.mdx
index 1bd7e6c..884a6dd 100644
--- a/packages/web/src/content/docs/docs/workspace/development.mdx
+++ b/packages/web/src/content/docs/docs/workspace/development.mdx
@@ -26,6 +26,7 @@ bun run test
 - keep reusable workflow logic in `packages/core`
 - keep OpenCode-specific wiring in `packages/opencode`
 - do not regenerate generated output unless the producing source changed or regeneration was requested
+- keep runtime definitions, bundled config, schema, docs, and generated output in sync when you change one of those surfaces
 
 ## Publishing direction
 
diff --git a/skills-lock.json b/skills-lock.json
index 865fc4e..9d9a843 100644
--- a/skills-lock.json
+++ b/skills-lock.json
@@ -1,6 +1,11 @@
 {
   "version": 1,
   "skills": {
+    "agent-browser": {
+      "source": "vercel-labs/agent-browser",
+      "sourceType": "github",
+      "computedHash": "1fdc3ae39490000d36b242168c64db00c1654fe1a0e45a1b12e93b38cc21e32c"
+    },
     "frontend-skill": {
       "source": "openai/skills",
       "sourceType": "github",

From 68e5c69368a0dacff18026d99a96e279332686d6 Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 12:23:10 -0300
Subject: [PATCH 6/7] feat: change dev command agent from build to navigator

- Update dev command to use navigator agent instead of build
- Refactor CommandShowcase to use fieldset-based layout
- Update scenario filtering to use agentName instead of ID lists
- Add horizontal scroll and centering for command tabs
---
 packages/core/commands/index.ts               |   2 +-
 packages/opencode/.opencode/commands/dev.md   |   2 +-
 .../web/src/components/CommandShowcase.astro  | 217 ++++++++++++------
 3 files changed, 151 insertions(+), 70 deletions(-)

diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts
index f18751a..0b2656d 100644
--- a/packages/core/commands/index.ts
+++ b/packages/core/commands/index.ts
@@ -33,7 +33,7 @@ export const commandDefinitions: Record<string, CommandDefinition> = {
   },
   dev: {
     description: "Implement a request and create a PR",
-    agent: "build",
+    agent: "navigator",
     templatePath: "commands/dev.md",
   },
   learn: {
diff --git a/packages/opencode/.opencode/commands/dev.md b/packages/opencode/.opencode/commands/dev.md
index c246228..563a940 100644
--- a/packages/opencode/.opencode/commands/dev.md
+++ b/packages/opencode/.opencode/commands/dev.md
@@ -1,6 +1,6 @@
 ---
 description: Implement a request and create a PR
-agent: build
+agent: navigator
 ---
 
 ## Goal
diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index 0494725..b7cfa92 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -157,30 +157,31 @@ const scenarios: CommandScenario[] = [
     id: 'dev',
     label: '/dev',
     command: '/dev implement the approved workflow in packages/core',
-    agentName: 'Worker',
-    task: 'Implement approved plans with validation',
+    agentName: 'Navigator',
+    task: 'Orchestrate implementation with validation and checkpointing',
     steps: [
       {
         id: 'thinking',
         phase: 'thinking',
-        content: 'Implementing workflow — loading ticket context and executing the approved plan. Will edit only relevant files and validate changes as I go.'
+        content: 'Planning implementation — loading ticket context and preparing to delegate tasks to workers. Will coordinate edits and validation checkpoints.'
       },
       {
         id: 'tools',
         phase: 'tool_calls',
         toolCalls: [
           { tool: 'ticket_load', args: '#128', status: 'complete' },
-          { tool: 'apply_patch', args: 'packages/core/commands/pr/review.md', status: 'complete' },
-          { tool: 'bash', args: 'npm run typecheck', status: 'complete' }
+          { tool: 'dispatch', args: '/ticket/plan', status: 'complete' },
+          { tool: 'dispatch', args: '/dev worker', status: 'complete' },
+          { tool: 'dispatch', args: '/commit-and-push', status: 'complete' }
         ]
       },
       {
         id: 'output',
         phase: 'output',
         output: [
-          'Implemented review workflow in packages/core/commands/pr/',
-          'Added navigator coordination and feedback threading',
-          'All validation checks passed successfully'
+          'Planned implementation in coordination with ticket',
+          'Delegated to worker for file edits and validation',
+          'Committed changes and pushed to remote'
         ]
       }
     ]
@@ -472,8 +473,8 @@ const scenarios: CommandScenario[] = [
 ];
 
 // Split scenarios into two groups
-const commandScenarios = scenarios.filter(s => ['ask', 'branch', 'commit', 'commit-and-push', 'dev', 'learn', 'reload', 'review', 'rmslop'].includes(s.id));
-const orchestratorScenarios = scenarios.filter(s => ['pr-create', 'pr-fix', 'pr-review', 'ship', 'todo', 'ticket-plan'].includes(s.id));
+const orchestratorScenarios = scenarios.filter(s => s.agentName === 'Navigator');
+const commandScenarios = scenarios.filter(s => s.agentName !== 'Navigator');
 
 ---
 
@@ -487,38 +488,46 @@ const orchestratorScenarios = scenarios.filter(s => ['pr-create', 'pr-fix', 'pr-
   </div>
 
   <div class="command-showcase__main">
-    <!-- Combined Tab navigation with groups -->
-    <div class="command-strip-wrapper">
-      <div class="command-strip" role="tablist" aria-label="Command examples">
-        <span class="command-group-label">Commands</span>
-        {commandScenarios.map((scenario, index) => (
-          <button 
-            type="button"
-            class:list={{ "command-tab": true, "is-active": index === 0 }}
-            role="tab"
-            aria-selected={index === 0 ? "true" : "false"}
-            aria-controls={`panel-${scenario.id}`}
-            id={`tab-${scenario.id}`}
-            data-command-tab={scenario.id}
-          >
-            {scenario.label}
-          </button>
-        ))}
-        <span class="command-group-divider"></span>
-        <span class="command-group-label command-group-label--orchestrators">Orchestrators</span>
-        {orchestratorScenarios.map((scenario) => (
-          <button 
-            type="button"
-            class:list={{ "command-tab command-tab--orchestrator": true }}
-            role="tab"
-            aria-selected="false"
-            aria-controls={`panel-${scenario.id}`}
-            id={`tab-${scenario.id}`}
-            data-command-tab={scenario.id}
-          >
-            {scenario.label}
-          </button>
-        ))}
+    <!-- Two fieldsets side-by-side, centered, exploding container -->
+    <div class="command-groups-wrapper">
+      <div class="command-groups">
+        <fieldset class="command-group">
+          <legend class="command-group__legend">Commands</legend>
+          <div class="command-group__tabs">
+            {commandScenarios.map((scenario, index) => (
+              <button 
+                type="button"
+                class:list={{ "command-tab": true, "is-active": index === 0 }}
+                role="tab"
+                aria-selected={index === 0 ? "true" : "false"}
+                aria-controls={`panel-${scenario.id}`}
+                id={`tab-${scenario.id}`}
+                data-command-tab={scenario.id}
+              >
+                {scenario.label}
+              </button>
+            ))}
+          </div>
+        </fieldset>
+        
+        <fieldset class="command-group command-group--orchestrators">
+          <legend class="command-group__legend">Orchestrators</legend>
+          <div class="command-group__tabs">
+            {orchestratorScenarios.map((scenario) => (
+              <button 
+                type="button"
+                class:list={{ "command-tab command-tab--orchestrator": true }}
+                role="tab"
+                aria-selected="false"
+                aria-controls={`panel-${scenario.id}`}
+                id={`tab-${scenario.id}`}
+                data-command-tab={scenario.id}
+              >
+                {scenario.label}
+              </button>
+            ))}
+          </div>
+        </fieldset>
       </div>
     </div>
 
@@ -773,10 +782,24 @@ const orchestratorScenarios = scenarios.filter(s => ['pr-create', 'pr-fix', 'pr-
     }
   }
 
+  // Center the scroll position on load
+  function centerScroll() {
+    const wrapper = document.querySelector('.command-groups-wrapper') as HTMLElement;
+    if (wrapper) {
+      const scrollWidth = wrapper.scrollWidth;
+      const clientWidth = wrapper.clientWidth;
+      wrapper.scrollLeft = (scrollWidth - clientWidth) / 2;
+    }
+  }
+
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', initShowcase);
+    document.addEventListener('DOMContentLoaded', () => {
+      initShowcase();
+      centerScroll();
+    });
   } else {
     initShowcase();
+    centerScroll();
   }
 </script>
 
@@ -865,44 +888,81 @@ const orchestratorScenarios = scenarios.filter(s => ['pr-create', 'pr-fix', 'pr-
     z-index: 1;
   }
 
-  /* Tab Groups */
-  .tab-groups {
+  /* Tabs - two fieldsets side-by-side on single line with horizontal scroll */
+  .command-groups-wrapper {
+    position: relative;
+    width: 100vw;
+    left: 50%;
+    right: 50%;
+    margin-left: -50vw;
+    margin-right: -50vw;
+    margin-bottom: 2rem;
+    overflow-x: auto;
+    scrollbar-width: thin;
+    scrollbar-color: rgba(125, 166, 196, 0.2) transparent;
+    scroll-snap-type: x proximity;
+  }
+
+  .command-groups-wrapper::-webkit-scrollbar {
+    height: 6px;
+  }
+
+  .command-groups-wrapper::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  .command-groups-wrapper::-webkit-scrollbar-thumb {
+    background: rgba(125, 166, 196, 0.25);
+    border-radius: 3px;
+  }
+
+  .command-groups {
     display: flex;
-    align-items: center;
+    flex-wrap: nowrap;
     justify-content: center;
+    align-items: flex-start;
     gap: 1rem;
-    margin-bottom: 0.75rem;
+    padding: 1rem 2rem;
+    min-width: min-content;
+  }
+
+  .command-group {
+    margin: 0;
+    padding: 1rem 1.25rem 1.25rem;
+    border: 1px solid rgba(125, 166, 196, 0.2);
+    border-radius: 0.75rem;
+    background: rgba(8, 18, 29, 0.5);
+    flex-shrink: 0;
+    scroll-snap-align: center;
+  }
+
+  .command-group--orchestrators {
+    border-color: rgba(95, 158, 197, 0.25);
+    background: rgba(95, 158, 197, 0.1);
+  }
+
+  .command-group__legend {
+    padding: 0.25rem 0.75rem;
     font-family: var(--font-mono);
-    font-size: 0.75rem;
+    font-size: 0.7rem;
     color: var(--muted);
     text-transform: uppercase;
-    letter-spacing: 0.1em;
+    letter-spacing: 0.08em;
+    background: rgba(125, 166, 196, 0.15);
+    border-radius: 0.25rem;
   }
 
-  .tab-group-divider {
-    width: 1px;
-    height: 1rem;
-    background: rgba(125, 166, 196, 0.3);
+  .command-group--orchestrators .command-group__legend {
+    color: rgba(95, 158, 197, 0.9);
+    background: rgba(95, 158, 197, 0.2);
   }
 
-  /* Tabs */
-  .command-strip {
+  .command-group__tabs {
     display: flex;
     flex-wrap: nowrap;
-    gap: 0.6rem;
+    gap: 0.5rem;
     justify-content: center;
-    margin-bottom: 0.75rem;
-    padding: 0.25rem 1rem;
-    overflow-x: auto;
-    scrollbar-width: none;
-  }
-
-  .command-strip--orchestrators {
-    margin-bottom: 1.5rem;
-  }
-
-  .command-strip::-webkit-scrollbar {
-    display: none;
+    padding-top: 0.5rem;
   }
 
   .command-tab {
@@ -1352,5 +1412,26 @@ const orchestratorScenarios = scenarios.filter(s => ['pr-create', 'pr-fix', 'pr-
       padding: 0.45rem 0.7rem;
       font-size: 0.78rem;
     }
+
+    .command-groups-wrapper {
+      margin-bottom: 1.5rem;
+    }
+
+    .command-groups {
+      padding: 0.75rem 1rem;
+      gap: 0.75rem;
+    }
+
+    .command-group {
+      padding: 0.875rem 1rem 1rem;
+    }
+
+    .command-group__legend {
+      font-size: 0.65rem;
+    }
+
+    .command-group__tabs {
+      gap: 0.4rem;
+    }
   }
 </style>
\ No newline at end of file

From a678674f1f96a31abf832b738bc0312791e45c08 Mon Sep 17 00:00:00 2001
From: dbpolito <danielbpolito@gmail.com>
Date: Thu, 26 Mar 2026 14:09:36 -0300
Subject: [PATCH 7/7] fix: update agent assignments and remove scroll centering
 from showcase

- Update dev command agent assertion from build to navigator in test
- Fix pr-create and pr-fix agent names from Navigator to Build in showcase
- Remove scroll centering logic and scroll-snap CSS from CommandShowcase
---
 .../opencode/test/commands-config.test.ts     |  2 +-
 .../web/src/components/CommandShowcase.astro  | 22 +++----------------
 2 files changed, 4 insertions(+), 20 deletions(-)

diff --git a/packages/opencode/test/commands-config.test.ts b/packages/opencode/test/commands-config.test.ts
index db0f44e..dc6a1ba 100644
--- a/packages/opencode/test/commands-config.test.ts
+++ b/packages/opencode/test/commands-config.test.ts
@@ -68,7 +68,7 @@ describe("applyCommandsConfig", () => {
       assert.equal(cfg.command!["ticket/plan-and-sync"]?.agent, "planner");
       assert.equal(cfg.command!["ask"]?.agent, "build");
       assert.equal(cfg.command!["ticket/ask"]?.agent, "build");
-      assert.equal(cfg.command!["dev"]?.agent, "build");
+      assert.equal(cfg.command!["dev"]?.agent, "navigator");
       assert.equal(cfg.command!["ship"]?.agent, "navigator");
       assert.equal(cfg.command!["todo"]?.agent, "navigator");
       assert.ok(cfg.command!["pr/review"]?.description);
diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro
index b7cfa92..a1483df 100644
--- a/packages/web/src/components/CommandShowcase.astro
+++ b/packages/web/src/components/CommandShowcase.astro
@@ -93,7 +93,7 @@ const scenarios: CommandScenario[] = [
     id: 'pr-create',
     label: '/pr/create',
     command: '/pr/create',
-    agentName: 'Navigator',
+    agentName: 'Build',
     task: 'Summarize branch work and publish a structured PR',
     steps: [
       {
@@ -412,7 +412,7 @@ const scenarios: CommandScenario[] = [
     id: 'pr-fix',
     label: '/pr/fix',
     command: '/pr/fix',
-    agentName: 'Navigator',
+    agentName: 'Build',
     task: 'Fix requested PR changes',
     steps: [
       {
@@ -782,24 +782,10 @@ const commandScenarios = scenarios.filter(s => s.agentName !== 'Navigator');
     }
   }
 
-  // Center the scroll position on load
-  function centerScroll() {
-    const wrapper = document.querySelector('.command-groups-wrapper') as HTMLElement;
-    if (wrapper) {
-      const scrollWidth = wrapper.scrollWidth;
-      const clientWidth = wrapper.clientWidth;
-      wrapper.scrollLeft = (scrollWidth - clientWidth) / 2;
-    }
-  }
-
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', () => {
-      initShowcase();
-      centerScroll();
-    });
+    document.addEventListener('DOMContentLoaded', initShowcase);
   } else {
     initShowcase();
-    centerScroll();
   }
 </script>
 
@@ -900,7 +886,6 @@ const commandScenarios = scenarios.filter(s => s.agentName !== 'Navigator');
     overflow-x: auto;
     scrollbar-width: thin;
     scrollbar-color: rgba(125, 166, 196, 0.2) transparent;
-    scroll-snap-type: x proximity;
   }
 
   .command-groups-wrapper::-webkit-scrollbar {
@@ -933,7 +918,6 @@ const commandScenarios = scenarios.filter(s => s.agentName !== 'Navigator');
     border-radius: 0.75rem;
     background: rgba(8, 18, 29, 0.5);
     flex-shrink: 0;
-    scroll-snap-align: center;
   }
 
   .command-group--orchestrators {