Add full company search page (#5293)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Operators need to find work, documents, agents, projects, comments,
and activity across a company without jumping through separate surfaces.
> - The existing Command-K flow was useful for fast navigation but not
enough for deeper company-wide discovery.
> - Search also needs company-scoped backend contracts, query cost
controls, and indexed document matching so it stays safe as company data
grows.
> - This pull request adds a full company search API and a dedicated
board search page that Command-K can hand off to.
> - The benefit is a single searchable control-plane surface with richer
result context, recents, highlights, and test coverage across server and
UI behavior.

## What Changed

- Added a company-scoped search endpoint/service with query validation,
rate limiting, text matching, fuzzy title matching, and result typing
shared through `@paperclipai/shared`.
- Added idempotent search migrations for document search indexes and
fuzzy matching support.
- Added the full `/companies/:companyKey/search` UI, search result row
components, highlighted snippets, recent searches, and sidebar/Command-K
handoff.
- Added Storybook coverage for search surfaces and Vitest coverage for
server search behavior, rate limiting, route generation, Command-K
behavior, and the search page.
- Addressed Greptile findings by renaming the no-match SQL helper,
applying search pagination after cross-type merge sorting, and
lazy-initializing the default search service so unrelated route-test
mocks do not need to know about it.
- Merged current `public-gh/master` and renumbered the search migrations
behind upstream `0078_white_darwin`: search indexes are now
`0079_company_search_document_indexes` and fuzzy matching is
`0080_company_search_fuzzystrmatch`.

## Verification

- `git fetch public-gh master`
- `git diff --check public-gh/master...HEAD`
- `git diff --name-only public-gh/master...HEAD | rg '^pnpm-lock\.yaml$'
|| true` produced no output before opening the PR.
- `pnpm run preflight:workspace-links && pnpm exec vitest run
server/src/__tests__/company-search-service.test.ts
server/src/__tests__/company-search-rate-limit-routes.test.ts
ui/src/pages/Search.test.tsx ui/src/components/CommandPalette.test.tsx
ui/src/lib/company-routes.test.ts` passed: 5 files, 25 tests.
- `pnpm --filter @paperclipai/shared typecheck && pnpm --filter
@paperclipai/db typecheck && pnpm --filter @paperclipai/server typecheck
&& pnpm --filter @paperclipai/ui typecheck` passed.
- `pnpm exec vitest run
server/src/__tests__/company-search-service.test.ts
server/src/__tests__/company-search-rate-limit-routes.test.ts && pnpm
--filter @paperclipai/server typecheck` passed after Greptile pagination
fixes.
- `pnpm exec vitest run
server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
server/src/__tests__/company-search-rate-limit-routes.test.ts
server/src/__tests__/company-search-service.test.ts && pnpm --filter
@paperclipai/server typecheck` passed after the CI mock fix.
- After resolving the migration conflict with current
`public-gh/master`: `pnpm --filter @paperclipai/db typecheck && pnpm
exec vitest run server/src/__tests__/company-search-service.test.ts
server/src/__tests__/company-search-rate-limit-routes.test.ts && pnpm
--filter @paperclipai/server typecheck` passed.
- DB migration numbering check passed as part of `@paperclipai/db`
typecheck.
- UI states are covered by the added Storybook stories in
`ui/storybook/stories/search.stories.tsx`.
- GitHub reports the PR merge state as `CLEAN` on head `18e54fa8`.
- GitHub PR checks are green on head `18e54fa8`: policy, verify,
serialized server shards 1/4 through 4/4, e2e, canary dry run, Snyk, and
Greptile Review.

## Risks

- Search ranking and snippets are new user-facing behavior, so reviewers
should check whether result ordering feels right on real company data.
- Search touches broad company data, so company scoping and query
cost/rate-limit behavior should be reviewed carefully.
- The migrations add search indexes/extensions; they are idempotent with
`IF NOT EXISTS` for users who may have applied an earlier branch
migration number.

> ROADMAP.md checked. This PR adds a focused board search surface and
does not duplicate an open roadmap item.

## Model Used

- OpenAI Codex, GPT-5 coding agent, tool-enabled shell/git/GitHub CLI
session with medium reasoning effort. Existing branch commits were
produced across prior agent sessions; this packaging pass verified,
opened the PR, addressed Greptile findings, resolved migration conflicts
after upstream PRs landed, and got PR checks green.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

packages/db/src/migrations/0079_company_search_document_indexes.sql

@@ -0,0 +1,2 @@
+CREATE INDEX IF NOT EXISTS "documents_title_search_idx" ON "documents" USING gin ("title" gin_trgm_ops);--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "documents_latest_body_search_idx" ON "documents" USING gin ("latest_body" gin_trgm_ops);

packages/db/src/migrations/0080_company_search_fuzzystrmatch.sql

@@ -0,0 +1 @@
+CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;

packages/db/src/migrations/meta/_journal.json

@@ -554,6 +554,20 @@
       "when": 1778004024976,
       "tag": "0078_white_darwin",
       "breakpoints": true
+    },
+    {
+      "idx": 79,
+      "version": "7",
+      "when": 1777821410992,
+      "tag": "0079_company_search_document_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 80,
+      "version": "7",
+      "when": 1777849000000,
+      "tag": "0080_company_search_fuzzystrmatch",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/documents.ts

@@ -22,5 +22,7 @@ export const documents = pgTable(
   (table) => ({
     companyUpdatedIdx: index("documents_company_updated_idx").on(table.companyId, table.updatedAt),
     companyCreatedIdx: index("documents_company_created_idx").on(table.companyId, table.createdAt),
+    titleSearchIdx: index("documents_title_search_idx").using("gin", table.title.op("gin_trgm_ops")),
+    bodySearchIdx: index("documents_latest_body_search_idx").using("gin", table.latestBody.op("gin_trgm_ops")),
   }),
 );

packages/shared/src/index.ts

@@ -317,6 +317,13 @@ export type {
   ProjectGoalRef,
   ProjectManagedByPlugin,
   ProjectWorkspace,
+  CompanySearchHighlight,
+  CompanySearchIssueSummary,
+  CompanySearchResponse,
+  CompanySearchResult,
+  CompanySearchResultType,
+  CompanySearchScope,
+  CompanySearchSnippet,
   ExecutionWorkspace,
   ExecutionWorkspaceSummary,
   ExecutionWorkspaceConfig,
@@ -573,6 +580,7 @@ export type {
   QuotaWindow,
   ProviderQuotaResult,
 } from "./types/index.js";
+export { COMPANY_SEARCH_SCOPES } from "./types/index.js";
 export {
   ISSUE_REFERENCE_IDENTIFIER_RE,
   buildIssueReferenceHref,
@@ -697,6 +705,13 @@ export {
   type CreateProjectWorkspace,
   type UpdateProjectWorkspace,
   projectExecutionWorkspacePolicySchema,
+  companySearchQuerySchema,
+  COMPANY_SEARCH_DEFAULT_LIMIT,
+  COMPANY_SEARCH_MAX_LIMIT,
+  COMPANY_SEARCH_MAX_OFFSET,
+  COMPANY_SEARCH_MAX_QUERY_LENGTH,
+  COMPANY_SEARCH_MAX_TOKENS,
+  type CompanySearchQuery,
   createIssueSchema,
   createChildIssueSchema,
   createIssueLabelSchema,

packages/shared/src/types/index.ts

@@ -90,6 +90,16 @@ export type {
 } from "./agent.js";
 export type { AssetImage } from "./asset.js";
 export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectManagedByPlugin, ProjectWorkspace } from "./project.js";
+export type {
+  CompanySearchHighlight,
+  CompanySearchIssueSummary,
+  CompanySearchResponse,
+  CompanySearchResult,
+  CompanySearchResultType,
+  CompanySearchScope,
+  CompanySearchSnippet,
+} from "./search.js";
+export { COMPANY_SEARCH_SCOPES } from "./search.js";
 export type {
   ExecutionWorkspace,
   ExecutionWorkspaceSummary,

packages/shared/src/types/search.ts

@@ -0,0 +1,56 @@
+import type { IssuePriority, IssueStatus } from "../constants.js";
+
+export const COMPANY_SEARCH_SCOPES = ["all", "issues", "comments", "documents", "agents", "projects"] as const;
+export type CompanySearchScope = (typeof COMPANY_SEARCH_SCOPES)[number];
+
+export type CompanySearchResultType = "issue" | "agent" | "project";
+
+export interface CompanySearchHighlight {
+  start: number;
+  end: number;
+}
+
+export interface CompanySearchSnippet {
+  field: string;
+  label: string;
+  text: string;
+  highlights: CompanySearchHighlight[];
+}
+
+export interface CompanySearchIssueSummary {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  priority: IssuePriority;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  projectId: string | null;
+  updatedAt: string;
+}
+
+export interface CompanySearchResult {
+  id: string;
+  type: CompanySearchResultType;
+  score: number;
+  title: string;
+  href: string;
+  matchedFields: string[];
+  sourceLabel: string | null;
+  snippet: string | null;
+  snippets: CompanySearchSnippet[];
+  issue?: CompanySearchIssueSummary;
+  updatedAt: string | null;
+  previewImageUrl: string | null;
+}
+
+export interface CompanySearchResponse {
+  query: string;
+  normalizedQuery: string;
+  scope: CompanySearchScope;
+  limit: number;
+  offset: number;
+  results: CompanySearchResult[];
+  countsByType: Record<CompanySearchResultType, number>;
+  hasMore: boolean;
+}

packages/shared/src/validators/index.ts

@@ -210,6 +210,16 @@ export {
   type RestoreIssueDocumentRevision,
 } from "./issue.js";
 
+export {
+  COMPANY_SEARCH_DEFAULT_LIMIT,
+  COMPANY_SEARCH_MAX_LIMIT,
+  COMPANY_SEARCH_MAX_OFFSET,
+  COMPANY_SEARCH_MAX_QUERY_LENGTH,
+  COMPANY_SEARCH_MAX_TOKENS,
+  companySearchQuerySchema,
+  type CompanySearchQuery,
+} from "./search.js";
+
 export {
   createIssueTreeHoldSchema,
   issueTreeControlModeSchema,

packages/shared/src/validators/search.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { COMPANY_SEARCH_SCOPES } from "../types/search.js";
+
+export const COMPANY_SEARCH_MAX_QUERY_LENGTH = 200;
+export const COMPANY_SEARCH_MAX_TOKENS = 8;
+export const COMPANY_SEARCH_DEFAULT_LIMIT = 20;
+export const COMPANY_SEARCH_MAX_LIMIT = 50;
+export const COMPANY_SEARCH_MAX_OFFSET = 200;
+
+function firstQueryValue(value: unknown): unknown {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function clampInteger(value: unknown, fallback: number, min: number, max: number) {
+  const raw = firstQueryValue(value);
+  const numeric = typeof raw === "number"
+    ? raw
+    : typeof raw === "string" && raw.trim().length > 0
+      ? Number.parseInt(raw, 10)
+      : Number.NaN;
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(numeric)));
+}
+
+export const companySearchQuerySchema = z.object({
+  q: z.preprocess(firstQueryValue, z.string().optional().default(""))
+    .transform((value) => value.slice(0, COMPANY_SEARCH_MAX_QUERY_LENGTH)),
+  scope: z.preprocess(firstQueryValue, z.enum(COMPANY_SEARCH_SCOPES).catch("all")).optional().default("all"),
+  limit: z.unknown()
+    .optional()
+    .transform((value) => clampInteger(value, COMPANY_SEARCH_DEFAULT_LIMIT, 1, COMPANY_SEARCH_MAX_LIMIT)),
+  offset: z.unknown()
+    .optional()
+    .transform((value) => clampInteger(value, 0, 0, COMPANY_SEARCH_MAX_OFFSET)),
+});
+
+export type CompanySearchQuery = z.infer<typeof companySearchQuerySchema>;

server/src/__tests__/company-search-rate-limit-routes.test.ts

@@ -0,0 +1,53 @@
+import express from "express";
+import request from "supertest";
+import { describe, expect, it, vi } from "vitest";
+import { issueRoutes } from "../routes/issues.js";
+import { createCompanySearchRateLimiter } from "../services/company-search-rate-limit.js";
+import type { CompanySearchQuery, CompanySearchResponse } from "@paperclipai/shared";
+
+function createSearchResponse(query: CompanySearchQuery): CompanySearchResponse {
+  return {
+    query: query.q,
+    normalizedQuery: query.q.trim().toLowerCase(),
+    scope: query.scope,
+    limit: query.limit,
+    offset: query.offset,
+    results: [],
+    countsByType: { issue: 0, agent: 0, project: 0 },
+    hasMore: false,
+  };
+}
+
+describe("company search route rate limiting", () => {
+  it("rejects repeated same-actor search calls before invoking search", async () => {
+    const search = vi.fn(async (_companyId: string, query: CompanySearchQuery) => createSearchResponse(query));
+    const app = express();
+    app.use((req, _res, next) => {
+      req.actor = {
+        type: "agent",
+        agentId: "agent-1",
+        companyId: "company-1",
+        source: "agent_key",
+      };
+      next();
+    });
+    app.use("/api", issueRoutes({} as never, {} as never, {
+      searchService: { search },
+      searchRateLimiter: createCompanySearchRateLimiter({
+        maxRequests: 1,
+        windowMs: 60_000,
+        now: () => 1_000,
+      }),
+    }));
+
+    await request(app).get("/api/companies/company-1/search?q=wizard").expect(200);
+    const limited = await request(app).get("/api/companies/company-1/search?q=wizard").expect(429);
+
+    expect(search).toHaveBeenCalledTimes(1);
+    expect(limited.body).toMatchObject({
+      error: "Search rate limit exceeded",
+      retryAfterSeconds: 60,
+    });
+    expect(limited.headers["retry-after"]).toBe("60");
+  });
+});

server/src/__tests__/company-search-service.test.ts

@@ -0,0 +1,454 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  agents,
+  companies,
+  createDb,
+  documents,
+  issueComments,
+  issueDocuments,
+  issues,
+  projects,
+} from "@paperclipai/db";
+import { companySearchQuerySchema, COMPANY_SEARCH_MAX_QUERY_LENGTH } from "@paperclipai/shared";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import {
+  COMPANY_SEARCH_BRANCH_FETCH_LIMIT,
+  companySearchBranchFetchLimit,
+  companySearchService,
+} from "../services/company-search.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres company search tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describe("company search query validation", () => {
+  it("clamps query length, limit, and offset without rejecting the request", () => {
+    const parsed = companySearchQuerySchema.parse({
+      q: "x".repeat(COMPANY_SEARCH_MAX_QUERY_LENGTH + 50),
+      limit: "500",
+      offset: "9000",
+      scope: "not-a-scope",
+    });
+
+    expect(parsed.q).toHaveLength(COMPANY_SEARCH_MAX_QUERY_LENGTH);
+    expect(parsed.limit).toBe(50);
+    expect(parsed.offset).toBe(200);
+    expect(parsed.scope).toBe("all");
+  });
+
+  it("includes offset in the internal per-branch fetch window", () => {
+    const lowOffset = companySearchQuerySchema.parse({ q: "needle", limit: "50", offset: "0" });
+    const highOffset = companySearchQuerySchema.parse({ q: "needle", limit: "50", offset: "9000" });
+
+    expect(companySearchBranchFetchLimit(lowOffset.limit, lowOffset.offset)).toBe(51);
+    expect(companySearchBranchFetchLimit(highOffset.limit, highOffset.offset)).toBe(COMPANY_SEARCH_BRANCH_FETCH_LIMIT);
+  });
+});
+
+describeEmbeddedPostgres("companySearchService", () => {
+  let db!: ReturnType<typeof createDb>;
+  let svc!: ReturnType<typeof companySearchService>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-search-");
+    db = createDb(tempDb.connectionString);
+    svc = companySearchService(db);
+    await db.execute(sql.raw("CREATE EXTENSION IF NOT EXISTS pg_trgm"));
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issueDocuments);
+    await db.delete(documents);
+    await db.delete(issueComments);
+    await db.delete(issues);
+    await db.delete(projects);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function createCompany(name = "Paperclip") {
+    const companyId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name,
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    return companyId;
+  }
+
+  async function createIssue(companyId: string, values: Partial<typeof issues.$inferInsert> = {}) {
+    const id = values.id ?? randomUUID();
+    await db.insert(issues).values({
+      id,
+      companyId,
+      title: values.title ?? "Search target",
+      description: values.description ?? null,
+      status: values.status ?? "todo",
+      priority: values.priority ?? "medium",
+      identifier: values.identifier ?? null,
+      hiddenAt: values.hiddenAt ?? null,
+      ...values,
+    });
+    return id;
+  }
+
+  async function createAgent(companyId: string, values: Partial<typeof agents.$inferInsert> = {}) {
+    const id = values.id ?? randomUUID();
+    await db.insert(agents).values({
+      id,
+      companyId,
+      name: values.name ?? "Search agent",
+      role: values.role ?? "engineer",
+      title: values.title ?? null,
+      capabilities: values.capabilities ?? null,
+      ...values,
+    });
+    return id;
+  }
+
+  async function createProject(companyId: string, values: Partial<typeof projects.$inferInsert> = {}) {
+    const id = values.id ?? randomUUID();
+    await db.insert(projects).values({
+      id,
+      companyId,
+      name: values.name ?? "Search project",
+      description: values.description ?? null,
+      ...values,
+    });
+    return id;
+  }
+
+  it("ranks exact issue identifiers before weaker title matches", async () => {
+    const companyId = await createCompany();
+    const exactId = await createIssue(companyId, {
+      identifier: "TST-42",
+      title: "Backend endpoint",
+    });
+    await createIssue(companyId, {
+      identifier: "TST-43",
+      title: "TST-42 mentioned in title only",
+    });
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "TST-42" }));
+
+    expect(result.results[0]?.id).toBe(exactId);
+    expect(result.results[0]?.matchedFields).toContain("identifier");
+  });
+
+  it("matches multiple tokens across the same issue thread and returns comment snippets", async () => {
+    const companyId = await createCompany();
+    const issueId = await createIssue(companyId, {
+      identifier: "TST-7",
+      title: "Checkout semantics",
+      description: "Atomic ownership is enforced here.",
+    });
+    await db.insert(issueComments).values({
+      companyId,
+      issueId,
+      body: "The ranking snippet should explain why this thread matched.",
+    });
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "checkout snippet" }));
+    const match = result.results.find((item) => item.id === issueId);
+
+    expect(match).toBeTruthy();
+    expect(match?.matchedFields).toEqual(expect.arrayContaining(["title", "comment"]));
+    expect(match?.snippets.some((snippet) => /snippet/i.test(snippet.text))).toBe(true);
+  });
+
+  it("searches issue documents and returns document metadata for snippets", async () => {
+    const companyId = await createCompany();
+    const issueId = await createIssue(companyId, {
+      identifier: "TST-8",
+      title: "Adapter manager",
+    });
+    const documentId = randomUUID();
+    await db.insert(documents).values({
+      id: documentId,
+      companyId,
+      title: "Hermes Parser Plan",
+      latestBody: "The external adapter parser should be discovered from the plugin package.",
+      format: "markdown",
+    });
+    await db.insert(issueDocuments).values({
+      companyId,
+      issueId,
+      documentId,
+      key: "plan",
+    });
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "Hermes parser", scope: "documents" }));
+
+    expect(result.results).toHaveLength(1);
+    expect(result.results[0]?.id).toBe(issueId);
+    expect(result.results[0]?.matchedFields).toContain("document");
+    expect(result.results[0]?.href).toContain("#document-plan");
+    expect(result.results[0]?.snippet).toMatch(/parser/i);
+  });
+
+  it("excludes hidden issues and other companies' data", async () => {
+    const companyId = await createCompany("Visible Co");
+    const otherCompanyId = await createCompany("Other Co");
+    const visibleId = await createIssue(companyId, {
+      identifier: "VIS-1",
+      title: "Visible needle",
+    });
+    await createIssue(companyId, {
+      identifier: "HID-1",
+      title: "Hidden needle",
+      hiddenAt: new Date(),
+    });
+    await createIssue(otherCompanyId, {
+      identifier: "OTH-1",
+      title: "Other company needle",
+    });
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "needle" }));
+
+    expect(result.results.map((item) => item.id)).toEqual([visibleId]);
+  });
+
+  it("treats bare SQL wildcard characters as literals instead of match-all queries", async () => {
+    const companyId = await createCompany();
+    const issueId = await createIssue(companyId, {
+      identifier: "TST-20",
+      title: "Plain issue target",
+      description: "Plain issue description",
+    });
+    await db.insert(issueComments).values({
+      companyId,
+      issueId,
+      body: "Plain comment body",
+    });
+    const documentId = randomUUID();
+    await db.insert(documents).values({
+      id: documentId,
+      companyId,
+      title: "Plain document",
+      latestBody: "Plain document body",
+      format: "markdown",
+    });
+    await db.insert(issueDocuments).values({
+      companyId,
+      issueId,
+      documentId,
+      key: "plain",
+    });
+    await createAgent(companyId, {
+      name: "Plain Agent",
+      role: "engineer",
+      capabilities: "Plain agent capabilities",
+    });
+    await createProject(companyId, {
+      name: "Plain Project",
+      description: "Plain project description",
+    });
+
+    for (const q of ["%", "_", "\\"]) {
+      const result = await svc.search(companyId, companySearchQuerySchema.parse({ q }));
+      expect(result.results, `q=${q}`).toEqual([]);
+    }
+  });
+
+  it("matches percent characters literally across issue, comment, document, agent, and project results", async () => {
+    const companyId = await createCompany();
+    const issueMatchId = await createIssue(companyId, {
+      identifier: "TST-21",
+      title: "Release 100% checklist",
+    });
+    const issueDecoyId = await createIssue(companyId, {
+      identifier: "TST-22",
+      title: "Release 1000 checklist",
+    });
+    const commentMatchId = await createIssue(companyId, {
+      identifier: "TST-23",
+      title: "Comment literal holder",
+    });
+    const commentDecoyId = await createIssue(companyId, {
+      identifier: "TST-24",
+      title: "Comment decoy holder",
+    });
+    await db.insert(issueComments).values([
+      {
+        companyId,
+        issueId: commentMatchId,
+        body: "QA is 100% confident in this result.",
+      },
+      {
+        companyId,
+        issueId: commentDecoyId,
+        body: "QA is 1000 confident in this result.",
+      },
+    ]);
+    const documentMatchIssueId = await createIssue(companyId, {
+      identifier: "TST-25",
+      title: "Document literal holder",
+    });
+    const documentDecoyIssueId = await createIssue(companyId, {
+      identifier: "TST-26",
+      title: "Document decoy holder",
+    });
+    const documentMatchId = randomUUID();
+    const documentDecoyId = randomUUID();
+    await db.insert(documents).values([
+      {
+        id: documentMatchId,
+        companyId,
+        title: "Literal rollout",
+        latestBody: "Ship 100% complete adapter support.",
+        format: "markdown",
+      },
+      {
+        id: documentDecoyId,
+        companyId,
+        title: "Decoy rollout",
+        latestBody: "Ship 1000 complete adapter support.",
+        format: "markdown",
+      },
+    ]);
+    await db.insert(issueDocuments).values([
+      {
+        companyId,
+        issueId: documentMatchIssueId,
+        documentId: documentMatchId,
+        key: "literal",
+      },
+      {
+        companyId,
+        issueId: documentDecoyIssueId,
+        documentId: documentDecoyId,
+        key: "decoy",
+      },
+    ]);
+    const agentMatchId = await createAgent(companyId, {
+      name: "100% Specialist",
+      role: "engineer",
+    });
+    const agentDecoyId = await createAgent(companyId, {
+      name: "1000 Specialist",
+      role: "engineer",
+    });
+    const projectMatchId = await createProject(companyId, {
+      name: "100% Launch Plan",
+    });
+    const projectDecoyId = await createProject(companyId, {
+      name: "1000 Launch Plan",
+    });
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "100%" }));
+    const ids = result.results.map((row) => row.id);
+
+    expect(ids).toEqual(expect.arrayContaining([
+      issueMatchId,
+      commentMatchId,
+      documentMatchIssueId,
+      agentMatchId,
+      projectMatchId,
+    ]));
+    expect(ids).not.toEqual(expect.arrayContaining([
+      issueDecoyId,
+      commentDecoyId,
+      documentDecoyIssueId,
+      agentDecoyId,
+      projectDecoyId,
+    ]));
+  });
+
+  it("applies offset after merging cross-type result ranking", async () => {
+    const companyId = await createCompany();
+    const base = new Date("2026-01-01T00:00:00.000Z").getTime();
+    const agentIds = await Promise.all([
+      createAgent(companyId, { name: "Needle agent 1", updatedAt: new Date(base + 6_000) }),
+      createAgent(companyId, { name: "Needle agent 2", updatedAt: new Date(base + 5_000) }),
+      createAgent(companyId, { name: "Needle agent 3", updatedAt: new Date(base + 4_000) }),
+    ]);
+    const projectIds = await Promise.all([
+      createProject(companyId, { name: "Needle project 1", updatedAt: new Date(base + 3_000) }),
+      createProject(companyId, { name: "Needle project 2", updatedAt: new Date(base + 2_000) }),
+      createProject(companyId, { name: "Needle project 3", updatedAt: new Date(base + 1_000) }),
+    ]);
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "needle", limit: "2", offset: "2" }));
+
+    expect(result.results.map((row) => row.id)).toEqual([agentIds[2], projectIds[0]]);
+    expect(result.countsByType).toEqual({ issue: 0, agent: 3, project: 3 });
+    expect(result.hasMore).toBe(true);
+  });
+
+  it("escapes underscore and backslash characters in issue phrase and token patterns", async () => {
+    const companyId = await createCompany();
+    const literalId = await createIssue(companyId, {
+      identifier: "TST-27",
+      title: "Literal foo_bar path c:\\tmp",
+    });
+    const decoyId = await createIssue(companyId, {
+      identifier: "TST-28",
+      title: "Decoy fooXbar path c:tmp",
+    });
+
+    for (const q of ["foo_bar", "c:\\tmp"]) {
+      const result = await svc.search(companyId, companySearchQuerySchema.parse({ q, scope: "issues" }));
+      const ids = result.results.map((row) => row.id);
+      expect(ids, `q=${q}`).toContain(literalId);
+      expect(ids, `q=${q}`).not.toContain(decoyId);
+    }
+  });
+
+  it("uses pg_trgm for conservative fuzzy title matches", async () => {
+    const companyId = await createCompany();
+    const issueId = await createIssue(companyId, {
+      identifier: "TST-9",
+      title: "Onboarding wizard polish",
+    });
+
+    const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: "onbordng wizard" }));
+
+    expect(result.results[0]?.id).toBe(issueId);
+    expect(result.results[0]?.matchedFields).toContain("title");
+  });
+
+  it("matches transposition typos against multi-word titles", async () => {
+    const companyId = await createCompany();
+    const searchIssueId = await createIssue(companyId, {
+      identifier: "TST-10",
+      title: "Improve search performance",
+    });
+    const mobileIssueId = await createIssue(companyId, {
+      identifier: "TST-11",
+      title: "Polish mobile navigation",
+    });
+    const otherIssueId = await createIssue(companyId, {
+      identifier: "TST-12",
+      title: "Refactor billing reports",
+    });
+
+    const transpositionCases: Array<{ query: string; expectedId: string; rejected: string }> = [
+      { query: "serach", expectedId: searchIssueId, rejected: otherIssueId },
+      { query: "mibile", expectedId: mobileIssueId, rejected: otherIssueId },
+      { query: "mobail", expectedId: mobileIssueId, rejected: otherIssueId },
+    ];
+
+    for (const { query, expectedId, rejected } of transpositionCases) {
+      const result = await svc.search(companyId, companySearchQuerySchema.parse({ q: query }));
+      const ids = result.results.map((row) => row.id);
+      expect(ids, `query=${query}`).toContain(expectedId);
+      expect(ids, `query=${query} should not match unrelated issue`).not.toContain(rejected);
+    }
+  });
+});

