Support external vault roots across tooling
This commit is contained in:
@@ -11,8 +11,18 @@ Markdown is the source of truth; `index/graph.json` is a generated navigation
|
||||
index. Use this skill to answer questions FROM the vault and to surface the
|
||||
exact notes that back the answer.
|
||||
|
||||
Obey `AGENTS.md` (read them if not loaded this
|
||||
session). This skill is read-only — do not modify notes here.
|
||||
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 generated index is stale. Skills and operational
|
||||
documentation belong to the framework; never infer the data vault from this
|
||||
skill's file location.
|
||||
|
||||
## Layout (PARA)
|
||||
|
||||
@@ -25,84 +35,58 @@ session). This skill is read-only — do not modify notes here.
|
||||
03_resources/repos/repo-landscape.md index of documented repos
|
||||
04_archives/ inactive items
|
||||
index/graph.json generated graph (nodes + edges)
|
||||
README.md vault hub; AGENT_QUERY_GUIDE.md graph query reference
|
||||
|
||||
```
|
||||
|
||||
Every note carries taxonomy frontmatter: `id`, `title`, `type`
|
||||
(`hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference`, enforced by
|
||||
`generate-graph.py --validate`), `status`
|
||||
`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 `make validate-graph`.
|
||||
by `id`. Legacy `[[wiki links]]` are rejected by `refresh_graph(validate=true)`.
|
||||
|
||||
## 1. Orient
|
||||
|
||||
Start broad, then narrow:
|
||||
|
||||
- `README.md` — vault hub and entry points.
|
||||
- `03_resources/repos/repo-landscape.md` — index of every documented repo, grouped.
|
||||
- `02_areas/ways-of-working.md` — global engineering policy.
|
||||
- `03_resources/meta/taxonomy.md` — what the frontmatter fields and PARA buckets mean.
|
||||
|
||||
For a repo question, read `03_resources/repos/<repo>/info.md` directly
|
||||
(`ls 03_resources/repos/` to confirm the repo is documented; if absent, say so —
|
||||
it is not yet in the vault).
|
||||
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
|
||||
|
||||
`index/graph.json` is for navigation by tag / type / repo / links. Use `jq`.
|
||||
Full schema and more examples are in `AGENT_QUERY_GUIDE.md`.
|
||||
Use the MCP tools directly:
|
||||
|
||||
```bash
|
||||
# all documented repos
|
||||
jq -r '.nodes[].repo' index/graph.json | sort -u
|
||||
| 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>")` |
|
||||
|
||||
# every note in one repo
|
||||
jq -r '.nodes[] | select(.repo=="tenant-controller") | "\(.id)\t\(.path)"' index/graph.json
|
||||
|
||||
# all notes of a type (e.g. policies, decisions, projects)
|
||||
jq -r '.nodes[] | select(.type=="policy") | "\(.id)\t\(.path)"' index/graph.json
|
||||
|
||||
# notes carrying a tag
|
||||
jq -r '.nodes[] | select(.tags[]? == "kcp") | "\(.id)\t\(.path)"' index/graph.json
|
||||
|
||||
# most-linked (central) notes
|
||||
jq -r '.nodes | sort_by(-(.inbound_count // 0))[] | "\(.inbound_count // 0)\t\(.id)"' index/graph.json | head
|
||||
|
||||
# outgoing links from a note, with relationship type + annotation
|
||||
NOTE_ID="repo/controller-util/info"
|
||||
jq -r --arg id "$NOTE_ID" '.edges[] | select(.from==$id) | "\(.type)\t\(.to)\t\(.annotation)"' index/graph.json
|
||||
|
||||
# incoming links to a note (who references it, and how)
|
||||
jq -r --arg id "$NOTE_ID" '.edges[] | select(.to==$id) | "\(.type)\t\(.from)\t\(.annotation)"' index/graph.json
|
||||
|
||||
# edges of a specific relationship type (e.g. supersedes, depends-on)
|
||||
jq -r '.edges[] | select(.type=="supersedes") | "\(.from) -> \(.to)"' index/graph.json
|
||||
```
|
||||
|
||||
Full-text fallback when you do not know the tag/type/id:
|
||||
|
||||
```bash
|
||||
grep -rIl "<term>" 01_projects 02_areas 03_resources 04_archives
|
||||
```
|
||||
`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. Open the
|
||||
matched `.path` files and read them. Follow the typed markdown links
|
||||
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, you may regenerate read-only:
|
||||
`python3 scripts/generate-graph.py` (does not touch Markdown). Do not commit.
|
||||
If the graph looks stale or a path is missing, use `refresh_graph`. This updates
|
||||
only the generated index; it does not touch Markdown. Do not 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/repos/gittea/info.md`) and/or `id` so the user can verify.
|
||||
`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
|
||||
|
||||
Reference in New Issue
Block a user