Docs Getting started Overview Overview What knowledge-lint checks, where it stops, and how this documentation is organised.
knowledge-lint validates a knowledge base made of Markdown files with YAML frontmatter: a
directory of category folders, declared in one _types.yml. It is a single Rust binary, so it
behaves the same locally and in CI, without an interpreter or package manager.
It was extracted from ai-knowledge-template ,
but works with any knowledge directory that follows the same conventions.
What it checks
Every folder is a declared category, and every entry’s type matches its category.
Required frontmatter fields, allowed status values and valid last_reviewed dates.
Overdue reviews for entries that are still marked active.
related links and _attachments.yml references point to files that exist.Secrets are SOPS-encrypted, and entries contain no plaintext keys.
What is checked depends on the kind a category has in _types.yml:
Focus What knowledge-lint checks per category kind What knowledge-lint checks per category kind Every folder in the knowledge directory needs a category in _types.yml; an undeclared folder is an error. knowledge_entry categories hold Markdown entries, checked for the required fields title, source and created, an allowed status, the category's type, a valid last_reviewed date and its review interval, related links, plaintext keys (4 private-key headers as errors, 6 API-key prefixes as warnings) and a file size above 500 KB (a warning). sops_secret categories need a top-level sops: key in every file; nothing is decrypted. assets categories are not checked; their files are referenced from _attachments.yml, which is checked for existing paths, reachable URLs (a warning) and existing referenced_by entries. knowledge/ → Undeclared folder knowledge/ → knowledge_entry knowledge_entry → Required fields knowledge_entry → status knowledge_entry → type knowledge_entry → last_reviewed knowledge_entry → related knowledge_entry → Plaintext keys knowledge_entry → File size knowledge/ → sops_secret sops_secret → sops: key knowledge/ → assets assets → No content checks knowledge/ → _attachments.yml _attachments.yml → path _attachments.yml → referenced_by knowledge/ – folders declared in _types.yml knowledge/ folders declared in _types.yml Undeclared folder – error Undeclared folder error ! knowledge_entry – Markdown entries knowledge_entry Markdown entries Required fields – title, source, created Required fields title, source, created status – one of status_values status one of status_values type – matches the category type matches the category last_reviewed – valid date, review interval last_reviewed valid date, review interval related – linked files exist related linked files exist Plaintext keys – 4 headers, 6 prefixes Plaintext keys 4 headers, 6 prefixes File size – warning above 500 KB File size warning above 500 KB sops_secret – SOPS files sops_secret SOPS files sops: key – structural, never decrypted sops: key structural, never decrypted assets – plain files assets plain files No content checks – listed in _attachments.yml No content checks listed in _attachments.yml _attachments.yml – attachment list _attachments.yml attachment list path – file exists, URL answers path file exists, URL answers referenced_by – entries exist referenced_by entries exist ! Critical Source: src/lint.rs, src/checks/knowledge_entry.rs, src/checks/secret_scan.rs, src/checks/secrets.rs, src/checks/attachments.rs
Show chart data Data for What knowledge-lint checks per category kind Node Level Parent Role Children knowledge/ 1 Undeclared folder, knowledge_entry, sops_secret, assets, _attachments.yml Undeclared folder 2 knowledge/ critical knowledge_entry 2 knowledge/ Required fields, status, type, last_reviewed, related, Plaintext keys, File size Required fields 3 knowledge_entry status 3 knowledge_entry type 3 knowledge_entry last_reviewed 3 knowledge_entry related 3 knowledge_entry Plaintext keys 3 knowledge_entry File size 3 knowledge_entry sops_secret 2 knowledge/ sops: key sops: key 3 sops_secret assets 2 knowledge/ No content checks No content checks 3 assets _attachments.yml 2 knowledge/ path, referenced_by path 3 _attachments.yml referenced_by 3 _attachments.yml
Focus What knowledge-lint checks per category kind What knowledge-lint checks per category kind Every folder in the knowledge directory needs a category in _types.yml; an undeclared folder is an error. knowledge_entry categories hold Markdown entries, checked for the required fields title, source and created, an allowed status, the category's type, a valid last_reviewed date and its review interval, related links, plaintext keys (4 private-key headers as errors, 6 API-key prefixes as warnings) and a file size above 500 KB (a warning). sops_secret categories need a top-level sops: key in every file; nothing is decrypted. assets categories are not checked; their files are referenced from _attachments.yml, which is checked for existing paths, reachable URLs (a warning) and existing referenced_by entries. knowledge/ → Undeclared folder knowledge/ → knowledge_entry knowledge_entry → Required fields knowledge_entry → status knowledge_entry → type knowledge_entry → last_reviewed knowledge_entry → related knowledge_entry → Plaintext keys knowledge_entry → File size knowledge/ → sops_secret sops_secret → sops: key knowledge/ → assets assets → No content checks knowledge/ → _attachments.yml _attachments.yml → path _attachments.yml → referenced_by knowledge/ – folders declared in _types.yml knowledge/ folders declared in _types.yml Undeclared folder – error Undeclared folder error ! knowledge_entry – Markdown entries knowledge_entry Markdown entries Required fields – title, source, created Required fields title, source, created status – one of status_values status one of status_values type – matches the category type matches the category last_reviewed – valid date, review interval last_reviewed valid date, review interval related – linked files exist related linked files exist Plaintext keys – 4 headers, 6 prefixes Plaintext keys 4 headers, 6 prefixes File size – warning above 500 KB File size warning above 500 KB sops_secret – SOPS files sops_secret SOPS files sops: key – structural, never decrypted sops: key structural, never decrypted assets – plain files assets plain files No content checks – listed in _attachments.yml No content checks listed in _attachments.yml _attachments.yml – attachment list _attachments.yml attachment list path – file exists, URL answers path file exists, URL answers referenced_by – entries exist referenced_by entries exist ! Critical Source: src/lint.rs, src/checks/knowledge_entry.rs, src/checks/secret_scan.rs, src/checks/secrets.rs, src/checks/attachments.rs
Show chart data Data for What knowledge-lint checks per category kind Node Level Parent Role Children knowledge/ 1 Undeclared folder, knowledge_entry, sops_secret, assets, _attachments.yml Undeclared folder 2 knowledge/ critical knowledge_entry 2 knowledge/ Required fields, status, type, last_reviewed, related, Plaintext keys, File size Required fields 3 knowledge_entry status 3 knowledge_entry type 3 knowledge_entry last_reviewed 3 knowledge_entry related 3 knowledge_entry Plaintext keys 3 knowledge_entry File size 3 knowledge_entry sops_secret 2 knowledge/ sops: key sops: key 3 sops_secret assets 2 knowledge/ No content checks No content checks 3 assets _attachments.yml 2 knowledge/ path, referenced_by path 3 _attachments.yml referenced_by 3 _attachments.yml
Each check and its exact message are listed under Rules .
Where it stops
knowledge-lint checks structure and metadata, not prose. It does not decrypt secrets, does not
judge whether an entry is correct, and does not let you rename the frontmatter fields.
How the docs are organised
Edit this page on GitHub · Docs for v0.1.0