@agentikos/omega-os 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,225 @@
+# Omega OS — Architecture
+
+> The deterministic harness is code. The intelligence is prompted LLM calls.
+> The SSOT is the bridge. This document defines all three.
+
+---
+
+## 1. The problem, and the principle
+
+The failure that defines this project: **an agent declares a task finished, you
+test it, it does not work.** "C'est bon, terminé" — and it is not.
+
+Three structural defects cause it in file-based orchestration (`workers write a
+done.json`, `the parent scans files`):
+
+1. **Self-declared completion** — the actor with the most incentive to say
+   "done" is the one asserting it.
+2. **Observed, not computed** — the parent *searches* for the state → polling,
+   races, missed files, stale reads.
+3. **The parent can finish before its children** — nothing mechanically
+   prevents a parent closing while children still run.
+
+**The principle that fixes all three:** completion is not *information an agent
+writes* — it is **a state the engine derives** from observable, immutable facts.
+An invariant computed by the system, never an assertion by an actor.
+
+Everything below is the consequence of that one sentence.
+
+---
+
+## 2. Two worlds, cleanly separated
+
+| World | What it is | Nature |
+|---|---|---|
+| **The harness** | state, dispatch, lifecycle, scheduling, locks, observability | deterministic **code** — typed, tested |
+| **The intelligence** | classify, plan, write code, audit | non-deterministic **LLM calls** — prompted, graded, verified |
+| **The SSOT** | rules, prompts, skills, schemas the harness injects into LLM calls | the **bridge** between the two |
+
+Most agentic systems blend these into one soup of scripts and prompt strings.
+Omega OS keeps them apart: the harness is `Agentik_Engine/` (generic Python that
+knows nothing about "oracles"); the intelligence is provider calls configured by
+`Agentik_Orchestration/`; the SSOT is `Agentik_SSOT/`.
+
+---
+
+## 3. The 8-block rack
+
+Omega OS installs as one master folder `~/Omega/` containing eight `Agentik_*`
+blocks. Each block has **one nature, one lifecycle, one owner** — a pluggable
+drawer you can open alone over SSH.
+
+```
+Omega/
+├── Agentik_SSOT/            TRUTH        — git repo, read-only in prod
+├── Agentik_Engine/          ENGINE       — generic Python, business-agnostic
+├── Agentik_Orchestration/   DEFINITIONS  — the logic, not the runtime
+├── Agentik_Providers/       WIRING       — one folder per LLM
+├── Agentik_Coding/          YOUR WORK    — project worktrees
+├── Agentik_Tools/           EXTERNAL     — the "/Applications" folder
+├── Agentik_Runtime/         LIVE STATE   — what is running now
+└── Agentik_Extra/           EPHEMERAL    — cache, config, secrets
+```
+
+### Lifecycle table
+
+| Block | Nature | Lifecycle | Git-versioned? |
+|---|---|---|---|
+| `Agentik_SSOT` | the neutral truth | stable, promoted | ✅ dedicated repo |
+| `Agentik_Engine` | the generic mechanics | rarely changes | ✅ dedicated repo |
+| `Agentik_Orchestration` | your business definitions | often changes | ✅ dedicated repo |
+| `Agentik_Providers` | LLM wiring | per-provider | ✅ (except secrets) |
+| `Agentik_Coding` | your work | very fluid | ✅ (each project) |
+| `Agentik_Tools` | third-party installs | installer-managed | ❌ (manifest only) |
+| `Agentik_Runtime` | live state | disposable except `memory.db` | ❌ |
+| `Agentik_Extra` | ephemeral + config | disposable / sensitive | ❌ |
+
+> **Note — it is eight blocks.** `Agentik_Extra` is a full block, not an
+> afterthought: it owns config, the structure manifest and the secrets vault,
+> each with its own permission regime.
+
+### Three design decisions worth stating
+
+- **Engine ≠ Orchestration.** The engine (reducer, barrier, store) knows nothing
+  about AISB or oracles — it executes graphs. *Who* is an oracle and *which*
+  topology lives in `Agentik_Orchestration/`. You can redesign all of your
+  orchestration logic without touching the engine.
+- **The RAG is split four ways, not dumped in `Tools/`.** A RAG system is not
+  one thing. The vector engine + embedding tooling (third-party, installed) →
+  `Agentik_Tools/knowledge/`. The index/corpus (derived, mutating state) →
+  `Agentik_Runtime/`. The router + strategies (`rag-route`) →
+  `Agentik_Orchestration/`. The thresholds + CRAG config → `Agentik_SSOT/`.
+  This is the engine≠config≠runtime rule applied to retrieval.
+- **`Agentik_*` prefix + the `Extra` block.** The prefix guarantees the eight
+  blocks sort and read together. `Extra/` absorbs all periphery (var, staging,
+  etc, secrets) so the master folder stays at exactly eight clean entries.
+
+---
+
+## 4. The orchestration engine (overview)
+
+Full spec: [`ENGINE-SPEC.md`](ENGINE-SPEC.md). The essentials:
+
+- **Everything is a `Task`.** AISB, oracle, worker, audit — all are `Task`s. The
+  only difference is `kind` (`dispatcher` / `executor` / `verifier`).
+- **Event sourcing.** One append-only event log (`Agentik_Runtime/eventlog/`,
+  SQLite WAL) is the single source of truth. The state of any task is a *fold*
+  (reduction) over its events. Free: audit trail, time-travel debug, no races.
+- **The reducer is pure.** `reduce(state, event) → state`. No agent ever writes
+  a state. Illegal transitions raise — they never corrupt.
+- **Structured concurrency.** A `dispatcher` opens a *scope* and spawns children
+  *inside* it. The scope cannot become `JOINABLE` until every child is terminal.
+  "Parent done when all children done" stops being something you *detect* — it
+  becomes a mechanical invariant.
+- **3-phase completion.** `CLAIMED_DONE` → an **independent verifier** → `VERIFIED`
+  or `REJECTED`. Only `VERIFIED` counts toward a parent's barrier. A worker's
+  declaration is a *request for inspection*, never an ending.
+- **Budget + deadman.** Every task has max-iterations, a wall deadline and a
+  heartbeat. No heartbeat → automatic terminal transition. No infinite hangs.
+
+### The completion FSM
+
+```
+PENDING → DISPATCHED → RUNNING → CLAIMED_DONE → VERIFYING → ┬ VERIFIED → COMPLETED
+                                                            └ REJECTED → (retry) → FAILED
+Terminal states: { COMPLETED, FAILED }
+```
+
+---
+
+## 5. The verifier — audits are not a module, they are a transition
+
+The audit system **is** the `CLAIMED_DONE → VERIFIED` transition. No task can be
+`VERIFIED` without passing the gate.
+
+```
+worker → CLAIMED_DONE
+   │
+   ▼
+AUDIT GATE  (kind = verifier — independent of the worker)
+   ├─ audit router  : selects audits by task type
+   ├─ concurrent run, semaphore-bounded
+   ├─ aggregate score vs threshold
+   ├─ ≥ threshold → VERIFIED   → counts for the parent barrier
+   └─ < threshold → REJECTED   → findings re-injected → retry within budget
+```
+
+**The non-negotiable: the gate contains a *runtime* audit.** The verifier does
+not read code and nod — it **runs the real flow**: starts the dev server, hits
+the endpoints, drives the UI path. A task is `VERIFIED` only if the live flow
+passes. This is the single mechanism that kills the lying "done": the ending is
+a fact observed by a third party that *ran the thing*. (This is `validate-live`,
+Layer 5 of the safety mesh.)
+
+---
+
+## 6. Providers — multi-LLM by contract
+
+Every LLM sits behind one interface, `AgentProvider` (see
+[`../omega/Agentik_Providers/README.md`](../omega/Agentik_Providers/README.md)).
+The engine talks only to that contract — it never knows whether Claude, GLM or
+OpenAI is behind it. A new provider = one adapter (~200–400 lines) + one line in
+`registry.yaml`. Providers can be assigned **per role** (cheap model for triage,
+Claude for code, a *different* model for audit — a real Popper falsification).
+
+---
+
+## 7. RAG — Corrective RAG as the envelope
+
+Retrieval in Omega OS follows the project's own posture (researcher, everything
+audited, runtime truth): **Corrective RAG (CRAG) wraps everything.** Whatever
+inner strategy runs, the CRAG envelope grades the retrieved chunks and
+re-retrieves if quality is low — "check / recheck until 100%" applied to context.
+
+- **Inner strategies** — Hybrid (dense + BM25, the default; `memory.db` FTS5 is
+  the hybrid base, extended with a vector index), Graph (cross-project,
+  relational), Multimodal (screenshots, PDFs, diagrams).
+- **The router** — `rag-route`, an agentic skill that classifies the query and
+  picks the inner strategy, exactly as `classify-intent` classifies missions.
+- **Placement** — engine in `Tools/`, corpus in `Runtime/`, router in
+  `Orchestration/`, config in `SSOT/` (see §3).
+
+---
+
+## 8. MCP & Claude Code plugins
+
+Full reference: [`MCP-AND-PLUGINS.md`](MCP-AND-PLUGINS.md). An MCP is three
+things: the **server binary** (third-party install → `Agentik_Tools/`), the
+**catalog + canonical config** (truth → `Agentik_SSOT/mcp/`, projected to each
+provider by its adapter), and the **secrets** (→ `Agentik_Extra/etc/secrets/`).
+The installer offers a curated catalog — Composio, Higgsfield, filesystem, git,
+GitHub, Notion, Slack, Linear, Playwright, context7 and more, plus the Claude
+Code plugin marketplace — as a checklist (interactive) or a manifest (headless).
+
+---
+
+## 9. Autonomous agents
+
+Full reference: [`AUTONOMOUS-AGENTS.md`](AUTONOMOUS-AGENTS.md). Long-running
+autonomous agents (the always-on, channel-bound, self-directed kind) are **not a
+separate subsystem**. An autonomous agent is a `Task`/`Node` with two extra
+fields: `lifecycle = persistent` and a `trigger` (cron / event / webhook /
+channel-message). Same reducer, same join barrier, same audit gate, same MCP and
+skills. They inherit verified completion and the deadman for free. This is what
+makes Omega OS *our* architecture and not Hermes' — one engine, configured.
+
+---
+
+## 10. The educators — the self-improving layer
+
+Eight *educators* live in `Agentik_Orchestration/educators/`. Each is a
+generator/compiler: it takes a high-level intention and produces the correct
+artifact **into the SSOT**, under the quality gate. They are the factory floor —
+they read the SSOT + adapters + current best practice and rewrite the system's
+own components. Driven by the learning loop, this is the auto-improvement cycle.
+See [`../omega/Agentik_Orchestration/educators/README.md`](../omega/Agentik_Orchestration/educators/README.md).
+
+---
+
+## 11. Install & always-on
+
+The repository **is** the product. Its installer, run on a fresh VPS, creates
+`~/Omega/`, wires the engine, installs MCP servers + plugins, connects a
+Telegram bot + group (topics = `Agentik_Coding` projects), and installs
+`systemd` services so the engine, the Telegram bridge and the autonomous-agent
+supervisor run **24/7**. See [`INSTALL.md`](INSTALL.md).

