Developer command reference

This is the authoritative table of supported system-level commands used to set up, develop, test, package, build, sign, and verify Arcane OS. Run root commands from the repository root unless a row says otherwise. Application-owned commands and product-specific command modes are documented with their owning packages and participate in the same completeness check.

Setup and routine verification

Every development-assets.ps1 action defaults to canonical OsSetup: 188 active paths comprising 116 shared speech assets and 72 published application originals (1,229,912,436 bytes). AppDevelopment must be passed explicitly to include all 260 entries and activate the 72 otherwise-passive application-source paths.

A version advance such as 0.8.10 to 0.8.12 is a verified transactional update and never a clean-uninstall trigger. An intentional clean reset still uses the exact installed ArcaneUninstaller.exe, its UAC prompt, and its typed confirmation; Microsoft NT must then restart before setup is rerun. If setup finds the protected uninstall stage left for restart or failure recovery, it stops before asset, dependency, signing, or build work instead of attempting a second uninstall or an unsafe same-session reinstall.

Command	Purpose	Result / output	Use
.\setup-developer.bat	Performs the Microsoft NT developer bootstrap from a real checkout root no longer than 46 UTF-16 code units. Before asset hydration it validates the pinned WebView2 metadata/cache shape, required SDK/.NET host paths and portable-executable identities, generated-release metadata and link-free exact topology, lock sources, synchronized version identity, and all four Windows host/source contracts; prepares an upgraded checkout; then owns passive-filter configuration, exact OsSetup asset hydration, dependencies, hooks, development signing, and the requested build. It runs no engineering tests and never activates app-source assets.	Prepared checkout, 1,229,912,436 exact OS-setup bytes, hydrated speech runtime, development-signed Microsoft NT distribution, and the freshly built Provisioner opened after success. Predictable input, toolchain-shape, source-contract, or existing-output failures stop before the expensive asset/dependency/build path; the pinned SDK is hash-verified and extracted from one retained stream at its consumption boundary, and functional/new-output checks run at their creation boundary.	Normal first-time setup or setup after upgrading an older checkout; use a short path such as C:\ArcaneOS. A valid older generated or installed version is an update/replacement input, not an error or clean-uninstall trigger.
.\Arcane - First Setup and Open Provisioner.bat	Clearly named double-click alias for setup-developer.bat.	Completes the unified first setup and opens the freshly built Provisioner once.	First use, prerequisite repair, asset repair, or an upgraded checkout.
.\Arcane - Rebuild Windows and Open Provisioner.bat [--offline]	Verifies the Microsoft NT checkout path and public lock sources, recreates the root and machine-bundle dependency trees with one npm ci each, runs the prepared-checkout Microsoft NT build exactly once, refuses stale output after any failure, verifies the new Provisioner exists, and then opens it. The optional explicit offline mode adds --offline to both installs and fails if the verified local cache is incomplete; an online failure never silently selects it.	Fresh dependencies, a fresh development-signed Microsoft NT distribution, and one Provisioner launch.	Normal post-pull development rebuild when prerequisites and assets are already prepared; use --offline only when internet access is unavailable.
.\Arcane - Open Current Provisioner.bat	Opens the already-built checkout Provisioner. If no build exists, the canonical Provisioner launcher invokes unified setup once.	Current Provisioner, or a first setup followed by the Provisioner when output is missing.	Fast reopen without rebuilding.
.\setup-developer.bat -SkipPrerequisiteInstall	Runs setup without using WinGet.	Same as setup when prerequisites already exist.	Managed machines or reruns.
.\setup-developer.bat -SkipChecks	Compatibility switch retained for older launch commands. It does not bypass required source, toolchain, publication, lock, version, or build-safety preflight.	Same fail-closed setup as the default command.	Existing automation only; omit it for new commands.
.\setup-developer.bat -SkipSigning	Does not create or use a development certificate.	Explicitly labeled unsigned-local-test build.	Local verification only.
.\setup-developer.bat -SkipBuild	Installs and verifies the development environment without building or opening the Provisioner.	Ready development checkout.	Environment preparation only.
.\setup-developer.bat -CleanInstall	Requests an explicit destructive reset. Before checkout build constraints, Node, assets, dependencies, signing, or build work, setup requires canonical Microsoft NT roots, no pending uninstall stage or install lease, exact administrator-protected Apps & Features ownership, canonical installed ACLs, and a manifest-bound uninstaller whose publisher state matches the protected installation. It retains the exact uninstaller bytes while opening that executable once through UAC with no arguments. This switch cannot be combined with -SkipBuild.	Exit disposition 23 means only that the interactive installed uninstaller was opened; it is not uninstall success. Complete the typed UNINSTALL ARCANE OS confirmation, restart Microsoft NT only after reported success, then rerun this same command for the fresh build and one Provisioner launch. If no installation exists, the same command proceeds directly as fresh setup.	Intentional purge/reset or an administrator-chosen signed-to-unsigned trust reset. Never use for an ordinary version upgrade, same-version repair, signer rotation, downgrade, malformed metadata, or unsafe recovery state.
npm run setup:developer	PowerShell form of the unified setup after Node/npm exists.	Prepared checkout and requested build; unlike the interactive .bat, it does not open the Provisioner.	npm-driven or scripted setup.
npm run machine:checkout:prepare	Runs the Git-backed machine-bundle checkout migration directly. It removes only retired version-suffixed machine-bundle directories with a canonical three-component suffix that contain no tracked paths, no nonignored untracked work, no links or special entries, and no ignored files outside recognized generated directories.	The permanent neutral machine-bundle source plus a list of any safely removed ignored-only legacy residue.	Manual preparation after upgrading a checkout, or focused diagnosis when setup or check:dev refuses legacy residue.
npm run verify:windows-checkout-paths	Reads the NUL-delimited Git-tracked path inventory and enforces a 160-UTF-16-code-unit repository-relative budget using Windows separators. On Microsoft NT it also limits the resolved build root to 46 code units, one below the exact current legacy-API ceiling.	Pass/fail inventory with the longest tracked path, absolute build-root length, and actionable remediation.	Focused diagnosis before a path rename, or automatic early verification within check:dev; move or clone to C:\ArcaneOS when the build root is too deep.
.\tools\development-assets.ps1 -Action Inspect	Uses default OsSetup to verify exactly 188 active paths and requires each to be either its pinned bytes or canonical LFS pointer. The 72 application-source paths are excluded unless -Scope AppDevelopment is explicit. Current release identities may retain the optional Core-only localAIModelPolicy; setup binds the complete manifest without projecting or duplicating native admission's policy validation.	Complete, Pointers, or PublishedPointers; fails on missing, modified, linked, or unapproved selected paths.	Focused read-only checkout diagnosis. Use setup-developer.bat for supported hydration.
.\tools\development-assets.ps1 -Action Hydrate -GitHubCliPath <gh.exe>	Uses default OsSetup and verifies the exact development-only tag/title, all 93 part names/sizes/digests, and both aggregate ZIPs. For the combined application archive it authenticates all 144 central-directory records, then opens, decompresses, individually hashes, and writes only the 72 selected published entries. Source members remain metadata/transport-only.	Exact required shared speech and published application files; the 72 source pointers remain byte-identical. The unchanged fallback transfer totals 1,554,389,002 bytes.	Focused hydration. Unified setup uses PrepareIndex so hydration and final verification share one owner. Requires authenticated private-repository access and never produces a product release.
.\tools\development-assets.ps1 -Action PrepareIndex -GitPath <git.exe> -NodePath <node.exe>	Canonical setup owner. It classifies without hashing exact-size candidates, optionally hydrates selected pointers, then gives one persistent Git process-filter the authenticated scope inventory. The owner retains selected files and policy inputs while the filter binds canonical path/filesystem identity/size/SHA-256, manifest and published-release hashes, Node toolchain, platform, architecture, and generation.	Complete, Pointers, or PublishedPointers. A complete default OsSetup hashes exactly 188 files/1,229,912,436 bytes once, transactionally updates only an isolated index, preserves excluded app-source entries, and derives the 116-file speech result from that generation.	Unified setup. AppDevelopment is explicit and hashes all 260 files/1,554,301,072 bytes; it never occurs in OS setup. Mutation invalidates the generation before retry.
.\tools\development-assets.ps1 -Action RefreshIndex -GitPath <git.exe> -NodePath <node.exe>	Focused exact/index form of the same single-owner transaction for an already hydrated selected scope. It rejects pre-existing/resulting staged asset changes and a concurrent byte, policy, tool, or index mutation.	Same bounded one-process progress and fail-closed isolated-index result as PrepareIndex; canonical pointer blobs remain unchanged.	Focused repair or contract verification. Pass -Scope AppDevelopment explicitly for all 260 entries. Cancellation or failure discards temporary selection/index files and preserves the real index.
.\tools\local-speech-runtime.ps1 -Action Verify	Verifies that the required shared STT/TTS executable, FFmpeg, Kokoro assets, and Whisper assets are hydrated regular files rather than missing Git LFS pointers.	Required-file, link-safety, file-count, and byte-count report.	Focused checkout verification; does not start either speech endpoint.
npm ci	Recreates the exact root dependency tree from the committed lock without rewriting installed third-party module contents. Use a second npm ci --prefix machine_bundles/arcane-os-machine-bundle when the machine bundle is in scope.	Fresh root node_modules, plus the fresh machine-bundle tree when selected.	Clean installs; do not substitute npm install or a copied dependency directory. With no internet, prefer explicit --offline against the verified repository-local cache.
npm run hooks:install	Installs the repository Git hooks, including canonical-root-bound post-pull compatibility maintenance, Git LFS object upload, and the development check before each push.	Configured development hooks.	Hook repair or manual setup.
npm run prepare	npm lifecycle alias that installs the repository Git hooks.	Configured Git LFS-aware development-check hook.	Runs automatically after supported dependency installs; manual use is rarely needed.
npm run verify:package-locks	Rejects dependency URLs outside approved public npm registries.	Pass/fail registry report.	Before and after lockfile changes.
npm run verify:setup	Runs the dependency-free setup source preflight: public package-lock registries, synchronized machine-bundle version metadata, and the four Microsoft NT host/source contracts used by the build. It runs no engineering tests and creates no build output.	Prerequisite-only pass/fail result before asset hydration, dependency installation, signing, or compilation.	Called by unified developer setup; not a development or test gate.
npm test	Alias of test:dev.	Fast development test report.	Routine focused verification.
npm run test:focused -- <test-file...>	Runs one or more explicitly named Node test files, rejecting more than 64 entries.	Focused Node test report for only the requested contracts.	Fast iteration before the broader development gate.
Arcane SDK integrated provider: tools/integrated-development-provider.mjs	Exposes the fixed arcane-integrated-toolchain/1 describe, prepare, and execute contract. It accepts only focused-test for exactly one repository-relative regular non-linked .test.mjs through tools/run-focused-tests.mjs, or development-check through npm run check; arbitrary commands, npm script names, multiple tests, package/build operations, and output selection are rejected.	One owned child process per request and a frozen invocation/completion record. integrated.operation.started and preparation events acknowledge before filesystem or process work; the SDK-owned runner streams process events and heartbeat, owns completion/error reporting, and receives the same AbortSignal for process-tree cancellation. Preparation checks only the current package, runner, and selected test path; no package, app, platform, model, asset, signing, hash, or verification-receipt loop is created.	Inside the Arcane OS checkout, run npm exec -- arcane test --workspace <arcane-root> --scope shared --test-file <repo-relative.test.mjs> for one focused shared test or npm exec -- arcane check --workspace <arcane-root> --scope shared for the canonical development gate. Shared scope is integrated-only and selects no app, target, package, or output; neither operation is a build, package, release, or production claim.
npm run test:dev	Runs encoding hygiene, catalog and badge validation, and focused Node-only development/test-infrastructure contracts.	Fast development-invariant report without OS coverage, complete OS integration, native, or application behavior suites.	Ordinary development, setup, CI, and pre-push.
npm run test:os	Runs test:dev followed by the remaining unique portable Arcane OS/shared-runtime contracts and generic ARCANE_APP_RELEASE.json admission checks. It excludes app adapters, source/content verifiers, and application-owned business-behavior suites.	Arcane OS portable and published-payload-admission report without rerunning canonical managed cases.	Explicit Arcane OS integration or release work.
npm run test:legacy:root	Runs only the remaining unique root OS contracts after test:dev; migrated canonical cases and app-owned suites are excluded.	Node test report for not-yet-migrated OS contracts.	Compatibility diagnosis; test:os owns this lane.
npm run test:encoding	Checks tracked text for common encoding corruption.	Pass/fail encoding report.	Before handoff or after text changes.
npm run verify:encoding	Runs the encoding hygiene checker in non-mutating verification mode.	Pass/fail tracked-text encoding report.	CI, pre-push, and any change that touches tracked text.
npm run test:docs	Runs the explicit Node contract suite for the Docs application, publication policy, shared browser dependencies, and package adapter.	Focused Docs contract report.	Docs content, publication, shared browser-runtime, or packaging changes.
npm run test:docs:coverage	Runs test:docs under c8 and records aggregate line coverage for Docs publication JavaScript under tmp/docs-quality/node-coverage/.	Private detailed coverage plus an aggregate line-coverage value; it is not whole-OS coverage.	Before generating verified Docs quality evidence.
npm run test:docs:browser	Serves the already-packaged Docs app on loopback, uses vanilla-test@2.1.0 to drive its existing browser checks in installed Google Chrome, and captures Chrome precise coverage only for first-party JavaScript and CSS the Docs app already runs.	Aggregate-only browser results in tmp/docs-quality/browser-summary.json; no native-only UI is adapted or measured.	Docs browser UI or public quality-evidence changes; run after packaging Docs.
npm run quality:docs	Clears prior Docs quality evidence, runs the Docs Node coverage suite, packages Docs, executes its Chrome/Vanilla Test checks, then rebuilds and verifies the package with same-run aggregate badges and evidence.	Verified dist/docs development artifact with self-hosted version, lifecycle, license, test, and narrowly scoped coverage badges.	Before publishing Arcane Docs; requires installed Google Chrome.
npm run clean:encoding	Conservatively repairs valid Windows-1252-to-UTF-8 mojibake in tracked text.	Changed tracked text files for review.	Repair command before rerunning the encoding check.
npm run cleanup:preview	Runs git clean -ndX to preview ignored files that Git would consider removable without deleting anything.	Read-only ignored-output inventory.	Before an Arcane OS or app release, or when checkout size grows unexpectedly; review every path before exact cleanup.
npm run maintenance:gc	Runs git gc --auto for safe local Git object maintenance.	Git-selected local object packing/cleanup when needed.	After reviewed cleanup or periodically; it does not rewrite shared history or purge remote LFS objects.
npm run verify:os:catalog	Validates every registered ARCANE OS test reason, owner, implementation, profile, resource, cleanup, and evidence record.	Catalog count or an exact validation failure.	After changing OS tests, profiles, or test ownership.
npm run verify:os:badges	Validates every tracked README badge endpoint and its numeric/not-run evidence format.	Eight valid set-specific badge endpoints.	After changing OS test results or badges.
npm run test:os:unit	Runs each canonical portable OS unit case once through the managed runner.	Numeric total/passed/failed/skipped/duration and cleanup summary.	Shared deterministic mechanism changes and ordinary development.
npm run test:os:functional	Runs each canonical portable OS functional case once without live services.	Numeric total/passed/failed/skipped/duration and cleanup summary.	Shared public capability and controlled boundary changes.
npm run test:os:mail	Runs exactly the three canonical shared mail transport/configuration cases.	Numeric total/passed/failed/skipped/duration and cleanup summary.	Focused mail client and gateway-boundary changes.
npm run test:os:ui	Parses the production Shell and Provisioner HTML in a standards-compatible DOM and executes each complete unmodified inline controller against controlled bridge boundaries.	Numeric total/passed/failed/skipped/duration and cleanup summary.	Shell, Provisioner, frontend-controller, or bridge changes.
npm run test:os:controller-ui	Selects the canonical controller/UI profile directly through the bounded OS test supervisor.	Numeric UI profile report and cleanup summary.	Focused controller/UI compatibility diagnosis.
npm run test:os:system:portable	Runs built/generated Core, terminal-process, and release-integrity composition against disposable fixtures.	Numeric total/passed/failed/skipped/duration and cleanup summary.	Core/RPC/process/package/integrity changes and explicit integration.
npm run test:os:portable-system	Delegates to the machine-bundle owner, builds the current Core once, then runs the portable-system profile against that generated state.	Built portable-system report without duplicating the owning build.	Explicit Core/package composition verification.
npm run test:os:infrastructure	Tests the bounded OS test supervisor, catalog routing, cleanup, and failure propagation.	Node test report for the OS test infrastructure itself.	Changes to the OS test runner or its command graph.
npm run test:os:smoke	Selects four existing canonical cases spanning a public API, Shell UI, Core RPC, and fail-closed release integrity.	Small numeric smoke summary; no copied test implementation.	Rapid built-artifact health check.
npm run test:os:coverage -- --evidence-dir tmp/os-test-evidence/coverage	Runs the combined unit and functional catalog exactly once under c8 native V8 coverage and retains the same-run reports and set summaries in the ignored owned evidence root.	Same-run reports for statements, branches, functions, and lines. The current Node.js 22.23.1/c8 11.0.0 baseline is 84.26% lines and statements (3,271/3,882), 92.85% functions (221/238), and 83.66% branches (1,004/1,200).	Explicit coverage review and the dedicated ARCANE OS coverage evidence workflow; never setup, smoke, ordinary check, or ordinary development CI.
npm run check:os:dev	Validates the canonical OS test catalog and badges without running the coverage lane.	Fast catalog and badge invariant result.	Ordinary OS development, setup, and CI.
npm run test:os:integration	Runs UI, portable-system, and not-yet-migrated unique legacy OS checks without rerunning unit/functional cases.	Per-set managed summaries plus a numeric 19-check compatibility summary and cleanup result.	Explicit cross-boundary integration.
npm run check:os:integration	Runs check:os:dev, the explicit OS coverage lane, and test:os:integration.	Complete platform-neutral OS integration evidence.	Shared Core/UI/package boundary changes.
npm run check:os:release	Composes checkout-path, lock-source, development, coverage, controller/UI, portable-system, and Microsoft NT checks without bypassing their owners.	Explicit development release-gate report.	Future promotion work only; not ordinary feature development.
npm run test:os:docs-runtime	Runs the eight shared OS unit cases and two scoped-cache functional cases used by the Docs publication workflow directly in one confined managed worker, without a nested test-runner process.	Numeric set, unit/functional subtotals, and cleanup summary.	Docs/shared-runtime changes.
npm run mail:test	Runs the shared mail gateway, application-routing, and browser transport contract suites with a fake SMTP transport.	Node test report; no network mail is sent.	Mail gateway, client routing, SMTP reliability, or deployment-policy changes.
npm run mail:start	Acknowledges startup, reads only approved MAIL_* entries from the current user's Arcane environment profile (including protected storage), removes ambient process values for that approved mail set, injects the profile without mutation or secret logging, and starts the loopback HTTP-to-SMTP gateway.	Readiness-verified listener on 127.0.0.1:8025 by default.	Local mail development after configuring the authorized protected environment profile; see docs/mail-gateway.md.
npm run mail:start:environment	Starts the loopback Arcane HTTP-to-SMTP gateway directly from validated process MAIL_* values without reading the Arcane environment profile.	Readiness-verified listener on 127.0.0.1:8025 by default.	Administrator-managed environment-file/service deployments.
npm run test:app-data-isolation	Runs canonical app-identity, DBOPFS/DBLS/worker/cache, native Core files, Microsoft NT/Linux profile paths, and Android profile source tests.	Node test and host-source reports.	Persistent-storage, renderer-profile, or app-identity changes.
npm run test:machine	Runs the portable machine-bundle OS check.	Core, bridge, host security, and app-package boundary checks without all-app builds or app behavior suites.	Machine/runtime changes or an Arcane OS release.
npm run test:external-apps	Runs the Arcane-owned external release-lock and one-pass artifact-admission contracts, including hostile GitHub/Ed25519 authority, immutable release/asset identity, archive, portable path-topology, deterministic-control, linked-placement, committed-state warning, runtime-lock, retained-backup cleanup, rollback, and cancellation cases.	Focused 33-test external-app trust-boundary report.	External repository, lock schema, deterministic bundle, admission, or external registry changes.
npm run test:os-app-builder	Runs the standalone OS-selector argument, delegation, and signing-profile contract tests.	Focused Node test report.	Standalone builder, target selection, or signing-profile changes.
npm run test:machine:fast	Runs the focused Microsoft NT iteration source-contract check without building or hashing a release tree.	Fast iteration contract result.	Local engineering before a fast iteration build.
npm run check:dev	Safely prepares an upgraded checkout, enforces the tracked Windows checkout-path budget, verifies public lockfile sources, checks machine-version and encoding invariants, and validates the OS catalog and tracked badge evidence.	Prepared checkout plus fast development-contract verification, without behavioral OS suites or coverage.	Default rapid-development, pre-push, and ordinary-CI prerequisite gate.
npm run check	Runs check:dev, the focused external-app trust boundary, then the complete cataloged portable OS unit profile once.	Development invariants plus external-app and numeric unit results; no functional, coverage, UI, system, native, or application behavior suite.	Before ordinary push or handoff when the canonical development gate is required.
npm run demo:check -- <app-id>	Rebuilds and verifies only the selected browser-context application package.	Verified dist/<app-id> development artifact.	Internal demonstration or selected package investigation; not staging or release evidence.
npm run app:external:inspect -- <app-id> --artifact <bundle> --proof <proof>	Acknowledges first, reads the Arcane-owned lock, stages and hashes each exact input once, verifies its independent authority, then streams the deterministic SDK bundle through bounded USTAR/gzip and release validation without installing it.	Non-retained candidate-verification receipt; no dist/<app-id> replacement.	Review an already downloaded external release and detached proof before admission.
npm run app:external:admit -- <app-id> --artifact <bundle> --proof <proof>	Performs the same authenticated one-pass verification, writes each payload file once into a private stage, and atomically replaces only the locked dist/<app-id> target.	Process-local admission receipt plus the exact authorized release tree.	After the lock entry and independent authority have been reviewed; cancellation or failure preserves the prior target.
npm run check:integration	Runs lockfile verification, test:os, and the portable machine-bundle OS check.	Complete platform-neutral Arcane OS integration report without duplicate managed cases or app behavior suites.	Explicit Arcane OS integration or release preparation.
npm run check:windows	Runs the Microsoft NT machine-bundle gate.	Microsoft NT smoke, unsigned build, and verification results.	Microsoft NT/release-path changes.
npm run check:windows:fast	Runs the focused iteration contract and an outer-hash-light build. It retains and verifies the SHA-256 machine manifest required for direct launch, while skipping the full app-package, release-directory, dispatch, and distribution suites.	Directly launchable dist/nt-iteration.	Local engineering only; never release-candidate evidence.
npm run prepush	Runs check:dev.	Fast lockfile and root contract result.	Normally invoked by Git during the current development-only lifecycle.
npm run release:check:arcane-os	Verifies the Microsoft NT build-root budget before any release work, then runs the portable Arcane OS integration gate followed by the complete Microsoft NT OS gate. App identity, capability, inventory, hash, and catalog admission remain OS responsibilities; app behavior suites are excluded.	Arcane-OS-only technical release report; signing/review/acceptance remain separate.	An explicit Arcane OS release moment only.
npm run release:check	Compatibility alias of release:check:arcane-os.	Same Arcane-OS-only technical release report.	Existing release automation; prefer the explicit command.

