fix(skills): teach the board skill how people find things in the web UI

Asked how to quickly find tasks without leaving their page, the chat agent
had no source describing quick search: it searched for docs, said it did not
know the UI, and told the person to ask in chat instead of naming Cmd/Ctrl+K.
Document the command palette, its search operators, the Search all handoff to
full search, and that the agent cannot drive the person's browser. Add a test
that ties the documented shortcuts to the palette's actual key bindings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

server/src/__tests__/board-skill-ui-guidance.test.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const read = (relPath: string) => readFileSync(path.join(repoRoot, relPath), "utf8");
+
+// Chat agents answer "how do I find X?" from the board skill; without this section they
+// had no source for the web UI's quick search and told people to ask in chat instead.
+describe("paperclip-board skill web UI guidance", () => {
+  const skill = read("skills/paperclip-board/SKILL.md");
+  const palette = read("ui/src/components/CommandPalette.tsx");
+  const section = skill.slice(skill.indexOf("## Finding Things in the Web UI"), skill.indexOf("## Presentation Rules"));
+
+  it("documents the quick-search shortcut the command palette actually binds", () => {
+    expect(section.length).toBeGreaterThan(0);
+    expect(palette).toMatch(/e\.key === "k" && \(e\.metaKey \|\| e\.ctrlKey\)/);
+    expect(section).toContain("**Cmd+K**");
+    expect(section).toContain("**Ctrl+K**");
+  });
+
+  it("documents the handoff to full search and the search route it opens", () => {
+    expect(palette).toMatch(/event\.key === "Enter" && \(event\.metaKey \|\| event\.ctrlKey\)/);
+    expect(palette).toContain("Search all for");
+    expect(section).toContain("**Search all**");
+    expect(section).toContain("Cmd/Ctrl+Enter");
+    expect(read("ui/src/App.tsx")).toContain('<Route path="search"');
+    expect(section).toContain("/{prefix}/search");
+  });
+
+  it("tells the agent it cannot operate the person's browser", () => {
+    expect(section).toMatch(/cannot press keys, focus fields, or open the palette/);
+  });
+
+  it("is discoverable from the skill description", () => {
+    const frontmatter = skill.slice(0, skill.indexOf("\n---", 4));
+    expect(frontmatter).toContain("finding things in the Paperclip web UI");
+  });
+});

skills/paperclip-board/SKILL.md

@@ -3,7 +3,7 @@ name: paperclip-board
 description: >
   Manage a Paperclip company as a board member via chat. Use when the user wants
   onboarding, company or agent management, approvals, task monitoring, cost
-  oversight, or work product review in the Paperclip control plane.
+  oversight, work product review, or help finding things in the Paperclip web UI.
 ---
 
 # Paperclip Board Skill
@@ -558,6 +558,17 @@ curl -sS -X PUT "$PAPERCLIP_API_URL/api/issues/{boardIssueId}/documents/decision
 ```
 2. Also update the local file at `./artifacts/decision-log.md`.
 
+## Finding Things in the Web UI
+
+When someone asks how to find, search for, or jump to tasks, projects, or agents themselves (for example "how do I quickly find X without leaving what I'm doing?"), tell them about quick search before or alongside listing results here:
+
+- **Quick search:** press **Cmd+K** (macOS) or **Ctrl+K** (Windows/Linux) on any board page, or click the search icon at the top of the sidebar. It opens over the current page, so they do not lose their place; Esc closes it.
+- Type words to match tasks, projects, and agents. Search operators narrow the results, for example `status:backlog`, `status:todo`, `assignee:me`, `project:"Launch"`, `label:bug`, `priority:high`, or `updated:>7d`.
+- Choose **Search all** (or press Cmd/Ctrl+Enter) to open the full search page (`/{prefix}/search`). It keeps the typed text and operators as filters and adds comments, documents, and artifacts.
+- Results only include what that person is allowed to see.
+
+You cannot press keys, focus fields, or open the palette in their browser; describe the steps for them to take. You may also offer to list the matching items in chat with links.
+
 ## Presentation Rules
 
 - Use markdown tables for lists (agents, tasks, costs)