Getting Started

Setup

Beta prerelease. Pin reviewed defaults, retain a recoverable backup, and validate them in your project. See the release policy.

New users should start with First-Time Setup, including preview, local installation logs, first project facts, verification, and removal planning. Open the Agent 0 roster to find the selected scope's registered roles, named instances, setup paths, and external CLI boundaries. For Codex/DOT, Amazon Kiro, another coding CLI, an IDE harness, or a named online BOT, follow the provider and harness onboarding sequence alongside Agent1's access and secret review. The current system atlas, four maps, and seven detailed agent guides show the record paths, CLI routes, and authority boundaries before first use. Once installed, record the project's actual routes in the System MAP and verified action boundaries in the Access Matrix.

Adopt the folder

Use the exact stored name .SYSTEMX on every platform. Review the case and alias guide before copying files. The installer option --lowercase-alias and menu option 12 provide an optional local alias; menu option 11 checks the current layout without changing it.

1. Choose project/VS Code, OS directory, Google Drive, or LLM chat. Identify the destination working directory and inspect existing files, including hidden files and local changes.
2. Use the additive installer for a managed version and pin, or copy the complete reviewed .SYSTEMX folder for document use and optional trusted local launcher commands. If one already exists, do not copy over it. Review an installer dry run and preserve existing records. Use a clean template checkout or reviewed release archive; a working project's folder can contain ignored private data that ordinary filesystem copying retains.
3. Read the selected release's .SYSTEMX/START-HERE.md, .SYSTEMX/docs/FIRST-RUN.md, and standard; inspect the scripts before execution. Those versioned files govern setup; this wiki is a changeable reference.
4. Run bash .SYSTEMX/SYSTEMX.sh validate and bash .SYSTEMX/SYSTEMX.sh doctor. Python 3.9+ is required only for the command tools. Git is optional for documentation use; the doctor uses it if available.

For a managed project, systemx run --target "/path/to/project" -- validate uses its selected defaults even if an older root launcher was retained. New installations are pinned with manual updates; opt-in startup release notices are configured separately in the installation guide. Existing root default copies remain unchanged.

Before initializing a pristine distribution, validate --template additionally checks that its project seeds are blank and that only distribution files are present. Use ordinary validate after adoption. The format contract documents these separate modes.

The CLI and Tools guide distinguishes the installed management CLI from local launchers, app/IDE workers, configured tools, and external provider CLIs. tools-guide and menu option 18 print the local guide. For child scopes, use the direct .SYSTEMXP command examples.

Agent 0 roster and CLI providers

After setup, inspect the selected scope's local roles and named instances:

bash .SYSTEMX/SYSTEMX.sh root roster
bash .SYSTEMX/SYSTEMX.sh onboard plan
bash .SYSTEMX/SYSTEMX.sh agent-y providers

root roster reads registered agents, AUTOBOT references, BOT/DOT records, recorded CLI channels, and access-decision pointers. It does not start a worker or verify a provider account. onboard plan pairs that local view with Agent1 question counts, provider surface choices, and credential-consumer boundaries; it does not connect a provider. agent-y providers detects installed CLI names, not usable login or permission. Check authentication and rights in the actual external system before a task handoff. Use Agent 0 roster for menu option 33 and the workbook tab; Agent 0 and subagents for task ownership; CLI and Tools and Agent Y for provider setup. The selected release's installable roster guide provides the exact child-scope route and command options.

Record project choices

Run bash .SYSTEMX/SYSTEMX.sh init to create .SYSTEMX/project.json. This creates only that file and never overwrites existing configuration.

Create .SYSTEMX/project/ as needed. Copy the project brief and architecture there, and replace prompts with project facts. Keep reusable templates blank for the next project. Describe unknowns as unknowns rather than making up requirements.

Fill GLOBAL/CONTEXT.md with approved shared context and create the accepted milestones in PLAN/MASTER-PLAN.md. Use WORK/README.md to create concrete tasks. The coordinator is agent.0; register other workers only as needed. Begin and end work with the memory protocol, keeping records specific to this project.