server/src/routes/issues.ts

@@ -9,6 +9,7 @@ import {
   addIssueCommentSchema,
   acceptIssueThreadInteractionSchema,
   cancelIssueThreadInteractionSchema,
+  companySearchQuerySchema,
   createIssueAttachmentMetadataSchema,
   createIssueThreadInteractionSchema,
   createIssueWorkProductSchema,
@@ -32,6 +33,8 @@ import {
   getClosedIsolatedExecutionWorkspaceMessage,
   isClosedIsolatedExecutionWorkspace,
   normalizeIssueIdentifier as normalizeIssueReferenceIdentifier,
+  type CompanySearchQuery,
+  type CompanySearchResponse,
   type ExecutionWorkspace,
   type SuccessfulRunHandoffState,
 } from "@paperclipai/shared";
@@ -44,6 +47,7 @@ import {
   accessService,
   agentService,
   companyService,
+  companySearchService,
   executionWorkspaceService,
   goalService,
   heartbeatService,
@@ -81,6 +85,10 @@ import { feedbackService } from "../services/feedback.js";
 import { instanceSettingsService } from "../services/instance-settings.js";
 import { environmentService } from "../services/environments.js";
 import { redactSensitiveText } from "../redaction.js";
+import {
+  createCompanySearchRateLimiter,
+  type CompanySearchRateLimiter,
+} from "../services/company-search-rate-limit.js";
 import {
   applyIssueExecutionPolicyTransition,
   normalizeIssueExecutionPolicy,
@@ -97,6 +105,9 @@ const updateIssueRouteSchema = updateIssueSchema.extend({
 
 type ParsedExecutionState = NonNullable<ReturnType<typeof parseIssueExecutionState>>;
 type NormalizedExecutionPolicy = NonNullable<ReturnType<typeof normalizeIssueExecutionPolicy>>;
+type CompanySearchService = {
+  search(companyId: string, query: CompanySearchQuery): Promise<CompanySearchResponse>;
+};
 type ActivityIssueRelationSummary = {
   id: string;
   identifier: string | null;
@@ -253,6 +264,23 @@ function summarizeIssueRelationForActivity(relation: {
   };
 }
 
+const defaultCompanySearchRateLimiter = createCompanySearchRateLimiter();
+
+function companySearchRateLimitActor(req: Request, companyId: string) {
+  if (req.actor.type === "agent") {
+    return {
+      companyId,
+      actorType: "agent" as const,
+      actorId: req.actor.agentId ?? req.actor.keyId ?? "unknown-agent",
+    };
+  }
+  return {
+    companyId,
+    actorType: "board" as const,
+    actorId: req.actor.userId ?? req.actor.source ?? "board",
+  };
+}
+
 function summarizeIssueReferenceActivityDetails(input:
   | {
       addedReferencedIssues: ActivityIssueRelationSummary[];
@@ -548,6 +576,8 @@ export function issueRoutes(
         now?: Date;
       }): Promise<unknown>;
     };
+    searchService?: CompanySearchService;
+    searchRateLimiter?: CompanySearchRateLimiter;
     pluginWorkerManager?: PluginWorkerManager;
   } = {},
 ) {
@@ -559,6 +589,12 @@ export function issueRoutes(
   });
   const feedback = feedbackService(db);
   const companiesSvc = companyService(db);
+  let searchSvc = opts.searchService ?? null;
+  const getSearchService = () => {
+    searchSvc ??= companySearchService(db);
+    return searchSvc;
+  };
+  const searchRateLimiter = opts.searchRateLimiter ?? defaultCompanySearchRateLimiter;
   const instanceSettings = instanceSettingsService(db);
   const agentsSvc = agentService(db);
   const projectsSvc = projectService(db);
@@ -1048,6 +1084,25 @@ export function issueRoutes(
     });
   });
 
+  router.get("/companies/:companyId/search", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const query = companySearchQuerySchema.parse(req.query);
+    const rateLimit = searchRateLimiter.consume(companySearchRateLimitActor(req, companyId));
+    res.setHeader("X-RateLimit-Limit", String(rateLimit.limit));
+    res.setHeader("X-RateLimit-Remaining", String(rateLimit.remaining));
+    if (!rateLimit.allowed) {
+      res.setHeader("Retry-After", String(rateLimit.retryAfterSeconds));
+      res.status(429).json({
+        error: "Search rate limit exceeded",
+        retryAfterSeconds: rateLimit.retryAfterSeconds,
+      });
+      return;
+    }
+    const result = await getSearchService().search(companyId, query);
+    res.json(result);
+  });
+
   router.get("/companies/:companyId/issues", async (req, res) => {
     const companyId = req.params.companyId as string;
     assertCompanyAccess(req, companyId);

server/src/services/company-search-rate-limit.ts

@@ -0,0 +1,63 @@
+export const COMPANY_SEARCH_RATE_LIMIT_WINDOW_MS = 60_000;
+export const COMPANY_SEARCH_RATE_LIMIT_MAX_REQUESTS = 60;
+
+export type CompanySearchRateLimitActor = {
+  companyId: string;
+  actorType: "agent" | "board";
+  actorId: string;
+};
+
+export type CompanySearchRateLimitResult = {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  retryAfterSeconds: number;
+};
+
+export type CompanySearchRateLimiter = {
+  consume(actor: CompanySearchRateLimitActor): CompanySearchRateLimitResult;
+};
+
+export function createCompanySearchRateLimiter(options: {
+  windowMs?: number;
+  maxRequests?: number;
+  now?: () => number;
+} = {}): CompanySearchRateLimiter {
+  const windowMs = options.windowMs ?? COMPANY_SEARCH_RATE_LIMIT_WINDOW_MS;
+  const maxRequests = options.maxRequests ?? COMPANY_SEARCH_RATE_LIMIT_MAX_REQUESTS;
+  const now = options.now ?? Date.now;
+  const hitsByKey = new Map<string, number[]>();
+
+  function key(actor: CompanySearchRateLimitActor) {
+    return `${actor.companyId}:${actor.actorType}:${actor.actorId}`;
+  }
+
+  return {
+    consume(actor) {
+      const currentTime = now();
+      const cutoff = currentTime - windowMs;
+      const actorKey = key(actor);
+      const recentHits = (hitsByKey.get(actorKey) ?? []).filter((hit) => hit > cutoff);
+
+      if (recentHits.length >= maxRequests) {
+        const oldestHit = recentHits[0] ?? currentTime;
+        hitsByKey.set(actorKey, recentHits);
+        return {
+          allowed: false,
+          limit: maxRequests,
+          remaining: 0,
+          retryAfterSeconds: Math.max(1, Math.ceil((oldestHit + windowMs - currentTime) / 1000)),
+        };
+      }
+
+      recentHits.push(currentTime);
+      hitsByKey.set(actorKey, recentHits);
+      return {
+        allowed: true,
+        limit: maxRequests,
+        remaining: Math.max(0, maxRequests - recentHits.length),
+        retryAfterSeconds: 0,
+      };
+    },
+  };
+}

server/src/services/company-search.ts

@@ -0,0 +1,696 @@
+import { and, desc, eq, isNull, sql } from "drizzle-orm";
+import type { SQL } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { agents, companies, issues, projects } from "@paperclipai/db";
+import {
+  COMPANY_SEARCH_MAX_LIMIT,
+  COMPANY_SEARCH_MAX_OFFSET,
+  COMPANY_SEARCH_MAX_TOKENS,
+  type CompanySearchIssueSummary,
+  type CompanySearchQuery,
+  type CompanySearchResponse,
+  type CompanySearchResult,
+  type CompanySearchResultType,
+  type CompanySearchScope,
+  type CompanySearchSnippet,
+} from "@paperclipai/shared";
+
+const MIN_TOKEN_LENGTH = 2;
+const MIN_FUZZY_QUERY_LENGTH = 4;
+const MIN_FUZZY_TOKEN_LENGTH = 4;
+// Cap fuzzy edits using the shorter of (query token, title word) so common
+// 4–5 letter English words don't sweep in noise (e.g. "serach" vs "each").
+const FUZZY_PAIR_LONG_LENGTH = 6;
+const FUZZY_PAIR_LONG_MAX_EDITS = 2;
+const FUZZY_PAIR_MEDIUM_LENGTH = 5;
+const FUZZY_PAIR_MEDIUM_MAX_EDITS = 1;
+const FUZZY_PAIR_SHORT_MAX_EDITS = 0;
+const FUZZY_IDENTIFIER_SIMILARITY_THRESHOLD = 0.45;
+const SNIPPET_MAX_CHARS = 240;
+export const COMPANY_SEARCH_BRANCH_FETCH_LIMIT = COMPANY_SEARCH_MAX_OFFSET + COMPANY_SEARCH_MAX_LIMIT + 1;
+
+type IssueSearchRow = {
+  id: string;
+  identifier: string | null;
+  title: string;
+  description: string | null;
+  status: string;
+  priority: string;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  projectId: string | null;
+  updatedAt: Date;
+  score: number | string;
+  matchedFields: string[] | null;
+  commentSnippet: string | null;
+  commentId: string | null;
+  documentSnippet: string | null;
+  documentTitle: string | null;
+  documentKey: string | null;
+};
+
+type SimpleSearchRow = {
+  id: string;
+  title: string;
+  description: string | null;
+  role?: string | null;
+  updatedAt: Date;
+};
+
+function normalizeQuery(query: string) {
+  return query.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
+
+function tokenizeQuery(normalizedQuery: string) {
+  const matches = normalizedQuery.match(/"[^"]+"|[^\s]+/g) ?? [];
+  const tokens: string[] = [];
+  for (const match of matches) {
+    const token = match.replace(/^"|"$/g, "").replace(/^[^\p{L}\p{N}%_\\-]+|[^\p{L}\p{N}%_\\-]+$/gu, "");
+    if (token.length < MIN_TOKEN_LENGTH) continue;
+    if (!tokens.includes(token)) tokens.push(token);
+    if (tokens.length >= COMPANY_SEARCH_MAX_TOKENS) break;
+  }
+  return tokens;
+}
+
+function fuzzyEligibleTokens(tokens: string[]): string[] {
+  return tokens.filter((token) => token.length >= MIN_FUZZY_TOKEN_LENGTH);
+}
+
+function sqlTextArray(values: string[]) {
+  if (values.length === 0) return sql`ARRAY[]::text[]`;
+  return sql`ARRAY[${sql.join(values.map((value) => sql`${value}`), sql`, `)}]::text[]`;
+}
+
+function tokenMatchExpression(textExpression: SQL, tokenArray: SQL) {
+  return sql<boolean>`
+    EXISTS (
+      SELECT 1
+      FROM unnest(${tokenArray}) AS search_token(value)
+      WHERE lower(coalesce(${textExpression}, '')) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+    )
+  `;
+}
+
+function noMatchSql() {
+  return sql<boolean>`false`;
+}
+
+function plainText(value: string | null | undefined) {
+  return (value ?? "")
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/[#>*_~|]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/;
+
+function extractFirstImageUrl(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const match = MARKDOWN_IMAGE_PATTERN.exec(value);
+  return match ? match[1] : null;
+}
+
+function findFirstMatchIndex(value: string, terms: string[]) {
+  const lower = value.toLowerCase();
+  let best = -1;
+  for (const term of terms) {
+    if (term.length === 0) continue;
+    const index = lower.indexOf(term.toLowerCase());
+    if (index >= 0 && (best < 0 || index < best)) best = index;
+  }
+  return best;
+}
+
+function highlightRanges(value: string, terms: string[]) {
+  const lower = value.toLowerCase();
+  const ranges: Array<{ start: number; end: number }> = [];
+  for (const term of terms) {
+    const normalized = term.toLowerCase();
+    if (normalized.length === 0) continue;
+    let index = lower.indexOf(normalized);
+    while (index >= 0) {
+      const next = { start: index, end: index + normalized.length };
+      const overlaps = ranges.some((range) => next.start < range.end && next.end > range.start);
+      if (!overlaps) ranges.push(next);
+      index = lower.indexOf(normalized, index + normalized.length);
+    }
+  }
+  return ranges.sort((left, right) => left.start - right.start);
+}
+
+function createSnippet(field: string, label: string, source: string | null | undefined, terms: string[]): CompanySearchSnippet | null {
+  const text = plainText(source);
+  if (!text) return null;
+  const firstMatch = findFirstMatchIndex(text, terms);
+  const windowStart = firstMatch < 0 ? 0 : Math.max(0, firstMatch - 80);
+  const windowEnd = Math.min(text.length, windowStart + SNIPPET_MAX_CHARS);
+  const prefix = windowStart > 0 ? "..." : "";
+  const suffix = windowEnd < text.length ? "..." : "";
+  const slice = text.slice(windowStart, windowEnd).trim();
+  const snippetText = `${prefix}${slice}${suffix}`;
+  const offset = prefix.length - windowStart;
+  return {
+    field,
+    label,
+    text: snippetText,
+    highlights: highlightRanges(text, terms)
+      .filter((range) => range.end > windowStart && range.start < windowEnd)
+      .map((range) => ({
+        start: Math.max(0, range.start + offset),
+        end: Math.min(snippetText.length, range.end + offset),
+      })),
+  };
+}
+
+function iso(value: Date | string | null | undefined) {
+  if (!value) return null;
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+
+function routePrefix(issuePrefix: string | null | undefined) {
+  return issuePrefix?.trim() || "company";
+}
+
+function issueHref(prefix: string, issue: { id: string; identifier: string | null }, suffix = "") {
+  return `/${prefix}/issues/${encodeURIComponent(issue.identifier ?? issue.id)}${suffix}`;
+}
+
+function matchTerms(normalizedQuery: string, tokens: string[]) {
+  return [normalizedQuery, ...tokens].filter((term, index, terms) => term.length > 0 && terms.indexOf(term) === index);
+}
+
+function makeCounts(results: CompanySearchResult[]) {
+  const counts: Record<CompanySearchResultType, number> = { issue: 0, agent: 0, project: 0 };
+  for (const result of results) counts[result.type] += 1;
+  return counts;
+}
+
+function scopeIncludesIssues(scope: CompanySearchScope) {
+  return scope === "all" || scope === "issues" || scope === "comments" || scope === "documents";
+}
+
+function scopeIncludesAgents(scope: CompanySearchScope) {
+  return scope === "all" || scope === "agents";
+}
+
+function scopeIncludesProjects(scope: CompanySearchScope) {
+  return scope === "all" || scope === "projects";
+}
+
+function issueSearchCondition(scope: CompanySearchScope, input: {
+  issueTextMatch: SQL<boolean>;
+  commentMatch: SQL<boolean>;
+  documentMatch: SQL<boolean>;
+  fuzzyMatch: SQL<boolean>;
+}) {
+  if (scope === "comments") return input.commentMatch;
+  if (scope === "documents") return input.documentMatch;
+  if (scope === "issues") return sql<boolean>`(${input.issueTextMatch} OR ${input.fuzzyMatch})`;
+  return sql<boolean>`(${input.issueTextMatch} OR ${input.commentMatch} OR ${input.documentMatch} OR ${input.fuzzyMatch})`;
+}
+
+function selectPrimarySnippets(row: IssueSearchRow, normalizedQuery: string, tokens: string[]) {
+  const terms = matchTerms(normalizedQuery, tokens);
+  const matchedFields = new Set(row.matchedFields ?? []);
+  const candidates: Array<CompanySearchSnippet | null> = [];
+  if (matchedFields.has("identifier")) {
+    candidates.push(createSnippet("identifier", "Identifier", row.identifier, terms));
+  }
+  if (matchedFields.has("title")) {
+    candidates.push(createSnippet("title", "Title", row.title, terms));
+  }
+  if (matchedFields.has("comment")) {
+    candidates.push(createSnippet("comment", "Comment", row.commentSnippet, terms));
+  }
+  if (matchedFields.has("document")) {
+    candidates.push(createSnippet("document", row.documentTitle || "Document", row.documentSnippet, terms));
+  }
+  if (matchedFields.has("description")) {
+    candidates.push(createSnippet("description", "Description", row.description, terms));
+  }
+  return candidates.filter((snippet): snippet is CompanySearchSnippet => Boolean(snippet)).slice(0, 2);
+}
+
+function issueResult(row: IssueSearchRow, prefix: string, normalizedQuery: string, tokens: string[]): CompanySearchResult {
+  const snippets = selectPrimarySnippets(row, normalizedQuery, tokens);
+  const sourceLabel = snippets[0]?.label ?? null;
+  const documentSuffix = row.documentKey ? `#document-${encodeURIComponent(row.documentKey)}` : "";
+  const commentSuffix = row.commentId ? `#comment-${encodeURIComponent(row.commentId)}` : "";
+  const suffix = row.commentId ? commentSuffix : documentSuffix;
+  const issue: CompanySearchIssueSummary = {
+    id: row.id,
+    identifier: row.identifier,
+    title: row.title,
+    status: row.status as CompanySearchIssueSummary["status"],
+    priority: row.priority as CompanySearchIssueSummary["priority"],
+    assigneeAgentId: row.assigneeAgentId,
+    assigneeUserId: row.assigneeUserId,
+    projectId: row.projectId,
+    updatedAt: iso(row.updatedAt)!,
+  };
+  const previewImageUrl =
+    extractFirstImageUrl(row.description) ??
+    extractFirstImageUrl(row.commentSnippet) ??
+    extractFirstImageUrl(row.documentSnippet);
+  return {
+    id: row.id,
+    type: "issue",
+    score: Number(row.score),
+    title: row.identifier ? `${row.identifier} ${row.title}` : row.title,
+    href: issueHref(prefix, row, suffix),
+    matchedFields: row.matchedFields ?? [],
+    sourceLabel,
+    snippet: snippets[0]?.text ?? null,
+    snippets,
+    issue,
+    updatedAt: issue.updatedAt,
+    previewImageUrl,
+  };
+}
+
+function scoreSimpleRow(row: SimpleSearchRow, normalizedQuery: string, tokens: string[]) {
+  const haystack = [row.title, row.description, row.role].filter(Boolean).join(" ").toLowerCase();
+  let score = haystack.includes(normalizedQuery) ? 90 : 0;
+  for (const token of tokens) {
+    if (haystack.includes(token)) score += 20;
+  }
+  if (row.title.toLowerCase().startsWith(normalizedQuery)) score += 80;
+  return score;
+}
+
+function simpleTextCondition(fields: SQL[], containsPattern: string, tokenArray: SQL) {
+  const phraseConditions = fields.map((field) => sql<boolean>`lower(coalesce(${field}, '')) LIKE ${containsPattern} ESCAPE '\\'`);
+  const tokenConditions = fields.map((field) => tokenMatchExpression(field, tokenArray));
+  return sql<boolean>`(${sql.join([...phraseConditions, ...tokenConditions], sql` OR `)})`;
+}
+
+export function companySearchBranchFetchLimit(limit: number, offset = 0) {
+  const normalizedLimit = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : COMPANY_SEARCH_MAX_LIMIT;
+  const normalizedOffset = Number.isFinite(offset) ? Math.max(0, Math.floor(offset)) : 0;
+  return Math.min(COMPANY_SEARCH_BRANCH_FETCH_LIMIT, normalizedOffset + normalizedLimit + 1);
+}
+
+export function companySearchService(db: Db) {
+  return {
+    search: async (companyId: string, query: CompanySearchQuery): Promise<CompanySearchResponse> => {
+      const normalizedQuery = normalizeQuery(query.q);
+      const tokens = tokenizeQuery(normalizedQuery);
+      const scope = query.scope;
+      const limit = query.limit;
+      const offset = query.offset;
+      const emptyCounts: Record<CompanySearchResultType, number> = { issue: 0, agent: 0, project: 0 };
+      if (normalizedQuery.length === 0) {
+        return {
+          query: query.q,
+          normalizedQuery,
+          scope,
+          limit,
+          offset,
+          results: [],
+          countsByType: emptyCounts,
+          hasMore: false,
+        };
+      }
+
+      const company = await db
+        .select({ issuePrefix: companies.issuePrefix })
+        .from(companies)
+        .where(eq(companies.id, companyId))
+        .then((rows) => rows[0] ?? null);
+      const prefix = routePrefix(company?.issuePrefix);
+      const fetchLimit = companySearchBranchFetchLimit(limit, offset);
+      const escapedTokens = tokens.map(escapeLikePattern);
+      const tokenArray = sqlTextArray(escapedTokens);
+      const fuzzyTokens = fuzzyEligibleTokens(tokens);
+      const fuzzyTokenArray = sqlTextArray(fuzzyTokens);
+      const escapedQuery = escapeLikePattern(normalizedQuery);
+      const containsPattern = `%${escapedQuery}%`;
+      const startsWithPattern = `${escapedQuery}%`;
+      const fuzzyEnabled = normalizedQuery.length >= MIN_FUZZY_QUERY_LENGTH && !/[\\%_]/.test(normalizedQuery);
+      const fuzzyTokensEnabled = fuzzyEnabled && fuzzyTokens.length > 0;
+
+      const titlePhraseMatch = sql<boolean>`lower(${issues.title}) LIKE ${containsPattern} ESCAPE '\\'`;
+      const titleStartsWith = sql<boolean>`lower(${issues.title}) LIKE ${startsWithPattern} ESCAPE '\\'`;
+      const identifierPhraseMatch = sql<boolean>`lower(coalesce(${issues.identifier}, '')) LIKE ${containsPattern} ESCAPE '\\'`;
+      const identifierStartsWith = sql<boolean>`lower(coalesce(${issues.identifier}, '')) LIKE ${startsWithPattern} ESCAPE '\\'`;
+      const descriptionPhraseMatch = sql<boolean>`lower(coalesce(${issues.description}, '')) LIKE ${containsPattern} ESCAPE '\\'`;
+      const titleTokenMatch = tokenMatchExpression(sql`${issues.title}`, tokenArray);
+      const identifierTokenMatch = tokenMatchExpression(sql`${issues.identifier}`, tokenArray);
+      const descriptionTokenMatch = tokenMatchExpression(sql`${issues.description}`, tokenArray);
+      const issueTextMatch = sql<boolean>`
+        ${titlePhraseMatch}
+        OR ${identifierPhraseMatch}
+        OR ${descriptionPhraseMatch}
+        OR ${titleTokenMatch}
+        OR ${identifierTokenMatch}
+        OR ${descriptionTokenMatch}
+      `;
+      const commentMatch = sql<boolean>`
+        EXISTS (
+          SELECT 1
+          FROM issue_comments search_comments
+          WHERE search_comments.company_id = ${companyId}
+            AND search_comments.issue_id = issues.id
+            AND (
+              lower(search_comments.body) LIKE ${containsPattern} ESCAPE '\\'
+              OR ${tokenMatchExpression(sql`search_comments.body`, tokenArray)}
+            )
+        )
+      `;
+      const documentMatch = sql<boolean>`
+        EXISTS (
+          SELECT 1
+          FROM issue_documents search_issue_documents
+          INNER JOIN documents search_documents
+            ON search_documents.id = search_issue_documents.document_id
+          WHERE search_issue_documents.company_id = ${companyId}
+            AND search_documents.company_id = ${companyId}
+            AND search_issue_documents.issue_id = issues.id
+            AND (
+              lower(coalesce(search_documents.title, '')) LIKE ${containsPattern} ESCAPE '\\'
+              OR lower(search_documents.latest_body) LIKE ${containsPattern} ESCAPE '\\'
+              OR ${tokenMatchExpression(sql`search_documents.title`, tokenArray)}
+              OR ${tokenMatchExpression(sql`search_documents.latest_body`, tokenArray)}
+            )
+        )
+      `;
+      // Each query token (length >= MIN_FUZZY_TOKEN_LENGTH) must have at least
+      // one title word within Levenshtein edit distance. This handles typos
+      // like "serach" -> "search" (transposition) and "mibile" -> "mobile"
+      // (substitution) without the trigram noise that drop-character variants
+      // produced (e.g. "serac" matching "service"). Edit budget is gated on
+      // the SHORTER of the two strings so 4–5 letter English words don't get
+      // swept in by lev=2 collisions.
+      const fuzzyMaxEditsExpr = sql.raw(
+        `CASE
+          WHEN least(length(qt.value), length(title_word.value)) >= ${FUZZY_PAIR_LONG_LENGTH} THEN ${FUZZY_PAIR_LONG_MAX_EDITS}
+          WHEN least(length(qt.value), length(title_word.value)) >= ${FUZZY_PAIR_MEDIUM_LENGTH} THEN ${FUZZY_PAIR_MEDIUM_MAX_EDITS}
+          ELSE ${FUZZY_PAIR_SHORT_MAX_EDITS}
+        END`,
+      );
+      const fuzzyMinTitleWordLengthExpr = sql.raw(`${MIN_FUZZY_TOKEN_LENGTH}`);
+      const fuzzyTokenTitleMatch = fuzzyTokensEnabled
+        ? sql<boolean>`
+          coalesce((
+            SELECT bool_and(
+              EXISTS (
+                SELECT 1
+                FROM regexp_split_to_table(lower(${issues.title}), '[^a-z0-9]+') AS title_word(value)
+                WHERE length(title_word.value) >= ${fuzzyMinTitleWordLengthExpr}
+                  AND levenshtein_less_equal(qt.value, title_word.value, ${fuzzyMaxEditsExpr}) <= ${fuzzyMaxEditsExpr}
+              )
+            )
+            FROM unnest(${fuzzyTokenArray}) AS qt(value)
+          ), false)
+        `
+        : noMatchSql();
+      const fuzzyIdentifierMatch = fuzzyEnabled
+        ? sql<boolean>`similarity(lower(coalesce(${issues.identifier}, '')), ${normalizedQuery}) >= ${FUZZY_IDENTIFIER_SIMILARITY_THRESHOLD}`
+        : noMatchSql();
+      const fuzzyMatch = sql<boolean>`(${fuzzyTokenTitleMatch} OR ${fuzzyIdentifierMatch})`;
+      const tokenCoverage = sql<number>`
+        (
+          SELECT count(*)::int
+          FROM unnest(${tokenArray}) AS search_token(value)
+          WHERE lower(${issues.title}) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+            OR lower(coalesce(${issues.identifier}, '')) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+            OR lower(coalesce(${issues.description}, '')) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+            OR EXISTS (
+              SELECT 1
+              FROM issue_comments coverage_comments
+              WHERE coverage_comments.company_id = ${companyId}
+                AND coverage_comments.issue_id = issues.id
+                AND lower(coverage_comments.body) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+            )
+            OR EXISTS (
+              SELECT 1
+              FROM issue_documents coverage_issue_documents
+              INNER JOIN documents coverage_documents
+                ON coverage_documents.id = coverage_issue_documents.document_id
+              WHERE coverage_issue_documents.company_id = ${companyId}
+                AND coverage_documents.company_id = ${companyId}
+                AND coverage_issue_documents.issue_id = issues.id
+                AND (
+                  lower(coalesce(coverage_documents.title, '')) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+                  OR lower(coverage_documents.latest_body) LIKE '%' || search_token.value || '%' ESCAPE '\\'
+                )
+            )
+        )
+      `;
+      const tokenCount = tokens.length;
+      const allTokensMatch = tokenCount > 0
+        ? sql<boolean>`${tokenCoverage} = ${tokenCount}`
+        : noMatchSql();
+      const score = sql<number>`
+        (
+          CASE WHEN lower(coalesce(${issues.identifier}, '')) = ${normalizedQuery} THEN 1200 ELSE 0 END
+          + CASE WHEN ${identifierStartsWith} THEN 700 ELSE 0 END
+          + CASE WHEN lower(${issues.title}) = ${normalizedQuery} THEN 900 ELSE 0 END
+          + CASE WHEN ${titleStartsWith} THEN 550 ELSE 0 END
+          + CASE WHEN ${titlePhraseMatch} THEN 350 ELSE 0 END
+          + CASE WHEN ${identifierPhraseMatch} THEN 320 ELSE 0 END
+          + CASE WHEN ${commentMatch} THEN 180 ELSE 0 END
+          + CASE WHEN ${documentMatch} THEN 170 ELSE 0 END
+          + CASE WHEN ${descriptionPhraseMatch} THEN 120 ELSE 0 END
+          + CASE WHEN ${allTokensMatch} THEN 260 ELSE 0 END
+          + (${tokenCoverage} * 70)
+          + CASE WHEN ${fuzzyMatch} THEN 110 ELSE 0 END
+          + CASE ${issues.status} WHEN 'done' THEN 0 WHEN 'cancelled' THEN -30 ELSE 20 END
+        )::double precision
+      `;
+      const matchedFields = sql<string[]>`
+        array_remove(ARRAY[
+          CASE WHEN ${identifierPhraseMatch} OR ${identifierTokenMatch} OR ${fuzzyIdentifierMatch} THEN 'identifier' END,
+          CASE WHEN ${titlePhraseMatch} OR ${titleTokenMatch} OR ${fuzzyTokenTitleMatch} THEN 'title' END,
+          CASE WHEN ${descriptionPhraseMatch} OR ${descriptionTokenMatch} THEN 'description' END,
+          CASE WHEN ${commentMatch} THEN 'comment' END,
+          CASE WHEN ${documentMatch} THEN 'document' END
+        ], NULL)::text[]
+      `;
+
+      const issueRows = scopeIncludesIssues(scope)
+        ? await db
+          .select({
+            id: issues.id,
+            identifier: issues.identifier,
+            title: issues.title,
+            description: issues.description,
+            status: issues.status,
+            priority: issues.priority,
+            assigneeAgentId: issues.assigneeAgentId,
+            assigneeUserId: issues.assigneeUserId,
+            projectId: issues.projectId,
+            updatedAt: issues.updatedAt,
+            score,
+            matchedFields,
+            commentSnippet: sql<string | null>`
+              (
+                SELECT search_comments.body
+                FROM issue_comments search_comments
+                WHERE search_comments.company_id = ${companyId}
+                  AND search_comments.issue_id = issues.id
+                  AND (
+                    lower(search_comments.body) LIKE ${containsPattern} ESCAPE '\\'
+                    OR ${tokenMatchExpression(sql`search_comments.body`, tokenArray)}
+                  )
+                ORDER BY
+                  CASE WHEN lower(search_comments.body) LIKE ${containsPattern} ESCAPE '\\' THEN 0 ELSE 1 END,
+                  search_comments.updated_at DESC,
+                  search_comments.id DESC
+                LIMIT 1
+              )
+            `,
+            commentId: sql<string | null>`
+              (
+                SELECT search_comments.id
+                FROM issue_comments search_comments
+                WHERE search_comments.company_id = ${companyId}
+                  AND search_comments.issue_id = issues.id
+                  AND (
+                    lower(search_comments.body) LIKE ${containsPattern} ESCAPE '\\'
+                    OR ${tokenMatchExpression(sql`search_comments.body`, tokenArray)}
+                  )
+                ORDER BY
+                  CASE WHEN lower(search_comments.body) LIKE ${containsPattern} ESCAPE '\\' THEN 0 ELSE 1 END,
+                  search_comments.updated_at DESC,
+                  search_comments.id DESC
+                LIMIT 1
+              )
+            `,
+            documentSnippet: sql<string | null>`
+              (
+                SELECT search_documents.latest_body
+                FROM issue_documents search_issue_documents
+                INNER JOIN documents search_documents
+                  ON search_documents.id = search_issue_documents.document_id
+                WHERE search_issue_documents.company_id = ${companyId}
+                  AND search_documents.company_id = ${companyId}
+                  AND search_issue_documents.issue_id = issues.id
+                  AND (
+                    lower(coalesce(search_documents.title, '')) LIKE ${containsPattern} ESCAPE '\\'
+                    OR lower(search_documents.latest_body) LIKE ${containsPattern} ESCAPE '\\'
+                    OR ${tokenMatchExpression(sql`search_documents.title`, tokenArray)}
+                    OR ${tokenMatchExpression(sql`search_documents.latest_body`, tokenArray)}
+                  )
+                ORDER BY
+                  CASE
+                    WHEN lower(coalesce(search_documents.title, '')) LIKE ${containsPattern} ESCAPE '\\' THEN 0
+                    WHEN lower(search_documents.latest_body) LIKE ${containsPattern} ESCAPE '\\' THEN 1
+                    ELSE 2
+                  END,
+                  search_documents.updated_at DESC,
+                  search_documents.id DESC
+                LIMIT 1
+              )
+            `,
+            documentTitle: sql<string | null>`
+              (
+                SELECT search_documents.title
+                FROM issue_documents search_issue_documents
+                INNER JOIN documents search_documents
+                  ON search_documents.id = search_issue_documents.document_id
+                WHERE search_issue_documents.company_id = ${companyId}
+                  AND search_documents.company_id = ${companyId}
+                  AND search_issue_documents.issue_id = issues.id
+                  AND (
+                    lower(coalesce(search_documents.title, '')) LIKE ${containsPattern} ESCAPE '\\'
+                    OR lower(search_documents.latest_body) LIKE ${containsPattern} ESCAPE '\\'
+                    OR ${tokenMatchExpression(sql`search_documents.title`, tokenArray)}
+                    OR ${tokenMatchExpression(sql`search_documents.latest_body`, tokenArray)}
+                  )
+                ORDER BY search_documents.updated_at DESC, search_documents.id DESC
+                LIMIT 1
+              )
+            `,
+            documentKey: sql<string | null>`
+              (
+                SELECT search_issue_documents.key
+                FROM issue_documents search_issue_documents
+                INNER JOIN documents search_documents
+                  ON search_documents.id = search_issue_documents.document_id
+                WHERE search_issue_documents.company_id = ${companyId}
+                  AND search_documents.company_id = ${companyId}
+                  AND search_issue_documents.issue_id = issues.id
+                  AND (
+                    lower(coalesce(search_documents.title, '')) LIKE ${containsPattern} ESCAPE '\\'
+                    OR lower(search_documents.latest_body) LIKE ${containsPattern} ESCAPE '\\'
+                    OR ${tokenMatchExpression(sql`search_documents.title`, tokenArray)}
+                    OR ${tokenMatchExpression(sql`search_documents.latest_body`, tokenArray)}
+                  )
+                ORDER BY search_documents.updated_at DESC, search_documents.id DESC
+                LIMIT 1
+              )
+            `,
+          })
+          .from(issues)
+          .where(and(
+            eq(issues.companyId, companyId),
+            isNull(issues.hiddenAt),
+            issueSearchCondition(scope, { issueTextMatch, commentMatch, documentMatch, fuzzyMatch }),
+          ))
+          .orderBy(desc(score), desc(issues.updatedAt), desc(issues.id))
+          .limit(fetchLimit)
+        : [];
+
+      const simpleCondition = simpleTextCondition([
+        sql`${agents.name}`,
+        sql`${agents.role}`,
+        sql`${agents.title}`,
+        sql`${agents.capabilities}`,
+      ], containsPattern, tokenArray);
+      const agentRows = scopeIncludesAgents(scope)
+        ? await db
+          .select({
+            id: agents.id,
+            title: agents.name,
+            description: agents.capabilities,
+            role: agents.role,
+            updatedAt: agents.updatedAt,
+          })
+          .from(agents)
+          .where(and(eq(agents.companyId, companyId), simpleCondition))
+          .orderBy(desc(agents.updatedAt), desc(agents.id))
+          .limit(fetchLimit)
+        : [];
+
+      const projectCondition = simpleTextCondition([
+        sql`${projects.name}`,
+        sql`${projects.description}`,
+      ], containsPattern, tokenArray);
+      const projectRows = scopeIncludesProjects(scope)
+        ? await db
+          .select({
+            id: projects.id,
+            title: projects.name,
+            description: projects.description,
+            updatedAt: projects.updatedAt,
+          })
+          .from(projects)
+          .where(and(eq(projects.companyId, companyId), isNull(projects.archivedAt), projectCondition))
+          .orderBy(desc(projects.updatedAt), desc(projects.id))
+          .limit(fetchLimit)
+        : [];
+
+      const results: CompanySearchResult[] = [
+        ...(issueRows as IssueSearchRow[]).map((row) => issueResult(row, prefix, normalizedQuery, tokens)),
+        ...(agentRows as SimpleSearchRow[]).map((row) => {
+          const terms = matchTerms(normalizedQuery, tokens);
+          const snippet = createSnippet("capabilities", "Agent", row.description ?? row.role ?? row.title, terms);
+          return {
+            id: row.id,
+            type: "agent" as const,
+            score: scoreSimpleRow(row, normalizedQuery, tokens),
+            title: row.title,
+            href: `/${prefix}/agents/${encodeURIComponent(row.id)}`,
+            matchedFields: ["agent"],
+            sourceLabel: snippet?.label ?? null,
+            snippet: snippet?.text ?? null,
+            snippets: snippet ? [snippet] : [],
+            updatedAt: iso(row.updatedAt),
+            previewImageUrl: null,
+          };
+        }),
+        ...(projectRows as SimpleSearchRow[]).map((row) => {
+          const terms = matchTerms(normalizedQuery, tokens);
+          const snippet = createSnippet("description", "Project", row.description ?? row.title, terms);
+          return {
+            id: row.id,
+            type: "project" as const,
+            score: scoreSimpleRow(row, normalizedQuery, tokens),
+            title: row.title,
+            href: `/${prefix}/projects/${encodeURIComponent(row.id)}`,
+            matchedFields: ["project"],
+            sourceLabel: snippet?.label ?? null,
+            snippet: snippet?.text ?? null,
+            snippets: snippet ? [snippet] : [],
+            updatedAt: iso(row.updatedAt),
+            previewImageUrl: null,
+          };
+        }),
+      ].sort((left, right) => {
+        if (right.score !== left.score) return right.score - left.score;
+        return (right.updatedAt ?? "").localeCompare(left.updatedAt ?? "");
+      });
+
+      const paged = results.slice(offset, offset + limit);
+      return {
+        query: query.q,
+        normalizedQuery,
+        scope,
+        limit,
+        offset,
+        results: paged,
+        countsByType: makeCounts(results),
+        hasMore: results.length > offset + limit,
+      };
+    },
+  };
+}

server/src/services/index.ts

@@ -1,4 +1,5 @@
 export { companyService } from "./companies.js";
+export { companySearchService } from "./company-search.js";
 export { feedbackService } from "./feedback.js";
 export { companySkillService } from "./company-skills.js";
 export { agentService, deduplicateAgentName } from "./agents.js";

ui/src/App.tsx

@@ -13,6 +13,7 @@ import { ProjectDetail } from "./pages/ProjectDetail";
 import { ProjectWorkspaceDetail } from "./pages/ProjectWorkspaceDetail";
 import { Workspaces } from "./pages/Workspaces";
 import { Issues } from "./pages/Issues";
+import { Search } from "./pages/Search";
 import { IssueDetail } from "./pages/IssueDetail";
 import { IssueChatLongThreadPerf } from "./pages/IssueChatLongThreadPerf";
 import { Routines } from "./pages/Routines";
@@ -95,6 +96,7 @@ function boardRoutes() {
       <Route path="projects/:projectId/budget" element={<ProjectDetail />} />
       <Route path="workspaces" element={<Workspaces />} />
       <Route path="issues" element={<Issues />} />
+      <Route path="search" element={<Search />} />
       <Route path="issues/all" element={<Navigate to="/issues" replace />} />
       <Route path="issues/active" element={<Navigate to="/issues" replace />} />
       <Route path="issues/backlog" element={<Navigate to="/issues" replace />} />

ui/src/api/search.ts

@@ -0,0 +1,23 @@
+import type { CompanySearchResponse, CompanySearchScope } from "@paperclipai/shared";
+import { api } from "./client";
+
+export interface CompanySearchParams {
+  q: string;
+  scope?: CompanySearchScope;
+  limit?: number;
+  offset?: number;
+}
+
+export const searchApi = {
+  search: (companyId: string, params: CompanySearchParams) => {
+    const search = new URLSearchParams();
+    search.set("q", params.q);
+    if (params.scope) search.set("scope", params.scope);
+    if (params.limit !== undefined) search.set("limit", String(params.limit));
+    if (params.offset !== undefined) search.set("offset", String(params.offset));
+    const qs = search.toString();
+    return api.get<CompanySearchResponse>(
+      `/companies/${companyId}/search${qs ? `?${qs}` : ""}`,
+    );
+  },
+};

ui/src/components/CommandPalette.test.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 
 import { act } from "react";
-import type { ReactNode } from "react";
+import type { KeyboardEventHandler, ReactNode } from "react";
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -46,8 +46,12 @@ vi.mock("../context/SidebarContext", () => ({
   useSidebar: () => sidebarState,
 }));
 
+const navigateState = vi.hoisted(() => ({
+  navigate: vi.fn(),
+}));
+
 vi.mock("@/lib/router", () => ({
-  useNavigate: () => vi.fn(),
+  useNavigate: () => navigateState.navigate,
 }));
 
 vi.mock("../api/issues", () => ({
@@ -73,15 +77,18 @@ vi.mock("@/components/ui/command", () => ({
   CommandInput: ({
     value,
     onValueChange,
+    onKeyDown,
   }: {
     value: string;
     onValueChange: (value: string) => void;
+    onKeyDown?: KeyboardEventHandler<HTMLInputElement>;
   }) => (
     <div>
       <input
         aria-label="Command search"
         value={value}
         onChange={(event) => onValueChange(event.currentTarget.value)}
+        onKeyDown={onKeyDown}
       />
       <button type="button" aria-label="Set query" onClick={() => onValueChange("pull/3303")} />
     </div>
@@ -89,10 +96,16 @@ vi.mock("@/components/ui/command", () => ({
   CommandItem: ({
     children,
     onSelect,
+    "data-testid": testId,
   }: {
     children: ReactNode;
     onSelect?: () => void;
-  }) => <button onClick={onSelect}>{children}</button>,
+    "data-testid"?: string;
+  }) => (
+    <button data-testid={testId} onClick={onSelect}>
+      {children}
+    </button>
+  ),
   CommandList: ({ children }: { children: ReactNode }) => <div>{children}</div>,
   CommandSeparator: () => <hr />,
 }));
@@ -153,6 +166,7 @@ describe("CommandPalette", () => {
     mockIssuesApi.list.mockReset();
     mockAgentsApi.list.mockReset();
     mockProjectsApi.list.mockReset();
+    navigateState.navigate.mockReset();
     mockIssuesApi.list.mockResolvedValue([]);
     mockAgentsApi.list.mockResolvedValue([]);
     mockProjectsApi.list.mockResolvedValue([]);
@@ -188,4 +202,78 @@ describe("CommandPalette", () => {
       root.unmount();
     });
   });
+
+  it("offers a Search-all command when the query is non-empty and routes Enter to /search when no issues match", async () => {
+    mockIssuesApi.list.mockResolvedValue([]);
+    const { root } = renderWithQueryClient(<CommandPalette />, container);
+
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "k", metaKey: true, bubbles: true }));
+    });
+
+    const input = container.querySelector('input[aria-label="Command search"]') as HTMLInputElement;
+    expect(input).not.toBeNull();
+
+    act(() => {
+      const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!;
+      nativeSetter.call(input, "auth flake");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    await waitForAssertion(() => {
+      const searchAllButton = container.querySelector(
+        'button[data-testid="command-search-all"]',
+      ) as HTMLButtonElement | null;
+      expect(searchAllButton).not.toBeNull();
+      expect(searchAllButton!.textContent).toContain("auth flake");
+    });
+
+    act(() => {
+      input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+
+    await waitForAssertion(() => {
+      expect(navigateState.navigate).toHaveBeenCalledWith("/search?q=auth%20flake");
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("navigates to /search when the user clicks the Search-all command", async () => {
+    mockIssuesApi.list.mockResolvedValue([]);
+    const { root } = renderWithQueryClient(<CommandPalette />, container);
+
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "k", metaKey: true, bubbles: true }));
+    });
+
+    const input = container.querySelector('input[aria-label="Command search"]') as HTMLInputElement;
+    act(() => {
+      const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!;
+      nativeSetter.call(input, "deflake");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    let searchAllButton: HTMLButtonElement | null = null;
+    await waitForAssertion(() => {
+      searchAllButton = container.querySelector(
+        'button[data-testid="command-search-all"]',
+      ) as HTMLButtonElement | null;
+      expect(searchAllButton).not.toBeNull();
+    });
+
+    act(() => {
+      searchAllButton!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    await waitForAssertion(() => {
+      expect(navigateState.navigate).toHaveBeenCalledWith("/search?q=deflake");
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
 });

ui/src/components/CommandPalette.tsx

@@ -28,10 +28,18 @@ import {
   History,
   SquarePen,
   Plus,
+  Search,
 } from "lucide-react";
 import { Identity } from "./Identity";
 import { agentUrl, projectUrl } from "../lib/utils";
 
+const SEARCH_ALL_VALUE = "__paperclip-search-all__";
+
+export function buildFullSearchPath(query: string) {
+  const trimmed = query.trim();
+  return trimmed.length === 0 ? "/search" : `/search?q=${encodeURIComponent(trimmed)}`;
+}
+
 export function CommandPalette() {
   const [open, setOpen] = useState(false);
   const [query, setQuery] = useState("");
@@ -90,6 +98,10 @@ export function CommandPalette() {
     navigate(path);
   }
 
+  function goFullSearch() {
+    go(buildFullSearchPath(searchQuery));
+  }
+
   const agentName = (id: string | null) => {
     if (!id) return null;
     return agents.find((a) => a.id === id)?.name ?? null;
@@ -100,6 +112,9 @@ export function CommandPalette() {
     [issues, searchedIssues, searchQuery],
   );
 
+  const showSearchAll = searchQuery.length > 0;
+  const showEmptyHint = showSearchAll && visibleIssues.length === 0;
+
   return (
     <CommandDialog open={open} onOpenChange={(v) => {
         setOpen(v);
@@ -109,9 +124,47 @@ export function CommandPalette() {
         placeholder="Search issues, agents, projects..."
         value={query}
         onValueChange={setQuery}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" && showEmptyHint) {
+            event.preventDefault();
+            goFullSearch();
+          }
+        }}
       />
       <CommandList>
-        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandEmpty>
+          {showSearchAll ? (
+            <span>
+              No quick issue matches. Press{" "}
+              <kbd className="rounded border border-border bg-muted px-1 py-0.5 text-[10px]">↵</kbd>{" "}
+              to <span className="font-medium">search all</span> or keep typing to refine.
+            </span>
+          ) : (
+            "No results found."
+          )}
+        </CommandEmpty>
+
+        {showSearchAll ? (
+          <CommandGroup heading="Search">
+            <CommandItem
+              value={`${SEARCH_ALL_VALUE} ${searchQuery}`}
+              onSelect={goFullSearch}
+              className="bg-accent/40 border border-accent data-[selected=true]:bg-accent/60"
+              data-testid="command-search-all"
+            >
+              <Search className="mr-2 h-4 w-4" />
+              <span className="flex-1 truncate">
+                Search all for <span className="font-semibold">&ldquo;{searchQuery}&rdquo;</span>
+              </span>
+              <span className="ml-auto inline-flex items-center gap-1 text-xs text-muted-foreground">
+                <span>open full search</span>
+                <kbd className="rounded border border-border bg-background px-1 py-0.5 text-[10px]">↵</kbd>
+              </span>
+            </CommandItem>
+          </CommandGroup>
+        ) : null}
+
+        {showSearchAll ? <CommandSeparator /> : null}
 
         <CommandGroup heading="Actions">
           <CommandItem

ui/src/components/Sidebar.tsx

@@ -99,6 +99,7 @@ export function Sidebar() {
 
         <SidebarSection label="Work">
           <SidebarNavItem to="/issues" label="Issues" icon={CircleDot} />
+          <SidebarNavItem to="/search" label="Search" icon={Search} />
           <SidebarNavItem to="/routines" label="Routines" icon={Repeat} />
           <SidebarNavItem to="/goals" label="Goals" icon={Target} />
           {showWorkspacesLink ? (

ui/src/components/search/HighlightedText.tsx

@@ -0,0 +1,68 @@
+import type { CompanySearchHighlight } from "@paperclipai/shared";
+import { cn } from "@/lib/utils";
+
+export interface HighlightedTextProps {
+  text: string;
+  highlights?: readonly CompanySearchHighlight[] | null;
+  className?: string;
+  markClassName?: string;
+}
+
+function clampedRanges(text: string, highlights: readonly CompanySearchHighlight[]) {
+  const result: Array<{ start: number; end: number }> = [];
+  for (const range of highlights) {
+    const start = Math.max(0, Math.min(text.length, range.start));
+    const end = Math.max(start, Math.min(text.length, range.end));
+    if (end <= start) continue;
+    result.push({ start, end });
+  }
+  result.sort((a, b) => a.start - b.start);
+  const merged: Array<{ start: number; end: number }> = [];
+  for (const range of result) {
+    const last = merged[merged.length - 1];
+    if (last && range.start <= last.end) {
+      last.end = Math.max(last.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+export function HighlightedText({ text, highlights, className, markClassName }: HighlightedTextProps) {
+  const ranges = highlights && highlights.length > 0 ? clampedRanges(text, highlights) : [];
+  if (ranges.length === 0) {
+    return <span className={className}>{text}</span>;
+  }
+  const segments: Array<{ key: string; text: string; highlight: boolean }> = [];
+  let cursor = 0;
+  ranges.forEach((range, index) => {
+    if (range.start > cursor) {
+      segments.push({ key: `t-${index}`, text: text.slice(cursor, range.start), highlight: false });
+    }
+    segments.push({ key: `m-${index}`, text: text.slice(range.start, range.end), highlight: true });
+    cursor = range.end;
+  });
+  if (cursor < text.length) {
+    segments.push({ key: "t-end", text: text.slice(cursor), highlight: false });
+  }
+  return (
+    <span className={className}>
+      {segments.map((segment) =>
+        segment.highlight ? (
+          <mark
+            key={segment.key}
+            className={cn(
+              "rounded-sm bg-yellow-200/60 px-0.5 text-foreground dark:bg-yellow-300/30",
+              markClassName,
+            )}
+          >
+            {segment.text}
+          </mark>
+        ) : (
+          <span key={segment.key}>{segment.text}</span>
+        ),
+      )}
+    </span>
+  );
+}

ui/src/components/search/MatchSourceChip.tsx

@@ -0,0 +1,46 @@
+import { cn } from "@/lib/utils";
+
+export type MatchSourceChipKind = "title" | "identifier" | "comment" | "document";
+
+const chipStyles: Record<MatchSourceChipKind, string> = {
+  title:
+    "bg-[var(--chip-match-title-bg)] text-[var(--chip-match-title-fg)] border-[var(--chip-match-title-border)]",
+  identifier:
+    "bg-[var(--chip-match-identifier-bg)] text-[var(--chip-match-identifier-fg)] border-[var(--chip-match-identifier-border)]",
+  comment:
+    "bg-[var(--chip-match-comment-bg)] text-[var(--chip-match-comment-fg)] border-[var(--chip-match-comment-border)]",
+  document:
+    "bg-[var(--chip-match-document-bg)] text-[var(--chip-match-document-fg)] border-[var(--chip-match-document-border)]",
+};
+
+const chipLabels: Record<MatchSourceChipKind, string> = {
+  title: "Title",
+  identifier: "Identifier",
+  comment: "Comment",
+  document: "Doc",
+};
+
+export interface MatchSourceChipProps {
+  kind: MatchSourceChipKind;
+  count?: number;
+  label?: string;
+  className?: string;
+}
+
+export function MatchSourceChip({ kind, count, label, className }: MatchSourceChipProps) {
+  const text = label ?? chipLabels[kind];
+  const showCount = typeof count === "number" && count > 1;
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1 rounded-full border px-2 py-px text-[11px] font-medium leading-none whitespace-nowrap",
+        chipStyles[kind],
+        className,
+      )}
+      data-kind={kind}
+    >
+      {text}
+      {showCount ? <span className="opacity-80">×{count}</span> : null}
+    </span>
+  );
+}

ui/src/components/search/SearchResultRow.tsx

@@ -0,0 +1,217 @@
+import { memo, type ComponentType, type SVGProps } from "react";
+import { Bot, FileText, Hexagon, MessageSquare, Quote } from "lucide-react";
+import type { Agent, CompanySearchResult } from "@paperclipai/shared";
+import { Link } from "@/lib/router";
+import { cn } from "@/lib/utils";
+import { StatusIcon } from "../StatusIcon";
+import { Identity } from "../Identity";
+import { HighlightedText, type HighlightedTextProps } from "./HighlightedText";
+
+type SnippetStyle = {
+  Icon: ComponentType<SVGProps<SVGSVGElement>>;
+  label: string;
+};
+
+const SNIPPET_STYLES: Record<string, SnippetStyle> = {
+  comment: { Icon: MessageSquare, label: "Comment" },
+  document: { Icon: FileText, label: "Doc" },
+  description: { Icon: Quote, label: "Description" },
+};
+
+function snippetStyle(field: string, fallbackLabel: string): SnippetStyle {
+  return SNIPPET_STYLES[field] ?? { Icon: Quote, label: fallbackLabel };
+}
+
+function formatRelativeTime(input: string | null): string {
+  if (!input) return "";
+  const value = new Date(input);
+  if (Number.isNaN(value.getTime())) return "";
+  const diffMs = Date.now() - value.getTime();
+  const seconds = Math.round(diffMs / 1000);
+  if (seconds < 60) return "just now";
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.round(hours / 24);
+  if (days < 7) return `${days}d`;
+  const weeks = Math.round(days / 7);
+  if (weeks < 5) return `${weeks}w`;
+  const months = Math.round(days / 30);
+  if (months < 12) return `${months}mo`;
+  const years = Math.round(days / 365);
+  return `${years}y`;
+}
+
+export interface SearchResultRowProps {
+  result: CompanySearchResult;
+  agentsById?: ReadonlyMap<string, Pick<Agent, "id" | "name">>;
+  isActive?: boolean;
+  className?: string;
+}
+
+const ROW_BASE =
+  "group flex items-start gap-3 rounded-md px-3 transition-colors no-underline text-inherit hover:bg-muted/40";
+
+function SearchResultRowImpl({
+  result,
+  agentsById,
+  isActive,
+  className,
+}: SearchResultRowProps) {
+  if (result.type === "agent") {
+    return (
+      <Link
+        to={result.href}
+        className={cn(ROW_BASE, "py-3", isActive && "bg-muted/40", className)}
+        data-result-type="agent"
+      >
+        <span className="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground">
+          <Bot className="h-3 w-3" />
+        </span>
+        <div className="min-w-0 flex-1">
+          <div className="flex min-w-0 items-center gap-2">
+            <span className="truncate text-sm font-medium">{result.title}</span>
+          </div>
+          {result.snippet ? (
+            <SnippetLine
+              text={result.snippets[0]?.text ?? result.snippet}
+              highlights={result.snippets[0]?.highlights}
+              field="agent"
+              fallbackLabel={result.sourceLabel ?? "Agent"}
+            />
+          ) : null}
+        </div>
+      </Link>
+    );
+  }
+
+  if (result.type === "project") {
+    return (
+      <Link
+        to={result.href}
+        className={cn(ROW_BASE, "py-3", isActive && "bg-muted/40", className)}
+        data-result-type="project"
+      >
+        <Hexagon className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+        <div className="min-w-0 flex-1">
+          <span className="truncate text-sm font-medium">{result.title}</span>
+          {result.snippet ? (
+            <SnippetLine
+              text={result.snippets[0]?.text ?? result.snippet}
+              highlights={result.snippets[0]?.highlights}
+              field="project"
+              fallbackLabel={result.sourceLabel ?? "Project"}
+            />
+          ) : null}
+        </div>
+      </Link>
+    );
+  }
+
+  const issue = result.issue;
+  if (!issue) return null;
+  const assigneeName = issue.assigneeAgentId
+    ? agentsById?.get(issue.assigneeAgentId)?.name ?? null
+    : null;
+  const updated = formatRelativeTime(result.updatedAt ?? issue.updatedAt);
+  const titleHighlights = result.snippets.find((snippet) => snippet.field === "title")?.highlights;
+  const bodySnippets = result.snippets.filter((snippet) => snippet.field !== "title").slice(0, 2);
+  const previewImageUrl = result.previewImageUrl;
+  const hasRightRail = previewImageUrl || assigneeName || updated;
+
+  return (
+    <Link
+      to={result.href}
+      disableIssueQuicklook
+      className={cn(ROW_BASE, "py-4", isActive && "bg-muted/40", className)}
+      data-result-type="issue"
+    >
+      <div className="mt-1 shrink-0">
+        <StatusIcon status={issue.status} />
+      </div>
+      <div className="min-w-0 flex-1">
+        <div className="flex min-w-0 flex-wrap items-baseline gap-x-2.5 gap-y-1">
+          {issue.identifier ? (
+            <span className="shrink-0 font-mono text-xs text-muted-foreground tabular-nums">
+              {issue.identifier}
+            </span>
+          ) : null}
+          <HighlightedText
+            text={issue.title}
+            highlights={titleHighlights}
+            className="min-w-0 flex-1 text-sm font-medium leading-snug text-foreground"
+          />
+        </div>
+        {bodySnippets.map((snippet, index) => (
+          <SnippetLine
+            key={`${snippet.field}-${index}`}
+            text={snippet.text}
+            highlights={snippet.highlights}
+            field={snippet.field}
+            fallbackLabel={snippet.label}
+            multiline
+          />
+        ))}
+        {hasRightRail ? (
+          <div className="mt-1.5 flex items-center gap-2 text-xs text-muted-foreground sm:hidden">
+            {assigneeName ? <span className="truncate">{assigneeName}</span> : null}
+            {updated ? <span className="ml-auto tabular-nums">{updated}</span> : null}
+          </div>
+        ) : null}
+      </div>
+      {hasRightRail ? (
+        <div className="ml-2 hidden shrink-0 flex-col items-end gap-2 sm:flex">
+          {assigneeName || updated ? (
+            <div className="flex items-center gap-2 text-xs text-muted-foreground">
+              {assigneeName ? <Identity name={assigneeName} size="sm" /> : null}
+              {updated ? <span className="tabular-nums">{updated}</span> : null}
+            </div>
+          ) : null}
+          {previewImageUrl ? (
+            <img
+              src={previewImageUrl}
+              alt=""
+              loading="lazy"
+              decoding="async"
+              className="h-[88px] w-[88px] shrink-0 rounded-md border border-border bg-muted object-cover"
+            />
+          ) : null}
+        </div>
+      ) : null}
+    </Link>
+  );
+}
+
+export const SearchResultRow = memo(SearchResultRowImpl);
+
+interface SnippetLineProps {
+  text: string;
+  highlights?: HighlightedTextProps["highlights"];
+  field: string;
+  fallbackLabel: string;
+  multiline?: boolean;
+}
+
+function SnippetLine({ text, highlights, field, fallbackLabel, multiline = false }: SnippetLineProps) {
+  const { Icon, label } = snippetStyle(field, fallbackLabel);
+  return (
+    <div
+      className={cn(
+        "mt-2.5 flex min-w-0 gap-1.5 text-xs text-muted-foreground",
+        multiline ? "items-start" : "items-center",
+      )}
+    >
+      <Icon
+        className={cn("h-3.5 w-3.5 shrink-0 text-muted-foreground/60", multiline && "mt-0.5")}
+        aria-hidden
+      />
+      <span className="sr-only">{label}: </span>
+      <HighlightedText
+        text={text}
+        highlights={highlights}
+        className={multiline ? "line-clamp-2 leading-relaxed" : "line-clamp-1 truncate"}
+      />
+    </div>
+  );
+}

ui/src/index.css

@@ -77,6 +77,18 @@
   --sidebar-accent-foreground: oklch(0.205 0 0);
   --sidebar-border: oklch(0.922 0 0);
   --sidebar-ring: oklch(0.708 0 0);
+  --chip-match-title-bg: oklch(0.97 0.02 265);
+  --chip-match-title-fg: oklch(0.4 0.13 265);
+  --chip-match-title-border: oklch(0.85 0.05 265);
+  --chip-match-comment-bg: oklch(0.97 0.02 145);
+  --chip-match-comment-fg: oklch(0.4 0.10 145);
+  --chip-match-comment-border: oklch(0.85 0.05 145);
+  --chip-match-document-bg: oklch(0.97 0.02 295);
+  --chip-match-document-fg: oklch(0.4 0.10 295);
+  --chip-match-document-border: oklch(0.85 0.05 295);
+  --chip-match-identifier-bg: var(--muted);
+  --chip-match-identifier-fg: var(--muted-foreground);
+  --chip-match-identifier-border: var(--border);
 }
 
 .dark {
@@ -112,6 +124,18 @@
   --sidebar-accent-foreground: oklch(0.985 0 0);
   --sidebar-border: oklch(0.269 0 0);
   --sidebar-ring: oklch(0.439 0 0);
+  --chip-match-title-bg: oklch(0.27 0.04 265 / 0.5);
+  --chip-match-title-fg: oklch(0.78 0.10 265);
+  --chip-match-title-border: oklch(0.4 0.06 265);
+  --chip-match-comment-bg: oklch(0.27 0.04 145 / 0.5);
+  --chip-match-comment-fg: oklch(0.78 0.08 145);
+  --chip-match-comment-border: oklch(0.4 0.05 145);
+  --chip-match-document-bg: oklch(0.27 0.04 295 / 0.5);
+  --chip-match-document-fg: oklch(0.78 0.08 295);
+  --chip-match-document-border: oklch(0.4 0.05 295);
+  --chip-match-identifier-bg: var(--muted);
+  --chip-match-identifier-fg: var(--muted-foreground);
+  --chip-match-identifier-border: var(--border);
 }
 
 @layer base {

ui/src/lib/company-routes.test.ts

@@ -27,4 +27,12 @@ describe("company routes", () => {
       "/execution-workspaces/workspace-123/routines",
     );
   });
+
+  it("treats /search as a board route that needs a company prefix", () => {
+    expect(isBoardPathWithoutPrefix("/search")).toBe(true);
+    expect(extractCompanyPrefixFromPath("/search")).toBeNull();
+    expect(applyCompanyPrefix("/search", "PAP")).toBe("/PAP/search");
+    expect(applyCompanyPrefix("/search?q=hello%20world", "PAP")).toBe("/PAP/search?q=hello%20world");
+    expect(toCompanyRelativePath("/PAP/search?q=foo")).toBe("/search?q=foo");
+  });
 });

ui/src/lib/company-routes.ts

@@ -18,6 +18,7 @@ const BOARD_ROUTE_ROOTS = new Set([
   "inbox",
   "u",
   "design-guide",
+  "search",
 ]);
 
 const GLOBAL_ROUTE_ROOTS = new Set(["auth", "invite", "board-claim", "cli-auth", "docs", "instance"]);

ui/src/lib/queryKeys.ts

@@ -136,6 +136,10 @@ export const queryKeys = {
     list: (companyId: string) => ["secrets", companyId] as const,
     providers: (companyId: string) => ["secret-providers", companyId] as const,
   },
+  companySearch: {
+    search: (companyId: string, q: string, scope: string, limit: number, offset: number) =>
+      ["company-search", companyId, q, scope, limit, offset] as const,
+  },
   dashboard: (companyId: string) => ["dashboard", companyId] as const,
   userProfile: (companyId: string, userSlug: string) =>
     ["user-profile", companyId, userSlug] as const,

ui/src/lib/recent-searches.ts

@@ -0,0 +1,57 @@
+const STORAGE_PREFIX = "paperclip:recent-searches:";
+const MAX_RECENT_SEARCHES = 5;
+
+function storageKey(companyId: string) {
+  return `${STORAGE_PREFIX}${companyId}`;
+}
+
+function isStorageAvailable() {
+  return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+}
+
+export function loadRecentSearches(companyId: string): string[] {
+  if (!isStorageAvailable() || !companyId) return [];
+  try {
+    const raw = window.localStorage.getItem(storageKey(companyId));
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    const cleaned: string[] = [];
+    for (const value of parsed) {
+      if (typeof value !== "string") continue;
+      const trimmed = value.trim();
+      if (!trimmed) continue;
+      cleaned.push(trimmed);
+      if (cleaned.length >= MAX_RECENT_SEARCHES) break;
+    }
+    return cleaned;
+  } catch {
+    return [];
+  }
+}
+
+export function pushRecentSearch(companyId: string, query: string): string[] {
+  if (!isStorageAvailable() || !companyId) return [];
+  const trimmed = query.trim();
+  if (!trimmed) return loadRecentSearches(companyId);
+  const existing = loadRecentSearches(companyId);
+  const filtered = existing.filter((entry) => entry.toLowerCase() !== trimmed.toLowerCase());
+  const next = [trimmed, ...filtered].slice(0, MAX_RECENT_SEARCHES);
+  try {
+    window.localStorage.setItem(storageKey(companyId), JSON.stringify(next));
+  } catch {
+    // ignore
+  }
+  return next;
+}
+
+export function clearRecentSearches(companyId: string): void {
+  if (!isStorageAvailable() || !companyId) return;
+  try {
+    window.localStorage.removeItem(storageKey(companyId));
+  } catch {
+    // ignore
+  }
+}
+
+export const RECENT_SEARCHES_LIMIT = MAX_RECENT_SEARCHES;

ui/src/pages/Search.test.tsx

@@ -0,0 +1,358 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import type { ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Search, buildSearchUrl } from "./Search";
+
+const companyState = vi.hoisted(() => ({
+  selectedCompanyId: "company-1",
+}));
+
+const breadcrumbState = vi.hoisted(() => ({
+  setBreadcrumbs: vi.fn(),
+}));
+
+const dialogState = vi.hoisted(() => ({
+  openNewIssue: vi.fn(),
+}));
+
+const navigateMock = vi.hoisted(() => vi.fn());
+
+const searchApiMock = vi.hoisted(() => ({
+  search: vi.fn(),
+}));
+
+const agentsApiMock = vi.hoisted(() => ({
+  list: vi.fn(),
+}));
+
+const projectsApiMock = vi.hoisted(() => ({
+  list: vi.fn(),
+}));
+
+vi.mock("../context/CompanyContext", () => ({
+  useCompany: () => companyState,
+}));
+
+vi.mock("../context/BreadcrumbContext", () => ({
+  useBreadcrumbs: () => breadcrumbState,
+}));
+
+vi.mock("../context/DialogContext", () => ({
+  useDialogActions: () => dialogState,
+}));
+
+vi.mock("../context/SidebarContext", () => ({
+  useSidebar: () => ({ isMobile: false, setSidebarOpen: vi.fn() }),
+}));
+
+vi.mock("../api/search", () => ({
+  searchApi: searchApiMock,
+}));
+
+vi.mock("../api/agents", () => ({
+  agentsApi: agentsApiMock,
+}));
+
+vi.mock("../api/projects", () => ({
+  projectsApi: projectsApiMock,
+}));
+
+vi.mock("@/lib/router", async () => {
+  const actual = await vi.importActual<typeof import("react-router-dom")>("react-router-dom");
+  return {
+    ...actual,
+    useNavigate: () => navigateMock,
+  };
+});
+
+vi.mock("../components/StatusIcon", () => ({
+  StatusIcon: ({ status }: { status: string }) => <span data-status={status} />,
+}));
+
+vi.mock("../components/StatusBadge", () => ({
+  StatusBadge: ({ status }: { status: string }) => <span data-status-badge={status}>{status}</span>,
+}));
+
+vi.mock("../components/Identity", () => ({
+  Identity: ({ name }: { name: string }) => <span>{name}</span>,
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+async function flush() {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+async function waitForAssertion(assertion: () => void, attempts = 50) {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      assertion();
+      return;
+    } catch (error) {
+      lastError = error;
+      await flush();
+    }
+  }
+  throw lastError;
+}
+
+function renderSearch(initialPath: string, container: HTMLDivElement, node?: ReactNode) {
+  const root = createRoot(container);
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  act(() => {
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={[initialPath]}>
+          <Routes>
+            <Route path="/search" element={node ?? <Search />} />
+          </Routes>
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+  });
+  return { root, queryClient };
+}
+
+describe("buildSearchUrl", () => {
+  it("writes q and scope when provided", () => {
+    expect(buildSearchUrl("http://x/search", "auth flake", "comments")).toBe(
+      "/search?q=auth+flake&scope=comments",
+    );
+  });
+
+  it("clears q when empty and omits scope when scope=all", () => {
+    expect(buildSearchUrl("http://x/search?q=stale&scope=issues", "", "all")).toBe("/search");
+  });
+
+  it("preserves the existing pathname and hash", () => {
+    expect(buildSearchUrl("http://x/PAP/search?q=x#anchor", "y", "issues")).toBe(
+      "/PAP/search?q=y&scope=issues#anchor",
+    );
+  });
+});
+
+describe("Search page", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    breadcrumbState.setBreadcrumbs.mockReset();
+    dialogState.openNewIssue.mockReset();
+    navigateMock.mockReset();
+    searchApiMock.search.mockReset();
+    agentsApiMock.list.mockReset();
+    projectsApiMock.list.mockReset();
+    agentsApiMock.list.mockResolvedValue([]);
+    projectsApiMock.list.mockResolvedValue([]);
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it("issues a search request when ?q is in the URL and renders the result", async () => {
+    searchApiMock.search.mockResolvedValueOnce({
+      query: "auth flake",
+      normalizedQuery: "auth flake",
+      scope: "all",
+      limit: 20,
+      offset: 0,
+      countsByType: { issue: 1, agent: 0, project: 0 },
+      hasMore: false,
+      results: [
+        {
+          id: "issue-1",
+          type: "issue",
+          score: 100,
+          title: "PAP-3142 Auth middleware flakes",
+          href: "/PAP/issues/PAP-3142",
+          matchedFields: ["title", "comment"],
+          sourceLabel: "Comment",
+          snippet: "we hit another flake",
+          snippets: [
+            {
+              field: "title",
+              label: "Title",
+              text: "Auth middleware flakes",
+              highlights: [{ start: 0, end: 4 }],
+            },
+            {
+              field: "comment",
+              label: "Comment",
+              text: "we hit another flake in the morning batch",
+              highlights: [{ start: 16, end: 21 }],
+            },
+          ],
+          issue: {
+            id: "issue-1",
+            identifier: "PAP-3142",
+            title: "Auth middleware flakes",
+            status: "in_progress",
+            priority: "medium",
+            assigneeAgentId: null,
+            assigneeUserId: null,
+            projectId: null,
+            updatedAt: new Date().toISOString(),
+          },
+          updatedAt: new Date().toISOString(),
+        },
+      ],
+    });
+
+    const { root } = renderSearch("/search?q=auth+flake", container);
+
+    await waitForAssertion(() => {
+      expect(searchApiMock.search).toHaveBeenCalledWith("company-1", {
+        q: "auth flake",
+        scope: "all",
+        limit: 20,
+      });
+    });
+
+    await waitForAssertion(() => {
+      expect(container.textContent).toContain("PAP-3142");
+      expect(container.textContent).toContain("Auth middleware flakes");
+      expect(container.textContent).toContain("1 result");
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("debounces typing into the input and dispatches a search after the debounce window", async () => {
+    searchApiMock.search.mockResolvedValue({
+      query: "deflake",
+      normalizedQuery: "deflake",
+      scope: "all",
+      limit: 20,
+      offset: 0,
+      countsByType: { issue: 0, agent: 0, project: 0 },
+      hasMore: false,
+      results: [],
+    });
+
+    const { root } = renderSearch("/search", container);
+
+    const input = container.querySelector('input[aria-label="Search query"]') as HTMLInputElement;
+    expect(input).not.toBeNull();
+
+    act(() => {
+      const nativeSetter = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )!.set!;
+      nativeSetter.call(input, "deflake");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    // The debounce hasn't fired yet, so no API call should be made synchronously.
+    expect(searchApiMock.search).not.toHaveBeenCalled();
+
+    await new Promise((resolve) => setTimeout(resolve, 350));
+
+    await waitForAssertion(() => {
+      expect(searchApiMock.search).toHaveBeenCalledWith("company-1", {
+        q: "deflake",
+        scope: "all",
+        limit: 20,
+      });
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("auto-redirects an exact identifier match to the issue root, dropping any deep-link suffix", async () => {
+    searchApiMock.search.mockResolvedValueOnce({
+      query: "PAP-3366",
+      normalizedQuery: "pap-3366",
+      scope: "all",
+      limit: 20,
+      offset: 0,
+      countsByType: { issue: 1, agent: 0, project: 0 },
+      hasMore: false,
+      results: [
+        {
+          id: "issue-3366",
+          type: "issue",
+          score: 1300,
+          title: "PAP-3366 Continuation summary",
+          href: "/PAP/issues/PAP-3366#document-continuation-summary",
+          matchedFields: ["identifier", "document"],
+          sourceLabel: "Document",
+          snippet: "Continuation summary excerpt",
+          snippets: [
+            {
+              field: "document",
+              label: "Continuation summary",
+              text: "Continuation summary excerpt",
+              highlights: [],
+            },
+          ],
+          issue: {
+            id: "issue-3366",
+            identifier: "PAP-3366",
+            title: "Continuation summary",
+            status: "in_progress",
+            priority: "medium",
+            assigneeAgentId: null,
+            assigneeUserId: null,
+            projectId: null,
+            updatedAt: new Date().toISOString(),
+          },
+          updatedAt: new Date().toISOString(),
+        },
+      ],
+    });
+
+    const { root } = renderSearch("/search?q=PAP-3366", container);
+
+    await waitForAssertion(() => {
+      expect(navigateMock).toHaveBeenCalledWith("/PAP/issues/PAP-3366", { replace: true });
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("renders the no-results state with a Search-all action when scope is non-default", async () => {
+    searchApiMock.search.mockResolvedValueOnce({
+      query: "ghost",
+      normalizedQuery: "ghost",
+      scope: "comments",
+      limit: 20,
+      offset: 0,
+      countsByType: { issue: 0, agent: 0, project: 0 },
+      hasMore: false,
+      results: [],
+    });
+
+    const { root } = renderSearch("/search?q=ghost&scope=comments", container);
+
+    await waitForAssertion(() => {
+      expect(container.textContent).toContain("No results for");
+      expect(container.textContent).toContain("ghost");
+      expect(container.textContent).toContain("Search all scopes");
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});

ui/src/pages/Search.tsx

@@ -0,0 +1,631 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { Search as SearchIcon, AlertTriangle, FileQuestion, Plus, X } from "lucide-react";
+import {
+  COMPANY_SEARCH_DEFAULT_LIMIT,
+  COMPANY_SEARCH_SCOPES,
+  type CompanySearchResponse,
+  type CompanySearchResult,
+  type CompanySearchScope,
+} from "@paperclipai/shared";
+import { Tabs, TabsContent } from "@/components/ui/tabs";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import { Skeleton } from "@/components/ui/skeleton";
+import { Badge } from "@/components/ui/badge";
+import { cn } from "@/lib/utils";
+import { useNavigate, useSearchParams } from "@/lib/router";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useDialogActions } from "../context/DialogContext";
+import { searchApi } from "../api/search";
+import { agentsApi } from "../api/agents";
+import { queryKeys } from "../lib/queryKeys";
+import { loadRecentSearches, pushRecentSearch } from "../lib/recent-searches";
+import { PageTabBar, type PageTabItem } from "../components/PageTabBar";
+import { IssueGroupHeader } from "../components/IssueGroupHeader";
+import { SearchResultRow } from "../components/search/SearchResultRow";
+import type { Agent } from "@paperclipai/shared";
+
+const SEARCH_DEBOUNCE_MS = 250;
+const IDENTIFIER_PATTERN = /^[A-Z]+-\d+$/;
+
+const SCOPE_LABELS: Record<CompanySearchScope, string> = {
+  all: "All",
+  issues: "Issues",
+  comments: "Comments",
+  documents: "Documents",
+  agents: "Agents",
+  projects: "Projects",
+};
+
+type SubGroupKey = "issues" | "comments" | "documents" | "agents" | "projects";
+
+const SUBGROUP_ORDER: SubGroupKey[] = ["issues", "comments", "documents", "agents", "projects"];
+
+const SUBGROUP_LABELS: Record<SubGroupKey, string> = {
+  issues: "Issues",
+  comments: "Comments",
+  documents: "Documents",
+  agents: "Agents",
+  projects: "Projects",
+};
+
+function classifyResult(result: CompanySearchResult): SubGroupKey {
+  if (result.type === "agent") return "agents";
+  if (result.type === "project") return "projects";
+  const matched = new Set(result.matchedFields);
+  if (matched.has("title") || matched.has("identifier") || matched.has("description")) return "issues";
+  if (matched.has("comment")) return "comments";
+  if (matched.has("document")) return "documents";
+  return "issues";
+}
+
+function buildSubgroups(results: CompanySearchResult[]): Array<{ key: SubGroupKey; results: CompanySearchResult[] }> {
+  const buckets = new Map<SubGroupKey, CompanySearchResult[]>();
+  for (const result of results) {
+    const key = classifyResult(result);
+    const list = buckets.get(key) ?? [];
+    list.push(result);
+    buckets.set(key, list);
+  }
+  return SUBGROUP_ORDER.filter((key) => (buckets.get(key)?.length ?? 0) > 0).map((key) => ({
+    key,
+    results: buckets.get(key) ?? [],
+  }));
+}
+
+function isCompanySearchScope(value: string | null): value is CompanySearchScope {
+  return Boolean(value) && (COMPANY_SEARCH_SCOPES as readonly string[]).includes(value as string);
+}
+
+function describeScope(scope: CompanySearchScope) {
+  if (scope === "all") return "All scopes";
+  return SCOPE_LABELS[scope];
+}
+
+export function buildSearchUrl(href: string, query: string, scope: CompanySearchScope): string {
+  const url = new URL(href);
+  if (query.length === 0) {
+    url.searchParams.delete("q");
+  } else {
+    url.searchParams.set("q", query);
+  }
+  if (scope === "all") {
+    url.searchParams.delete("scope");
+  } else {
+    url.searchParams.set("scope", scope);
+  }
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+function shapeError(error: unknown): { message: string; status?: number } {
+  if (!error) return { message: "Unknown error" };
+  if (error instanceof Error) {
+    const status = (error as Error & { status?: number }).status;
+    return { message: error.message, status: typeof status === "number" ? status : undefined };
+  }
+  return { message: String(error) };
+}
+
+export function Search() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const { openNewIssue } = useDialogActions();
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+
+  const urlQuery = searchParams.get("q") ?? "";
+  const urlScopeRaw = searchParams.get("scope");
+  const urlScope: CompanySearchScope = isCompanySearchScope(urlScopeRaw) ? urlScopeRaw : "all";
+
+  const [draftQuery, setDraftQuery] = useState(urlQuery);
+  const [committedQuery, setCommittedQuery] = useState(urlQuery);
+  const [scope, setScope] = useState<CompanySearchScope>(urlScope);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const lastUrlSyncRef = useRef<string>("");
+  const lastIdentifierRedirectRef = useRef<string>("");
+  const [recentSearches, setRecentSearches] = useState<string[]>([]);
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Search" }]);
+  }, [setBreadcrumbs]);
+
+  useEffect(() => {
+    if (!selectedCompanyId) return;
+    setRecentSearches(loadRecentSearches(selectedCompanyId));
+  }, [selectedCompanyId]);
+
+  // Pull URL changes back into local state (e.g. browser back/forward).
+  useEffect(() => {
+    setDraftQuery(urlQuery);
+    setCommittedQuery(urlQuery);
+  }, [urlQuery]);
+
+  useEffect(() => {
+    setScope(urlScope);
+  }, [urlScope]);
+
+  // Debounce the draft query into committedQuery and write to URL via replaceState.
+  useEffect(() => {
+    if (draftQuery === committedQuery) return;
+    const handle = window.setTimeout(() => {
+      setCommittedQuery(draftQuery);
+      if (typeof window !== "undefined") {
+        const next = buildSearchUrl(window.location.href, draftQuery, scope);
+        if (next !== `${window.location.pathname}${window.location.search}${window.location.hash}` && next !== lastUrlSyncRef.current) {
+          lastUrlSyncRef.current = next;
+          window.history.replaceState(window.history.state, "", next);
+        }
+      }
+    }, SEARCH_DEBOUNCE_MS);
+    return () => window.clearTimeout(handle);
+  }, [draftQuery, committedQuery, scope]);
+
+  const handleScopeChange = useCallback(
+    (next: string) => {
+      if (!isCompanySearchScope(next) || next === scope) return;
+      setScope(next);
+      if (typeof window !== "undefined") {
+        const url = buildSearchUrl(window.location.href, committedQuery, next);
+        window.history.pushState(window.history.state, "", url);
+      }
+    },
+    [committedQuery, scope],
+  );
+
+  const trimmedQuery = committedQuery.trim();
+  const queryEnabled = !!selectedCompanyId && trimmedQuery.length > 0;
+
+  const { data, isFetching, error, refetch } = useQuery<CompanySearchResponse>({
+    queryKey: queryKeys.companySearch.search(
+      selectedCompanyId ?? "__no-company__",
+      trimmedQuery,
+      scope,
+      COMPANY_SEARCH_DEFAULT_LIMIT,
+      0,
+    ),
+    queryFn: () =>
+      searchApi.search(selectedCompanyId!, {
+        q: trimmedQuery,
+        scope,
+        limit: COMPANY_SEARCH_DEFAULT_LIMIT,
+      }),
+    enabled: queryEnabled,
+    placeholderData: (previousData) => previousData,
+  });
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const agentsById = useMemo<ReadonlyMap<string, Pick<Agent, "id" | "name">>>(() => {
+    const map = new Map<string, Pick<Agent, "id" | "name">>();
+    for (const agent of agents ?? []) map.set(agent.id, agent);
+    return map;
+  }, [agents]);
+
+  // Persist recent searches once we have a successful response with a non-empty query.
+  useEffect(() => {
+    if (!selectedCompanyId) return;
+    if (!data || !trimmedQuery) return;
+    const next = pushRecentSearch(selectedCompanyId, trimmedQuery);
+    setRecentSearches(next);
+  }, [data, trimmedQuery, selectedCompanyId]);
+
+  // Identifier shortcut: when q matches PAP-123 and the API returns an exact identifier match, redirect to it.
+  useEffect(() => {
+    if (!data) return;
+    const upper = trimmedQuery.toUpperCase();
+    if (!IDENTIFIER_PATTERN.test(upper)) return;
+    if (lastIdentifierRedirectRef.current === upper) return;
+    const exact = data.results.find(
+      (result) => result.type === "issue" && result.issue?.identifier?.toUpperCase() === upper,
+    );
+    if (!exact?.issue) return;
+    lastIdentifierRedirectRef.current = upper;
+    // Strip the comment/document deep-link suffix so an exact identifier match
+    // lands on the issue root, not the top-scored snippet.
+    const baseHref = exact.href.split("#")[0] ?? exact.href;
+    const navigateHref = baseHref.startsWith("/") ? baseHref : `/${baseHref}`;
+    navigate(navigateHref, { replace: true });
+  }, [data, navigate, trimmedQuery]);
+
+  const handleClear = useCallback(() => {
+    setDraftQuery("");
+    setCommittedQuery("");
+    inputRef.current?.focus();
+    if (typeof window !== "undefined") {
+      const next = buildSearchUrl(window.location.href, "", scope);
+      window.history.replaceState(window.history.state, "", next);
+    }
+  }, [scope]);
+
+  const focusInput = useCallback(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  // Global "/" focus shortcut.
+  useEffect(() => {
+    function handler(event: KeyboardEvent) {
+      if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey) return;
+      const target = event.target as HTMLElement | null;
+      const tag = target?.tagName?.toLowerCase();
+      if (target?.isContentEditable || tag === "input" || tag === "textarea") return;
+      event.preventDefault();
+      focusInput();
+    }
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [focusInput]);
+
+  const counts = data?.countsByType ?? { issue: 0, agent: 0, project: 0 };
+  const totalResults = data?.results.length ?? 0;
+
+  const tabItems = useMemo<PageTabItem[]>(() => {
+    function pill(value: number) {
+      if (!data) return null;
+      return (
+        <Badge variant="outline" className="ml-1.5 px-1.5 py-0 text-[10px] tabular-nums font-normal">
+          {value}
+        </Badge>
+      );
+    }
+    const issuesTotal = counts.issue ?? 0;
+    return COMPANY_SEARCH_SCOPES.map((value) => {
+      let count: number | null = null;
+      if (value === "all") count = (counts.issue ?? 0) + (counts.agent ?? 0) + (counts.project ?? 0);
+      else if (value === "issues") count = issuesTotal;
+      else if (value === "agents") count = counts.agent ?? 0;
+      else if (value === "projects") count = counts.project ?? 0;
+      return {
+        value,
+        label: (
+          <span className="flex items-center">
+            {SCOPE_LABELS[value as CompanySearchScope]}
+            {count !== null ? pill(count) : null}
+          </span>
+        ),
+      } satisfies PageTabItem;
+    });
+  }, [counts, data]);
+
+  const subgroups = useMemo(() => buildSubgroups(data?.results ?? []), [data?.results]);
+
+  const showInitialState = !trimmedQuery;
+  const isLoading = queryEnabled && isFetching && !data;
+  const hasResults = !!data && totalResults > 0;
+  const isEmpty = !!data && !isFetching && totalResults === 0;
+  const hasError = !!error && !isLoading;
+  const apiError = hasError ? shapeError(error) : null;
+  const apiMessage = data?.results === undefined && data ? null : null;
+  void apiMessage;
+
+  function navigateIssuesFallback() {
+    navigate(`/issues?q=${encodeURIComponent(trimmedQuery)}`);
+  }
+
+  function handleRecentClick(value: string) {
+    setDraftQuery(value);
+    setCommittedQuery(value);
+    if (typeof window !== "undefined") {
+      const next = buildSearchUrl(window.location.href, value, scope);
+      window.history.replaceState(window.history.state, "", next);
+    }
+  }
+
+  function showAllScope() {
+    if (scope === "all") return;
+    handleScopeChange("all");
+  }
+
+  return (
+    <div className="flex h-full min-h-0 flex-col" data-page="search">
+      <div className="border-b border-border px-4 py-3 sm:px-6">
+        <h1 className="sr-only">Search</h1>
+        <div className="relative">
+          <SearchIcon className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            ref={inputRef}
+            autoFocus
+            value={draftQuery}
+            onChange={(event) => setDraftQuery(event.currentTarget.value)}
+            onKeyDown={(event) => {
+              if (event.key === "Escape") {
+                if (draftQuery.length > 0) {
+                  event.preventDefault();
+                  handleClear();
+                } else {
+                  event.currentTarget.blur();
+                }
+              }
+            }}
+            placeholder="Search issues, comments, documents, agents, projects…"
+            aria-label="Search query"
+            className="h-10 pl-9 pr-20 text-sm"
+          />
+          {draftQuery.length > 0 ? (
+            <button
+              type="button"
+              onClick={handleClear}
+              aria-label="Clear search"
+              className="absolute right-12 top-1/2 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-full text-muted-foreground hover:bg-accent/50"
+            >
+              <X className="h-3.5 w-3.5" />
+            </button>
+          ) : null}
+          <kbd
+            aria-hidden
+            className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 rounded border border-border bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground"
+          >
+            ⌘K
+          </kbd>
+        </div>
+      </div>
+
+      <Tabs value={scope} onValueChange={handleScopeChange} className="flex h-full min-h-0 flex-col">
+        <div className="border-b border-border px-2 sm:px-4">
+          <PageTabBar items={tabItems} value={scope} onValueChange={handleScopeChange} align="start" />
+        </div>
+
+        {COMPANY_SEARCH_SCOPES.map((scopeValue) => (
+          <TabsContent
+            key={scopeValue}
+            value={scopeValue}
+            className="flex h-full min-h-0 flex-col overflow-y-auto"
+          >
+            {scopeValue === scope ? (
+              <SearchTabContent
+                showInitialState={showInitialState}
+                isLoading={isLoading}
+                hasResults={hasResults}
+                hasError={hasError}
+                apiError={apiError}
+                isEmpty={isEmpty}
+                trimmedQuery={trimmedQuery}
+                scope={scope}
+                showAllScope={showAllScope}
+                navigateIssuesFallback={navigateIssuesFallback}
+                openNewIssue={() => openNewIssue({ title: trimmedQuery })}
+                refetch={() => void refetch()}
+                recentSearches={recentSearches}
+                onRecentClick={handleRecentClick}
+                subgroups={subgroups}
+                totalResults={totalResults}
+                isFetching={isFetching && !!data}
+                agentsById={agentsById}
+              />
+            ) : null}
+          </TabsContent>
+        ))}
+      </Tabs>
+    </div>
+  );
+}
+
+interface SearchTabContentProps {
+  showInitialState: boolean;
+  isLoading: boolean;
+  hasResults: boolean;
+  hasError: boolean;
+  apiError: { message: string; status?: number } | null;
+  isEmpty: boolean;
+  trimmedQuery: string;
+  scope: CompanySearchScope;
+  showAllScope: () => void;
+  navigateIssuesFallback: () => void;
+  openNewIssue: () => void;
+  refetch: () => void;
+  recentSearches: string[];
+  onRecentClick: (query: string) => void;
+  subgroups: Array<{ key: SubGroupKey; results: CompanySearchResult[] }>;
+  totalResults: number;
+  isFetching: boolean;
+  agentsById: ReadonlyMap<string, Pick<Agent, "id" | "name">>;
+}
+
+function SearchTabContent({
+  showInitialState,
+  isLoading,
+  hasResults,
+  hasError,
+  apiError,
+  isEmpty,
+  trimmedQuery,
+  scope,
+  showAllScope,
+  navigateIssuesFallback,
+  openNewIssue,
+  refetch,
+  recentSearches,
+  onRecentClick,
+  subgroups,
+  totalResults,
+  isFetching,
+  agentsById,
+}: SearchTabContentProps) {
+  if (showInitialState) {
+    return (
+      <div className="mx-auto flex w-full max-w-2xl flex-col gap-4 px-4 py-10 sm:px-6">
+        <div>
+          <h2 className="text-lg font-semibold">Type to search company memory.</h2>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Issues, comments, plan documents, agents, projects — same surface, ranked by relevance.
+          </p>
+        </div>
+        {recentSearches.length > 0 ? (
+          <div>
+            <div className="mb-2 text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">
+              Recent searches
+            </div>
+            <ul className="flex flex-col divide-y divide-border rounded-md border border-border">
+              {recentSearches.map((entry) => (
+                <li key={entry}>
+                  <button
+                    type="button"
+                    onClick={() => onRecentClick(entry)}
+                    className="flex w-full items-center gap-2 px-3 py-2 text-left text-sm hover:bg-accent/40"
+                  >
+                    <SearchIcon className="h-3.5 w-3.5 text-muted-foreground" />
+                    <span className="flex-1 truncate">{entry}</span>
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ) : null}
+        <ul className="space-y-1 text-xs text-muted-foreground">
+          <li>
+            <span className="font-medium text-foreground">Identifier lookup:</span> type{" "}
+            <code className="rounded bg-muted px-1 py-0.5 text-[11px]">PAP-123</code> to jump straight to an issue.
+          </li>
+          <li>
+            <span className="font-medium text-foreground">Quoted phrases:</span> wrap a phrase in quotes to match the
+            exact sequence.
+          </li>
+          <li>
+            <span className="font-medium text-foreground">⌘K:</span> reopens the command palette pre-seeded with your
+            current query.
+          </li>
+        </ul>
+      </div>
+    );
+  }
+
+  if (hasError) {
+    const status = apiError?.status;
+    return (
+      <div className="mx-auto flex w-full max-w-xl flex-col items-center justify-center gap-3 px-4 py-12 text-center">
+        <AlertTriangle className="h-10 w-10 text-destructive" aria-hidden />
+        <div className="text-base font-semibold">Couldn’t run that search</div>
+        <p className="text-sm text-muted-foreground">
+          {status ? `The server returned ${status}.` : "The request failed."} Your input and filters are still here, so
+          you can retry or fall back to the Issues filter.
+        </p>
+        <div className="flex flex-wrap items-center justify-center gap-2">
+          <Button onClick={refetch} variant="default" size="sm">
+            Retry
+          </Button>
+          <Button onClick={navigateIssuesFallback} variant="outline" size="sm">
+            Open Issues filter view
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col gap-2 px-2 py-3 sm:px-4">
+        <div className="px-3 text-xs text-muted-foreground" data-testid="search-loading">
+          Searching for &ldquo;{trimmedQuery}&rdquo;…
+        </div>
+        <div className="flex flex-col">
+          <div className="px-3 py-2">
+            <Skeleton className="h-3 w-24" />
+          </div>
+          {Array.from({ length: 5 }).map((_, index) => (
+            <div key={index} className="flex items-start gap-3 px-3 py-2">
+              <Skeleton className="mt-1 h-4 w-4 rounded-full" />
+              <div className="flex flex-1 flex-col gap-1.5">
+                <Skeleton className="h-3 w-3/4" />
+                <Skeleton className="h-3 w-1/2" />
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  if (isEmpty) {
+    return (
+      <div className="mx-auto flex w-full max-w-xl flex-col items-center justify-center gap-3 px-4 py-12 text-center">
+        <FileQuestion className="h-10 w-10 text-muted-foreground" aria-hidden />
+        <div className="text-base font-semibold">No results for &ldquo;{trimmedQuery}&rdquo;</div>
+        <p className="text-sm text-muted-foreground">
+          We couldn’t find a match in {describeScope(scope).toLowerCase()}. Try widening the scope or rephrasing your
+          query.
+        </p>
+        <div className="flex flex-wrap items-center justify-center gap-2">
+          {scope !== "all" ? (
+            <Button onClick={showAllScope} size="sm" variant="outline">
+              Search all scopes
+            </Button>
+          ) : null}
+          <Button onClick={openNewIssue} size="sm" variant="default">
+            <Plus className="mr-1.5 h-4 w-4" />
+            Create issue from this query
+          </Button>
+          <Button onClick={navigateIssuesFallback} size="sm" variant="ghost">
+            Open Issues filter view
+          </Button>
+        </div>
+        <ul className="mt-2 space-y-0.5 text-xs text-muted-foreground">
+          <li>Try fewer tokens or a single distinctive term.</li>
+          <li>
+            Use an identifier shortcut like <code className="rounded bg-muted px-1 py-0.5">PAP-123</code>.
+          </li>
+          <li>Wrap multi-word phrases in quotes.</li>
+        </ul>
+      </div>
+    );
+  }
+
+  if (!hasResults) return null;
+
+  return (
+    <div className="flex w-full max-w-[960px] flex-col px-2 sm:px-4" data-testid="search-results">
+      <div className="flex items-center justify-between py-2 text-[11px] uppercase tracking-wide text-muted-foreground">
+        <span>
+          {totalResults === 1 ? "1 result" : `${totalResults} results`} · sorted by relevance
+        </span>
+        {isFetching ? <span aria-live="polite" className="normal-case tracking-normal">Updating…</span> : null}
+      </div>
+      <div className="flex flex-col pb-10">
+        {scope === "all" ? (
+          subgroups.map((group, groupIndex) => (
+            <section
+              key={group.key}
+              aria-label={SUBGROUP_LABELS[group.key]}
+              className={cn("flex flex-col", groupIndex > 0 && "mt-6")}
+            >
+              <IssueGroupHeader
+                label={SUBGROUP_LABELS[group.key]}
+                trailing={
+                  <span className="text-xs font-normal tabular-nums text-muted-foreground">
+                    {group.results.length}
+                  </span>
+                }
+                className="pt-2 pb-1 text-[11px] tracking-wider text-muted-foreground"
+              />
+              <div className="flex flex-col gap-y-1">
+                {group.results.map((result) => (
+                  <SearchResultRow
+                    key={`${result.type}:${result.id}:${result.href}`}
+                    result={result}
+                    agentsById={agentsById}
+                  />
+                ))}
+              </div>
+            </section>
+          ))
+        ) : (
+          <div className="flex flex-col gap-y-1">
+            {subgroups
+              .flatMap((group) => group.results)
+              .map((result) => (
+                <SearchResultRow
+                  key={`${result.type}:${result.id}:${result.href}`}
+                  result={result}
+                  agentsById={agentsById}
+                />
+              ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

ui/storybook/stories/search.stories.tsx

@@ -0,0 +1,618 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { CompanySearchResult, CompanySearchResponse } from "@paperclipai/shared";
+import { Badge } from "@/components/ui/badge";
+import { IssueGroupHeader } from "@/components/IssueGroupHeader";
+import { Input } from "@/components/ui/input";
+import { PageTabBar, type PageTabItem } from "@/components/PageTabBar";
+import { MatchSourceChip } from "@/components/search/MatchSourceChip";
+import { SearchResultRow } from "@/components/search/SearchResultRow";
+import { Tabs } from "@/components/ui/tabs";
+import {
+  Bot,
+  CircleDot,
+  DollarSign,
+  Hexagon,
+  History,
+  Inbox,
+  LayoutDashboard,
+  Plus,
+  Search as SearchIcon,
+  SquarePen,
+  Target,
+} from "lucide-react";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from "@/components/ui/command";
+import { StatusBadge } from "@/components/StatusBadge";
+import { storybookAgents, storybookProjects, storybookIssues } from "../fixtures/paperclipData";
+
+const agentsById = new Map(storybookAgents.map((agent) => [agent.id, agent]));
+
+type IssueResultOverrides = Omit<Partial<CompanySearchResult>, "issue"> & {
+  issue?: Partial<NonNullable<CompanySearchResult["issue"]>>;
+};
+
+function buildIssueResult(overrides: IssueResultOverrides): CompanySearchResult {
+  const baseIssue = {
+    id: overrides.issue?.id ?? "issue-1",
+    identifier: overrides.issue?.identifier ?? "PAP-3142",
+    title: overrides.issue?.title ?? "Auth middleware flakes on cold-start when session token is rotated",
+    status: overrides.issue?.status ?? "in_progress",
+    priority: overrides.issue?.priority ?? "high",
+    assigneeAgentId: overrides.issue?.assigneeAgentId ?? storybookAgents[0]?.id ?? null,
+    assigneeUserId: overrides.issue?.assigneeUserId ?? null,
+    projectId: overrides.issue?.projectId ?? storybookProjects[0]?.id ?? null,
+    updatedAt: overrides.issue?.updatedAt ?? new Date(Date.now() - 1000 * 60 * 60 * 3).toISOString(),
+  } satisfies NonNullable<CompanySearchResult["issue"]>;
+  return {
+    id: overrides.id ?? baseIssue.id,
+    type: "issue",
+    score: 100,
+    title: `${baseIssue.identifier} ${baseIssue.title}`,
+    href: `/PAP/issues/${baseIssue.identifier}`,
+    matchedFields: overrides.matchedFields ?? ["title"],
+    sourceLabel: overrides.sourceLabel ?? null,
+    snippet: overrides.snippet ?? null,
+    snippets: overrides.snippets ?? [],
+    issue: baseIssue,
+    updatedAt: baseIssue.updatedAt,
+    previewImageUrl: overrides.previewImageUrl ?? null,
+  };
+}
+
+const fixtureResults: CompanySearchResult[] = [
+  buildIssueResult({
+    id: "issue-1",
+    matchedFields: ["title", "comment"],
+    sourceLabel: "Comment",
+    snippet: "we hit another flake in the morning batch — auth middleware",
+    snippets: [
+      {
+        field: "title",
+        label: "Title",
+        text: "Auth middleware flakes on cold-start when session token is rotated",
+        highlights: [{ start: 0, end: 4 }],
+      },
+      {
+        field: "comment",
+        label: "Comment",
+        text: "we hit another flake in the morning batch — auth middleware ate the request",
+        highlights: [{ start: 16, end: 21 }, { start: 47, end: 51 }],
+      },
+    ],
+  }),
+  buildIssueResult({
+    id: "issue-2",
+    issue: {
+      id: "issue-2",
+      identifier: "PAP-3091",
+      title: "Audit auth flake telemetry from last quarter",
+      status: "in_review",
+      assigneeAgentId: storybookAgents[1]?.id ?? null,
+    },
+    matchedFields: ["title", "document"],
+    sourceLabel: "Document",
+    snippet: "the deflake plan ranks auth regressions above latency tickets",
+    snippets: [
+      {
+        field: "title",
+        label: "Title",
+        text: "Audit auth flake telemetry from last quarter",
+        highlights: [{ start: 6, end: 10 }],
+      },
+      {
+        field: "document",
+        label: "PLAN",
+        text: "the deflake plan ranks auth regressions above latency tickets",
+        highlights: [{ start: 12, end: 16 }, { start: 26, end: 30 }],
+      },
+    ],
+    previewImageUrl:
+      "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' fill='%23a78bfa'/><text x='50' y='55' font-size='14' fill='white' text-anchor='middle' font-family='sans-serif'>chart</text></svg>",
+  }),
+  buildIssueResult({
+    id: "issue-3",
+    issue: {
+      id: "issue-3",
+      identifier: "PAP-2748",
+      title: "Pin worker registration to a single auth backend",
+      status: "done",
+      assigneeAgentId: null,
+    },
+    matchedFields: ["title", "identifier"],
+    snippets: [
+      {
+        field: "title",
+        label: "Title",
+        text: "Pin worker registration to a single auth backend",
+        highlights: [{ start: 36, end: 40 }],
+      },
+    ],
+  }),
+];
+
+const fixtureAgents: CompanySearchResult[] = storybookAgents.slice(0, 1).map((agent) => ({
+  id: agent.id,
+  type: "agent" as const,
+  score: 80,
+  title: agent.name,
+  href: `/PAP/agents/${agent.id}`,
+  matchedFields: ["agent"],
+  sourceLabel: "Agent",
+  snippet: agent.capabilities ?? null,
+  snippets: agent.capabilities
+    ? [
+        {
+          field: "capabilities",
+          label: "Agent",
+          text: agent.capabilities,
+          highlights: [],
+        },
+      ]
+    : [],
+  updatedAt: new Date().toISOString(),
+  previewImageUrl: null,
+}));
+
+const fixtureProjects: CompanySearchResult[] = storybookProjects.slice(0, 1).map((project) => ({
+  id: project.id,
+  type: "project" as const,
+  score: 70,
+  title: project.name,
+  href: `/PAP/projects/${project.id}`,
+  matchedFields: ["project"],
+  sourceLabel: "Project",
+  snippet: project.description ?? null,
+  snippets: project.description
+    ? [
+        {
+          field: "description",
+          label: "Project",
+          text: project.description,
+          highlights: [],
+        },
+      ]
+    : [],
+  updatedAt: new Date().toISOString(),
+  previewImageUrl: null,
+}));
+
+const fixtureResponse: CompanySearchResponse = {
+  query: "auth flake",
+  normalizedQuery: "auth flake",
+  scope: "all",
+  limit: 20,
+  offset: 0,
+  results: [...fixtureResults, ...fixtureAgents, ...fixtureProjects],
+  countsByType: {
+    issue: fixtureResults.length,
+    agent: fixtureAgents.length,
+    project: fixtureProjects.length,
+  },
+  hasMore: false,
+};
+
+function ScopeTabsPreview({
+  active,
+  response,
+}: {
+  active: "all" | "issues" | "comments" | "documents" | "agents" | "projects";
+  response: CompanySearchResponse;
+}) {
+  const total =
+    (response.countsByType.issue ?? 0) +
+    (response.countsByType.agent ?? 0) +
+    (response.countsByType.project ?? 0);
+  const items: PageTabItem[] = [
+    { value: "all", label: <ScopeTabLabel label="All" count={total} /> },
+    { value: "issues", label: <ScopeTabLabel label="Issues" count={response.countsByType.issue} /> },
+    { value: "comments", label: <ScopeTabLabel label="Comments" count={response.results.filter((result) => result.matchedFields.includes("comment")).length} /> },
+    { value: "documents", label: <ScopeTabLabel label="Documents" count={response.results.filter((result) => result.matchedFields.includes("document")).length} /> },
+    { value: "agents", label: <ScopeTabLabel label="Agents" count={response.countsByType.agent} /> },
+    { value: "projects", label: <ScopeTabLabel label="Projects" count={response.countsByType.project} /> },
+  ];
+  return (
+    <Tabs value={active}>
+      <PageTabBar items={items} value={active} align="start" />
+    </Tabs>
+  );
+}
+
+function ScopeTabLabel({ label, count }: { label: string; count: number }) {
+  return (
+    <span className="flex items-center">
+      {label}
+      <Badge variant="outline" className="ml-1.5 px-1.5 py-0 text-[10px] tabular-nums font-normal">
+        {count}
+      </Badge>
+    </span>
+  );
+}
+
+function SearchPagePreview({
+  response,
+  state,
+  query,
+}: {
+  response: CompanySearchResponse;
+  state: "results" | "empty" | "loading" | "initial";
+  query: string;
+}) {
+  return (
+    <div className="flex h-full min-h-0 flex-col rounded-md border border-border bg-background">
+      <div className="border-b border-border px-4 py-3">
+        <div className="relative">
+          <SearchIcon className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            value={query}
+            readOnly
+            placeholder="Search issues, comments, documents, agents, projects…"
+            className="h-10 pl-9 pr-20 text-sm"
+            aria-label="Search query"
+          />
+          <kbd className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 rounded border border-border bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
+            ⌘K
+          </kbd>
+        </div>
+      </div>
+      <div className="border-b border-border px-2 sm:px-4">
+        <ScopeTabsPreview active="all" response={response} />
+      </div>
+
+      {state === "results" ? (
+        <div className="flex w-full max-w-[960px] flex-col px-2 sm:px-4">
+          <div className="flex items-center justify-between py-2 text-[11px] uppercase tracking-wide text-muted-foreground">
+            <span>{response.results.length} results · sorted by relevance</span>
+          </div>
+          <section aria-label="Issues" className="flex flex-col">
+            <IssueGroupHeader
+              label="Issues"
+              trailing={
+                <span className="text-xs font-normal tabular-nums text-muted-foreground">
+                  {fixtureResults.length}
+                </span>
+              }
+              className="pt-2 pb-1 text-[11px] tracking-wider text-muted-foreground"
+            />
+            <div className="flex flex-col gap-y-1">
+              {fixtureResults.map((result) => (
+                <SearchResultRow
+                  key={result.id}
+                  result={result}
+                  agentsById={agentsById}
+                />
+              ))}
+            </div>
+          </section>
+          <section aria-label="Agents" className="mt-6 flex flex-col">
+            <IssueGroupHeader
+              label="Agents"
+              trailing={
+                <span className="text-xs font-normal tabular-nums text-muted-foreground">
+                  {fixtureAgents.length}
+                </span>
+              }
+              className="pt-2 pb-1 text-[11px] tracking-wider text-muted-foreground"
+            />
+            <div className="flex flex-col gap-y-1">
+              {fixtureAgents.map((result) => (
+                <SearchResultRow key={result.id} result={result} />
+              ))}
+            </div>
+          </section>
+          <section aria-label="Projects" className="mt-6 flex flex-col">
+            <IssueGroupHeader
+              label="Projects"
+              trailing={
+                <span className="text-xs font-normal tabular-nums text-muted-foreground">
+                  {fixtureProjects.length}
+                </span>
+              }
+              className="pt-2 pb-1 text-[11px] tracking-wider text-muted-foreground"
+            />
+            <div className="flex flex-col gap-y-1">
+              {fixtureProjects.map((result) => (
+                <SearchResultRow key={result.id} result={result} />
+              ))}
+            </div>
+          </section>
+        </div>
+      ) : null}
+
+      {state === "empty" ? (
+        <div className="mx-auto flex w-full max-w-xl flex-col items-center justify-center gap-3 px-4 py-12 text-center">
+          <div className="text-base font-semibold">
+            No results for &ldquo;{query}&rdquo;
+          </div>
+          <p className="text-sm text-muted-foreground">
+            We couldn&rsquo;t find a match in all scopes. Try widening the scope or rephrasing your query.
+          </p>
+          <ul className="mt-2 space-y-0.5 text-xs text-muted-foreground">
+            <li>Try fewer tokens or a single distinctive term.</li>
+            <li>Use an identifier shortcut like <code className="rounded bg-muted px-1 py-0.5">PAP-123</code>.</li>
+          </ul>
+        </div>
+      ) : null}
+
+      {state === "loading" ? (
+        <div className="flex flex-col gap-2 px-2 py-3 sm:px-4">
+          <div className="px-3 text-xs text-muted-foreground">Searching for &ldquo;{query}&rdquo;…</div>
+          <div className="flex flex-col">
+            {Array.from({ length: 5 }).map((_, index) => (
+              <div key={index} className="flex items-start gap-3 px-3 py-2">
+                <div className="mt-1 h-4 w-4 rounded-full bg-muted" />
+                <div className="flex flex-1 flex-col gap-1.5">
+                  <div className="h-3 w-3/4 rounded bg-muted" />
+                  <div className="h-3 w-1/2 rounded bg-muted/60" />
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      ) : null}
+
+      {state === "initial" ? (
+        <div className="mx-auto flex w-full max-w-2xl flex-col gap-4 px-4 py-10 sm:px-6">
+          <div>
+            <h2 className="text-lg font-semibold">Type to search company memory.</h2>
+            <p className="mt-1 text-sm text-muted-foreground">
+              Issues, comments, plan documents, agents, projects — same surface, ranked by relevance.
+            </p>
+          </div>
+          <ul className="space-y-1 text-xs text-muted-foreground">
+            <li>
+              <span className="font-medium text-foreground">Identifier lookup:</span> type{" "}
+              <code className="rounded bg-muted px-1 py-0.5 text-[11px]">PAP-123</code> to jump straight to an issue.
+            </li>
+            <li>
+              <span className="font-medium text-foreground">Quoted phrases:</span> wrap a phrase in quotes to match the
+              exact sequence.
+            </li>
+            <li>
+              <span className="font-medium text-foreground">⌘K:</span> reopens the command palette pre-seeded with your
+              current query.
+            </li>
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function CommandPaletteWithSearchAll({
+  query,
+  emptyResults = false,
+}: {
+  query: string;
+  emptyResults?: boolean;
+}) {
+  return (
+    <Command className="rounded-md border border-border bg-popover shadow-lg">
+      <CommandInput value={query} readOnly placeholder="Search issues, agents, projects..." />
+      <CommandList className="max-h-none">
+        {emptyResults ? (
+          <CommandEmpty>
+            <span>
+              No quick issue matches. Press{" "}
+              <kbd className="rounded border border-border bg-muted px-1 py-0.5 text-[10px]">↵</kbd>{" "}
+              to <span className="font-medium">search all</span> or keep typing to refine.
+            </span>
+          </CommandEmpty>
+        ) : null}
+        <CommandGroup heading="Search">
+          <CommandItem
+            value="search-all"
+            className="bg-accent/40 border border-accent data-[selected=true]:bg-accent/60"
+          >
+            <SearchIcon className="mr-2 h-4 w-4" />
+            <span className="flex-1 truncate">
+              Search all for <span className="font-semibold">&ldquo;{query}&rdquo;</span>
+            </span>
+            <span className="ml-auto inline-flex items-center gap-1 text-xs text-muted-foreground">
+              <span>open full search</span>
+              <kbd className="rounded border border-border bg-background px-1 py-0.5 text-[10px]">↵</kbd>
+            </span>
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Actions">
+          <CommandItem>
+            <SquarePen className="mr-2 h-4 w-4" />
+            Create new issue
+            <span className="ml-auto text-xs text-muted-foreground">C</span>
+          </CommandItem>
+          <CommandItem>
+            <Plus className="mr-2 h-4 w-4" />
+            Create new agent
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Pages">
+          <CommandItem>
+            <LayoutDashboard className="mr-2 h-4 w-4" />
+            Dashboard
+          </CommandItem>
+          <CommandItem>
+            <Inbox className="mr-2 h-4 w-4" />
+            Inbox
+          </CommandItem>
+          <CommandItem>
+            <CircleDot className="mr-2 h-4 w-4" />
+            Issues
+          </CommandItem>
+          <CommandItem>
+            <Target className="mr-2 h-4 w-4" />
+            Goals
+          </CommandItem>
+          <CommandItem>
+            <Bot className="mr-2 h-4 w-4" />
+            Agents
+          </CommandItem>
+          <CommandItem>
+            <DollarSign className="mr-2 h-4 w-4" />
+            Costs
+          </CommandItem>
+          <CommandItem>
+            <History className="mr-2 h-4 w-4" />
+            Activity
+          </CommandItem>
+        </CommandGroup>
+        {!emptyResults ? (
+          <>
+            <CommandSeparator />
+            <CommandGroup heading="Issues">
+              {storybookIssues.slice(0, 3).map((issue) => (
+                <CommandItem key={issue.id}>
+                  <CircleDot className="mr-2 h-4 w-4" />
+                  <span className="mr-2 font-mono text-xs text-muted-foreground">{issue.identifier}</span>
+                  <span className="flex-1 truncate">{issue.title}</span>
+                  <StatusBadge status={issue.status} />
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </>
+        ) : null}
+        <CommandSeparator />
+        <CommandGroup heading="Projects">
+          {storybookProjects.slice(0, 2).map((project) => (
+            <CommandItem key={project.id}>
+              <Hexagon className="mr-2 h-4 w-4" />
+              {project.name}
+            </CommandItem>
+          ))}
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  );
+}
+
+function SearchStories() {
+  return (
+    <div className="paperclip-story">
+      <main className="paperclip-story__inner max-w-[1320px] space-y-6">
+        <section className="paperclip-story__frame p-6">
+          <div className="paperclip-story__label">Search</div>
+          <h1 className="mt-2 text-3xl font-semibold tracking-tight">Full search page and Command K handoff</h1>
+          <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+            Snippet-forward results, scope tabs, match-source chips, and the supporting empty / loading / initial
+            states. Cmd K palette renders the persistent &ldquo;Search all for…&rdquo; row when a query is non-empty.
+          </p>
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">/search</div>
+            <h2 className="mt-1 text-lg font-semibold">Results, query &ldquo;auth flake&rdquo;</h2>
+          </div>
+          <SearchPagePreview response={fixtureResponse} state="results" query="auth flake" />
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">/search</div>
+            <h2 className="mt-1 text-lg font-semibold">Initial state — no query</h2>
+          </div>
+          <SearchPagePreview response={fixtureResponse} state="initial" query="" />
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">/search</div>
+            <h2 className="mt-1 text-lg font-semibold">Loading skeleton</h2>
+          </div>
+          <SearchPagePreview response={fixtureResponse} state="loading" query="auth flake" />
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">/search</div>
+            <h2 className="mt-1 text-lg font-semibold">No results state</h2>
+          </div>
+          <SearchPagePreview response={{ ...fixtureResponse, results: [], countsByType: { issue: 0, agent: 0, project: 0 } }} state="empty" query="ghostbuster" />
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden p-4">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">Match-source chips</div>
+            <h2 className="mt-1 text-lg font-semibold">Type-coded chip variants</h2>
+          </div>
+          <div className="flex flex-wrap items-center gap-2 p-2">
+            <MatchSourceChip kind="title" />
+            <MatchSourceChip kind="identifier" />
+            <MatchSourceChip kind="comment" count={3} />
+            <MatchSourceChip kind="document" />
+            <MatchSourceChip kind="document" count={2} label="Doc" />
+          </div>
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden p-4">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">Cmd+K palette</div>
+            <h2 className="mt-1 text-lg font-semibold">Search-all row with quick results</h2>
+          </div>
+          <div className="grid gap-4 lg:grid-cols-2">
+            <div>
+              <div className="mb-2 text-[11px] uppercase tracking-wide text-muted-foreground">
+                With quick issue matches
+              </div>
+              <CommandPaletteWithSearchAll query="auth flake" />
+            </div>
+            <div>
+              <div className="mb-2 text-[11px] uppercase tracking-wide text-muted-foreground">
+                Empty results — Enter routes to /search
+              </div>
+              <CommandPaletteWithSearchAll query="ghostbuster" emptyResults />
+            </div>
+          </div>
+        </section>
+
+        <section className="paperclip-story__frame overflow-hidden p-4">
+          <div className="paperclip-story__title-block">
+            <div className="paperclip-story__label">Search result row</div>
+            <h2 className="mt-1 text-lg font-semibold">Issue, agent, project rows</h2>
+          </div>
+          <div className="flex w-full max-w-[960px] flex-col gap-y-1">
+            {fixtureResults.map((result) => (
+              <SearchResultRow
+                key={result.id}
+                result={result}
+                agentsById={agentsById}
+              />
+            ))}
+            {fixtureAgents.map((result) => (
+              <SearchResultRow key={result.id} result={result} />
+            ))}
+            {fixtureProjects.map((result) => (
+              <SearchResultRow key={result.id} result={result} />
+            ))}
+          </div>
+        </section>
+      </main>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Product/Search & Command K",
+  component: SearchStories,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Full search page surfaces and Command K Search-all handoff. Reuses StatusIcon, StatusBadge, Identity, IssueGroupHeader, and PageTabBar; adds MatchSourceChip + SearchResultRow.",
+      },
+    },
+  },
+} satisfies Meta<typeof SearchStories>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const SearchSurfaces: Story = {};