Installed third-party modules are opaque dependency content. Repository source checks do not assert their formatting or source bytes; deployment and quality-assurance functionality testing validates their behavior. Generic package-integrity verification still covers every distributed file.

Repository JavaScript cases admitted through Node's test API require Node.js 22.12.0 or newer and enter one vanilla-test 2.1.0 lifecycle per case through the shared adapter. Node remains the repository-wide orchestrator for discovery, hooks, selection, isolation, timeouts, cleanup, concurrency, normalized reporting, and exit status. Native and non-JavaScript suites retain their established runners, and the separately owned c8 11.0.0 unit/functional coverage contract is unchanged.

Unified setup owns checkout preparation, its early Microsoft NT build-root guard, exact-asset validation, package-lock source verification, dependency installation, version validation, signing safety, and the requested build. Its asset owner acknowledges through the setup transcript before work, runs one backpressured process-filter, and retains selected asset/manifest/filter/release-policy handles until the isolated-index transaction completes. The exact 188-file OsSetup generation is the immutable receipt consumed by index normalization and the unchanged 116-file speech subset; byte, filesystem identity, scope, manifest, release policy, toolchain, platform, architecture, or index mutation invalidates it. Progress and five-second heartbeats reach the transcript; cancellation, child failure, or retry preserves the real index and discards temporary state. It invokes the prerequisite-only npm run verify:setup; it never invokes a test, generic check, coverage, smoke, UI, application, or test-infrastructure profile.

