sonic-screwdriver

Sonic Screwdriver is the deployment, installation, and recovery layer of the public Sonic/uDOS architecture.

It is responsible for:

• hardware-aware planning
• USB and image deployment
• manifest generation and verification
• device catalog and compatibility guidance
• portable provisioning and rescue workflows

It is not the canonical owner of the uHOME runtime contract.

Repo Family Boundary

The current repo split is:

• uDOS-core = deterministic runtime contracts and execution semantics
• uDOS-shell = interactive shell and workspace interaction surfaces
• uDOS-wizard = provider, MCP, assist, and remote publishing adapters
• sonic-screwdriver = deployment, provisioning, hardware bootstrap
• uDOS-ubuntu = always-on command-centre runtime
• uHOME-server = downstream uHOME service stream

For family runtime contracts, the source of truth is the sibling uDOS-ubuntu repository. For uHOME-specific downstream services, use the uHOME-server repository.

uDOS family install contract

Sonic is the first-entry deployment lane for the public uDOS shape. Canonical install order, ~/.udos/ path rules, Docker boundary, and Sonic/Ventoy split are specified in the uDOS-dev repository: docs/foundation-distribution.md (check out the uDOS-family tree per its CURSOR_HANDOVER_PLAN.md). Lane-2 automated verification from Ubuntu: uDOS-ubuntu/scripts/foundation-distribution-workspace-proof.sh.

What Sonic Owns

Sonic owns the deployment lane that takes a reviewed profile and applies it to real hardware:

take profile -> generate manifest -> verify -> stage payloads -> apply to device

Current active surfaces in this repo:

• USB plan and run CLI
• standalone HTTP API
• MCP facade over the same service layer
• browser UI for planning and catalog inspection
• device catalog and manifest validation
• explicit live/install/recovery product docs and demo surfaces
• Sonic-owned CLI/TUI/ThinUI deployment surfaces

What Sonic Does Not Own

Sonic does not own:

• the long-running uDOS command centre
• the family command-centre runtime
• uHOME bundle/preflight/install-plan source of truth
• Wizard-managed beacon, Home Assistant, or network control surfaces
• canonical vault truth or always-on runtime scheduling

This repo no longer carries local uHOME bundle contract code. Use the sibling uHOME-server repo directly for uHOME bundle, preflight, and install-plan work.

First-Run Preflight (Any OS)

Operator experience (simpler path, planned): see docs/operator-first-run-plan.md (one-command setup + launcher + dependency checks + startup health).

Run the repo preflight entrypoint first (deeper validation; developers / CI):

bash scripts/first-run-preflight.sh

This command performs four checks:

• repo validation (scripts/run-sonic-checks.sh)
• v2 canonical root structure check
• quickstart probe
  • Linux: CLI sonic plan --dry-run
  • macOS/Windows: API health probe (/api/sonic/health)
• cross-repo uHOME contract conformance probe (when sibling repos exist)
  • scripts/smoke/uhome-contract-conformance.sh

Platform boundary:

• macOS supports repo validation, API/MCP, UI, catalog work, and dry-run planning
• Linux is required for real partitioning, formatting, mounting, and device writes
• Windows remains unsupported for Sonic build/apply operations

Starter CLI

Sonic now starts from the CLI surface first, then hands off to the browser GUI.

Run the installable starter CLI with:

sonic

Starter commands:

• help
• commands
• start
• status
• test
• doctor
• exit

GUI handoff:

sonic start

That bootstraps the local API and browser UI, then opens the Sonic surface on http://127.0.0.1:5173.

One-command bootstrap launcher (installs deps on first run, then starts API + UI):

./sonic-open
# or: bash scripts/sonic-open.sh

macOS (Finder): double-click scripts/sonic-open.command (or the legacy scripts/first-run-launch.command, which calls the same flow).

Use bash scripts/sonic-open.sh --repair to force reinstall of pip/npm deps. Use --no-open to skip opening a browser.

Short operator-only walkthrough: docs/operator-quickstart.md.

Quick Start (Linux)

After preflight passes, run the Linux deployment quickstart:

If you are on macOS, you can still validate the non-destructive path first:

sonic plan \
  --usb-device /dev/sdz \
  --dry-run \
  --out /tmp/sonic-manifest.json

bash scripts/sonic-stick.sh \
  --manifest /tmp/sonic-manifest.json \
  --dry-run

Those commands validate planning, manifest generation, layout synthesis, and payload-stage wiring without touching a real block device. Real apply remains Linux-only.

Install editable CLI entrypoints:

bash installers/setup/install-sonic-editable.sh

This repo currently supports editable installation from source, not a self-contained wheel. That keeps the CLI aligned to the tracked repo assets in config/, datasets/, distribution/, and scripts/.

Generate a plan:

sonic plan \
  --usb-device /dev/sdb \
  --out memory/sonic/sonic-manifest.json

Run a dry-run first:

sonic plan \
  --usb-device /dev/sdb \
  --dry-run \
  --out memory/sonic/sonic-manifest.json

bash scripts/sonic-stick.sh \
  --manifest memory/sonic/sonic-manifest.json \
  --dry-run

Apply the manifest:

bash scripts/sonic-stick.sh --manifest memory/sonic/sonic-manifest.json

