@hawkeyexl/manni 4.12.3 → 4.13.0

package/dist/{list-PMC7W6MO.js → list-OOOCLOAL.js}

@@ -2,29 +2,29 @@
 import {
   renderList,
   runList
-} from "./chunk-7KCF6YCA.js";
-import "./chunk-PWMORIGE.js";
+} from "./chunk-OREHJQNN.js";
+import "./chunk-OBXCJZ6R.js";
 import "./chunk-SSQZB5SQ.js";
 import "./chunk-YNHZHSSM.js";
 import "./chunk-ZPLVANY2.js";
 import "./chunk-ZXRAE55H.js";
 import "./chunk-SE4JN5XN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
 import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -32,4 +32,4 @@ export {
   renderList,
   runList
 };
-//# sourceMappingURL=list-PMC7W6MO.js.map
+//# sourceMappingURL=list-OOOCLOAL.js.map

package/dist/{list-VVZKMISE.js → list-OYQ5XPN2.js}

@@ -2,18 +2,18 @@
 import {
   LIST_FORMATS,
   runList
-} from "./chunk-GOBQS4Q7.js";
-import "./chunk-7IY773CK.js";
+} from "./chunk-7JPL3CUC.js";
+import "./chunk-3XGTNN3M.js";
 import "./chunk-IKEWBMCN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-77AINBYM.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
@@ -21,7 +21,7 @@ import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -29,4 +29,4 @@ export {
   LIST_FORMATS,
   runList
 };
-//# sourceMappingURL=list-VVZKMISE.js.map
+//# sourceMappingURL=list-OYQ5XPN2.js.map

package/dist/{page-6YKD7SRI.js → page-XPX5XJZE.js}

@@ -8,26 +8,26 @@ import {
   pickExtractor,
   readPage,
   validateEntry
-} from "./chunk-5D5DT5P7.js";
+} from "./chunk-X4MPUD4B.js";
 import "./chunk-IKEWBMCN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
 import {
   bodyLineOf
-} from "./chunk-PKIX6FUE.js";
+} from "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
 import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -42,4 +42,4 @@ export {
   readPage,
   validateEntry
 };
-//# sourceMappingURL=page-6YKD7SRI.js.map
+//# sourceMappingURL=page-XPX5XJZE.js.map

package/dist/{prepare-ZAHCPMKM.js → prepare-VMBIQYAM.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-YQV75FIL.js";
 import {
   resolveAlwaysSources
-} from "./chunk-HEHYX7TD.js";
+} from "./chunk-PCGBXHSE.js";
 import {
   NOT_SET_UP,
   libraryLocalModels,
@@ -23,7 +23,7 @@ import {
   parseHookPayload,
   readStdin
 } from "./chunk-TZOYZK2E.js";
-import "./chunk-NODDMFCE.js";
+import "./chunk-E6BVUDGY.js";
 import {
   discoverConfig
 } from "./chunk-OKMTUAWO.js";
@@ -38,14 +38,14 @@ import {
 } from "./chunk-UKZNLVJW.js";
 import "./chunk-YNHZHSSM.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
 import "./chunk-YEUYKR62.js";
@@ -54,7 +54,7 @@ import "./chunk-HX44GB4Z.js";
 import {
   DEFAULT_KEEP_ALIVE_MS
 } from "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -156,4 +156,4 @@ async function runPrepare(options = {}) {
 export {
   runPrepare
 };
-//# sourceMappingURL=prepare-ZAHCPMKM.js.map
+//# sourceMappingURL=prepare-VMBIQYAM.js.map

package/dist/{pretty-SXH5QO6N.js → pretty-KG6TMOEI.js}

@@ -9,26 +9,26 @@ import {
   resultFor,
   rewriteLine,
   splitBaselined
-} from "./chunk-YHTR4GRV.js";
-import "./chunk-WJBKYW3N.js";
-import "./chunk-5D5DT5P7.js";
+} from "./chunk-GWI6JPTT.js";
+import "./chunk-WVXCN5DS.js";
+import "./chunk-X4MPUD4B.js";
 import "./chunk-IKEWBMCN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
 import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -43,4 +43,4 @@ export {
   rewriteLine,
   splitBaselined
 };
-//# sourceMappingURL=pretty-SXH5QO6N.js.map
+//# sourceMappingURL=pretty-KG6TMOEI.js.map