The dedicated .github/workflows/arcane-os-coverage.yml workflow is the sole CI owner of OS coverage evidence. Relevant source changes trigger that path-filtered Windows x64 workflow, and an explicit dispatch can rerun it without a source change. Each job invokes the documented test:os:coverage npm owner once with an ignored evidence directory, verifies the tracked unit and functional badge endpoints against that run's normalized summaries, then uses node tools/os-test-badge.mjs verify-coverage to authenticate the same run against the tracked source-bound coverage receipt and its derived endpoint. The README's static numeric badge is linked to that receipt and paired with the workflow-status badge; the Docs Pages job neither publishes nor authorizes coverage evidence. No generic alias or ordinary CI job silently selects this workflow or its coverage command.

Checkout preparation is deliberately narrower than a cleanup command. Git must identify the requested checkout, the canonical machine_bundles/arcane-os-machine-bundle directory must be real and neutral, and every exact legacy candidate must pass inspection before any candidate is removed. A tracked path, nonignored untracked path, link, junction, reparse point, unsupported entry, or ignored file outside the recognized generated directories rejects the migration and preserves the legacy directories for manual review. Near matches such as backup directories are not migration targets.

Application packaging

Command	Purpose	Result / output
npm run apps:list	Lists registered applications and versions.	Stable app inventory.
npm run apps:serve	Immediately acknowledges, runs one authoritative app discovery, reads the exhaustive 24-app local-test policy plus the small release manifests once, then starts one catalog listener and at most one sequentially created loopback listener per browser-approved package. Each served app receives a distinct origin; Settings, Terminal, native-only applications, and private-data-gated applications receive no listener. The command does not package, hash, sign, start Arcane OS/Core, or fabricate native APIs. Requested files stream on demand only when present in the immutable package inventory, while ARCANE_APP_RELEASE.json, unrelated files, directories, links, traversal, unexpected hosts, request bodies, and non-GET/HEAD methods remain unavailable.	Development-only catalog at http://127.0.0.1:4173/ by default, with up to 17 isolated ephemeral app origins. Ctrl+C owns and closes every listener. Run npm run demo:check -- <app-id> before serving a changed package; that selected command remains the verification owner and this server creates no replacement trust receipt.
npm run app:inspect -- <app-id>	Shows one app's package definition without building it.	Inspection record.
npm run app:package -- <app-id>	Creates one static/adapter application package.	App package under its configured distribution path.
npm run app:release -- <app-id>	Performs the app release workflow.	Verified versioned app release.
npm run app:check -- <app-id>	Verifies an existing app package.	Package-policy and integrity result.
npm run app:bump -- <app-id> <major|minor|patch|prerelease>	Changes an app's SemVer through the packager.	Updated app version after successful validation.
npm run machine:version -- [<major>.<minor>.<patch>]	With a version, updates the central machine manifest and synchronizes its required npm/README mirrors; without one, resynchronizes mirrors from the manifest. A matching changelog section must already exist.	Synchronized machine source metadata; generated runtime/platform files are refreshed by the normal machine build.
npm run machine:version:check	Verifies the required machine metadata mirrors agree with arcane-bundle.json without writing files.	Central-version synchronization result.
npm run test:app-packager	Runs focused app-packager tests.	Node test report.
npm run check:public-apps	Runs each public application's owned publication check.	Public application verification result.
npm run model:ensure -- [--model=<variant>] [--target=<target>] [--smoke]	Pulls each missing base once, creates or repairs the selected managed platform or application aliases serially, and optionally runs one bounded inference probe per alias. With no target it preserves the platform-only behavior. Application-specific targets and variants are documented by their owning package.	Verified local aliases; platform runs also maintain arcane:latest and the saved selection.
npm --prefix machine_bundles/arcane-os-machine-bundle run test:local-speech	Exercises the frontend speech API, Core validation, capability denial, and simulated Kokoro/Whisper responses.	Focused local-speech test report; no live inference.
npm --prefix machine_bundles/arcane-os-machine-bundle run verify:local-models:live	Creates or repairs the effective Arcane boot alias, then verifies representative package-policy aliases already present in the protected store. This can download a large Arcane base; use model:ensure for another declared variant. It does not define an application's renderer default.	Live representative model-lineage evidence.
npm --prefix machine_bundles/arcane-os-machine-bundle run verify:local-app-inference:live	Runs bounded representative prompts through rebuilt package Cores and their managed local models.	Live local-model inference evidence.
npm --prefix machine_bundles/arcane-os-machine-bundle run verify:local-speech:live	Synthesizes a fixed phrase through one package Core, converts it in memory to browser WebM, and transcribes it through another package Core.	Live loopback speech-bridge evidence without retaining audio.

