Scripts and tools used across many projects, kept in one place instead of being copied into the next repository that needs them.
The operator works across many hosts, shells and environments. Every tool here says which hosts it runs on, and fails with a message on the ones it does not.
Licence: 0BSD. Use it however you like.
One thing is published from here. The
wsl-toolkit tool is cut as a
GitHub release, with a
SHA256SUMS computed in CI over the bytes that are uploaded. The release holds
the executable for two Windows architectures, the sums file, and one keyless
signature bundle per published file.
Everything else here is scripts and their documentation: no images, no packages,
no second release train. The BSD container images some of its history refers to
are built by
pkgforge-dev/docker-bsd.
⭐ On a Windows machine and want Linux?
tools/windows/wsl-toolkit/wsl-toolkit.md
is the one page to read.
| path | what it is |
|---|---|
⭐ tools/windows/wsl-toolkit/ |
one executable: a host survey that resolves past every shim, one owned WSL distribution running a rootless engine, container jobs that get a COPY of a workspace and never a mount, a fleet runner over a catalog of fully qualified images, a FreeBSD guest on the host's own hypervisor, adapters that install a multiplexer and coding agents into the base, and a cleanup that removes only what it made. ⭐ It CARRIES the general-purpose scripts below, so a machine with the binary needs no clone: wsl-toolkit shipped list |
scripts/doctor/ |
one read-only pass reporting the host, the shell, the installed tools with versions, and the repository state |
scripts/common/ |
the entry points to the gate and the helpers that write files, move the record, commit and fill a licence. ⚠ Each is a thin sh and PowerShell pair over one Go subcommand; the rules themselves are not written twice. |
⭐ tools/check/ |
every rule this repository enforces over its own tree. One binary, one tree walk. ⚠ The count moves; the gate prints it and TODO/PROGRESS.md records the measurement |
⭐ tools/text-tool/ |
one program that writes a file, adds to a file, changes part of a file, and converts line endings, without the shell ever touching the payload. ⭐ It is PUBLISHED for Windows and Linux, so an agent downloads one asset and needs no clone. Its eol mode is the whole of dos2unix and unix2dos |
tools/repo/ |
the tools that are NOT gate rules: the mutation harness, open-items reader, git-sync, release verifier/tagger, binfmt probe, deslop, and licence filler |
LICENSES/ |
the SPDX texts scripts/common/fill-license.sh reads |
skills/ |
three skills for an agent driving this repository's products: wsl-toolkit itself, the agents that run under herdr inside a base, and text-tool. ⭐ Each stands alone and tells the reader to generate the manual rather than carrying a flag list that rots |
Every tool has a .md beside it that stands alone. Read the tool's own page,
not this one, before using it.
| path | what is in it |
|---|---|
README.md |
this page |
CHANGELOG.md |
what shipped, when, and where the evidence is |
TODO/ |
the work: the record, the entry list, the entries themselves, and the standing rules |
docs/ |
how this repository is worked on. The map is below. |
scripts/ |
the tools and the checks |
tools/ |
the Go modules: check holds every gate rule, repo the tools that are not rules, text-tool the file writer, and windows/wsl-toolkit the compiled tool |
LICENSES/ |
licence texts, not code |
.github/workflows/ |
CI. ci.yml on every push, across ubuntu and windows; release.yml on a version tag; release-smoke.yml and remote-items.yml weekly. TODO/RULES.md has the counts and which of them main requires. |
| file | answers |
|---|---|
docs/AGENTS.md |
the router an agent reads in full: where it is, the absolutes, and which document each task needs |
docs/consumers.md |
who fetches from this repository, what they pin, and what breaks them |
docs/methodology/gate.md |
what a unit of work passes before it is done |
docs/methodology/reviews.md |
the three review lenses |
docs/methodology/sessions.md |
what a session owes at its start and its end |
docs/methodology/authoring.md |
how an idea becomes an approved unit of work |
docs/methodology/work-todo.md |
the work model: an index, a record, entries that close in place |
docs/methodology/references.md |
how to study somebody else's project |
docs/methodology/initialize.md |
how to start a project that does not exist yet |
docs/conventions/prose.md |
how documents are written here |
docs/conventions/docs.md |
which documents exist and what makes them trustworthy |
docs/conventions/git.md |
commit identity, and what may reach a remote |
docs/conventions/code.md |
language-agnostic construction rules |
docs/conventions/forbidden-patterns.md |
mistakes that shipped, each with what it caused |
docs/conventions/shell.md |
quoting, exit codes, streams, line endings, and the platform traps |
docs/security/secrets.md |
what never enters the tree |
docs/security/remote-ops.md |
the tiers governing action on anything outside this machine |
docs/public/README.md |
what changes because this repository is public |
docs/reference-sweeps/findings.md |
what external repositories were read, and what was true in them |
docs/reference-sweeps/usable.md |
which of those findings this repository can use |
docs/HISTORY/README.md |
superseded wording and the story of fixes that have shipped. Nothing there is read to do work. |
Fetch it by URL. Nothing here assumes it is being run from a clone.
⭐ Or take the executable, which carries them. wsl-toolkit shipped list
names each file it holds with its length and SHA-256, shipped cat and shipped write produce one, and base bootstrap runs the carried bootstrap inside the
base with nothing copied anywhere. The URLs below stay the contract for a caller
that does not hold the binary.
Resolve a commit and use that. A branch moves, and a moved reference runs code nobody reviewed:
gh api repos/Azathothas/ToolKit/commits/main --jq .shaDownload to a file, then run the file. Piping a download into a shell executes the prefix of a truncated transfer and leaves nothing to inspect.
For wsl-toolkit, pick a release tag, download the executable for the host
architecture with its SHA256SUMS and signature bundle, verify both, then run
it from disk. TAG is a release such as the one gh release list --repo Azathothas/ToolKit names first:
gh release download TAG --repo Azathothas/ToolKit --pattern 'wsl-toolkit-windows-amd64.exe*' --pattern SHA256SUMSdocs/consumers.md carries the verification commands, the
register of who fetches what, and what a rename here breaks out there.
⭐ Read docs/AGENTS.md in full. It is the one router,
and it is written to be read end to end. TODO/PROGRESS.md
carries the current state and the work order, and
TODO/RULES.md the part of it that does not change.
Run the probe first, on any machine:
sh scripts/doctor/doctor.shpwsh -NoProfile -File scripts/doctor/doctor.ps1Then the gate, which is every local check in one command:
sh scripts/common/check-gate.shpwsh -NoProfile -File scripts/common/check-gate.ps1docs/methodology/gate.md is the rule the gate
implements, and CI runs the same checks on two hosts.
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4){kind=small}