@zerwiz/ymir 0.1.3 → 0.1.5

package/docs/ymir-rut.md

@@ -0,0 +1,260 @@
+# YMIR RUT — System Specification v2.6
+
+> **Status:** ADOPTED AS THE **TARGET** ARCHITECTURE (ENTRY 2026-09-11-009/010).
+> The v2.6 spec below is the long-term zenith (Rust, NATS, Envoy, PostgreSQL,
+> libgit2, Cgroups v2). The **current** implementation deliberately uses the
+> agent-proficient stack — **TypeScript + Python + React + Vue** — with a
+> one-for-one crumb trail to Rut so the eventual port is a *re-floor*, not a
+> redesign. See the **Reconciliation** appendix at the end of this document.
+
+---
+
+# PART 1 — System Structure & Repository Layout Specification
+
+## Monorepo & Daemon Module Architecture v2.6
+
+### 1. Monorepo Workspace Topology
+
+`Ymir Rut` is structured as an enterprise-grade Cargo workspace combined with isolated worker runtimes, ensuring clean boundaries between control plane daemons, tenant sandboxes, and agent harnesses. *(Today: an npm/pnpm workspace + Python services holding the same boundaries.)*
+
+```
+ymir-rut/
+├── Cargo.toml                    # Workspace manifest (Rust Edition 2024)   → [today: package.json / pyproject.toml]
+├── proto/                        # Shared Protocol Buffers & gRPC definitions → [today: JSON-RPC/.agents/bus schemas]
+├── crates/
+│   ├── bifrost/                  # [Ingress Gateway] Envoy/Reverse Proxy & TLS → [today: TS gateway service]
+│   ├── hlidskjalf/               # [Control Plane] Telemetry, auth & dashboards → [today: React/Vue portal]
+│   ├── svartalfaheim/            # [Tenant Realms] Namespace & credential stores → [today: TS tenant daemon]
+│   ├── ratatoskr/                # [Event Bus] NATS JetStream broker integration → [today: TS A2A backbone + Redis]
+│   └── yggdrasil/                # [Worktree Manager] libgit2 .treehouses engine → [today: TS worktree manager]
+├── runtime/
+│   ├── utgard/                   # [Sandboxes] Rootless Docker & cgroups v2 configs → [today: Python/Docker sandbox]
+│   └── brokk/                    # [Worker Cluster] Autonomous agent harness → [today: Python/TS agent harness]
+└── configs/                      # Cluster deployment helm charts & compose files → [today: docker-compose.yml]
+```
+
+### 2. Core Workspace Crates & Daemons
+
+**A. Bifrost (`crates/bifrost/`)**
+
+Role: Edge ingress gateway handling TLS termination, rate-limiting, and tenant route redirection.
+
+Key Modules:
+- `ingress::proxy`: Reverse proxy request forwarder.
+- `auth::verifier`: Zero-trust token validation against Svartalfaheim stores.
+
+**B. Hlidskjalf (`crates/hlidskjalf/`)**
+
+Role: Central observability and dashboard metrics collector.
+
+Key Modules:
+- `telemetry::emitter`: Broadcasts operational metrics (98.4% traceability index tracking).
+- `dashboard::api`: REST and GraphQL endpoints for cluster monitoring.
+
+**C. Svartalfaheim (`crates/svartalfaheim/`)**
+
+Role: Multi-tenant realm isolation engine.
+
+Key Modules:
+- `realm::namespace`: Ephemeral memory and environment variable scoping per tenant ID.
+- `vault::keys`: Secure credential store with zero memory bleed guarantees.
+
+**D. Ratatoskr (`crates/ratatoskr/`)**
+
+Role: Asynchronous event bus and message broker.
+
+Key Modules:
+- `bus::nats`: JetStream publisher/subscriber client wrapper.
+- `dispatch::router`: Inter-daemon event dispatch and trace logging.
+
+**E. Yggdrasil (`crates/yggdrasil/`)**
+
+Role: Parallel Git worktree manager (.treehouses).
+
+Key Modules:
+- `worktree::libgit2`: Manages isolated concurrent branches for agent code mutations without collision.
+- `snapshot::diff`: Rapid staging and commit verification.
+
+### 3. Worker & Runtime Subsystems
+
+**A. Utgard (`runtime/utgard/`)**
+
+Role: Ephemeral sandbox container runtime.
+
+Specification: Configures rootless Docker engines, enforces Cgroups v2 limits (128GB memory ceiling), and applies strict seccomp syscall filters.
+
+**B. Brokk (`runtime/brokk/`)**
+
+Role: Autonomous agent execution worker cluster.
+
+Specification: Python 3.12+ and Node.js 22 runtimes providing tool execution loops, prompt pipelines, and structured code transformation harnesses. *(This crate is the one Rut spec that is already current-stack — Python 3.12+ and Node/TypeScript.)*
+
+### 4. Inter-Module IPC & Protocol Definitions
+
+All inter-daemon communication relies on strongly typed Protocol Buffers (`proto/v2/`) compiled via tonic (gRPC) and JSON-RPC over Unix domain sockets for zero-latency local worker communication. *(Today: JSON-RPC 2.0 / A2A 1.0 over HTTP(S) + Unix-domain sockets between local daemons.)*
+
+---
+
+# PART 2 — Technical Architecture & Stack Requirements
+
+## System Specification v2.6
+
+### 1. System Topology & Component Architecture
+
+`Ymir Rut` is structured around a decoupled, micro-daemon architecture designed for high-concurrency agent orchestration, zero-trust tenant isolation, and immutable worktree management.
+
+```
+                  ┌─────────────────────────────────────────┐
+                  │          BIFROST (Ingress GW)           │
+                  │  Envoy / NGINX Reverse Proxy & TLS Term │
+                  └────────────────────┬────────────────────┘
+                                       │
+                  ┌────────────────────┴────────────────────┐
+                  │       HLIDSKJALF (Control Plane)        │
+                  │  Telemetry, Dashboards & Auth Daemons   │
+                  └────────────────────┬────────────────────┘
+                                       │
+            ┌──────────────────────────┴──────────────────────────┐
+            ▼                                                     ▼
+┌───────────────────────────────────┐                 ┌───────────────────────────────────┐
+│     SVARTALFAHEIM (Tenant A)      │                 │     SVARTALFAHEIM (Tenant B)      │
+│  Isolated Namespace & Cred Store  │                 │  Isolated Namespace & Cred Store  │
+└───────────┬───────────────────────┘                 └───────────┬───────────────────────┘
+            │                                                     │
+            ├──► RATATOSKR (Async Event Bus / NATS Broker)        │
+            ├──► YGGDRASIL (Git Worktree Manager / libgit2)       │
+            └──► UTGARD (Docker Ephemeral Sandboxes)              │
+                  └── BROKK (Autonomous Agent Worker Cluster)     │
+```
+
+### 2. Comprehensive Technology Stack Requirements
+
+**A. Core Control Plane & Daemons**
+
+- Language: Rust (Edition 2024) — Chosen for zero-cost abstractions, memory safety without garbage collection, and lightning-fast async performance. *(Target. Today: TypeScript on Node.)*
+- Async Runtime: Tokio — Handles concurrent I/O across thousands of active tenant connections and agent worker streams. *(Today: Node async I/O.)*
+- API & IPC Layer: gRPC (Protobuf v3) and JSON-RPC for low-latency inter-daemon communication between Bifrost, Ratatoskr, and Brokk. *(Today: JSON-RPC 2.0 + A2A 1.0 + Redis.)*
+
+**B. Agent Orchestration & Worker Runtime**
+
+- Primary Agent Harness: Python 3.12+ / TypeScript (Node.js 22) — Supporting flexible LLM SDK bindings, tool execution loops, and structured planning pipelines. ✅ *already current stack*
+- Worker Daemons (Brokk): Containerized worker nodes compiled as standalone static binaries interacting via IPC with the host kernel. *(Today: Python/TS services under PM2/Docker.)*
+
+**C. Sandbox & Container Runtime (Utgard)**
+
+- Isolation Engine: Docker Engine / containerd with rootless container configurations and seccomp syscall filtering.
+- Resource Limits: Cgroups v2 enforcement per sandbox instance (default allocation: 128GB memory ceiling, ephemeral storage bounds).
+- Network Policies: Strict zero-egress or scoped proxy-routed egress via Bifrost.
+
+**D. Event Bus & Messaging (Ratatoskr)**
+
+- Broker: NATS Server (JetStream enabled) — Ultra-low latency pub/sub messaging broker ensuring reliable event delivery across all seven system realms with 98.4% traceability index assurance. *(Today: Redis pub/sub under the A2A 1.0 task model.)*
+
+**E. Version Control & Worktrees (Yggdrasil)**
+
+- Engine: libgit2 / Git CLI — Manages isolated parallel branch worktrees (.treehouses) on shared storage volumes, preventing file collision during concurrent agent file mutations.
+
+**F. Persistence & Storage Tier**
+
+- Relational Database: PostgreSQL 16+ — Stores tenant metadata, user credentials, access control lists, and immutable audit logs. *(Today: Postgres available self-hosted; engram/SQLite stays the memory well.)*
+- Object Storage: MinIO / AWS S3 Compatible — Caches build artifacts, large model contexts, and compressed snapshot archives for ephemeral sandboxes.
+
+### 3. Security & Multi-Tenant Isolation Specifications
+
+- **Realm Boundary Enforcement:** Svartalfaheim enforces strict namespace isolation. Memory pages, environment variables, and temporary credential tokens cannot cross tenant boundaries.
+- **Traceability Auditing:** Every agent modification generates cryptographic checksums and execution telemetry logs recorded to the immutable audit ledger, maintaining a minimum traceability index of 98.4%.
+- **Ephemeral Lifecycle:** Utgard sandboxes are destroyed immediately upon task completion or failure, wiping all local container states from disk.
+
+---
+
+# PART 3 — Multi-Tenant Agent OS
+
+## Comprehensive Design & Architecture Specification (v2.6)
+
+### 1. Executive Summary & Brand Identity
+
+`Ymir Rut` is an advanced **Multi-Tenant Agent Operating System** designed for orchestrating autonomous AI worker clusters, secure tenant sandboxes, and immutable version-controlled worktrees. The brand identity fuses Norse mythic durability (symbolizing primeval creation, forged iron, and runic permanence) with modern cloud-native systems architecture (zero-trust isolation, ephemeral container runtimes, and real-time telemetry).
+
+### 2. Design System Rules & Visual Language
+
+**A. Typography**
+
+- **Headings & Runes:** Cinzel (Google Fonts) — Provides carved, lapidary, monumental elegance representing ancient galdrastafir and runic inscriptions.
+- **Code, Telemetry & Status:** JetBrains Mono (Google Fonts) — Precision monospaced typeface for command-line interfaces, json configs, and operational metrics.
+- **Body & UI Text:** Inter (Google Fonts) — Clean, highly legible sans-serif for dashboard readability and interface descriptions.
+
+**B. Color Palette & Lighting**
+
+- **Canvas Base:** Deep obsidian slate (`#080c14` to `#060911`), evoking subterranean forge chambers and deep space telemetry.
+- **Luminescence & Primary Accent:** Electric Cyan (`#38bdf8`, `#0ea5e9`), representing crystalline energy and Bifrost transit beams.
+- **Secondary Accent:** Deep Violet / Indigo (`#818cf8`, `#6366f1`), denoting ethereal multi-tenant realms and deep compute nodes.
+- **Borders & Structural Lines:** Muted slate (`#1e293b`, `#334155`), providing crisp container framing without visual clutter.
+
+**C. Iconography & Emblem Geometry**
+
+- **The Ymir Root Mark:** Combines the **Algiz** rune (signifying divine protection and branching worker stems) with a heavy **blacksmith anvil base** (signifying industrial strength and compute execution).
+- **Chiseled Bevels:** Modeled with dual-layer vector depth — a dark iron forged exterior (`#334155`) paired with a luminous cyan chiseled inner edge (`#7dd3fc`).
+
+### 3. Core Architecture Topology (The 7 Realms / Modules)
+
+The Ymir OS runtime is structured around seven interlinked daemons and architectural modules:
+
+| Realm | Module | Function |
+|---|---|---|
+| **Bifrost** | Ingress Gateway | Reverse proxy router and TLS HTTP gateway handling secure ingress traffic across tenant realms. Route spec: `/ingress/proxy/router` |
+| **Hlidskjalf** | Control Plane & Observability | Centralized user dashboard providing real-time telemetry, trace logs, and cluster health metrics |
+| **Svartalfaheim** | Tenant Isolation Realms | Scoped customer workspaces ensuring zero credential, memory, or state bleed between execution nodes. Isolation level: `sandbox_isolated` |
+| **Brokk** | Autonomous Agent Workers | Primary task execution workers responsible for orchestrating builds, audits, and code transformations |
+| **Utgard** | Ephemeral Sandboxes | Hardened Docker task runtimes for executing untrusted shell code and automated compilation safely. Runtime spec: `docker_ephemeral` |
+| **Yggdrasil** | Git Worktree Manager | Manages isolated branch worktrees (.treehouses) for concurrent agent modifications without repo collision |
+| **Ratatoskr** | Event Bus | Lightweight asynchronous message broker facilitating inter-daemon communication and event dispatch |
+
+### 4. System Metadata & Config Specification
+
+Every Ymir cluster broadcasts standardized telemetry conformant with the core engine spec:
+
+```json
+{
+  "system_identifier": "ymir_rut_core",
+  "operational_status": "NOMINAL",
+  "core_light_wavelength": ["460nm (Cyan)", "390nm (Violet)"],
+  "surface_texture": "Hand_Hammered_Steel",
+  "crystalline_grid": "Icosahedral_Facets",
+  "glyph_set": "A-Z_Runes_Simplified",
+  "resource_allocation": {
+    "engine": "utgard_sandbox",
+    "instance": "78c70",
+    "memory": "128GB"
+  },
+  "traceability_index": 0.984
+}
+```
+
+### 5. Interactive Harness & CLI Specifications
+
+- **Command Set:** Supports interactive commands such as `ymir status`, `brokk agent spawn`, and `ymir init`.
+- **Traceability Assurance:** Every agent execution returns a verified traceability index (e.g., 98.4%), ensuring complete auditability of automated code changes.
+
+---
+---
+
+# APPENDIX — Reconciliation: Rut (target) → Current Stack (today)
+
+Both stacks speak the same Norse module language; only the floors differ.
+
+| Rut module (target) | Current implementation (TypeScript · Python · React · Vue) |
+|---|---|
+| `crates/bifrost` (Envoy/gRPC) | TS gateway service — Traefik/Caddy + JSON-RPC routing; `auth::verifier` → Heimdall OAuth2-proxy |
+| `crates/hlidskjalf` (Rust dashboard) | **React/Vue** portal — smidja visualizer paradigm, `#/memory`, `#/fleet`, `#/tasks`, Runes stream |
+| `crates/svartalfaheim` (tenant/cred vault) | TS tenant daemon — realm namespaces, `.env.realm`, scoped registries, per-realm A2A discovery |
+| `crates/ratatoskr` (NATS JetStream) | TS **A2A 1.0 backbone** + Redis queue under the task model (plan 25) |
+| `crates/yggdrasil` (libgit2 .treehouses) | TS worktree manager over git CLI — `.yggdrasil/<agent-id>/` branches |
+| `runtime/utgard` (rootless Docker, cgroups v2, seccomp) | Python/Docker sandbox — network-none, CPU/RAM/timeouts (unchanged intent) |
+| `runtime/brokk` (agent harness, Py 3.12+/Node 22) | **already current stack** — Python + TS/Node agent harnesses, tool loops, mirroring |
+| `proto/` (Protobuf/gRPC) | `.agents/bus` schemas (JSON-RPC 2.0, A2A task lifecycle, `InterAgentMessage`) |
+| PostgreSQL 16 + MinIO | self-hosted Postgres 16 for tenant metadata/audit; MinIO/S3 for artifacts; **engram** = memory well |
+| CLI (`ymir status`, `brokk agent spawn`, `ymir init`) | same command surface, implemented in TS/Python |
+| Traceability index 98.4% | every significant action → Runes ledger + Mimirsbrunn episode (audit coverage) |
+
+**Port policy (ENTRY-009/010):** ship end-to-end on TS/Python/React/Vue first; when stable,
+re-floor each service into its Rut crate without redesigning the module contract.

