From ec604089592fff706c2d7100ff1324678d42f253 Mon Sep 17 00:00:00 2001 From: Pummelchen <0xa0b1@gmail.com> Date: Thu, 25 Jun 2026 16:45:36 +0700 Subject: [PATCH] docs: add AI onboarding context --- .ai/ARCHITECTURE.md | 66 ++++++++++++++++++++ .ai/CHANGELOG.md | 42 +++++++++++++ .ai/COMMANDS.md | 95 +++++++++++++++++++++++++++++ .ai/COMPONENTS.md | 69 +++++++++++++++++++++ .ai/KNOWN_UNKNOWNS.md | 69 +++++++++++++++++++++ .ai/MANIFEST.json | 128 +++++++++++++++++++++++++++++++++++++++ .ai/PLAYBOOKS.md | 66 ++++++++++++++++++++ .ai/PROJECT_MAP.md | 83 +++++++++++++++++++++++++ .ai/SECURITY.md | 58 ++++++++++++++++++ .ai/START_HERE.md | 44 ++++++++++++++ .ai/TESTING.md | 74 ++++++++++++++++++++++ AGENTS.md | 86 ++++++++++++++++++++++++++ AI_INDEX.md | 138 ++++++++++++++++++++++++++++++++++++++++++ README.md | 8 +++ 14 files changed, 1026 insertions(+) create mode 100644 .ai/ARCHITECTURE.md create mode 100644 .ai/CHANGELOG.md create mode 100644 .ai/COMMANDS.md create mode 100644 .ai/COMPONENTS.md create mode 100644 .ai/KNOWN_UNKNOWNS.md create mode 100644 .ai/MANIFEST.json create mode 100644 .ai/PLAYBOOKS.md create mode 100644 .ai/PROJECT_MAP.md create mode 100644 .ai/SECURITY.md create mode 100644 .ai/START_HERE.md create mode 100644 .ai/TESTING.md create mode 100644 AGENTS.md create mode 100644 AI_INDEX.md diff --git a/.ai/ARCHITECTURE.md b/.ai/ARCHITECTURE.md new file mode 100644 index 0000000..48dadaf --- /dev/null +++ b/.ai/ARCHITECTURE.md @@ -0,0 +1,66 @@ + +# 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 new file mode 100644 index 0000000..c43ad6b --- /dev/null +++ b/.ai/CHANGELOG.md @@ -0,0 +1,42 @@ + +# 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 new file mode 100644 index 0000000..9fe891f --- /dev/null +++ b/.ai/COMMANDS.md @@ -0,0 +1,95 @@ + +# 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 new file mode 100644 index 0000000..31cb33d --- /dev/null +++ b/.ai/COMPONENTS.md @@ -0,0 +1,69 @@ + +# 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 new file mode 100644 index 0000000..be88332 --- /dev/null +++ b/.ai/KNOWN_UNKNOWNS.md @@ -0,0 +1,69 @@ + +# 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. diff --git a/.ai/MANIFEST.json b/.ai/MANIFEST.json new file mode 100644 index 0000000..88d2189 --- /dev/null +++ b/.ai/MANIFEST.json @@ -0,0 +1,128 @@ +{ + "repo_url": "https://github.com/Pummelchen/XAIOS", + "indexed_commit": "8458ff956831e1b3b44a0cbcb396352ce28e3a01", + "previous_indexed_commit": "", + "generated_at": "2026-06-25T09:20:22Z", + "generator": "generic high-end AI coding agent", + "operation_mode": "bootstrap", + "primary_languages": ["C", "Assembly", "Python", "Shell"], + "frameworks": ["freestanding C99 OS", "UEFI", "QEMU", "VirtIO"], + "package_managers": ["pip for Python helper dependencies", "Homebrew or apt for host toolchain"], + "generated_files": [ + "README.md", + "AI_INDEX.md", + "AGENTS.md", + ".ai/START_HERE.md", + ".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", + ".ai/CHANGELOG.md", + ".ai/MANIFEST.json" + ], + "recommended_read_order": [ + "AI_INDEX.md", + "AGENTS.md", + ".ai/START_HERE.md", + ".ai/PROJECT_MAP.md", + ".ai/COMMANDS.md", + ".ai/TESTING.md", + ".ai/KNOWN_UNKNOWNS.md" + ], + "important_commands": { + "install": ["make bootstrap"], + "dev": ["make qemu", "make qemu-dry-run", "make xaios-ssh-bridge"], + "build": ["make all", "make image", "make image-x86_64"], + "test": ["make qemu-smoke", "make qemu-regression-suite", "make qemu-readiness-gate", "make qemu-full-os-rc"], + "lint": [], + "typecheck": ["make compile-check"] + }, + "source_files_used": [ + "README.md", + "CONTRIBUTING.md", + "SECURITY.md", + "HARDWARE-READINESS.md", + "PROJECT-TRACKER.md", + "LICENSE", + ".gitignore", + ".github/workflows/ci.yml", + "Makefile", + "requirements-dev.txt", + "docs/ARCHITECTURE.md", + "docs/API.md", + "docs/GETTING-STARTED.md", + "scripts/build-image.sh", + "scripts/run-qemu-aarch64.sh", + "scripts/qemu-smoke.py", + "scripts/qemu-abi-contract.py", + "scripts/qemu_gate_lib.py", + "kernel/core/kmain.c", + "kernel/include/xaios/syscall.h", + "kernel/user/syscall.c", + "kernel/runtime/security.c", + "userspace/include/xaios_user.h", + "tools/convert_gguf_to_xaios.py", + "contracts/qemu-rc-v1.json" + ], + "changed_files_since_previous_index": [], + "refresh_reason": ["initial bootstrap; no previous AI onboarding manifest found"], + "migrated_model_specific_files": [], + "deprecated_model_specific_files": [], + "preserved_model_specific_files_requiring_human_review": [], + "warnings": [ + "Direct git clone was unavailable in the runtime; inspection and writes used the GitHub connector.", + "QEMU results are correctness evidence only, not hardware performance proof." + ], + "unknowns": [ + "Hardware validation status beyond repository docs is unknown.", + "Production signing/key-management status is incomplete from inspected source/comments.", + "License status is ambiguous." + ], + "conflicts": [ + "Performance claims in README/wiki/tracker conflict with QEMU-correctness-only guidance in HARDWARE-READINESS.md and contracts/qemu-rc-v1.json.", + "Syscall source, docs/API.md, and contracts/qemu-rc-v1.json appear out of sync.", + "LICENSE contains MIT text and also says license to be decided." + ], + "refresh_policy": { + "recommended_mode": "event_driven_plus_periodic_check", + "regenerate_after_relevant_main_merges": true, + "staleness_check_on_pull_request": true, + "weekly_check_for_active_repos": true, + "monthly_check_for_stable_repos": true, + "force_review_after_days": 30, + "force_regeneration_after_meaningful_commits": 20, + "relevant_change_paths": [ + "README.md", + "package.json", + "pyproject.toml", + "go.mod", + "Cargo.toml", + "pom.xml", + "build.gradle", + "Dockerfile", + "docker-compose.yml", + ".github/workflows/**", + "src/**", + "app/**", + "apps/**", + "packages/**", + "services/**", + "migrations/**", + "db/**", + "prisma/**", + "tests/**", + "docs/architecture*", + "docs/deployment*", + "docs/security*", + "kernel/**", + "userspace/**", + "scripts/**", + "contracts/**", + "tools/**" + ] + } +} diff --git a/.ai/PLAYBOOKS.md b/.ai/PLAYBOOKS.md new file mode 100644 index 0000000..d6e39cf --- /dev/null +++ b/.ai/PLAYBOOKS.md @@ -0,0 +1,66 @@ + +# Playbooks + +## Add or change a syscall + +1. Inspect `kernel/include/xaios/syscall.h`, `kernel/user/syscall.c`, and `userspace/include/xaios_user.h`. +2. Add/adjust capability requirements and request structs. +3. Add userspace wrapper support in `userspace/lib/xaios_user.c` if needed. +4. Update `docs/API.md` and decide whether `contracts/qemu-rc-v1.json` must change. +5. Add/adjust self-tests and QEMU markers. +6. Validate with `make compile-check`, `python3 scripts/qemu-abi-contract.py`, and `make qemu-smoke` where possible. + +## Add a userspace app + +1. Create `userspace/apps/.c` with `#include `. +2. Add the app to `USER_APPS` in `scripts/build-image.sh`. +3. Launch it from `kernel/core/kmain.c` with the least-privilege capability mask. +4. Add smoke markers to `scripts/qemu-smoke.py` if the output is part of validation. +5. Run `make image && make qemu-smoke`. + +## Change kernel subsystem behavior + +1. Inspect the subsystem source and matching headers. +2. Check `kmain()` init/self-test order. +3. Maintain or add `*_self_test()` coverage. +4. Update gate markers/reports only if behavior intentionally changes. +5. Validate with `make compile-check` and a relevant QEMU gate. + +## Change filesystem/initramfs format + +1. Inspect `kernel/fs/`, `scripts/create-initfs.py`, and `contracts/qemu-rc-v1.json`. +2. Keep constants and contract schema aligned. +3. Update ABI/format gate logic if the contract changes. +4. Validate with filesystem gate, ABI contract, and smoke. + +## Change AI runtime/model format + +1. Inspect `kernel/runtime/cpu_ai_runtime.c`, `kernel/runtime/model_arena.c`, `kernel/runtime/ai_cell.c`, and `tools/convert_gguf_to_xaios.py`. +2. Keep model headers, tokenizer assumptions, quantization IDs, and admission checks aligned. +3. Avoid hardware performance claims without measured baselines. +4. Validate with CPU-AI suite, AI Cell gate, ABI/contract checks, and smoke. + +## Change security/update/SSH behavior + +1. Inspect `kernel/runtime/security.c`, `kernel/runtime/update.c`, `kernel/user/syscall.c`, and `userspace/sshd/`. +2. Preserve least privilege and credential-material rejection. +3. Do not relax auth/admin/update policy without human approval. +4. Validate with security/update/network gates and smoke. + +## Refresh AI onboarding docs + +1. Read `.ai/MANIFEST.json` and previous indexed commit. +2. Compare previous commit to current HEAD for high-impact paths. +3. Re-scan source/config/docs touched by build, test, API, architecture, security, deployment, or major docs changes. +4. Preserve correct human edits. +5. Update `AI_INDEX.md`, `AGENTS.md`, `.ai/*`, and README block idempotently. +6. Validate manifest JSON, local links, documentation-only diff, and secret-like patterns. diff --git a/.ai/PROJECT_MAP.md b/.ai/PROJECT_MAP.md new file mode 100644 index 0000000..aa22c98 --- /dev/null +++ b/.ai/PROJECT_MAP.md @@ -0,0 +1,83 @@ + +# Project map + +## Top-level structure + +| Path | Role | +|---|---| +| `boot/uefi/` | AArch64 UEFI loader, PE/COFF build, handoff to kernel. | +| `kernel/` | Freestanding kernel source. | +| `userspace/` | EL0 runtime, init/service manager, apps, worker, SSH daemon. | +| `scripts/` | Build image, create initfs, run QEMU, smoke/regression/readiness gates. | +| `contracts/` | QEMU release-candidate contract JSON. | +| `docs/` | Architecture, getting started, API docs. | +| `wiki/` | Local copies of selected design docs. | +| `.github/workflows/` | CI. | +| `benchmarks/` | Benchmark methodology. | +| `.qoder/repowiki/` | Generated repo-wiki material; non-authoritative for this onboarding system. | + +## Kernel module map + +| Path | Main responsibility | +|---|---| +| `kernel/arch/aarch64/` | Assembly entry, exception vectors, timer, GIC, MMU, SMP, PCI/SMMU/RTC/watchdog. | +| `kernel/core/` | `kmain()`, logging, telemetry, panic/assert, stack canaries. | +| `kernel/mm/` | PMM, NUMA, VMM support, heap/arena, ELF loader. | +| `kernel/dev/virtio/` | VirtIO transport, block, net drivers. | +| `kernel/fs/` | Initramfs and mutable filesystem. | +| `kernel/net/` | ARP, IPv4/IPv6, ICMP/ICMPv6, NDP, routing, DNS, socket buffers. | +| `kernel/runtime/` | AI Cell, CPU-AI runtime, model arena, security, sandbox, update, persistence, remote login, source index, Git workspace, agent protocol. | +| `kernel/sched/` | Scheduler and AArch64 context switch. | +| `kernel/user/` | Process lifecycle, service supervisor, syscall dispatch. | +| `kernel/include/xaios/` | Kernel public/internal headers. | + +## Userspace map + +| Path | Role | +|---|---| +| `userspace/include/xaios_user.h` | Userspace syscall numbers, wrappers, data structures. | +| `userspace/lib/` | Userspace start and support library. | +| `userspace/init/` | `/init` and init config. | +| `userspace/service-manager/` | Service manager and service descriptor. | +| `userspace/worker/` | Worker process used for lifecycle/scheduler validation. | +| `userspace/apps/` | Shell, tests, ML/network/system apps, `agenttest`. | +| `userspace/sshd/` | SSH/SFTP daemon implementation. | + +## Entrypoints + +- Bootloader: `boot/uefi/loader_main.c` +- Kernel entry/init: `kernel/core/kmain.c` +- Syscall dispatch: `kernel/user/syscall.c` +- Userspace API: `userspace/include/xaios_user.h`, `userspace/lib/xaios_user.c` +- Build image: `scripts/build-image.sh` +- QEMU run: `scripts/run-qemu-aarch64.sh`, `scripts/run-qemu-x86_64.sh` +- Primary smoke: `scripts/qemu-smoke.py` +- ABI gate: `scripts/qemu-abi-contract.py`, `scripts/qemu_gate_lib.py` +- Model conversion: `tools/convert_gguf_to_xaios.py` + +## External dependencies + +- Host toolchain: Clang, LLD, mtools, QEMU, Python 3. +- Python dev dependency: `paramiko==3.5.1` in `requirements-dev.txt`. +- Model converter runtime dependencies documented in README/tool: `gguf`, `numpy`. +- No Docker, database, ORM, migration framework, Node package manager, Rust/Cargo, Go module, Java build, or web framework detected in inspected files. + +## Important config/files + +- `Makefile` +- `.github/workflows/ci.yml` +- `.gitignore` +- `contracts/qemu-rc-v1.json` +- `userspace/init/xaios-init.conf` +- `userspace/service-manager/source-index.svc` +- `SECURITY.md` +- `HARDWARE-READINESS.md` diff --git a/.ai/SECURITY.md b/.ai/SECURITY.md new file mode 100644 index 0000000..bafb75b --- /dev/null +++ b/.ai/SECURITY.md @@ -0,0 +1,58 @@ + +# Security notes for AI agents + +## Verified security surfaces + +| Area | Files | Notes | +|---|---|---| +| Capability model | `kernel/include/xaios/syscall.h`, `kernel/user/syscall.c` | Syscalls map to required capabilities. | +| Credential-material rejection | `kernel/runtime/security.c` | Rejects selected credential/private-key/password/token/secret patterns in inputs and log buffers. | +| Filesystem policy | `kernel/runtime/security.c`, `kernel/fs/` | Read/write paths are policy constrained. | +| Sandbox/Git workspace | `kernel/runtime/sandbox.c`, `kernel/runtime/git_workspace.c`, `kernel/runtime/security.c` | Ownership and path checks. | +| Update/rollback | `kernel/runtime/update.c`, `kernel/runtime/security.c` | Admin/update capability and dev-mode signature format checks. | +| SSH/SFTP | `userspace/sshd/` | Remote login and file-transfer surface. | +| QEMU host forwarding | `scripts/run-qemu-aarch64.sh` | Default host forwarding maps host port 2222 to guest port 22 unless disabled. | + +## Rules for AI agents + +- Never commit credentials, API keys, private keys, tokens, passwords, secret benchmark data, or host-specific auth material. +- Do not weaken capability checks, user-buffer validation, credential-material rejection, sandbox path validation, update authorization, or admin gating without explicit human approval. +- Treat comments in `security_validate_update_signature()` as authoritative for current source: QEMU dev-mode signature validation is format/generation validation, not production cryptographic verification. +- Do not claim the SSH/update/security model is production-ready solely from docs; inspect current source and tests. +- Do not expose local host usernames, paths, SSH keys, or environment values in docs/logs. + +## Sensitive implementation details + +- `kernel/runtime/security.c` includes counters for denied operations, capability denials, filesystem denials, workspace/sandbox denials, rollback denials, update policy rejects, signature/key accepts/rejects, credential rejects, admin denials, and sandbox escape rejects. +- `kernel/user/syscall.c` validates syscall numbers, capabilities, and selected user buffers. +- `userspace/sshd/` is security-sensitive because it implements remote access behavior and SFTP. +- `scripts/run-qemu-aarch64.sh` may expose local service ports through QEMU user networking. + +## Validation + +For security-sensitive changes, run the narrowest relevant gate plus smoke: + +```sh +make compile-check +make qemu-security-gate +make qemu-smoke +``` + +For update or filesystem changes, also consider: + +```sh +make qemu-update-gate +make qemu-filesystem-gate +make qemu-readiness-gate +``` + +Record any skipped gate with a concrete reason. diff --git a/.ai/START_HERE.md b/.ai/START_HERE.md new file mode 100644 index 0000000..77aa16b --- /dev/null +++ b/.ai/START_HERE.md @@ -0,0 +1,44 @@ + +# Start here + +Paste this prompt into a fresh AI coding session for XAIOS: + +```text +You are working in the XAIOS repository. Start by reading AI_INDEX.md, AGENTS.md, .ai/PROJECT_MAP.md, .ai/COMMANDS.md, .ai/TESTING.md, and .ai/KNOWN_UNKNOWNS.md. Then inspect the current source files relevant to my task before proposing or making edits. + +When you summarize the repo, separate verified facts, assumptions, inferences, unknowns, and conflicts. Treat onboarding docs as guidance only; current source code and build/test config are the source of truth. + +Before editing, produce a concise plan with files to inspect/change and validations to run. Prefer small, reviewable changes. Do not modify generated build artifacts, do not create vendor/model-specific AI files, and do not make hardware performance claims from QEMU-only results. + +After editing, report changed files, tests or commands run, tests skipped with reasons, and remaining risks. +``` + +## Reading order + +1. `AI_INDEX.md` +2. `AGENTS.md` +3. `.ai/PROJECT_MAP.md` +4. `.ai/ARCHITECTURE.md` +5. `.ai/COMMANDS.md` +6. `.ai/TESTING.md` +7. `.ai/SECURITY.md` +8. `.ai/KNOWN_UNKNOWNS.md` + +For large tasks, do not load every file at once. Start from the task map in `AI_INDEX.md`, then inspect the narrow source slice. + +## Required behavior + +- Inspect current source/config before editing. +- Cite source file paths in reasoning. +- Keep QEMU correctness evidence separate from hardware performance claims. +- Preserve human documentation edits when refreshing onboarding files. +- Ask a human before resolving license ambiguity, changing security policy, or updating performance claims without measurements. diff --git a/.ai/TESTING.md b/.ai/TESTING.md new file mode 100644 index 0000000..547fe9b --- /dev/null +++ b/.ai/TESTING.md @@ -0,0 +1,74 @@ + +# Testing + +## Test model + +No conventional unit-test framework was detected. Validation is based on: + +- kernel/userspace self-tests run during boot; +- Python QEMU gates that search serial output and telemetry markers; +- ABI/contract Python checks; +- CI compile checks and QEMU smoke/regression jobs. + +Evidence: +- `kernel/core/kmain.c` +- `scripts/qemu-smoke.py` +- `scripts/qemu-abi-contract.py` +- `scripts/qemu_gate_lib.py` +- `.github/workflows/ci.yml` +- `Makefile` + +## Main validations + +| Validation | Command | When to use | +|---|---|---| +| Syntax-only C check | `make compile-check` | Small C changes; quicker than booting QEMU. | +| Smoke gate | `make qemu-smoke` | Most code changes. | +| ABI contract | `python3 scripts/qemu-abi-contract.py` | Syscall, initfs, contract, model format changes. | +| Regression | `make qemu-regression-suite` | Broader kernel/userspace changes. | +| Network suite | `make qemu-network-suite` | Network/socket/SSH-adjacent changes. | +| CPU-AI suite | `make qemu-cpu-ai-suite` | AI runtime/model changes. | +| Readiness | `make qemu-readiness-gate` | Changes that may affect QEMU readiness. | +| Full OS RC | `make qemu-full-os-rc` | Release-candidate or hardware-entry decisions. | + +## CI behavior + +GitHub Actions workflow `.github/workflows/ci.yml` runs: + +- compile-check for kernel C files; +- compile-check for userspace C files; +- ABI contract validation; +- `make image` followed by `scripts/qemu-smoke.py`; +- `make image` followed by `scripts/qemu-regression-suite.py`. + +CI installs toolchain packages with apt and sets `XAIOS_QEMU_SMOKE_TIMEOUT=120` for QEMU smoke/regression jobs. + +## Focused testing guidance + +- Syscall/API change: run `make compile-check` and `python3 scripts/qemu-abi-contract.py`; then `make qemu-smoke` if QEMU is available. +- Userspace app change: run `make image && make qemu-smoke`; update smoke markers if expected output changes. +- Security/update change: run relevant security/update gates plus smoke. +- Filesystem/persistence change: run filesystem/update/readiness gates. +- Network/SSH change: run network suite and SSH smoke if environment supports it. +- Docs-only change: validate Markdown links, manifest JSON, changed-file scope, and secret-like patterns; source tests may be skipped with explanation. + +## Fixtures and generated reports + +- QEMU marker lists live in scripts such as `scripts/qemu-smoke.py`. +- Contract data lives in `contracts/qemu-rc-v1.json`. +- Gate reports are generated under `build/` and should not be committed. + +## Known testing caveats + +- QEMU gates are correctness evidence only and do not authorize hardware performance claims. +- `contracts/qemu-rc-v1.json` appears behind source for syscalls beyond 28; validate intent before treating contract coverage as complete. +- Local QEMU gates require host QEMU/firmware/toolchain availability. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8405bcc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,86 @@ + +# AGENTS.md + +Generic instructions for high-capability AI coding agents working in XAIOS. + +## Start every session this way + +1. Read `AI_INDEX.md`. +2. Read `.ai/START_HERE.md`, `.ai/PROJECT_MAP.md`, `.ai/COMMANDS.md`, `.ai/TESTING.md`, and `.ai/KNOWN_UNKNOWNS.md` as needed. +3. Inspect the current source/config files relevant to the task before editing. +4. Summarize verified facts, assumptions, inferences, and unknowns separately. +5. Make a small implementation plan before changing files. + +These onboarding files are not authoritative when they conflict with source. Trust current source code first, then build/test config, CI, lockfiles/package metadata, tests, current docs, older docs, and only then inference. + +## Scope and safety rules + +- Do not modify product/source code unless the user asked for an implementation change. +- Do not commit credentials, private keys, API keys, tokens, passwords, or secret benchmark data. +- Do not use QEMU correctness gates as proof of hardware performance. +- Do not add model- or vendor-specific AI instruction files. +- Do not add external generated wiki/deep-repo-learning links to onboarding docs. +- Avoid destructive commands, production migrations, or deploy commands. +- Keep changes small and reviewable. + +## Project-specific engineering rules + +- Kernel and userspace C are freestanding C99. Do not assume libc, POSIX headers, dynamic allocation, filesystem APIs, or host OS services unless present in this repo. +- Follow existing naming: module prefixes in kernel code (`pmm_`, `vmm_`, `smmu_`, etc.) and `xaios_` for userspace wrappers. +- Use fixed-size buffers in userspace unless current source proves a safe allocator exists. +- Kernel modules should maintain `*_self_test()` coverage and correct init ordering in `kernel/core/kmain.c`. +- Syscall changes must update all relevant surfaces: `kernel/include/xaios/syscall.h`, `kernel/user/syscall.c`, `userspace/include/xaios_user.h`, `docs/API.md`, `contracts/qemu-rc-v1.json`, and ABI validation scripts if needed. +- Userspace app additions usually require edits to `userspace/apps/`, `scripts/build-image.sh`, `kernel/core/kmain.c`, and smoke-test markers. + +## Validation expectations + +For documentation-only changes, validate links, JSON, changed-file scope, and secret-like patterns. + +For source changes, choose the smallest relevant validation set: + +- Syntax-only C check: `make compile-check` +- Primary smoke: `make qemu-smoke` +- ABI contract: `python3 scripts/qemu-abi-contract.py` +- Regression: `make qemu-regression-suite` +- Readiness/RC: `make qemu-readiness-gate`, `make qemu-full-os-rc` + +Do not claim tests passed unless you actually ran them. + +## Planning and reporting + +Before editing, state: + +- verified source files inspected; +- assumptions and risks; +- planned files to change; +- validation to run or skip, with reason. + +After editing, report: + +- changed files; +- behavioral impact; +- tests/commands run; +- tests skipped and why; +- unresolved risks. + +## Extra caution areas + +- Boot and memory: `boot/uefi/`, `kernel/arch/aarch64/`, `kernel/mm/`, `kernel/core/kmain.c` +- Syscalls/capabilities: `kernel/include/xaios/syscall.h`, `kernel/user/syscall.c`, `userspace/include/xaios_user.h` +- Persistence/update/security: `kernel/fs/`, `kernel/runtime/persistence.c`, `kernel/runtime/update.c`, `kernel/runtime/security.c` +- SSH/network: `userspace/sshd/`, `kernel/net/`, `kernel/runtime/network_stack.c` +- AI runtime/model format: `kernel/runtime/cpu_ai_runtime.c`, `kernel/runtime/model_arena.c`, `tools/convert_gguf_to_xaios.py` +- Gates/contracts: `contracts/qemu-rc-v1.json`, `scripts/qemu_gate_lib.py`, `scripts/qemu-*.py` + +## Refresh policy + +Update these onboarding files when changes affect architecture, build/test commands, API/syscalls, contracts, CI, security model, deployment/run paths, major docs, or significant directory layout. On refresh, preserve correct human edits, remove stale generated claims, and record conflicts in `.ai/KNOWN_UNKNOWNS.md`. diff --git a/AI_INDEX.md b/AI_INDEX.md new file mode 100644 index 0000000..87aeb69 --- /dev/null +++ b/AI_INDEX.md @@ -0,0 +1,138 @@ + +# AI Index: XAIOS + +## Snapshot + +| Field | Value | +|---|---| +| Repository | `Pummelchen/XAIOS` | +| Indexed commit | `8458ff956831e1b3b44a0cbcb396352ce28e3a01` | +| Operation mode | `bootstrap` | +| Default branch | `main` | +| Primary languages | C99, Assembly, Python, Shell | +| Runtime target | Freestanding OS, currently AArch64 UEFI on QEMU `virt`; x86_64 and hardware ports are present/planned areas. | + +## Read first + +1. `AI_INDEX.md` — this map. +2. `AGENTS.md` — repository-specific working rules for any AI coding agent. +3. `.ai/START_HERE.md` — compact first-session prompt. +4. `.ai/PROJECT_MAP.md` — top-level and module map. +5. `.ai/COMMANDS.md` and `.ai/TESTING.md` — validation commands and gates. +6. `.ai/KNOWN_UNKNOWNS.md` — conflicts, stale docs, and questions to ask humans. + +Always inspect current source files before editing. These onboarding files are guidance, not a source-code substitute. + +## Verified repository purpose + +XAIOS is a freestanding operating-system project for CPU-only AI inference and embedded AI-agent workloads. It builds UEFI boot artifacts, a monolithic kernel, userspace programs, initramfs images, QEMU runners, and Python validation gates. + +Evidence: +- `README.md` +- `docs/ARCHITECTURE.md` +- `docs/GETTING-STARTED.md` +- `kernel/core/kmain.c` +- `scripts/build-image.sh` + +## Architecture summary + +Boot starts in `boot/uefi/loader_main.c`, which loads `kernel.elf` and passes boot information to `kmain()` in `kernel/core/kmain.c`. `kmain()` initializes exceptions, timers, SMP/topology, NUMA/PMM/VMM, SMMU/PCI/GIC, VirtIO block/network, persistence, mutable filesystem, security, source index, Git workspace, sandboxing, services, syscalls, scheduler, model arena, CPU-AI runtime, AI Cell, agent protocol, telemetry, and then runs userspace programs. + +Runtime structure: +- Kernel code: `kernel/` +- Userspace runtime/apps/daemon: `userspace/` +- Build and QEMU gates: `scripts/` +- ABI/release-candidate contracts: `contracts/` +- User docs: `docs/`, `wiki/`, `HARDWARE-READINESS.md`, `PROJECT-TRACKER.md` + +## Directory map + +| Path | Responsibility | Notes | +|---|---|---| +| `boot/uefi/` | AArch64 UEFI loader and linker script. | Earliest boot code. | +| `kernel/arch/aarch64/` | EL1 entry, vectors, timer, GIC, MMU, SMP, SMMU, PCI, RTC, watchdog. | Hardware-sensitive. | +| `kernel/core/` | `kmain`, logging, telemetry, panic/assert, stack canaries. | `kmain.c` is the central init map. | +| `kernel/mm/` | PMM, NUMA, VMM support, heap/arena, ELF loading. | Boot and process-loader sensitive. | +| `kernel/dev/virtio/` | VirtIO transport, block, network drivers. | Recent HEAD changes block-device selection. | +| `kernel/fs/` | Initramfs and mutable persistent filesystem. | Coupled to `scripts/create-initfs.py` and contract JSON. | +| `kernel/net/` | ARP, IPv4/IPv6, ICMP/ICMPv6, NDP, DNS, routing, socket buffers. | Validate with network gates. | +| `kernel/runtime/` | AI Cell, CPU-AI runtime, model arena, security, sandbox, persistence, update, remote login, agent protocol, source index, Git workspace. | Security/AI-runtime sensitive. | +| `kernel/user/` | Process table, service supervisor, syscall dispatch. | API and capability sensitive. | +| `userspace/` | EL0 runtime, init, service manager, worker, apps, SSH daemon. | Built into initramfs by `scripts/build-image.sh`. | +| `scripts/` | Build scripts, QEMU runners, gates, report generation, initfs creation. | Primary validation surface. | +| `contracts/` | Machine-readable QEMU release-candidate contract. | May lag newer source. | +| `.github/workflows/` | CI compile, ABI, build/smoke, regression jobs. | Ubuntu toolchain/QEMU path. | + +## Entrypoints and commands + +| Task | Command | +|---|---| +| Toolchain verification | `make bootstrap` | +| Default build | `make all` | +| Build AArch64 image | `make image` | +| Build x86_64 image | `make image-x86_64` | +| Interactive AArch64 QEMU | `make qemu` or `make qemu-aarch64` | +| Dry-run QEMU commands | `make qemu-dry-run` | +| Primary smoke gate | `make qemu-smoke` | +| Full readiness gate | `make qemu-readiness-gate` | +| Full OS release-candidate gate | `make qemu-full-os-rc` | +| Compile syntax check | `make compile-check` | +| SSH bridge | `make xaios-ssh-bridge` | + +## Common task map + +| Change type | Start with | Also inspect/update | +|---|---|---| +| Boot/UEFI | `boot/uefi/`, `scripts/build-image.sh` | `kernel/core/kmain.c`, `docs/ARCHITECTURE.md` | +| Kernel subsystem | Relevant `kernel/*` module | Matching header, `kmain()` init/self-test order, QEMU gate markers | +| Syscall/API | `kernel/include/xaios/syscall.h` | `kernel/user/syscall.c`, `userspace/include/xaios_user.h`, `docs/API.md`, `contracts/qemu-rc-v1.json`, `scripts/qemu_gate_lib.py` | +| Userspace app | `userspace/apps/` | `scripts/build-image.sh`, `kernel/core/kmain.c`, `scripts/qemu-smoke.py` | +| SSH/network | `userspace/sshd/`, `kernel/net/`, `kernel/runtime/network_stack.c` | Socket syscalls and network gates | +| Security/update | `kernel/runtime/security.c`, `kernel/runtime/update.c` | `SECURITY.md`, `.ai/SECURITY.md`, QEMU security/update gates | +| CPU-AI/model format | `kernel/runtime/cpu_ai_runtime.c`, `kernel/runtime/model_arena.c`, `tools/convert_gguf_to_xaios.py` | `contracts/qemu-rc-v1.json`, model docs, smoke markers | +| CI/gates | `.github/workflows/ci.yml`, `Makefile`, `scripts/qemu-*.py` | `.ai/TESTING.md`, `HARDWARE-READINESS.md` | + +## Important conventions + +- C is freestanding C99, compiled with `-Wall -Wextra -Werror`; do not assume libc or POSIX in kernel/userspace. +- Userspace APIs use `userspace/include/xaios_user.h` and fixed-size buffers; no documented userspace `malloc` path. +- New kernel modules should include or update self-tests and ensure init/self-test order in `kmain()` is correct. +- Syscalls require capability mapping and user-buffer validation. +- QEMU gates are correctness evidence. Do not make hardware performance claims from QEMU-only results. + +## Security-sensitive areas + +- `kernel/runtime/security.c` +- `kernel/user/syscall.c` +- `kernel/fs/`, `kernel/runtime/persistence.c`, `kernel/runtime/update.c` +- `kernel/runtime/sandbox.c`, `kernel/runtime/git_workspace.c`, `kernel/runtime/source_index.c` +- `userspace/sshd/` +- `scripts/run-qemu-aarch64.sh` host forwarding and local SSH bridge + +## Generated or do-not-edit zones + +- Ignored generated outputs: `build/`, `out/`, `dist/`, `*.img`, `*.efi`, `*.elf`, `*.bin`, `*.map`, `*.log`, `.cache/`, `__pycache__/`, `compile_commands.json`. +- Do not hand-edit generated QEMU reports under `build/`. +- `.qoder/repowiki/` appears to be generated repository-wiki material; do not treat it as source of truth. + +## Known conflicts and unknowns + +High-impact items are tracked in `.ai/KNOWN_UNKNOWNS.md`: + +- Performance language in README/wiki/tracker conflicts with `HARDWARE-READINESS.md` and `contracts/qemu-rc-v1.json`, which restrict QEMU outputs to correctness evidence. +- Source declares syscalls through `XAIOS_SYSCALL_AGENT_DISPATCH` number 34, while `docs/API.md` documents through 33 and `contracts/qemu-rc-v1.json` lists through 28. +- `LICENSE` contains MIT text but also says “License to be decided”; README also says license is undecided. +- Some docs omit current `agenttest`/agent-dispatch paths visible in source. + +## What changed since last index + +Initial bootstrap. No previous AI onboarding manifest or recognizable generic onboarding file set was found on `main`. diff --git a/README.md b/README.md index bbf12a8..6c7d286 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,13 @@ # XAI OS +> **AI agents: start here** +> +> Before making changes, read [`AI_INDEX.md`](./AI_INDEX.md), then [`AGENTS.md`](./AGENTS.md). +> The generic first-session prompt is in [`.ai/START_HERE.md`](./.ai/START_HERE.md). +> +> These files summarize the repository architecture, commands, conventions, risks, and recommended reading order for a fresh AI session. +> They are vendor-neutral and intended for any high-end AI coding agent. + **XAI OS is a supercomputer-grade operating system for CPU-only AI inference at scale.** ## Purpose