Installation and Updates

Installation and additive updates

The same distribution supports project roots, OS directories, Google Drive, and LLM chats. A profile describes location and persistence; it does not fork the task format, configure a stack, or start an agent runtime. Use systemx setup --profile project to print its setup URL and capabilities.

The current installation version is 1.11.0-alpha.6. The 1.9.0-alpha.1 tag was withdrawn after a distribution mismatch and must not be installed. Review the current alpha release and its exact codeload tag ZIP digest before using the pinned remote examples below.

For a guided first adoption, use first-time setup. The first-run command previews by default, then installs/adopts and creates empty configuration only when explicitly applied.

Install from a reviewed folder

bash .SYSTEMX/INSTALL.sh --target "/path/to/project" --profile project --dry-run
bash .SYSTEMX/INSTALL.sh --target "/path/to/project" --profile project

On Windows use .SYSTEMX\INSTALL.ps1 with the same flags, or invoke py -3 -I -B .SYSTEMX\manager.py install .... Quote paths containing spaces. The target is the containing working directory, not .SYSTEMX, any case variant, a directory inside it, or a drive root. Use --lowercase-alias to request a local .systemx -> .SYSTEMX link. The installer recognizes case-insensitive paths without creating a link, and refuses separate case-conflicting entries. See exact casing and alias setup for the menu, library, and recovery. The installer requires Python but does not install runtimes or OS services. For installation as a command or importable package, see the library guide. On a fresh installation, an existing .py, .sh, or .ps1 default with different content is a conflict. Preview and inspect it; setup will not silently preserve an incompatible executable beside the new managed defaults.

Ownership and layout

project/
└── .SYSTEMX/
    ├── INSTALLATION.json       Manager-owned selection, policy, archive digests
    ├── GLOBAL/, PLAN/, WORK/   Project-owned records
    ├── MEMORY/, AGENTS/        Project-owned memory and roles
    ├── project.json            Optional project-owned command configuration
    ├── STANDARD.md, scripts/…  Initial files; existing copies are preserved
    └── .systemx/              # internal cache, not the optional sibling alias
        ├── releases/<version>/ Immutable default files for each retained release
        ├── operations/        Local installation operation receipts
        ├── history/           Earlier manager state, retained locally
        ├── last-check.json    Optional startup-check metadata
        └── update.lock        Temporary local writer lock

The installed defaults and INSTALLATION.json can be committed together for reproducible project clones. The supplied ignores exclude transient checks, state history, operation logs, and the lock. Do not deploy this folder as public application data.

Updates never replace or delete existing files or folders in the project. They append a new versioned defaults directory, create only missing root files, and update the manager-owned selection metadata. They retain files removed or renamed upstream, older releases, custom defaults, tasks, configuration, and memory. Removal is a separate explicit, reversible operation; see uninstall and cleanup. It archives the complete folder and logs its inventory instead of deleting records. The separately requested bootstrap-refresh procedure below may replace eight recognized stock root bootstrap/launcher files, with backups for replacements. It may add a genuinely absent stock file only when no intact retained historical release ever contained that file. It never rewrites project records or custom launchers.

The root VERSION records the initially copied files and is preserved too. systemx status --target ... reports the authoritative selected defaults version. Use the selected release's guidance, templates, and runner; retained root copies can be older or customized. A changed-release update requires all eight stock bootstrap/launcher files to match the destination release. The managed runner always reads/writes project records from the outer .SYSTEMX, never the blank seeds in a release snapshot.

systemx run --target ... requires a selected managed installation. A trusted external manager refuses an unmanaged target rather than executing that target's .SYSTEMX/scripts/systemx.py. To inspect an untrusted checkout, use the trusted manager's read-only audit or an install preview. Do not run its local wrappers or scripts until you trust the checkout and project configuration. Target-owned installation metadata is not independent proof of origin; assess the source before choosing to execute its retained defaults.

Select, lock, or update a version

Before moving from 1.5.0 or earlier to alpha, upgrade the external CLI/library first. Older managers cannot parse alpha IDs, and additive updates deliberately preserve their original files. See alpha migration and release policy. systemx --version reports the installed tool; systemx status --target ... reports that project's selected defaults and derived releaseChannel.

New installations are pinned to the installed release and use manual updates. For an existing managed installation, use a reviewed manager from the intended release outside the project to preview its root bootstrap migration:

systemx bootstrap-refresh --target "/path/to/project" \
  --source "/path/to/reviewed-dotSYSTEMX/.SYSTEMX"
systemx bootstrap-refresh --target "/path/to/project" \
  --source "/path/to/reviewed-dotSYSTEMX/.SYSTEMX" --apply