Serve the local API directly:

sonic-api

Serve the MCP facade directly:

sonic-mcp

Run the Linux smoke workflow:

bash scripts/smoke/linux-runtime-smoke.sh

For a real Linux box/runbook, use docs/v1/howto/linux-runner-validation.md. For a one-command runner on Ubuntu/Alpine, use bash scripts/linux-runner-validation.sh.

Ubuntu And Ventoy Integration (v2.0.6 Round B)

Sonic now exposes an explicit integration lane for the uDOS-ubuntu profile and sonic-ventoy boot templates.

Initialize a stick workspace from sonic-ventoy templates:

sonic init \
  --stick-root memory/sonic/artifacts/sonic-stick \
  --theme modern \
  --profile udos-ubuntu

Register image metadata and checksum assumptions from the profile manifest:

sonic add udos-ubuntu \
  --stick-root memory/sonic/artifacts/sonic-stick \
  --image-name udos-ubuntu-22.04.iso \
  --checksum <sha256>

Refresh boot templates and profile metadata without deleting user images/config:

sonic update \
  --stick-root memory/sonic/artifacts/sonic-stick \
  --profile udos-ubuntu

Switch the active boot theme:

sonic theme retro --stick-root memory/sonic/artifacts/sonic-stick

OS boundary:

• sonic init is Linux-only for the CLI path, but the underlying file integration helpers can be validated on macOS during development
• sonic add, sonic update, and sonic theme are Linux/macOS maintenance commands
• Windows remains unsupported for Sonic build operations

Run the Ubuntu/Ventoy integration smoke workflow (Linux, sibling repos required):

bash scripts/smoke/ubuntu-ventoy-integration-smoke.sh

Learning Surfaces

There are now three ways to enter this repo:

• student-facing wiki: wiki/Home.md
• Sonic course: courses/README.md
• reference docs: docs/README.md

Use the wiki for orientation, the Sonic course for the deployment lane, and docs/ for implementation details and active contracts.

Activation

The v2 repo activation path is documented in docs/activation.md.

Run the current repo validation entrypoint with:

scripts/run-sonic-checks.sh

Run the current ThinUI NES launcher demo with:

bash scripts/demo-thinui-launch.sh

Run the current live/install/recovery product demo with:

bash scripts/demo-live-install-recovery.sh

For broader platform learning, use the wider uDOS v2 family docs instead of duplicating the same pathway structure in Sonic. Start with uDOS-docs, uDOS-core, and uDOS-wizard.

Public docs entry points:

• repo: https://github.com/fredporter/uDOS-docs/
• Pages index: https://fredporter.github.io/uDOS-docs/

If you prefer repo-local execution without installing entrypoints, the direct CLI path remains python3 apps/sonic-cli/cli.py, and the starter launch path is python3 apps/sonic-cli/cli.py start.

Current Runtime Layout

The active runtime now aligns to the public repo structure:

• apps/sonic-cli/ = operator CLI
• apps/sonic-ui/ = browser UI
• services/ = planner, manifest, API, MCP, and runtime service layer
• installers/setup/ = editable install helpers
• modules/ = install-domain architecture surfaces
• vault/ = tracked templates, manifests, and deployment notes for learners
• scripts/ = Linux-side execution steps
• config/ = layout and manifest defaults
• distribution/ = tracked packaging descriptors and launch assets
• memory/sonic/ = local runtime state and generated artifacts
• datasets/ = device catalog sources
• tests/ = verification coverage

The earlier structure review is kept as a baseline record in docs/v1/sonic-structure-assessment-2026-03-08.md.

Current Default Deployment Story

The default standalone profile currently produces a dual-boot disk with:

• a Linux-side uHOME surface and handoff path
• a Windows 10 gaming surface
• controller-first launch metadata for both sides

That is one active deployment profile, not the whole identity of the repo. The broader Sonic role is deployment infrastructure and portable provisioning.

Key Docs

• docs index: docs/README.md
• v2 architecture: docs/architecture.md
• v2 boundary: docs/boundary.md
• live/install/recovery product: docs/LIVE_INSTALL_RECOVERY_PRODUCT.md
• Ubuntu/Ventoy/Sonic handoff: docs/UBUNTU_VENTOY_SONIC_HANDOFF.md
• release policy: docs/release-policy.md
• archived provisioning contract: docs/v1/specs/sonic-screwdriver.md
• archived integration boundary: docs/v1/integration-spec.md
• archived structure assessment: docs/v1/sonic-structure-assessment-2026-03-08.md
• setup helper: installers/setup/README.md

Project Governance

• license: LICENSE
• legal summary: LEGAL.md
• contributing: CONTRIBUTING.md
• contributors: CONTRIBUTORS.md
• conduct: CODE_OF_CONDUCT.md

Development Lane

Sonic uses a local @dev / binder-style development lane for in-progress work, but this repository remains the curated public output surface. Local binder state, scratch material, and review staging are ignored by default so dev-mode work does not leak into tracked repo content.

OS Support

• Supported: Linux
• Unsupported for build operations: macOS, Windows

Safety

• destructive steps require explicit execution
• always verify the target block device
• run dry-run before any real apply
• treat memory/sonic/ as local runtime state, not canonical tracked source