diff --git a/.agents/skills/docs-lint/SKILL.md b/.agents/skills/docs-lint/SKILL.md new file mode 100644 index 0000000..e6a8a9a --- /dev/null +++ b/.agents/skills/docs-lint/SKILL.md @@ -0,0 +1,25 @@ +--- +name: docs-lint +risk_class: read_only +inputs: [paths] +verification: "python3 .agents/skills/docs-lint/lint.py" +docs_update_checklist: [] +--- + +# Docs lint + +Check committed documentation against the mechanical rules in +[writing-style.md](../../shared/writing-style.md): banned vocabulary and broken relative markdown +links. Prose-voice rules are not machine-checkable — those stay a review responsibility. + +Run from the repo root: + + python3 .agents/skills/docs-lint/lint.py # default: knowledge/ .agents/ operations/ investigations/ plans/ + python3 .agents/skills/docs-lint/lint.py knowledge/wiki/containers/104-gitea.md + +Exit code is non-zero when any violation is found, so it can gate a commit. The banned-vocabulary +list mirrors `writing-style.md`; update both together if the standard changes. + +> **Known baseline.** The lab carries pre-existing broken links to destroyed/archived nodes (e.g. +> `124-authentik.md`, now `106-auth-outpost`). Clean those opportunistically; do not treat the +> current count as a regression from this skill. diff --git a/.agents/skills/docs-lint/lint.py b/.agents/skills/docs-lint/lint.py new file mode 100644 index 0000000..dc1261d --- /dev/null +++ b/.agents/skills/docs-lint/lint.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +"""Lint committed docs against .agents/shared/writing-style.md. + +Checks two mechanical rules: + 1. Banned vocabulary (significance puffers, analytical verbs, poetic nouns, + promotional adjectives, opening crutches). + 2. Broken relative markdown links. + +Prose-voice rules are not machine-checkable; this covers the parts that are. +Run from the repo root: python3 .agents/skills/docs-lint/lint.py [paths...] +Exit 1 if any violation is found. +""" +import os, re, sys + +BANNED = [ + "pivotal", "crucial", "vital", "groundbreaking", "transformative", "testament", + "paramount", "invaluable", "delve", "leverage", "utilize", "facilitate", "foster", + "showcase", "underscore", "streamline", "harness", "tapestry", "realm", "paradigm", + "nexus", "cornerstone", "robust", "seamless", "innovative", "cutting-edge", + "meticulous", "holistic", "comprehensive", "in today's world", + "it's worth noting", "it is important to note", +] +BAN_RE = re.compile(r'(? {link}") + violations += 1 + print(f"\n{violations} violation(s)") + return 1 if violations else 0 + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/knowledge/index.md b/knowledge/index.md index 0067f7f..8252ad3 100644 --- a/knowledge/index.md +++ b/knowledge/index.md @@ -6,7 +6,7 @@ cross-cutting system, synthesized from live state and evidence. Structure and ru | Section | What it covers | |---------|----------------| -| [wiki/hosts/](wiki/hosts/) | Proxmox host narratives — `hubris`, `strong`. | +| [wiki/hosts/](wiki/hosts/index.md) | Proxmox host narratives — `hubris`, `strong`. | | [wiki/containers/](wiki/containers/index.md) | LXC fleet — one page per container, plus the master table and archaeology. | | [wiki/vms/](wiki/vms/index.md) | Virtual machines — ZimaOS, Home Assistant OS. | | [wiki/infrastructure/](wiki/infrastructure/index.md) | Cross-cutting systems — DNS, ingress, mesh, storage, auth, monitoring, generated topology. | diff --git a/knowledge/log.md b/knowledge/log.md index 4cb195a..508908b 100644 --- a/knowledge/log.md +++ b/knowledge/log.md @@ -5,3 +5,4 @@ source ingests, lint sweeps). One line per operation, newest last. Infrastructur each page's `## Changelog` and the Oikos change ledger, not here. ## [2026-07-06] restructure | moved node/infrastructure narratives under knowledge/wiki/; references under knowledge/sources/; repointed inventory doc_page fields and gen-topology.py output. +## [2026-07-06] lint | banned-vocabulary scan of knowledge/ clean; added .agents/skills/docs-lint and knowledge/wiki/hosts/index.md. diff --git a/knowledge/wiki/hosts/index.md b/knowledge/wiki/hosts/index.md new file mode 100644 index 0000000..1c7ab00 --- /dev/null +++ b/knowledge/wiki/hosts/index.md @@ -0,0 +1,9 @@ +# Hosts + +The two Proxmox VE nodes that run the fleet. Narrative pages; the machine-readable host records are +the generated `hosts/*.yaml` files at the repo root. + +| Document | What it covers | +|----------|----------------| +| [hubris.md](hubris.md) | Primary PVE node (GMKtec NucBox M6 Ultra, `192.168.8.77`) — runs most LXCs plus the VMs. | +| [strong.md](strong.md) | Secondary PVE node / cluster member (`192.168.178.181`) — hosts the LXCs migrated from hubris. |