Use the external new tool for both commands, not an older preserved root launcher. When using a reviewed checkout directly, invoke its manager as python3 -I -B /path/to/reviewed-dotSYSTEMX/.SYSTEMX/manager.py (Windows: py -3 -I -B). The preview lists exact files to replace and any conflicts. The direct manager enforces -I before imports; named local helpers are loaded from their source bytes so an unlisted module or poisoned .pyc cannot replace them. The installed systemx console entry point resolves its package through the initial Python import paths, then restarts in isolated mode before importing the manager. For untrusted PYTHONPATH or working directories, start a reviewed virtual environment's Python with -I -B -m systemx; the importable library inherits its host application's Python trust environment. Apply only when the preview is free of conflicts. It recognizes these eight stock files from intact retained releases or the reviewed new distribution: manager.py, lifecycle.py, versions.py, systemx_paths.py, SYSTEMX.sh, SYSTEMX.ps1, INSTALL.sh, and INSTALL.ps1. The refreshed wrappers invoke Python with -I -B. Review the preview's add, replace, and conflicts fields. A stock file absent from every intact retained historical release can be added; for example, a genuine v1.5.0 installation can gain the later versions.py. If a file existed in a retained release but is missing now, or its contents are customized or unrecognized, refresh stops for manual review. Apply saves byte-for-byte backups of replaced files under .SYSTEMX/.systemx/history/ and records a local operation receipt. An add-only refresh has no old file to back up. Ordinary project records and other root files stay untouched. If the root bootstrap already matches the new release, the preview has no additions or replacements and no apply is needed. A remote version with an independent --archive-sha256 pin can also supply the reviewed release.

After reviewing the published release history, select the new defaults:

systemx status --target "/path/to/project"
systemx policy --target "/path/to/project" --pin none
systemx update --target "/path/to/project" --version 1.11.0-alpha.6 \
  --archive-sha256 a50f0566c07f5a0c51b14a38bf6e3eb38b3c61d2953352304b186fa4fca0b464 --dry-run
systemx update --target "/path/to/project" --version 1.11.0-alpha.6 \
  --archive-sha256 a50f0566c07f5a0c51b14a38bf6e3eb38b3c61d2953352304b186fa4fca0b464
systemx policy --target "/path/to/project" --pin current

update refuses to proceed when the root bootstrap differs from the selected release. This prevents new installation-state metadata from being saved behind an incompatible old root manager. Refresh the stock bootstrap first, then retry the update. If a file is customized, preserve it and resolve that customization deliberately; do not overwrite it to make the update pass.

For a reviewed local source, use systemx update --target "/path/to/project" --source "/path/to/reviewed-dotSYSTEMX/.SYSTEMX" after the bootstrap preview and explicit policy unlock shown above; preview it with --dry-run first, then pin the selected version again. Verify that this source's .SYSTEMX/VERSION is 1.11.0-alpha.6. Omitting --version on an unpinned update discovers the selected version's channel: stable versions select only final releases; alpha versions select newer published alpha or final releases. Discovery cannot silently downgrade a project. --source selects a local reviewed distribution instead; its manifest determines the version. This manager installs and newly selects only releases 1.8.7-alpha.1 or newer, where native isolated runner support begins; bootstrap-refresh also requires a target release at or above that floor. status can inspect an older managed installation. If an older release is already selected, this manager can run its verified retained snapshot through an isolated compatibility shim while a reviewed external migration is prepared. The old runner keeps its historical behavior and record compatibility; the shim does not turn it into current code. An explicit older selection within the supported range may be possible after unpinning when the stock bootstrap/launcher files are unchanged and records are compatible. Bootstrap rollback is refused. Recovering a release older than 1.8.7-alpha.1 requires a separately reviewed backup or legacy path outside this manager's selection flow. Application/schema migrations are never reversed automatically; check compatibility before historical recovery.

An existing version directory cannot be replaced with different content under the same version ID. Before running its Python code, the manager checks both manifest fingerprints and the complete physical inventory of the selected release cache. Unlisted files, Python modules, packages, links, or directories stop selection and remain in place for inspection. An interrupted partial cache can still be completed by retrying. This closes the path where an unlisted local module could be imported by a verified runner; it does not authenticate the remote publisher. From 1.9.0-alpha.3, distribution manifest schema 2 requires exact-byte hashes for binary media and unknown file types. Only reviewed UTF-8 text formats have CRLF/LF checkout tolerance. Older schema-1 snapshots keep their published hash behavior for compatibility; alpha.3 cannot be represented as schema 1, and a 1.9 distribution missing Agent Y core files is refused.

Independent archive pin

For an exact remote release, install, update, and first-run accept a SHA-256 pin for the exact GitHub codeload tag ZIP fetched by the manager:

systemx update --target "/path/to/project" --version 1.11.0-alpha.6 \
  --archive-sha256 "a50f0566c07f5a0c51b14a38bf6e3eb38b3c61d2953352304b186fa4fca0b464" --dry-run
systemx update --target "/path/to/project" --version 1.11.0-alpha.6 \
  --archive-sha256 "a50f0566c07f5a0c51b14a38bf6e3eb38b3c61d2953352304b186fa4fca0b464"

