@agentikos/omega-os 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Moison — Agentik OS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# Omega OS
+
+**An agentic operating system for a VPS. One command installs it; it runs your
+software-engineering agents 24/7, takes missions over Telegram, and ships
+production code without supervision — with completion that is *verified*, never
+*claimed*.**
+
+Omega OS is the from-scratch, installable successor of the Omega orchestration
+system. It is built on one hard principle:
+
+> **An agent must never be able to say "done" and be wrong.**
+> Completion is a state the engine *derives* from observable facts — never a
+> claim an agent writes about itself.
+
+---
+
+## Why Omega OS exists
+
+Most agentic frameworks have the same three structural bugs:
+
+1. **Completion is self-declared.** The worker writes "I finished". You trust the
+   actor with the most incentive to declare itself done.
+2. **Completion is *observed*, not *computed*.** The parent polls files, races,
+   reads stale state.
+3. **A parent can finish before its children.** Nothing mechanically stops an
+   orchestrator from closing while its workers still run.
+
+Omega OS makes all three **structurally impossible** — see
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) and
+[`docs/ENGINE-SPEC.md`](docs/ENGINE-SPEC.md).
+
+## What makes it different
+
+| | Omega OS |
+|---|---|
+| **Verified completion** | A task is `VERIFIED` only after an independent verifier *runs the real flow* (dev server, endpoints, UI path). Lying "it's done" is impossible. |
+| **Structured concurrency** | A parent scope cannot close until every child is in a terminal state. Join barrier, not polling. |
+| **Event-sourced** | One append-only log is the single source of truth. Free audit trail, time-travel debug, zero races. |
+| **Topology-as-data** | `AISB → Oracle → Worker` is *one* graph. New orchestration = new graph, **zero engine code**. |
+| **Multi-LLM by contract** | Claude, GLM, OpenAI behind one `AgentProvider` interface. Swap by config. |
+| **Account pool** | Multiple Claude Code Max accounts pooled — N accounts yield the sum of their rate limits as throughput. `omega account` / `omega billing`. |
+| **Autonomous agents** | Long-running agents are first-class `Node`s of the *same* engine — not a bolted-on subsystem. |
+| **Self-improving** | Eight *educators* regenerate the system's own prompts, skills, agents and automations into the SSOT, under a quality gate. |
+
+## The 8-block rack
+
+Everything installs under one master folder, `~/Omega/`, as eight pluggable
+`Agentik_*` blocks — each a single nature, a single lifecycle, openable alone
+over SSH:
+
+```
+Omega/
+├── Agentik_SSOT/           truth — rules, skills, schemas, MCP catalog (git, read-only in prod)
+├── Agentik_Engine/         the generic Python engine — reducer, store, barrier, supervisor
+├── Agentik_Orchestration/  definitions — topologies, roles, verifier, educators, autonomous
+├── Agentik_Providers/      LLM wiring — one folder per provider, zero business logic
+├── Agentik_Coding/         your projects — git worktrees
+├── Agentik_Tools/          the "/Applications" — third-party installs, MCP servers, RAG engine
+├── Agentik_Runtime/        live state — event log, sessions, verdicts, memory.db
+└── Agentik_Extra/          ephemeral + config + encrypted secrets
+```
+
+Full reference + lifecycle table: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Install
+
+One command on a fresh VPS (Ubuntu) or workstation (macOS):
+
+```bash
+npx @agentikos/omega-os                  # interactive
+```
+
+Headless (CI / scripted provisioning):
+
+```bash
+npx @agentikos/omega-os --manifest bootstrap/manifest.example.yaml --non-interactive
+```
+
+From a git clone (no npm needed):
+
+```bash
+git clone https://github.com/agentik-os/OmegaOS && cd OmegaOS && bash install.sh
+```
+
+The installer is **idempotent and resumable** — if it stops at step 5/8,
+re-running resumes. It detects the OS, installs dependencies, builds the
+`~/Omega/` tree, wires the engine, lets you pick MCP servers and Claude Code
+plugins from a catalog, connects a Telegram bot + group, registers your
+autonomous agents, installs `systemd` services (the 24/7 layer), and runs
+`omega doctor` to validate everything.
+
+Details: [`docs/INSTALL.md`](docs/INSTALL.md).
+
+## Documentation
+
+| Doc | Content |
+|---|---|
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | The full architecture — 8 blocks, philosophy, RAG, lifecycle |
+| [`docs/ENGINE-SPEC.md`](docs/ENGINE-SPEC.md) | The orchestration engine — FSM, reducer, join barrier, audit gate |
+| [`docs/AUTONOMOUS-AGENTS.md`](docs/AUTONOMOUS-AGENTS.md) | Long-running autonomous agents as first-class nodes |
+| [`docs/MCP-AND-PLUGINS.md`](docs/MCP-AND-PLUGINS.md) | MCP servers & Claude Code plugins — catalog, placement, install |
+| [`docs/ACCOUNT-AND-BILLING.md`](docs/ACCOUNT-AND-BILLING.md) | Claude Max account pool, login flow, per-account billing |
+| [`docs/INSTALL.md`](docs/INSTALL.md) | Install guide — profiles, manifest, troubleshooting |
+
+## Status
+
+This repository is the **product**: its installer, run on a fresh machine,
+produces a running `~/Omega/` deployment.
+
+The **orchestration runtime is implemented and tested.** `omega run` executes a
+real mission (`Oracle → Worker → Verifier → VERIFIED`), the Oracle emits a
+whitepaper **PDF report**, progress streams live to a **Telegram topic** with a
+progress bar, and `omega project` creates a project with its bound topic.
+
+The **Quality Arsenal — 18 forensic audits** (code, security, performance, a11y,
+…) is wired into the verification gate: when a worker claims done, the
+`ArsenalGate` runs the audits that apply (deterministic tools + an agentic
+Gestalt-Popper falsification pass) and a task reaches `VERIFIED` only if it
+passes. The engine test suite is green.
+
+Still build-out: the 8 educators, the RAG subsystem, autonomous-agent daemons,
+and the 24/7 service layer — see [`docs/RUNTIME-PLAN.md`](docs/RUNTIME-PLAN.md).
+
+---
+
+*Omega OS — the intelligence was always there. This gives it a body that does
+not shake.*