model:ensure acknowledges the request before contacting Ollama, emits pull/create progress and a heartbeat during quiet network work, and stops with a nonzero exit on cancellation or verification failure. A cold --target=all --model=3b run has one invariant base download (about 2.1 GB), two identity-bound product creates, two lineage checks, one exact digest-bound arcane:latest selection check, and—only with --smoke—two short inference probes. The command uses concurrency one so the two products reuse the same downloaded base instead of multiplying download, memory, or disk work.

Standalone OS-target application builds

These root commands build one Shell-independent application while preserving its allowlisted shared Arcane runtime, app-scoped Core, window.Arcane bridge, capability policy, and platform host. The complete machine_bundles/arcane-os-machine-bundle/dist/targets/<app-id>/ directory is the output and deployment unit. All signing flavors replace that same canonical directory. These standalone root commands do not mutate the full machine distribution's dist/apps/ catalog; projection is an explicit lower-level machine-bundle concern.

Command	Purpose	Signing requirement	Result / output
npm run app:build:os -- --list	Lists application IDs accepted by the standalone builder.	None.	Registered application inventory.
node tools/build-os-app.mjs <app-id> --os <portable|windows> [--signing <mode>]	Direct system-tool form; use --list without an app or other options to list IDs.	Portable accepts no signing mode; Microsoft NT requires unsigned-local-test, development, or production.	The same canonical package as the npm interface.
npm run app:build:os -- <app-id> --os portable	Builds one deterministic host-neutral app package.	Not applicable; portable output has no native publisher claim.	Portable package at dist/targets/<app-id>/.
npm run app:build:os -- <app-id> --os windows --signing <unsigned-local-test|development|production>	Builds one Microsoft NT package with an explicit signing profile.	The selected explicit mode.	Native package at dist/targets/<app-id>/.
npm run app:build:portable -- <app-id>	Builds one explicit portable package without relying on the host OS default.	Not applicable.	Portable package at dist/targets/<app-id>/.
npm run app:build:windows:unsigned-local-test -- <app-id>	Builds one consistently unsigned, exact-inventory Microsoft NT package that launches directly as a local demo.	Explicit local-test build consent is compiled into the host; no separate launch argument is required.	Unsigned native package; local engineering only.
npm run app:build:windows:dev -- <app-id>	Builds one app with the current user's bootstrapped development signer.	npm run signing:bootstrap:dev:windows completed for this user.	Locally trusted development-signed native package.
npm run app:build:windows:signed -- <app-id>	Builds one app with the authorized production signer and timestamp service.	Production certificate/private key, independently supplied matching expected publisher, RFC 3161 endpoint, and SignTool.	Production-signed native package.

