First Time Setup

First-Time Setup

Alpha: use at your own risk; may change daily. See the release policy.

This guide takes a new user from choosing a workspace to a project with a pinned .SYSTEMX installation, empty command configuration, and a clear next step. It does not install a product stack, fill in invented requirements, or start agents. It is a wiki walkthrough; for an exact installation, follow the selected release's versioned .SYSTEMX/START-HERE.md and .SYSTEMX/docs/FIRST-RUN.md if a wiki or README summary differs. The 1.9.0-alpha.1 tag was withdrawn after a distribution manifest mismatch; do not install or select that version. The commands below target 1.11.0-alpha.6.

To have an assistant perform this setup, copy the New Chat Setup Prompt and fill in the project name, location, and objective.

1. Choose the project and profile

Choose the containing project directory, such as /home/me/projects/example or C:\Projects\Example. Use the exact .SYSTEMX name beneath it. Inspect existing hidden files before adoption; do not copy over existing records.

Profile	Choose it for
project	A repository or VS Code project root
directory	Another Windows, macOS, or Linux working directory
drive	A locally available regular-file Drive project folder
chat	A local project used to prepare a reviewable LLM chat packet

Once you define the isolated shorthand in step 3, run systemx setup --profile project for the corresponding setup URL. Cloud URLs are not local filesystem targets. Browser-only Drive and chats follow the profile guides and explicit upload/readback workflows.

2. Choose a tool entry point

Documentation alone needs no runtime. For commands, install Python 3.9+ through your platform's normal trusted method if it is not already available. The template does not install Python, Git, an editor, cloud clients, or OS services.

For a reusable CLI/library, use a dedicated environment outside the project. These paths are examples; choose paths you own and keep package logs outside the environment so they survive its later removal.

macOS/Linux:

python3 -m venv "$HOME/.venvs/dotsystemx"
"$HOME/.venvs/dotsystemx/bin/python" -m pip --log "$HOME/dotsystemx-install.log" install \
  "git+https://github.com/WayneTechLab/dotSYSTEMX.git@v1.11.0-alpha.6"
"$HOME/.venvs/dotsystemx/bin/python" -I -B -m systemx --help

Windows PowerShell:

py -3 -m venv "$HOME\.venvs\dotsystemx"
& "$HOME\.venvs\dotsystemx\Scripts\python.exe" -m pip --log "$HOME\dotsystemx-install.log" install "git+https://github.com/WayneTechLab/dotSYSTEMX.git@v1.11.0-alpha.6"
& "$HOME\.venvs\dotsystemx\Scripts\python.exe" -I -B -m systemx --help

Calling the environment's Python directly avoids changing activation policy or global PATH. Git-based installation requires Git. The release wheel can be installed through the same pip command by supplying its downloaded path instead of the Git URL; no PyPI publication is implied.

Alternatively, use python3 -I -B /path/to/reviewed-template/.SYSTEMX/manager.py (Windows: py -3 -I -B ...) for the commands below. Keep that reviewed checkout outside the target project, especially for later uninstall/restore.

3. Preview and apply first run

In the following examples, systemx is shorthand for the isolated command. Define it in each shell session using the virtual environment from step 2:

systemx() { "$HOME/.venvs/dotsystemx/bin/python" -I -B -m systemx "$@"; }

function systemx { & "$HOME\.venvs\dotsystemx\Scripts\python.exe" -I -B -m systemx @args }

If you chose the separate reviewed manager script, replace the function body with its python3 -I -B .../manager.py invocation. The installed systemx console entry point remains available on supported platforms, including Windows, when its initial Python import paths are trusted. It resolves the package before restarting in isolated mode. If PYTHONPATH or the working directory is untrusted, starting a reviewed virtual environment's Python with -I -B -m systemx isolates that initial import too. Isolation hides user site-packages, so pip install --user is not a substitute for the virtual environment here.

systemx first-run --target "/path/to/project" --profile project
systemx first-run --target "/path/to/project" --profile project --apply

Without --apply, this is a read-only preview for the target; a requested remote version may be downloaded for verification. --dry-run explicitly selects the same preview behavior. Applying first run:

1. Installs or adopts .SYSTEMX, preserving every existing root file.
2. Pins a new installation to its selected release and uses manual updates.
3. Creates an empty project.json only when absent.
4. Records local installation/first-run operations and prints the remaining steps.

Fresh setup refuses an existing .py, .sh, or .ps1 default if its content differs from the selected distribution. Inspect that conflict before retrying; the installer does not silently keep an incompatible executable in a new managed installation. For an existing managed project, use the bootstrap migration steps before selecting new defaults when prompted.

Add --lowercase-alias to opt into the local .systemx -> .SYSTEMX link if the filesystem needs one. Case-insensitive filesystems need no link. Conflicting case variants stop setup. On an already managed project, first run preserves the selected version and policy; use the explicit update command to change them.

The ordinary install command remains available when you want only the managed folder without configuration initialization. Both workflows use the same defaults.

4. Record this project's actual facts

The preceding --target commands do not change the shell's working directory. Before editing relative paths or using the local launchers below, enter the same containing project directory that you installed:

cd "/path/to/project"

Set-Location -LiteralPath 'C:\path\to\project'

Replace these example paths with your actual target. From another directory, keep using systemx run --target ACTUAL_PROJECT --offline -- COMMAND instead of a relative .SYSTEMX launcher. Confirm the target before applying task changes.

