Workspace initialization

Run day-shift init after installing the CLI and from inside the repository you intend to manage. Initialization creates a usable authoring workspace; it does not migrate an incompatible workspace, install local-only ignore rules, or create downstream planning artifacts.

Choose the target and preview it

Day Shift first detects the repository root. With no target option, init writes there:

day-shift init --dry-run
day-shift init

--dry-run reports the same planned directory and file outcomes without writing. Review its create, keep, and overwrite actions before a real run.

Use --directory <path> to initialize a nested workspace. Relative paths resolve from the current directory; absolute paths are accepted only when they remain inside the detected repository root. A target outside that boundary is rejected. After creation, ordinary commands walk upward from the current directory and use the nearest ancestor .day-shift/config.toml as the effective workspace root, so a nested workspace can intentionally override an outer one.

day-shift init --directory packages/service --dry-run
day-shift init --directory packages/service

Initialization modes and options

Command	Effect
day-shift init	Create the complete baseline at the detected repository root.
day-shift init --directory <path>	Target an allowed directory inside that repository.
day-shift init --dry-run	Preview all outcomes with no workspace writes.
day-shift init --no-agent	Skip .day-shift/agents.md.
day-shift init --without-templates	Skip packaged policy packs, user prompts, references, workflows, and templates while retaining their baseline directories.
day-shift init --force	Replace divergent eligible managed defaults; review the force boundary below first.
day-shift init --sandbox-run-id [runId]	Also create or reuse sandbox/run-<id>/ at the selected target; omitting the value generates an id.

Options compose. For example, day-shift init --directory packages/service --no-agent --without-templates --dry-run previews a minimal nested scaffold. A sandbox is disposable run state inside the selected target, not a different workspace root and not a substitute for testing init in a disposable repository.

Generated workspace anatomy

Every run ensures these ten directories exist:

.day-shift/
├── planning/
├── policy-packs/
├── prompts/
│   ├── user/
│   └── latest/
├── references/
├── specs/
├── templates/
└── workflows/

The baseline file contract is:

Path or family	Created by default	Ownership and purpose
.markdownlint.json	Yes	Repository-level recommended Markdown rules; an existing customized file is preserved unless force is explicit.
.day-shift/.markdownlint.json	Yes	Day Shift-scoped Markdown rules; managed default, but safe to inspect and customize deliberately.
.day-shift/config.toml	Yes	Repository configuration marker and effective-root anchor. Configuration precedence belongs to the next getting-started step.
.day-shift/specs/index.json	Yes	Repository-owned source-spec registry initialized with the root registration; never force-overwritten by init.
.day-shift/specs/root-spec.md	Yes	Repository-owned registration anchor for root-spec.md; never force-overwritten by init.
.day-shift/agents.md	Yes, unless --no-agent	Repository agent entrypoint rendered from the shipped scaffold.
.day-shift/policy-packs/**	Unless --without-templates	Packaged enforcement guidance copied as managed starting content.
.day-shift/prompts/user/**	Unless --without-templates	Repository-editable prompt layer. .day-shift/prompts/latest/ is ensured but init does not populate it.
.day-shift/references/**	Unless --without-templates	Packaged command, metadata, planning, and validation references.
.day-shift/workflows/**	Unless --without-templates	Packaged workflow guides used by humans and agents.
.day-shift/templates/**	Unless --without-templates	Local artifact templates and their manifest.json. Use that manifest and the shipped directory as the per-file inventory.
sandbox/run-<id>/	Only with --sandbox-run-id	Local-only, disposable execution state at the selected target. Keep durable specifications and planning outside this tree.

The shared authoring families are discovered recursively from the installed release, so their exact per-file set can evolve with the selected Day Shift version. The family boundaries above are stable; inspect the init dry-run for the exact paths that release will create.

Init does not create .day-shift/local.toml, populate .day-shift/planning/, or install ignore rules. After initialization, run day-shift ignore install separately when you intend to ignore .day-shift/planning/ and .day-shift/local.toml locally.

Repeat runs and existing state

Init plans each managed file independently:

• A missing directory or file is created.
• An existing directory is kept.
• A file that exactly matches the packaged default is kept as a no-op.
• A divergent existing file is preserved by default, including customized prompts, workflows, templates, config, lint rules, and agent guidance.
• --force replaces divergent eligible managed defaults with the selected release’s packaged content.
• .day-shift/specs/index.json and .day-shift/specs/root-spec.md are always protected from force because they carry repository-owned source registration.
• Disabled assets are reported as kept/skipped by --no-agent or --without-templates; those options do not delete files from an existing workspace.

Before force, save a diff or commit, run the same command with --dry-run --force, and inspect every planned overwrite. Force is a packaged-default reset, not a merge: reapply intentional customization afterward. A repeated ordinary run is safe for customized files because it fills missing baseline assets without replacing divergent content.

Recover from stale or partial state

Use the least-mutating route:

Evidence	Safe response
Fresh or partially scaffolded compatible target	Run init --dry-run, inspect missing and preserved paths, then rerun without dry-run.
Customized defaults from an older release	Preserve them, compare against the selected release, and use targeted edits; use --force only for an intentional full default replacement.
Nested workspace initialized in the wrong place	Confirm the nearest .day-shift/config.toml with repository detection/config inspection. Do not manually move .day-shift/; initialize the intended in-repository target and migrate durable work deliberately.
Doctor reports incompatible, stale-schema, or partially migrated state	Stop init writes. Run read-only day-shift doctor --format json, then preview the supported complete migration with day-shift workspace migrate --target-schema-version <supported-version> --dry-run. Apply only with the command’s explicit confirmation contract.
Interrupted force or uncertain overwrite	Inspect repository history/backups and the dry-run plan before retrying. Restore user-owned customization from version control rather than deleting the workspace.

Never delete, rearrange, or bulk-copy .day-shift/ as a first recovery step. Specifications, planning evidence, local configuration, and customized authoring assets can be user-owned even when their directories began as init scaffolding.

For a release-to-release comparison, recoverable three-way body merge, stale prompt/template classification, or generated-output refresh, continue with Upgrade prompt and template customizations.

Next steps

1. Run day-shift agent from the effective workspace to read its repository contract.
2. Run day-shift ignore install only if the recommended local-only ignore boundary matches your workflow.
3. Continue with Configuration and first health checks to inspect effective values, preview shell integration, diagnose workspace health, and enter planning safely.
4. If setup evidence is inconsistent, use Troubleshooting before authorizing migration or force.