External SDK native development providers

The external Arcane SDK can select one application and its explicit dependency closure and delegate to Arcane's arcane-native-builder/1 providers. These are development-only providers: windows-x64 produces a real x64 EXE package; linux-x64 and linux-arm64 produce one architecture-bound DEB; and android-arm64 produces one development-signed, architecture-neutral APK with no native ABI payload. Desktop providers are unsigned-local-test; Android uses only the fixed arcane-android-development-v1 profile. They do not select production signing, mutate Arcane's canonical dist/ trees, install a desktop artifact, publish to an Android app store, or make a release claim. The Android provider does publish its development APK into the explicit external output.

From an external SDK project with arcane available through its npm dependency, the public command forms are:

npm exec -- arcane build --target windows-x64 --arcane-root <arcane-root>
npm exec -- arcane build --target linux-x64 --arcane-root <arcane-root>
npm exec -- arcane build --target linux-arm64 --arcane-root <arcane-root> --format deb --signing unsigned-local-test
npm exec -- arcane build --target android-arm64 --arcane-root <arcane-root> --format apk --signing development
npm exec -- arcane run --target windows-x64 --arcane-root <arcane-root>
npm exec -- arcane run --target linux-x64 --arcane-root <arcane-root>
npm exec -- arcane run --target linux-arm64 --arcane-root <arcane-root> --format deb --signing unsigned-local-test
npm exec -- arcane run --target android-arm64 --arcane-root <arcane-root> --format apk --signing development

The external-project default is build/<target> inside that project. An integrated Arcane-workspace invocation must instead name the selected app and an explicit output outside every Arcane workspace, toolchain, runtime, and admitted release root, for example:

npm exec -- arcane build --target windows-x64 --arcane-root <arcane-root> --workspace <arcane-root> --app <id> --output-root <external-directory>

Substitute the matching declared target for another provider. Do not point --output-root at the Arcane checkout or an installed Arcane tree. Linux ARM64 build and run require a native ARM64 Linux toolchain. Android build requires the prepared Android SDK/JDK/Gradle closure; run additionally requires exactly one connected physical or native ARM64 device and owns install, authenticated content-and-bridge readiness, cancellation, force-stop, and uninstall. Android AAB, release signing, store publishing, and update continuity remain deferred; Linux AppImage/RPM and production signing are not admitted by this contract.

After the arcane-os@dev package is published, a new external project may select a provider with npx arcane-os@dev new <id> --target <target>, where <target> is windows-x64, linux-x64, linux-arm64, or android-arm64. Until then, use the SDK source CLI or current local tarball form documented by the SDK; the registry scaffolding command is not yet an availability claim.

The cardinality is one target x one selected app closure. Portable admission, toolchain preparation, native assembly, and exact artifact verification each have one owner; there is no all-app, all-platform, or architecture loop. Invariant SDK/toolchain inputs are prepared once for the live toolchain receipt, while the selected app and declared dependency bytes remain identity-bound inputs. Cold-path bytes and elapsed time depend on that closure and the local toolchain and are reported through acknowledged phase/progress events and five-second heartbeats rather than a fixed estimate. Each provider admits only one operation at a time, owns cancellation and child failures, and returns a nonzero error instead of leaving an unobserved task.

Toolchain and artifact receipts are live, retained, same-provider-process authority. They bind canonical locations and filesystem/content identities, descriptor and inventory hashes, target/signing policy, toolchain identity, and generation. arcane run therefore performs build, verify, and launch in the same process; a separate build command followed by a later run command cannot reuse those receipts. On Linux, run extracts the retained verified DEB into a provider-owned temporary tree, authenticates that tree, launches the selected ArcaneAppHost, and removes the tree. It never invokes sudo, apt, dpkg -i, or a system installation.

For the Windows provider, explicit unsigned mode strips ambient certificate, publisher, signer-provider, SignTool, timestamp, Artifact Signing DLib/metadata/ account/profile, development-signer, and required-signed selectors before the child build. In particular, all ARCANE_SIGNING_* and ARCANE_ARTIFACT_SIGNING_* values plus ARCANE_EXPECTED_PUBLISHER_THUMBPRINT, ARCANE_SIGNTOOL_PATH, ARCANE_TIMESTAMP, ARCANE_TIMESTAMP_SERVER, ARCANE_DEVELOPMENT_SELF_SIGNED_ALLOWED, and ARCANE_REQUIRE_SIGNED_RELEASE are removed; the child receives only explicit ARCANE_SIGNING_MODE=unsigned-local-test and ARCANE_REQUIRE_SIGNED_RELEASE=0. Ambient production signing configuration cannot silently create signed executables carrying an unsigned-local-test label.

