Skip to main content

Docsite — Work Record

Intent​

Internal Docusaurus publishing site for reports, docs, and artifacts the owner needs to review. Docker-only, reachable over the tailnet, with a Portals service directory and a nightly-regenerated landing page.

Status​

building — live on tailnet :8445; rebranded to the dark theme; 13-category structure in place; private GitHub repo jknash/docsite live with docs-sync push path; work-record convention added 2026-09-28.

Decisions​

DateDecisionWhy / rejected alternative
2026-09-28Docusaurus 3.10.2, node:22-alpine, pinnedReproducible, no unpinned floats
2026-09-28Dark slate + cyan theme matching /portalsOne visual language across the site
2026-09-2813 categories from X-Centric _Design foldersStandards/Runbooks/Catalogs/Templates/Tooling/Voice fit the actual work
2026-09-28_Archive/ excluded from buildSuperseded versions stay on disk, off the sidebar
2026-09-28One initiative = one project folder + living work-recordPreserves the trail of how things happened
2026-09-30url/footer/navbar-title parameterized via DOCUSITE_URL/DOCUSITE_FOOTER/DOCUSITE_NAV_TITLE build-args (env in JS)Any Docker host can run a clean-branded copy from the repo; primary host keeps its values as defaults, so no-arg builds are byte-identical to before

Progress log​