package/bin/omega-os.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Omega OS — npx bootstrap launcher.
+ *
+ *   npx @agentik-os/omega-os [--profile vps|workstation|minimal]
+ *                            [--manifest FILE] [--non-interactive] [--force]
+ *
+ * A thin launcher. npm has already fetched the whole package (install.sh,
+ * bootstrap/, omega/, docs/) into its cache; this script runs install.sh with
+ * the OS-native bash. The engine itself is Python — npx is only the one-command
+ * entry point, so a fresh machine needs nothing pre-installed but Node.
+ */
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const pkgRoot = path.resolve(__dirname, "..");
+const installer = path.join(pkgRoot, "install.sh");
+
+function fail(msg) {
+  console.error(`omega-os: ${msg}`);
+  process.exit(1);
+}
+
+if (process.platform === "win32") {
+  fail("Windows is not supported — use a Linux VPS or macOS.");
+}
+if (!fs.existsSync(installer)) {
+  fail("install.sh is missing from the package — the download is incomplete.");
+}
+
+console.log("");
+console.log("  Omega OS — npx bootstrap");
+console.log("  -> handing off to install.sh");
+console.log("");
+
+const args = process.argv.slice(2);
+const result = spawnSync("bash", [installer, ...args], {
+  stdio: "inherit",
+  cwd: pkgRoot,
+});
+
+if (result.error) {
+  fail(`could not run install.sh — ${result.error.message}`);
+}
+process.exit(result.status === null ? 1 : result.status);

