Configuration

One configuration file and one state root. Configuration is never inferred from the working directory, so two terminals in different directories cannot silently use different plugins or different state.

The file

Key	Type	Meaning
`version`	number	Must be `1`. Any other value is refused and never migrated.
`stateRoot`	string, optional	State root directory. A relative value resolves against the configuration file's directory.
`providers`	object, optional	Provider overrides. Each key is a provider id and each value has exactly one key, `path`, resolved against the configuration file's directory.

{
  "version": 1,
  "stateRoot": "state",
  "providers": {
    "bluesky": { "path": "vendor/bluesky-provider" }
  }
}

Unknown top-level keys are refused. A key whose name looks like a token, secret, password, API key or credential is refused by name, so a secret cannot be smuggled into the configuration file even accidentally. A provider entry accepts only path, and a path with a URL scheme is refused.

How the file is selected

Without a flag, the CLI reads $XDG_CONFIG_HOME/syndroo/config.json, falling back to $HOME/.config/syndroo/config.json when XDG_CONFIG_HOME is unset or not absolute.
--config names an explicit file. The path must be absolute; a relative path is refused instead of resolved, so an accidental --config config.json cannot pick up a file from the working directory.
A missing default file is not an error for a command that resolves no provider. A missing file named by --config is an error.

The file is read as strict JSON: at most 64 KiB, no duplicate keys, no invalid UTF-8, and no value the JSON data model cannot represent.

The state root

The state root defaults to $XDG_STATE_HOME/syndroo/runtime-v1, falling back to $HOME/.local/state/syndroo/runtime-v1. A relative XDG_STATE_HOME is ignored, as the XDG base directory specification requires.

The root carries one format marker. A root whose marker is missing, or that names any other format, is refused: the runtime does not guess, and it never probes, migrates or deletes state written by an earlier Syndroo version. A read-only command on a machine that has never connected anything reports the state as uninitialized rather than creating a directory.

Environment variables

Variable	Used by	Meaning
`XDG_CONFIG_HOME`	configuration	Chooses the default configuration directory when it is absolute.
`XDG_STATE_HOME`	state root	Chooses the default state directory when it is absolute.
`HOME`	both	The fallback base for both defaults. A missing or relative value is an error.
`SYNDROO_CREDENTIALS`	`--from-env`	One credential object as JSON, read only when `--from-env` is passed and at most 64 KiB.
`NO_COLOR`	human output	Disables colour, like `--no-color`.

Nothing else is read from the environment: no .env file, no per-provider variable registry, and no credential is ever taken from the configuration file.

Fail closed

Every one of these is refused rather than guessed at: an unsupported version, an unknown key, a secret-looking key, a relative --config path, a provider entry with more than one key, an oversized file, and a state root whose format marker does not match.