Skip to main content

SPEC_MARKDOWN

Constant SPEC_MARKDOWN 

Source
pub const SPEC_MARKDOWN: &str = "# treeboot Specification v2.6.0\n\nA portable worktree lifecycle helper that lets every coding agent, editor, and\norchestration tool run the same repo-local bootstrap and teardown commands.\n\n**Tags:** compatibility contract, command-line executable, TOML config,\nidempotent default, configured commands, teardown commands, agent-tool aliases\n\n| Term            | Description                                                |\n| --------------- | ---------------------------------------------------------- |\n| Default command | `treeboot` == `treeboot run`                               |\n| Root path       | Source checkout for copy, symlink, and sync operations     |\n| Worktree path   | Current worktree root where operations execute             |\n| Conflict policy | Skip existing by default, strict validates, force replaces |\n| Primary file    | `.treeboot.toml`                                           |\n| Teardown        | Explicit commands run before an external worktree removal  |\n\ntreeboot requires Git 2.36 or newer.\n\n## Intent: One setup contract for many tools\n\nAgentic coding tools already create isolated Git worktrees. The repeated pain is\neverything Git intentionally leaves behind: ignored files, local credentials,\ndependency caches, and per-worktree setup commands.\n\n### Goals\n\n- Provide one repo-local worktree bootstrap command.\n- Avoid duplicate setup files across agent tools.\n- Make common copy, symlink, and sync operations declarative.\n- Allow custom setup through configured commands.\n- Allow explicit cleanup before another tool removes a linked worktree.\n- Be safe and idempotent by default.\n- Ship as a small, portable executable.\n\n### Non-goals\n\n- Create Git worktrees.\n- Remove Git worktrees or branches.\n- Install or enforce hooks around `git worktree remove`.\n- Manage long-running dev servers.\n- Allocate per-worktree ports.\n- Replace tool-specific setup systems entirely.\n- Manage secrets beyond user-configured file operations.\n\n### Design rule\n\ntreeboot should be boring to run repeatedly. File operations are idempotent by\ndefault. Bootstrap and teardown commands always run when their phase is\nexecuted, so users must make configured commands safe to rerun when that\nmatters.\n\n### Conformance scope\n\nA compatible implementation is any executable that provides the observable CLI\nbehavior defined by this specification. The executable\'s implementation\nlanguage, internal APIs, parser library, and release process are outside this\ncontract.\n\nContractual behavior appears as declarative behavior descriptions, required text\nor data shapes, durable output, and explicit mandatory requirements, which\ntypically use `must`. `should` marks non-binding design or adoption guidance.\nExamples and rationale do not add requirements. Placeholder and example values\nare illustrative unless the surrounding text identifies an exact value. A\nconformance result applies to the specification version, host platform, and\ncapabilities exercised by that run. A result on one host does not establish\nsupport for other platforms.\n\n## CLI surface: Subcommands and one default path\n\nThe common integration point is intentionally short: `treeboot`. Tool-specific\nsetup hooks only need to invoke the declarative treeboot config.\n\n`TB-CLI-HELP`: The top-level command, every subcommand, and every nested\nsubcommand must accept `--help`, exit `0`, and write human-readable help to\nstdout. Help must identify the invoked command and its supported arguments,\noptions, and immediate subcommands. Exact layout, capitalization, wrapping, and\nparser-generated prose are not contractual.\n\n`TB-CLI-USAGE`: Invalid command syntax must exit `2`, write a non-empty\ndiagnostic to stderr, and not execute treeboot behavior. This includes unknown\noptions or commands, missing required arguments, conflicting options, and\nunsupported enumerated values. Exact parser wording, suggestions, quoting,\ncolor, and usage layout are not contractual unless another section requires\nspecific text.\n\n### `treeboot run`\n\nRuns worktree bootstrap. This is also the implicit command when no subcommand is\nprovided.\n\n```sh\ntreeboot\ntreeboot run\ntreeboot run --dry-run\ntreeboot run --verbose\ntreeboot run --strict\ntreeboot run --force\ntreeboot run --root /path/to/root-checkout\ntreeboot run --config .treeboot.toml\ntreeboot run --skip-commands\ntreeboot run --dry-run --json\ntreeboot run --skip-commands --json\n```\n\nText is the default output. Structured JSON/YAML output is accepted only when\n`--dry-run` prevents all effects or `--skip-commands` prevents configured\ncommands from writing to stdout. See\n[Structured output formats](#structured-output-formats).\n\n### `treeboot plan`\n\nPlans the bootstrap work that `treeboot run` would perform from the current\nfilesystem state. Planning never writes files or spawns configured commands.\n\n```sh\ntreeboot plan\ntreeboot plan --root /path/to/root-checkout\ntreeboot plan --config .treeboot.toml\ntreeboot plan --strict\ntreeboot plan --force\ntreeboot plan --skip-commands\ntreeboot plan --verbose\ntreeboot plan --json\ntreeboot plan --yaml\n```\n\nPlan uses the same discovery, runtime policy, validation, concrete file\ndecisions, root-checkout behavior, and missing-config behavior as run. It does\nnot accept `--dry-run` because it is always side-effect-free. By default it\nreports configured bootstrap commands as planned work. `--skip-commands` omits\nthem without weakening config parsing or bootstrap validation. Text output uses\nthe same file-decision and `treeboot: would run <label>` lines as run dry-run,\nand also prints each non-fatal validation warning as\n`treeboot: warning: <message>`.\n\n### `treeboot teardown`\n\nRuns configured teardown commands for a linked worktree without removing the\nworktree itself.\n\n```sh\ntreeboot teardown\ntreeboot teardown --dry-run\ntreeboot teardown --yes\ntreeboot teardown --worktree ../feature-branch\ntreeboot teardown --worktree ../feature-branch --yes\ntreeboot teardown --root /path/to/root-checkout\ntreeboot teardown --config .treeboot.toml\n```\n\nThe target defaults to the process working directory. `--worktree <path>` may\npoint anywhere inside another linked worktree and resolves to that worktree\'s\nGit top level. Teardown rejects Git\'s main/root checkout before prompting.\n\n`--yes` is long-only and grants non-interactive approval. Without `--yes`,\nteardown prompts only when stdin is a terminal. `--dry-run` validates and\nreports every teardown command without prompting, requiring `--yes`, or spawning\na process.\n\nTeardown is command-only. It never applies configured file operations, runs\nbootstrap `commands`, removes a worktree, or deletes a branch.\n\nTeardown does not accept `--force` or `--strict`. `--force` remains the\nfile-replacement option, and teardown has no file conflict policy. Use\n`--config` when teardown must require a specific config.\n\n### `treeboot status`\n\nPrints the detected worktree, root checkout, default branch, and config file\nwithout parsing config or running configured commands. `treeboot info` is an\nalias.\n\n```sh\ntreeboot status\ntreeboot status --root /path/to/root-checkout\ntreeboot status --config .treeboot.toml\ntreeboot status --format json\ntreeboot status --format yaml\ntreeboot status --json\ntreeboot status --yaml\ntreeboot info\n```\n\nJSON and YAML output are defined in\n[Structured output formats](#structured-output-formats).\n\n### `treeboot version`\n\nPrints version metadata and exits without discovering Git context or config.\n`treeboot --version` and `treeboot -V` are global version flags. Nested command\nparsers also accept both flags.\n\n```sh\ntreeboot version\ntreeboot version --format json\ntreeboot version --format yaml\ntreeboot version --json\ntreeboot version --yaml\ntreeboot --version\ntreeboot -V\n```\n\nHuman-readable output is a compact, flag-like summary:\n\n```text\ntreeboot <PACKAGE_VERSION> (spec <SPEC_VERSION>)\n```\n\n`TB-CLI-VERSION`: Every version flag must report the implementation\'s package\nversion and implemented specification version and exit `0` without Git or config\ndiscovery. A nested version flag may identify the invoked command in its leading\nlabel; that label and the parser\'s exact formatting are not contractual.\n`treeboot version` text output retains the exact compact summary shape shown\nabove, substituting the implementation\'s actual package version for\n`<PACKAGE_VERSION>` and its implemented specification version for\n`<SPEC_VERSION>`.\n\nJSON and YAML output are defined in\n[Structured output formats](#structured-output-formats).\n\n### `treeboot config`\n\nParses the selected TOML config and prints the normalized file, bootstrap\ncommand, and teardown command operations without executing them.\n\n```sh\ntreeboot config\ntreeboot config --config .treeboot.toml\ntreeboot config --format json\ntreeboot config --format yaml\ntreeboot config --json\ntreeboot config --yaml\n```\n\nThis command is view-only. It is intended for validating and inspecting config\nparsing behavior; editing config values is out of scope.\n\nHuman-readable text output lists normalized source and target values plus\nbehavior-affecting normalized fields such as `required`, `compare`, `delete`,\n`symlinks`, `include`, `ignore`, `allow_failure`, `cwd`, and command `env`\nvalues when present. Before those collections it prints the effective worktree\nID and slug with their normalized `length`, `max_length`, and `separator`\nsettings. It labels bootstrap and teardown command collections separately and\nprints `(none)` for an empty collection. JSON and YAML output emit the effective\nvalues as the top-level `worktree_id` and `worktree_slug` strings and the full\nnormalized config structure, including its fully defaulted settings objects.\n\n### `treeboot check`\n\nValidates the complete selected config contract without applying file operations\nor running bootstrap or teardown commands.\n\n```sh\ntreeboot check\ntreeboot check --root /path/to/root-checkout\ntreeboot check --config .treeboot.toml\ntreeboot check --strict\ntreeboot check --format json\ntreeboot check --format yaml\ntreeboot check --json\ntreeboot check --yaml\n```\n\n`check` resolves the same worktree context and config selection rules as `run`,\nparses and normalizes declarative config, resolves bootstrap runtime policy, and\nindependently validates the bootstrap and teardown plans.\n\nWhen declarative config is selected, config parse and normalization errors are\nfatal to the whole contract. After normalization, bootstrap and teardown\nsemantic validation are independent. `check` evaluates both, preserves both\nfailures when both phases are invalid, reports them in bootstrap-then-teardown\norder, and exits non-zero when either phase fails.\n\nOn success, human-readable output prints:\n\n```text\ntreeboot: check ok\n```\n\nRun validation can produce non-fatal warnings, such as an include list that\nmatches no source paths. `check` prints each warning as a\n`treeboot: warning: ...` line before the final `treeboot: check ok` line and\nstill exits zero.\n\nJSON and YAML output are defined in\n[Structured output formats](#structured-output-formats). Fatal errors still use\ntreeboot\'s normal error reporting and non-zero exit behavior.\n\n### `treeboot init`\n\nCreates a starter config.\n\n```sh\ntreeboot init\ntreeboot init --config\ntreeboot init --path .treeboot.toml\n```\n\nThe default path is `.treeboot.toml`. Existing init targets, including symlinks,\nare never replaced.\n\n### `treeboot schema`\n\nPrints the bundled JSON Schema for treeboot config to stdout and exits without\ndiscovering Git context or config.\n\n```sh\ntreeboot schema\ntreeboot schema --output config.schema.json\ntreeboot schema -o config.schema.json\ntreeboot schema > config.schema.json\n```\n\nThe emitted schema is the canonical config schema at\n`crates/treeboot-spec/assets/treeboot.schema.json`. Stdout and `--output` must\ncontain that document\'s exact UTF-8 bytes without added framing or byte changes.\nWhen `--output` is provided, treeboot writes the schema to that path instead of\nstdout. Parent directories must already exist. Existing regular files are\nreplaced.\n\n`schema` does not support `--format`, `--json`, or `--yaml`; the schema payload\nis already JSON.\n\n### `treeboot copy`\n\nRuns one or more copy operations without running declarative config file\noperations or configured commands.\n\n```sh\ntreeboot copy .env.local\ntreeboot copy .env.local mise.local.toml --target local\ntreeboot copy templates/editorconfig --target .editorconfig\ntreeboot copy shared/config --symlinks preserve\ntreeboot copy shared/config --verbose\n```\n\n### `treeboot symlink`\n\nRuns one or more symlink operations from the root path into the current\nworktree.\n\n```sh\ntreeboot symlink .tool-versions\ntreeboot symlink bin scripts --target .local\ntreeboot symlink shared/bin --target bin\n```\n\n### `treeboot sync`\n\nRuns one or more sync operations without running declarative config file\noperations or configured commands.\n\n```sh\ntreeboot sync shared/config\ntreeboot sync shared/config shared/editor --target .config\ntreeboot sync shared/config --delete\ntreeboot sync shared/config --compare checksum\ntreeboot sync shared/config --verbose\n```\n\n### `treeboot completions`\n\nPrints shell completion scripts for supported shells so package managers and\nusers can install them.\n\n```sh\ntreeboot completions bash\ntreeboot completions zsh\ntreeboot completions fish\ntreeboot completions powershell\ntreeboot completions elvish\n```\n\n`TB-COMPLETION-SCRIPTS`: Each supported shell invocation must emit a usable\nregistration script for the named shell without Git or config discovery. The\ninstalled script must complete the commands, options, option values, and nested\ncommands documented by this specification. The emitted script bytes, helper\nprocess protocol, and environment variables used to obtain candidates are not\ncontractual.\n\n### `treeboot doctor`\n\nPrints diagnostics for the current treeboot environment without applying file\noperations or running configured commands.\n\n```sh\ntreeboot doctor\ntreeboot doctor --root /path/to/root-checkout\ntreeboot doctor --config .treeboot.toml\ntreeboot doctor --strict\ntreeboot doctor --format json\ntreeboot doctor --format yaml\ntreeboot doctor --json\ntreeboot doctor --yaml\n```\n\n`doctor` checks Git availability, worktree discovery, root path discovery,\ndefault branch discovery, child environment construction, config discovery, and\nboth bootstrap and teardown validation when config is selected. It reports\nseparate phase diagnostics from the same complete-config validation result used\nby `check`. It is intended for human troubleshooting. Warnings do not fail the\ncommand, but fatal discovery or config errors exit non-zero.\n\n`--strict` makes doctor report missing config, root-checkout execution context,\nand strict file-operation validation failures as fatal diagnostics while still\nprinting the diagnostics report when possible. `TREEBOOT_STRICT=true` applies\nthe same strict pre-config diagnostics and config validation. Config-level\n`strict = true` applies to config validation only, because config-level options\nare not loaded before root-checkout or missing-config checks.\n\nJSON and YAML output are defined in\n[Structured output formats](#structured-output-formats).\n\n### `treeboot env`\n\nPrints the environment variables treeboot passes to configured commands.\n\n```sh\ntreeboot env\ntreeboot env --config .treeboot.toml\ntreeboot env --root /path/to/root-checkout\ntreeboot env --format json\ntreeboot env --format yaml\ntreeboot env --json\ntreeboot env --yaml\n```\n\nThe text format is one `KEY=value` pair per line, sorted by variable name.\nValues are resolved for the current worktree context and selected config. `env`\ndiscovers and parses config to resolve the effective worktree ID and slug, but\ndoes not apply file operations or run commands. Missing discovered config uses\ndefault identity settings. A missing explicit config or any invalid selected\nconfig is an error.\n\nJSON and YAML output are defined in\n[Structured output formats](#structured-output-formats).\n\n`env` prints only the treeboot-owned child environment variables described in\n[Environment variables](#compatibility-environment-variables). It does not print\nthe full process environment, per-command `env` overlays, or the config option\noverride variables that treeboot reads from its parent environment.\n\n### `treeboot worktree`\n\nDerives a stable Treeboot ID and readable slug for one target, or inventories\nthe registered worktrees in the current Git repository.\n\n```sh\ntreeboot worktree id\ntreeboot worktree id ../prospective-worktree\ntreeboot worktree slug\ntreeboot worktree slug ../prospective-worktree\ntreeboot worktree path k7m2qx\ntreeboot worktree list\ntreeboot worktree id --json\ntreeboot worktree slug --yaml\ntreeboot worktree path k7m2qx --yaml\ntreeboot worktree list --format json\n```\n\nWithout `PATH`, `worktree id` and `worktree slug` discover and fully parse the\ncurrent worktree\'s config using the same rules as `treeboot env`. Text output is\nthe requested effective value followed by a newline.\n\nWith `PATH`, both commands derive identity for the exact target rather than\nreplacing it with an enclosing Git worktree root. A relative input resolves\nagainst the process current directory. The result is normalized to an absolute\npath by canonicalizing the longest existing ancestor and lexically normalizing\nany missing suffix. An explicitly supplied empty argument is a usage error.\nWindows drive-relative paths such as `C:target` and root-relative paths without\na drive or share such as `\\target` are unsupported path errors; they are not\njoined to the current directory. Existing non-directory targets are errors,\nincluding regular files, symlinks to files, and dangling symlinks. Ordinary\ndirectories, symlinks to directories, and nonexistent targets work outside Git.\n\nAn existing target directory uses config discovered directly within that\ndirectory and fully parses the selected file. A nonexistent target uses default\nidentity settings. Invalid discovered config is fatal before output even when\nthe invalid declaration is unrelated to identity. Explicit mode ignores ambient\nroot and default-branch compatibility overrides. Git discovery is optional and\nstarts from the exact target when it exists or its nearest existing directory\nancestor otherwise. It may supply only the main-worktree basename used by the\nslug\'s readable fallback and never replaces the exact hash target.\n\nEquivalent relative, absolute, symlink, `.`, and `..` spellings normalize to one\nidentity. A nonexistent target retains that identity after creation as an\nordinary directory while the normalized target remains the same. For an actual\nGit worktree, explicit and implicit invocations produce the same values.\n\n`worktree path <ID>` enumerates all of the current repository\'s registered,\nnon-bare worktrees whose paths still exist. Every candidate path is\ncanonicalized, then that candidate\'s discovered config is fully parsed. The\ncomplete effective ID is compared exactly and case-sensitively. The main\nworktree participates. Text output is the matching canonical absolute path\nfollowed by a newline.\n\nNo match exits non-zero. Multiple matches are a distinct error that reports\nevery matching canonical path. Lookup always scans every candidate before\nsucceeding so a later collision cannot be missed.\n\n`worktree list` uses the same candidate discovery and identity generation. Text\noutput is an `ID`, `SLUG`, and `PATH` table. The main worktree is first and\nremaining entries are sorted by canonical path. Duplicate IDs and slugs remain\nvisible and do not make listing fail. Only ID collisions affect lookup. On Unix,\n`worktree path` and `worktree list` text output preserve native path bytes\nexactly.\n\nMissing registered paths are stale and skipped without changing Git metadata.\nBare records are excluded from inventory and reverse lookup, but a bare primary\nrepository remains the Git main-worktree identity used to resolve linked\nworktree context. An existing candidate that cannot be canonicalized,\ndiscovered, or fully parsed makes the complete operation fail. A candidate that\ndisappears during inspection is skipped only when the failure is a not-found I/O\nerror; other failures are fatal and attributed to the candidate path. Reports\nare collected before rendering, so a candidate failure does not leave partial\nstandard output.\n\nAmbient recognized Treeboot environment inputs remain honored by implicit\nsingle-target and repository-wide inspection. Explicit `id PATH` and `slug PATH`\nignore them. These commands do not accept `--root` or `--config`.\n\n### Manual file operation commands\n\n`copy`, `symlink`, and `sync` expose the same file operation engine used by\ndeclarative config. Each command requires at least one source argument. Multiple\nsource arguments create multiple independent file operations. These commands\nstill discover the root path and worktree path, but they do not run configured\ncommands.\n\nAfter worktree/root context checks, manual file operation commands discover and\nparse config when one is present only to load top-level runtime policy. They\nignore the config\'s file operations, bootstrap commands, and teardown commands.\nIf config parsing is reached and the config is invalid, the manual command fails\nbefore applying file operations.\n\nWith one source, `--target` is the exact target path. With multiple sources,\n`--target` is a directory or path prefix joined with each source value. For\nexample, `treeboot copy .env.local mise.local.toml --target local` copies\n`.env.local` to `local/.env.local` and `mise.local.toml` to\n`local/mise.local.toml`.\n\nManual commands apply the same output contract as declarative file operations.\nMultiple source arguments create multiple top-level file operations for output\nand progress as well as execution. A command such as\n`treeboot copy a b --target local` reports separate decisions for `a -> local/a`\nand `b -> local/b`; it does not collapse them into one command-wide summary.\n\nOperation-specific flags are valid only on the commands listed in the option\ntable. For example, using `--compare` on `copy` or `--symlinks` on `symlink` is\na CLI usage error and exits with code `2`.\n\n| Option                                                     | Scope                                                              | Behavior                                                                                                                                                                                                                                                                    |\n| ---------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `-r`, `--root <path>`                                      | run/plan/teardown/status/config/check/copy/symlink/sync/doctor/env | Overrides the root checkout used for discovery and file-operation context.                                                                                                                                                                                                  |\n| `-c`, `--config <path>`                                    | run/plan/teardown/status/config/check/doctor/env                   | Uses one specific config file and skips config discovery. For teardown and env, relative paths resolve from the selected worktree.                                                                                                                                          |\n| `--worktree <path>`                                        | teardown                                                           | Selects the linked worktree to tear down. Defaults to the process working directory; a path inside a worktree resolves to its Git top level.                                                                                                                                |\n| `-o`, `--format <text\\|json\\|yaml>`                        | run/plan/status/version/config/check/doctor/env/worktree leaves    | Selects human-readable, JSON, or YAML output. Defaults to `text`. Structured run requires `--dry-run` or `--skip-commands`.                                                                                                                                                 |\n| `-J`, `--json`                                             | run/plan/status/version/config/check/doctor/env/worktree leaves    | Shortcut for `--format json`. Conflicts with `--format` and `--yaml`.                                                                                                                                                                                                       |\n| `-Y`, `--yaml`                                             | run/plan/status/version/config/check/doctor/env/worktree leaves    | Shortcut for `--format yaml`. Conflicts with `--format` and `--json`.                                                                                                                                                                                                       |\n| `-V`, `--version`                                          | global and nested command parsers                                  | Prints package and spec version details and exits before command validation.                                                                                                                                                                                                |\n| `-o`, `--output <path>`                                    | schema                                                             | Writes the bundled config schema to a file instead of stdout.                                                                                                                                                                                                               |\n| `-S`, `--strict`                                           | run/plan/check/copy/symlink/sync/doctor                            | Fails if a copy/symlink target exists; rejects sync operations; exits non-zero when run from the root checkout. Declarative config can also enable strict mode with top-level `strict = true`. For doctor, strict failures are reported as fatal diagnostics when possible. |\n| `-f`, `--force`                                            | run/plan/copy/symlink/sync                                         | Replaces existing file-operation targets where supported.                                                                                                                                                                                                                   |\n| `-n`, `--dry-run`                                          | run/teardown/copy/symlink/sync                                     | Prints planned work without writing files or running commands. Teardown does not prompt or require `--yes`.                                                                                                                                                                 |\n| `-v`, `--verbose`                                          | run/plan/copy/symlink/sync                                         | Prints detailed file-operation actions instead of compact summaries. Interactive progress is disabled in verbose mode. JSON/YAML run and plan reject it.                                                                                                                    |\n| `--skip-commands`                                          | run/plan                                                           | Omits configured bootstrap commands. Run applies or previews files only; plan omits commands from the report.                                                                                                                                                               |\n| `--yes`                                                    | teardown                                                           | Long-only explicit approval that suppresses the terminal confirmation prompt. It does not bypass discovery, parsing, or validation.                                                                                                                                         |\n| `-t`, `--target <path>`                                    | copy/symlink/sync                                                  | Overrides the target. With multiple sources, acts as the target path prefix for each source.                                                                                                                                                                                |\n| `--required`                                               | copy/symlink/sync                                                  | Fails when any requested source does not exist.                                                                                                                                                                                                                             |\n| `--symlinks <preserve>`                                    | copy/sync                                                          | Selects how source symlinks are handled. The initial supported value is `preserve`.                                                                                                                                                                                         |\n| `--include <pattern>`                                      | copy/sync                                                          | Repeats to narrow directory operations to source paths matching operation-local include patterns. Patterns use gitignore-style syntax without `!` negation and are not read from `.gitignore` files. Conflicts with `--delete` / `-D`.                                      |\n| `--ignore <pattern>`                                       | copy/sync                                                          | Repeats to skip source paths matching operation-local ignore patterns. Patterns use gitignore-style syntax and are not read from `.gitignore` files.                                                                                                                        |\n| `--ignore-metadata <permissions\\|owner\\|group\\|ownership>` | copy/sync                                                          | Repeats to opt out of metadata comparison and preservation. `ownership` means owner and group.                                                                                                                                                                              |\n| `--compare <metadata\\|checksum>`                           | sync                                                               | Selects sync comparison behavior.                                                                                                                                                                                                                                           |\n| `-D`, `--delete` / `--no-delete`                           | sync                                                               | Controls whether sync deletes target-only files. Defaults to `--no-delete`.                                                                                                                                                                                                 |\n| `--config`                                                 | init                                                               | Creates a starter TOML config. This intentionally has no short alias so `-c` can consistently mean config path for run/teardown/config.                                                                                                                                     |\n| `-p`, `--path <path>`                                      | init                                                               | Writes the generated init output to a custom path.                                                                                                                                                                                                                          |\n\n## Structured output formats\n\nCommands that accept `--format json`, `--json`, `--format yaml`, or `--yaml`\nmust emit the structures in this section. JSON output is pretty-printed and YAML\noutput uses the same field names, values, and nesting as JSON. Path values are\nstrings. Optional values are `null` when absent. Tagged enum values are\nlowercase `snake_case` strings. JSON object member order is not part of the\ncontract.\n\nStructured path values require valid UTF-8. If any path cannot be represented by\nthe JSON/YAML string schema, serialization fails before stdout is written. Use\ntext output when native non-UTF-8 Unix path bytes must be preserved.\n\nThe shared worktree context object has this shape:\n\n```json\n{\n  \"root_path\": \"/repo\",\n  \"worktree_path\": \"/repo-worktree\",\n  \"default_branch\": \"main\"\n}\n```\n\n### `treeboot status` JSON\n\n`treeboot status`, and its `treeboot info` alias, emit a discovery report:\n\n```json\n{\n  \"context\": {\n    \"root_path\": \"/repo\",\n    \"worktree_path\": \"/repo-worktree\",\n    \"default_branch\": \"main\"\n  },\n  \"config\": \"/repo-worktree/.treeboot.toml\"\n}\n```\n\n`config` is a path string or `null`.\n\n### `treeboot version` JSON\n\n`treeboot version` emits package and implemented-spec metadata:\n\n```json\n{\n  \"package\": \"treeboot\",\n  \"version\": \"<PACKAGE_VERSION>\",\n  \"spec_version\": \"<SPEC_VERSION>\"\n}\n```\n\n`package` is the CLI package name. `version` is the package version.\n`spec_version` is the TreeBoot spec version implemented by the build. The\nangle-bracketed values above are placeholders, not literals.\n\n### `treeboot config` JSON\n\n`treeboot config` emits the selected config path and normalized config:\n\n```json\n{\n  \"path\": \"/repo-worktree/.treeboot.toml\",\n  \"worktree_id\": \"a1b2c3\",\n  \"worktree_slug\": \"repo-worktree-a1b2c3\",\n  \"config\": {\n    \"strict\": false,\n    \"default_ignore\": [],\n    \"dangerously_allow_sources_outside_root\": false,\n    \"dangerously_allow_targets_outside_worktree\": false,\n    \"worktree_id\": {\n      \"length\": 6\n    },\n    \"worktree_slug\": {\n      \"max_length\": 48,\n      \"separator\": \"-\"\n    },\n    \"files\": [\n      {\n        \"operation\": \"copy\",\n        \"source\": \".env\",\n        \"target\": \".env\",\n        \"source_path\": \"/repo/.env\",\n        \"target_path\": \"/repo-worktree/.env\",\n        \"required\": false,\n        \"compare\": null,\n        \"delete\": null,\n        \"symlinks\": \"preserve\",\n        \"include\": [],\n        \"ignore\": [],\n        \"ignore_metadata\": [],\n        \"declaration\": {\n          \"start\": 0,\n          \"end\": 15,\n          \"line\": 1,\n          \"column\": 1\n        }\n      }\n    ],\n    \"commands\": [\n      {\n        \"name\": \"Install packages\",\n        \"command\": {\n          \"kind\": \"shell\",\n          \"run\": \"mise install\"\n        },\n        \"cwd\": null,\n        \"cwd_path\": null,\n        \"env\": {},\n        \"allow_failure\": false,\n        \"declaration\": {\n          \"start\": 17,\n          \"end\": 50,\n          \"line\": 3,\n          \"column\": 1\n        }\n      }\n    ],\n    \"teardown_commands\": [\n      {\n        \"name\": \"Drop database\",\n        \"command\": {\n          \"kind\": \"shell\",\n          \"run\": \"mise run db:drop\"\n        },\n        \"cwd\": null,\n        \"cwd_path\": null,\n        \"env\": {},\n        \"allow_failure\": false,\n        \"declaration\": {\n          \"start\": 52,\n          \"end\": 98,\n          \"line\": 5,\n          \"column\": 1\n        }\n      }\n    ]\n  }\n}\n```\n\nThe top-level `worktree_id` and `worktree_slug` strings are the effective\nidentity values for the selected worktree. `config.worktree_id` and\n`config.worktree_slug` contain their normalized settings.\n\n`files`, `commands`, and `teardown_commands` are ordered arrays. Omitted\ncollections normalize to empty arrays. File `operation` is `copy`, `symlink`, or\n`sync`. `compare` is `metadata`, `checksum`, or `null`. `delete` is a boolean or\n`null`. `symlinks` is `preserve` or `null`. `include` is an ordered array of\noperation-local path include patterns. `ignore` is an ordered array of\noperation-local path ignore patterns. `ignore_metadata` is an ordered array of\ncanonical ignored metadata fields: `permissions`, `owner`, and `group`. Config\ninput can use `ownership` as a shorthand, but normalized inspection output\nexpands it to `owner` and `group`.\n\nCommand `name`, `cwd`, and `cwd_path` are strings or `null`. `env` is an object\nwhose keys and values are strings. `command` is one of:\n\n```json\n{\n  \"kind\": \"shell\",\n  \"run\": \"mise install\"\n}\n```\n\n```json\n{\n  \"kind\": \"direct\",\n  \"program\": \"npm\",\n  \"args\": [\n    \"install\"\n  ]\n}\n```\n\nEach `declaration` object describes the byte and one-based line/column location\nof the source TOML declaration:\n\n```json\n{\n  \"start\": 0,\n  \"end\": 15,\n  \"line\": 1,\n  \"column\": 1\n}\n```\n\n### `treeboot check` JSON\n\n`treeboot check` emits the resolved context, the selected bootstrap action, and\nnon-fatal run-validation warnings:\n\n```json\n{\n  \"context\": {\n    \"root_path\": \"/repo\",\n    \"worktree_path\": \"/repo-worktree\",\n    \"default_branch\": \"main\"\n  },\n  \"action\": {\n    \"kind\": \"config\",\n    \"path\": \"/repo-worktree/.treeboot.toml\"\n  },\n  \"warnings\": []\n}\n```\n\n`warnings` is an ordered array of human-readable warning strings produced by run\nvalidation, such as an include list that matches no source paths. It is empty\nwhen validation produces no warnings.\n\n`action` is one of:\n\n```json\n{ \"kind\": \"missing_config\" }\n```\n\n```json\n{ \"kind\": \"root_worktree_skipped\" }\n```\n\n```json\n{\n  \"kind\": \"config\",\n  \"path\": \"/repo-worktree/.treeboot.toml\"\n}\n```\n\n### `treeboot plan` and structured `treeboot run`\n\nPlan and the safe structured run modes emit one complete bootstrap report:\n\n```json\n{\n  \"mode\": \"plan\",\n  \"context\": {\n    \"root_path\": \"/repo\",\n    \"worktree_path\": \"/repo-worktree\",\n    \"default_branch\": \"main\"\n  },\n  \"action\": {\n    \"kind\": \"config\",\n    \"path\": \"/repo-worktree/.treeboot.toml\"\n  },\n  \"has_file_changes\": true,\n  \"file_summary\": {\n    \"changed\": 4,\n    \"skipped\": 2,\n    \"deleted\": 1,\n    \"metadata_changed\": 1,\n    \"file_warnings\": 1\n  },\n  \"files\": [\n    {\n      \"operation\": \"sync\",\n      \"source\": \"shared\",\n      \"target\": \"shared\",\n      \"summary\": {\n        \"changed\": 4,\n        \"skipped\": 2,\n        \"deleted\": 1,\n        \"metadata_changed\": 1,\n        \"file_warnings\": 1,\n        \"expanded\": true,\n        \"skip_reason\": null\n      }\n    }\n  ],\n  \"commands_skipped\": false,\n  \"commands\": [\n    {\n      \"label\": \"Install packages: mise run setup\",\n      \"allow_failure\": false\n    }\n  ],\n  \"validation_warnings\": [],\n  \"file_warnings\": [\n    {\n      \"path\": \"shared/current\",\n      \"reason\": \"symlink target does not exist\"\n    }\n  ],\n  \"execution_warnings\": []\n}\n```\n\n`mode` is `plan` for `treeboot plan`, `dry_run` for structured run with\n`--dry-run`, and `execute` for structured run with `--skip-commands` but no\n`--dry-run`.\n\nThe `action` variants match check: `missing_config`, `root_worktree_skipped`, or\n`config` with its path. Missing discovered config and non-strict root-worktree\ninvocations are successful empty reports. An explicitly requested missing config\nremains an error, as do strict missing-config and root-worktree cases.\n\n`files` preserves config declaration order and contains one entry for every\nnormalized top-level file operation, including operations with zero decisions.\nEach operation `summary` uses the current concrete filesystem decisions.\n`changed` counts creates, updates, replacements, and metadata repairs. `deleted`\ncounts sync deletions. A metadata repair increments both `changed` and\n`metadata_changed`. `file_warnings` counts concrete planning warnings. Aggregate\ncounts equal the sums of the operation counts. An expanded operation always has\n`skip_reason: null`; one unexpanded skip includes its reason.\n\n`has_file_changes` is true exactly when `file_summary.changed > 0` or\n`file_summary.deleted > 0`. Skips and warnings do not make it true.\n\n`commands` preserves config declaration order and uses the labels from text\ndry-run output. `commands_skipped` is true, and `commands` is empty, when\n`--skip-commands` is selected. Structured execute mode therefore always omits\ncommands. A consumer interested in all planned bootstrap work checks\n`has_file_changes || !commands.is_empty()`.\n\n`validation_warnings` contains ordered human-readable `ActionPlan` warnings.\n`file_warnings` contains ordered path/reason pairs from concrete planning, and\nits length equals the aggregate warning count. `execution_warnings` contains\nordered path/reason pairs produced while files are applied, currently ownership\npreservation warnings. It is empty in plan and dry-run modes. Execution warnings\ndo not change the precomputed file counts.\n\nJSON/YAML run output is valid only with `--dry-run` or `--skip-commands`.\n`treeboot run --json`, `treeboot run --yaml`, and equivalent non-text format\nuses without either option are usage errors. Structured run and plan also reject\n`--verbose`. These checks happen before Git or config discovery. Any implicit\nrun option placed before an explicit subcommand is a usage error. Implicit run\noptions are accepted before command selection only when no subcommand follows.\n\nStructured output never contains configured command stdout. Dry-run never spawns\ncommands, while `--skip-commands` omits them. Implementations must buffer the\ncomplete document before writing stdout. A structured executing run must\npreflight every prepared action path before mutation. A later execution failure\nmay retain the same partial file effects as text execution, but stdout remains\nempty. Successful reports exit `0` whether or not changes exist.\n\n### `treeboot doctor` JSON\n\n`treeboot doctor` emits an ordered diagnostics report:\n\n```json\n{\n  \"fatal\": false,\n  \"context\": {\n    \"root_path\": \"/repo\",\n    \"worktree_path\": \"/repo-worktree\",\n    \"default_branch\": \"main\"\n  },\n  \"diagnostics\": [\n    {\n      \"name\": \"worktree\",\n      \"status\": \"ok\",\n      \"message\": \"worktree context resolved\"\n    },\n    {\n      \"name\": \"config\",\n      \"status\": \"ok\",\n      \"message\": \"config is valid: /repo-worktree/.treeboot.toml\"\n    },\n    {\n      \"name\": \"teardown_validation\",\n      \"status\": \"ok\",\n      \"message\": \"teardown config is valid\"\n    }\n  ]\n}\n```\n\n`fatal` is `true` when any diagnostic is fatal. `context` is the shared context\nobject or `null` when context discovery fails. Each diagnostic has a stable\n`name`, a `status` of `ok`, `warning`, or `error`, and a human-readable\n`message`.\n\nThe diagnostic names defined by this spec are `environment_options`, `worktree`,\n`root`, `root_worktree`, `default_branch`, `environment`, `config`,\n`config_validation`, and `teardown_validation`. Bootstrap validation preserves\nthe spec-2.0 behavior: success uses `config` with `config is valid: <path>`,\nwhile failure uses `config_validation`. Teardown validation is reported\nseparately as `teardown_validation`.\n\nThe `default_branch` diagnostic is `ok` when a non-empty default branch was\nresolved and `warning` when default branch discovery falls back to the\nbest-effort empty string. An unknown default branch is not fatal; treeboot still\nsets `TREEBOOT_DEFAULT_BRANCH` and `CONDUCTOR_DEFAULT_BRANCH` to an empty\nstring.\n\n### `treeboot env` JSON\n\n`treeboot env` emits an object containing only treeboot-owned child environment\nvariables:\n\n```json\n{\n  \"CODEX_SOURCE_TREE_PATH\": \"/repo\",\n  \"CODEX_WORKTREE_PATH\": \"/repo-worktree\",\n  \"CONDUCTOR_DEFAULT_BRANCH\": \"main\",\n  \"CONDUCTOR_ROOT_PATH\": \"/repo\",\n  \"CONDUCTOR_WORKSPACE_PATH\": \"/repo-worktree\",\n  \"GIT_SOURCE_TREE_PATH\": \"/repo\",\n  \"GIT_WORKTREE_PATH\": \"/repo-worktree\",\n  \"SUPERSET_ROOT_PATH\": \"/repo\",\n  \"TREEBOOT_DEFAULT_BRANCH\": \"main\",\n  \"TREEBOOT_ROOT_PATH\": \"/repo\",\n  \"TREEBOOT_WORKTREE_ID\": \"nw67nj\",\n  \"TREEBOOT_WORKTREE_PATH\": \"/repo-worktree\",\n  \"TREEBOOT_WORKTREE_SLUG\": \"repo-worktree-nw67nj\"\n}\n```\n\nKeys are variable names and values are strings. The object excludes the parent\nprocess environment, per-command config overlays, and config option override\nvariables that treeboot reads from the parent environment.\n\n### `treeboot worktree` JSON\n\n`treeboot worktree id` emits:\n\n```json\n{\n  \"id\": \"nw67nj\"\n}\n```\n\n`treeboot worktree slug` emits:\n\n```json\n{\n  \"slug\": \"repo-worktree-nw67nj\"\n}\n```\n\n`treeboot worktree path <ID>` emits:\n\n```json\n{\n  \"id\": \"nw67nj\",\n  \"path\": \"/repo-worktree\"\n}\n```\n\n`treeboot worktree list` emits:\n\n```json\n{\n  \"worktrees\": [\n    {\n      \"id\": \"a1b2c3\",\n      \"slug\": \"repo-a1b2c3\",\n      \"path\": \"/repo\"\n    },\n    {\n      \"id\": \"nw67nj\",\n      \"slug\": \"repo-worktree-nw67nj\",\n      \"path\": \"/repo-worktree\"\n    }\n  ]\n}\n```\n\nThe YAML forms have the same fields and nesting.\n\n### `treeboot schema` JSON\n\n`treeboot schema` emits the bundled config JSON Schema document directly. It is\nnot wrapped in a treeboot report object and it does not support the structured\noutput flags. The schema payload is defined by\n`crates/treeboot-spec/assets/treeboot.schema.json`.\n\n### Commands without structured output\n\n`treeboot teardown`, `treeboot init`, `treeboot copy`, `treeboot symlink`,\n`treeboot sync`, and `treeboot completions` do not support `--format`, `--json`,\nor `--yaml`. Their output is text-only and follows the command sections plus\n[Operator experience](#operator-experience-output-and-exit-codes).\n\n## Path model: Root path feeds the worktree path\n\nUser-facing docs use \"root path\" instead of \"main worktree\" to avoid confusion\nwith main branches. The spec still explains that Git\'s main worktree is the\ndefault source when no override exists.\n\n### Root path\n\nSource checkout treeboot reads from. Defaults to Git\'s main worktree, but can be\noverridden.\n\n### Worktree path\n\nCurrent worktree root. File targets and command execution are anchored here.\n\nThe current worktree path resolved from `git rev-parse --show-toplevel`\npreserves platform-native filesystem path data. On Unix, this includes non-UTF-8\nbytes and boundary whitespace. Only Git\'s single trailing LF delimiter is\nremoved.\n\n### Root Path Discovery\n\nThe root path is the checkout used as the source for copy, symlink, and sync\noperations.\n\n1. Use `--root`, if provided.\n2. Use `TREEBOOT_ROOT_PATH`, if set.\n3. Use `CODEX_SOURCE_TREE_PATH`, if set.\n4. Use `CONDUCTOR_ROOT_PATH`, if set.\n5. Use `SUPERSET_ROOT_PATH`, if set.\n6. Use Git\'s main worktree from `git worktree list --porcelain -z`.\n\nGit-discovered worktree and root paths preserve platform-native filesystem path\ndata. On Unix, this includes non-UTF-8 bytes and boundary whitespace. Git\'s\nNUL-delimited worktree output is parsed as bytes so path quoting and embedded\nnewlines cannot change the discovered root path.\n\nTreeboot always retains Git\'s discovered main-worktree path as a separate\nidentity used for root-target checks. `--root` and environment aliases override\nthe file-operation source root only; they cannot make the actual main worktree\nlook like a linked worktree.\n\nIf no root path can be determined, `treeboot run` fails with a clear error.\n\n### Root Checkout No-op\n\nIf Git\'s actual main-worktree identity and the current worktree path are the\nsame, `treeboot run` is running from the root checkout rather than a separate\nworktree. This classification is unchanged by source-root overrides.\n\nIn the default mode, treeboot prints `This is not a work tree` and exits\nsuccessfully before discovering config. In strict mode enabled by `--strict` or\n`TREEBOOT_STRICT`, treeboot prints the same info message and exits non-zero.\nConfig-level `strict` is not loaded before this check.\n\nThe same root-checkout behavior applies to manual `copy`, `symlink`, and `sync`\ncommands. In default mode they exit successfully without applying file\noperations. In strict mode they exit non-zero before applying file operations.\n`treeboot doctor` reports root-checkout strictness as a fatal `root_worktree`\ndiagnostic instead of exiting before printing the diagnostics report.\n\n`treeboot teardown` has no root-checkout no-op. It rejects the main/root\ncheckout with exit code `1` before loading config or reading confirmation input.\nTeardown is only valid for a linked worktree. Bootstrap strictness does not\nchange this rule.\n\n### Default Branch Discovery\n\n`TREEBOOT_DEFAULT_BRANCH` is best effort. treeboot uses an existing\n`CONDUCTOR_DEFAULT_BRANCH` value if present, otherwise resolves `origin/HEAD`,\notherwise sets an empty string. When resolved from Git, the value is the short\nbranch name, such as `main`, not `origin/main` or a full ref path.\n\n## Compatibility: Environment variables\n\nConfigured commands adapted from Codex, Conductor, or Superset setup scripts\nshould usually work with minimal changes. treeboot sets canonical variables plus\naliases for common setup-script ecosystems.\n\n### Scope\n\ntreeboot builds one environment variable set for the resolved worktree and\napplies it when executing bootstrap or teardown commands from declarative\nconfig.\n\n### Config option environment overrides\n\nBootstrap and manual file-operation flows read environment variables for\nconfig-level boolean options. Values `1`, `true`, `yes`, and `on` enable an\noption; `0`, `false`, `no`, and `off` disable it. Invalid values are errors\nbefore bootstrap file operations or commands run.\n\n```text\nTREEBOOT_STRICT\nTREEBOOT_DANGEROUSLY_ALLOW_SOURCES_OUTSIDE_ROOT\nTREEBOOT_DANGEROUSLY_ALLOW_TARGETS_OUTSIDE_WORKTREE\n```\n\nThese variables affect bootstrap file planning and manual file operations.\nCommand-only teardown does not parse or resolve bootstrap runtime policy, so\neven invalid values do not fail teardown. They do not make a missing discovered\nteardown config fatal, permit teardown of the root checkout, or change teardown\ncommand planning.\n\n### Canonical\n\n```text\nTREEBOOT_ROOT_PATH\nTREEBOOT_WORKTREE_PATH\nTREEBOOT_WORKTREE_ID\nTREEBOOT_WORKTREE_SLUG\nTREEBOOT_DEFAULT_BRANCH\n```\n\n### Worktree ID and slug\n\n`TREEBOOT_WORKTREE_ID` is a stable compact ID shared by bootstrap and teardown\ncommands. It contains only a configured prefix of the path digest.\n`TREEBOOT_WORKTREE_SLUG` is the readable companion containing a sanitized name,\none configured separator, and the complete ID:\n\n```text\nTREEBOOT_WORKTREE_ID=k7m2qx\nTREEBOOT_WORKTREE_SLUG=feature-login-k7m2qx\n```\n\nTwo optional top-level inline objects control the values:\n\n```toml\nworktree_id = { length = 6 }\nworktree_slug = { max_length = 48, separator = \"-\" }\n```\n\nAll fields independently default. `worktree_id.length` must be in `1..=52`.\n`worktree_slug.separator` must be exactly `-` or `_`. `worktree_slug.max_length`\nmust be at least `worktree_id.length + 2` so the slug can hold one readable\ncharacter, one separator, and the complete ID. Validation happens after omitted\nfields default, so `worktree_id = { length = 50 }` is invalid against the\ndefault slug maximum of 48. Normalized config output always includes both\nsettings objects and all of their fields. The unreleased composite `worktree_id`\nfields `max_length`, `hash_length`, and `separator` are unknown fields; there\nare no compatibility aliases for that shape. There is no environment or CLI\noverride for these settings.\n\nThe identity digest is SHA-256 over a platform-native, domain-separated byte\nsequence:\n\n```text\n<ASCII \"treeboot-worktree-id-v1\"><NUL><ASCII platform><NUL><canonical path bytes>\n```\n\nOn Unix, `platform` is `unix` and the final bytes are the canonical worktree\npath\'s raw `OsStr` bytes. On Windows, `platform` is `windows` and the final\nbytes are the canonical worktree path\'s UTF-16 code units serialized\nlittle-endian. The canonical `Worktree.worktree_path` is the only identity\ninput: root-source overrides, current directory, branch, config path, and\nmanager state do not affect it. No additional case folding occurs.\n\nTreat the 256-bit digest as a big-endian bitstream and encode it without padding\nusing the lowercase Crockford alphabet:\n\n```text\n0123456789abcdefghjkmnpqrstvwxyz\n```\n\nConsume five bits per character from most to least significant. Left-align the\nfinal remaining high bit and fill its low four bits with zero, producing 52\ncharacters for the complete digest. Retain the first `worktree_id.length`\ncharacters as the complete ID. Readable naming and slug settings never affect\nthe ID.\n\nChoose the readable source using the first matching complete trailing component\npattern:\n\n| Manager       | Trailing path pattern                                          | Readable source              |\n| ------------- | -------------------------------------------------------------- | ---------------------------- |\n| Codex/ChatGPT | `.../.codex/worktrees/<opaque>/<project>`                      | `<project>`                  |\n| Claude Code   | `.../<project>/.claude/worktrees/<name>`                       | `<name>`                     |\n| T3 Code       | `.../.t3/worktrees/<project>/t3code-<opaque>`                  | `<project>`                  |\n| Conductor     | `.../conductor/workspaces/<project>/<city>`                    | `<project>` plus `<city>`    |\n| Superset      | `.../.superset/worktrees/<project>/<workspace>/<workspace...>` | Components after `<project>` |\n| Generic       | no recognized pattern                                          | Worktree basename            |\n\nHere `...` consumes any leading components and Superset requires one or more\ncomponents after the project. Matches are component-wise and use the literal\nmarker spelling; Treeboot does not read `HOME`, `CODEX_HOME`, or other vendor\nenvironment variables.\n\nA selected single component is considered mechanical when it is a canonical\nhexadecimal UUID in `8-4-4-4-12` form, a hexadecimal token of at least eight\ncharacters, or `t3code-` followed by a non-empty ASCII alphanumeric, `_`, or `-`\ntoken. When Git supplies a main-worktree fallback, mechanical names use that\nfallback. Without one, including non-Git explicit targets, the target basename\nis retained as the deterministic readable source.\n\nSanitize the selected native components lossily for the slug while retaining\nexact native bytes for hashing: lowercase ASCII letters, retain ASCII letters\nand digits, replace each maximal run of all other characters (including\ncomponent boundaries) with one configured separator, and trim boundary\nseparators. If nothing remains, sanitize the main-worktree basename when\navailable, then the target basename, then use `worktree` as the defensive\nfallback.\n\nThe readable budget is `worktree_slug.max_length - 1 - worktree_id.length`.\nTruncate from the right to that budget and trim a separator exposed at the new\nend, then append exactly one configured separator and the complete ID. The\ndefault slug is at most 48 ASCII characters and is a DNS-compatible label. `_`\nintentionally favors unquoted SQL/programming identifiers over DNS-label\ncompatibility.\n\nBoth identity variables are Treeboot-owned. A bootstrap or teardown command that\ndeclares either one in its `env` table fails planning before file operations or\ncommands run. Changing the hash input, encoding, recognizer precedence,\nsanitization, or truncation behavior is a compatibility change.\n\nExisting configs that omit either settings object use defaults. Older Treeboot\nversions reject the new `worktree_slug` key under the normal unknown-field\nforward-version rule. Structured `env` and `config` consumers receive additive\nslug keys. Scripts that previously ran `treeboot env` successfully beside an\ninvalid discovered config now fail until that config is fixed or an explicit\nvalid config is selected, because environment inspection must match configured\ncommand behavior.\n\n### Aliases\n\n```text\nGIT_SOURCE_TREE_PATH\nGIT_WORKTREE_PATH\n\nCODEX_SOURCE_TREE_PATH\nCODEX_WORKTREE_PATH\n\nCONDUCTOR_ROOT_PATH\nCONDUCTOR_WORKSPACE_PATH\nCONDUCTOR_DEFAULT_BRANCH\n\nSUPERSET_ROOT_PATH\n```\n\n| Variable                   | Value                     | Reason                                  |\n| -------------------------- | ------------------------- | --------------------------------------- |\n| `CODEX_SOURCE_TREE_PATH`   | `TREEBOOT_ROOT_PATH`      | Matches Codex setup-script terminology. |\n| `CODEX_WORKTREE_PATH`      | `TREEBOOT_WORKTREE_PATH`  | Matches Codex setup-script terminology. |\n| `GIT_SOURCE_TREE_PATH`     | `TREEBOOT_ROOT_PATH`      | Generic compatibility alias.            |\n| `GIT_WORKTREE_PATH`        | `TREEBOOT_WORKTREE_PATH`  | Generic compatibility alias.            |\n| `CONDUCTOR_ROOT_PATH`      | `TREEBOOT_ROOT_PATH`      | Supports Conductor-style setup scripts. |\n| `CONDUCTOR_WORKSPACE_PATH` | `TREEBOOT_WORKTREE_PATH`  | Supports Conductor-style setup scripts. |\n| `CONDUCTOR_DEFAULT_BRANCH` | `TREEBOOT_DEFAULT_BRANCH` | Supports Conductor-style setup scripts. |\n| `SUPERSET_ROOT_PATH`       | `TREEBOOT_ROOT_PATH`      | Supports Superset-style setup scripts.  |\n\n### Tool-mode variables are intentionally absent\n\ntreeboot does not set `CONDUCTOR_IS_LOCAL`, `CONDUCTOR_PORT`, or\n`SUPERSET_PORT_BASE`. Those variables are owned by the tools that define them\nand must not be fabricated.\n\n## Execution: Plan and run flow\n\nDeclarative config is the only bootstrap mode.\n\n1. **Confirm Git context**: Fail early if not inside a Git working tree.\n2. **Discover paths**: Resolve worktree path, root path, and default branch.\n3. **Skip root checkout**: If Git\'s actual main-worktree identity and the\n   current worktree path match, print `This is not a work tree` and exit before\n   config; strict mode from CLI or environment exits non-zero.\n4. **Build environment**: Set treeboot canonical variables and compatibility\n   aliases, including a default `TREEBOOT_WORKTREE_ID`.\n5. **Load config**: Discover TOML config unless a specific path is provided. If\n   no config is found, print an info message and exit.\n6. **Resolve config options**: Refine `TREEBOOT_WORKTREE_ID` from normalized\n   config, then merge runtime options with environment overrides and CLI flags.\n7. **Validate config**: Normalize entries and detect duplicate operation\n   targets.\n8. **Prepare file groups**: Plan every concrete file-operation group and\n   cross-operation warning before the first possible mutation.\n9. **Preview or apply**: Plan and dry-run report the prepared groups without\n   mutation. Run applies those exact groups, then runs commands unless\n   `--skip-commands` was selected.\n\n## Execution: Teardown flow\n\nTeardown is an explicitly approved, command-only phase for a linked worktree.\n\n1. **Select target**: Resolve `--worktree`, or the process working directory,\n   through Git worktree discovery to a canonical worktree top level.\n2. **Discover paths**: Resolve the root checkout, default branch, and\n   treeboot-owned environment for that target.\n3. **Reject root checkout**: Fail before config loading or confirmation when\n   Git\'s actual main-worktree identity and target worktree path are equal.\n   Explicit and environment source-root overrides do not change this identity.\n4. **Load config**: Discover TOML config in the target worktree, or use only the\n   explicitly requested config path. Report `treeboot: config detected <path>`\n   after selecting the path and before reading or parsing it.\n5. **Normalize the whole document**: Parse all declarations and construct one\n   normalized config. Any TOML syntax, type, unknown-field, declaration-shape,\n   or declaration-normalization error anywhere in the document is fatal.\n6. **Plan teardown**: Refine `TREEBOOT_WORKTREE_ID` from normalized config and\n   validate only the teardown command collection. Bootstrap file and command\n   semantic planning failures do not prevent a valid teardown.\n7. **Approve**: Skip approval for no-op and dry-run outcomes. Otherwise require\n   `--yes` or affirmative terminal confirmation.\n8. **Execute the prepared plan**: Run the exact validated command set that was\n   approved. Do not reload or reparse config after confirmation.\n\nThe preparation result distinguishes missing discovered config, a valid config\nwith no teardown commands, and a ready teardown plan. Missing discovered config\nprints `treeboot: no config detected` and exits successfully. An explicitly\nrequested missing config is an error. An empty teardown plan prints\n`treeboot: no teardown commands configured` and exits successfully. Neither\nno-op prompts.\n\n### Teardown confirmation\n\nConfirmation occurs only after discovery, parsing, normalization, and teardown\nplanning succeed. The prompt is written to stderr and flushed before reading\nstdin:\n\n```text\nRun 2 teardown commands for /repo/worktrees/feature?\nThese commands may delete resources outside the worktree. [y/N]\n```\n\nOnly `y` and `yes`, case-insensitively after trimming whitespace, approve. Every\nother response, an empty line, and EOF decline. A decline runs nothing and exits\nwith code `1`.\n\nThe prompt uses `1 teardown command` for one command and\n`<count> teardown commands` for every other count.\n\nWhen stdin is not a terminal, teardown without `--yes` runs nothing, exits with\ncode `1`, and tells the caller to rerun with `--yes`. Prompt read or write\nfailures also run nothing and exit with code `1`. `--yes` suppresses the prompt\nbut does not bypass discovery, parsing, normalization, or validation.\n`--dry-run` never prompts and never requires `--yes`.\n\nThe unsuccessful decline contract makes this composition safe:\n\n```sh\ntreeboot teardown --worktree \"$path\" &&\n  git worktree remove \"$path\"\n```\n\nTreeboot itself never performs the removal.\n\n## Migration from legacy init scripts\n\ntreeboot does not discover or execute `.treeboot.sh`, `.treebootrc`, or\n`.config/treeboot/init`. These names have no special meaning and are treated as\nordinary repository files, regardless of executable permissions.\n`--no-init-script`, `init --script`, and `init -s` are not accepted options;\nusing them is a CLI usage error with exit code `2`.\n\nMove custom setup into a declarative command. For example:\n\n```toml\ncommands = [\n  { run = \"./scripts/bootstrap-worktree.sh\" },\n]\n```\n\nConfigured commands inherit the complete `TREEBOOT_*` environment and\ncompatibility aliases and run from the worktree root by default. Unlike the old\ninit-script invocation, treeboot does not automatically pass the root checkout\nas positional argument `$1`; scripts should read `TREEBOOT_ROOT_PATH`, or the\nconfig should pass it explicitly. Configured commands run after configured file\noperations. `--skip-commands` omits them, and `--dry-run` reports them without\nexecuting them.\n\n## Declarative mode: Config files\n\nTOML is the intended config format. Simple lists cover the common case;\ntop-level options and object entries cover stricter runtime, file, and command\nbehavior.\n\n### Discovery\n\n```text\n.treeboot.toml\ntreeboot.toml\n.config/treeboot/config.toml\n```\n\nThe first existing config file wins. If `--config` is provided, only that file\nis used. Relative config paths resolve from `TREEBOOT_WORKTREE_PATH`.\n\n### Init Defaults\n\n`treeboot init` creates `.treeboot.toml` by default. `treeboot init --config` is\nan explicit spelling of the same config output. The command never prompts\ninteractively and fails if the output path already exists, including when that\npath is a symlink. The starter config includes an empty `teardown_commands = []`\ndeclaration.\n\n```toml\nteardown_commands = [\n]\n```\n\n### Missing config\n\nIf no config file is detected, treeboot prints an info message such as\n`treeboot: no config detected`. Without `--strict` or `TREEBOOT_STRICT` it exits\nsuccessfully. With either one, it exits non-zero. Config-level `strict` cannot\naffect missing-config behavior because no config has been loaded.\n\nFor `treeboot teardown`, missing discovered config is always a successful no-op.\nTeardown does not resolve bootstrap strictness. An explicitly selected missing\nconfig remains an error.\n\n### Config inspection\n\n`treeboot config` uses the same config discovery rules as run mode, parses the\nselected TOML file, normalizes file, bootstrap command, and teardown command\ndeclarations, and exits successfully when parsing and normalization succeed. It\ndoes not apply file operations or execute configured commands. Invalid TOML,\nunknown fields, invalid enum values, missing required fields, and mutually\nexclusive command fields are config errors.\n\nAfter normalization, config inspection independently validates bootstrap and\nteardown semantics. It prints phase-labelled `treeboot: warning: ...` lines for\neach invalid phase without changing the successful parse-only exit status.\nNon-fatal bootstrap validation warnings, such as an include list that matches no\nsource paths, are printed the same way. Warnings go to stderr in every output\nformat, so JSON and YAML stdout output stays parseable and the structured config\nshape is unchanged.\n\n### JSON Schema\n\n`TB-CONFIG-SCHEMA`: The JSON Schema at\n`crates/treeboot-spec/assets/treeboot.schema.json` is the normative\nmachine-readable definition of the config document\'s structure. It must describe\nthe accepted document shapes, rejected fields, and constraints that the schema\nexpresses. Passing schema validation does not guarantee runtime acceptance:\nsemantic rules that depend on normalized values, path or pattern syntax,\nfilesystem state, repository context, or runtime policy remain defined by the\nprose contract and conformance requirements. Runtime defaults also remain\ndefined by the prose contract. `treeboot schema` stdout and `--output` must emit\nthe canonical document\'s exact UTF-8 bytes as described in\n[`treeboot schema`](#treeboot-schema).\n\n```toml\n#:schema https://github.com/jimeh/treeboot/releases/latest/download/config.schema.json\n\nstrict = false\ndefault_ignore = [\".DS_Store\", \"Thumbs.db\"]\nworktree_id = { length = 6 }\nworktree_slug = { max_length = 48, separator = \"-\" }\ndangerously_allow_sources_outside_root = false\ndangerously_allow_targets_outside_worktree = false\n\ncopy = [\n  \".env.local\",\n  \".env.development.local\",\n  \".env.test.local\",\n  \"mise.local.toml\",\n]\n\nsymlink = [\n  \".tool-versions\",\n  { source = \"shared/.agents\", target = \".agents\" },\n]\n\nsync = [\n  \"shared/config\",\n  { source = \"tooling/config\", target = \".config/tooling\" },\n]\n\ncommands = [\n  \"mise install\",\n  { name = \"Install dependencies\", run = \"mise run setup\" },\n]\n\nteardown_commands = [\n  { name = \"Stop services\", run = \"docker compose down\" },\n  { name = \"Drop database\", run = \"mise run db:drop\" },\n]\n\nfiles = [\n  { operation = \"copy\", source = \".npmrc\", target = \".npmrc\" },\n  { operation = \"symlink\", source = \"shared/bin\", target = \"bin\" },\n  { operation = \"sync\", source = \"shared/editor\", target = \".editor\" },\n]\n```\n\n### Top-level options\n\nTop-level options are project defaults for declarative bootstrap execution.\nEnvironment variables override matching config values. CLI flags override both\nwhere an equivalent flag exists. The normalized config still carries these\nvalues during teardown, but command-only teardown does not resolve or apply\nthem.\n\n| Option                                       | Environment                                           | Meaning                                                                                                                                                 |\n| -------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `strict`                                     | `TREEBOOT_STRICT`                                     | Defaults to `false`. Enables stricter declarative validation and conflict handling. CLI or environment strictness also applies before config discovery. |\n| `dangerously_allow_sources_outside_root`     | `TREEBOOT_DANGEROUSLY_ALLOW_SOURCES_OUTSIDE_ROOT`     | Defaults to `false`. Allows declarative file operation sources outside `TREEBOOT_ROOT_PATH`.                                                            |\n| `dangerously_allow_targets_outside_worktree` | `TREEBOOT_DANGEROUSLY_ALLOW_TARGETS_OUTSIDE_WORKTREE` | Defaults to `false`. Allows declarative file operation targets outside `TREEBOOT_WORKTREE_PATH`.                                                        |\n| `default_ignore`                             | none                                                  | Defaults to `[]`. Ordered path ignore patterns prepended to every `copy` and `sync` operation\'s effective ignore list.                                  |\n| `worktree_id`                                | none                                                  | Defaults to `{ length = 6 }`. Controls the compact path-digest prefix used as the worktree ID.                                                          |\n| `worktree_slug`                              | none                                                  | Defaults to `{ max_length = 48, separator = \"-\" }`. Controls readable worktree slug presentation.                                                       |\n\n### File objects\n\n`copy`, `symlink`, and `sync` accept strings and objects. Strings mean source\nand target are the same path. For `sync`, string entries also use\n`compare = \"metadata\"` and `delete = false`. The `files` list accepts objects\nwith an `operation` field for mixed copy, symlink, and sync entries. Missing\nsources are skipped by default; object entries can set `required = true` to make\na missing source fail. When an object has `source` but no `target`, its target\ndefaults to the same path as `source`.\n\n```toml\ncopy = [\n  \".env.local\",\n  { source = \".env.development.local\" },\n  \".env.test.local\",\n  \"mise.local.toml\",\n  { source = \".env.required.local\", required = true },\n]\n\nsymlink = [\n  \".tool-versions\",\n  { source = \"shared/.agents\", target = \".agents\" },\n]\n\nsync = [\n  \"shared/config\",\n  { source = \"tooling/config\", target = \".config/tooling\", delete = true },\n  { source = \"shared/tool.lock\", target = \".tool.lock\", compare = \"checksum\" },\n  { source = \"shared/cache\", target = \".cache/shared\", ignore_metadata = [\"ownership\"] },\n  { source = \"shared/vendor\", ignore = [\"**/tmp/**\", \"!**/tmp/keep/**\"] },\n]\n\nfiles = [\n  { operation = \"copy\", source = \".npmrc\", target = \".npmrc\" },\n  { operation = \"copy\", source = \".env.local\", ignore_metadata = [\"permissions\"] },\n  { operation = \"symlink\", source = \"shared/bin\", target = \"bin\" },\n  { operation = \"sync\", source = \"shared/editor\", target = \".editor\" },\n]\n\n[[file]]\noperation = \"copy\"\nsource = \"templates/editorconfig\"\ntarget = \".editorconfig\"\n```\n\nThe verbose table-array name is singular `[[file]]` so it can coexist with the\nplural `files = [...]` list in the same TOML file.\n\n| File field        | Applies to          | Meaning                                                                                                                                                                      |\n| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `operation`       | `files`, `[[file]]` | Required for object entries; one of copy, symlink, or sync.                                                                                                                  |\n| `source`          | all file operations | Required for object entries. Relative paths resolve from root path.                                                                                                          |\n| `required`        | all file operations | Defaults to `false`. When true, a missing source is a failure instead of a skipped operation.                                                                                |\n| `target`          | all file operations | Optional; defaults to source. Relative paths resolve from worktree path.                                                                                                     |\n| `compare`         | `sync`              | `metadata` by default; `checksum` for content checks.                                                                                                                        |\n| `delete`          | `sync` directories  | Defaults to `false`; when true, deletes target-only files and directories.                                                                                                   |\n| `symlinks`        | `copy`, `sync`      | Defaults to `preserve`; safe source symlinks are recreated as symlinks and unsafe symlinks are validation errors.                                                            |\n| `include`         | `copy`, `sync`      | Optional list of operation-local path include patterns that narrow directory operations to matching source paths. A non-empty list cannot combine with sync `delete = true`. |\n| `ignore`          | `copy`, `sync`      | Optional list of operation-local path ignore patterns appended after top-level `default_ignore`.                                                                             |\n| `ignore_metadata` | `copy`, `sync`      | Optional list of metadata fields to ignore. Supported values are `permissions`, `owner`, `group`, and `ownership`. `ownership` is shorthand for owner and group.             |\n\n### Command objects\n\n`commands` accepts string entries and compact object entries. Strings are\nshorthand for objects with a `run` field. For longer command definitions, use\nverbose `[[command]]` entries.\n\n`teardown_commands` and verbose `[[teardown_command]]` entries accept the same\nfields and defaults. Compact teardown entries run before verbose teardown\nentries, matching the bootstrap `commands` then `[[command]]` ordering.\nBootstrap and teardown normalize into separate ordered collections. An omitted\nteardown declaration normalizes to an empty collection, so existing config files\nremain valid. Older treeboot versions reject configs using the new keys because\nunknown config fields are deliberately denied.\n\n```toml\ncommands = [\n  \"mise install\",\n  { run = \"mise run setup\", env = { NODE_ENV = \"development\" } },\n]\n\nteardown_commands = [\n  { name = \"Stop services\", run = \"docker compose down\" },\n]\n\n[[command]]\nname = \"Install dependencies\"\nrun = \"npm install\"\ncwd = \".\"\nallow_failure = false\n[command.env]\nNODE_ENV = \"development\"\n\n[[command]]\nname = \"Install dependencies without a shell\"\nprogram = \"npm\"\nargs = [\"install\"]\n\n[[teardown_command]]\nname = \"Drop database\"\nprogram = \"mise\"\nargs = [\"run\", \"db:drop\"]\nallow_failure = false\n```\n\n| Command field      | Meaning                                                                                                                     |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |\n| `run`              | Shell command to execute. Mutually exclusive with `program`.                                                                |\n| `program` / `args` | Direct process execution without shell parsing.                                                                             |\n| `cwd`              | Command working directory, relative to the worktree by default. Normalized paths must stay inside `TREEBOOT_WORKTREE_PATH`. |\n| `env`              | Extra environment variables merged into the treeboot env set. Treeboot-owned variables and aliases cannot be overridden.    |\n| `allow_failure`    | Defaults to `false`. When true, non-zero exit is not fatal.                                                                 |\n\nExactly one of `run` or `program` is required. `args` is valid only with\n`program`. The parser rejects unknown fields in both bootstrap and teardown\ncommand declarations.\n\n## Before execution: Operation validation\n\ntreeboot validates self-conflicting file operations before it starts changing\nthe worktree.\n\n### Whole-document and phase boundary\n\nConfig loading parses and normalizes the whole TOML document before any\nbootstrap or teardown semantic plan is built. A syntax, type, unknown-field,\ndeclaration-shape, mutually exclusive field, or path-normalization error in any\ndeclaration makes config loading fail for every command.\n\nAfter a normalized config exists, bootstrap and teardown semantic planning are\nindependent:\n\n- `treeboot run` validates and builds only the bootstrap plan.\n- `treeboot teardown` validates and builds only the teardown plan.\n- a missing required bootstrap source, strict sync conflict, bootstrap command\n  cwd escape, or bootstrap owned-environment override does not block valid\n  teardown planning\n- an invalid teardown cwd or owned-environment override does not block bootstrap\n  planning\n- `treeboot check`, `treeboot doctor`, and `treeboot config` independently\n  evaluate both phase outcomes from one complete-config validation pass\n\nComplete-config validation orders bootstrap before teardown deterministically\nand preserves both errors when both phases fail. `check` returns one fatal\naggregate error containing every failed phase. `doctor` reports separate phase\ndiagnostics. `config` reports phase-labelled warnings while preserving its\nsuccessful parse-only status.\n\n### Normalize first\n\nConfig parsing normalizes `copy`, `symlink`, `sync`, `files`, and `[[file]]`\ninto one ordered list of file operations with resolved source and target paths.\nIt normalizes bootstrap and teardown declarations into separate ordered command\ncollections. Manual `copy`, `symlink`, and `sync` commands must produce the same\nnormalized operation shape.\n\nRelative file-operation source paths resolve from `TREEBOOT_ROOT_PATH`. Relative\nfile-operation target paths and command `cwd` paths resolve from\n`TREEBOOT_WORKTREE_PATH`. Absolute paths are preserved and then normalized\nagainst the filesystem where possible. Missing final path components are\nnormalized by canonicalizing the nearest existing ancestor and applying lexical\n`.` / `..` cleanup to the missing tail.\n\nOn Windows, normalized paths must be emitted in ordinary tool-friendly form when\nthe platform returns an extended-length path during canonicalization. Fully\nqualified drive paths such as `C:\\repo\\file`, UNC paths such as\n`\\\\server\\share\\repo\\file`, and relative paths without a drive or root prefix\nare supported. Drive-relative paths such as `C:repo\\file` and root-relative\npaths without a drive or share such as `\\repo\\file` are rejected for declarative\nfile-operation paths, manual file-operation paths, and command `cwd` values\nbecause they depend on process-local current-drive state.\n\n### Conflicting targets\n\nIf multiple file operations target the same normalized absolute path, or one\ntarget is inside another target, treeboot must report every conflicting entry\nwith its operation, source, target, and declaration location when available.\n\n### Target boundary\n\nEvery file operation target must resolve inside `TREEBOOT_WORKTREE_PATH`.\nTargets outside the current worktree are validation errors by default. For\nsymlink operations, the target is the path of the symlink created in the\nworktree; the symlink destination is the source and may point back into\n`TREEBOOT_ROOT_PATH`.\n\nExisting target parent components under `TREEBOOT_WORKTREE_PATH` must be real\ndirectories. If a target parent component is a symlink or another non-directory\nfile type, validation fails before any file operation or command runs. Missing\nparent components are allowed and created as directories when the operation is\napplied. The final target path itself is not treated as a parent component:\nforce and sync may still replace the final target path when the conflict matrix\nallows replacing an existing file or symlink.\n\nImmediately before a file operation mutates a target, treeboot must re-check the\nlive target ancestor chain. If a target ancestor became a symlink or\nnon-directory after validation, that operation fails before mutating the target.\n\n### Source boundary\n\nEvery file operation source must resolve inside `TREEBOOT_ROOT_PATH`. Sources\noutside the root path are validation errors by default.\n\n### Command boundary\n\nBootstrap and teardown command `cwd` values are normalized relative to\n`TREEBOOT_WORKTREE_PATH`. Paths may contain `..`, but the final resolved path\nmust stay inside the worktree. Planning resolves each cwd before any side effect\nand retains that canonical worktree boundary. Immediately before spawning each\ncommand, treeboot re-resolves the cwd and live worktree root. The live root must\nstill equal the planning-time boundary, and the freshly resolved cwd must remain\ninside it. For bootstrap this happens after file operations; teardown has no\nfile phase. A changed root or escaped cwd prevents the spawn and follows the\nnormal command-start `allow_failure` policy.\n\n| Rule                                                        | Behavior                                                        |\n| ----------------------------------------------------------- | --------------------------------------------------------------- |\n| Any duplicate operation target                              | Fail before any file operation or command runs.                 |\n| Target resolves outside the worktree                        | Fail before any file operation or command runs.                 |\n| Target parent is a symlink or non-directory at validation   | Fail before any file operation or command runs.                 |\n| Target ancestor becomes a symlink or non-directory at apply | Fail that operation before mutating the target.                 |\n| Source resolves outside the root path                       | Fail before any file operation or command runs.                 |\n| Required file operation source does not exist               | Fail before any file operation or command runs.                 |\n| Optional file operation source does not exist               | Skip that operation, make no target changes, and continue.      |\n| Command `cwd` resolves outside the worktree during planning | Fail before any file operation or command runs.                 |\n| Live worktree root differs from its planned boundary        | Do not spawn it; fail or warn and continue per `allow_failure`. |\n| Command `cwd` resolves outside the worktree before spawn    | Do not spawn it; fail or warn and continue per `allow_failure`. |\n| Command `env` overrides treeboot-owned variables            | Fail before any file operation or command runs.                 |\n| Copy or sync encounters an unsafe source symlink            | Fail before any file operation or command runs.                 |\n| Preserved copy or sync source symlink changes before apply  | Fail that operation before mutating the target.                 |\n| Strict mode with any sync operation                         | Fail before any file operation or command runs.                 |\n| `--dry-run`                                                 | Print the validation error, change no files, and exit non-zero. |\n\n### Conflicting targets are invalid config\n\nA config that copies a file and later symlinks to the same target is ambiguous\nat best and destructive under force mode. treeboot must reject duplicate\nconfigured targets in every mode. It must also reject ancestor/descendant target\npairs because a sync operation with `delete = true` can remove target-only\nchildren produced by another operation in the same plan. Manual commands must\nreject duplicate and overlapping targets derived from their source arguments and\n`--target` before any file changes are made.\n\n### Outside-worktree targets need an explicit escape hatch\n\nThe top-level option `dangerously_allow_targets_outside_worktree = true`\ndisables the target-boundary check. `dangerously_allow_sources_outside_root`\nseparately disables the source-boundary check. These checks affect declarative\nfile operations and manual file operation commands. Configured commands remain\nunrestricted because treeboot cannot safely validate arbitrary command behavior.\n\n### Strict mode is incompatible with sync\n\nSync expects existing targets and can be configured to delete target-only files,\nso strict mode rejects sync operations before execution. Strict mode can be\nenabled with `--strict`, top-level `strict = true`, or `TREEBOOT_STRICT=true`.\n\n## Files first: File operations\n\nSources resolve against the root path. Targets resolve against the worktree\npath. Parent target directories are created as needed.\n\n| Config                                               | Source                                         | Target                                                     |\n| ---------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |\n| `copy = [\".env.local\"]`                              | `TREEBOOT_ROOT_PATH/.env.local`                | `TREEBOOT_WORKTREE_PATH/.env.local`                        |\n| `symlink = [\".tool-versions\"]`                       | `TREEBOOT_ROOT_PATH/.tool-versions`            | `TREEBOOT_WORKTREE_PATH/.tool-versions`                    |\n| `sync = [\"shared/config\"]`                           | `TREEBOOT_ROOT_PATH/shared/config`             | `TREEBOOT_WORKTREE_PATH/shared/config`                     |\n| `{ source = \"a\", target = \"b\" }`                     | `TREEBOOT_ROOT_PATH/a`                         | `TREEBOOT_WORKTREE_PATH/b`                                 |\n| `{ operation = \"sync\", source = \"a\", target = \"b\" }` | `TREEBOOT_ROOT_PATH/a`                         | `TREEBOOT_WORKTREE_PATH/b`                                 |\n| `treeboot copy a --target b`                         | `TREEBOOT_ROOT_PATH/a`                         | `TREEBOOT_WORKTREE_PATH/b`                                 |\n| `treeboot copy a c --target b`                       | `TREEBOOT_ROOT_PATH/a`, `TREEBOOT_ROOT_PATH/c` | `TREEBOOT_WORKTREE_PATH/b/a`, `TREEBOOT_WORKTREE_PATH/b/c` |\n\n### Manual operation source completion\n\n`TB-COMPLETION-SOURCES`: Installed shell completions for the source arguments of\n`treeboot copy`, `treeboot symlink`, and `treeboot sync` must list files and\ndirectories from the resolved root path, not from the current worktree.\n\nCompletion candidates must be relative to the root path so completed values can\nbe reused as default targets.\n\nRoot-relative source completion applies to every shell supported by\n`treeboot completions`: Bash, Zsh, Fish, PowerShell, and Elvish.\n\nCompletion candidate generation uses root/worktree discovery only. It must not\nparse config files, run configured commands, or fail because config is missing\nor invalid.\n\n### Manual operation normalization\n\nManual file operation commands normalize to the same internal file operation\nshape as config entries. The subcommand supplies `operation`, each positional\nsource supplies `source`, `--required` supplies `required = true`, and\noperation-specific flags supply `symlinks`, `compare`, `delete`, `include`,\n`ignore`, or `ignore_metadata`.\n\nManual normalization happens under the same resolved runtime policy as\ndeclarative file operations: defaults, then config top-level policy when a\nconfig is present, then environment overrides, then CLI strictness. For manual\n`copy` and `sync`, effective ignore rules are the loaded config\'s\n`default_ignore` patterns followed by repeated `--ignore` flags. Effective\ninclude rules are the repeated `--include` flags alone; no config default is\nmerged.\n\nIf `--target` is omitted, each target defaults to its source value. If one\nsource is passed, `--target` is that operation\'s target. If more than one source\nis passed, `--target` is joined with each source value to produce each\noperation\'s target.\n\n### Missing sources\n\nMissing sources are optional by default for copy, symlink, and sync. When a\nsource does not exist and the entry does not set `required = true`, treeboot\nskips that operation and leaves the target unchanged. This lets one config list\nseveral local-only files, such as `.env.local` and `.env.development.local`,\nwhile only applying the files that exist in the root checkout.\n\n### Copy\n\nCopies files and directories. Directory copies recursively copy the source\ndirectory into the configured target path. This is a copy operation, not a sync\noperation: treeboot never deletes target files merely because they are absent\nfrom the source. Source symlinks are preserved by default when they are safe. By\ndefault, copy preserves the metadata described in\n[File metadata preservation](#file-metadata-preservation). Configure `ignore`,\nor use `--ignore`, to skip selected source paths during directory copies.\nConfigure `include`, or use `--include`, to narrow directory copies to selected\nsource paths. Configure `ignore_metadata`, or use `--ignore-metadata`, to opt\nout of selected metadata fields.\n\n`treeboot copy` exposes `--target`, `--required`, `--symlinks`, `--include`,\n`--ignore`, `--ignore-metadata`, `--dry-run`, `--verbose`, `--strict`, and\n`--force`.\n\n### Symlink\n\nCreates relative symlinks whenever treeboot can compute the path from the target\nparent to the source. If it cannot, it falls back to an absolute symlink.\n\n`treeboot symlink` exposes `--target`, `--required`, `--dry-run`, `--verbose`,\n`--strict`, and `--force`.\n\n### Sync\n\nReconciles target content to match source content. Files are compared by size\nand modified time by default, or by content when `compare = \"checksum\"` is set.\nChecksum comparison must detect content changes even when size and modified time\ndo not change. Sync also compares and repairs the metadata fields described in\n[File metadata preservation](#file-metadata-preservation), unless those fields\nare listed in `ignore_metadata`. Configure `ignore`, or use `--ignore`, to skip\nselected source and target paths during directory sync. Configure `include`, or\nuse `--include`, to narrow directory sync to selected source paths; a non-empty\n`include` list cannot be combined with `delete = true`. Source symlinks are\npreserved by default when they are safe.\n\n`treeboot sync` exposes `--target`, `--required`, `--compare`, `--delete`,\n`--no-delete`, `--symlinks`, `--include`, `--ignore`, `--ignore-metadata`,\n`--dry-run`, `--verbose`, `--strict`, and `--force`.\n\n### Path ignore rules\n\n`default_ignore` is an ordered top-level list of path patterns prepended to\nevery `copy` and `sync` operation\'s effective ignore list. `ignore` is an\nordered list of operation-local path patterns appended after `default_ignore`.\nPatterns use gitignore-style syntax, including `*`, `?`, `**`, character\nclasses, trailing slash directory matches, comments, escaped metacharacters, and\n`!` negation. Later matching patterns override earlier matching patterns. A path\nmatched by a non-negated pattern is ignored. A path matched by a later negated\npattern is re-included. Because operation-local `ignore` patterns come after\n`default_ignore`, an operation-local `!` pattern can re-include a path ignored\nby the top-level defaults.\n\nA pattern that cannot be parsed as a glob is a file operation validation error,\nreported before any side effects. Unlike Git, treeboot does not silently skip\nmalformed patterns.\n\nNormalized file operations expose the effective merged ignore list in their\n`ignore` field. Normalized config output also preserves `default_ignore` as a\ntop-level policy field.\n\ntreeboot never loads `.gitignore`, `.ignore`, `.rgignore`, `.git/info/exclude`,\nor global Git ignore files for file operations. Ignore rules come only from\ntop-level `default_ignore`, the operation\'s `ignore` field, or repeated manual\n`--ignore` flags.\n\nPatterns match source-relative paths for the operation. For example, with\n`source = \"shared\"` and `ignore = [\"**/vendor/**\"]`, the pattern is evaluated\nagainst paths below `TREEBOOT_ROOT_PATH/shared`, not against paths below the\nrepository root unless the operation source is the root itself. Matching uses\ndirectory knowledge, so directory-only patterns match only directories.\n\nIgnore rules affect directory sources only. When a `copy` or `sync` source is a\nsingle file or a source symlink, treeboot validates the patterns but does not\napply them to skip the top-level source. Use a directory source when selective\npath filtering is required.\n\nIgnored source paths are skipped before copy/sync action planning and before\nunsafe source-symlink validation. Ignored unsafe symlinks are therefore not\nvalidation errors. Re-included paths are planned and validated normally.\n\nWhen negated patterns are present, treeboot must still be able to discover\nre-included descendants under ignored directories. Implementations may traverse\nignored directories conservatively to find re-included descendants. Ignored\ndirectories that exist only as ancestors of re-included descendants may be\ncreated as target parent directories, but treeboot must not report or repair the\nignored directory itself unless that directory is re-included.\n\nFor directory sync with `delete = true`, ignore rules also apply to target-only\npaths by evaluating the same operation-relative path under the sync target.\nIgnored target-only files and directories are preserved. Re-included target-only\npaths remain eligible for deletion.\n\n### Path include rules\n\n`include` is an ordered list of operation-local path patterns that narrows a\n`copy` or `sync` operation to matching source paths. When an operation\'s include\nlist is empty or absent, no include filtering applies. When it is non-empty, a\npath below a directory source is in scope only when it matches at least one\ninclude pattern and is not ignored.\n\nInclude and ignore are independent gates evaluated against the same\nsource-relative paths. Include selects paths as a plain union: a path is\nincluded when any include pattern matches it, without last-match-wins ordering.\nIgnore rules then remove paths from that selection. A negated `!` ignore pattern\nonly unwinds earlier ignore patterns; it cannot re-include a path that does not\nmatch the include rules.\n\nInclude patterns use the same gitignore-style syntax as ignore patterns, except\nthat every include entry must be an effective positive pattern. Patterns\nbeginning with `!`, blank or whitespace-only patterns, and `#` comment lines are\nvalidation errors in include lists; exclusion belongs to `ignore`. The `\\!` and\n`\\#` escapes remain valid and match literal leading `!` or `#` characters in\nfile names. As with ignore patterns, an include pattern that cannot be parsed as\na glob is a file operation validation error. Because inert entries are rejected,\na non-empty include list always filters.\n\nA directory that matches an include pattern includes its whole subtree, subject\nto ignore rules. A directory that matches no include pattern is still traversed\nwhen a descendant could match. Directories receive target actions only when the\ndirectory itself is included or its subtree contains an in-scope path; a path\nthat matches include but is ignored is not in scope and does not materialize its\nancestors. Ancestor directories of in-scope paths that are not ignored are\ncreated as target parent directories and keep their normal metadata comparison\nand repair behavior, even when every in-scope descendant is unchanged. Ignored\nancestors traversed only to reach in-scope descendants follow\n[Path ignore rules](#path-ignore-rules) and are not reported or repaired unless\nre-included. Directories with no in-scope descendants that are not themselves\nincluded produce no target actions.\n\nLike ignore rules, include rules affect directory sources only. When a `copy` or\n`sync` source is a single file or a source symlink, treeboot validates the\npatterns but never filters the top-level source. Each operation\'s include list\napplies only within that operation\'s source tree; selecting which sources an\ninvocation covers is done by listing them.\n\nNon-included source paths are skipped before copy/sync action planning and\nbefore unsafe source-symlink validation. Non-included unsafe symlinks are\ntherefore not validation errors.\n\n`include` is rejected on `symlink` operations, like `ignore`. A `sync` operation\nwith a non-empty `include` list cannot combine it with `delete = true`: config\nvalidation rejects the combination, and `--include` conflicts with `--delete` /\n`-D` for manual `treeboot sync`. Absent `include` and `include = []` do not\nconflict with deletion. To mirror a subtree with deletion, narrow the\noperation\'s source instead of using include patterns.\n\nThere is no top-level `default_include`. Include rules come only from the\noperation\'s `include` field or repeated manual `--include` flags. For manual\n`copy` and `sync`, the effective include list is the repeated `--include` flags\nalone; the config `default_ignore` merging behavior has no include counterpart.\n\nAn include list that matches no source paths is not an error. `run` performs the\noperation with no in-scope paths and stays silent. `treeboot check` and\n`treeboot config` surface one non-fatal warning, in operation order, for each\n`copy` or `sync` operation whose effective include list is non-empty, whose\nsource exists and is a directory, and whose source tree contains no path\nmatching the include rules before ignore filtering. Operations whose source is\nmissing, a single file, or a source symlink do not produce zero-match include\nwarnings.\n\nImplementations may prune directories that cannot contain included paths instead\nof traversing them. Because of this latitude, an unreadable directory that is\noutside include scope may or may not produce an error. Pruning must not\notherwise change observable results.\n\nNormalized file operations expose the operation-local include list in their\n`include` field.\n\n### Symlinks inside copy and sync\n\nCopy and sync use `symlinks = \"preserve\"` by default: safe source symlinks are\nrecreated as symlinks instead of copying their referents. A source symlink whose\ntarget text is empty, whose target is dangling or otherwise cannot be resolved,\nor whose resolved target is outside `TREEBOOT_ROOT_PATH` is a validation error.\nIgnored paths and paths outside include scope may be skipped before this\nvalidation under [Path ignore rules](#path-ignore-rules) and\n[Path include rules](#path-include-rules). Preserved source symlinks are\nrechecked immediately before target mutation; if the source stops being a\nsymlink, changes the planned target, cannot be resolved, or resolves outside\n`TREEBOOT_ROOT_PATH`, treeboot fails the operation before creating or replacing\nthe worktree link. When source and target layouts differ, treeboot rewrites\ncopied symlinks to point at the analogous worktree destination when it can.\nRoot-local symlink targets are mapped by root-relative path into the worktree\nbefore treeboot computes the destination symlink. When no rewrite is needed,\ntreeboot preserves the symlink target text. For a safe, resolvable root-local\nsource symlink, treeboot prints a warning if its final worktree referent does\nnot exist and will not be created by the current run. This warning does not\napply to a dangling source symlink, which fails validation. Projects that need\ncustom symlink handling should use a configured command.\n\n### File metadata preservation\n\nCopy and sync preserve regular file contents, permissions, owner, group, and\nmodified time where the platform supports them. For directories, copy and sync\npreserve permissions, owner, and group where supported. Directory modified time\nis not preserved or compared because directory modified times change as children\nare created, removed, or updated.\n\n`ignore_metadata` lets a copy or sync operation opt out of selected metadata\ncomparison and preservation. Supported values are:\n\n| Value         | Meaning                                                        |\n| ------------- | -------------------------------------------------------------- |\n| `permissions` | Do not compare or apply file or directory permission metadata. |\n| `owner`       | Do not compare or apply owner metadata.                        |\n| `group`       | Do not compare or apply group metadata.                        |\n| `ownership`   | Shorthand for `owner` and `group`.                             |\n\nIgnored metadata fields do not trigger sync updates and are not applied after\ncopy or sync content updates. Non-ignored metadata fields are still compared and\napplied. Modified time is not configurable in this version; regular-file\nmodified time remains part of the default sync idempotency contract because\n`compare = \"metadata\"` compares size and modified time for content drift.\n\nPermission preservation failures are operation failures. Owner and group\npreservation is best-effort when the operating system denies ownership changes,\nbecause unprivileged users often cannot set arbitrary owners or groups. In that\ncase treeboot reports a warning and continues. Other unexpected ownership errors\nare operation failures.\n\nThis metadata contract is intentionally narrower than archive copying. treeboot\ndoes not preserve ACLs, extended attributes, resource forks, file flags,\nhard-link identity, sparse-file layout, or other platform-specific archive\nmetadata. Projects that need archive semantics should use project-local commands\nsuch as `rsync`, `cp -a`, `ditto`, or another purpose-built tool.\n\n### Sync preserves extras by default\n\nWhen the source is a directory, sync recurses through source and target. It\ncopies new files and updates changed files. Target files or directories that do\nnot exist in the source are preserved by default. Configure `delete = true` on a\nsync entry, or use `--delete` / `-D` for manual sync, to delete target-only\nfiles and directories. Deletion cannot be combined with a non-empty `include`\nlist; see [Path include rules](#path-include-rules).\n\n### Operation order\n\ntreeboot executes `copy` list entries first, `symlink` list entries second,\n`sync` list entries third, `files` entries fourth, then `[[file]]` entries in\ndocument order.\n\n## Safety: Conflict modes\n\nThe default mode is optimized for repeated worktree setup. Strict mode is for\nCI-like validation. Force mode is intentionally destructive and requires\nexplicit selection.\n\n### Trusted setup inputs\n\n`treeboot run` and `treeboot teardown` are intended for repositories whose setup\ncontract the user trusts. The trust boundary includes declarative config files\nand configured commands, which can run arbitrary code and may modify or delete\nresources outside the worktree. Use `treeboot config` to inspect TOML without\nexecution, `treeboot run --skip-commands` to apply only configured file\noperations, and `treeboot teardown --dry-run` to inspect teardown command\nexecution.\n\nDry-run reports the same file-operation decision that treeboot would take\nwithout mutating files. Default text output reports one compact line per\ntop-level file operation when that operation has a visible decision. A single\nfile create, update, symlink, delete, or skip uses the same direct line shape as\nthe concrete action. Directory copy and sync operations summarize expanded child\nactions with counts. `--verbose` reports each concrete child action instead of\nthe compact top-level summary.\n\nThe table below is the compatibility contract for file-operation conflicts.\n\n| Case                                  | Default                                                                                              | `--strict`                             | `--force`                                | `--dry-run`                                                                                       |\n| ------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| Copy file to missing destination      | Create file and parents.                                                                             | Create file and parents.               | Create file and parents.                 | Report planned create.                                                                            |\n| Copy file to existing file or symlink | Skip with info output.                                                                               | Fail before mutation.                  | Replace file or symlink.                 | Report skip, fail, or replace.                                                                    |\n| Copy file to existing directory       | Fail operation.                                                                                      | Fail before mutation.                  | Fail; do not remove directory.           | Report failure.                                                                                   |\n| Copy directory to missing destination | Recursively create directory tree. Summarize expanded child actions by default.                      | Recursively create directory tree.     | Recursively create directory tree.       | Report planned creates, summarized by default.                                                    |\n| Copy directory to existing directory  | Recursively copy missing files and skip existing files. Summarize expanded child actions by default. | Fail before mutation.                  | Merge and overwrite matching files only. | Report planned creates, skips, fail, or merge, summarized by default.                             |\n| Copy directory to file or symlink     | Fail operation.                                                                                      | Fail before mutation.                  | Fail; do not replace with directory.     | Report failure.                                                                                   |\n| Symlink to missing destination        | Create parent directories and symlink.                                                               | Create parent directories and symlink. | Create parent directories and symlink.   | Report planned symlink.                                                                           |\n| Symlink to existing file or symlink   | Skip with info output.                                                                               | Fail before mutation.                  | Replace file or symlink.                 | Report skip, fail, or replace.                                                                    |\n| Symlink to existing directory         | Fail operation.                                                                                      | Fail before mutation.                  | Fail; do not remove directory.           | Report failure.                                                                                   |\n| Sync file                             | Create or update when changed.                                                                       | Rejected by validation.                | Same as default.                         | Report create or update; stay silent when unchanged.                                              |\n| Sync directory                        | Reconcile tree; preserve target-only files by default. Summarize expanded child actions by default.  | Rejected by validation.                | Same as default.                         | Report creates, updates, and explicit deletes, summarized by default; stay silent when unchanged. |\n| Optional missing source               | Skip and leave target unchanged.                                                                     | Skip and leave target unchanged.       | Skip and leave target unchanged.         | Report planned skip.                                                                              |\n\n### Directory copy under force\n\nIn force mode, copying a source directory over an existing target directory\ntraverses the source and overwrites matching target files. It does not remove\ntarget files or directories that are not present in the source. Removing extras\nwould be sync behavior, not copy behavior.\n\n### Force does not erase directories casually\n\nForce mode may replace existing regular files and symlinks. It must not delete a\nnon-empty directory to satisfy a copy or symlink operation. Copying a file over\na directory, creating a symlink over a directory, or copying a directory over a\nfile are operation failures. Use sync when directory contents should be\nreconciled.\n\n### Sync is intentionally destructive\n\nSync is the operation that may delete target-only files when deletion is\nexplicitly enabled. Existing targets are expected for sync and are not treated\nas conflicts in default or force mode. Strict mode rejects configs with sync\noperations before runtime. Use `--dry-run` to preview sync creates, updates, and\nexplicit deletes.\n\n## File operation output and progress\n\nFile-operation output is compact by default and preserves detailed diagnostics\nwhen requested. Default text output is grouped by top-level file operation.\nTop-level operations are declarative config entries or normalized manual source\narguments.\n\nSingle concrete actions omit parenthesized counts because the source and target\nalready describe the work:\n\n```text\ntreeboot: copy .env -> .env\ntreeboot: sync .env -> .env\ntreeboot: would copy .env -> .env\ntreeboot: skip copy .env; target exists\ntreeboot: would skip copy .env; target exists\n```\n\nExpanded operations include counts after the source and target:\n\n```text\ntreeboot: copy shared -> shared (12 changed)\ntreeboot: copy node_modules -> node_modules (1842 changed, 27 skipped)\ntreeboot: sync shared -> shared (4 changed, 1 deleted)\ntreeboot: would sync shared -> shared (4 changes, 1 delete)\n```\n\nCount words are singular when the count is one and plural otherwise. `changed`\ncounts created directories, copied files, created symlinks, and replaced files\nor symlinks. `skipped` counts planned or actual skip decisions. `deleted` counts\nsync target-only paths removed or planned for removal.\n\nManual multi-source commands report each normalized source operation\nindependently:\n\n```text\ntreeboot copy a b --target local\n\ntreeboot: copy a -> local/a (12 changed)\ntreeboot: copy b -> local/b (4 changed, 2 skipped)\n```\n\n`--verbose` preserves the detailed action stream. In verbose mode, directory\ncopy and sync report concrete creates, updates, deletes, skips, and warnings\nrather than only the grouped summary. Verbose mode disables interactive progress\nrendering so detailed lines do not interleave with progress redraws.\n\nWhen stdout and stderr are interactive terminals, non-verbose copy and sync\noperations may render ephemeral progress on stderr: a spinner while planning a\ntop-level operation and a determinate progress bar while applying planned\nactions. Progress rendering must not change the final stdout summary lines. When\noutput is redirected, captured by CI, or otherwise non-interactive, non-verbose\nfile operations must suppress spinner/progress control output and print only\nnormal summary, warning, command, and error lines.\n\nFile-operation warnings remain visible in compact mode. If a warning is emitted\nwhile progress is active, progress must be cleared or suspended before printing\nthe warning so terminal output remains readable.\n\n## Command phases: Shared runtime\n\nBootstrap and teardown commands are arbitrary project commands. treeboot plans\nand runs both collections through the same command semantics while keeping the\nphase plans separate.\n\n### Execution rules\n\n- Bootstrap commands run after file operations complete successfully and run\n  even if every file operation was skipped.\n- Teardown commands run without applying any file operation or bootstrap\n  command.\n- Commands run sequentially in declaration order.\n- Re-resolve each command cwd and the live worktree root immediately before\n  spawn, require the root to equal the planning-time boundary, and reject a live\n  cwd escape.\n- A command with `allow_failure = true` warns when it cannot be spawned or exits\n  non-zero, then later commands continue.\n- Run from `TREEBOOT_WORKTREE_PATH` unless a command sets `cwd`.\n- Receive the full treeboot environment variable set described in\n  [Environment variables](#compatibility-environment-variables).\n- Per-command `env` values are merged into that environment for that command\n  only.\n- Bootstrap commands skip only when `treeboot run --skip-commands` is provided.\n- In run `--dry-run`, report planned file operations and bootstrap commands\n  without spawning any configured command process.\n- In teardown `--dry-run`, report teardown commands without prompting or\n  spawning any configured command process.\n\n### Shells\n\n```text\nUnix:    sh -c <command>\nWindows: cmd /C <command>\n\nDirect:  program + args\n```\n\nString commands and objects with `run` use the shell. Objects with `program`\nexecute directly without shell parsing.\n\n### Parallel setup work\n\ntreeboot does not parallelize configured commands. Projects that want parallel\nsetup work should delegate to one project-local task, such as `mise run setup`,\n`make setup`, or another task runner command.\n\n### Lifecycle output\n\nFor bootstrap, treeboot reports `treeboot: run <label>` before spawning each\ncommand. In dry-run it reports `treeboot: would run <label>` instead.\n\nFor teardown, treeboot reports `treeboot: teardown run <label>` before spawning\neach command. In dry-run it reports `treeboot: teardown would run <label>`\ninstead.\n\nA successful command in either phase does not produce a separate success event.\n\n### Command labels\n\nLabels include both `name` and invocation when `name` is set, formatted as\n`Name: invocation`. Without a name, shell commands use the shell string and\ndirect commands use `program arg...`.\n\n### Child output\n\nCommands inherit stdout and stderr directly.\n\n### Failures\n\nFatal command failures exit non-zero immediately and later commands do not run.\nIn either phase, a command that cannot be spawned reports\n`treeboot: failed to run command <label>: <io-error>` to stderr and exits\nnon-zero unless `allow_failure = true`.\n\nAllowed failures always emit a phase-labelled warning and do not make the\ncommand fail by themselves:\n\n```text\ntreeboot: warning: command optional lint: npm run lint failed with exit status: 1\ntreeboot: warning: teardown command Stop services: docker compose down failed with exit status 1\n```\n\nExecution-time cwd resolution or boundary failures use the same phase-specific\ncommand-start failure behavior and prevent that command from spawning. Under\n`allow_failure = false` the failure is fatal; under `allow_failure = true` it\nwarns and later commands continue.\n\n### Cross-platform contract\n\nWindows support is part of the compatibility contract. Shell execution, path\nhandling, symlink creation, and canonical path presentation must follow the\nplatform-specific rules in this specification.\n\n## Operator experience: Output and exit codes\n\nOutput should be concise enough for setup logs while still making skipped\ntargets and destructive choices obvious.\n\n```text\ntreeboot: copy .env.local -> .env.local\ntreeboot: skip copy .env.local; target exists\ntreeboot: symlink .tool-versions -> ../repo/.tool-versions\ntreeboot: sync shared/config -> .config\ntreeboot: sync metadata shared/editor/settings.json -> .editor/settings.json\ntreeboot: sync shared -> shared (4 changed, 1 deleted)\ntreeboot: run Install packages: npm install\ntreeboot: teardown run Stop services: docker compose down\ntreeboot: warning: could not preserve ownership shared/cache: operation not permitted\ntreeboot: warning: command optional lint: npm run lint failed with exit status: 1\n```\n\nUnchanged sync files and directories produce no output. Sync reports creates,\ncontent updates, metadata-only updates, and deletes directly for single concrete\nactions and as grouped counts for expanded directory operations. Command child\noutput is inherited directly.\n\nMetadata-only sync updates use the same source and target display style as\ncontent updates:\n\n```text\ntreeboot: sync metadata shared/config -> shared/config\ntreeboot: would sync metadata shared/config -> shared/config\ntreeboot: warning: could not preserve ownership shared/config: operation not permitted\n```\n\nInteractive progress is ephemeral terminal UI, not durable log output. It is\nrendered to stderr only for non-verbose copy and sync operations on interactive\nterminals. Final summaries, warnings, and command lifecycle lines remain normal\n`treeboot:` lines.\n\nCommand start lines use `treeboot: run <label>`. Dry-run uses\n`treeboot: would run <label>` and does not spawn commands. Fatal command\nfailures are reported as `treeboot: command <label> failed with <status>`. Fatal\nspawn failures are reported as\n`treeboot: failed to run command <label>: <io-error>`. Allowed spawn failures\nare reported as\n`treeboot: warning: command <label> failed to start: <io-error>`.\n\nTeardown command start lines use `treeboot: teardown run <label>`. Teardown\ndry-run uses `treeboot: teardown would run <label>`. Teardown allowed-failure\nmessages identify the teardown phase. Discovery output remains shared:\n\n```text\ntreeboot: config detected /repo/worktrees/feature/.treeboot.toml\ntreeboot: teardown run Stop services: docker compose down\ntreeboot: teardown run Drop database: mise run db:drop\n```\n\nNo-op output is durable:\n\n```text\ntreeboot: no config detected\ntreeboot: no teardown commands configured\n```\n\nCommand-wide manual argument or option validation errors must identify the CLI\noperation and the offending option, value, or reason. An error while normalizing\na manual operation\'s declared source-to-target mapping must identify the CLI\noperation and source. It must also identify the target once target derivation\nhas succeeded. After normalization, a file-operation planning or execution error\nmust identify the CLI operation, the path involved, and the reason. A recursive\nsource-tree inspection or resolution error must identify the CLI operation and a\nsource path associated with the failure. That path may be the operation\'s\ndeclared top-level source, its normalized location, or a nested source path. It\nshould identify the most specific failing source path available. None of these\nerror categories reports synthetic config paths or TOML locations for\ncommand-line arguments. Config parse or normalization errors found while loading\nmanual command policy still report the real config path and TOML location.\n\n| Exit | Meaning                                                                                                             |\n| ---- | ------------------------------------------------------------------------------------------------------------------- |\n| `0`  | Success, including missing discovered config or no teardown commands.                                               |\n| `1`  | Runtime failure, config error, operation or command failure, teardown decline, or missing non-interactive approval. |\n| `2`  | CLI usage error.                                                                                                    |\n\nThis Markdown document is the project specification for treeboot.\n";
Expand description

Canonical Treeboot specification Markdown.