package/package.json

@@ -1,27 +1,57 @@
 {
   "name": "@zerwiz/ymir",
-  "version": "0.1.3",
-  "description": "Ymir — the official local installer (curl | bash, or npx ymir)",
-  "type": "module",
+  "version": "0.1.5",
+  "description": "Ymir \u2014 the single-tenant agent operating system. Omarchy-first, host-aware, self-healing.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/zerwiz/ymir",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zerwiz/ymir.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zerwiz/ymir/issues"
+  },
+  "keywords": [
+    "agent",
+    "agents",
+    "ymir",
+    "brokk",
+    "omarchy",
+    "wsl",
+    "a2a",
+    "mcp"
+  ],
   "bin": {
-    "ymir": "bin/ymir.js"
+    "ymir": "bin/ymir.js",
+    "ymir-install": "bin/ymir-install.sh"
   },
   "files": [
-    "bin",
-    "install.sh",
+    "bin/",
+    ".agents/",
+    "scripts/",
+    "config/",
+    "RULES/",
+    "docs/",
+    "packaging/",
+    "AGENTS.md",
     "README.md",
-    "LICENSE"
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "!**/node_modules/**"
   ],
   "engines": {
-    "node": ">=18"
-  },
-  "license": "Apache-2.0",
-  "homepage": "https://github.com/zerwiz/ymir",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/zerwiz/ymir-release.git"
+    "node": ">=20"
   },
