Cursor rule

1---
2description: "Knowledge-vault authoring conventions for OKF bundles: this project's frontmatter contract, link rules, verified_against drift discipline, and the vault-sync loop. Activate when authoring or maintaining knowledge-vault concepts."
3alwaysApply: false
4---
5 
6# Knowledge Vault Conventions
7 
8Activate this rule when writing or maintaining concepts in an OKF knowledge vault.
9 
10A vault is a **map, not the territory**. Source-of-truth docs stay where they live; code stays
11authoritative over everything, including the vault. A concept is a ~50-line map-card that
12summarizes and links — it never restates its source.
13 
14## The Frontmatter Contract
15 
16Required on every concept: `type`, `title`, `description` (≤160 chars), `tags`, `timestamp`,
17`status`.
18 
19`timestamp` is **the date the concept was last verified against its sources** — not the date the
20file was edited. Optional: `resource`, `domain`, `ticket`, `sources`, `docs`, `verified_against`.
21 
22**YAML subset only** — scalars, double-quoted strings, inline lists, and two-space block lists. No
23nested maps, no multiline scalars. This is what keeps the validator dependency-free.
24 
25## Link Rules
26 
271. Relative markdown links only. **No wikilinks**, no leading-slash paths, no repo-host URLs for
28   files in this repo.
292. Concept-to-concept links never leave the bundle.
303. Links that leave the bundle appear only under `## Citations` (`index.md` and `guide` types are
31   exempt — they are navigation).
324. **Link only to concept IDs listed in `_meta/manifest.json`.** If the concept does not exist,
33   name it in prose and report it as a suggestion. **Never invent a link.**
34 
35Rule 4 is the one that matters most when several agents author in parallel. Without it you get a
36graph of plausible, confident, broken references.
37 
38## Writing Rules
39 
40- **Summarize, never duplicate.** If you are restating more than a paragraph, stop and link.
41- **Code wins.** Name the helper actually called, not the one the code *should* call. When code
42  contradicts docs, document the code and note the discrepancy.
43- Section H2s must exactly match the type's template, in order. Do not add, remove, or rename.
44- Environment variable names may be mentioned; values never.
45- No emoji in concept files.
46 
47## Drift Discipline
48 
49Staleness is computed, not felt: a concept is stale if and only if a path in its `resource` or
50`sources` changed since the manifest's `baseline_sha`.
51 
52**A citation is not re-verification.** Linking a concept from somewhere new does not make its
53claims fresher. Only re-deriving it from source bumps `timestamp` and `verified_against`.
54 
55Deleted source → `status: deprecated`, never a file deletion; inbound links must be cleaned first.
56 
57## Before You Commit
58 
59```bash
60node knowledge-vault/scripts/validate-vault.mjs --vault <vault>
61```
62 
63Must exit 0. Prepend a dated entry to `log.md` and bump the `timestamp` of every concept you
64actually re-verified.
65 
66## References
67 
68- `knowledge-vault/docs/GUIDE.md` -- the method and why each rule exists
69- `knowledge-vault/docs/ADOPTION-PLAYBOOK.md` -- running your first build
70- `knowledge-vault/templates/starter-bundle/_meta/CONVENTIONS.md` -- the full constitution
71