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

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - People use chat with a board agent. The board agent reads the
`paperclip-board` skill.
> - People also ask the agent how to use the web UI. An example is "How
can I quickly find Launch tasks without leaving what I am doing?"
> - The skill does not describe the web UI search. The agent searched
for docs and found none. Then it said that it did not know the UI and
told the person to ask in chat.
> - The correct answer is quick search: Cmd+K or Ctrl+K opens the
command palette over the current page.
> - This pull request adds a short "Finding Things in the Web UI"
section to the board skill.
> - The benefit is that the agent gives the real entry point and
shortcut, and does not claim that it can operate the person's browser.

## Linked Issues or Issue Description

No issue exists. This is the problem description (bug template labels):

**What happened?**
A person asked the board chat agent how to quickly find Launch tasks
without leaving their page. The agent did not mention quick search or
Cmd/Ctrl+K. Its reasoning said that it did not know the exact UI
capabilities. It told the person to ask in chat.

**Steps to reproduce**
1. Open board chat in a company that has a "Launch" project.
2. Ask "How can I quickly find Launch tasks without leaving what I am
doing?"
3. Read the reply. It does not name the quick-search shortcut.

**Expected behavior**
The agent names quick search (Cmd+K on macOS, Ctrl+K on Windows/Linux,
or the sidebar search icon), operators such as `status:backlog`, and
"Search all" for full search. It tells the person to do these steps. It
does not claim to press keys for them.

Found by the chat-feature eval `navigation-preferences.quick-search`
(runner-opencode cell).

## What Changed

- `skills/paperclip-board/SKILL.md`: add a "Finding Things in the Web
UI" section. It describes the Cmd/Ctrl+K command palette, the sidebar
search icon, search operators, the "Search all" and Cmd/Ctrl+Enter
handoff to `/{prefix}/search`, and permission-scoped results. It tells
the agent that it cannot press keys or focus fields in the person's
browser.
- `skills/paperclip-board/SKILL.md`: add "help finding things in the
Paperclip web UI" to the skill description, so agents select the skill
for UI how-to questions.
- `server/src/__tests__/board-skill-ui-guidance.test.ts`: new test. It
checks that the documented shortcuts match the key bindings in
`ui/src/components/CommandPalette.tsx`, that the full-search route
exists, and that the description makes the section discoverable.

## Verification

- `pnpm exec vitest run
server/src/__tests__/board-skill-ui-guidance.test.ts
server/src/__tests__/cli-invocation-safety.test.ts
server/src/__tests__/agent-skills-routes.test.ts
server/src/__tests__/onboarding-seed-route.test.ts
server/src/__tests__/board-claim.test.ts
cli/src/__tests__/managed-agent.test.ts` passes.
- The new test fails on `master`, because the section does not exist
there.
- End-to-end: the change is cherry-picked onto the eval branch
`chat-eval/case-quick-search`, and the
`navigation-preferences.quick-search` chat eval runs on it.

## Risks

- Low risk. This is a documentation change to one skill and one new
test.
- If the palette shortcut or route changes, the new test fails. Then
update the skill and the test together.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude
Code with tool use (shell, file edits, GitHub CLI).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

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

@@ -0,0 +1,53 @@
+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("keeps the overlay promise to the shortcut and describes the sidebar Search item as full search", () => {
+    // The classic sidebar Search item is a link to the full search page, not the overlay.
+    expect(read("ui/src/components/Sidebar.tsx")).toMatch(/<SidebarNavItem to="\/search" label="Search"/);
+    expect(section).toMatch(/sidebar \*\*Search\*\* item[^\n]*opens the full search page/);
+    expect(section).not.toMatch(/search icon[^\n]*opens over the current page/i);
+  });
+
+  it("does not claim operators narrow the quick-search results", () => {
+    // The palette sends only the parsed free text; operators apply after the full-search handoff.
+    expect(palette).toMatch(/issuesApi\.list\(selectedCompanyId!, \{ q: quickSearchQuery, limit: 10/);
+    expect(section).toContain("they do not narrow the quick-search results");
+  });
+
+  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,18 @@ 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. It opens over the current page, so they do not lose their place; Esc closes it.
+- The sidebar **Search** item is different: it opens the full search page, so they leave their current page.
+- Type words to match tasks, projects, and agents. They can also type operators such as `status:backlog`, `status:todo`, `assignee:me`, `project:"Launch"`, `label:bug`, `priority:high`, or `updated:>7d`. These filters take effect on the full search page; they do not narrow the quick-search results.
+- 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)