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.

Scaffold target paths are repository-relative and do not depend on framework directory names. Day Shift accepts canonical runtime paths under roots such as server/, cmd/, Sources/, or any other repository-specific layout. Paths classified as documentation-only remain excluded from executable scaffold evidence unless the repository deliberately marks a prefix as runtime-eligible. Use the callable shared-config surface for that exception:

day-shift config set runtime_evidence.path_policy.runtime_eligible_paths '["docs/runtime","examples/executable"]'
day-shift config get runtime_evidence.path_policy --format json

The array is the complete repository-specific exception list. Each value may name a file or directory prefix, must remain inside the repository, and is stored under [runtime_evidence.path_policy] in .day-shift/config.toml. This policy is consumed at every Governed child-scaffold transition—slice to phase, phase to milestone, and milestone to task—so rerun the rejected review or scaffold command after setting it. Do not use the exception to admit validation commands, globs, absolute paths, or .. traversal; those remain invalid target evidence.

The path behavior covers every hierarchy level supported by each planning lane:

Planning lane	Supported hierarchy	Architecture-neutral target coverage
Basic	Direct task pair	work create accepts safe repository-relative task targets without assuming a source root.
Structured	Work overview → direct task pairs	work task create preserves safe repository-relative targets in each generated task pair.
Governed	Slice → phase → milestone → task	Each parent scaffold parser and the final task projection consume the same repository path policy.

Basic and Structured intentionally do not invent phase or milestone layers. Governed is the lane that exercises the complete four-level hierarchy; the shared policy applies at each transition rather than only at final task generation.

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.

Diagnose scan risk and memory pressure

When a large workspace is slow or memory use rises, keep the first evidence bounded. Select the artifact you are working on, request a compact context pack, and run artifact-scoped doctor before considering repository-wide inventory or audit work:

day-shift work select --artifact <path> --format json
day-shift agent context --artifact <path> --format json --detail compact
day-shift doctor --artifact <path> --format json

If the evidence points to workspace traversal or editor indexing, run these exact read-only routes separately:

day-shift doctor --scan-surface --format json
day-shift ignore integration preview vscode --format json

The scan-surface diagnostic is bounded by default. Deep repository audit is a separate, explicit escalation, not an automatic recovery step. Integration preview requires the explicit vscode target and performs no writes.

Memory evidence is process-specific. A Day Shift CLI subprocess can report its own bounded work, while agent-session context growth belongs to the active agent runtime. VS Code’s editor extension host and each language server are separate processes, and terminals, build tools, plugins, or other third-party processes have their own health boundaries. A Day Shift command cannot prove, repair, restart, or control those external processes; inspect the relevant process with the editor or operating-system diagnostics when its health is the question.

Preview and apply report configuration evidence only. Preview shows the proposed VS Code settings change without writing. Apply is a separately authorized write and requires the preview-derived policy and content preconditions; do not infer apply from preview output. A successful preview or apply does not verify editor, extension-host, language-server, or other third-party process health, so treat that health evidence as incomplete until it is checked at the process that owns it.

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.