+  "os": [
+    "linux",
+    "darwin"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh",
+    "compliance": "bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh"
   }
 }

package/packaging/build.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# build.sh — build the installer each host can actually build.
+#
+#   packaging/build.sh --exe     # Windows installer  → Ymir-Setup-<version>.exe   (NSIS, needs makensis)
+#   packaging/build.sh --mac     # macOS installer    → Ymir-<version>.pkg         (pkgbuild, macOS only)
+#   packaging/build.sh --check   # what this host can build, and with what
+#
+# Honest boundaries, stated up front:
+#   • The .exe is an NSIS installer, so it can be built on Linux or Windows —
+#     NSIS is a compiler, not a Windows VM.
+#   • The .pkg needs Apple's own pkgbuild/productbuild: it is built ON a Mac, or
+#     in CI on a macos runner (.github/workflows/ymir-installers.yml). Signing and
+#     notarisation need the operator's Apple credentials and are deliberately not
+#     attempted here.
+set -u
+
+VERSION="$(git -C "$(dirname "${BASH_SOURCE[0]}")" describe --tags --always 2>/dev/null || printf '0.1.0')"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT="$ROOT/packaging/out"
+REPO="${YMIR_REPO:-$(git -C "$ROOT" remote get-url origin 2>/dev/null || printf 'https://github.com/zerwiz/ymir.git')}"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+can_exe() { have makensis; }
+can_mac() { [ "$(uname -s)" = "Darwin" ] && have pkgbuild; }
+
+check() {
+  printf 'installers[3]{target,buildable,why}:\n'
+  printf '  "windows .exe","%s","%s"\n' \
+    "$([ "$(can_exe && echo y)" = y ] && printf yes || printf no)" \
+    "$(can_exe && printf 'makensis present' || printf 'makensis absent — apt-get install nsis (or choco install nsis), or let CI build it')"
+  printf '  "macos .pkg","%s","%s"\n' \
+    "$([ "$(can_mac && echo y)" = y ] && printf yes || printf no)" \
+    "$(can_mac && printf 'pkgbuild present' || printf 'pkgbuild is Apple-only — build on a Mac, or in CI on a macos runner')"
+  printf '  "universal .command","yes","shipped as a file; double-clickable on any Mac (no build step)"\n'
+}
+
+exe() {
+  if ! can_exe; then
+    printf 'error: makensis not found\nhelp: sudo apt-get install -y nsis\n' >&2
+    printf 'help: or build in CI — .github/workflows/ymir-installers.yml\n' >&2
+    exit 1
+  fi
+  mkdir -p "$OUT"
+  makensis -DREPO="$REPO" -DVERSION="$VERSION" "$ROOT/packaging/windows/ymir-setup.nsi" >/dev/null 2>&1 \
+    || { printf 'error: makensis failed\nhelp: run it by hand to see why:\n  makensis -DREPO=%s packaging/windows/ymir-setup.nsi\n' "$REPO" >&2; exit 1; }
+  mv -f "$ROOT/packaging/windows/Ymir-Setup-"*.exe "$OUT/" 2>/dev/null || true
+  printf 'installers[1]{target,artifact}:\n  "windows .exe","%s"\n' "$OUT/$(ls "$OUT" | grep '\.exe$' | head -1)"
+}
+
+pkg() {
+  if ! can_mac; then
+    printf 'error: pkgbuild is Apple-only; this host cannot build a .pkg\nhelp: on a Mac run: packaging/build.sh --mac\nhelp: or CI on a macos runner — .github/workflows/ymir-installers.yml\n' >&2
+    exit 1
+  fi
+  mkdir -p "$OUT"
+  local stage="$OUT/stage"
+  rm -rf "$stage"; mkdir -p "$stage/Applications/Ymir"
+  cp "$ROOT/packaging/macos/Ymir Installer.command" "$stage/Applications/Ymir/"
+  chmod +x "$stage/Applications/Ymir/Ymir Installer.command"
+  cp "$ROOT/bin/bootstrap-macos.sh" "$stage/Applications/Ymir/" 2>/dev/null || true
+  pkgbuild --root "$stage" --identifier com.ymir.installer --version "$VERSION" --install-location / "$OUT/Ymir-$VERSION.pkg" >/dev/null \
+    || { printf 'error: pkgbuild failed\nhelp: run it by hand to see why\n' >&2; exit 1; }
+  printf 'installers[1]{target,artifact}:\n  "macos .pkg","%s"\n' "$OUT/Ymir-$VERSION.pkg"
+}
+
+case "${1:-}" in
+  --exe) exe ;;
+  --mac) pkg ;;
+  --check|"") check ;;
+  -v|-V|--version) printf '%s\n' "$VERSION" ;;
+  -h|--help) sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//' ;;
+  *) printf 'error: unknown flag %s\nhelp: packaging/build.sh [--exe|--mac|--check]\n' "$1" >&2; exit 2 ;;
+esac

