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

Inspect and edit configuration in the GUI

Open Settings → Project → Day Shift project settings, then Show settings. Each row shows its effective value and source. Use Where this value comes from to inspect provenance; choose a registered project when project-specific values are needed. Search by setting name or description.

For an editable setting, choose Edit setting, enter a supported value, and select Preview change. Review the target file and before/after values before confirming. Read-only settings stay inspectable. An incomplete inventory or changed revision requires a refresh before saving. The config get, config inventory, and config set commands above remain the terminal path.

Browser appearance and layout preferences are separate from repository configuration. Settings → Preferences controls theme, accent, and preference import/export; Layout controls panes, text size, and workspace scale. Those settings do not change task policy or lifecycle state.

Choose performance limits for your environment

Open Settings → Performance and limits, load the settings, and choose an Environment preset for the machine running the Day Shift server. Choose for the VM’s assigned resources when using a VM, rather than its host or the device displaying the browser.

Available starting points are Day Shift defaults, Budget laptop, Budget PC, Everyday laptop, Gaming PC, Super gaming PC / workstation, Small virtual machine, Large virtual machine, and Enterprise infrastructure. These are suggested CPU/RAM budgets, not measured ratings. GPU capacity does not accelerate planning guidance. Leave capacity for your editor, builds, other applications and local models.

Selecting a preset does not save it. Choose Preview preset, review all eight before/after values, select I have reviewed this change, then Save change. Use Edit setting to customize an individual limit afterward. Overrides are stored in .day-shift/local.toml for this checkout. New requests use saved limits immediately; requests already running retain their original limits.

Setting	Day Shift default	What it bounds
Preview length	20,000 characters	Text returned for display; guidance reads full evidence independently
Evidence file size	1.5 MiB (1,572,864 bytes)	One file read for repository previews or planning guidance
Total guidance evidence	16 MiB	Unique unchanged file content read during one guidance request
Guidance file reads	1,024	Evidence reads during one request; unchanged cached files count once
Guidance result size	64 KiB	Serialized guidance response
Guidance timeout	15 seconds	One guidance worker’s execution
Guidance worker heap	128 MiB	V8 heap per worker; buffers and other allocations add memory
Concurrent guidance requests	2	Simultaneously active guidance workers

A byte limit is not a character count: non-ASCII text can use multiple bytes per character. Raising file, total-evidence or result budgets allows larger reads or responses but can increase memory, processing and browser rendering costs. More workers multiply resource use. Raise the limit named in the failure, refresh guidance, and inspect the result. Increasing preview length alone does not repair an evidence-read failure. These settings do not change validation execution, diagnostics retention or every runtime limit. See incomplete guidance recovery.

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.