package/bootstrap/lib/common.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Omega OS installer — shared helpers. Sourced by install.sh.
+
+# --- paths ---
+OMEGA_HOME="${OMEGA_HOME:-$HOME/Omega}"
+STATE_DIR="$OMEGA_HOME/Agentik_Extra/var"
+STATE_FILE="$STATE_DIR/.install-state"
+LOG_FILE="$STATE_DIR/logs/install.log"
+
+# --- colours (only when attached to a tty) ---
+if [ -t 1 ]; then
+  C_OK=$'\033[32m'; C_ERR=$'\033[31m'; C_INFO=$'\033[36m'; C_DIM=$'\033[2m'; C_RST=$'\033[0m'
+else
+  C_OK=''; C_ERR=''; C_INFO=''; C_DIM=''; C_RST=''
+fi
+
+log()  { mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+         printf '%s\n' "$*" | tee -a "$LOG_FILE" 2>/dev/null || printf '%s\n' "$*"; }
+info() { log "${C_INFO}::${C_RST} $*"; }
+ok()   { log "${C_OK}ok${C_RST} $*"; }
+err()  { log "${C_ERR}!!${C_RST} $*" >&2; }
+die()  { err "$*"; exit 1; }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# --- OS / package-manager detection ---
+detect_os() {
+  case "$(uname -s)" in
+    Linux)  OMEGA_OS="linux" ;;
+    Darwin) OMEGA_OS="macos" ;;
+    *)      die "unsupported OS: $(uname -s)" ;;
+  esac
+  if [ "$OMEGA_OS" = "linux" ]; then
+    if   have apt-get; then OMEGA_PKG="apt"
+    elif have dnf;     then OMEGA_PKG="dnf"
+    else                    OMEGA_PKG="unknown"; fi
+  else
+    OMEGA_PKG="brew"
+  fi
+  export OMEGA_OS OMEGA_PKG
+}
+
+# --- step state (idempotent / resumable) ---
+step_done()   { [ -f "$STATE_FILE" ] && grep -qx "$1" "$STATE_FILE"; }
+mark_done()   { mkdir -p "$STATE_DIR"; printf '%s\n' "$1" >> "$STATE_FILE"; }
+reset_state() { rm -f "$STATE_FILE"; }
+
+# run_step <name> <function>
+run_step() {
+  local name="$1" fn="$2"
+  if step_done "$name" && [ "${FORCE:-0}" != "1" ]; then
+    log "${C_DIM}-- skip $name (already done)${C_RST}"
+    return 0
+  fi
+  info "step $name"
+  if "$fn"; then
+    mark_done "$name"
+    ok "$name"
+  else
+    die "step $name failed — fix the cause and re-run install.sh (it resumes here)"
+  fi
+}
+
+# ask <var> <prompt> <default> — respects --non-interactive
+ask() {
+  local __var="$1" __prompt="$2" __default="${3:-}" __reply
+  if [ "${NONINTERACTIVE:-0}" = "1" ]; then
+    printf -v "$__var" '%s' "$__default"
+    return 0
+  fi
+  read -r -p "$__prompt ${__default:+[$__default] }" __reply || true
+  printf -v "$__var" '%s' "${__reply:-$__default}"
+}