package/dist/{pretty-TKZVPCZW.js → pretty-KSTZMBUF.js}

@@ -6,18 +6,18 @@ import {
   renderListPretty,
   renderValeWiring,
   renderWritePretty
-} from "./chunk-CHVWGSG2.js";
-import "./chunk-7IY773CK.js";
+} from "./chunk-PA7CMQGD.js";
+import "./chunk-3XGTNN3M.js";
 import "./chunk-IKEWBMCN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-77AINBYM.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
@@ -25,7 +25,7 @@ import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -37,4 +37,4 @@ export {
   renderValeWiring,
   renderWritePretty
 };
-//# sourceMappingURL=pretty-TKZVPCZW.js.map
+//# sourceMappingURL=pretty-KSTZMBUF.js.map

package/dist/{reporters-WTXEHZT4.js → reporters-AQU4W3KY.js}

@@ -26,8 +26,8 @@ import {
   renderSarif,
   ruleIdFor,
   xmlEscape
-} from "./chunk-E77FC2QG.js";
-import "./chunk-MAE6674H.js";
+} from "./chunk-BMBAAPGN.js";
+import "./chunk-HY6ROJTH.js";
 import {
   escapeWorkflowCommandMessage,
   escapeWorkflowCommandProperty
@@ -36,7 +36,7 @@ import "./chunk-RNVYGWIC.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -70,4 +70,4 @@ export {
   ruleIdFor,
   xmlEscape
 };
-//# sourceMappingURL=reporters-WTXEHZT4.js.map
+//# sourceMappingURL=reporters-AQU4W3KY.js.map

package/dist/{reporters-W2NMRDWO.js → reporters-FBYLPKD4.js}

@@ -9,26 +9,26 @@ import {
   renderTemplates,
   renderTools,
   toValidationResults
-} from "./chunk-BPVDKCPD.js";
+} from "./chunk-NTEYYYKL.js";
 import "./chunk-GLP5PSXB.js";
-import "./chunk-TBAMBLF3.js";
-import "./chunk-YGFIQ6Y5.js";
+import "./chunk-6ZFJWUUH.js";
+import "./chunk-SCLXVTFZ.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
 import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -43,4 +43,4 @@ export {
   renderTools,
   toValidationResults
 };
-//# sourceMappingURL=reporters-W2NMRDWO.js.map
+//# sourceMappingURL=reporters-FBYLPKD4.js.map

package/dist/{run-OH6DLHJE.js → run-KUGTU3TT.js}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   runRun
-} from "./chunk-HL4VFPPM.js";
-import "./chunk-PWMORIGE.js";
+} from "./chunk-KE2F7QES.js";
+import "./chunk-OBXCJZ6R.js";
 import "./chunk-SSQZB5SQ.js";
 import "./chunk-YNHZHSSM.js";
 import "./chunk-ZPLVANY2.js";
@@ -12,21 +12,21 @@ import {
 import "./chunk-ZXRAE55H.js";
 import "./chunk-SE4JN5XN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
-import "./chunk-6GE2RFM6.js";
-import "./chunk-2VZSOKG3.js";
-import "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+import "./chunk-HIEGOW7X.js";
+import "./chunk-IGQMBHFY.js";
+import "./chunk-OUAH7XF2.js";
+import "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-MNH7QO4Z.js";
 import "./chunk-RNVYGWIC.js";
 import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
@@ -34,4 +34,4 @@ export {
   render,
   runRun
 };
-//# sourceMappingURL=run-OH6DLHJE.js.map
+//# sourceMappingURL=run-KUGTU3TT.js.map

package/dist/{term-XIPBAZFB.js → term-SI3VM6EM.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   renderFindingsGithub
-} from "./chunk-HZYB4ALZ.js";
+} from "./chunk-CODWRUAD.js";
 import {
   renderFindingsJson,
   renderFormatsJson,
   renderGetJson,
   renderListJson
-} from "./chunk-3E33NXK4.js";
+} from "./chunk-ULDV2LUI.js";
 import {
   renderFindingsPretty,
   renderFormatsPretty,
@@ -15,7 +15,7 @@ import {
   renderListPretty,
   renderValeWiring,
   renderWritePretty
-} from "./chunk-CHVWGSG2.js";
+} from "./chunk-PA7CMQGD.js";
 import {
   FINDING_FORMATS,
   JUNIT_CLASSNAME,
@@ -27,11 +27,11 @@ import {
   runCheck,
   summarize,
   toResults
-} from "./chunk-7GYHLAOG.js";
+} from "./chunk-BQXY76JB.js";
 import {
   LIST_FORMATS,
   runList
-} from "./chunk-GOBQS4Q7.js";
+} from "./chunk-7JPL3CUC.js";
 import {
   DEFAULT_CRAWL_MIN_PAGES,
   DEFAULT_FILL_CACHE_DIR,
@@ -83,34 +83,34 @@ import {
   valeConfigFor,
   xmlAttribute,
   xmlText
-} from "./chunk-7IY773CK.js";
+} from "./chunk-3XGTNN3M.js";
 import "./chunk-IKEWBMCN.js";
 import "./chunk-YUTVAMWW.js";
