--- name: ade-search description: Use this skill to search project-backed ADE chats across registered projects and search the active project's terminals, PRs, commits, branches, lanes, files, Linear issues, and proof artifacts via `ade search` instead of grepping .ade/ internals. --- # ADE search ## What it is `ade search` queries deterministic full-text indexes maintained by ADE. Chat queries include project-backed chats from every project registered with the machine brain. Other kinds — terminal/CLI scrollback, PRs, commits, branches, lanes, workspace files, Linear issues, and proof artifacts — come from the active project. Personal/no-project chats are intentionally excluded and stay on the separate personal-chat surface. This policy is identical for session-bound agents and unbound human shells; search does not silently narrow chat hits to the caller's own session. It is not a grep over `.ade/`: the runtime keeps each project index fresh and the machine router combines bounded chat result pages. Each project contributes at most its first 200 matches to one aggregate query; `resultsTruncated: true` (and the text-mode `bounded:` line) means you should narrow the query rather than assuming the tail was exhaustive. Every hit carries a deep link back to the exact ADE surface. Use it instead of poking at `.ade/ade.db`, replaying `git log`, or asking the user "which chat was that in". It answers "where did this happen in ADE" across kinds in one call. ## Command forms ```bash ade search "" # ranked results as JSON (default) ade search "" --text # aligned rows + count summary ade search "" --kind chat,terminal # restrict to kinds ade search "" --lane fix-login # restrict to a lane (id or name) ade search "" --limit 20 # cap result count ade search "" --cursor # next page from a prior query ade search --status --text # index doc counts + backfill state ade search --rebuild --text # rebuild the index (CTO-only) ``` ## Query syntax The query string is passed through to the index. It supports: | Form | Meaning | Example | | ------------------- | -------------------------------- | ------------------------------------------ | | bare terms | AND-ed together | `ade search "retry backoff"` | | `"quoted phrase"` | exact adjacent phrase | `ade search '"connection refused"'` | | `kind:` | restrict to a kind inline | `ade search "kind:pr merge queue"` | | `lane:` | restrict to a lane inline | `ade search "lane:fix-login timeout"` | | `session:` | restrict to one session | `ade search "session:abc123 panic"` | | `since:` | recency floor (ISO date) | `ade search "since:2026-06-01 crash"` | Inline `kind:` / `lane:` filters and the `--kind` / `--lane` flags can be mixed; the flags are the scriptable form and validate their input. Kind values: `lane`, `chat`, `terminal`, `pr`, `commit`, `branch`, `file`, `linear`, `artifact`. `--kind` takes a comma-separated list and rejects unknown kinds with a usage error (exit 2). ## Result kinds and where they deep-link | kind | deep-links to | | ---------- | --------------------------------------------------------- | | `chat` | the Work chat session, scrolled to the matching message | | `terminal` | the terminal/CLI session, at the matching scrollback offset | | `pr` | the PR detail tab | | `commit` | the commit in the lane's history | | `branch` | the branch (find-or-offer-to-create lane) | | `lane` | the lane | | `file` | the workspace file | | `linear` | the Linear pane for the issue | | `artifact` | the proof/artifact in the proof drawer | Each result also carries `laneId`/`laneName`, `sessionId`, and `updatedAt`; the `deepLink` is an `ade://…` URL you can hand to `ade open`. Machine-routed results additionally carry `projectId`, `projectName`, and `projectRoot` so same-named lanes and chats remain distinguishable. ## Output modes - `--json` (default): the full `SearchQueryResult` — `results[]` (each with `kind`, `id`, `title`, `snippet`, `matchRanges`, `laneId`, `laneName`, `sessionId`, `deepLink`, `updatedAt`, and machine-routed project fields), `totalByKind`, `nextCursor`, and project coverage metadata. Use this when you need the deep link or want to page. - `--text`: aligned `KIND PROJECT TITLE SNIPPET ID` rows when project metadata is present, then a `N results (chat 3, terminal 2, …)` summary from `totalByKind`, and a `more: --cursor ` line when another page exists. Use this for a quick human-readable scan. Exit codes are script-friendly: `0` when the query matched at least one result, `1` when it matched nothing (so `ade search "x" >/dev/null && …` works), and `2` on a usage error such as an unknown `--kind`. ## When to use which - **"Which chat discussed X?"** → `ade search "X" --kind chat --text`, then `ade open ` or read a bounded window with `ade chat read --limit 20 --max-chars 8000 --text`. Use `--page --cursor ` only when you need older content. - **"Which terminal ran the failing command?"** → `ade search "" --kind terminal --text`; the result offset drops you at the failure in scrollback. - **"Find the PR discussing Y."** → `ade search "Y" --kind pr --text`. - **"Where in this lane did we touch Z?"** → `ade search "Z" --lane --text` across files, commits, and chats. - **Index looks stale or empty** → `ade search --status --text` to see `docCount`, per-kind counts, and `backfillComplete`; rebuild with `ade search --rebuild` only if backfill is genuinely broken. Reach for `ade search` before grepping `.ade/` internals or asking the user to locate something. Remember the boundary: chats span registered projects; non-chat kinds use the active project; personal chats are excluded.