Select the runtime, package manager, build approach, environments, integration owners, deployment target, and applicable quality checks. Do not install every tool mentioned in the documentation. Pin the selected runtime and dependency versions through the host project's normal files and lockfiles.

Review the stock Agenda and Access catalogs

Beta.2 includes two read-only stock definition files: ten AUTOBOT context settings in AUTOBOT/AGENDA-SETTINGS.json and access decision rules in GLOBAL/ACCESS-DECISION-RULES.json. Each setting defaults to unset and includes no context automatically. The Access Matrix still has 20 default-deny role and actor-pattern rows; a selected project's options and decisions arrays start empty. The catalog is a reference, not an actual permission.

From the containing project directory, inspect the fixed definitions and the selected scope separately:

bash .SYSTEMX/SYSTEMX.sh agenda catalog
bash .SYSTEMX/SYSTEMX.sh agenda status
bash .SYSTEMX/SYSTEMX.sh agenda table --format csv

On Windows, use pwsh -File .SYSTEMX/SYSTEMX.ps1 agenda catalog. After an adopted beta.1 scope selects beta.2 defaults, agenda catalog can show a distribution-preview while the new catalog pair is absent. Preview agenda init to inspect the additions; activate Agent Alpha in that selected scope before applying it. The additive write preserves existing options and decisions. See Access Matrix and Agent Alpha for decision and context-selection review rules.

Wire commands

Edit .SYSTEMX/project.json using the configuration contract in the README. Point each check at a real project command. Order fast checks before expensive ones. Add development, build, and deployment commands only when the host project supports those operations.

Use checked-in scripts for complex workflows. Do not put credentials in command arrays. A docs-only project can use document validation and generation; a library may leave deployment unconfigured until its publish process is defined.

bash .SYSTEMX/SYSTEMX.sh doctor
bash .SYSTEMX/SYSTEMX.sh check --dry-run
bash .SYSTEMX/SYSTEMX.sh check

Read the displayed plan before running unfamiliar commands. --dry-run runs no project commands, including quality checks. Missing executable names are reported by doctor; remote authentication and service health are not tested.

Establish boundaries

• Add host-project ignore rules for secrets, dependencies, caches, and artifacts. .SYSTEMX/.gitignore protects only paths inside .SYSTEMX.
• Use .SYSTEMX/local/, logs/, or state/ for private local runtime artifacts. Git ignore rules are convenience, not secret protection or access control.
• Keep sanitized project configuration and project records in version control.
• Configure public output allowlists so .SYSTEMX and private material cannot be published accidentally.
• Put any AI discovery entry point required by your tool at the host repository root and link it to START-HERE.md. Merge the supplied entry-point template with existing instructions. A hidden folder is not automatically discovered by every AI tool.

Ready for project work

Project setup is ready when context is recorded, selected tools are available, configured checks pass, and local run/build instructions are reproducible. Production acceptance additionally requires the applicable release steps in OPERATIONS.md. A template validation pass proves neither state.

Continue with Daily workflow, then use the Prompt cookbook to ask your assistant to execute, review, or checkpoint a task. The manual home provides the full reading order.

More than one project or channel

Keep one outer installation and create child record folders through SYSTEMX PROJECTS. Each .SYSTEMXP has its own context, plan, work ledger, status, sources, and agent memory. This is optional; existing root work remains valid. Never install .SYSTEMX inside .SYSTEMX.

Complete projects and connect shared work

• One-shot project guide: start with a deep-research brief, map a 20-page web app, organize phases/milestones/tasks/waves, coordinate workers, and finish with evidence.
• Shared workspaces, clouds, chats, and bots: choose repository, portfolio, or hybrid ownership; connect authorized Drive/cloud/local context; reconcile multi-chat and bot handoffs.

Both guides explain the shared-context feedback model and provide copyable prompts. Verified project knowledge can accumulate across turns; persistence and review remain explicit rather than automatic model training or a guarantee of AGI.