package/bootstrap/lib/steps.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Omega OS installer — the 8 steps. Each function returns 0 on success, 1 on
+# failure. run_step (common.sh) records success so re-runs resume.
+
+OMEGA_BLOCKS="Agentik_SSOT Agentik_Engine Agentik_Orchestration Agentik_Providers \
+Agentik_Coding Agentik_Tools Agentik_Runtime Agentik_Extra"
+
+# --- 00 -----------------------------------------------------------------------
+step_preflight() {
+  info "OS=$OMEGA_OS  pkg=$OMEGA_PKG  OMEGA_HOME=$OMEGA_HOME"
+  if [ "$(id -u)" -eq 0 ]; then
+    err "do not run as root — create and use a non-root user with sudo"
+    return 1
+  fi
+  have git || { err "git is required"; return 1; }
+  [ "$OMEGA_PKG" = "unknown" ] && { err "no supported package manager (apt/dnf/brew)"; return 1; }
+  mkdir -p "$STATE_DIR/logs"
+  return 0
+}
+
+# --- 10 -----------------------------------------------------------------------
+step_system_deps() {
+  local pkgs="python3 git tmux sqlite3 jq curl"
+  case "$OMEGA_PKG" in
+    apt)  sudo apt-get update -qq && sudo apt-get install -y -qq $pkgs python3-venv ;;
+    dnf)  sudo dnf install -y -q $pkgs ;;
+    brew) brew install $pkgs 2>/dev/null || true ;;
+    *)    err "install manually: $pkgs"; return 1 ;;
+  esac
+  if ! have uv && [ ! -x "$HOME/.local/bin/uv" ]; then
+    info "installing uv (Python package/venv manager)"
+    curl -LsSf https://astral.sh/uv/install.sh | sh || { err "uv install failed"; return 1; }
+  fi
+  return 0
+}
+
+# --- 20 -----------------------------------------------------------------------
+step_structure() {
+  local b
+  for b in $OMEGA_BLOCKS; do mkdir -p "$OMEGA_HOME/$b"; done
+  mkdir -p "$OMEGA_HOME/Agentik_Runtime"/{eventlog,sessions,verdicts,memory,locks,snapshots}
+  mkdir -p "$OMEGA_HOME/Agentik_Extra"/{var/cache,var/tmp,var/logs,staging/promotion,etc/secrets}
+  chmod 700 "$OMEGA_HOME/Agentik_Extra/etc/secrets" 2>/dev/null || true
+  # deploy the repo's source blocks into the live tree
+  if [ -d "${OMEGA_REPO:-}/omega" ]; then
+    cp -R "$OMEGA_REPO/omega/." "$OMEGA_HOME/"
+    ok "deployed source blocks from $OMEGA_REPO/omega"
+  else
+    err "repo source not found at \$OMEGA_REPO/omega"; return 1
+  fi
+  ok "8-block tree ready at $OMEGA_HOME"
+  return 0
+}
+
+# --- 30 -----------------------------------------------------------------------
+step_engine() {
+  local uv_bin; uv_bin="$(command -v uv || echo "$HOME/.local/bin/uv")"
+  [ -x "$uv_bin" ] || { err "uv not found after step 10"; return 1; }
+  cd "$OMEGA_HOME/Agentik_Engine" || { err "engine block missing"; return 1; }
+  "$uv_bin" venv >/dev/null 2>&1     || { err "uv venv failed"; return 1; }
+  "$uv_bin" pip install -e . >/dev/null 2>&1 || { err "engine install failed"; return 1; }
+  mkdir -p "$OMEGA_HOME/Agentik_Tools/bin"
+  ln -sf "$OMEGA_HOME/Agentik_Engine/.venv/bin/omega" "$OMEGA_HOME/Agentik_Tools/bin/omega"
+  ok "engine installed — omega CLI at Agentik_Tools/bin/omega"
+  return 0
+}
+
+# --- 40 -----------------------------------------------------------------------
+step_mcp() {
+  local catalog="$OMEGA_HOME/Agentik_SSOT/mcp/mcp-catalog.yaml"
+  [ -f "$catalog" ] || { err "MCP catalog missing: $catalog"; return 1; }
+  info "MCP catalog present ($(grep -c '^- id:' "$catalog" 2>/dev/null || echo '?') entries)"
+  if [ "${NONINTERACTIVE:-0}" = "1" ]; then
+    info "headless — MCP selection comes from the manifest (\`mcp:\` list)"
+  else
+    info "interactive — the MCP/plugin checklist reads $catalog"
+  fi
+  # Build-out: render the checklist, install selected servers into
+  # Agentik_Tools/<id>/, write Agentik_SSOT/mcp/mcp-config.yaml, run `omega sync`.
+  # See docs/MCP-AND-PLUGINS.md.
+  return 0
+}
+
+# --- 50 -----------------------------------------------------------------------
+step_telegram() {
+  local token
+  ask token "Telegram bot token (from @BotFather)" "${TELEGRAM_TOKEN:-}"
+  if [ -z "$token" ]; then
+    err "a Telegram bot token is required (or install with --profile minimal)"
+    return 1
+  fi
+  if have curl; then
+    if ! curl -s "https://api.telegram.org/bot${token}/getMe" | grep -q '"ok":true'; then
+      err "Telegram token rejected by the API"
+      return 1
+    fi
+  fi
+  local sec="$OMEGA_HOME/Agentik_Extra/etc/secrets"
+  mkdir -p "$sec"
+  printf 'TELEGRAM_TOKEN=%s\n' "$token" > "$sec/telegram.env"
+  chmod 600 "$sec/telegram.env"
+  ok "Telegram bot validated and wired (secret stored in the vault)"
+  return 0
+}
+
+# --- 60 -----------------------------------------------------------------------
+step_services() {
+  if [ "${PROFILE:-vps}" = "minimal" ]; then
+    info "minimal profile — no services installed"
+    return 0
+  fi
+  if [ "$OMEGA_OS" = "linux" ]; then
+    local unitdir="$HOME/.config/systemd/user"
+    mkdir -p "$unitdir"
+    _systemd_unit "Omega OS engine"               "$OMEGA_HOME/Agentik_Tools/bin/omega status" \
+      > "$unitdir/omega-engine.service"
+    _systemd_unit "Omega OS Telegram bridge"      "$OMEGA_HOME/Agentik_Tools/bin/omega status" \
+      > "$unitdir/omega-telegram.service"
+    _systemd_unit "Omega OS autonomous supervisor" "$OMEGA_HOME/Agentik_Tools/bin/omega status" \
+      > "$unitdir/omega-autonomous.service"
+    info "systemd user units written to $unitdir"
+    info "the 24/7 layer: \`systemctl --user enable --now omega-engine omega-telegram omega-autonomous\`"
+    info "(enable once the engine daemon / bridge build-out is complete — see docs/ENGINE-SPEC.md)"
+  else
+    info "macOS — launchd plists for the workstation profile go here (build-out)"
+  fi
+  return 0
+}
+
+_systemd_unit() {  # _systemd_unit <description> <execstart>
+  cat <<EOF
+[Unit]
+Description=$1
+After=network.target
+
+[Service]
+Type=simple
+Environment=OMEGA_HOME=$OMEGA_HOME
+ExecStart=$2
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+}
+
+# --- 70 -----------------------------------------------------------------------
+step_doctor() {
+  local omega="$OMEGA_HOME/Agentik_Tools/bin/omega"
+  [ -x "$omega" ] || { err "omega CLI not found — the engine step is incomplete"; return 1; }
+  OMEGA_HOME="$OMEGA_HOME" "$omega" doctor
+}

