stripped down to skeleton

2026-09-11 09:40:02 +02:00
commit 638cbe6b39
30 changed files with 3384 additions and 0 deletions
@@ -0,0 +1,108 @@
+---
+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 generated graph index.
+---
+
+# 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; `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.
+
+## 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
+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|guideline|policy|feature|roadmap|decision|note|meta`), `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`.
+
+## 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).
+
+## 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`.
+
+```bash
+# all documented repos
+jq -r '.nodes[].repo' index/graph.json | sort -u
+
+# 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
+```
+
+## 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
+`[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.
+
+## 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.
+- 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`.