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.
What is a topic?
A topic is the atomic unit of context in Driftless. It connects a slice of your codebase to the team’s shared knowledge about it.
A topic has:
| Field | Description |
|---|
| slug | Unique name within the workspace (e.g., auth-flow, billing-webhook) |
| what | Short summary of what this code does |
| how | Technical detail: the mechanism, the pattern |
| decisions | Why choices were made (architecture decisions) |
| gotchas | Traps, edge cases, things that will break |
| invariants | Rules that must always hold true |
| content | Full free-form body (Markdown). Can include diagrams, code snippets, references |
| anchors | Patterns, files, and repos that link this topic to code |
| tags | Labels for discovery (e.g., auth, security, billing) |
| relations | Typed links to other topics |
| classification | Origin, status, and kind |
Anchoring topics to code
Topics are connected to code through anchors. When anchored code changes, the topic goes stale.
# 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
driftless context update auth-flow --remove-pattern "src/old-auth/**"
Topic classification
Kinds
| Kind | Purpose |
|---|
code-context | How a module/service/package works (default) |
domain-map | Overview of a business domain and its boundaries |
decision | Architecture decision and rationale |
roadmap | Planned changes or migration path |
runbook | Operational procedures, incident response |
customer-insight | Why something exists because of a customer need |
integration-note | How a third-party integration works |
docs-note | Supplementary documentation |
operational-note | Deployment, monitoring, or infra details |
Status
| Status | Meaning |
|---|
reviewed | Actively maintained, confirmed accurate |
draft | Written but not yet reviewed |
suggested | Auto-generated by scanner, needs human review |
orphaned | No repo claims this topic anymore |
Origin
| Origin | Meaning |
|---|
auto | Generated by scanner |
manual | Written by a human |
doc | Anchored from a document file |
agent | Written by a coding agent |
Typed relations
Topics connect to each other through typed relations, building a semantic knowledge graph:
| Relation | Meaning |
|---|
depends_on | Topic A depends on B (e.g., auth-guard depends on jwt-service) |
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 is documentation for B |
risk_for | A introduces risk for B |
driftless context update auth-guard \
--rel depends_on:jwt-service \
--rel relates_to:role-decorator
driftless context update jwt-service \
--rel risk_for:token-refresh
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 in the graph.
driftless context update billing-webhook \
--gotcha "Same idempotency race as [[stripe-webhook-ingest]]; deduplicate by event ID"
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 <slug> from any repo, that repo is added to the topic’s where_repos list. Topics accumulate repos organically without manual wiring.
To explicitly link the current repo to a topic:
driftless context link auth-flow
driftless context get auth-flow --json | jq '.where_repos'
The knowledge graph
The topic graph is explorable from CLI and dashboard:
driftless context graph auth-flow # BFS graph from a topic, terminal output
