Configuration and first health checks

Use this guide after workspace initialization. It keeps observation separate from mutation: inspect effective configuration and health first, preview optional integrations, then authorize only the smallest required write.

Understand configuration layers

Day Shift resolves configuration in this precedence order:

1. Built-in defaults provide baseline behavior.
2. Shared .day-shift/config.toml overrides supported repository-scoped values and marks the effective workspace root.
3. Local .day-shift/local.toml overrides supported machine-specific values and should remain uncommitted.

The order is defaults < repository < local, but each key has an allowed source-layer contract. A local file cannot override a repository-only key merely because local has higher precedence. Unknown keys, wrong scopes, malformed TOML, invalid types, and invalid threshold ordering fail closed.

Inspect resolved values and their provenance without writing:

day-shift config get --format json
day-shift config get default_readiness --format json
day-shift config inventory --format json

config get reports effective values, source layers, and source paths. config inventory adds ownership, mutability, sensitivity, validation, display policy, and whether a key is writable through config set; sensitive values can be summarized, redacted, or omitted.

day-shift config set <key> <value> is a workspace write. It validates the catalog key and value, selects the key’s supported target layer, preserves unrelated TOML, and reports the target path. Most writable collaboration settings go to shared .day-shift/config.toml; machine-specific editor goes to local .day-shift/local.toml. Review version control before changing shared policy.

If configuration cannot be parsed or the workspace schema is stale or partially migrated, stop. Do not delete files or copy values between layers. Run read-only doctor checks, then preview the supported migration before any confirmed apply:

day-shift doctor --runtime-only --format json
day-shift workspace migrate --target-schema-version <supported-version> --dry-run

Add shell completion optionally

Completion supports bash, zsh, and fish. Script and candidate resolution are read-only and do not execute the target command:

day-shift completion script --shell bash
day-shift completion complete --shell bash --line "day-shift con" --cursor 13

You may source the generated script for the current session. Persistent installation changes a shell-native file under the current user’s home directory, so preview it first:

day-shift completion install --shell bash --dry-run --format json
day-shift completion install --shell bash --format json

Use --shell zsh or --shell fish for those shells. Install creates or updates only the Day Shift-managed integration. An unmanaged target is blocked; --force is the explicit host-write boundary for replacing it. Inspect and back up that file before force.

Removal is also a host write and removes only recognized Day Shift-managed content:

day-shift completion uninstall --shell bash --dry-run --format json
day-shift completion uninstall --shell bash --format json

Run the first health checks

doctor is read-only. It reports structured findings and a derived readiness status without repairing files, changing status, applying migrations, or creating planning artifacts.

day-shift doctor --runtime-only --format json
day-shift doctor --artifact .day-shift/planning/example/task-definition.md --format json
day-shift doctor --planning-directory .day-shift/planning/example --format json
day-shift doctor --repository-audit --format json

The scope selectors are mutually exclusive: choose only one of --runtime-only, --artifact, --planning-directory, or --repository-audit. With no selector, repository audit is the default. Artifact and directory targets must already exist inside the configured planning root.

Use --action "<exact command>" to classify findings against one authoritative command descriptor, for example --action "task new". Current-action blockers can be narrower than repository-wide findings, but warnings still require review or explicit acceptance. Doctor evidence never authorizes its recommended write command.

Go from an empty repository to planning

Follow this order so every write has prior evidence:

1. Create or enter the repository and verify day-shift --help.
2. Run day-shift init --dry-run, inspect every planned path, then run day-shift init.
3. Run day-shift agent to read the repository contract and confirm the nearest .day-shift/config.toml workspace.
4. Run day-shift config get --format json and day-shift config inventory --format json; use config set only for a deliberate supported override.
5. Preview completion installation if desired; it is optional for planning.
6. Run day-shift doctor --runtime-only --format json. Resolve blocking setup or compatibility findings through the stated preview-first recovery route.
7. Inspect registered source intent with day-shift spec list and use day-shift planning next-action --artifact <existing-artifact> when planning already exists. Create a spec or downstream planning artifact only when your chosen workflow explicitly authorizes that write.

Fresh, existing, customized, stale, and partially migrated workspaces all use the same safety rule: preserve user-owned state, gather read-only evidence, preview the supported operation, and apply only with explicit intent. Never repair uncertainty by manually moving or deleting .day-shift/ or by testing completion against the operator’s real shell files.

For diagnostic interpretation and recovery escalation, continue to Troubleshooting.