package/docs/AUTONOMOUS-AGENTS.md

@@ -0,0 +1,128 @@
+# Omega OS — Autonomous Agents
+
+> Long-running, self-directed, channel-bound agents — **as first-class nodes of
+> the one engine**, not a bolted-on subsystem.
+
+---
+
+## 1. The principle
+
+Frameworks like Hermes treat autonomous agents as a parallel stack. Omega OS
+does not. An autonomous agent **is a `Task`/`Node`** of the same engine, with
+two extra fields:
+
+- `lifecycle: persistent` — it does not end after one mission (vs `ephemeral`).
+- `trigger` — what wakes it: `cron` | `event` | `webhook` | `channel`.
+
+Everything else is identical to a mission task: the same reducer, the same join
+barrier, the same audit gate, the same providers, the same MCP servers, the same
+skills. **An autonomous agent inherits verified completion and the deadman for
+free.** This is what makes it *our* architecture — one engine, configured — and
+not a second framework to maintain.
+
+A mission task answers *"do this one thing."* An autonomous agent answers
+*"hold this role, indefinitely, and act when your trigger fires."*
+
+---
+
+## 2. What an autonomous agent is
+
+A persistent `dispatcher` node with a **charter**. When its trigger fires it
+opens a scope and spawns ephemeral mission tasks *inside* that scope — which run
+through the normal `AISB → Oracle → Worker` topology, verified-completion and
+all. The autonomous agent is the long-lived parent; the missions it launches are
+its ephemeral children.
+
+```
+   trigger fires
+        │
+        ▼
+   autonomous agent (persistent dispatcher, bound to a Telegram channel)
+        │  opens a scope, spawns a mission
+        ▼
+   AISB → Oracle → Worker → Verifier      (ephemeral, normal topology)
+        │
+        ▼
+   scope.joinable → the agent reports to its channel → waits for the next trigger
+```
+
+---
+
+## 3. The charter
+
+Charters live in `Agentik_Orchestration/autonomous/`. One YAML file per agent:
+
+```yaml
+id: support-agent
+role: customer-support
+lifecycle: persistent
+charter: >
+  Watch the support channel. Triage every inbound message, draft a reply,
+  and for anything requiring a code change, open a mission against the
+  relevant project. Never close a thread the customer has not confirmed.
+trigger:
+  type: channel
+  config: { telegram_topic: 4012 }
+channel:
+  telegram_topic: 4012          # where it listens AND reports
+budget:
+  max_iterations: 5
+  heartbeat_interval_s: 300
+provider: glm                   # cheap model for triage; missions escalate
+allowed:
+  skills:  [classify-intent, draft-reply, rag-route]
+  mcp:     [filesystem, github, linear]
+  topologies: [aisb-oracle-worker]
+guardrails:
+  may_spawn_missions: true
+  may_ship: false               # missions it spawns still pass the audit gate
+```
+
+| Field | Meaning |
+|---|---|
+| `trigger` | what wakes the agent — `cron` (schedule), `event` (an event-bus pattern), `webhook` (an HTTP hook), `channel` (a Telegram message) |
+| `channel` | the Telegram topic the agent listens to and reports into |
+| `allowed` | the agent's capability surface — which skills, MCP servers, topologies it may use |
+| `guardrails` | hard limits — may it spawn missions, may it ship |
+
+---
+
+## 4. Triggers
+
+| Trigger | Fires when | Example |
+|---|---|---|
+| `cron` | a schedule elapses | a daily metrics-review agent |
+| `event` | the event bus matches a pattern | an agent that reacts to every `task.failed` |
+| `webhook` | an external HTTP call arrives | a CI agent reacting to a GitHub push |
+| `channel` | a message lands in a bound Telegram topic | a support agent |
+
+Multiple autonomous agents can coexist, each bound to a different channel, each
+with its own role and management — exactly the "different agents, different
+channels, same access to MCP/skills" you asked for.
+
+---
+
+## 5. The supervisor and persistent agents
+
+A persistent agent never reaches a terminal state in normal operation — so the
+deadman's `heartbeat_interval_s` is its liveness contract: a persistent agent
+must emit `task.heartbeat` on schedule. If it goes silent, the supervisor
+restarts it (a persistent agent is *respawned*, not failed). The engine
+distinguishes this by `lifecycle`: `ephemeral` + deadman → `FAILED`;
+`persistent` + deadman → respawn.
+
+---
+
+## 6. Lifecycle
+
+- **Register** — drop a charter in `Agentik_Orchestration/autonomous/`, or run
+  the installer's `70-autonomous` step.
+- **Run** — the autonomous-agent supervisor (`systemd` service) loads every
+  charter and keeps each agent's persistent node alive.
+- **Observe** — `omega status` shows persistent nodes alongside mission tasks;
+  each agent also reports into its bound Telegram channel.
+- **Retire** — remove the charter; the supervisor lets the node finish its
+  current scope, then stops respawning it.
+
+See `Agentik_Orchestration/autonomous/example-agents.yaml` for a charter
+template and two worked examples (a support agent and a growth agent).

