Plan: mac-server-setup docs site (issue #205)¶
History. In progress. These PRs merged on 2026-11-13: Phase 0 #245, Phase 1 #246, Phase 2 #259, Phase 3 #247 and #263, Phase 4 #248 and #264, Phase 5 #260, Phase 6 #254, #255, #256 and #257, and Phase 7 #253 (landing page and llms.txt) and #262 (history banners). #266 gave the last four top-level pages their final homes. The repo homepage points at the site, and the referral issue is #252. The last banners and the shorter README are in a later PR. The plan is complete when that PR merges and #205 is closed.
How to resume (new session):
- Read this file.
- Read the private research file that sits beside the working copy of this plan, outside the repo. It is PRIVATE and must never be committed. It holds the inventory, the known-wrong statements, the code-to-doc reference list and the sensitive-value list, all with file:line.
- Find the first phase whose PR does not exist yet. List the open PRs on smartwatermelon/mac-server-setup with branches
claude/docs-*. - Work in a worktree per Protocol 1.
Context¶
Issue #205 "needs a definitive guide and wiki": the project outgrew its docs. There are 47 tracked .md files (about 15k lines). They go stale, they overlap, and a new adopter has no single start-to-finish path. The README also says app setup runs automatically after reboot. That is wrong: first-boot.sh:1442 tells you to run run-app-setup.sh yourself.
Outcome: a public, cross-linked, searchable docs site. Every current doc either moves into it or is listed in its "Design history" section. CI checks keep the site from drifting away from the code.
Decisions made by Andrew (2026-11-12):
- Platform: GitHub Pages, built with Zensical from
docs/and checked in CI on every PR. It uses themkdocs.ymlformat, so Material for MkDocs is the fallback. The GitHub Wiki tab stays off. (Search engines do not index a wiki under 500 stars, and wiki edits skip review.) - Sensitive data: scrub and generalize. Pages use placeholders (
YOUR_SERVER,example.com,192.0.2.x). TILSIT-specific values move to a private operator note. Git history keeps the old values; we accept that. - History: plans, archive and the old code review appear under a "Design history" section. They are scrubbed, but otherwise not edited. Navigation and search favor the current pages.
- PR flow: stacked PRs. Each phase branches from the previous phase's branch, and Andrew approves the merges in batches. Goal mode stops only at a real human gate. After a lower PR merges, rebase the stack with
git rebase --onto.
Out of scope: the referral and partnership idea in #205. It gets its own new issue at the end.
Hard rules for this project¶
- Nothing deploys to Pages until Phase 2 (scrub) has merged. Phases 0 and 1 build in CI only.
- No sensitive literal goes into any committed file. That includes the sensitive-data test itself.
- Repo docs keep the repo's normal voice. STE is for chat only. Use
asd-ste100on runbook steps only where a step reads ambiguously. - Every move or rename updates every code, test and
CLAUDE.mdreference in the same PR.tests/docs-references.batsenforces this. - Each doc path is fixed once, in Phase 3. Later phases add new pages beside it and never move it again.
Information architecture (final paths, fixed in Phase 3)¶
docs/
index.md landing: what it is, stack diagram, "start here"
get-started/ TUTORIAL: one numbered path, prereqs → first play
01-choose-stack.md 02-prerequisites.md 03-configure.md 04-build-package.md
05-first-boot.md 06-operator-login.md 07-run-app-setup.md 08-verify.md
components/<name>.md HOW-TO hub per component; the moved app READMEs land here
caddy cloudflare-tunnel cloudflare-ddns home-vpn monitoring pia-vpn plex
plex-watchdog rclone stable-signing transmission-filebot tvmaze-scrobble ...
reference/ config-keys (generated), launchagents, logs, ports, scripts, glossary
explanation/ architecture, tls-strategy, credential-chain, storage-virtiofs,
tunnel-security-layers
troubleshooting/ symptom → cause → fix, per area
plans/ STAYS WHERE IT IS (planning skills and code use this path); nav: History
archive/ STAYS; nav: History; the old code review moves here
Code and alert text point at components/<name>.md (repo path in comments, site URL in alert text). A component page may later link out to new explanation and reference pages, but its own path never changes again.
Phases (one stacked PR each)¶
Phase 0: Tooling, build-only. No content changes.
- Go/no-go check on Zensical. Use
context7and the Zensical docs. Confirm three things: - (a) a strict build that fails on broken links
- (b) a way to exclude files (
CLAUDE.md,LICENSE.md,docs/setup/firstboot-README.md) - (c) a way to down-rank or exclude a section in search
If any of these fails, switch to Material for MkDocs now.
2. Read the external smartwatermelon/github-workflows standards-check-v1 workflow. Do not duplicate or conflict with any Markdown linting it already does.
3. Add these files:
- mkdocs.yml: nav, search, Mermaid, excludes.
- requirements-docs.txt: pinned versions.
- .markdownlint-cli2.jsonc.
- lychee.toml.
- .vale.ini: warn-only.
4. Add .github/workflows/docs.yml. On a PR it runs the strict build, lychee and markdownlint. The deploy job is present but turned off until Phase 2.
5. Commit this plan, without the research file, as docs/plans/2026-11-12-docs-site.md.
6. Install the local tools: lychee (brew install lychee), and Zensical in a venv under ~/.cache/zensical-venv. Also install Anthropic's doc-coauthoring skill if Andrew approves; it gives the reader test.
Phase 0 outcome (2026-11-12):
- Zensical is a go. All three checks were tried against this tree, not only read in the docs:
- (a)
zensical build --strictexits 1 on the brokenoperator.mdlink insetup/first-boot.md, and exits 0 once it is fixed. - (b)
exclude_docskeepssetup/firstboot-README.mdout of the site.CLAUDE.mdandLICENSE.mdsit outsidedocs/, so they are never built. - (c) front matter
search: {exclude: true}removes a page fromsearch.json. - Pinned to Zensical 0.1.0, not 0.1.1: 0.1.1 was two days old, under the fleet's three-day release floor. Dependabot (pip, three-day cooldown) proposes later bumps.
- No
.markdownlint-cli2.jsonc. standards-check already runs markdownlint-cli2 on every changed.mdfile. A repo-root config would replace the shared fleet config inside that required check, sodocs.ymldoes not lint Markdown and the repo keeps the fleet config. This replaces step 3's config file and the markdownlint part of step 4. - No deploy job yet. actionlint rejects a job gated by a constant
if: false, and a repo-variable gate could be flipped without review. Phase 2 adds the deploy job instead of enabling one. - Two link fixes moved forward from Phase 1 (research section B, item 10):
setup/first-boot.md→../operator.md, and READMElicense.md→LICENSE.md. Without them the new checks fail on the unmodified tree, and a red PR at the bottom of the stack blocks every PR above it. The README one passes on macOS only because its file system ignores case; the Linux runner would fail. - Links out of
docs/into code files (pia-vpn-README.md) are not flagged by the strict build and pass lychee as local files. They still 404 on the site. Phase 1 or Phase 3 turns them into repo URLs. - Dependabot auto-merge gates only on BATS, so a pip bump that breaks the docs build could merge. Add the docs check to
sanity_checkswhen Andrew marks it required (human gate 5).
Phase 1: Quick correctness fixes.
Fix the known-wrong statements in research section B, items 1, 2, 6, 8 and 10. These are the broken links, the README "automatic" claim, the nfs-watchdog troubleshooting, the /scripts path and the SMB wording.
Phase 2: Scrub and generalize.
- Write
tests/docs-sensitive.batsfirst. Its rules are shape-based, so it needs no literal values: - any IPv4 address outside 192.0.2/24, 198.51.100/24, 203.0.113/24, 127/8 and an allowlist of documented private examples
- any 32-hex id or UUID
- any
op://reference - any email address not at
example.com/example.org - a short allowlist file for real non-secret exceptions (for example, a public upstream IP in an archive page)
- Prove the test fails on the current tree before you fix anything.
- Replace each match with a placeholder. In current pages,
TILSITbecomesYOUR_SERVERandtilsit.vipbecomesexample.com. History pages get only the sensitive values replaced. - Move the TILSIT-specific values (Cloudflare object ids, LAN map, account labels) to a gitignored
local/operator-notes.md. Andrew keeps a copy in 1Password. - Point the
CLAUDE.mdservice sections atlocal/operator-notes.md. - Turn on the deploy job.
- Andrew enables Pages (source: GitHub Actions) after this PR merges.
Phase 2 outcome (2026-11-12):
- The checker is
scripts/docs/check-sensitive.sh.tests/docs-sensitive.batsunit-tests it on synthetic values and scans the tracked docs (git ls-files 'docs/*.md', which recurses, plusREADME.md). The scan failed on the unscrubbed tree before any fix. The PR lands in two commits, becauseREADME*files need copy approval: the first scans every page except README-named ones, and the second scrubs those and widens the scan to all pages. - Rules added beyond the four above, because the research list held values the four missed: 64-hex ids (an Access AUD tag), 26-character 1Password ids, and Zero Trust team hosts (
<team>.cloudflareaccess.com). Ids are matched on whole alphanumeric runs, so two ids joined by one character are both found. - A second, independent check ran outside the repo: every literal the checker found on
origin/main, grepped withgrep -Fover the scrubbed tree. It found them in the original and found none after. - The example LAN is
192.168.20.0/22with the server's/24at192.168.21.0/24. It keeps the real /24-inside-/22 relation, which the 192.0.2.0/24 documentation block cannot, and reuses none of the real map's octets in the same position. WAN examples are 203.0.113.10 to .13, one per real address. - The allowlist (
tests/fixtures/docs-sensitive/allowlist.tsv) holds only third-party addresses: PIA gateways and plex.tv edges. - Current pages: everything under
docs/andREADME.mdnot listed as history. History pages:plans/,archive/,code-review-plex-setup-v1.1.md,container-transmission-proposal.md,apps/caddy-cloudflare-checklist.mdandapps/caddy-dns01-migration.md. Only the sensitive values changed in history pages, includinguser@hosttargets and the admin account name;TILSITandtilsit.vipremain there. - Names kept in current pages on purpose:
QUICKCONNECT_ROMANO(a real config key),smartwatermelon/tilsit-caddy(a real archived repo), andDSMediaandROMANO(not in the plan's list).CLAUDE.mdkeepsTILSIT, because environment detection depends on it. - History runbooks that substituted real ids now read them from shell variables (
${CLOUDFLARE_ZONE_ID}), with a:?guard, so a copied command stops instead of writing an empty id into a script. - Git history still holds the old values; plan decision 2 accepts that.
- The deploy job runs only on
main, and only when the repo variableDOCS_DEPLOYistrue. Andrew sets it when he enables Pages; until thenmainstays green.
Phase 3: Restructure, with a drift guard.
- Write
tests/docs-references.batsfirst. It pulls everydocs/…mdpath out ofapp-setup/,scripts/,tests/,config/andCLAUDE.md, and fails if a path does not exist. - Before you edit alert text, grep the BATS files for any test that asserts on it. Update those tests in the same PR.
git mveach app README to its final path,components/<name>.md, and the setup pages intoget-started/. Content stays the same in this phase.- Update every reference in research section C, plus
CLAUDE.md. - Alert email bodies get the site URL.
- Convert about 80 backtick doc mentions into relative links.
Phase 4: Generated config reference.
- Add
scripts/docs/gen-config-reference.sh. It buildsreference/config-keys.mdfrom the comments inconfig.conf.template. - Add a BATS test. It fails when a key has no description, or when the generated page is out of date.
- Fold
configuration.mdandenvironment-variables.mdinto the new page and the component pages. This closes the 31-key gap.
Phase 5: Get-started tutorial.
- Write
get-started/01–08. Check every step againstprep-airdrop.sh,first-boot.shandrun-app-setup.sh: the order,--only,--continue-on-error, and which account runs it. - Run the reader test: a fresh subagent with no context follows the pages against the code. It lists every step that is missing or wrong.
- Fix what it finds. Repeat until it finds nothing.
Phase 6: Component content. One PR per area:
- remote access
- media pipeline
- Plex and monitoring
- extras
- explanation pages
- troubleshooting
In each PR:
- Rewrite the component pages in place.
- Split the "why" material into
explanation/. Split facts and tables intoreference/. - Check every command, path, port and LaunchAgent label against the code.
- Add the missing setup pages: Catch, the FileBot license, msmtp and the Gmail App Password, Backblaze, and the first Podman/Transmission install.
- Add cross-links and glossary links.
Phase 7: History, landing page, close-out.
- Give each history page a status banner. This fixes the wrong statuses listed in research section A.
- Cut the README down to an overview plus a link to the site.
- Write the landing page with
personify. - Turn on
llmstxt. - Set the repo homepage URL.
- Open the referral issue.
- Close #205.
Permanent CI checks¶
- Strict site build, which catches broken internal links and nav entries.
- lychee for external links. Cache the results. A scheduled run only warns.
- markdownlint-cli2, run by the required standards-check workflow with the fleet config.
tests/docs-references.bats.tests/docs-sensitive.bats.- The config-reference generator test.
Verification (each phase)¶
- Run the strict build,
lychee docs/andmarkdownlint-cli2 "docs/**/*.md"locally. - Run
bats tests/docs-*.bats, plus the BATS files for every script touched. The full suite runs in CI only. - Run
shellcheck -S infoandshfmt -d -i 2 -ci -bnon new scripts. - Pass the normal pre-commit gates. Push, then run the
post-push-loopskill until CI is green. - After the first deploy, search the live site for
run-app-setup,VirtioFSandCF_API_TOKEN. Each search must find the right page. - Phase 5: the reader test reports nothing.
Goal-mode "done" criteria¶
- The site is live on Pages, and search works.
- Every one of the 47 inventoried docs is a current page or a history page. Nothing is orphaned.
- All six CI checks are green, and Andrew has marked them required.
- The get-started path passes the reader test.
-
205 is closed, and the referral issue exists.¶
Human gates (Andrew)¶
- Approve the
doc-coauthoringinstall (Phase 0). - Approve merges in batches through merge-lock.
- Enable Pages after Phase 2 merges.
- Store the operator notes in 1Password.
- Mark the docs CI checks as required in branch protection.