@orderful/droid 0.16.1 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @orderful/droid
 
+## 0.17.1
+
+### Patch Changes
+
+- [#90](https://github.com/Orderful/droid/pull/90) [`30abc1c`](https://github.com/Orderful/droid/commit/30abc1cd699a41ca7bbb699586b27246e99762e3) Thanks [@frytyler](https://github.com/frytyler)! - Improve /brain check to delegate to /comments check when available
+
+- [#89](https://github.com/Orderful/droid/pull/89) [`624518e`](https://github.com/Orderful/droid/commit/624518ec2ad0b9ac303ead7ae39684b8db73459e) Thanks [@frytyler](https://github.com/frytyler)! - Improve skill descriptions with "Use when" pattern for better Claude matching
+
+  Updated all skill frontmatter descriptions to follow the official Claude Code pattern:
+  `{What it does}. Use when {scenarios}. User prompts like {examples}.`
+
+  This helps Claude better recognise when to invoke skills based on user intent.
+
+  Bumps tool versions: brain 0.2.1, coach 0.1.1, code-review 0.1.1, comments 0.2.4, droid 0.2.1, project 0.1.3
+
+## 0.17.0
+
+### Minor Changes
+
+- [#86](https://github.com/Orderful/droid/pull/86) [`af57231`](https://github.com/Orderful/droid/commit/af5723101f301dc7d5357558325bd9d6997259f7) Thanks [@frytyler](https://github.com/frytyler)! - Add TUI testing infrastructure with ink-testing-library for component tests and Playwright + ttyd for E2E visual testing
+
 ## 0.16.1
 
 ### Patch Changes

package/bun.lock

@@ -18,6 +18,7 @@
       "devDependencies": {
         "@changesets/changelog-github": "^0.5.2",
         "@changesets/cli": "^2.29.8",
+        "@playwright/test": "^1.57.0",
         "@types/bun": "latest",
         "@types/ink-text-input": "^2.0.5",
         "@types/inquirer": "^9.0.7",
@@ -27,6 +28,7 @@
         "@typescript-eslint/parser": "^8.49.0",
         "esbuild": "^0.27.1",
         "eslint": "^8.57.0",
+        "ink-testing-library": "^4.0.0",
         "prettier": "^3.2.5",
         "typescript": "^5.4.2",
       },
@@ -155,6 +157,8 @@
 
     "@nodelib/fs.walk": ["@nodelib/fs.walk@1.2.8", "", { "dependencies": { "@nodelib/fs.scandir": "2.1.5", "fastq": "^1.6.0" } }, "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg=="],
 
+    "@playwright/test": ["@playwright/test@1.57.0", "", { "dependencies": { "playwright": "1.57.0" }, "bin": { "playwright": "cli.js" } }, "sha512-6TyEnHgd6SArQO8UO2OMTxshln3QMWBtPGrOCgs3wVEmQmwyuNtB10IZMfmYDE0riwNR1cu4q+pPcxMVtaG3TA=="],
+
     "@types/bun": ["@types/bun@1.3.4", "", { "dependencies": { "bun-types": "1.3.4" } }, "sha512-EEPTKXHP+zKGPkhRLv+HI0UEX8/o+65hqARxLy8Ov5rIxMBPNTjeZww00CIihrIQGEQBYg+0roO5qOnS/7boGA=="],
 
     "@types/ink": ["@types/ink@0.5.2", "", { "dependencies": { "@types/node": "*", "@types/prop-types": "*" } }, "sha512-yEuhWTRMXJkIWiaM58c5kuRot5HFccv9kjjgy0fBZG0+tYb+sMBaxHNPVqyZXspGGlmwDOQ1d3BsygWpWlW17w=="],
@@ -341,6 +345,8 @@
 
     "fs.realpath": ["fs.realpath@1.0.0", "", {}, "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw=="],
 
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
     "get-east-asian-width": ["get-east-asian-width@1.4.0", "", {}, "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q=="],
 
     "glob": ["glob@7.2.3", "", { "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", "minimatch": "^3.1.1", "once": "^1.3.0", "path-is-absolute": "^1.0.0" } }, "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q=="],
@@ -379,6 +385,8 @@
 
     "ink-select-input": ["ink-select-input@6.2.0", "", { "dependencies": { "figures": "^6.1.0", "to-rotated": "^1.0.0" }, "peerDependencies": { "ink": ">=5.0.0", "react": ">=18.0.0" } }, "sha512-304fZXxkpYxJ9si5lxRCaX01GNlmPBgOZumXXRnPYbHW/iI31cgQynqk2tRypGLOF1cMIwPUzL2LSm6q4I5rQQ=="],
 
+    "ink-testing-library": ["ink-testing-library@4.0.0", "", { "peerDependencies": { "@types/react": ">=18.0.0" }, "optionalPeers": ["@types/react"] }, "sha512-yF92kj3pmBvk7oKbSq5vEALO//o7Z9Ck/OaLNlkzXNeYdwfpxMQkSowGTFUCS5MSu9bWfSZMewGpp7bFc66D7Q=="],
+
     "ink-text-input": ["ink-text-input@6.0.0", "", { "dependencies": { "chalk": "^5.3.0", "type-fest": "^4.18.2" }, "peerDependencies": { "ink": ">=5", "react": ">=18" } }, "sha512-Fw64n7Yha5deb1rHY137zHTAbSTNelUKuB5Kkk2HACXEtwIHBCf9OH2tP/LQ9fRYTl1F0dZgbW0zPnZk6FA9Lw=="],
 
     "inquirer": ["inquirer@9.3.8", "", { "dependencies": { "@inquirer/external-editor": "^1.0.2", "@inquirer/figures": "^1.0.3", "ansi-escapes": "^4.3.2", "cli-width": "^4.1.0", "mute-stream": "1.0.0", "ora": "^5.4.1", "run-async": "^3.0.0", "rxjs": "^7.8.1", "string-width": "^4.2.3", "strip-ansi": "^6.0.1", "wrap-ansi": "^6.2.0", "yoctocolors-cjs": "^2.1.2" } }, "sha512-pFGGdaHrmRKMh4WoDDSowddgjT1Vkl90atobmTeSmcPGdYiwikch/m/Ef5wRaiamHejtw0cUUMMerzDUXCci2w=="],
@@ -487,6 +495,10 @@
 
     "pify": ["pify@4.0.1", "", {}, "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g=="],
 
+    "playwright": ["playwright@1.57.0", "", { "dependencies": { "playwright-core": "1.57.0" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-ilYQj1s8sr2ppEJ2YVadYBN0Mb3mdo9J0wQ+UuDhzYqURwSoW4n1Xs5vs7ORwgDGmyEh33tRMeS8KhdkMoLXQw=="],
+
+    "playwright-core": ["playwright-core@1.57.0", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-agTcKlMw/mjBWOnD6kFZttAAGHgi/Nw0CZ2o6JqWSbMlI219lAFLZZCyqByTsvVAJq5XA5H8cA6PrvBRpBWEuQ=="],
+
     "prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
 
     "prettier": ["prettier@3.7.4", "", { "bin": "bin/prettier.cjs" }, "sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA=="],

package/dist/commands/tui/components/Badge.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Badge.test.d.ts.map

package/dist/commands/tui/components/Badge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Badge.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/tui/components/Badge.test.tsx"],"names":[],"mappings":""}

package/dist/commands/tui/components/TabBar.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=TabBar.test.d.ts.map

package/dist/commands/tui/components/TabBar.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TabBar.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/tui/components/TabBar.test.tsx"],"names":[],"mappings":""}

package/dist/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.2.0
+version: 0.2.1
 status: beta
 
 includes:

package/dist/tools/brain/skills/brain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain
-description: "Your scratchpad (or brain) - a collaborative space for planning and research. Triggers on phrases like 'let's use our brain', 'open a scratchpad', or 'plan this out' to capture AI output into a persistent doc. Create docs with /brain plan (or /scratchpad plan), /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
+description: "Collaborative scratchpad for planning and research. Use when planning a feature, exploring a problem, or capturing thinking that should persist across sessions. User prompts like 'let's think through', 'open a scratchpad', 'plan this out', 'use our brain'."
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false
@@ -148,7 +148,7 @@ Full procedure: `references/workflows.md` § Adding
 
 **Trigger:** `/brain check`
 
-**TLDR:** Find `> @droid` comments in active doc, address each one with `> @{user_mention}` response (always use blockquote `>`).
+**TLDR:** Invoke `/comments check {active_doc_path}`. If unavailable, find `> @droid` comments and address each (preserve original, add response below).
 
 Full procedure: `references/workflows.md` § Checking
 

package/dist/tools/brain/skills/brain-obsidian/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain-obsidian
-description: "Obsidian extension for brain skill. Adds YAML frontmatter, wikilinks, and folder organization. Requires brain skill. Install this to use brain docs with your Obsidian vault."
+description: "Obsidian extension for brain skill with YAML frontmatter, wikilinks, and PARA folder organization. Use when your brain docs live in an Obsidian vault."
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false

package/dist/tools/coach/TOOL.yaml

@@ -1,6 +1,6 @@
 name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions."
-version: 0.1.0
+version: 0.1.1
 status: beta
 
 includes:

package/dist/tools/coach/skills/coach/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coach
-description: "Learning-mode AI assistance - AI as coach, not crutch. Triggers on phrases like 'help me think through', 'coach me on', 'I want to learn how to', or 'don't just give me the answer'. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions on your code."
+description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix. Use when learning a new codebase, wanting to understand deeply, or building skills to retain. User prompts like 'coach me on', 'help me think through', 'I want to learn how to', 'don't just give me the answer'."
 alwaysApply: false
 allowed-tools: Read, Grep, Glob
 ---

package/dist/tools/code-review/TOOL.yaml

@@ -1,6 +1,6 @@
 name: code-review
 description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring."
-version: 0.1.0
+version: 0.1.1
 status: alpha
 
 includes:

package/dist/tools/code-review/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files. Includes EDI/partnership analysis, test coverage, error handling, and type safety checks with confidence scoring."
+description: "Comprehensive code review using specialized agents. Use when reviewing PRs, checking staged changes, or analysing code quality. User prompts like 'review this PR', 'check my changes', 'review before I commit'."
 globs:
   - "**/*"
 alwaysApply: false

package/dist/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.2.3
+version: 0.2.4
 status: beta
 
 includes:

package/dist/tools/comments/skills/comments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comments
-description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
+description: "Inline conversations using @droid/@user markers in any file. Use when leaving async questions in code or having discussion that should stay near the code. User prompts like 'check for comments', 'address the @droid markers', 'clean up resolved comments'."
 globs:
   - "**/*"
 alwaysApply: false

package/dist/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
 description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.2.0
+version: 0.2.1
 status: beta
 
 # System tool - always stays current regardless of auto-update settings

package/dist/tools/droid/skills/droid/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: droid
-description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
+description: "Core droid meta-skill for updates and tool discovery. Use when checking for droid updates or discovering available tools. User prompts like 'any droid updates?', 'what tools do I have?', 'is droid up to date?'."
 globs:
   - "**/*"
 alwaysApply: false

package/dist/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.1.2
+version: 0.1.3
 status: beta
 
 includes:

package/dist/tools/project/skills/project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project
-description: "Manage project context files for persistent AI memory across sessions. Load project context before working (/project {name}), update with new learnings (/project update), or create new projects (/project create). Use when working on multi-session features, refactors, or any work that benefits from accumulated context."
+description: "Persistent project context for AI memory across sessions. Use when working on multi-session features, refactors, or any work that benefits from accumulated context. User prompts like 'load the project', 'update project context', 'what's the current project?'."
 globs:
   - "**/PROJECT.md"
 alwaysApply: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {
@@ -13,6 +13,9 @@
     "start": "bun dist/bin/droid.js",
     "test": "bun test src/",
     "test:watch": "bun test src/ --watch",
+    "test:tui": "bun test src/commands/tui/",
+    "test:e2e": "playwright test",
+    "screenshot": "bun scripts/screenshot-tui.ts",
     "lint": "eslint src --ext .ts,.tsx",
     "format": "prettier --write 'src/**/*.ts'",
     "changeset": "changeset",
@@ -54,6 +57,7 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
+    "@playwright/test": "^1.57.0",
     "@types/bun": "latest",
     "@types/ink-text-input": "^2.0.5",
     "@types/inquirer": "^9.0.7",
@@ -63,6 +67,7 @@
     "@typescript-eslint/parser": "^8.49.0",
     "esbuild": "^0.27.1",
     "eslint": "^8.57.0",
+    "ink-testing-library": "^4.0.0",
     "prettier": "^3.2.5",
     "typescript": "^5.4.2"
   }

package/playwright.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  timeout: 30000,
+  expect: {
+    timeout: 5000,
+  },
+  fullyParallel: false, // ttyd can only serve one session at a time
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1, // Single worker since ttyd serves one session
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:7681',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  outputDir: 'tests/screenshots',
+});

package/scripts/screenshot-tui.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+/**
+ * Take a screenshot of the TUI at a specific state
+ *
+ * Usage:
+ *   bun scripts/screenshot-tui.ts                     # Screenshot welcome screen
+ *   bun scripts/screenshot-tui.ts enter               # Screenshot after pressing enter
+ *   bun scripts/screenshot-tui.ts enter right         # Screenshot Settings tab
+ *   bun scripts/screenshot-tui.ts -o my-screenshot    # Custom output name
+ *
+ * Actions:
+ *   enter, right, left, up, down, escape, tab
+ *   wait:500  (wait 500ms)
+ *   type:hello (type "hello")
+ */
+
+import { chromium } from 'playwright';
+import { spawn, type ChildProcess } from 'child_process';
+import { join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+
+const SCREENSHOTS_DIR = 'tests/screenshots';
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse output name
+  let outputName = 'screenshot';
+  const outputIndex = args.indexOf('-o');
+  if (outputIndex !== -1 && args[outputIndex + 1]) {
+    outputName = args[outputIndex + 1];
+    args.splice(outputIndex, 2);
+  }
+
+  // Remaining args are actions
+  const actions = args.length > 0 ? args : [];
+
+  // Ensure screenshots directory exists
+  if (!existsSync(SCREENSHOTS_DIR)) {
+    mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+  }
+
+  // Start ttyd
+  console.log('Starting ttyd...');
+  const distPath = join(process.cwd(), 'dist/bin/droid.js');
+
+  if (!existsSync(distPath)) {
+    console.error('Error: dist/bin/droid.js not found. Run `bun run build` first.');
+    process.exit(1);
+  }
+
+  const ttyd: ChildProcess = spawn('ttyd', ['-W', '-p', '7681', 'node', distPath], {
+    stdio: 'ignore',
+    detached: true,
+  });
+
+  // Wait for ttyd to start
+  await new Promise((r) => setTimeout(r, 2000));
+
+  try {
+    console.log('Launching browser...');
+    const browser = await chromium.launch();
+    const page = await browser.newPage();
+
+    await page.goto('http://localhost:7681');
+    await page.waitForSelector('.xterm-screen', { timeout: 10000 });
+
+    // Wait for initial render
+    await page.waitForTimeout(1000);
+
+    // Focus the terminal - click the screen first, then focus the textarea
+    await page.click('.xterm-screen');
+    await page.waitForTimeout(100);
+
+    const textarea = page.locator('textarea.xterm-helper-textarea');
+    if ((await textarea.count()) > 0) {
+      await textarea.click();
+      await page.waitForTimeout(100);
+    }
+
+    // Execute actions
+    for (const action of actions) {
+      console.log(`  Action: ${action}`);
+
+      if (action.startsWith('wait:')) {
+        const ms = parseInt(action.slice(5), 10);
+        await page.waitForTimeout(ms);
+      } else if (action.startsWith('type:')) {
+        const text = action.slice(5);
+        await page.keyboard.type(text);
+      } else {
+        // Key press
+        const keyMap: Record<string, string> = {
+          enter: 'Enter',
+          right: 'ArrowRight',
+          left: 'ArrowLeft',
+          up: 'ArrowUp',
+          down: 'ArrowDown',
+          escape: 'Escape',
+          esc: 'Escape',
+          tab: 'Tab',
+        };
+        const key = keyMap[action.toLowerCase()] || action;
+        await page.keyboard.press(key);
+        await page.waitForTimeout(200);
+      }
+    }
+
+    // Wait for final render
+    await page.waitForTimeout(300);
+
+    // Take screenshot
+    const outputPath = `${SCREENSHOTS_DIR}/${outputName}.png`;
+    await page.screenshot({ path: outputPath });
+    console.log(`Screenshot saved: ${outputPath}`);
+
+    await browser.close();
+  } finally {
+    ttyd.kill();
+  }
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/src/commands/tui/components/Badge.test.tsx

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'bun:test';
+import { render } from 'ink-testing-library';
+import { Badge, ComponentBadges } from './Badge';
+import type { ToolManifest } from '../../../lib/types';
+
+describe('Badge', () => {
+  it('renders with default label from type', () => {
+    const { lastFrame } = render(<Badge type="skill" />);
+    expect(lastFrame()).toContain('Skill');
+  });
+
+  it('renders with custom label', () => {
+    const { lastFrame } = render(<Badge type="command" label="Custom" />);
+    expect(lastFrame()).toContain('Custom');
+  });
+
+  it('renders dimmed style', () => {
+    const { lastFrame } = render(<Badge type="agent" dimmed />);
+    expect(lastFrame()).toContain('Agent');
+  });
+
+  it('renders selected style with leading space', () => {
+    const { lastFrame } = render(<Badge type="skill" isSelected />);
+    // Selected badges have space padding - at minimum leading space
+    expect(lastFrame()).toContain(' Skill');
+  });
+
+  it('renders all component types', () => {
+    const types = ['skill', 'command', 'agent'] as const;
+    for (const type of types) {
+      const { lastFrame } = render(<Badge type={type} />);
+      expect(lastFrame()).toContain(type.charAt(0).toUpperCase() + type.slice(1));
+    }
+  });
+});
+
+describe('ComponentBadges', () => {
+  const mockTool: ToolManifest = {
+    name: 'test-tool',
+    version: '1.0.0',
+    description: 'A test tool',
+    includes: {
+      skills: [
+        { name: 'skill1', required: true },
+        { name: 'skill2', required: false },
+      ],
+      commands: ['cmd1'],
+      agents: [],
+    },
+  };
+
+  it('renders badges for skills and commands', () => {
+    const { lastFrame } = render(<ComponentBadges tool={mockTool} />);
+    expect(lastFrame()).toContain('2 skills');
+    expect(lastFrame()).toContain('1 cmd');
+  });
+
+  it('does not render agent badge when no agents', () => {
+    const { lastFrame } = render(<ComponentBadges tool={mockTool} />);
+    expect(lastFrame()).not.toContain('agent');
+  });
+
+  it('renders singular form for single item', () => {
+    const singleSkillTool: ToolManifest = {
+      ...mockTool,
+      includes: { skills: [{ name: 'skill1', required: true }], commands: [], agents: [] },
+    };
+    const { lastFrame } = render(<ComponentBadges tool={singleSkillTool} />);
+    expect(lastFrame()).toContain('1 skill');
+    expect(lastFrame()).not.toContain('1 skills');
+  });
+
+  it('renders compact view', () => {
+    const { lastFrame } = render(<ComponentBadges tool={mockTool} compact />);
+    // Compact view shows colored squares, not full labels
+    expect(lastFrame()).not.toContain('skills');
+    expect(lastFrame()).not.toContain('cmd');
+  });
+
+  it('renders all badge types when tool has everything', () => {
+    const fullTool: ToolManifest = {
+      ...mockTool,
+      includes: {
+        skills: [{ name: 's1', required: true }],
+        commands: ['c1'],
+        agents: ['a1'],
+      },
+    };
+    const { lastFrame } = render(<ComponentBadges tool={fullTool} />);
+    expect(lastFrame()).toContain('1 skill');
+    expect(lastFrame()).toContain('1 cmd');
+    expect(lastFrame()).toContain('1 agent');
+  });
+});

package/src/commands/tui/components/TabBar.test.tsx

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'bun:test';
+import { render } from 'ink-testing-library';
+import { TabBar } from './TabBar';
+import type { Tab } from '../types';
+
+describe('TabBar', () => {
+  const tabs: { id: Tab; label: string }[] = [
+    { id: 'tools', label: 'Tools' },
+    { id: 'settings', label: 'Settings' },
+  ];
+
+  it('renders all tabs', () => {
+    const { lastFrame } = render(<TabBar tabs={tabs} activeTab="tools" />);
+    expect(lastFrame()).toContain('Tools');
+    expect(lastFrame()).toContain('Settings');
+  });
+
+  it('highlights the active tab', () => {
+    const { lastFrame } = render(<TabBar tabs={tabs} activeTab="tools" />);
+    // The active tab should be rendered (we can't easily check styling in text output)
+    expect(lastFrame()).toContain('Tools');
+  });
+
+  it('renders with settings tab active', () => {
+    const { lastFrame } = render(<TabBar tabs={tabs} activeTab="settings" />);
+    expect(lastFrame()).toContain('Settings');
+  });
+
+  it('renders empty tabs array', () => {
+    const { lastFrame } = render(<TabBar tabs={[]} activeTab="tools" />);
+    expect(lastFrame()).toBeDefined();
+  });
+
+  it('renders single tab', () => {
+    const singleTab: { id: Tab; label: string }[] = [{ id: 'tools', label: 'Tools' }];
+    const { lastFrame } = render(<TabBar tabs={singleTab} activeTab="tools" />);
+    expect(lastFrame()).toContain('Tools');
+  });
+});

package/src/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.2.0
+version: 0.2.1
 status: beta
 
 includes:

package/src/tools/brain/skills/brain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain
-description: "Your scratchpad (or brain) - a collaborative space for planning and research. Triggers on phrases like 'let's use our brain', 'open a scratchpad', or 'plan this out' to capture AI output into a persistent doc. Create docs with /brain plan (or /scratchpad plan), /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
+description: "Collaborative scratchpad for planning and research. Use when planning a feature, exploring a problem, or capturing thinking that should persist across sessions. User prompts like 'let's think through', 'open a scratchpad', 'plan this out', 'use our brain'."
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false
@@ -148,7 +148,7 @@ Full procedure: `references/workflows.md` § Adding
 
 **Trigger:** `/brain check`
 
-**TLDR:** Find `> @droid` comments in active doc, address each one with `> @{user_mention}` response (always use blockquote `>`).
+**TLDR:** Invoke `/comments check {active_doc_path}`. If unavailable, find `> @droid` comments and address each (preserve original, add response below).
 
 Full procedure: `references/workflows.md` § Checking
 

package/src/tools/brain/skills/brain-obsidian/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain-obsidian
-description: "Obsidian extension for brain skill. Adds YAML frontmatter, wikilinks, and folder organization. Requires brain skill. Install this to use brain docs with your Obsidian vault."
+description: "Obsidian extension for brain skill with YAML frontmatter, wikilinks, and PARA folder organization. Use when your brain docs live in an Obsidian vault."
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false

package/src/tools/coach/TOOL.yaml

@@ -1,6 +1,6 @@
 name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions."
-version: 0.1.0
+version: 0.1.1
 status: beta
 
 includes:

package/src/tools/coach/skills/coach/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coach
-description: "Learning-mode AI assistance - AI as coach, not crutch. Triggers on phrases like 'help me think through', 'coach me on', 'I want to learn how to', or 'don't just give me the answer'. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions on your code."
+description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix. Use when learning a new codebase, wanting to understand deeply, or building skills to retain. User prompts like 'coach me on', 'help me think through', 'I want to learn how to', 'don't just give me the answer'."
 alwaysApply: false
 allowed-tools: Read, Grep, Glob
 ---

package/src/tools/code-review/TOOL.yaml

@@ -1,6 +1,6 @@
 name: code-review
 description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring."
-version: 0.1.0
+version: 0.1.1
 status: alpha
 
 includes:

package/src/tools/code-review/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files. Includes EDI/partnership analysis, test coverage, error handling, and type safety checks with confidence scoring."
+description: "Comprehensive code review using specialized agents. Use when reviewing PRs, checking staged changes, or analysing code quality. User prompts like 'review this PR', 'check my changes', 'review before I commit'."
 globs:
   - "**/*"
 alwaysApply: false

package/src/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.2.3
+version: 0.2.4
 status: beta
 
 includes:

package/src/tools/comments/skills/comments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comments
-description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
+description: "Inline conversations using @droid/@user markers in any file. Use when leaving async questions in code or having discussion that should stay near the code. User prompts like 'check for comments', 'address the @droid markers', 'clean up resolved comments'."
 globs:
   - "**/*"
 alwaysApply: false

package/src/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
 description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.2.0
+version: 0.2.1
 status: beta
 
 # System tool - always stays current regardless of auto-update settings

package/src/tools/droid/skills/droid/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: droid
-description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
+description: "Core droid meta-skill for updates and tool discovery. Use when checking for droid updates or discovering available tools. User prompts like 'any droid updates?', 'what tools do I have?', 'is droid up to date?'."
 globs:
   - "**/*"
 alwaysApply: false

package/src/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.1.2
+version: 0.1.3
 status: beta
 
 includes:

package/src/tools/project/skills/project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project
-description: "Manage project context files for persistent AI memory across sessions. Load project context before working (/project {name}), update with new learnings (/project update), or create new projects (/project create). Use when working on multi-session features, refactors, or any work that benefits from accumulated context."
+description: "Persistent project context for AI memory across sessions. Use when working on multi-session features, refactors, or any work that benefits from accumulated context. User prompts like 'load the project', 'update project context', 'what's the current project?'."
 globs:
   - "**/PROJECT.md"
 alwaysApply: false

package/tests/e2e/tui.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * E2E tests for the droid TUI using ttyd + Playwright
+ *
+ * Prerequisites:
+ * - ttyd installed: `brew install ttyd`
+ * - Build droid: `bun run build`
+ *
+ * These tests start ttyd serving the TUI, then use Playwright
+ * to interact with it and take screenshots for visual verification.
+ */
+
+import { test } from '@playwright/test';
+import { spawn, type ChildProcess } from 'child_process';
+import { join } from 'path';
+
+const distPath = join(process.cwd(), 'dist/bin/droid.js');
+let portCounter = 7681;
+
+// Helper to focus terminal for keyboard input
+async function focusTerminal(page: import('@playwright/test').Page) {
+  await page.click('.xterm-screen');
+  await page.waitForTimeout(100);
+  const textarea = page.locator('textarea.xterm-helper-textarea');
+  if ((await textarea.count()) > 0) {
+    await textarea.click();
+    await page.waitForTimeout(100);
+  }
+}
+
+// Helper to start ttyd on a unique port
+async function startTtyd(): Promise<{ process: ChildProcess; port: number }> {
+  const port = portCounter++;
+  const ttyd = spawn('ttyd', ['-W', '-p', String(port), 'node', distPath], {
+    stdio: 'ignore',
+    detached: true,
+  });
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+  return { process: ttyd, port };
+}
+
+// Run tests serially since they share the same port
+test.describe.configure({ mode: 'serial' });
+
+test.describe('TUI Welcome Flow', () => {
+  let ttyd: { process: ChildProcess; port: number };
+
+  test.beforeAll(async () => {
+    ttyd = await startTtyd();
+  });
+
+  test.afterAll(async () => {
+    ttyd?.process.kill();
+  });
+
+  test('shows welcome screen', async ({ page }) => {
+    await page.goto(`http://localhost:${ttyd.port}`);
+    await page.waitForSelector('.xterm-screen', { timeout: 10000 });
+    await page.waitForTimeout(2000);
+
+    await page.screenshot({ path: 'tests/screenshots/01-welcome.png' });
+  });
+
+  test('navigates past welcome screen', async ({ page }) => {
+    await page.goto(`http://localhost:${ttyd.port}`);
+    await page.waitForSelector('.xterm-screen', { timeout: 10000 });
+    await page.waitForTimeout(1000);
+
+    await focusTerminal(page);
+    await page.keyboard.press('Enter');
+    await page.waitForTimeout(1000);
+
+    await page.screenshot({ path: 'tests/screenshots/02-after-welcome.png' });
+  });
+});
+
+test.describe('TUI Navigation', () => {
+  let ttyd: { process: ChildProcess; port: number };
+
+  test.beforeAll(async () => {
+    ttyd = await startTtyd();
+  });
+
+  test.afterAll(async () => {
+    ttyd?.process.kill();
+  });
+
+  test('shows Tools tab by default', async ({ page }) => {
+    await page.goto(`http://localhost:${ttyd.port}`);
+    await page.waitForSelector('.xterm-screen', { timeout: 10000 });
+    await page.waitForTimeout(2000);
+
+    await focusTerminal(page);
+    await page.keyboard.press('Enter');
+    await page.waitForTimeout(1000);
+
+    await page.screenshot({ path: 'tests/screenshots/03-tools-tab.png' });
+  });
+
+  test('navigates to Settings tab', async ({ page }) => {
+    await page.goto(`http://localhost:${ttyd.port}`);
+    await page.waitForSelector('.xterm-screen', { timeout: 10000 });
+    await page.waitForTimeout(2000);
+
+    await focusTerminal(page);
+    await page.keyboard.press('Enter');
+    await page.waitForTimeout(500);
+    await page.keyboard.press('ArrowRight');
+    await page.waitForTimeout(300);
+
+    await page.screenshot({ path: 'tests/screenshots/04-settings-tab.png' });
+  });
+
+  test('navigates back to Tools tab', async ({ page }) => {
+    await page.goto(`http://localhost:${ttyd.port}`);
+    await page.waitForSelector('.xterm-screen', { timeout: 10000 });
+    await page.waitForTimeout(2000);
+
+    await focusTerminal(page);
+    await page.keyboard.press('Enter');
+    await page.waitForTimeout(500);
+    await page.keyboard.press('ArrowRight');
+    await page.waitForTimeout(300);
+    await page.keyboard.press('ArrowLeft');
+    await page.waitForTimeout(300);
+
+    await page.screenshot({ path: 'tests/screenshots/05-back-to-tools.png' });
+  });
+});