Pummelchen · Pummelchen · Jun 25, 2026 · Jun 25, 2026
diff --git a/.ai/ARCHITECTURE.md b/.ai/ARCHITECTURE.md
@@ -0,0 +1,66 @@
+<!--
+AI onboarding file.
+Mode: bootstrap
+Indexed commit: 8458ff956831e1b3b44a0cbcb396352ce28e3a01
+Last generated: 2026-06-25T09:20:22Z
+Generator: generic high-end AI coding agent
+Purpose: Help future AI sessions understand this repository quickly.
+Audience: Any high-capability AI coding agent, regardless of vendor or model family.
+Human edits are allowed. Future refreshes should preserve valid human edits.
+-->
+# Architecture
+
+## Verified high-level architecture
+
+XAIOS is a freestanding OS repository, not a hosted application. The current source builds an AArch64 UEFI/QEMU path, kernel ELF, userspace ELFs, a FAT boot image, a VirtIO test block image, and a persistent mutable storage image.
+
+Evidence:
+- `docs/ARCHITECTURE.md`
+- `scripts/build-image.sh`
+- `kernel/core/kmain.c`
+- `scripts/run-qemu-aarch64.sh`
+
+## Boot/runtime flow
+
+1. UEFI firmware loads `BOOTAA64.EFI` from the FAT image.
+2. `boot/uefi/loader_main.c` loads `kernel.elf` and passes `xaios_boot_info_t`.
+3. `kernel/core/kmain.c` initializes architecture, memory, device, filesystem, security, network, process, AI runtime, and telemetry subsystems.
+4. The kernel loads `/init`, `/bin/service-manager`, workers, and userspace apps from initramfs.
+5. The kernel emits telemetry and enters an idle `wfe` loop.
+
+## Major components
+
+| Component | Files | Responsibility |
+|---|---|---|
+| Bootloader | `boot/uefi/loader_main.c`, `boot/uefi/linker.ld` | UEFI entry and kernel handoff. |
+| Kernel init | `kernel/core/kmain.c` | Strict init/self-test order and userspace launch. |
+| Memory | `kernel/mm/`, `kernel/arch/aarch64/mmu.c` | Physical/virtual memory, NUMA, heaps, arenas, ELF loading. |
+| Devices | `kernel/dev/virtio/`, `kernel/arch/aarch64/pci.c`, `kernel/arch/aarch64/smmu.c` | VirtIO block/net, PCI, SMMU. |
+| Filesystems | `kernel/fs/`, `scripts/create-initfs.py` | RO initramfs and mutable persistent filesystem. |
+| Process/API | `kernel/user/`, `userspace/include/xaios_user.h` | Process table, service supervisor, syscall ABI/wrappers. |
+| Network | `kernel/net/`, `kernel/runtime/network_stack.c` | Protocols, socket buffers, network telemetry. |
+| Security | `kernel/runtime/security.c` | Capabilities, credential-material rejection, update policy, sandbox path checks. |
+| AI runtime | `kernel/runtime/cpu_ai_runtime.c`, `kernel/runtime/model_arena.c`, `kernel/runtime/ai_cell.c` | CPU-only inference simulation/runtime, shared model arena, resource isolation. |
+| Remote/admin | `kernel/runtime/remote_login.c`, `userspace/sshd/` | Remote login and SSH/SFTP surfaces. |
+
+## Trust boundaries
+
+- EL0 userspace crosses into kernel via syscall dispatch in `kernel/user/syscall.c`.
+- Syscalls are gated by capability masks in `kernel/include/xaios/syscall.h` and dispatch table entries.
+- Filesystem access is constrained by security policy in `kernel/runtime/security.c`.
+- Mutable state and updates cross persistence/update boundaries in `kernel/fs/`, `kernel/runtime/persistence.c`, and `kernel/runtime/update.c`.
+- Network/SSH paths cross from QEMU host forwarding into socket and SSH code.
+- Model conversion reads external model files on the host and writes XAIOS-native images.
+
+## Data/job flows
+
+- Build flow: `make image` -> `scripts/build-image.sh` -> Clang/LLD/mtools -> `build/xaios-aarch64.img`, kernel/userspace ELFs, VirtIO images.
+- Smoke flow: `make qemu-smoke` -> `scripts/qemu-smoke.py` -> boot QEMU -> scan output markers and telemetry.
+- ABI flow: `scripts/qemu-abi-contract.py` -> `scripts/qemu_gate_lib.py` -> compare source syscall header/initfs/model constants against `contracts/qemu-rc-v1.json`.
+- Userspace app flow: compile app from `userspace/apps/`, pack into initramfs, launch from `kmain()` with per-app capability mask.
+
+## Current architecture risks
+
+- Contract/docs lag source for newer syscalls and `agenttest` paths.
+- Hardware performance is not validated by QEMU gates.
+- Security update signature validation is documented in source as QEMU dev-mode format validation, not production cryptographic verification.
diff --git a/.ai/CHANGELOG.md b/.ai/CHANGELOG.md
@@ -0,0 +1,42 @@
+<!--
+AI onboarding file.
+Mode: bootstrap
+Indexed commit: 8458ff956831e1b3b44a0cbcb396352ce28e3a01
+Last generated: 2026-06-25T09:20:22Z
+Generator: generic high-end AI coding agent
+Purpose: Help future AI sessions understand this repository quickly.
+Audience: Any high-capability AI coding agent, regardless of vendor or model family.
+Human edits are allowed. Future refreshes should preserve valid human edits.
+-->
+# AI onboarding changelog
+
+## 2026-06-25 — bootstrap
+
+Indexed commit: `8458ff956831e1b3b44a0cbcb396352ce28e3a01`
+
+### Added
+
+- Root `AI_INDEX.md` with repository snapshot, task map, commands, risks, and read order.
+- Root `AGENTS.md` with vendor-neutral AI-agent working rules.
+- `.ai/START_HERE.md` first-session prompt.
+- `.ai/PROJECT_MAP.md`, `.ai/ARCHITECTURE.md`, `.ai/COMPONENTS.md`.
+- `.ai/COMMANDS.md`, `.ai/TESTING.md`, `.ai/SECURITY.md`, `.ai/PLAYBOOKS.md`.
+- `.ai/KNOWN_UNKNOWNS.md` for conflicts and unresolved questions.
+- `.ai/MANIFEST.json` machine-readable manifest.
+
+### README
+
+- Added a top-of-file AI onboarding block after the title.
+- Preserved the existing project README content.
+
+### Model-specific file migration
+
+- No generated model-specific AI onboarding files were found during targeted inspection.
+- No model-specific AI files were created.
+
+### Risks recorded
+
+- QEMU correctness vs hardware performance claim conflict.
+- Syscall/API/contract documentation drift.
+- License ambiguity.
+- Some stale or duplicate existing human docs.
diff --git a/.ai/COMMANDS.md b/.ai/COMMANDS.md
@@ -0,0 +1,95 @@
+<!--
+AI onboarding file.
+Mode: bootstrap
+Indexed commit: 8458ff956831e1b3b44a0cbcb396352ce28e3a01
+Last generated: 2026-06-25T09:20:22Z
+Generator: generic high-end AI coding agent
+Purpose: Help future AI sessions understand this repository quickly.
+Audience: Any high-capability AI coding agent, regardless of vendor or model family.
+Human edits are allowed. Future refreshes should preserve valid human edits.
+-->
+# Commands
+
+Run commands from the repository root unless noted.
+
+## Toolchain install / verification
+
+macOS prerequisites documented in `docs/GETTING-STARTED.md`:
+
+```sh
+brew install llvm lld qemu mtools python3
+make bootstrap
+```
+
+Ubuntu/Debian prerequisites documented in `docs/GETTING-STARTED.md` and CI:
+
+```sh
+sudo apt-get update
+sudo apt-get install -y clang lld qemu-system-arm qemu-efi-aarch64 mtools python3
+make bootstrap
+```
+
+Optional Python dev dependency:
+
+```sh
+python3 -m pip install -r requirements-dev.txt
+```
+
+Model converter dependencies, when using `tools/convert_gguf_to_xaios.py`:
+
+```sh
+python3 -m pip install gguf numpy
+```
+
+## Build
+
+| Task | Command |
+|---|---|
+| Default build | `make all` |
+| AArch64 image | `make image` |
+| x86_64 image | `make image-x86_64` |
+| Clean generated outputs | `make clean` |
+| Clean persistent image | `make clean-persistent` |
+| Syntax-only C compile check | `make compile-check` |
+
+## Run locally
+
+| Task | Command |
+|---|---|
+| AArch64 QEMU | `make qemu` or `make qemu-aarch64` |
+| x86_64 QEMU | `make qemu-x86_64` |
+| Dry-run QEMU command lines | `make qemu-dry-run` |
+| SSH bridge | `make xaios-ssh-bridge` |
+| Connect to local SSH bridge | `ssh -p 2222 admin@localhost` |
+
+`run-qemu-aarch64.sh` supports environment overrides such as `XAIOS_AAVMF_CODE`, `XAIOS_QEMU_ACCEL`, `XAIOS_QEMU_CPU`, `XAIOS_QEMU_MACHINE`, `XAIOS_QEMU_MEMORY`, `XAIOS_QEMU_SMP`, and `XAIOS_QEMU_HOSTFWD_PORT`.
+
+## Test/gates
+
+| Gate | Command | Notes |
+|---|---|---|
+| Primary smoke | `make qemu-smoke` | Boots full OS and scans markers. |
+| Process | `make qemu-process-gate` | Process lifecycle/scheduler. |
+| OS control | `make qemu-osctl-gate` | Control-plane telemetry. |
+| Filesystem | `make qemu-filesystem-gate` | Mutable filesystem. |
+| Network | `make qemu-network-suite` or `make qemu-network-full-gate` | TCP/UDP/network paths. |
+| CPU-AI | `make qemu-cpu-ai-suite` or `make qemu-cpu-ai-runtime-gate` | CPU-only AI runtime. |
+| AI Cell | `make qemu-ai-cell-gate` | Resource contracts. |
+| Security | `make qemu-security-gate` | Security policy markers. |
+| Update | `make qemu-update-gate` | Update/rollback paths. |
+| Regression | `make qemu-regression-suite` | Broader regression suite. |
+| ABI contract | `make qemu-abi-contract` or `python3 scripts/qemu-abi-contract.py` | Contract/source validation. |
+| Readiness | `make qemu-readiness-gate` | Full local QEMU readiness. |
+| Full OS RC | `make qemu-full-os-rc` | Release-candidate gate. |
+
+## Format/lint/typecheck
+
+No standalone formatter, linter, or typechecker command was detected beyond C compiler warnings-as-errors and Python gate execution.
+
+## Database, migrations, Docker, deploy
+
+No database migration tooling, Dockerfile/compose setup, or deploy command was detected in inspected files.
+
+## Release/readiness artifacts
+
+Readiness and RC gates write reports under `build/`, including `build/qemu-readiness-report.json` and `build/qemu-full-os-rc-report.json`. These are generated artifacts and should not be committed.
diff --git a/.ai/COMPONENTS.md b/.ai/COMPONENTS.md
@@ -0,0 +1,69 @@
+<!--
+AI onboarding file.
+Mode: bootstrap
+Indexed commit: 8458ff956831e1b3b44a0cbcb396352ce28e3a01
+Last generated: 2026-06-25T09:20:22Z
+Generator: generic high-end AI coding agent
+Purpose: Help future AI sessions understand this repository quickly.
+Audience: Any high-capability AI coding agent, regardless of vendor or model family.
+Human edits are allowed. Future refreshes should preserve valid human edits.
+-->
+# Components
+
+## Bootloader
+
+- Responsibility: Load kernel ELF from FAT image and transfer control with boot info.
+- Key files: `boot/uefi/loader_main.c`, `boot/uefi/linker.ld`, `scripts/build-image.sh`.
+- Risks: earliest boot failures; toolchain/linker sensitivity.
+- Validate: `make image`, `make qemu-smoke`.
+
+## Kernel initialization/core
+
+- Responsibility: strict subsystem initialization and userspace launch.
+- Key files: `kernel/core/kmain.c`, `kernel/core/telemetry.c`, `kernel/core/klog.c`.
+- Invariants: self-tests run before dependent runtime paths; capability masks match app needs.
+- Validate: `make compile-check`, `make qemu-smoke`.
+
+## Memory and process loading
+
+- Responsibility: PMM/NUMA/VMM, arenas, heap, ELF loading, process address spaces.
+- Key files: `kernel/mm/`, `kernel/arch/aarch64/mmu.c`, `kernel/user/user.c`.
+- Risks: boot failure, address-space corruption, user-buffer validation regressions.
+- Validate: compile check plus smoke/regression.
+
+## Syscall/API surface
+
+- Responsibility: kernel/user boundary and userspace wrappers.
+- Key files: `kernel/include/xaios/syscall.h`, `kernel/user/syscall.c`, `userspace/include/xaios_user.h`, `userspace/lib/xaios_user.c`.
+- Public interfaces: syscall numbers, request structs, capability bits, wrapper functions.
+- Risks: docs/contract drift; missing capability enforcement.
+- Validate: `python3 scripts/qemu-abi-contract.py`, `make qemu-smoke`.
+
+## Filesystem, persistence, update
+
+- Responsibility: initramfs, mutable filesystem, persistent state, update/rollback.
+- Key files: `kernel/fs/`, `kernel/runtime/persistence.c`, `kernel/runtime/update.c`, `scripts/create-initfs.py`, `contracts/qemu-rc-v1.json`.
+- Risks: data loss, rollback/auth bypass, contract mismatch.
+- Validate: filesystem/update/readiness gates.
+
+## Network and SSH
+
+- Responsibility: packet/protocol/socket paths and remote administration surfaces.
+- Key files: `kernel/net/`, `kernel/runtime/network_stack.c`, `userspace/sshd/`, `scripts/run-qemu-aarch64.sh`.
+- External dependency: QEMU host forwarding defaults to host port `2222` for guest SSH port 22.
+- Risks: auth/security regressions, socket accounting mismatch.
+- Validate: network suite and SSH smoke if environment supports it.
+
+## CPU-AI runtime and AI Cell
+
+- Responsibility: CPU-only inference runtime/model handling and resource isolation.
+- Key files: `kernel/runtime/cpu_ai_runtime.c`, `kernel/runtime/model_arena.c`, `kernel/runtime/ai_cell.c`, `tools/convert_gguf_to_xaios.py`.
+- Risks: model format mismatch, unsupported hardware-performance claims, arena/KV-cache accounting bugs.
+- Validate: CPU-AI suite, AI Cell gate, smoke.
+
+## Build/gate system
+
+- Responsibility: reproducible build images and QEMU validation reports.
+- Key files: `Makefile`, `scripts/build-image.sh`, `scripts/qemu-*.py`, `scripts/qemu_gate_lib.py`, `.github/workflows/ci.yml`.
+- Generated outputs: `build/` reports/images/ELFs.
+- Validate: relevant make targets; do not commit generated reports.
diff --git a/.ai/KNOWN_UNKNOWNS.md b/.ai/KNOWN_UNKNOWNS.md
@@ -0,0 +1,69 @@
+<!--
+AI onboarding file.
+Mode: bootstrap
+Indexed commit: 8458ff956831e1b3b44a0cbcb396352ce28e3a01
+Last generated: 2026-06-25T09:20:22Z
+Generator: generic high-end AI coding agent
+Purpose: Help future AI sessions understand this repository quickly.
+Audience: Any high-capability AI coding agent, regardless of vendor or model family.
+Human edits are allowed. Future refreshes should preserve valid human edits.
+-->
+# Known unknowns and conflicts
+
+## Conflicting: performance claims vs QEMU evidence
+
+README, project tracker, and local wiki pages contain CPU-only performance targets and claims. `HARDWARE-READINESS.md` and `contracts/qemu-rc-v1.json` say QEMU benchmark/gate output is correctness evidence only and does not authorize hardware performance claims.
+
+Recommendation: treat performance numbers as targets or unverified design claims unless a human provides measured hardware baselines.
+
+Evidence:
+- `README.md`
+- `PROJECT-TRACKER.md`
+- `wiki/Qwen3.6-INT6-Support.md`
+- `HARDWARE-READINESS.md`
+- `contracts/qemu-rc-v1.json`
+
+## Conflicting: syscall/API documentation lag
+
+Source defines syscalls through `XAIOS_SYSCALL_AGENT_DISPATCH` number 34, while `docs/API.md` documents through socket close number 33 and `contracts/qemu-rc-v1.json` lists only numbers 1-28. `scripts/qemu_gate_lib.py` validates contract entries against source, but does not obviously require the contract to cover every source syscall.
+
+Recommendation: before changing syscalls, decide whether to update docs/API and contract coverage in the same PR.
+
+Evidence:
+- `kernel/include/xaios/syscall.h`
+- `userspace/include/xaios_user.h`
+- `kernel/user/syscall.c`
+- `docs/API.md`
+- `contracts/qemu-rc-v1.json`
+- `scripts/qemu_gate_lib.py`
+
+## Conflicting: license status
+
+`LICENSE` starts with MIT license text but ends with “License to be decided.” `README.md` also says license is to be decided.
+
+Recommendation: do not alter license language without human approval.
+
+Evidence:
+- `LICENSE`
+- `README.md`
+
+## Stale or incomplete docs
+
+- `docs/ARCHITECTURE.md` userspace lifecycle omits source-visible `agenttest` PID 16.
+- `PROJECT-TRACKER.md` references commands such as `make sshd` and some milestone commands that were not present in the inspected `Makefile`.
+- `CONTRIBUTING.md` contains duplicate sections and an existing vendor-specific workflow heading; it was preserved because it is human-facing contributor documentation, not a generated AI onboarding file.
+
+## Unknowns
+
+- Exact complete repository file tree could not be cloned in this runtime because direct GitHub DNS resolution failed; inspection used the GitHub connector and targeted source/config/docs reads.
+- Hardware validation status beyond repository docs is unknown.
+- Production signing/key-management design is not complete in source comments inspected.
+- Whether `.qoder/repowiki/` should be removed, ignored, or refreshed is unknown; it was not modified.
+
+## Ask a human before editing
+
+- Licensing text.
+- Hardware performance claims or benchmark methodology.
+- Production security model/signing claims.
+- Removal of non-onboarding docs with vendor-specific wording.
+- Any change that relaxes capability checks, credential-material rejection, update authorization, or sandbox path validation.