slosh.git/README.md, branch docs-new

docs: deprecate boring design narrative, more trimming and culling

2026-09-02T10:32:45Z

docs: less wordy

2026-08-29T18:25:39Z

arch: sign the packages and the database, and say whose key

2026-08-29T13:57:54Z

An ed25519 key made for exactly this -- slosh package signing , 0F67C909938CFFA8A76B59FD8D69B55A0E9056B9 -- signs every package and both indexes. The public half travels two ways that would both have to lie: contrib/arch/slosh.asc in git, and /arch/slosh.asc on the website; the READMEs walk through pacman-key --add and --lsign-key, and the [slosh] stanza loses its SigLevel override because pacman's default demands signatures and now gets them. contrib/arch-repo pins the fingerprint, refuses to run without the secret key (an unsigned update would make every enrolled pacman refuse the repo), and now regenerates the index from the directory every time: repo-add skips an entry whose version it already has, so after a same-version rebuild an incremental add left the db describing the previous bytes -- a checksum mismatch for every client. An index rebuilt from disk cannot disagree with disk. Verified end to end with a scratch pacman keyring: enrolled key syncs and downloads under Required DatabaseRequired, unenrolled key is refused at the database.

arch: a self-hosted pacman repository, since the AUR is shut

2026-08-29T13:48:25Z

AUR signups are closed while the AUR deals with supply chain attacks, so the package is published from our own roof -- which is the better offer anyway: a pacman repository serves built packages where the AUR hands every user a rebuild. contrib/aur/ becomes contrib/arch/ (the .SRCINFO goes; it is AUR metadata, regenerated in a minute when signups reopen), and contrib/arch-repo builds the package and maintains the slosh.db / slosh.files indexes in dist/arch//, which rsyncs to /opt/slosh/arch/ on the box. The README and the front page carry the [slosh] stanza; SigLevel is spelled out because the packages are not signed yet and pacman defaults to demanding it.

gitignore: DESIGN.md and .fastfeedback are local, not the project

2026-08-28T13:38:41Z

DESIGN.md was a scratch design doc and .fastfeedback a per-repo tool cache; neither belongs in the tree. Both stay on disk, ignored. Everything that pointed at DESIGN.md now points at docs/design.md, and the decision counts quoted from it (which had already drifted: the README said twenty-one, the docs said twenty-two) are gone with it.

windows release: a zip in dist/, built beside the linux tarballs

2026-08-28T13:38:27Z

make -f Makefile.windows dist stages slosh.exe as slosh--windows-.zip -- a zip, not a tarball, because Windows is the machine that will open it -- carrying the same licensing paperwork as the linux tarballs, with docs/windows.md riding along instead of the manpages. `make release` now builds both architectures via release-windows, so the windows zips land under the same SHA256SUMS as everything else.

docs: the Windows build is a cross-compile, and only that

2026-08-28T12:22:57Z

The docs offered a native build as an equal alternative -- "the same command builds natively on the Windows box itself, with zig on PATH and a make" -- and it does not work. Makefile.windows needs sed, cat, mkdir -p and shell grouping, none of which cmd.exe has; and on ARM64 `zig cc` in zig 0.16.0 dies with an access violation on a one-line C file, so the compiler cannot run there at all. The zip that does it matches the published shasum, so this is upstream rather than a bad download. Nobody following those two sentences reached a binary. So they are gone, along with the "# host arch, native" usage line in the makefile and the "cross-compiles too" aside in the two install sections, which both implied that building on the box was the normal path and the cross-compile a bonus. It is the other way round, and now the pages say so once, in the same words each time. `builds and runs natively` on the doc's first line loses `builds`: what is native about slosh.exe is the binary, not where it was made.

docs: the Windows port, and what is different there

2026-08-27T22:23:19Z

An install subsection alongside macOS and Linux, and a page under Inside for the rest: how to build it, what changes about running it (%ComSpec% panes, sessions in %LOCALAPPDATA%), and the reasoning the code can only gesture at in comments. The three traps are written down in full, because each one presents as something other than what it is and cost real time: a pane with a title and no body (the child inherited slosh's stdout rather than the pseudoconsole), a pane that stays alive after `exit` (a ConPTY's output pipe belongs to the console, not the child, so the read never ends), and an editor refusing a path that plainly exists (cmd.exe and CommandLineToArgvW disagree about what \" means, and separately the CRT accepts a mixed-separator path where a GUI dialog will not).

install docs: one subsection per OS

2026-08-27T14:19:25Z

'With Homebrew (macOS or Linux)' followed by a source build made every reader parse which half was theirs; now macOS and Linux each have a heading, and you read yours. macOS is the tap; Linux is the same tap under Homebrew on Linux, or the source build, which the docs landing page had never mentioned brew at all. Also fixes the README telling people to run bare 'make', which prints the help text (the default goal) and builds nothing. install.sh had this figured out and commented on it; the README had not.

README/docs: stop leaning on the aside dash

2026-08-27T14:11:26Z

Some 230 sentences hung their qualifications between dashes, and at that density the tic reads as the writing's signature rather than a tool it occasionally picks up. Each one is now the punctuation the sentence actually wanted: a colon where the aside defines, parentheses where it whispers, a comma where it barely pauses, a full stop where two thoughts were pretending to be one. Definition lists and reference tables take colons throughout. Two double hyphens remain on purpose, both literal: the argv separator in a shell example, and a table cell that means 'takes nothing'.