package/docs/ENGINE-SPEC.md

@@ -0,0 +1,174 @@
+# Omega OS — Engine Specification
+
+> Reference for the `Agentik_Engine/` build-out. The core (`task`, `events`,
+> `reducer`, `barrier`, `store`, `supervisor`) is implemented and tested; `bus`
+> and `router` are specified here.
+
+---
+
+## 1. The 6 founding principles
+
+| # | Principle | Effect |
+|---|---|---|
+| 1 | **Event sourcing** | One append-only log of immutable events is the single source of truth. Any task's state = a fold over its events. Free: audit trail, time-travel debug, zero races. |
+| 2 | **Structured concurrency** | A parent owns its children. A parent scope cannot close until every child is terminal. |
+| 3 | **Verified completion** | 3-phase commit: the worker *claims*, an independent verifier *validates*. Only the verified state counts. |
+| 4 | **Topology = data** | The engine knows only `Node`s (`dispatcher`/`executor`/`verifier`) in a DAG. An orchestration is a graph file. |
+| 5 | **Push, not poll** | Tasks emit events; the bus pushes to subscribers. Cron is a cold backstop only. |
+| 6 | **Budget + deadman** | Every task has max-iterations, a wall deadline and a heartbeat. No heartbeat → automatic terminal transition. |
+
+---
+
+## 2. The Task FSM
+
+```
+PENDING → DISPATCHED → RUNNING → CLAIMED_DONE → VERIFYING → ┬ VERIFIED → COMPLETED
+                                                            └ REJECTED → (retry) → FAILED
+Terminal states: { COMPLETED, FAILED }
+```
+
+| State | Meaning |
+|---|---|
+| `PENDING` | created, not yet dispatched |
+| `DISPATCHED` | assigned to an executant |
+| `RUNNING` | executing |
+| `CLAIMED_DONE` | the executant *thinks* it finished — **not trusted** |
+| `VERIFYING` | the audit gate is running |
+| `VERIFIED` | ✅ validated by a third party — **the only state that counts for a parent** |
+| `REJECTED` | audits failed → findings re-injected → retry within budget |
+| `COMPLETED` | terminal — success |
+| `FAILED` | terminal — budget exhausted / stall / honest block, with evidence |
+
+### Legal transition table (the reducer)
+
+`(state, event) → state`. Anything not listed is illegal and **raises** —
+it never corrupts.
+
+| From | Event | To |
+|---|---|---|
+| `None` | `task.created` | `PENDING` |
+| `PENDING` | `task.dispatched` | `DISPATCHED` |
+| `DISPATCHED` | `task.started` | `RUNNING` |
+| `RUNNING` | `task.claimed_done` | `CLAIMED_DONE` |
+| `CLAIMED_DONE` | `task.verifying` | `VERIFYING` |
+| `VERIFYING` | `task.verified` | `VERIFIED` |
+| `VERIFYING` | `task.rejected` | `REJECTED` |
+| `VERIFIED` | `task.completed` | `COMPLETED` |
+| `REJECTED` | `task.dispatched` | `DISPATCHED` (retry) |
+| *any non-terminal* | `task.failed` | `FAILED` (the deadman) |
+
+`task.heartbeat` and `scope.joinable` are not task-state transitions: the first
+is a liveness ping, the second is consumed by the barrier.
+
+---
+
+## 3. The reducer — the anti-hallucination core
+
+A **pure** function. No agent ever writes a `TaskState`; the engine replays
+events to derive it. The only path to `VERIFIED` is the event `task.verified`,
+and only a `verifier` node may emit that event.
+
+```python
+def reduce(state, event) -> TaskState     # one step, raises on illegal moves
+def reduce_task(events)  -> TaskState     # fold an ordered event stream
+```
+
+This is the mechanical answer to "the agent said done and it wasn't": there is
+no event an executor can emit that reaches `VERIFIED`.
+
+---
+
+## 4. The join barrier — structured concurrency
+
+A `dispatcher` owns a **scope**. `scope_status(children_states)` derives:
+
+- **RUNNING** — ≥1 child non-terminal → the parent *cannot* close.
+- **PARTIAL** — all children terminal, ≥1 `FAILED`.
+- **JOINABLE** — all children terminal, none `FAILED`.
+
+When the last child reaches a terminal state, the engine re-reduces the scope;
+if `JOINABLE`, it emits `scope.joinable` *to the parent*. The parent may only
+move toward `COMPLETED` on receiving that event. **Finishing early is impossible
+by construction.**
+
+### The 3 questions, resolved mechanically
+
+- *How does the oracle know its workers finished?* — It does not search. A
+  worker reaching `VERIFIED` re-reduces the parent scope; the result is *pushed*.
+- *How does the oracle know its own work is done?* — It is not allowed to
+  decide. The barrier computes `JOINABLE`; the oracle transitions only on
+  `scope.joinable`.
+- *How does AISB stay informed?* — Same mechanism one level up. AISB is the root
+  scope; oracles are its children. Completion propagates up the DAG, level by
+  level, automatically.
+
+### The `PARTIAL` policy (spec gap to close)
+
+`PARTIAL` is deliberately distinct from `JOINABLE`. The dispatcher's reaction to
+a `PARTIAL` scope is **declared per topology** in
+`Agentik_Orchestration/topologies/<name>.yaml`:
+
+```yaml
+on_partial: retry_failed   # retry_failed | accept_partial | fail_up
+```
+
+The engine never hard-codes this.
+
+---
+
+## 5. The audit gate — the verifier
+
+The audit system **is** the `CLAIMED_DONE → VERIFYING → VERIFIED/REJECTED`
+transition.
+
+```
+worker → CLAIMED_DONE
+   │  (emits task.verifying — a verifier node is spawned)
+   ▼
+VERIFIER  (kind = verifier, independent of the worker)
+   ├─ audit router : selects audits by task type
+   ├─ concurrent run, semaphore-bounded
+   ├─ static audits  (lint, types, code review)
+   └─ RUNTIME audit  (start the server, hit endpoints, drive the UI)  ← mandatory
+   │
+   ├─ aggregate score ≥ threshold → emit task.verified
+   └─ aggregate score < threshold → emit task.rejected (+ findings)
+```
+
+The **runtime audit is non-negotiable**. A task is `VERIFIED` only if the real
+flow ran and passed. Retry loop: `REJECTED → dispatched` is bounded by the
+`Budget` — `max_iterations` retries, then an honest `FAILED` with evidence.
+
+---
+
+## 6. Event schema
+
+Every event is immutable: `{ id, task_id, type, ts, payload }`. Stored
+append-only — no UPDATE, no DELETE. See `Agentik_SSOT/schemas/event.schema.json`.
+
+Event types: `task.created`, `task.dispatched`, `task.started`,
+`task.claimed_done`, `task.verifying`, `task.verified`, `task.rejected`,
+`task.completed`, `task.failed`, `task.heartbeat`, `scope.joinable`.
+
+---
+
+## 7. Components
+
+| Component | Responsibility | Status |
+|---|---|---|
+| Event Store | append-only log, single source of truth — `SQLiteStore` (WAL) | implemented |
+| Reducer | pure `(state, event) → state` | implemented |
+| Barrier | scope status `RUNNING / PARTIAL / JOINABLE` | implemented |
+| Supervisor | deadman / watchdog — stall → `task.failed` | implemented |
+| Bus | push events to subscribers (in-process → Redis pub/sub) | **to build** |
+| Model Router | task → required capability → provider (reason in capabilities, not names) | **to build** |
+
+---
+
+## 8. Store choice
+
+**SQLite WAL** — simple, ample for a VPS. The `EventStore` is an interface;
+`RedisStreamStore` can be added later for hundreds of concurrent workers, behind
+the same contract. **Snapshotting** (`Agentik_Runtime/snapshots/`) keeps
+`reduce_task` from replaying the whole log as it grows — needed for scale, not
+for correctness.

