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

agent/managed-skills/serverappconfigs-docs-only-landing/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: serverappconfigs-docs-only-landing
+description: "Land a docs-only (vault/log) commit on serverAppConfigs main without a PR: tests green, then fast-forward main via git push origin HEAD:main — including recovery when the omp worktree base is stale or pre-compaction edits vanished."
+---
+
+# serverAppConfigs docs-only landing
+
+Land vault/log edits on `main` directly (no PR) when the change touches only
+`serverAppConfigs-docs/**` (or `AGENTS.md`): the deployer treats docs-only
+changes as a no-op, and origin is the self-hosted Gitea — pushing there is
+allowed.
+
+## Procedure
+
+1. **Ground-truth the worktree BEFORE editing** (omp worktrees go stale
+   between sessions/compactions):
+   - `git fetch origin && git log --oneline 3e140cd..origin/main`-style check:
+     `git log --oneline HEAD..origin/main` — if non-empty, main advanced
+     (sibling sessions land zealot/dankclaw work constantly).
+   - NEVER trust the session summary that "file X was already edited": the
+     worktree may sit at an older commit and transcript-era edits may not
+     exist on disk. Verify with `grep -n "<new-phrase>" <file>`; redo edits
+     against a fresh read if absent.
+   - Line numbers in AGENTS.md shift between main versions — re-locate stale
+     claims by `grep -n "on disk\|stays on disk\|rollback target" AGENTS.md`,
+     never by remembered line numbers.
+2. Edit (read target regions fresh; long table rows in AGENTS.md must be
+   re-emitted whole via `PUT n.=n:` — get the full row first with
+   `read path:N:raw`).
+3. `./tests/run.sh` — full bats suite must pass (~60–75 s; run async, do
+   other work). Docs seams of interest: `docs_completeness` (index links
+   every page, no unresolved `[[wikilinks]]`).
+4. Commit on the worktree branch, then rebase onto `origin/main` if it
+   advanced. Typical conflict: `log.md` tail — both sides appended entries;
+   resolution = keep both blocks, `CUT` the three marker lines, re-add the
+   blank line before the second heading.
+5. Re-run the docs seam (or full suite if non-prose changed) against the
+   exact pushed tree.
+6. **Push:** `git push origin HEAD:main` — plain push IS the fast-forward
+   PR-less merge. NEVER `--force`/`--no-verify`. If Gitea rejects, main moved
+   again: rebase (step 4) and push again.
+7. Docs-only = no `deploy.sh` run needed; hosts pick the pages up on their
+   next pull.
+
+## Gotchas
+
+- `git status` not listing a file you "just edited" + `rev-parse HEAD`
+  mismatch vs `git worktree list` → the harness recreated/reset the worktree;
+  the edits are gone. Redo, don't hunt.
+- `log.md` entries: heading `## YYYY-MM-DD — topic`, blank line between
+  entries; docs seam tolerates either entry order within a day.
+- Prose-only amend after a green suite: rerun at least
+  `bats tests/docs_completeness.bats` before push.
+- Do not reset the shared `main` checkout in `~/Projects/serverAppConfig`;
+  it falls behind origin and the user syncs it.