• Fill .SYSTEMX/GLOBAL/CONTEXT.md with purpose, constraints, accepted sources, terminology, and privacy boundaries for this project.
• Fill the blank Access Matrix in .SYSTEMX/GLOBAL/ACCESS-MATRIX.md with verified actor, target, operation, approval, and permission-source facts. Unknown access remains unknown; writing this document does not grant permissions.
• Define outcomes, milestones, and acceptance in .SYSTEMX/PLAN/MASTER-PLAN.md.
• Fill the blank System MAP in .SYSTEMX/PLAN/MAP.md with the actual source hierarchy, record scope, toolchain, environments, and evidence route. Keep task statuses in WORK/TASKS.json and current selection in WORK/FOCUS.json, not in the map.
• Add only known commands to .SYSTEMX/project.json; keep unsupported operations empty. Check the selected stack.
• Merge the optional root agent entry-point template into existing host instructions if needed. No host instruction is installed automatically. Record any manual integration so you can reverse it later.
• Start with agent.0; create worker records only for authorized assignments.

5. Verify and start work

systemx run --target "/path/to/project" --offline -- validate
systemx run --target "/path/to/project" --offline -- doctor
systemx run --target "/path/to/project" --offline -- context --agent agent.0
systemx audit --target "/path/to/project"

Validation checks the format; empty checks do not prove product readiness. Add the first accepted task and current focus through the work workflow. Use focused context to avoid redundant loading; see efficiency. Save the uninstall/restore instructions with the handoff.

Menu option 13 opens this guide. Option 14 opens the removal guide. Selecting these guide entries makes no setup or removal changes.

6. Complete a first task

Follow Daily workflow to create a bounded task, set current focus, record actual evidence, review completion, and leave a checkpoint. Use Agent 0 and subagents to verify instruction discovery and connect the records to your assistant. The Prompt cookbook has requests for solo work, authorized subagents, review, and recovery.

Optional: initialize multiple projects

After outer setup, use SYSTEMX PROJECTS to preview and create Projects/NAME/.SYSTEMXP records. Choose a project explicitly for every scoped command. Each new project starts blank with Agent 0 only; existing folders are never replaced. Do not run a second installer inside .SYSTEMX. Use the child's own GLOBAL/ACCESS-MATRIX.md and PLAN/MAP.md for its project-specific boundaries. Do not infer its access from the outer records.

bash .SYSTEMX/SYSTEMX.sh projects add Project-A --kind software
bash .SYSTEMX/SYSTEMX.sh projects add Project-A --kind software --apply
bash .SYSTEMX/SYSTEMX.sh projects context --project Project-A --agent agent.0

& .\.SYSTEMX\SYSTEMX.ps1 projects add Project-A --kind software
& .\.SYSTEMX\SYSTEMX.ps1 projects add Project-A --kind software --apply
& .\.SYSTEMX\SYSTEMX.ps1 projects context --project Project-A --agent agent.0

Optional: activate standard Agent X, Agent Y, and Agent Z roles

The three-role setup requires selected 1.9.0-alpha.2 defaults or a later compatible release. Check the selected version before activation; a project still pinned to 1.8.9-alpha.1 has only the X/Z role format.

Preview and then apply the selected scope's role initialization:

bash .SYSTEMX/SYSTEMX.sh roles-init
bash .SYSTEMX/SYSTEMX.sh roles-init --apply
# For a child project, preview first; then apply explicitly:
bash .SYSTEMX/SYSTEMX.sh projects roles-init --project Project-A
bash .SYSTEMX/SYSTEMX.sh projects roles-init --project Project-A --apply

& .\.SYSTEMX\SYSTEMX.ps1 roles-init
& .\.SYSTEMX\SYSTEMX.ps1 roles-init --apply
# For a child project, preview first; then apply explicitly:
& .\.SYSTEMX\SYSTEMX.ps1 projects roles-init --project Project-A
& .\.SYSTEMX\SYSTEMX.ps1 projects roles-init --project Project-A --apply

Applying creates project-owned event/schedule ledgers, blank Agent Y CLI jobs, a review policy, and X/Y/Z memory. Use the scoped variant for a child. This activation is separate from installing defaults and starts no worker, provider CLI, or scheduler. Follow Agent X, Agent Y, and Agent Z; existing projects remain unchanged until activation.

Choose the next workflow

Use the one-shot project guide for a researched brief through a complete app or report. Use shared workspaces, clouds, and bots when several chats or runtimes need the same scoped records. Confirm the canonical writer, actual access, selected version, and persistence before the first task.

Optional Tier 2 and local DATA setup

After selecting compatible 1.11.0-alpha.6 defaults, preview optional AUTOBOT/Agent Alpha setup in the intended root or child, then explicitly apply it if needed. Alpha activation is separate from X/Y/Z roles-init. Populate only known project facts and retain existing bytes. Preview data init, use --apply for missing scaffolds, then data audit to inspect effective exclusions and tracked payloads. Start with one relevant specialist request; no startup bot/check loop is required.

Optional ROOT planning after the first task

Once the selected defaults support ROOT, preview root init and apply it only where useful. Read ROOT/SX-RULES.md and ROOT/SX-MILESTONE.md, then use existing canonical task IDs for request/outline references and actual harness/bot bindings. A small project can keep using the Master Plan and task ledger alone.

bash .SYSTEMX/SYSTEMX.sh root init
bash .SYSTEMX/SYSTEMX.sh root init --apply
bash .SYSTEMX/SYSTEMX.sh root status
bash .SYSTEMX/SYSTEMX.sh projects root init --project Project-A

The child must already be registered. Its ROOT records initialize separately with an explicit --apply; outer records never become the child's task state. See ROOT planning and task delta for flexible hierarchy, selected packets, tool cards, and readback-based reconciliation.