> ## 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.

# MCP: Knowledge and governance

> The context tools over MCP: retrieve and read Topics, write and edit them, walk the graph, audit health, and move a Note through the Note to Knowledge lifecycle.

This is the Knowledge plane over MCP: the tools an AI client uses to read the team's context before acting and to write a clean Note after learning. For setup, authentication, and the OAuth scopes referenced below, see [MCP & OAuth](/mcp/overview).

Every read carries a flat **`trust`** field (`reviewed` = Knowledge, the team's source of truth; `proposed` / `draft` = a Note, a hint), so a client can key on `trust === "reviewed"` directly.

## Retrieval and reading

Start with `driftless_context_retrieve` when you have a task but no slug. Bodies come back **brief** by default (the durable why, not the full `content`); fetch one full body with `driftless_context_get`.

| Tool                              | Purpose                                               | Main params                        | Returns                                       |
| --------------------------------- | ----------------------------------------------------- | ---------------------------------- | --------------------------------------------- |
| `driftless_context_retrieve`      | Ranked, drifted-first context for a task and/or files | `task`, `files`, `view`, `limit`   | `{ shown, has_more, next_action, results[] }` |
| `driftless_context_search`        | Full-text search, relevance-ranked                    | `query`, `tags`, `stale`, `limit`  | top 5 summaries, `has_more`                   |
| `driftless_context_list`          | List topics, drifted-first                            | `status`, `stale`, `tags`, `limit` | top 40 summaries                              |
| `driftless_context_get`           | One topic by slug (full body)                         | `topic`, `view`                    | the full topic                                |
| `driftless_context_get_for_files` | Match topics to file paths                            | `files`, `view`, `limit`           | top 10, brief                                 |

Permission: `context:read`. Availability: Available.

```text theme={"theme":"github-light"}
driftless_context_retrieve task:'harden the webhook handler' files:['src/webhooks/handler.ts']
  → { results: [ { slug, trust, why_matched, confidence } ], has_more }
```

## Writing and editing

| Tool                       | Purpose                                         | Main params                           | Notes                       |
| -------------------------- | ----------------------------------------------- | ------------------------------------- | --------------------------- |
| `driftless_context_create` | Create a topic (defaults to Up for review)      | `title`, `content`, `pattern`, `rels` | returns `anchor_validation` |
| `driftless_note_add`       | Capture a private Note (stays a draft)          | `content`, `project_id`, `card_id`    | never auto-submitted        |
| `driftless_context_update` | Append-safe update                              | `topic`, fields, `rels`               | returns `anchor_validation` |
| `driftless_context_delete` | Delete a topic (destructive)                    | `topic`                               | irreversible                |
| `driftless_context_merge`  | Fold a duplicate into a survivor                | `source`, `into`                      | archives the source         |
| `driftless_context_share`  | Publish a public page and/or share with members | `topic`, `to_web`, `with_members`     | sharing, not merging        |

Permissions: `topics:create` / `topics:write`; `work:write` for merge and share. Availability: Available. Write responses carry `anchor_validation` (`ok` / `overbroad` / `zero`), which never blocks the write.

```json theme={"theme":"github-light"}
{ "topic": "refund-flow", "rels": [ { "to": "billing-flow", "type": "depends_on" } ] }
```

## Graph and health

| Tool                          | Purpose                     | Main params      | Returns                           |
| ----------------------------- | --------------------------- | ---------------- | --------------------------------- |
| `driftless_context_relations` | A topic's typed relations   | `topic`          | incoming + outgoing               |
| `driftless_context_graph`     | Local relation graph        | `topic`, `depth` | nodes + edges                     |
| `driftless_context_doctor`    | Audit the context layer     | (none)           | stale / zombie / orphaned / draft |
| `driftless_context_coverage`  | Source areas with no topic  | (none)           | the coverage gaps                 |
| `driftless_context_events`    | Recent activity for a topic | `topic`          | the event stream                  |

Permission: `context:read`. Availability: Available.

## Registries: tags and areas

| Tool              | Actions                              | Purpose                                           |
| ----------------- | ------------------------------------ | ------------------------------------------------- |
| `driftless_tags`  | `list`, `create`, `delete`           | The tag registry (per-tag counts; curation)       |
| `driftless_areas` | `list`, `create`, `update`, `delete` | The area registry (the domains topics file under) |

Permissions: `list` is member-level; `create` / `update` / `delete` need `work:write`. Availability: Available.

## Governance

A topic becomes Knowledge only once an owner or admin merges it. An MCP client always proposes; it can merge only with owner/admin authority, and only when the authorizing person explicitly asks.

| Tool                                | Purpose                                     | Main params                   | Permission                   |
| ----------------------------------- | ------------------------------------------- | ----------------------------- | ---------------------------- |
| `driftless_context_propose`         | Put a Note up for review (draft → proposed) | `topic`                       | `work:write`                 |
| `driftless_context_approve`         | Merge into Knowledge (proposed → reviewed)  | `topic`                       | owner/admin, only when asked |
| `driftless_context_create_proposal` | Open a Suggested edit to existing Knowledge | `topic`, `summary`, `content` | `work:write`                 |
| `driftless_context_proposals`       | List Notes up for review (the review queue) | (none)                        | member                       |

Availability: Available. Automatic merge or auto-approval is Not available: a person always decides.

```text theme={"theme":"github-light"}
driftless_context_propose topic:'token-verification'
```

## Permissions

| Scope           | Covers                                                               |
| --------------- | -------------------------------------------------------------------- |
| `context:read`  | Read topics, retrieve, search, list, graph, doctor, coverage, events |
| `topics:create` | Create topics                                                        |
| `topics:write`  | Update existing topics                                               |
| `work:write`    | Tag/area curation, merge, share, propose, and Suggested edits        |
| `context:diff`  | Read topic diff for local changes                                    |

Merging into Knowledge additionally requires owner/admin authority, not just a scope.

## Related

* [Topics](/concepts/topics), [Governance](/concepts/governance), [Drift](/concepts/drift) - the concepts.
* [Govern agent learning](/guides/govern-agent-learning), [Clean workspace context](/guides/clean-workspace-context) - the workflows.
* [CLI: Context Commands](/cli/context) - the same surface from the terminal.
* [MCP & OAuth](/mcp/overview) - setup, auth, and scopes.