Developer setup

Arcane OS currently operates in a development-only lifecycle with no staging or production environment. Development uses a normal Git checkout, locked public dependencies, the shared browser runtime, focused Node.js tests, and explicit platform-specific build gates. 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, root-authorized standard-account provisioning, and a guarded X11 graphical-session policy.

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/**"
git lfs fsck

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 repeats the pull and integrity checks and fails closed if Git LFS or a required object 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 verifying the basic tools needed to run, the bootstrap prepares an upgraded checkout before dependency installation, signing, or compilation. It verifies dependency registries and machine-version metadata, installs locked dependencies and Git hooks, creates or reuses the current developer's non-exportable local signing identity, builds a development-signed Microsoft NT distribution, and opens the freshly built Provisioner. Setup runs no engineering test profile; it can fail only for a prerequisite/build-safety problem, failure of the requested build, or failure to start the Provisioner. Run npm test separately when you intentionally want the development tests.

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. Local development trust belongs only to the Microsoft NT user who created it and is never 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, verify the public dependency sources, and build and verify 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/**"
git lfs fsck
cd machine_bundles/arcane-os-machine-bundle
./build-linux.sh
npm run verify:distribution:linux:unsigned-local-test
./start-shell.sh --allow-unsigned-local-release

./build-linux.sh prepares the checkout, verifies the public lock sources, and freshly 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 fails before compilation. The explicit verification command above checks the final published tree before launch.

No host logout or login is required for this direct Shell launch. Installation and account changes require the exact verified Provisioner in a separately authorized root graphical session; Arcane does not invoke sudo or PolicyKit itself. On supported native Linux, a fresh installation registers the guarded 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. Linux publisher signing, automatic privilege brokerage, and disposable-host acceptance remain incomplete. Read the Linux developer host guide for the host boundary 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/**"
git lfs fsck
npm run machine:checkout:prepare
npm run verify:package-locks
npm ci
npm run hooks:install
npm test

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 and test an application

Arcane apps are packaged from positive inventories. The docs site is an adapter package because its catalog is generated from a reviewed public-source allowlist.

npm run demo:check -- docs

The command packages and verifies only the selected app. The verified output is written under dist/docs. Pull-request validation has no deployment authority; only a successful main workflow may upload that verified directory and publish it at https://thewizardnexus.github.io/ARCANE-OS/. The hosted documentation remains development-only and is not staging, production, a release candidate, or release evidence.

Run the default development gate before pushing or handing off:

npm run check

The development gate repeats checkout preparation before its strict neutral-directory and manifest-version invariant, so a pull or branch switch cannot leave an obsolete version-suffixed build directory masquerading as active source.

For explicit cross-repository integration, use:

npm run check:integration

The Microsoft NT compiled gate remains an explicit native-boundary operation:

npm run check:windows

npm run release:check:arcane-os is the explicit Arcane-OS-only release gate. It combines the portable Arcane OS integration boundary with the compiled Microsoft NT OS gate while excluding app-owned behavior suites. Passing it does not create a staging environment, turn a local build into a release candidate, or replace production signing and clean-machine acceptance.

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 and focused tests required by the change. Add examples and packaging updates when that boundary is in scope; formal security/accessibility evidence is deferred to promotion unless the development change crosses a real high-impact boundary.

When diagnosing an ordinary discrepancy, follow the compact development path in docs/debugging.md: verify the expectation, reproduce, preserve useful evidence, isolate one cause, fix it, and rerun the focused original case. Use the complete clean-state sequence for security/privilege defects, destructive or persistent failures, unexplained flakes, and promotion blockers.

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 sends only bounded, secret-pattern-redacted repository excerpts. 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 explicitly injected by a trusted host. Publishing this bounded documentation artifact does not promote Arcane OS or any native build beyond the development profile.