package/packaging/macos/Ymir Installer.command

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Ymir Installer.command — double-click this on a Mac.
+#
+# macOS gets its Linux host the same way Windows does: a VM. This launcher finds
+# the Ymir checkout and hands over to bin/bootstrap-macos.sh, which raises Ubuntu
+# in Lima and installs Ymir inside it. It is a .command file so Finder runs it on
+# a double-click — no terminal knowledge required of the operator.
+#
+# If there is no checkout yet, it clones one first (the URL below, overridable
+# with YMIR_REPO).
+set -u
+REPO="${YMIR_REPO:-https://github.com/zerwiz/ymir.git}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+echo "Ymir — macOS bootstrap"
+echo
+
+# 1. find a checkout: beside this file, ~/Ymir, or clone one.
+ROOT=""
+for cand in "$HERE/../.." "$HOME/Ymir" "$HOME/Documents/Ymir-src"; do
+  [ -x "$cand/bin/bootstrap-macos.sh" ] && { ROOT="$(cd "$cand" && pwd)"; break; }
+done
+if [ -z "$ROOT" ]; then
+  echo "cloning Ymir into $HOME/Ymir …"
+  git clone "$REPO" "$HOME/Ymir" || { echo "clone failed — set YMIR_REPO to your checkout URL"; read -r -p "press return to close" _; exit 1; }
+  ROOT="$HOME/Ymir"
+fi
+
+echo "checkout: $ROOT"
+echo
+
+# 2. readiness, then the bootstrap. The bootstrap itself is gated on macOS and
+#    refuses politely anywhere else, so this launcher stays dumb on purpose.
+"$ROOT/bin/bootstrap-macos.sh" --check
+echo
+read -r -p "Proceed with the install? [y/N] " reply
+case "$reply" in
+  y|Y|yes|YES) "$ROOT/bin/bootstrap-macos.sh" ;;
+  *) echo "nothing changed." ;;
+esac
+
+echo
+read -r -p "press return to close" _

