Skip to content

🧭 NeXuS Compass — Fossil SCM adoption · Docs architecture · TUI kitchen-sink

Stamped 2026-07-17 · Anon shutting down — pick up here

This session: resolved the "git vs Simple" question by evaluating Fossil SCM hands-on, landed the docs-with-code architecture, and pre-screened a 215-package TUI kitchen-sink batch (ready for a doas install).

✅ DONE this session

Fossil SCM — evaluated hands-on, leaning ADOPT

Fossil v2.28 already installed (/usr/bin/fossil). Answers the parked "is git the best / not so Simple / is gitea the same" question: - git = the VC tool (powerful, not Simple). Gitea = a self-hosted git server/forge — NOT a different/simpler tool, still git underneath. Fossil = a genuinely simpler, self-contained alternative. - Proven facts (all demoed live in ~/Projects/fossil-lab): - 1 .fossil file = 1 whole repo — files + history + wiki + forum + chat + tickets + users, all in one SQLite file. Proved by deleting the working tree and rebuilding it from the file alone. - Working dir = disposable checkout (.fslckout); repo lives in the ONE file (opposite of git's in-tree .git/). Two steps: init/clone the file, then open a checkout. - Empty repo ≈ 212K = fixed forge-schema overhead (27 tables). Text compresses + deltas; binaries bloat it — keep out (matches CLAUDE.md no-binaries rule). - Simpler than git: no staging/index dance — commit auto-includes tracked edits; add only for NEW files. Has fossil undo (reverses last update/merge/revert — git has no equivalent). - Not a walled garden: fossil git export maintains an incremental git mirror → still push to GitHub. Fossil = sovereign source of truth, GitHub = mirror. - Zero-install access for others: browse via web UI (browser only); grab code via /tarball/... or /zip/... with plain curl. Only real collaborators need the (tiny, single-binary, zero-dep) install. - Repo list in UI: fossil server ~/museum/ (a DIRECTORY) → root page lists every .fossil = your self-hosted forge homepage. (fossil server repo.fossil = straight into one repo, no list.) CLI: fossil all list (only shows repos opened at least once — dir-server list shows ALL files regardless). - Search: fossil grep PATTERN file = content search across ALL historical versions, no index. Plus FTS5 full-text index (fossil fts-config enable all; index on; reindex) over file content + wiki + forum + tickets + comments → web-UI search box. Use tokenizer trigram for code.

Docs architecture — SETTLED (after a false start)

  • False start: I overcomplicated with wiki-vs-embedded + project-vs-cross-cutting split → confused Anon. Reset.
  • The rule Anon landed on: a script + its .help.md = ONE unit; repo boundary wraps the natural unit. Docs live WITH their code (already half-stated in CLAUDE.md). No format conversion — help files are already markdown; Fossil renders them as-is (embedded docs). The "NeXuS operation manual" is a VIEW, not a hoard: one index.md linking the help files = the manual's table of contents.
  • Mapping: ~/scripts → nexus-scripts.fossil (scripts + help together — also knocks out the parked "offsite-backup of /scripts" task). Each ~/Projects/* → its own repo (code + docs/). Only truly standalone broad manuals (some of ~/manuals) might want a separate knowledge repo later — small tail, don't let it complicate.
  • Doc inventory (read-only, this session): ~/manuals 66 · ~/claude/docs 88 · ~/claude/reports 27 · ~/claude/compass 14 · ~/notes/nexus 4 · ~15 per-project docs/ dirs · ~/scripts 89 loose .md (help files) · only 1 binary (docs are ~all text = Fossil-friendly).

TUI kitchen-sink batch — pre-screened, ready to install

  • Manifest saved: ~/scripts/nexus_tui_sink.pkgs (215 pkgs — TUI apps, terminals, players, net tools, icon themes, fonts).
  • Dry-run (nexus-apk-sink.sh -n -f, no doas needed): 125 would-install · 88 already · 0 not-in-repo · 0 conflicts flagged (conflicts NOT screened — apk --simulate needs root; real screen happens under doas).

Memory written

  • memory/project_fossil.md (new) + MEMORY.md index updated.

⏳ PENDING doas op (Anon runs — I can't go root)

Install the TUI sink (does the real conflict pre-screen under root, installs what sticks): 

doas sh ~/scripts/nexus-apk-sink.sh -f ~/scripts/nexus_tui_sink.pkgs

▶️ NEXT / PICK UP HERE

  1. First real Fossil repo — I offered, awaiting "go": ~/scripts → ~/museum/nexus-scripts.fossil fossil init ~/museum/nexus-scripts.fossil → fossil open a checkout → copy (never move) scripts + .help.md in → commit → serve. Get the operation-manual view for free.
  2. Then the char-gen copy→commit pilot (replay its ~8 copies oldest→newest as real commits into one repo).
  3. Optional nexus-forge.sh wrapper so raw fossil verbs stay hidden: new (init in ~/museum + open in ~/Projects) · save "msg" · log · back <ver> · serve (localhost default + optional Tor-publish).

📌 OPEN DECISIONS

  • Store dir name: ~/museum/ vs ~/fossils/ for canonical .fossil files.
  • Wrapper vs raw: build nexus-forge.sh now, or drive raw fossil first to get a feel.
  • MkDocs fate: keep mkdocs/GitHub-Pages as the polished PUBLIC render layer (fed from Fossil via git-mirror), or let Fossil /doc rendering replace it (plainer but sovereign + searchable + versioned).
  • 3-copies doctrine maps to Fossil: canonical .fossil in store · working checkout in ~/Projects · backup = cp the one file.

🧹 CLEANUP / STATE

  • Scratch demo ~/Projects/fossil-lab/ = throwaway (nexus-demo.fossil, medusa-demo.fossil, fresh-checkout/). Safe to delete. FTS was enabled on nexus-demo (harmless).
  • All fossil demo servers STOPPED — nothing left running (8080/8081 down). NOTE: pkill -f 'fossil server' tripped a sandbox signal (exit 144) mid-command twice — cosmetic, servers still died; just don't chain pkill with other output.
  • Nothing committed/pushed anywhere. No secrets touched.