Vault Health & Permissions

Two related controls live together in the Agents workspace: Vault Health (what's broken or stale) and Permissions (what an AI can or can't do). Both run against your live vault.

Vault Health

Vault Health is a single-page integrity report. It runs on demand and surfaces the things in your vault that need attention.

What it checks

CheckWhat it finds
Orphan pagesPages with no inbound or outbound wikilinks
Broken linksWikilinks pointing to pages that don't exist
Recent errorsFailed MCP tool calls in the last activity window
Unlinked contentPages that exist but never appear in another page's body
Inactive sessionsMCP clients that haven't been used recently

The health score

Vault Health computes an overall score from 0 to 100:

score = max(0, 100 − (orphan_pages × 2) − pending_proposals − (recent_errors × 3))

A score of 100 means clean (no orphans, no pending proposals, no errors). Scores drift down as orphans accumulate, proposals pile up unreviewed, and tool calls fail. The numeric score isn't a goal in itself — it's a quick signal of whether the vault needs attention.

Acting on findings

Each health finding has a recommendation:

  • Orphan page — link it from a relevant page, or move it to capture/ for re-triage
  • Broken link — fix the wikilink, or remove it, or create the target page
  • Recent error — open Sessions & Activity, find the failing tool call, debug
  • Inactive session — revoke if it's no longer needed, from /account/connections or /account/api-keys

You can run health checks programmatically via the mindwiki_lint MCP tool or via GET /vault/health on the REST API. Both require read scope.

Permissions

The Permissions view shows the matrix of capabilities AI clients have against your vault.

What's actually enforced

The current permission model is built on token scopes:

CapabilityWhat it requires
Read vault (search, read pages, list, ask, similar, graph, lint, export)read scope
Write vault (capture, create page, update page, delete page, rebuild index)write scope
Create proposals (the soft-touch alternative to direct writes)write scope

The table above describes personal API key scopes. OAuth grants use mcp:read, mcp:capture, and mcp:write. The legacy mcp grant allows all three; mcp:write also permits capture. Scope checks and vault agent permissions both apply. Read access does not permit saving captures or editing pages.

Reviewing permissions

The Permissions view in the Agents workspace lists active scopes and the operations they enable, plus indicators for capabilities that are reserved or in development:

  • Active — fully working today (read vault, create proposals, capture, write pages)
  • Restricted — not enabled by default (delete and archive operations on critical pages)
  • Roadmap — protected folders and per-folder permissions are not shipped yet

Tightening permissions

If you want an AI client to read but not write:

  1. Go to mindwiki.io/account/api-keys.
  2. Create a new key with only the read scope selected.
  3. Use that key in the AI client instead of a full read+write key.

Read-only keys cannot call mindwiki_write_page, mindwiki_capture, mindwiki_update_index, or mindwiki_create_proposal. REST scope failures return HTTP 403. MCP scope failures are returned through the MCP error response; clients should inspect the error rather than rely only on the HTTP status.

For OAuth connections, choose read-only or read and capture on MindWiki’s approval page when available for the requested grant. Revoke an existing connection in Account → Connections and reconnect to choose different access. Muse uses this planned approval journey; directory availability is pending.

Auditing what an AI did

Every tool call is logged. See Sessions & Activity for the full audit trail.

Best practices

  • Check Vault Health weekly. Three minutes, occasionally productive surprises.
  • Mint scoped keys. Don't use one key everywhere. A read-only key for browsers / dashboards, a write key for capture automations.
  • Revoke aggressively. When a tool no longer needs access, kill its key. The cost is one click; the upside is reduced surface area.

Where to go next