live: heartbeat sync 2026-10-18T16:47:59-07:00 (Refs #11)

agent/managed-skills/serverappconfigs-vault-page-registration/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: serverappconfigs-vault-page-registration
+description: "Add a page to the serverAppConfigs docs vault without failing the docs_completeness test: frontmatter, dual index registration, link checker, suite gate."
+---
+
+# serverAppConfigs vault page registration
+
+Adding any page under `serverAppConfigs-docs/` fails `tests/docs_completeness.bats` ("docs index links every docs page") unless registered in BOTH indexes. Learned the hard way: the section index alone is not enough.
+
+## Procedure
+
+1. Write the page with OKF frontmatter: `type` (e.g. `reference`), `title`, `description`, `tags`, `timestamp` (ISO with `-07:00` offset).
+2. Cross-links inside page bodies use **markdown links** for cross-folder paths (`[Observability](../Infrastructure/Observability.md)`); `[[wikilinks]]` resolve by page title and must NOT carry relative paths.
+3. Register a `[[Page Title]]` bullet in the section index (e.g. `serverAppConfigs-docs/Operations/index.md`).
+4. Register the SAME `[[Page Title]]` bullet in the ROOT index `serverAppConfigs-docs/index.md` under the matching section heading (root index has its own "Operations:", "Architecture:", ... lists). This is the step the test enforces.
+5. Verify: `python3 scripts/check-vault-links.py` → `0 unresolved links`, then `./tests/run.sh` → ALL TESTS PASSED.
+
+## Comment-sweep conventions (same repo)
+
+- Scope of "comments": code/config `#` comments (scripts, env, quadlets, Caddyfile, tests). Identifiers, string literals, and `__pycache__` are separate decisions; docs prose is documentation, not comments.
+- User-approved idiom for lore comments: state the mechanism and why it matters, generically — no incident dates, no project-specific names, no named-thing slogans.
+- Edit-tool workflow: a fresh `grep`/`read` snapshot yields the file's `#TAG`; batch edits per file in one call; file tag changes after each edit, never re-edit the same file within one batch.