For any later version, replace the version and digest together, and unlock the current selection before changing versions. Obtain the digest from a separately trusted record. A checksum fetched from the same movable tag does not establish independent trust, and a SHA256SUMS entry for a separately built release archive or wheel is not the digest of the codeload ZIP. The manager checks the raw ZIP digest before parsing it. INSTALLATION.json records explicit-pin when the supplied digest matches and observed-only when no pin was supplied; local sources have no remote archive digest. systemx status shows the selected receipt. This receipt is consistency evidence, not a publisher signature or a security audit.

--archive-sha256 requires an explicit remote --version and cannot accompany --source or unversioned discovery. Remote updates use the configured GitHub repository's exact release tag; an explicit repository override is a trusted source choice for that installation.

Optional startup release notices

Release 1.8.8-alpha.1 changes on-start to a check-only policy. An older preserved root manager can still perform the earlier startup-selection behavior. Keep its policy at manual until you have reviewed and refreshed the stock root manager and launcher to this release.

# With the reviewed check-only manager and refreshed stock root bootstrap:
systemx policy --target "/path/to/project" --auto on-start
systemx run --target "/path/to/project" -- status

# Stop startup checks; keep the selected release and any version pin:
systemx policy --target "/path/to/project" --auto manual

In the check-only manager, the launcher reads release metadata at startup at most once per 24 hours after a successful check and reports a newer release. It never downloads the release archive or changes selected defaults, the pin, project-owned files, or the release cache during that check. A pinned project can enable notices without unpinning. An alpha project checks for alpha or final releases; a stable project checks only final releases. A new major version is reported for separate review. No process runs when SYSTEMX is closed. There are no OS scheduler, login, or Git hooks.

After a notice, review the release and obtain its exact codeload tag ZIP SHA-256 through a channel you trust. Unpin only if changing the selected version. Then preview and apply an explicit update using both the release ID and digest, verify the selected defaults, and pin the current version again if desired. For a changed stock root bootstrap or launcher, use the external reviewed bootstrap-refresh procedure first. Replace both placeholders below with the published release ID and independently verified digest:

systemx policy --target "/path/to/project" --pin none --auto manual
systemx bootstrap-refresh --target "/path/to/project" \
  --version RELEASE_VERSION --archive-sha256 CODELOAD_ZIP_SHA256
systemx bootstrap-refresh --target "/path/to/project" \
  --version RELEASE_VERSION --archive-sha256 CODELOAD_ZIP_SHA256 --apply
systemx update --target "/path/to/project" --version RELEASE_VERSION \
  --archive-sha256 CODELOAD_ZIP_SHA256 --dry-run
systemx update --target "/path/to/project" --version RELEASE_VERSION \
  --archive-sha256 CODELOAD_ZIP_SHA256
systemx status --target "/path/to/project"
systemx policy --target "/path/to/project" --pin current

If the bootstrap preview has no additions or replacements, skip its --apply step. Inspect any conflicts before proceeding; do not overwrite custom root files. The checksum must cover the codeload tag ZIP downloaded by these commands, not the separately built portable folder ZIP or wheel. The manager rejects a mismatched digest before ZIP parsing. Setting --pin current resets the startup policy to manual; opt back into --auto on-start separately if wanted.

An unavailable check leaves the verified installed release usable. A failed check can be retried at the next startup. Use systemx run --offline --target ... -- ... to skip network checks for that invocation. Inspection via manager status and export-chat is always offline. The notice records only local manager-owned metadata under .SYSTEMX/.systemx/last-check.json.

The 1.8.9 manager introduced a five-second cap on the caller's wait for advisory release-metadata discovery. If it times out, the selected local runner continues and the check reports unavailable; the underlying daemon request may still finish later. The check cannot fetch or select a release. The exact historical 1.8.9 source and artifact evidence is in Versions and changelog.

Existing installations and recovery

Run install --dry-run against the real project to inspect what will be added. The manager never overwrites an existing INSTALLATION.json; recognized installs use update. Unsupported legacy task layouts need the upgrade guide. Installation does not assert that old records are compatible with new tooling: run ordinary validate and inspect context before continuing work.

If an update is interrupted, earlier defaults and project files remain. A partial new snapshot is never selected before its files verify. Retry the same release; if a partial file differs or an unlisted entry is present, move that incomplete snapshot aside for inspection before retrying. Do not delete project records to recover an update. A lock file is a local process guard; verify that its recorded owner has stopped before manually removing a stale lock. Drive synchronization is not a distributed lock.

The manager writes installation metadata atomically and retains previous states. It cannot guarantee atomicity against a separate, uncooperative program changing the same filesystem at the same instant. Coordinate writers for shared folders.

Multiple child projects

SYSTEMX PROJECTS adds Projects/NAME/.SYSTEMXP beneath this one installation. Child records, source references, code, and the populated project registry are user-owned. Updates preserve them, including folders absent from new defaults. New children use the selected release's blank creation seeds. All children share the outer pin and update policy; do not install or update .SYSTEMX separately beneath Projects. Existing custom child registries need an explicit reviewed migration before the generic routing commands can use them.