An unsigned target app outside the canonical installed tree may coexist with a signed installed publisher pin only when its host was compiled with both ARCANE_TARGET_APP and ARCANE_UNSIGNED_LOCAL_TEST. This exception is limited to that isolated, noninstalled development path. An administrator publisher policy still rejects it; unreadable registry policy or continuity state still fails closed; a canonical installed unsigned target still rejects; and a target without either compile-time symbol receives no bypass. Use the development- signed workflow when exercising the canonical installed path.

Launch repository-built standalone targets directly from machine_bundles/arcane-os-machine-bundle/dist/targets/<app-id>/ArcaneApp-<app-id>.exe; a full Shell redistribution is unnecessary for the first host-level test.

Microsoft NT native hosts use the internal https://os.arcane WebView2 virtual origin. Do not introduce a .local virtual-host mapping: Microsoft documents a navigation delay for that top-level domain. The current transition does not migrate https://arcane.local storage. Test https://os.arcane as a separate origin, preserve the legacy profile untouched, and record migration as deferred. See application-data-isolation.md before testing against an existing profile or shipping the changed host.

The private developer checkout contains Standalone OS-target application builds for package composition, application examples, launch commands, projection recovery, platform status, and the fail-closed, certificate-gated production contract. Public readers can use Application packaging and the repository-access boundary.

Microsoft NT development and signing

Command	Purpose	Signing requirement	Result / output
npm run signing:bootstrap:dev:windows	Creates/reuses and trusts the current user's non-exportable Arcane development certificate. Microsoft NT may request one-time confirmation before trusting the self-signed certificate.	None; creates development identity only.	Current-user development certificate and trust.
npm run build:dev:windows	Builds the complete Microsoft NT distribution with the development certificate.	Development bootstrap.	Development-signed dist/nt.
npm run build:dev:apps:windows	Builds all Microsoft NT apps with the development certificate.	Development bootstrap.	Development-signed app executables.
npm run build:dev:app:windows -- -AppId <app-id>	Builds one Microsoft NT app with the development certificate.	Development bootstrap.	One development-signed app executable.
npm run signing:preflight:windows	Validates the selected certificate-store or Azure Artifact Signing provider, public publisher identity, timestamp, and signing tools without building the package. Artifact Signing performs one disposable live signing probe.	Authorized production signing access.	Production signing readiness result and exact active signer thumbprint.
npm run build:signed:windows	Builds the complete production Microsoft NT distribution.	Either a matching certificate-store signer/publisher pair or an authorized Artifact Signing Public Trust profile, plus SignTool and RFC 3161 timestamping.	Production-signed dist/nt.
npm run build:deployable:signed:windows	Builds, signs, verifies, archives, extracts, and re-verifies the complete Microsoft NT distribution while the live signer pin remains in scope.	Same production signing access as build:signed:windows.	Arcane-OS-<version>-Windows-x64-PRODUCTION-SIGNED.zip plus inventory and SHA-256 sidecars under the bundle's dist/deployable/windows-production-signed/.
npm run package:deployable:signed:windows	Packages an already-built, current production-signed dist/nt; never signs or repairs it.	ARCANE_EXPECTED_PUBLISHER_THUMBPRINT for the already-built release.	Verified deployable ZIP and sidecars.
npm run verify:deployable:signed:windows	Extracts and independently re-verifies the default deployable ZIP, exact inventory, hashes, every executable signature, and installer entry point.	Matching expected publisher thumbprint.	Verification result; no package mutation.
npm run build:signed:apps:windows	Builds all production-signed Microsoft NT apps.	Production signing material.	Production-signed app executables.
npm run build:signed:app:windows -- -AppId <app-id>	Builds one production-signed Microsoft NT app.	Production signing material.	One production-signed app executable.

Development setup never creates, reads, or persists production signing material. Production commands complete signer, expected-publisher, timestamp, and tool preflight before starting a package build; without that trusted identity, they create no production artifact.

For Azure Artifact Signing, set ARCANE_SIGNING_PROVIDER=artifact-signing, ARCANE_ARTIFACT_SIGNING_DLIB_PATH, and ARCANE_ARTIFACT_SIGNING_METADATA_PATH. The metadata must be a regular UTF-8 JSON file outside the repository containing only the regional HTTPS endpoint, account name, certificate-profile name, and optional non-secret correlation/credential-exclusion fields. AccessToken and other credential-bearing or unknown fields are rejected. Authenticate outside the repository (for this workstation, az login with an Azure-CLI-only credential selection) and keep tokens out of files and command arguments. The wrapper snapshots and locks the validated metadata, probes the live Public Trust signer, then binds that exact leaf to the build.

Artifact Signing leaf certificates rotate frequently. The current runtime pins the exact leaf, so a later build issued under a different leaf needs Arcane's administrator-approved predecessor rotation policy. The durable Artifact Signing subscriber identity EKU is verified and reported but is not yet a runtime replacement for leaf continuity.

The older build:dev:app:windows and build:signed:app:windows wrappers remain supported lower-level signing entries. Prefer the app:build:* root commands above for ordinary standalone builds because they make OS and signing selection explicit. An explicit production wrapper rejects a conflicting ambient development signing mode.

Machine-bundle commands

Install both lockfiles first with root npm ci and machine-bundle npm ci, then run these from machine_bundles/arcane-os-machine-bundle, or add npm --prefix machine_bundles/arcane-os-machine-bundle run before the script name. Managed machine JavaScript tests join the repository-wide shared vanilla-test 2.1.0 adapter lifecycles and intentionally use the root-pinned c8 11.0.0 and DOM harness dependencies. Node remains their test orchestrator.