-import "./chunk-TGJEDSQ7.js";
+import "./chunk-HIEGOW7X.js";
 import {
   DEFAULT_CHUNK_CHARS,
   splitBody
-} from "./chunk-6GE2RFM6.js";
+} from "./chunk-IGQMBHFY.js";
 import {
   mergeMetaProvenance
-} from "./chunk-2VZSOKG3.js";
+} from "./chunk-OUAH7XF2.js";
 import {
   OMITTED_WHEN_CLEAN,
   renderJunit,
   renderSarif
-} from "./chunk-E77FC2QG.js";
-import "./chunk-SDCODO2V.js";
+} from "./chunk-BMBAAPGN.js";
+import "./chunk-52WO7ESI.js";
 import {
   collect,
   readStdin,
   splitList
-} from "./chunk-PKIX6FUE.js";
+} from "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
 import {
   STDIN_TOKEN,
   extractorByName,
   extractorForExtension
-} from "./chunk-MAE6674H.js";
+} from "./chunk-HY6ROJTH.js";
 import "./chunk-77AINBYM.js";
 import "./chunk-MNH7QO4Z.js";
 import {
@@ -139,7 +139,7 @@ import {
 } from "./chunk-VM7VAFJW.js";
 import {
   package_default
-} from "./chunk-4HW7YJ74.js";
+} from "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import {
   errorMessage
@@ -2560,4 +2560,4 @@ export {
   TermError,
   buildProgram
 };
-//# sourceMappingURL=term-XIPBAZFB.js.map
+//# sourceMappingURL=term-SI3VM6EM.js.map

package/dist/{validate-IWPWBJIH.js → validate-NQO7TFSN.js}

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 import {
   runValidate
-} from "./chunk-SDCODO2V.js";
-import "./chunk-PKIX6FUE.js";
+} from "./chunk-52WO7ESI.js";
+import "./chunk-LNGSE7V2.js";
 import "./chunk-DSWKBZWW.js";
-import "./chunk-MAE6674H.js";
+import "./chunk-HY6ROJTH.js";
 import "./chunk-YEUYKR62.js";
 import "./chunk-OTJOBZJ5.js";
 import "./chunk-HX44GB4Z.js";
 import "./chunk-VM7VAFJW.js";
-import "./chunk-4HW7YJ74.js";
+import "./chunk-HKTGHLBA.js";
 import "./chunk-OWBRDNRZ.js";
 import "./chunk-G3T47CFV.js";
 import "./chunk-2H7UOFLK.js";
 export {
   runValidate
 };