package/docs/INSTALL.md

@@ -0,0 +1,106 @@
+# Omega OS — Install Guide
+
+> One command on a fresh VPS or workstation. Idempotent and resumable.
+
+---
+
+## 1. Requirements
+
+- **OS** — Ubuntu 22.04+ (VPS) or macOS 13+ (workstation).
+- **Access** — a non-root user with `sudo` (for system packages only).
+- **Accounts** — a Telegram bot token (from `@BotFather`) and at least one LLM
+  provider credential (Claude / GLM / OpenAI). None are shipped; you connect
+  your own.
+- Everything else (Python, `uv`, `tmux`, `git`, `sqlite3`, `jq`) is installed by
+  the bootstrap.
+
+## 2. Quick start
+
+One command:
+
+```bash
+npx @agentikos/omega-os
+```
+
+`npx` fetches the package and hands off to the installer — **interactive** by
+default, walking you through provider setup, the MCP/plugin checklist, and
+Telegram wiring. From a git clone, `bash install.sh` is equivalent.
+
+### Headless install
+
+```bash
+npx @agentikos/omega-os --manifest bootstrap/manifest.example.yaml --non-interactive
+```
+
+Copy `bootstrap/manifest.example.yaml`, fill in your choices (profile, MCP
+selection, Telegram), and the installer runs end-to-end with no prompts — for CI
+or scripted VPS provisioning.
+
+## 3. What it does — the 8 steps
+
+| Step | Action |
+|---|---|
+| `00-preflight` | detect OS + package manager; check `git`, disk, user is non-root |
+| `10-system-deps` | install Python 3.11+, `uv`, `tmux`, `git`, `sqlite3`, `jq`, `curl` |
+| `20-structure` | create `~/Omega/` and the 8 `Agentik_*` blocks |
+| `30-engine` | `uv venv` + install `omega-engine`; expose the `omega` CLI |
+| `40-mcp` | MCP / Claude-plugin checklist → install servers, write canonical config |
+| `50-telegram` | prompt for bot token, validate it, wire the bot + forum group |
+| `60-services` | install `systemd` (Linux) / `launchd` (macOS) units — the 24/7 layer |
+| `70-doctor` | run `omega doctor` — validate the deployment |
+
+> `70-autonomous` (register autonomous-agent charters) runs inside `60-services`
+> when the profile enables it.
+
+## 4. Idempotent & resumable
+
+Each completed step is recorded in `~/Omega/Agentik_Extra/var/.install-state`.
+Re-running `install.sh` **skips completed steps** — if it stopped at step 5/8
+(e.g. a missing Telegram token), fix the cause and re-run; it resumes at step 5.
+
+Force a full re-run: `bash install.sh --force`.
+
+## 5. Profiles
+
+| Profile | For | Result |
+|---|---|---|
+| `vps` | a headless server | `systemd` services, Telegram bridge, autonomous agents — runs 24/7 |
+| `workstation` | a Mac/Linux laptop | `launchd`, on-demand, no always-on services |
+| `minimal` | CI / containers | engine only, no Telegram, no services |
+
+Select with `--profile vps` (default on Linux) or in the manifest.
+
+## 6. The 24/7 layer
+
+On the `vps` profile, `60-services` installs three `systemd` user units:
+
+- `omega-engine.service` — the orchestration engine + event bus.
+- `omega-telegram.service` — the Telegram bridge (missions in, reports out).
+- `omega-autonomous.service` — the autonomous-agent supervisor.
+
+These give Omega OS its "Agent runs 7/7" property: the VPS keeps the engine and
+every autonomous agent alive across reboots.
+
+## 7. Telegram
+
+`50-telegram` connects a bot to a Telegram **forum group**. Each project under
+`Agentik_Coding/` maps to a **topic** in that group; replying in a topic routes
+a mission to that project. The same model as the original Omega — one chat
+thread is the whole interface.
+
+## 8. Verify
+
+```bash
+omega doctor      # 8-block tree + event store — must print "doctor: PASS"
+omega status      # every task and its derived state
+omega version
+```
+
+## 9. Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `preflight: running as root` | create and use a non-root `sudo` user |
+| `uv: command not found` after `10` | re-run `install.sh` — step 10 installs `uv` and re-execs the shell |
+| Telegram token rejected | re-check the token from `@BotFather`; re-run — it resumes at `50` |
+| `doctor: FAIL` on a block | the step that builds that block failed — read `Agentik_Extra/var/logs/install.log` |