Script	Purpose	Result / output
prepare:checkout	Machine-directory alias of the root machine:checkout:prepare command.	Prepared neutral checkout or a fail-closed explanation of preserved user work.
version:sync -- [<major>.<minor>.<patch>]	Machine-directory form of the root machine:version command.	Metadata synchronized from arcane-bundle.json.
version:check	Checks machine version mirrors without writing them.	Central-version synchronization result.
generate:method-policies	Generates host method-policy artifacts from the canonical application and capability manifests.	Synchronized Core and Android policy sources.
build	Prepares the upgraded checkout, then generates the core runtime from its canonical template.	runtime/arcane-core.cjs from the permanent neutral source directory.
verify	Verifies runtime, API source, directory selection, and Microsoft NT host source contracts.	Verification report.
smoke	Builds current Core and selects the four canonical public API, Shell UI, Core RPC, and release-integrity smoke cases.	Numeric smoke report with cleanup and budget status.
test:os:smoke	Builds current Core and runs the canonical four-case smoke selector.	Numeric smoke report with cleanup and budget status.
test:os:ui	Runs all nine canonical Shell and Provisioner cases against production HTML and complete inline controllers in the shared DOM harness.	Numeric UI-integration report and cleanup status.
test:os:controller-ui	Runs the same canonical controller/UI profile directly without adding another implementation.	Numeric UI profile report and cleanup status.
test:os:system:portable	Builds current Core, then runs all three canonical portable system cases.	Numeric portable-system report and cleanup status.
test:os:system:portable:built	Runs the three portable system cases against a Core already built by the owning command graph.	Numeric portable-system report; internal exactly-once composition seam.
test:os:portable-system	Builds the machine bundle once, then delegates to the built portable-system seam.	Built portable-system report and cleanup status.
test:os:portable-system:built	Runs the portable-system profile against the already generated machine Core.	Numeric portable-system report; internal exactly-once composition seam.
test:legacy:full	Runs the 19 remaining unique machine compatibility checks, excluding cases with canonical managed owners.	Numeric compatibility report and cleanup proof.
test:app-packager	Runs the three machine app catalog and packager test files under a bounded parent supervisor.	Node test report plus verified process-tree and nonce-output cleanup.
test:linux-app-host	Tests the shared Linux application host, frame-aware WebKit bridge, navigation containment, and extension integrity contracts.	Focused Linux host contract report.
test:local-speech	Tests the bounded native local speech bridge, capability policy, simulated Core speech methods, and denial behavior.	Node test report.
test:content-binding	Tests release bindings, signing, recovery, and worker claims.	Node test report.
test:archive:windows:production-signed	Tests the production-signed Windows archive contract without creating production output.	Focused archive-contract result.
test:linux-host-release-claims	Compiles the GTK Linux host probe and proves hostile ambient release claims are stripped unless exact unsigned-local consent is present.	Compiled Linux host claim-isolation result.
check	Runs the portable build, verification, complete managed UI and portable-system sets, 19 remaining unique compatibility checks, packager tests, and portable app builds. It intentionally does not rerun the four-case smoke subset.	Complete portable machine gate.
check:windows	Runs Microsoft NT tests, an unsigned-local-test distribution build, and final verification.	Complete Microsoft NT machine gate.
check:windows:fast	Runs test:windows:iteration:fast and build:windows:iteration:fast; it intentionally omits the full Microsoft NT test and release gate.	Fast local dist/nt-iteration build.
prepush	Runs both machine check gates.	Full machine pre-push report.
dev:provisioner	Serves the provisioner with the development HTTP bridge.	Local provisioner development host.
dev:shell	Serves the shell with the development HTTP bridge.	Local shell development host.
build:app -- --list	Lists registered standalone application IDs.	Stable application inventory.
build:app -- --app=<app-id> --platform=portable	Builds one explicit portable native-capable app.	Portable app package.
build:app:windows -- --app=<app-id>	Builds one explicitly labeled unsigned-local-test Microsoft NT app and publishes its full-machine catalog projection.	Directly launchable local-test target plus verified dist/apps/ projection.
build:app:windows -- --app=<app-id> --standalone-only	Builds only the canonical unsigned-local-test Shell-independent target and leaves the full-machine catalog untouched.	Directly launchable local-test target directory.
build:app:windows:unsigned-local-test -- --app=<app-id>	Builds one explicitly unsigned local-test Microsoft NT app.	Complete labeled unsigned test directory.
build:app:windows:signed-policy -- --app=<app-id>	Internal adapter used only after a development or production signed wrapper establishes an explicit signed policy.	Refuses an unprofiled direct invocation; otherwise one signed app target.
build:apps:portable	Builds every registered portable app.	Portable app packages.
build:apps	Alias of build:apps:portable.	Portable app packages.
build:apps:linux:portable	Builds every registered app into the deterministic Linux portable-source staging projection.	22 packages under dist/targets/.linux-portable.
build:apps:linux:projection	Verifies the Linux portable-source packages and publishes the canonical shared-host catalog projection.	22 manifest-bound packages and catalog.json under dist/linux-apps.
build:apps:windows	Builds every Microsoft NT app as explicitly labeled unsigned-local-test output.	Directly launchable local-test app executables.
build:apps:windows:unsigned-local-test	Builds all explicitly unsigned local-test Microsoft NT apps.	Labeled unsigned test executables.
build:apps:windows:signed-policy	Internal adapter used only after a development or production signed wrapper establishes an explicit signed policy.	Refuses an unprofiled direct invocation; otherwise signed app executables.
build:distribution:windows	Builds the explicitly labeled unsigned-local-test Microsoft NT distribution.	Directly launchable local-test dist/nt; never production output.
build:win	Alias of build:distribution:windows.	Directly launchable local-test dist/nt; never production output.
build:distribution:windows:unsigned-local-test	Builds the explicitly labeled unsigned Microsoft NT distribution.	Local-test dist/nt.
build:distribution:windows:signed-policy	Internal complete-distribution adapter selected only by a preflighted development or production signed wrapper. During transactional publication, an existing generated distribution is authenticated against its own release version and signing policy before it may be retained as rollback for the verified current stage.	Signed dist/nt under the wrapper's explicit mode.
build:windows:iteration	Rebuilds the Microsoft NT iteration distribution without production signing, using short locked same-parent stage and backup paths so admitted app paths remain inside the supported Windows PowerShell path budget.	dist/nt-iteration.
build:windows:iteration:fast	Skips outer release-manifest hashes and runtime smoke programs but retains the SHA-256 machine manifest required by the native host; it reuses the same bounded stage and retargets only its copied app-catalog signing metadata for the unsigned iteration host; use only for local engineering.	Directly launchable dist/nt-iteration.
test:windows:iteration:fast	Runs the focused source contract and one-way staged-catalog regression for the isolated fast iteration path; it does not hash a release tree.	Fast iteration contract result.
build:core:win	Packages the generated Node core as a Microsoft NT executable.	dist/ArcaneCore.exe.
build:core:linux	Packages the generated Node core as a Linux executable.	dist/ArcaneCore.
build:linux	Alias of build:distribution:linux:unsigned-local-test.	Exact-inventory dist/linux artifacts; not a publisher-signed production release.
build:distribution:linux:unsigned-local-test	Builds Core, Shell, Provisioner, the shared WebKitGTK AppHost, and the exact 22-app projection only after exact unsigned-local intent is supplied to the low-level publisher.	Explicitly labeled, exact-inventory unsigned-local-test dist/linux.
./build-linux.sh [--offline]	Outer Linux build launcher. It prepares the checkout, verifies public lock sources, recreates the root and machine-bundle dependency trees with exactly one npm ci each, then runs the Linux build once. The optional explicit offline mode adds --offline to both installs and fails if the verified local cache is incomplete; an online failure never silently selects it.	Fresh dependencies and the explicitly labeled unsigned-local-test dist/linux tree.
verify:apps	Verifies built application packages.	App verification result.
verify:app-catalog	Verifies the generated application catalog.	Catalog verification result.
verify:winhost:build	Verifies the Microsoft NT host, DPI, iteration, and Ollama service source contracts required before a build, including dependency-complete execution of the extracted Core error-normalization contract, without entering test-only SDK or service lifecycle suites.	Focused Microsoft NT build-input verification result.
verify:winhost	Verifies Microsoft NT host source contracts, exact selective WebView2 SDK extraction, artifact-lock cleanup, retained-file reuse, direct published-app admission, and the 22-app/one-shared-host work graph.	Focused native-host, admission, and build-input verification result.
verify:local-models:live	Verifies and repairs the managed Ollama product-model catalog against the live local service.	Live model lineage and readiness report.
verify:local-app-inference:live	Exercises representative package-bound inference through native Core executables and managed local models.	Live packaged-app inference report.
verify:local-speech:live	Exercises native Core synthesis and transcription through the loopback local speech runtime.	Live TTS/STT bridge report.
verify:distribution:windows	Verifies a signed Microsoft NT distribution and its security binding.	Signed-release verification result.
verify:distribution:windows:unsigned-local-test	Verifies the unsigned-local-test distribution and binding.	Local-test verification result.
package:windows:production-signed	Packages an already verified production-signed Windows distribution through the explicit archive boundary.	Deterministic ZIP transport, canonical inventory, and SHA-256 sidecar under dist/deployable/windows-production-signed/.
verify:archive:windows:production-signed	Verifies the sidecars, extracts the ZIP, rechecks exact content, and authenticates every physical executable against one non-self-signed publisher and timestamp.	Archive verification result; no mutation.
test:archive:windows:production-signed	Exercises stale, unsigned, self-signed, substituted-signer, tamper, deterministic-byte, and extraction-verification archive contracts.	Focused Node test report.
verify:distribution:linux	Alias of verify:distribution:linux:unsigned-local-test.	Unsigned controlled-acceptance verification result for dist/linux.
verify:distribution:linux:unsigned-local-test	Verifies the local Linux distribution's exact schema-2 inventory without claiming publisher trust.	Explicit unsigned-local-test verification result for dist/linux.
prepare:android	Acknowledges the Android request, then performs a bounded read-only preflight for Node.js 22+, Java 17 from explicit JAVA_HOME or an installed Arcane-managed fallback, Android SDK API 35 and Build Tools 35.0.0 from explicit variables or the trusted user-local fallback, the exact schema-1 22-app registry, the pinned Gradle 8.9 URL/SHA/URL-validation contract, and non-overlapping link-free Android-private paths. It performs no downloads, installations, global environment changes, builds, model pulls, or Arcane output writes.	Prerequisite report naming the selected Java and SDK sources, bounded trust probes, explicit path-comparison count, elapsed time, and zero network bytes; fail-closed guidance when a requirement is missing.
build:distribution:android:debug-local-test	Runs the owned Android preflight, then builds the HOME-eligible Launcher and one independently installable debug APK for each of the 22 registered applications. Android assets, projections, Gradle state, staging, and final output remain in Android-private ignored paths.	Exact 23-APK local-test distribution and SHA-256 manifest at dist/android; Microsoft NT output and shared Core output remain untouched.
verify:distribution:android:debug-local-test	Independently binds the generated index and Android directory to the canonical 22-app registry, then verifies the exact 23-APK manifest inventory, sizes, and hashes.	Android local-test verification result; no publisher-signing claim.
check:android:debug-local-test	Runs the Android build and final distribution verifier as the complete focused development gate. The build owns preflight, so a separate unchanged prepare:android immediately beforehand is unnecessary.	Built and verified 23-APK debug-local-test distribution, or a nonzero failure with owned error reporting.
verify:winhost	Verifies Microsoft NT host, DPI, iteration, Ollama service, direct published-app admission, retained policy, and shared-host work-amplification contracts.	Microsoft NT host source and focused contract report.
verify:windispatch	Verifies native Microsoft NT host dispatch against built binaries.	Dispatch verification result.
verify:winsecurity	Verifies signatures and release binding for signed output.	Signed security result.
verify:winsecurity:unsigned-local-test	Verifies binding without requiring signatures.	Unsigned local-test security result.
smoke:windows:release-directory-locks	Tests recovery from locked Microsoft NT release directories.	PowerShell smoke result.
smoke:windows:installed-apps	Tests behavior against installed Microsoft NT apps.	Node smoke result.
smoke:windows:pipe-guard	Runs the explicit behavioral PipeGuard smoke against the already published Microsoft NT artifact as part of check:windows; setup and build commands do not invoke it.	Focused guard, attacker, and legitimate-client process result.
test:windows:ollama-service:admin -- -CompiledServiceHost <absolute-path> -RealOllamaExecutable <absolute-path>	Runs the real Microsoft NT ArcaneOllama service acceptance harness with caller-supplied service-host and Ollama binaries. Requires an already elevated Administrator PowerShell on a disposable host.	Copies and SHA-256-verifies the supplied binaries, reconfigures and starts ArcaneOllama, proves final locale-invariant numeric Running state and a nonempty scalar version from http://127.0.0.1:11434/api/version within 30 seconds, then writes C:\ProgramData\Arcane OS\cache\ollama\real-service-test.json.

