Support external vault roots across tooling
This commit is contained in:
+18
-20
@@ -26,6 +26,9 @@ through MCP.
|
||||
|
||||
## MCP tools
|
||||
|
||||
- `read_instructions` — framework `AGENTS.md` and `AGENT_QUERY_GUIDE.md`.
|
||||
Call this first and read both; report failure if unavailable. These documents
|
||||
live outside the data graph, and the server locates them without a guessed path.
|
||||
- `graph_summary` — overview of the graph: counts, repo scopes, the tag
|
||||
vocabulary (`by_tag`, most frequent first) and central nodes.
|
||||
- `graph_search_nodes` — find nodes by tag / type / repo / id / text.
|
||||
@@ -39,7 +42,7 @@ through MCP.
|
||||
Given a **topic or task**, return a complete, cited briefing:
|
||||
|
||||
1. **Orient** — what the vault holds and where the topic likely lives (`graph_summary`).
|
||||
2. **Find** — every relevant note, via `graph_search_nodes` (+ text-search fallback).
|
||||
2. **Find** — every relevant note, via `graph_search_nodes`, then `read_note` for candidate note bodies.
|
||||
3. **Read** — the actual Markdown via `read_note`; the answer is there, not in the index.
|
||||
4. **Follow links** — traverse internal links (via `graph_neighbors`) AND external URLs.
|
||||
5. **Synthesize** — one briefing, every claim cited to a note path/id.
|
||||
@@ -47,15 +50,15 @@ Given a **topic or task**, return a complete, cited briefing:
|
||||
## Vault layout (PARA)
|
||||
|
||||
```
|
||||
01_projects/ active efforts with a goal and an end
|
||||
02_areas/ ongoing standards: policies, value-stream areas, decisions (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
|
||||
README.md vault hub
|
||||
01_projects/ active efforts with a goal and an end
|
||||
02_areas/ ongoing responsibilities and standards
|
||||
03_resources/ reference material
|
||||
04_archives/ inactive items
|
||||
```
|
||||
|
||||
Framework owns agents, skills and tooling. The MCP server selects the data vault;
|
||||
its directory is independent of this agent definition's location.
|
||||
|
||||
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`
|
||||
@@ -68,23 +71,18 @@ Legacy `[[wiki links]]` are rejected by the graph validator and must not be writ
|
||||
Start broad with `graph_summary` to see node counts, repo scopes, the tag
|
||||
vocabulary and the most-central notes. Its `by_tag` list is the only place the
|
||||
tag spellings are visible — read it before filtering by `tag`, which matches
|
||||
verbatim. Then `read_note` the entry points:
|
||||
|
||||
- vault hub (`README.md`) — entry points.
|
||||
- `03_resources/repos/repo-landscape.md` — index of documented repos, grouped.
|
||||
- `02_areas/ways-of-working.md` — global engineering policy.
|
||||
- `03_resources/meta/taxonomy.md` — frontmatter fields and PARA buckets.
|
||||
|
||||
For a repo topic, `read_note` on `03_resources/repos/<repo>/info.md`. If
|
||||
`graph_search_nodes` returns no node for it, say it is not yet documented.
|
||||
verbatim. Find hubs with `graph_search_nodes(type="hub")` and read relevant
|
||||
ones with `read_note`. Discover policies and repo scopes through the graph;
|
||||
do not assume a root README or any particular taxonomy subfolders exist.
|
||||
If no relevant node exists, say the topic is not yet documented.
|
||||
|
||||
## 2. Find — query the graph
|
||||
|
||||
Use `graph_search_nodes` to locate notes:
|
||||
|
||||
- by **repo** — every note tied to a repo (e.g. `tenant-controller`).
|
||||
- by **repo** — every note tied to a repo (e.g. `<repo>`).
|
||||
- by **type** — `policy`, `decision`, `feature`, `guideline`, `project`, ...
|
||||
- by **tag** — e.g. `kcp`. Exact match; take the spelling from `by_tag`.
|
||||
- by **tag** — e.g. a value from `by_tag`. Exact match; take the spelling from `by_tag`.
|
||||
- by **text** — `query` matches a node's id, title, path and tags, not the note
|
||||
body. Widen with a tag or repo filter rather than a longer phrase.
|
||||
|
||||
@@ -119,7 +117,7 @@ Links are the intended navigation. Traverse, do not guess.
|
||||
|
||||
- Answer the topic/task directly from what the notes say.
|
||||
- Cite every claim by vault-relative `path` (e.g.
|
||||
`03_resources/repos/controller-util/info.md`) and/or `id`.
|
||||
`03_resources/<resource>/index.md`) and/or `id`.
|
||||
- Separate vault facts from external-source facts (give the URL) and from your
|
||||
own inference.
|
||||
- Flag `status: draft`/`deprecated` notes. If the vault does not cover part of
|
||||
|
||||
+19
-22
@@ -25,6 +25,8 @@ already captured into `raw/` (a PDF, an image) at the absolute path
|
||||
## MCP tools
|
||||
|
||||
Read:
|
||||
- `read_instructions` — framework `AGENTS.md` and `AGENT_QUERY_GUIDE.md`,
|
||||
available without a graph or a data-vault copy of either document.
|
||||
- `graph_summary` — counts, repo scopes, the tag vocabulary (`by_tag`), most-linked notes.
|
||||
- `graph_search_nodes` — find notes by tag / type / repo / id / free text.
|
||||
- `graph_neighbors` — inbound + outbound links of a node, with edge `type` and `annotation`.
|
||||
@@ -42,8 +44,9 @@ Write:
|
||||
- `edit_note(path, old_string, new_string, replace_all?)` — exact-string edit,
|
||||
for backlinks into notes that already exist.
|
||||
|
||||
Publish:
|
||||
- `refresh_graph(validate=true)` — regenerate and validate `index/graph.json`.
|
||||
|
||||
Publish only when the caller explicitly authorizes it:
|
||||
- `git_commit(message, paths[])` — stage the named paths and commit.
|
||||
- `git_push(remote?, branch?)` — push to `origin` / current branch.
|
||||
|
||||
@@ -55,21 +58,14 @@ Invoke the skill first, then follow it step by step:
|
||||
Skill(knowledge-base-ingest-resource)
|
||||
```
|
||||
|
||||
The skill is the source of truth for the procedure. Translate each of its shell
|
||||
steps into the MCP equivalent:
|
||||
Then call `read_instructions` and read both documents before any vault mutation.
|
||||
The MCP server locates the framework; no filesystem access or path guessing is
|
||||
needed. If instructions cannot be loaded, report the failure before writing.
|
||||
Use the skill's explicit graph queries to discover additional vault policies.
|
||||
Apply task-specific instructions supplied by the caller as well.
|
||||
|
||||
| Skill step | Your call |
|
||||
|-------------------------------------|--------------------------------------------------|
|
||||
| check slug not taken / find matches | `graph_search_nodes`, `read_note` |
|
||||
| `printf … > raw/source.url` | `write_note("03_resources/<slug>/raw/source.url", …)` |
|
||||
| save fetched page to `raw/page.md` | `WebFetch` → `write_note(".../raw/page.md", …)` |
|
||||
| `cp "<source-path>" raw/` | `capture_raw(path=".../raw/<file>", source_path="<source-path>")` |
|
||||
| `curl -fsSL "<url>" -o raw/<file>` | `capture_raw(path=".../raw/<file>", url="<url>")` |
|
||||
| read the captured binary | `Read(<absolute_path from capture_raw>)` |
|
||||
| write the topic + index notes | `write_note` |
|
||||
| backlink an existing note | `edit_note` |
|
||||
| `make graph` | `refresh_graph(validate=true)` |
|
||||
| `git add <path>` (one by one) | `git_commit(message, paths=[…])` |
|
||||
The skill is the source of truth for the procedure. Follow its MCP calls directly;
|
||||
do not translate missing operations into shell commands.
|
||||
|
||||
## Operating rules
|
||||
|
||||
@@ -84,10 +80,10 @@ steps into the MCP equivalent:
|
||||
Never fabricate a page or transcript — if the fetch or capture fails, stop and
|
||||
report what is missing. Verify the capture landed: the result carries `bytes`
|
||||
and `sha256`.
|
||||
- **YouTube is still out of reach.** Transcripts need `yt-dlp` or
|
||||
`youtube-transcript-api`, which are shell tools you do not have. Capture the
|
||||
URL into `raw/source.url`, then hand the video to **the-collector** rather than
|
||||
inventing transcript text.
|
||||
- **YouTube transcripts must be supplied.** Capture a supplied transcript with
|
||||
`capture_raw` or `write_note`. If none is supplied, preserve the source URL and
|
||||
report the missing transcript before writing content notes. Do not run shell
|
||||
extractors or invent transcript text.
|
||||
- **Link, don't duplicate.** Search the graph before writing a topic note. If the
|
||||
vault already covers the topic, link it instead of creating a second note.
|
||||
- **Typed markdown links only.** `[title](note-id){"type":"…","link-info":"…"}`.
|
||||
@@ -100,9 +96,10 @@ steps into the MCP equivalent:
|
||||
- **Name every path you commit.** `git_commit` takes an explicit list; wildcard
|
||||
staging is rejected by the server. Include the resource folder, every
|
||||
backlinked note, and `index/graph.json`.
|
||||
- **Push straight to `main`.** This vault takes ingests as direct commits; no
|
||||
branch, no PR. Commit with Conventional Commits (`feat: ingest <resource>`),
|
||||
then `git_push`. If the caller says "don't push", stop after the commit.
|
||||
- **Follow the caller's publishing instructions.** Do not commit or push unless
|
||||
explicitly authorized. Use the selected vault's branch and review policy;
|
||||
do not assume a branch name or a direct-push workflow. Without publishing
|
||||
authorization, report the changed paths and validation result.
|
||||
|
||||
## Report
|
||||
|
||||
|
||||
Reference in New Issue
Block a user