Developer setup

Arcane OS currently operates in a development-only lifecycle with no staging or production environment. Development uses a normal Git checkout, the shared browser runtime, and a selected platform target when a native build is actually needed. Microsoft NT is the primary native development host. Linux is an experimental unsigned-local developer host with GTK 4 and WebKitGTK 6.0 Provisioner and Shell binaries.

Fast path on Microsoft NT

1. Install Git and clone the repository.

   git clone git@github.com:TheWizardNexus/ARCANE-OS.git
   cd ARCANE-OS
   

Before running setup, confirm that the separate Git LFS program is installed, then initialize and hydrate the required shared speech runtime.

git lfs install --local
git lfs pull --include="local/servers/stt_tts_server/**,local/vendors/ffmpeg/**,local/vendors/kokoro_onnx/**,local/vendors/whisper_cpp/**"

GitHub stores LFS pointer files in the normal Git tree and the corresponding large objects separately, so a checkout without Git LFS does not contain usable STT/TTS binaries or models. The unified bootstrap pulls the required objects and reports when one is unavailable.

2. Double-click Arcane - First Setup and Open Provisioner.bat, or run the unified developer bootstrap from the repository root.

   .\setup-developer.bat
   

After finding the basic tools needed to run, the bootstrap prepares the checkout, installs the declared dependencies and Git hooks, creates or reuses the current developer's local development signing identity required by the Microsoft NT build, builds the selected distribution, and opens the freshly built Provisioner. Setup runs no engineering test profile. Run a test only when you explicitly intend to request that test.

Checkout preparation is deliberately conservative. It considers only retired version-suffixed machine-bundle directories with a canonical three-component suffix and removes one only when Git reports no tracked paths or nonignored untracked work and a filesystem inspection finds no links, special entries, or ignored user material outside recognized generated directories. Every candidate must pass before any is deleted. If preparation refuses a directory, leave it in place and inspect, move, commit, or remove the reported material manually; do not rename it over the permanent machine_bundles/arcane-os-machine-bundle source. Run npm run machine:checkout:prepare for the same focused migration without the rest of setup.

3. If prerequisites are centrally managed, use the documented setup switches instead of editing the script. For example:

   .\setup-developer.bat -SkipPrerequisiteInstall
   

4. Setup opens the development-signed Provisioner automatically. For later use, double-click Arcane - Rebuild Windows and Open Provisioner.bat after a pull, or Arcane - Open Current Provisioner.bat when no rebuild is needed. The binary is under machine_bundles\arcane-os-machine-bundle\dist\nt\bin\ArcaneProvisioner.exe. The local Microsoft NT development signing identity belongs only to the user who created it and is not a production signing claim.

5. To open the native Shell inside the current Microsoft NT desktop session, without signing out or provisioning another account, run:

   .\machine_bundles\arcane-os-machine-bundle\start-shell.bat
   

   The direct Shell reports the current operating-system account. It is suitable for development and screenshots, but it is not first-login acceptance evidence for a provisioned Arcane user. Close the Shell window when finished; its Log out action ends the current host operating-system session.

Fast path on Linux

Install Node.js 22 or newer plus the GTK/WebKitGTK build prerequisites and build the unsigned-local machine bundle:

sudo apt update
sudo apt install -y git-lfs build-essential pkg-config xdg-utils libgtk-4-dev libwebkitgtk-6.0-dev libjson-glib-dev
git lfs install --local
git lfs pull --include="local/servers/stt_tts_server/**,local/vendors/ffmpeg/**,local/vendors/kokoro_onnx/**,local/vendors/whisper_cpp/**"
cd machine_bundles/arcane-os-machine-bundle
./build-linux.sh
./start-shell.sh --allow-unsigned-local-release

./build-linux.sh prepares the checkout and recreates both the root and bundle dependency trees before the Linux build. If internet access is unavailable and the repository-local npm cache is already complete, use ./build-linux.sh --offline; an incomplete cache is reported before compilation.

No host logout or login is required for this direct Shell launch. Installation and account changes require a separately authorized root graphical session because Arcane does not invoke sudo or PolicyKit itself. On supported native Linux, a fresh installation registers the Arcane OS X11 session and changes only the next-boot default to graphical.target; WSLg stays in manual-launch mode and receives no boot-target mutation. Read the Linux developer host guide for the host behavior and the Linux provisioning walkthrough for the account and sign-in transaction.

Manual, browser-runtime-only setup

For documentation, shared JavaScript, and portable app work that does not need a native build:

git lfs install --local
git lfs pull --include="local/servers/stt_tts_server/**,local/vendors/ffmpeg/**,local/vendors/kokoro_onnx/**,local/vendors/whisper_cpp/**"
npm run machine:checkout:prepare
npm ci
npm run hooks:install

Use Node.js 22 or newer. Keep package-lock.json authoritative and use npm ci; do not replace the public registry with an undeclared private or local dependency source.

Build an application

Arcane apps are packaged from their declared contents. The Docs site is an adapter package because it generates a readable catalog from the published documentation and source selection.

npm run app:package -- docs

The command packages only the selected app. The output is written under dist/docs. Only a successful main workflow can publish that directory at https://thewizardnexus.github.io/ARCANE-OS/. The hosted documentation remains development-only and is not staging, production, or a release candidate. Tests and checks run only when the user explicitly requests them or when a selected release artifact requires its own verification.

Create or change an app

Before implementation:

1. Read docs/app-building.md in full.
2. Search arcane/, existing apps, examples, and tests for reusable behavior.
3. Answer the four capability questions and keep general mechanisms in the appropriate shared arcane/ layer.
4. Load arcane/css/theme.css and arcane/modules/ThemeBootstrap.js, then shared primitives, then app CSS.
5. Use Arcane theme tokens and rgb(...) or rgba(...) for any new color values.
6. Add the capability declaration, examples, and packaging updates when that boundary is in scope. Add test coverage as source when useful, but run it only when the user explicitly requests it or a selected release artifact requires it.

When diagnosing an ordinary discrepancy, follow the compact development path in docs/debugging.md: establish the expectation, preserve the reported state, inspect the first divergence, and make the smallest coherent repair. Run a focused reproduction or check only when the user explicitly authorizes it.

Work with the Developer app

Inside an installed Arcane environment, Arcane Developer can pair one explicitly selected checkout, inspect its supported setup state, and run one chosen setup task at a time. Its assistant uses the AI provider configured for the current Arcane user and adds no app-owned cap to the secret-pattern-redacted repository context supplied by the shared workspace mechanism. Shared workspace and provider limits are reported when present. It never scans for checkouts or executes AI suggestions.

The public development GitHub Pages site at https://thewizardnexus.github.io/ARCANE-OS/ has no native filesystem or command authority. Its search works against the published catalog; its optional assistant remains unavailable unless a compatible Arcane AI bridge is present. Publishing the documentation does not promote Arcane OS or any native build beyond the development profile.