2026-09-30​

  • External agent publishing (owner request): added docs/07-reference/agent-publishing.md — the full publishing contract for agents pushing from outside the host (checkout, categories, naming, front matter, tag vocabulary, MDX body rules, commit message format, git pull --ff-only discipline, archive-not-delete). AGENTS.md at repo root points new agents at it (landed 2026-09-30 after owner approval via the gateway approval card; pushed as 897f3a1).
  • Provenance footer rule (owner rule, 2026-09-30): every agent-created document ends with _Published by <agent name> · YYYY-MM-DD._ — now codified in §6 of the publishing contract; the contract itself carries the footer.
  • Periodic pull cron docsite-docs-pull (every 30m, watchdog-silent): ~/.hermes/scripts/docsite-docs-pull.sh fetches main, fast-forwards, rebuilds the live site via plain docker exec (compose v1.29 exec workaround), and reports new commits/docs to owner Slack only when something lands. Divergence or dirty local tree → blocker/hold, never guesses. This replaces the assumption that only in-run docs-sync.py pushes matter — external agents now flow in via pull.
  • Portability verified + URL/branding parameterized (owner request): proved a fresh clone builds and serves on any Docker host (isolated clone → docker build rc=0 → live 200s on /, /docs/, /portals). docusaurus.config.js now reads DOCUSITE_URL, DOCUSITE_FOOTER, DOCUSITE_NAV_TITLE from the environment with the primary-host values as fallback; Dockerfile exposes them as build-args and docker-compose.yml forwards them as build.args + container environment (so in-container rebuilds inherit them). Verified both paths: no-arg build bakes the primary-host output; override build baked http://mybox.example.net:3000 + "Local docsite · testing" + "MyBox Docs" into the static HTML. README gained a Per-instance URL & branding section.
  • Knowledge Reference category + first entry + Tailscale agent runbook (owner request): new 14-knowledge/ category (index + tailscale.md) — verified tailnet facts, jkdev001 port map (8443–8447), agent-join model, pitfalls; runbook 09-runbooks/agent-tailscale-host.md references it. Publishing contract category table and navbar Practice menu updated for the new category.
  • Convention cross-linking pass (owner request — "link everything where it needs to be; keep conventions up to date in an agent-findable doc"): the knowledge-reference pointer is now wired into every agent entry point — the agent-publishing.md contract (read-first + "check knowledge before researching" rule), the publishing.md site category tree (now 14), the 09-runbooks/index.md conventions ("reference, don't restate, verified facts"), and the README.md repo layout + Conventions ("Agents" pointer: AGENTS.md → contract → knowledge). Navbar Practice menu → Knowledge. Agent-facing convention of record at the time was docs/07-reference/agent-publishing.md; the 2026-10-01 Knowledge consolidation moves it to docs/14-knowledge/agent-publishing.md.
  • Two research reports published (owner requests): 01-reports/2026-09-30-self-hosted-oidc-federation.md (authentik recommended, Keycloak runner-up after a critical review finding was remediated in-artifact; Apple out of scope on Apple's own prerequisites; UNVERIFIED tailnet-redirect question flagged as a 20-min pre-commit test) and 01-reports/2026-09-30-self-hosted-secrets-storage.md (two-category split: Vaultwarden for human credentials, OpenBao conditionally for app/agent secrets; "auto-unlock on any OS" resolved to the human-credential mechanism with the once-per-restart caveat). Both went through the full research pipeline (coordinator → compiler → fresh-context Level 2 review); secrets-storage grade B with the hash condition independently verified and three A-grade defects fixed; full evidence packets at /root/Working/Research/self-hosted-oidc-federation-20260930/ and /root/Working/Research/secrets-storage-20260930/.

2026-09-29​

  • Owner readability: body/sidebar/table text set to portals gray #94a3b8 (7.97:1 on dark).
  • Retheme to X-Centric brand (item 7): Electric Violet #5C15FF on Midnight Navy #000319, links lavender #A58FFF, buttons/accents brand violet, status badges use complement teal/gold/danger. Body stays the owner's gray. /portals and the home page rethemed to match.
  • Fixed broken logo (item 5): navbar logo was a base64url data URI that wouldn't load; replaced with a standard-base64 open-book SVG in brand violet.
  • Ordering rule (item 1): NN- folder prefix = top-level order; within a category, alphabetical by filename. Category index.md → sidebar_position: 1 to lead; content docs drop positions.
  • Date naming (item 4): point-in-time deliverables = YYYY-MM-DD-slug.md; evergreen docs stay undated.
  • Archive/prune lifecycle (item 3): Live → _Archive/ (excluded from build, kept on disk) → deliberate delete. Default: archive finished reports.
  • Portability (item 2): added README.md (run-on-any-Docker-box steps) and package-lock.json (pinned dependency tree) so a fresh box builds reproducibly with minimal config.
  • Brand kit published (item 8): 08-standards/xcentric-brand-kit.md + logo assets, sourced from the assessor-repo X-Centric Design System.
  • Projects tracking rule (item 6): new dev work gets a 03-projects/<slug>/ folder + work record as the first step when queued.

2026-09-28​

  • Stood up Docker container; verified end-to-end publish loop.
  • Added /portals service directory + nightly cron (portals-landing-page, 02:00 CST).
  • Remapped tailnet services to contiguous block 8443–8447.
  • Rebranded to dark theme; adopted 13-category structure from _Design.zip.
  • Added .gitignore, docs-sync.py, and the Projects work-record convention.
  • Created private jknash/docsite; initial push + docs-sync.py push path verified (first report pushed as be7a7e6).
  • Documented all 27 cron jobs in 04-fleet/cron-jobs.md (+ 11-templates/cron-job.md).
  • Added nightly docsite-docs-push cron (45339a72da0c, 02:10 CST, watchdog-silent): pushes uncommitted docs to GitHub + rebuilds; staggered 10 min after portals-landing-page.

Blockers / open items​

  • Controlled publishing / backups / rollback (RH-12) still open.
  • Host gotcha (2026-09-29): docker-compose v1.29.2 breaks on Docker engine 29 (KeyError: 'ContainerConfig' on up/create). docker-compose exec still works, but recreating the container means plain docker run --name docsite --network docsite_docsite_net -p 3000:3000 -e NODE_ENV=production -v /root/Working/Projects/docsite/docs:/app/docs -v /root/Working/Projects/docsite/src:/app/src docsite:latest. Config changes need docker-compose build docsite first (config is baked into the image; only docs/ + src/ are mounted).
  • Auto-push is handled by the nightly docsite-docs-push cron (02:10 CST); in-run pushes happen via docs-sync.py.
  • Live: https://jkdev001.tail6817df.ts.net:8445
  • Source: /root/Working/Projects/docsite
  • X-Centric brand kit (this pass): /docs/standards/xcentric-brand-kit — full palette, gradients, logo, usage rules + logo assets, sourced from the assessor-repo design system.
  • Publishing guide (ordering / date-naming / archive-prune rules): /docs/knowledge/publishing
  • Projects tracking rule: /docs/projects
  • README (run on any Docker host): repo root README.md
  • Worked items 1–8 on 2026-09-29 (see progress log above); all verified live against the running build.

Published by Hermes · 2026-10-01.