The Android commands are development-only and do not install or control Android Linux Terminal, start Ollama, or acquire models. Their private paths, 23-APK work-amplification record, and temporary user-managed Android Linux Terminal/Ollama boundary are documented in the Android multi-package distribution record.

test:windows:ollama-service:admin is a state-changing acceptance command, not a routine developer check. It can stop and reconfigure an existing ArcaneOllama service, replace C:\Program Files\Ollama\ArcaneOllamaService.exe and ollama.exe, replace the runtime ACL, set service environment registry values, and leave the service/runtime in place after either success or failure so first-failure evidence is preserved. Each supplied binary at a different path is copied unconditionally and then checked against the stable source size and SHA-256; an equal-length installed file is never treated as proof of equality. An exact same-path input is hashed and verified without copying over itself. The result records source and installed paths, sizes, and SHA-256 values for both binaries. Run it only in an already elevated PowerShell on a disposable Microsoft NT acceptance machine. The command fails closed when Administrator approval is absent, either input is missing, a supplied or installed path or any existing ancestor is a reparse point, any retained runtime file has more than one hard link, the source changes during installation, or installed hash proof fails. Before service start it applies and proves the managed ACL on the runtime, both executables, and model root, then rechecks executable link counts and SHA-256 values. Result persistence uses a same-directory temporary file and atomic replacement where available; a persistence error is reported separately and never replaces an original service/configuration failure, while an otherwise successful run fails acceptance if its required record cannot be saved.

The command accepts whatever binaries the caller names; it does not build, sign, or verify their publisher. An explicitly unsigned-local-test distribution may be used for local engineering evidence only. Production acceptance must use the exact production-signed candidate and its authorized Ollama input, and must separately complete the signed distribution verification. A passing unsigned-local run is not production-signing, release-candidate, or risk-acceptance evidence.

Native launchers

Command	Purpose
build-windows.bat	Compatibility entry point for the Microsoft NT development build. It delegates to the repository-root setup-developer.bat, so checkout preparation, exact asset hydration, public locked dependencies, development signing, compilation, and the successful Provisioner launch use one supported interactive sequence. It never selects the production-policy build.
tools/build-linux-webkitgtk.sh --unsigned-local-test	Low-level Linux publisher used by build:distribution:linux:unsigned-local-test; it requires GTK 4, WebKitGTK 6.0, and JSON-GLib 1.0 development metadata and refuses calls without that exact flavor argument.
start-provisioner.bat / start-provisioner.sh	Starts the native provisioner. On Microsoft NT, missing checkout output automatically invokes the repository-root developer setup exactly once, then the original launcher opens the exact current Provisioner. Nested launch ownership prevents duplicate windows, and setup failures keep the log path visible.
start-provisioner-debug.bat	Starts the Microsoft NT provisioner with debugging enabled.
start-shell.bat / start-shell.sh	Opens the native Arcane Shell inside the current Microsoft NT or Linux desktop session for development, demonstrations, and screenshots; no host logout or login is required.
& 'C:\Program Files\Arcane OS\bin\ArcaneUninstaller.exe'	Opens the globally installed Microsoft NT uninstaller. The executable requests one UAC elevation, performs the read-only preflight, displays scope and warnings, and requires the exact typed confirmation. A Provisioner started from a development checkout delegates to this installed executable rather than running checkout-local uninstall code. Uninstall intentionally has no release-integrity or signing-mode admission flag; Windows still displays the executable's actual signature state in its normal trust UI.

Every interactive Microsoft NT first-run or missing-build path converges on repository-root setup-developer.bat; no launcher owns a second hydration, dependency, signing, or build sequence. The clearly named rebuild launcher owns exactly one fast build and never retries it through setup after failure. A launcher never falls through to stale output, and a failed setup or build keeps the exact error visible when opened by double-clicking.

Maintenance rule

Follow the repository-only Developer Reference Maintenance SOP; the repository-access guide explains that boundary. Every new or changed public system tool, launcher, root npm command, or machine-bundle npm command must update this table in the same change.