> ## Documentation Index > Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt > Use this file to discover all available pages before exploring further. # Topics and relations > How topics connect code to team knowledge. ## What is a topic? A topic is the atomic unit of context in Driftless. It connects a slice of your system to the team's shared knowledge about it. The slice can be TypeScript, Python, Rust, Go, docs, config, infrastructure, or a workflow that spans repos. A topic has: | Field | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **slug** | Unique kebab-case **id** within the workspace (e.g., `auth-flow`, `billing-webhook`) | | **title** | Short human display name: a noun like a diagram node (`Auth`, `Billing`). Keep it to one or two words; the explanation goes in `what`/`content`, never the title | | **what** | Short summary of what this code does | | **how** | Short note (1-3 sentences) on the mechanism or approach. Long-form explanation belongs in `content`, not here | | **decisions** | Why choices were made (architecture decisions) | | **gotchas** | Traps, edge cases, things that will break | | **invariants** | Rules that must always hold true | | **required\_checks** | Checks to run before changing this code | | **ownership** | Team or individual responsible | | **content** | Full free-form body (Markdown). Can include diagrams, code snippets, references | | **anchors** | Patterns, files, and repos that link this topic to code | | **tags** | Workspace categories for discovery and filtering (e.g., `auth`, `billing`): filter with `context list/search --tag `, the MCP `tags` param, or the dashboard chips. Pre-create and curate them in the registry (`driftless tags`) | | **relations** | Typed links to other topics | | **classification** | Status (`reviewed`, `draft`) | Topics are **content-first**: the markdown `content` body IS the topic. The structured fields (`gotcha` / `decision` / `invariant` / `check`) are optional highlights layered on top. Add one only when you want that specific thing surfaced to the machine (the PR bot, a future agent's brief). Use `tags` to label and group topics. ## Create your first topic Start with the smallest useful topic: a durable note that explains one area well enough for a future human or agent to work there. ```bash theme={"theme":"github-light"} # The first topic should be something REAL: the gotcha that bit you, the # invariant nothing may break, anchored to the module it governs: driftless context add billing-webhooks --title "Webhooks" \ --what "Stripe webhook ingestion and its idempotency rules." \ --gotcha "Stripe delivers at-least-once: handlers must short-circuit on a seen event.id" \ --pattern "src/billing/webhooks/**" ``` Then enrich it as reality becomes clear: ```bash theme={"theme":"github-light"} driftless context update billing-webhooks \ --gotcha "..." \ --decision "..." \ --check "..." ``` ## Anchoring topics to code Topics are connected to code through glob patterns and file paths. This is language-agnostic: Driftless matches paths, not ASTs. When anchored code changes, the topic drifts. ```bash theme={"theme":"github-light"} # Anchor by glob pattern driftless context add api-guards --pattern "src/auth/**" # Multiple patterns for cross-cutting topics driftless context update api-guards --add-pattern "src/common/guards/**" # Anchor by exact file path driftless context add auth-flow --where src/auth/guard.ts # Anchor a document driftless context add architecture-decisions --file docs/decisions/auth.md ``` The CLI validates every pattern against your local checkout at write time: * `✓ pattern "src/auth/**" matches 12 files`: healthy anchor * `⚠ over-broad anchor`: pattern matches over 100 files; consider splitting * `✗ pattern "src/nonexistent/**" matches 0 files`: blocked; fix the glob **Discipline:** 5-40 matched files per topic is healthy. Fewer than 5 means you're fragmenting. More than 100 is a catch-all trap that nobody will maintain. If a topic covers too much, split it; if it covers too little, merge it. Remove anchors when they no longer make sense: ```bash theme={"theme":"github-light"} driftless context update auth-flow --remove-pattern "src/old-auth/**" ``` ## Topic classification A topic is content-first: the markdown `content` body IS the topic. Use `tags` to label and group topics. The only trust axis is `status`. ### Status: governance lifecycle A note becomes Knowledge once it's merged in: `draft → proposed → reviewed → archived`. `reviewed` is Knowledge; the read response carries `governance.authoritative`. Agents propose; merging is an owner/admin act (an agent runs it only when explicitly asked). See [Governance](/concepts/governance). | Status | Meaning | | ---------- | ----------------------------------------------------------------------------------------------------------- | | `draft` | Captured, not yet merged in: a hint (a Note), not truth | | `proposed` | Up for review | | `reviewed` | **Knowledge**: an owner/admin merged it in (or an agent did on their request); the agent treats it as truth | | `archived` | Retired | | `orphaned` | Code-driven (repo deleted), orthogonal to governance | ### Visibility A topic lives in the **workspace** and is visible to all its members. The exception is a **private Note** (a draft with `is_private` set), visible only to its creator until put up for review or un-marked. Need isolation between groups? Use a separate workspace. ## Typed relations Topics connect to each other through typed relations, building a semantic graph: | Relation | Meaning | | ------------ | ----------------------------------------------------- | | `depends_on` | Topic A depends on B | | `relates_to` | General association | | `supersedes` | Topic B replaces A | | `blocks` | A cannot proceed until B is done | | `implements` | A is the implementation of the pattern described in B | | `documents` | A documents or explains B | | `risk_for` | A introduces risk for B | ```bash theme={"theme":"github-light"} driftless context update auth-guard \ --rel depends_on:jwt-service \ --rel relates_to:role-decorator ``` ## Wiki-links Use `[[slug]]` syntax inside any free-text field (what, how, decisions, gotchas, invariants, content). The API auto-parses these into forward and backward references. ```bash theme={"theme":"github-light"} driftless context update billing-webhook \ --gotcha "Same idempotency race as [[stripe-webhook-ingest]]; deduplicate by event ID" ``` Both `billing-webhook` and `stripe-webhook-ingest` will show each other in their references when fetched. ## Cross-repo context A topic can span multiple repositories. When you run `driftless context update ` from any repo, that repo is added to the topic's `where_repos` list. Topics accumulate repos organically without manual wiring. Use one cross-repo topic when the same concept truly spans repos, for example `billing-contracts` across an API repo, worker repo, and frontend repo. Use separate topics plus relations when each repo has its own implementation details, for example `billing-api` `depends_on:billing-worker`. To explicitly link the current repo to a topic: ```bash theme={"theme":"github-light"} driftless context link auth-flow ``` ## The topic graph The topic graph is explorable from CLI and dashboard: ```bash theme={"theme":"github-light"} driftless context graph auth-flow # BFS graph from a topic, terminal output ``` The dashboard renders the full interactive graph. Nodes are topics, edges are typed relations. Click any node to see its full context and anchors.