Installing

Installation answers one narrow question: how does the Coldstart payload get from a source snapshot into a dedicated root on one machine? It does not answer which project should use that root, how an existing project should be adopted, or how one person wants the workflow explained.

[Visual 8.1 — The machine-installation lane enlarged. At the left, a sealed file labelled "payload allowlist" contains three row types: "file", "directory" and "skip". It enters a validation gate with four refusal tabs: "unsafe path", "missing entry", "user-owned area" and "source/target overlap". Two equal branches leave the gate: "Bash entry point" and "PowerShell entry point". They rejoin at a dedicated "machine root" containing a root marker and an install receipt. Beneath the root, one arrow loops back through "re-run: copy current allowlist + prune only previously owned stale files". A hard stop to the right reads "no project registrations here". A caption under the two branches reads "declared host surfaces are broader than the environment exercised by any one test run".]

The payload is closed before copying starts

Both installers read the same payload manifest. It names individual files, directories to walk and glob patterns to skip. The scripts do not maintain separate hidden lists, and they do not infer a payload from everything present in the source tree.

Before copying, each entry is checked. Paths must be relative, cannot traverse upward, cannot name the user-owned knowledge areas that Coldstart promises not to install over, and must exist in the source. A directory entry is expanded only after the skip rules are known, so build artifacts, platform junk and repository-only hook files do not enter the installed tree by accident.

This is the primary safety wall. A list of warnings would still leave the installer able to inspect and copy the wrong material. A closed allowlist means material outside the manifest is never part of the copy operation in the first place.

The manifest is an install allowlist, not a complete public-release package definition. At the pinned revision the product is unreleased and the distribution shape is not settled. A successful payload copy therefore must not be described as receiving a released buyer archive.

The target root has one precedence and several refusals

Root selection follows the same order in both entry points: an explicit root argument, then the Coldstart root environment setting, then the development default. The chosen path is resolved before the scripts compare it with protected locations.

The installers refuse a machine home, the host tool's configuration home, the live predecessor root, the source tree itself, and any source/target nesting in either direction. They also refuse an existing non-directory. A non-empty directory with no Coldstart marker is treated as somebody else's directory unless the operator deliberately invokes the narrow force path.

Those checks do not make force a general overwrite switch. The payload is still closed, and the install receipt still defines what a later prune or uninstall may own. Force only changes the decision about entering a foreign non-empty target; it does not widen the payload or authorize project adoption.

Bash and PowerShell are two entry points to one contract

The Bash script declares macOS, Linux and Git Bash as its host surface. The PowerShell script implements the same flags and root rules for PowerShell hosts. It also writes its own manifest text with explicit encoding and line endings so the two branches can be compared without a byte-order mark, culture-aware sort order or newline convention creating two products.

The parity test measures four useful surfaces:

1. Both installers place the same set of paths on disk.
2. Their install receipts are byte-equal.
3. The installed registry assigns the same classes to those paths.
4. An explicit root and an environment-selected root resolve with the same precedence.

The test includes defect injections. It disables each installer's skip handling in turn and requires the comparison to go red. A parity test that stayed green when one branch copied a skipped file would not represent the contract it claims.

The test deliberately does not compare every copied payload byte. A checkout may carry platform line endings before either installer sees it. The parity claim belongs to path ownership, manifest bytes, classification and root resolution, not to pretending different checkouts started byte-identical.

What this documentation run exercised

For this page, the four pinned setup test modules were run from an isolated archive on macOS with Python 3.12, Bash and PowerShell 7 available. The suite passed 116 tests with one named skip.

The installer-parity module exercised both the Bash and PowerShell installers. Its real-payload comparison, root-precedence cases and three defect-injection cases passed. The separate init-script parity case skipped because that older test searches for a legacy PowerShell command name and did not recognize the available PowerShell 7 executable name.

That distinction matters. The installer evidence is green on this environment. The init launcher skip is a limit, not a pass. Neither result proves all advertised operating-system journeys, filesystem behaviors, shell versions or later runtime actions. The product's wider preserved platform evidence also contains failures and explicit skips, so “cross-platform support proven” would exceed the evidence.

Re-running owns only the installer's receipt

After validation, the installer creates the root, copies the sorted payload and writes an install receipt naming every copied relative path. A later run compares the old receipt with the new allowlist. If a previously installed payload file is no longer shipped, that file can be pruned. Directories are removed only when that pruning leaves them empty.

This is idempotence with an ownership boundary. Re-running converges on the payload of the current source revision. It does not authorize deleting arbitrary files that happen to be under the same root, and it does not scan a project for material that looks obsolete.

An optional settings argument has the same posture. The pristine settings state is backed up once and kept across re-installs. Installation does not merge project hook registrations into it. The completion message points toward a later project opt-in; the install itself stops at the machine root.

Exit meanings

Both entry points reserve three process outcomes:

• Exit 0 means the requested install or dry run completed.
• Exit 1 means the operation was refused or failed.
• Exit 2 means the invocation or installer machinery was invalid.

A dry run resolves the root, validates the manifest and reports the planned payload without writing. It is useful evidence about what the installer intends, but it is not evidence that the target filesystem accepted the real copy.

What installation does not do

Installation does not activate Coldstart globally. It does not register the hook roster in every repository, seed project state, write a project plan or choose how existing documents should move. It also does not create a personal profile.

Those omissions are the boundary, not missing convenience. The machine root is harness-owned machinery. The selected project's seed has a different owner and a different undo receipt. Personal calibration belongs outside both.

Next

With the machine boundary clear, continue to activating one project.

How current this page is

Checked on 10 August 2026 against the pinned Bash and PowerShell installers, their shared defaults and payload manifest, and the install-discovery and parity tests. The local evidence statement above records the observed environment and its one explicit skip instead of generalizing beyond it. To ask whether a claim here still holds, or to report one that does not, write to [email protected].