---
name: knowledge-base-read
description: Read and query the knowledge-base vault — a personal docs-as-code knowledge database (PARA-organized). Use when the user asks what is known about a repo, policy, decision (ADR), area, or project; wants context before working in a repo; or asks to find/navigate notes by tag, type, repo, or link. Resolves the question against the Markdown notes and the graph the MCP server builds from them in memory.
---

# Read the Knowledge Base

This vault is a personal docs-as-code knowledge database,
organized with the [PARA method](https://fortelabs.com/blog/para/).
Markdown is the source of truth; the graph is a navigation index the MCP
server builds from it in memory (nothing on disk). Use this skill to answer questions FROM the vault and to surface the
exact notes that back the answer.

Call `read_instructions` on `knowledge-database` to read the framework's
`AGENTS.md` and `AGENT_QUERY_GUIDE.md` before querying the vault. These documents
are not data-vault nodes. If unavailable, report the missing instructions.
This skill is read-only — do not modify notes here.

## Vault access

The `knowledge-database` MCP server is the only interface for vault access. Use `graph_summary` to orient, `graph_search_nodes` to find notes,
`graph_neighbors` to traverse links, and `read_note` to read the source.
Use `refresh_graph` when the graph looks stale. Skills and operational
documentation belong to the framework; never infer the data vault from this
skill's file location.

## Layout (PARA)

```
01_projects/                 active efforts with a goal and an end
02_areas/                    ongoing standards: policies, value-stream areas, decisions
02_areas/decisions/          global ADRs
03_resources/meta/           taxonomy + note templates
03_resources/repos/<repo>/   per-repo info.md (+ decisions/)
03_resources/repos/repo-landscape.md   index of documented repos
04_archives/                 inactive items

```

Every note carries taxonomy frontmatter: `id`, `title`, `type`
(`hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference`, enforced by
`refresh_graph(validate=true)`), `status`
(`active|draft|deprecated`), `tags`, `last_reviewed`, optional `repo`. Notes are
linked with typed markdown links — `[text](note-id){"type":"…"}` — that resolve
by `id`. Legacy `[[wiki links]]` are rejected by `refresh_graph(validate=true)`.

## 1. Orient

Start broad, then narrow. Begin with `graph_summary`, then find hubs using
`graph_search_nodes(type="hub")` and read relevant ones with `read_note`.
Discover repo scopes and tags from the graph rather than assuming a particular
folder layout. An external data vault need not contain a root README or
framework operational documents.

## 2. Query the graph

Use the MCP tools directly:

| Need | Tool |
|------|------|
| Repo scopes, tag spellings, most-linked notes | `graph_summary` |
| Notes in a repo | `graph_search_nodes(repo="<repo>")` |
| Notes of a type | `graph_search_nodes(type="policy")` |
| Notes with a tag | `graph_search_nodes(tag="<tag>")` |
| Search ids, titles, paths and tags | `graph_search_nodes(query="<term>")` |
| Incoming/outgoing links, relationship types and annotations | `graph_neighbors(id="<note-id>")` |

`query` does not search note bodies. Read candidate notes with `read_note` and
follow their neighbors when metadata search is insufficient. Report any search
coverage limits; do not use filesystem or shell searches.

## 3. Read the source notes

The graph gives ids and paths; the ANSWER lives in the Markdown. Read matched
notes with `read_note(id="<note-id>")` or `read_note(path="<vault-relative-path>")`. Follow the typed markdown links
`[text](id){"type":"…"}`, resolving each to its node `path` to pull in related
policies, decisions, and repo info. Use each edge's `type` and `annotation` to
judge which links are worth following; links are the intended navigation, so
traverse them rather than guessing.

If the graph looks stale or a path is missing, use `refresh_graph`. This rebuilds
the in-memory graph; it does not touch Markdown. Nothing to commit.

## 4. Answer with citations

- Answer the question directly from what the notes say.
- Cite the backing notes by vault-relative `path` (e.g.
  `03_resources/<resource>/index.md`) and/or `id` so the user can verify.
- Distinguish vault facts from inference. If the vault does not cover it, say so
  plainly — do not invent. Note `status: draft`/`deprecated` when relevant.
- For "what links to / relates to X" questions, report the inbound/outbound
  edges you found, including each edge's relationship `type` and `annotation`.