package/packaging/windows/ymir-setup.nsi

@@ -0,0 +1,74 @@
+; ymir-setup.nsi — the Windows bootstrap installer (Ymir-Setup.exe).
+;
+; It does one honest thing: install the Windows bootstrap and run it. Ymir's host
+; on Windows is Ubuntu inside WSL2, so the "installer" sets that up and then
+; hands over to bin/ymir-install.sh inside the distro. It is not a native
+; Windows build of Ymir, and it does not pretend to be.
+;
+; Build (from the repo root, on Linux or Windows):
+;   packaging/build.sh --exe
+;   makensis -DREPO=https://github.com/<you>/ymir.git packaging/windows/ymir-setup.nsi
+;
+; Requires NSIS 3.x (Ubuntu: apt-get install nsis; Windows: choco install nsis).
+
+Unicode true
+!include "MUI2.nsh"
+!include "x64.nsh"
+
+!ifndef REPO
+  !define REPO "https://github.com/zerwiz/ymir.git"
+!endif
+!ifndef VERSION
+  !define VERSION "0.1.0"
+!endif
+
+!define APPNAME "Ymir"
+Name "${APPNAME} — set up the Linux host (Ubuntu on WSL2)"
+OutFile "Ymir-Setup-${VERSION}.exe"
+InstallDir "$LOCALAPPDATA\Ymir"
+InstallDirRegKey HKCU "Software\Ymir" "InstallDir"
+RequestExecutionLevel admin          ; enabling WSL requires elevation
+
+VIProductVersion "0.1.0.0"
+VIAddVersionKey "ProductName" "Ymir"
+VIAddVersionKey "CompanyName" "Ymir"
+VIAddVersionKey "FileDescription" "Ymir bootstrap — installs Ubuntu on WSL2 and Ymir inside it"
+VIAddVersionKey "FileVersion" "${VERSION}"
+
+!define MUI_ABORTWARNING
+
+; ── pages ────────────────────────────────────────────────────────────────────
+!insertmacro MUI_PAGE_WELCOME
+!insertmacro MUI_PAGE_INSTFILES
+!insertmacro MUI_PAGE_FINISH
+!insertmacro MUI_UNPAGE_CONFIRM
+!insertmacro MUI_UNPAGE_INSTFILES
+!insertmacro MUI_LANGUAGE "English"
+
+; ── install ──────────────────────────────────────────────────────────────────
+Section "Bootstrap" SecBootstrap
+  SetOutPath "$INSTDIR"
+  File "..\..\bin\bootstrap-windows.ps1"
+  WriteUninstaller "$INSTDIR\uninstall.exe"
+
+  WriteRegStr HKCU "Software\Ymir" "InstallDir" "$INSTDIR"
+  WriteRegStr HKCU "Software\Ymir" "Repo" "${REPO}"
+
+  ; The powershell bootstrap prints its own TOON rows to the log window, so the
+  ; operator sees exactly what happened (WSL enabled, distro installed, Ymir in).
+  DetailPrint "Setting up the Linux host (Ubuntu on WSL2)…"
+  nsExec::ExecToLog 'powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\bootstrap-windows.ps1" -Repo "${REPO}"'
+  Pop $0
+  ${If} $0 != 0
+    DetailPrint "bootstrap returned $0 — read the log above; a reboot may be required."
+  ${EndIf}
+SectionEnd
+
+Section "Uninstall"
+  Delete "$INSTDIR\bootstrap-windows.ps1"
+  Delete "$INSTDIR\uninstall.exe"
+  RMDir "$INSTDIR"
+  DeleteRegKey HKCU "Software\Ymir"
+  ; The Ubuntu distro and its data are the operator's — never removed here.
+  ; To remove them: wsl --unregister Ubuntu
+SectionEnd

package/scripts/README.md

@@ -0,0 +1,22 @@
+# YMIR — scripts
+
+Local run helpers. Both scripts are safe to call repeatedly.
+
+## Hlidskjalf (control plane SPA)
+
+```bash
+scripts/start.sh          # raise the SPA  → http://127.0.0.1:3888/
+scripts/start.sh --foreground   # run in the foreground (Ctrl-C to stop)
+scripts/stop.sh           # lower it (process group, then port fallback)
+scripts/stop.sh --force   # SIGKILL if TERM did not land
+```
+
+- Installs `apps/hlidskjalf` dependencies on first run if missing.
+- Writes a PID file to `.run/hlidskjalf.pid` and logs to `.run/hlidskjalf.log`.
+- `HLIDSKJALF_PORT` overrides the default port (`3888`).
+
+## Notes
+
+- Never `pkill -f` on a path that appears in your own command line — kill by the
+  PID file (process group) or by port, as `stop.sh` does.
+- `.run/` is runtime-only and must not be committed.