(sigil env setup)
sigil env setup: the one-time, consent-gated host step that makes /sigil/store resolve to the user's environment store.
WHY IT EXISTS. Packages are built inside a sandbox that mounts the store at the fixed path /sigil/store, so their outputs bake /sigil/store/<item>/... paths (that is what makes identities portable across machines). On the host the store lives in the user's data directory, so nothing resolves those paths until /sigil points there. Measured 2026-09-23: a channel-built Emacs exits "will not function correctly without the character map files" without it, and starts in 3.2 s instead of 30-47 ms when only relocated by variables.
THE DECISION (David, 2026-09-23): a host symlink, /sigil -> <data root>, where <data root> is the directory holding the env store (so /sigil/store IS the env store). It is ALWAYS a prompt the user can decline; nothing edits machine configuration without consent.
EXIT CODES, a stable contract (the installer calls this and branches on them): 0 done /sigil was created by this run and verified 2 already-set /sigil already links to this user's env root; nothing done 3 declined the user said no, the run was non-interactive, or no privilege tool (sudo/doas) exists -- the command is printed 4 refused /sigil exists and is NOT this user's link (another user's store, a stale link, an indirect link, a real directory) -- never touched 5 failed the user said yes and the link command did not produce the expected link 64 usage, including running as root without an explicit --store (1 is deliberately NOT in the contract: it is what an unexpected error exits with, and an installer must never read a crash as a known outcome.)
TRUST MODEL, stated so nobody has to infer it: the store under the link is writable by its owner, exactly like a single-user Nix install. sigil env shell -f LOCK verifies the closure on every entry, re-hashing anything whose recorded metadata (including ctime) changed. That catches accidental change and a careless tamper. It does NOT stop code running as the owner, which can rewrite the verification record in the same user-writable store (review 2026-09-23, reproduced); sigil env verify --full ignores that record. Programs launched OUTSIDE sigil through /sigil paths are not verified at launch; the link does not change that.
Exports
env-link-pathprocedureWhere the link lives. /sigil in real use; SIGIL_ENV_LINK moves it so the contract can be tested without root. It is not a way around consent: every path still prompts, and a non-writable parent still needs sudo.
absolute-pathprocedureThe directory /sigil must point at: the parent of the env store, which must itself be named store so that /sigil/store is exactly the store. Absolute and normalized: a link to a relative or oddly spelled path is a link that does not resolve (review 2026-09-23: SIGIL_ENV_STORE=data/store with /sigil -> data was reported "already set").
link-stateprocedure(state . detail): absent | ours | foreign-link TARGET | not-a-link
OURS MEANS THE LINK'S OWN TEXT IS OUR TARGET -- not merely that it resolves to the same directory. An indirect link (/sigil -> /tmp/x -> our data dir) resolves correctly today and is controlled by whoever owns the middle hop; accepting it would report "already set" for a link we do not control. Such a link is refused and explained instead.
shell-wordsprocedurePOSIX quoting for the PRINTED command, so what the user reads and could paste is exactly the argv sigil runs: anything outside a safe set is single-quoted, and an embedded ' becomes '"'"'.
refuse-root-without-store!procedureNOT AS ROOT. The link targets the store of whoever runs setup, and the default store is found through HOME, so sudo sigil env setup links /sigil to ROOT's store -- measured on David's first run (2026-09-23): it printed ln -sT /root/.local/share/sigil /sigil, created it, and ls /sigil as him then said "Permission denied". Setup already asks for sudo itself, only for the one ln. A genuinely root-owned store is still possible, but only named explicitly with --store.
env-store-handlerproceduresigil env store VERB ... -- operations on the environment store itself, as opposed to remove/gc/prune, which manage profiles and generations. Named by David (2026-09-23). One verb today, rm; the group leaves room for more (ls, verify) without adding them now.
env-store-rm-handlerproceduresigil env store rm ITEM... / sigil env store rm --all
The supported way to delete from the environment store, whose items are read-only by design (David, 2026-09-23): it lifts the seal itself, so nobody has to chmod by hand.
ITEM is a store item name (5f13...-emacs-31.1) or a path to one. A path must be a DIRECT child of the env store, compared after resolving both, so .., other directories and symlinks leading out are refused. --all deletes the whole env store, and only if it is a sigil store.
Exit codes: 0 removed (or nothing to remove), 64 usage, 66 no such item, 77 refused (outside the env store, not an item, not a sigil store).
env-setup-hint!procedureOne line, once, the first time sigil env shell runs on a machine whose link is not set up -- a pointer, not a wall of text. The marker lives in the env data root so it is per-store, and failing to write it only means the line may show again.
env-setup-handlervariable(No description)