Overview#

Spis remembers an adopted corpus in $XDG_CONFIG_HOME/spis/corpus.json, or $HOME/.config/spis/corpus.json when XDG_CONFIG_HOME is absent. Corpus commands use that location; without an adopted corpus they use the working directory. Check spis corpus status before a mutation. Command flags and command-specific environment inputs configure external services.

Environment variables read by Spis#

Variable	Readers	Default / absence behavior
`XDG_CONFIG_HOME`	adopted corpus location	`$HOME/.config` when absent; a fresh configuration directory isolates qualification from the operator's adopted corpus
`HOME`	corpus configuration, tilde-expanded paths and command-specific data directories	corpus configuration uses `$HOME/.config/spis/corpus.json`, then `.spis/corpus.json` if HOME is absent
`PATH`	`stado`, `gh`, and capturable product discovery	no fallback; commands refuse or omit products when required executables cannot be resolved
`MODEL_ROUTER_URL`	`discover` ranking and `collect-example-images` image choice, through Brama	required; absent or empty is refused with `<purpose>: set MODEL_ROUTER_URL to the Brama address`
`MODEL_ROUTER_MODEL`	the same two commands	required, the operator's Brama model alias; absent or empty is refused with `<purpose>: set MODEL_ROUTER_MODEL to a Brama model alias`
`MODEL_ROUTER_TOKEN_ROLE`	the same two commands	optional `ROLE#FIELD`, read with `stado credentials get --role ROLE --field FIELD` (`STADO_BIN` names the executable); absent or empty sends no bearer, a malformed reference or a failed read is refused naming it

This table is not an exhaustive list of worker bindings. Command-specific service and credential inputs are documented with their command. capture-cli-references constructs its PTY child environment with the terminal size its capture plan states and fixed paging behavior, so retained recordings made under one plan remain comparable.

Important flag defaults#

Command	Setting	Default
`crawl-docs`	`--workers`	64
`docs-corpus search`	`--limit`	20
`discover`	`--limit`	6 selected pages
`discover`	`--max-links`	120 extracted same-origin links
`verify-reference-evidence`	`--jobs`	8
`verify-reference-evidence`	state matching	enabled; disable with `--no-state-match`
`collect-example-images`	candidates per record	14, compiled constant
`capture-widths`	`--host`	active host of the Stado registry's `weles-admission` service; an explicit registered target overrides it
`audit-reference-accessibility`	`--target`	active host of the Stado registry's `weles-admission` service; an explicit registered target overrides it

Network behaviour#

Shared GET: every fetch except discovery sends the user agent Spis/<version> (evidence-grade interface corpus; +https://spis.wisent.com/docs). Each request is sent once and waits for the server's own answer; a refusal or a dropped connection is reported with the URL and its cause, and bodies are read whole, with no size ceiling.
Robots: crawl-docs reads one origin's /robots.txt and obeys the group addressed to Spis for every documentation fetch. Only a served policy, or a 404 or 410 answer meaning there is none, lets fetches through; any other answer, an unreachable origin or a rule that does not compile denies every path and leaves a durable diagnostic in the inventory.
Discovery: spis discover fetches with the user agent Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) spis-discovery/1.0, sends each request once, and reads at most the first 64 MiB of a body.
README drift: spis check-upstream-drift asks the GitHub contents API through gh api repos/<repo>/contents/<path> and compares the answered blob SHA with the recorded one; an answer without a SHA is reported as unreachable with the answer quoted.
Model calls go to Brama at MODEL_ROUTER_URL with the model alias MODEL_ROUTER_MODEL and the bearer the vault role MODEL_ROUTER_TOKEN_ROLE names; each missing variable is refused naming it and the command that needed it.
Image collection: spis collect-example-images fetches pages and images once each with the Spis user agent, reads each body whole and stores the original image bytes as served.

Local paths#

Path	Content
`$HOME/.spis/docs-corpus/<slug>/`	`pages.jsonl.gz`, `state.json`, and resume data
`$HOME/.spis/work/landing-width-plans/`	Weles width-capture plans
`$HOME/.spis/work/wisent-capture/run/<product>/`	PTY cast and rendered screenshots
`.build/accessibility-audit/` in the active corpus	private plans, staging downloads and execution index; excluded from version control and publication
catalog directories in CWD	source/index records and retained evidence
`.build/upstream-drift.json` in the active corpus	private operational observations written by `check-upstream-drift --write-report`; excluded from publication

External executable requirements#

stado is mandatory for width capture and accessibility audit; those commands explicitly refuse direct SSH. gh and an authenticated token are mandatory for README refresh and used for README drift checks. capture-cli-references requires a capture plan (--plan), the planned product binaries on PATH, /bin/bash, and Menlo (/System/Library/Fonts/Menlo.ttc) or SF Mono (/System/Library/Fonts/SFNSMono.ttf) for PNG rendering, which spis draws itself. Media verification may call local media tooling such as ffprobe as described by its errors.