From f875378503c21725f3ad5d3f814b1c37825a9313 Mon Sep 17 00:00:00 2001 From: ykcheungab Date: Wed, 30 Sep 2026 16:12:34 +0800 Subject: [PATCH] docs: state where this repository's documentation rules live The workspace writing standard (D:\orisys_ws\docs\AUTHORING.md) is not auto-discovered from inside a repository: the workspace skill root is D:\orisys_ws\.agents\skills\, and an agent working here resolves its project root to this repository's .git. This file points at the standard and at the gate command, and records which kinds of document belong in this repo's docs. Without it, agents working inside the repository would not learn the budgets or the placement rules. --- docs/AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/AGENTS.md diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000..69abf0e --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,27 @@ +# Documentation rules for this repository + +This repository lives inside the Orisys workspace at `D:\orisys_ws`. The workspace's writing +standard is authoritative for every document here: + +**`D:\orisys_ws\docs\AUTHORING.md`** — one home per fact, current state only, link instead of +restating, the slop checklist, and the word budgets (standard 1,200 / general 1,500 / reference +3,000). + +This file exists because the standard is not auto-discovered from inside a repository: the +workspace skill root is `D:\orisys_ws\.agents\skills\`, and an agent whose working directory is +this repository resolves its project root to this repository's `.git`. Read the standard at the +path above, or load the `orisys-doc-standard` skill when working from the workspace root. + +## Check your docs before finishing + +```powershell +python D:\orisys_ws\scripts\doc_lint.py # changed Markdown — must pass +python D:\orisys_ws\scripts\doc_lint.py --all # audit the whole corpus +``` + +`tools/lint_gate.py` runs this automatically alongside Ruff, so a change that adds an oversized +document fails the same gate as a change that breaks a lint rule. Pass `--no-docs` to skip it. + +Pre-existing oversized documents in this repository are listed in `D:\orisys_ws\docs\inventory.json` +as `budget-exempt` with a written reason, and pre-existing findings are baselined there, so the +gate is red only for new regression. Fix one when you touch it and remove its entry.