package/bootstrap/manifest.example.yaml

@@ -0,0 +1,45 @@
+# Omega OS — headless install manifest.
+#
+#   cp bootstrap/manifest.example.yaml bootstrap/manifest.yaml   # then edit
+#   TELEGRAM_TOKEN=... bash install.sh --manifest bootstrap/manifest.yaml --non-interactive
+#
+# Secrets are NEVER stored in this file — they are read from environment
+# variables or the encrypted vault. This file declares choices, not credentials.
+
+profile: vps                 # vps | workstation | minimal
+omega_home: ~/Omega
+
+telegram:
+  token_env: TELEGRAM_TOKEN  # the installer reads the token from this env var
+  group_chat_id: ""          # the Telegram forum group; topics map to projects
+
+providers:                   # which LLMs to wire, and their default roles
+  - id: claude
+    roles: [oracle, manager, worker, verifier]
+  - id: glm
+    roles: [aisb]
+  # - id: openai
+  #   roles: [audit]
+  # credentials come from env / the vault, never from here
+
+mcp:                         # entries from Agentik_SSOT/mcp/mcp-catalog.yaml
+  - filesystem
+  - git
+  - github
+  - composio
+  - playwright
+  - context7
+  - fetch
+  # - higgsfield
+  # - notion
+  # - linear
+
+autonomous_agents:           # charters from Agentik_Orchestration/autonomous/
+  - support-agent
+  # - growth-agent
+
+options:
+  enable_services: true      # install + describe the systemd 24/7 layer
+  rag:
+    envelope: corrective     # CRAG wraps every retrieval
+    strategies: [hybrid, graph, multimodal]