-//# sourceMappingURL=validate-IWPWBJIH.js.map
+//# sourceMappingURL=validate-NQO7TFSN.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawkeyexl/manni",
-  "version": "4.12.3",
+  "version": "4.13.0",
   "description": "One command line for documentation that is meant to be checked. `manni meta` validates the presence and format of document metadata (Markdown frontmatter and more) against JSON Schema, built for CI. Formerly docmeta.",
   "type": "module",
   "bin": {

package/plugin/manni/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "manni",
   "description": "Checks the docs an agent edits against everything the repository set up in manni, blocks on errors, and records the session manifest tracevals reads.",
-  "version": "4.12.3",
+  "version": "4.13.0",
   "author": { "name": "hawkeyexl" },
   "homepage": "https://hawkeyexl.github.io/manni/",
   "repository": "https://github.com/hawkeyexl/manni",

package/plugin/manni/skills/fix/SKILL.md

@@ -43,8 +43,10 @@ After you change a term page, run `manni term write` to regenerate any rendered
 
 ## lint check
 
-Run `manni lint structure <path> --explain` to see which template routed the page and why.
-Then edit the page to meet that template. Change the page `type` only if the routing is wrong.
+Each structure finding names its template and rule, says what that section is for, and links the guide. Read those lines before editing.
+Run `manni lint templates show <template>` to see the whole shape in order.
+Write what the section asks for. Never add a heading, table or list only to satisfy a count.
+Run `manni lint structure <path> --explain` only when the template looks wrong for the page. Change the page `type` only if the routing is wrong.
 
 ## docevals run
 

package/schemas/lint/template.json

@@ -45,7 +45,7 @@
       "pattern": "^[A-Za-z][A-Za-z0-9-_]*$"
     },
     "description": {
-      "description": "Prose description of what the rule is for. Never checked.",
+      "description": "What the rule's section is for, written for the page's author. Shown with every finding about the rule, and by `manni lint templates show`. Never checked.",
       "type": "string"
     },
     "heading": {
@@ -109,6 +109,11 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
+        "guide": {
+          "description": "Link to the author's guide for this doctype. Shown with every finding from the template and by `manni lint templates show`. A template that `extends` another inherits its `guide` unless it sets its own.",
+          "type": "string",
+          "pattern": "^https?://"
+        },
         "extends": {
           "description": "Template reference (built-in id, path, or URL, optionally with a `#name` fragment) whose rules this template inherits.",
           "type": "string",

package/templates/lint/tgdp/concept.yaml

@@ -32,41 +32,54 @@ templates:
     types:
       - concept
       - explanation
+    guide: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/concept/guide_concept.md
+    # The page title, whatever the author calls the concept. Its body is the
+    # summary that introduces the concept and the definition that follows -
+    # upstream notes the definition deliberately carries no heading of its
+    # own, so it is checked here rather than in a section.
     description: >-
-      The page title, whatever the author calls the concept. Its body is the
-      summary that introduces the concept and the definition that follows -
-      upstream notes the definition deliberately carries no heading of its
-      own, so it is checked here rather than in a section.
+      Explain one concept so the reader understands what it is and how it
+      fits the bigger picture. Open with a short summary, then define the
+      concept.
     contains:
       paragraphs:
         min: 1
     sections:
+      # Context, prehistory, or background for the concept.
       - id: background
-        description: Context, prehistory, or background for the concept.
+        description: >-
+          Give the history or context that helps the reader understand the
+          concept, such as why it was designed the way it was.
         heading:
           pattern: '^(\(Optional\) )?Background$'
         min: 0
         max: 1
+      # How a reader benefits from the concept. The one section upstream
+      # does not mark optional.
       - id: use-cases
         description: >-
-          How a reader benefits from the concept. The one section upstream
-          does not mark optional.
+          Show how the concept helps the reader, starting from a real problem
+          they face and how the concept solves it.
         heading: Use cases
         max: 1
+      # A comparison of the options or alternatives the concept sits
+      # among. Upstream titles it `Comparison of {thing being compared}`,
+      # so only the literal prefix is anchored.
       - id: comparison
         description: >-
-          A comparison of the options or alternatives the concept sits
-          among. Upstream titles it `Comparison of {thing being compared}`,
-          so only the literal prefix is anchored.
+          Compare the concept with its alternatives, versions, or types, and
+          say when to choose each one.
         heading:
           pattern: '^(\(Optional\) )?Comparison( of .+)?$'
         min: 0
         max: 1
+      # Links out to related documentation. Upstream recommends "Related
+      # concepts" or "Additional information" as more descriptive names,
+      # so all three are accepted.
       - id: related-resources
         description: >-
-          Links out to related documentation. Upstream recommends "Related
-          concepts" or "Additional information" as more descriptive names,
-          so all three are accepted.
+          Link to related concepts, how-to guides, and other material for
+          readers who want to go deeper.
         heading:
           pattern: '^(\(Optional\) )?(Related resources|Related concepts|Additional information)$'
         min: 0
@@ -75,3 +88,4 @@ templates:
       # published template never named. The four above are the ones TGDP
       # names; anything else the author needs is allowed through.
       - min: 0
+        description: Add any other sections the explanation needs here, after the ones above.