## Summary **Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the **124** hand-authored pages whose leading body H1 differed from the manifest nav label, this promotes the richer body H1 to the front-matter **page title** and drops the duplicate H1, while keeping the short manifest **label** as the sidebar entry. Policy agreed with the docs owner: - Short sidebar labels win. Duplicate sidebar labels are acceptable. - Identical **page titles** across two pages are not. On a collision, rename the non-generated page's title. ## Page-title collisions resolved Promoting the H1 created 4 page-title collisions; each is disambiguated by renaming the non-generated / secondary page (sidebar labels left unchanged): | page | sidebar label | body H1 | → page title | |------|---------------|---------|--------------| | `install/index.md` | Install | Installing Coder | **Install Coder in your infrastructure** | | `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder CLI** | | `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs | **JetBrains** | | `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | Web IDEs *(kept — primary user guide)* | | `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | **Web IDEs in templates** | | `workspace-management.md` | Workspace Management | Workspaces | **Manage workspaces** *(vs generated `api/workspaces.md`)* | These titles are the only non-mechanical editorial calls in this PR. ## Deliberately excluded: generated pages `admin/security/audit-logs.md` and `admin/setup/configuration-reference.md` are `make gen` outputs (`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a hand-added title would be reverted on the next generation. They're excluded here and need their generators taught to emit front matter first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the same issue for three other generated pages; it has been corrected there too. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Promote = set front-matter `title` to the body H1 (or the disambiguated title above) and remove that one duplicate H1. No other body prose is reflowed. - Every added front-matter block parses as YAML; all files pass `pnpm check-docs` (markdownlint-cli2 + table formatter): `Summary: 0 error(s)`. - Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in `ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into the retitled pages found no real breakage. Anchor-change note Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each page's effective title from the manifest label to the body H1, so the rendered H1 **anchor slug changes**. An audit of cross-file `.md#fragment` links into these pages surfaced no links that break as a result (the only hits were false positives against a still-present `## TLS & Reverse Proxy` heading). Same-file fragments are enforced by markdownlint MD051, which is green. ## Title casing (follow-up, DOCS-742) A follow-up commit puts the promoted titles into sentence case and removes leading gerunds (for example, `Managing workspace schedules` → `Manage workspace schedules`): 57 of the 120 titles changed, the other 63 were already compliant. Proper nouns and branded names (Coder Validated Architecture, JetBrains, File Browser, Dev Containers, Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the Premium license tier, and maturity labels (Beta, Experimental) are preserved. The four `Nk-users` pages become `Reference architecture: up to N users` (lowercase, matching the CVA landing page's own usage); the CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0 error(s)`. Linear: DOCS-484, DOCS-742 > This PR was created with AI assistance (Coder Agents).
4.8 KiB
4.8 KiB
title
| title |
|---|
| Conversation search syntax |
The chat list endpoint accepts a q query parameter for filtering
conversations. All filters use key:value syntax. Bare search terms
are rejected; use title: for title filtering or search: for
full-text search.
Filters
| Key | Values | Description |
|---|---|---|
title |
substring | Case-insensitive substring match. Quote multi-word values. |
archived |
true, false |
Filter by archived state. Default: false. |
has_unread |
true, false |
Conversations with unread assistant messages. |
pr_status |
draft, open, merged, closed |
Linked pull request state. Comma-separated for OR. |
diff_url |
URL | Match by associated diff URL. Quote values containing colons. |
pr |
positive integer | Exact PR number match. |
repo |
substring | Case-insensitive substring match against git remote origin or URL. Quote values containing colons. |
pr_title |
substring | Case-insensitive PR title substring match. Quote multi-word values. |
source |
created_by_me, shared_with_me |
Ownership scope. Default: created_by_me. Pass both values comma-separated to return owned and shared conversations. |
search |
text | Full-text search across chat titles, PR titles, PR numbers, and message content. Quote multi-word values. |
Multiple filters in one query combine with AND logic. search: cannot
be combined with title:, pr_title:, or pr:.
Full-text search
search: uses token-based PostgreSQL full-text search:
- Case-insensitive whole-word matching with AND semantics. Quoted
phrases,
OR, and-negation followwebsearch_to_tsqueryrules. - Message content matches English word stems (
refactormatchesrefactoring) and ignores English stopwords. Titles and PR titles do not stem. - No fuzzy, semantic, or prefix matching.
- Whole-number values also match exact PR numbers.
- A value with no searchable words (punctuation only) returns an empty list; an empty value returns HTTP 400.
- Results use the standard chat list ordering (pinned first, then most recently updated) and pagination, without match snippets.
- Message content becomes searchable shortly after it is written (background indexing, usually within 10 minutes). Titles and PR titles are searchable immediately.
Examples
# Title substring (case-insensitive)
?q=title:deploy
# Multi-word title (URL-encode the space or use +)
?q=title:my+project
# Unread conversations
?q=has_unread:true
# Conversations with open or draft PRs
?q=pr_status:open,draft
# Filter by diff URL (quote values containing colons)
?q=diff_url:"https://github.com/coder/coder/pull/123"
# Combine filters
?q=title:refactor+has_unread:true+pr_status:merged
# Conversations linked to PR #42
?q=pr:42
# Conversations for a specific repository
?q=repo:coder/coder
# Conversations with a specific PR title
?q=pr_title:"fix auth bug"
# Conversations shared with you, plus your own
?q=source:created_by_me,shared_with_me
# Full-text search across titles, PR titles, and messages
?q=search:"kubernetes restart"
# Combine full-text search with other filters
?q=search:refactor+pr_status:open
Notes
title:,repo:, andpr_title:use ILIKE matching.%and_act as wildcards.pr_status:draftmeans the PR is open and marked as a draft.pr_status:openmeans the PR is open and not a draft.- Conversations without a linked diff status are excluded when
pr_status,pr,repo, orpr_titleis set. Therepo:filter also matches chats tracking a branch with no PR. - Unrecognized keys, bare terms, or combining
search:withtitle:,pr_title:, orpr:return HTTP 400 with a validation error.