package/docs/ACCOUNT-AND-BILLING.md

@@ -0,0 +1,95 @@
+# Omega OS — Accounts & Billing
+
+> Multiple Claude Code Max accounts as a **pool**, and per-account usage
+> tracking. Commands: `omega account`, `omega billing`.
+
+---
+
+## 1. The shift — from "switch" to "pool"
+
+In the original Omega, work ran in N tmux sessions, each its own `claude`
+process. "Switching account" meant rewriting the OAuth credentials every
+session used — the job of the old `account.py` + `claude-oauth.sh`.
+
+**Omega OS has no tmux fan-out.** One engine process makes every provider call.
+There is nothing to "switch" globally. Instead, the Claude provider holds an
+**account pool** and assigns each agent call to an account.
+
+This is strictly better. With N Max accounts in the pool you get the **sum** of
+their rate limits as usable throughput — more concurrent agents, and no single
+account slamming into its weekly cap. "Switching" becomes "pooling".
+
+---
+
+## 2. The account pool
+
+`Agentik_Providers/claude/accounts.yaml` declares the pool:
+
+| Field | Meaning |
+|---|---|
+| `id` | a short handle for the account (`max-primary`, `max-secondary`, …) |
+| `label` | a human description |
+| `secret_ref` | a **reference** into the vault — never the token itself |
+| `weight` | relative share of agent calls (`by-quota` / `round-robin`) |
+| `status` | `active` · `resting` (temporarily out) · `disabled` |
+| `selection` | pool-wide: `round-robin` \| `least-used` \| `by-quota` |
+
+OAuth tokens are **never** in this file. They live encrypted in
+`Agentik_Extra/etc/secrets/`; `accounts.yaml` only stores a `secret_ref`.
+
+---
+
+## 3. Commands
+
+| Command | Does |
+|---|---|
+| `omega account` | show the pool and the selection strategy |
+| `omega account login` | run the Claude OAuth flow, store the token in the vault, add the account to the pool |
+| `omega account use <id>` | set an account `active` / `resting` |
+| `omega account pool` | edit weights and the selection strategy |
+| `omega billing` | usage & cost per account |
+
+> `omega account login` (the OAuth flow) and live `omega billing` aggregation
+> are build-out — the commands and the model are in place; the OAuth handshake
+> and usage rollup are the module-by-module implementation, like `bus.py`.
+
+---
+
+## 4. The login flow
+
+```
+omega account login
+   │
+   ├─ 1. open the Claude OAuth flow (device / browser code)
+   ├─ 2. on success, store the token encrypted in
+   │      Agentik_Extra/etc/secrets/  as CLAUDE_OAUTH_<id>
+   ├─ 3. add a pool entry to Agentik_Providers/claude/accounts.yaml
+   │      (secret_ref only — never the token)
+   └─ 4. the account is immediately part of the rotation
+```
+
+No credential ever lands in the git-tracked tree.
+
+---
+
+## 5. Billing
+
+Every `task.*` event can carry token usage in its payload. `omega billing`
+aggregates that usage **per account** against the provider cost model — so you
+can see, at a glance, which Max account is near its weekly limit and when to add
+another one to the pool. Per-account is the point: each Max account has its own
+cap, and the pool's whole value is spreading load across them.
+
+---
+
+## 6. Where it lives
+
+| Concern | Block |
+|---|---|
+| pool config (`accounts.yaml`) | `Agentik_Providers/claude/` |
+| OAuth tokens | `Agentik_Extra/etc/secrets/` (encrypted vault) |
+| the rotation logic | the Claude provider adapter (`Agentik_Providers/claude/`, build-out) |
+| usage data | the event log (`Agentik_Runtime/eventlog/`) |
+
+Consistent with the rest of the rack: config in Providers, secrets in Extra,
+runtime data in Runtime.