@agentikos/omega-os 0.2.0 → 0.19.5

package/bootstrap/templates/autonomous/audit-patrol.yaml

@@ -0,0 +1,41 @@
+# audit-patrol — autonomous charter that re-runs the Quality Arsenal periodically.
+#
+# Selected via `autonomous_agents: [audit-patrol]` in the install manifest.
+# Step 55 copies this file to Agentik_Orchestration/autonomous/audit-patrol.yaml
+# where the AutonomousSupervisor (omega daemon autonomous) picks it up.
+#
+# The patrol runs `omega audit all` against the live tree, persists every
+# verdict to Agentik_Runtime/audits.db, and lets the doctor's "audit
+# history" section show trend (↑ improving / → stable / ↓ degrading).
+#
+# Cadence: every 6 hours by default. Tune for your VPS load — running on
+# a 10-project tree can take a few minutes per pass.
+
+id: audit-patrol
+description: >
+  Re-run every applicable forensic audit on the live tree at a regular
+  cadence. Records scores to audit history so the doctor + dashboard can
+  show whether the project is improving over time.
+enabled: true
+
+trigger:
+  type: cron
+  # Stdlib 5-field cron — see omega_engine.autonomous.
+  schedule: "0 */6 * * *"
+
+role: worker
+
+spec:
+  intent: >
+    Run `omega audit all --scope $OMEGA_HOME/Agentik_Coding` in read-only
+    mode. Record every verdict to history. If any audit dropped below
+    its threshold since the previous run, append a `pending_action` to
+    the patrol's .done.json so the operator sees it on next inspection.
+  budgets:
+    max_tasks_per_run: 1
+    max_tokens_per_run: 200000
+
+io:
+  inbound: []
+  outbound:
+    - { kind: report, channel: project_topic }

package/bootstrap/templates/autonomous/smith-reflect.yaml

@@ -0,0 +1,43 @@
+# smith-reflect — autonomous charter that runs Smith reflection daily.
+#
+# Drops into Agentik_Orchestration/autonomous/smith-reflect.yaml when
+# `autonomous_agents: [smith-reflect]` is in the manifest. The
+# AutonomousSupervisor picks it up on its next tick.
+#
+# Cadence: once a day at 03:00 UTC. The Smith reflection analyses the
+# last 30 days of audit history + worker outcomes and writes insights
+# as JSON files into Agentik_Extra/staging/promotion/ — the educator
+# staging pipeline picks them up.
+#
+# This is OPT-IN and READ-ONLY. Smith never edits the live tree; it
+# only proposes. The operator's existing promotion gates apply.
+
+id: smith-reflect
+description: >
+  Daily reflection on audit + worker outcomes. Detects patterns
+  (weak audits, repeated pending actions, regressions) and writes
+  structured insights to the staging pipeline.
+enabled: false                # opt-in — flip to true after reading
+
+trigger:
+  type: cron
+  schedule: "0 3 * * *"       # daily at 03:00 UTC
+
+role: smith
+
+spec:
+  intent: >
+    Read the last 30 days of audit_runs + .done.json files. Identify
+    audits below threshold consistently, regressions in the last 7
+    days, repeated pending_actions, and the failure-vs-completion
+    ratio. Write each finding as a separate JSON file in
+    Agentik_Extra/staging/promotion/smith-<ts>-N.json — the educator
+    pipeline reads them in the next promotion cycle.
+  budgets:
+    max_tasks_per_run: 1
+    max_tokens_per_run: 50000
+
+io:
+  inbound: []
+  outbound:
+    - { kind: report, channel: project_topic }

package/bootstrap/templates/autonomous/ssh-key-rotate.yaml

@@ -0,0 +1,46 @@
+# ssh-key-rotate — autonomous charter for periodic SSH key rotation.
+#
+# Drops into Agentik_Orchestration/autonomous/ssh-key-rotate.yaml when
+# selected in `autonomous_agents: [ssh-key-rotate]` in the manifest. The
+# AutonomousSupervisor picks it up on its next tick.
+#
+# Cadence: quarterly (1st day of Jan/Apr/Jul/Oct at 03:00 UTC). The
+# charter dispatches a worker mission whose intent is to:
+#   1. Generate a new SSH keypair under $OMEGA_HOME/Agentik_Extra/var/ssh-rotation/
+#   2. Add the new public key to the operator's authorized_keys
+#   3. Notify the project topic with the new fingerprint + rollback steps
+#   4. Schedule a follow-up "remove old key" 7 days later
+#
+# This charter is OPT-IN and intentionally conservative — the rotation
+# does NOT remove the old key on its own. The follow-up step is a manual
+# `omega ssh-rotate confirm` after the operator has validated the new
+# key works on every machine they SSH from.
+
+id: ssh-key-rotate
+description: >
+  Quarterly SSH keypair rotation reminder + draft. Generates the new
+  key, suggests authorized_keys update, never removes the old key
+  without explicit operator confirmation.
+enabled: false                # opt-in — flip to true after reading
+
+trigger:
+  type: cron
+  schedule: "0 3 1 1,4,7,10 *"  # 1st of Jan/Apr/Jul/Oct at 03:00 UTC
+
+role: worker
+
+spec:
+  intent: >
+    SSH key rotation cycle. Generate a new keypair under
+    $OMEGA_HOME/Agentik_Extra/var/ssh-rotation/<YYYY-MM-DD>/, add the
+    public key to ~/.ssh/authorized_keys (without removing existing
+    keys), and post the new fingerprint + per-machine update steps
+    into the project topic. Do NOT remove any existing key.
+  budgets:
+    max_tasks_per_run: 1
+    max_tokens_per_run: 100000
+
+io:
+  inbound: []
+  outbound:
+    - { kind: report, channel: project_topic }

package/bootstrap/templates/autonomous/support-agent.yaml

@@ -0,0 +1,38 @@
+# support-agent — example autonomous-agent charter shipped by the installer.
+#
+# Selected via `autonomous_agents: [support-agent]` in the install manifest;
+# step_autonomous copies this file to Agentik_Orchestration/autonomous/<id>.yaml
+# where the AutonomousSupervisor picks it up.
+#
+# Charters are pure data. The supervisor binds the trigger, dispatches a task
+# with the role/spec, and emits events through the same engine that runs
+# user-driven missions — see docs/AUTONOMOUS-AGENTS.md.
+
+id: support-agent
+description: >
+  Triage inbound issues from configured channels (Telegram, email, GitHub),
+  attempt automated remediation for known patterns, draft responses for
+  human review on the rest.
+enabled: true
+
+trigger:
+  type: cron
+  # Every 4 hours, on the hour. Stdlib 5-field cron — see omega_engine.autonomous.
+  schedule: "0 */4 * * *"
+
+role: support
+
+spec:
+  intent: >
+    Pull new items from the inbound queue, classify each, run any safe
+    automated remediation, and draft a human-reviewable response for the rest.
+  budgets:
+    max_tasks_per_run: 5
+    max_tokens_per_run: 50000
+
+# Wiring — what surfaces this charter reads/writes.
+io:
+  inbound:
+    - { kind: telegram, scope: project }
+  outbound:
+    - { kind: report, channel: project_topic }

package/docs/AUDITS.md

@@ -0,0 +1,85 @@
+# Omega OS — Quality Arsenal (18 audits)
+
+> Every audit lives in `Agentik_SSOT/audits/<id>.yaml`. They feed the
+> `ArsenalGate`, which is the verification gate in the orchestration engine:
+> a worker's `CLAIMED_DONE` only becomes `VERIFIED` if every applicable audit
+> passes.
+
+## Why we replaced the legacy commands
+
+The originals live under `~/.claude/commands/*audit.md` as freeform prompt
+files — 700–1,900 lines each, English-only, no machine-actionable scoring,
+no deterministic gather phase, no per-domain weighting, and bound to a
+single orchestrator. They are excellent prompts, but they are *prompts*, not
+audits an engine can run.
+
+The Omega OS rewrite makes each audit:
+
+| Concern | Legacy | Omega OS |
+|---|---|---|
+| Format | Markdown prompt | YAML data |
+| Doctrine | Embedded in each file | Shared shell in `audit_arsenal._DOCTRINE` |
+| Deterministic phase | None | `gather:` runs real linters/tools first |
+| Agentic phase | Yes | Yes (now structured: `phases:` + `falsification:`) |
+| Output | Free text | `ArsenalVerdict { score, findings, fixes }` |
+| Hookable | No | `ArsenalGate` plugs into the engine as the audit gate |
+| Per-domain weight | No | `weight:` + `threshold:` per audit |
+| Scope filter | No | `applies_to.changed:` pattern list |
+
+The shared Gestalt-Popper doctrine (`_DOCTRINE` in `audit_arsenal.py`) carries
+the hinge-point rule, the falsification mandate, and the "claim vs reality"
+framing into *every* audit — so we don't drift across 18 separate files.
+
+## The 18 audits — per-file evidence
+
+| Audit | Domain question | Phases | Gather tools | Size |
+|---|---|---:|---:|---:|
+| a11yaudit | Is it ACCESSIBLE? | 14 | 3 | 5.8 KB |
+| apiaudit | Is the API SOLID? | 13 | 5 | 5.4 KB |
+| automationaudit | Is automation RELIABLE? | 14 | 7 | 5.2 KB |
+| codeaudit | Is the code SOLID? | 12 | 4 | 2.8 KB |
+| copyaudit | Is the copy CLEAR? | 14 | 4 | 4.1 KB |
+| dataaudit | Is the data INTACT? | 13 | 6 | 5.7 KB |
+| debugaudit | What is BROKEN right now? | 14 | 6 | 4.7 KB |
+| dxaudit | Is the DX SMOOTH? | 14 | 7 | 4.6 KB |
+| featureaudit | Is the product COMPLETE? | 14 | 5 | 4.3 KB |
+| flowaudit | Does the experience WORK? | 15 | 4 | 4.9 KB |
+| logicaudit | Is the logic OPTIMAL? | 15 | 5 | 5.8 KB |
+| motionaudit | Is the motion PURPOSEFUL? | 15 | 2 | 4.8 KB |
+| perfaudit | Is it FAST enough? | 14 | 5 | 4.8 KB |
+| refontaudit | Is the redesign coherent? | 15 | 3 | 5.6 KB |
+| retentionaudit | What FEATURES are missing? | 15 | 6 | 5.5 KB |
+| secaudit | Is it SECURE? | 13 | 6 | 5.2 KB |
+| seoaudit | Is it DISCOVERABLE? | 14 | 6 | 4.8 KB |
+| uiuxaudit | Is the interface BEAUTIFUL? | 15 | 0 ⓘ | 4.1 KB |
+
+ⓘ `uiuxaudit.gather` is intentionally empty — design has no reliable
+deterministic linter, and a 1px hierarchy break or a rogue color used for the
+wrong intent isn't catchable by `eslint` or `axe`. The agentic falsification
+pass does that job. Every other domain has at least 2 real gather tools.
+
+**Phase totals:** 256 distinct domain phases across the 18 audits. Each phase
+is one "claim under test" that the falsification pass must concretely
+disprove or accept with cited evidence.
+
+**Gather totals:** 90 deterministic tool invocations (`ruff`, `eslint`, `tsc`,
+`axe-cli`, `lighthouse`, `npm audit`, `prisma validate`, `playwright`, `gh`,
+`grep`, `lhci`, …) — all run *before* the LLM is consulted, so the agentic
+pass sees real data, not pure prose.
+
+## What this gives the engine
+
+Because every audit is data, the `ArsenalGate` can:
+
+1. Filter audits by `applies_to.roles` and `applies_to.changed` patterns —
+   a CSS-only diff doesn't trigger `secaudit`.
+2. Weight scores by `weight` and `threshold` per domain — design failures
+   block ship harder than copy nits.
+3. Surface findings to the educators (the `Smith` learner reads audit
+   results to propose systemic improvements).
+4. Render a single PDF report covering every domain that ran — the
+   `report.py` whitepaper template iterates the verdict structure directly.
+
+Re-creating any audit means editing one short YAML, not a 1,500-line Markdown
+prompt — and the shared doctrine guarantees the rest of the system keeps
+working the same way.

package/docs/GAP-ANALYSIS.md

@@ -0,0 +1,214 @@
+# OmegaOS — what the install still does not have
+
+A deliberately deep audit of what would round out the system. Sorted by
+how much pain the gap actually causes today, with concrete designs for
+each — not just "would be nice".
+
+This is the **truth document**. Items we ship today aren't in this file.
+
+---
+
+## Tier 1 — pain points we feel today
+
+### 1. Conversation history per Telegram topic ✅ (fixed in v0.3.x)
+
+**Was:** The Telegram daemon called `run_mission(intent=text)` with only
+the new line. The Oracle saw a fresh mission every turn — no memory of the
+exchange. The user's reply to a follow-up question landed without context.
+
+**Now:** `omega_engine.telegram_history` persists every inbound + outbound
+message per topic in `Agentik_Runtime/telegram-history.db`. The daemon
+prepends the last 10 exchanges to the intent before calling `run_mission`.
+DM messages are explicitly refused with a helpful redirect.
+
+### 2. Notifications never go to the AISB DM ✅ (fixed in v0.3.x)
+
+`TelegramBridge` only exposes `post(topic_id, ...)` / `send_document(topic_id, ...)`.
+There is no DM send method. The daemon also explicitly rejects starting
+a mission from a DM and tells the user to open the project topic.
+
+### 3. API key validation at install time (NOT FIXED)
+
+**Pain:** an operator wires `providers: [claude]` in the manifest with
+their key in `$CLAUDE_API_KEY`, install passes, then the first mission
+fails because the key is expired/wrong/format-broken.
+
+**Design:** new `step_validate_providers` (between step 35 and 40) that
+runs a 1-token test call against every wired provider's `/messages` API.
+Failures are surfaced immediately, install can be re-run after fixing.
+
+### 4. "Ready to go" verdict in `omega doctor` (NOT FIXED)
+
+**Pain:** doctor prints a wall of `[ok]` / `[warn]` lines and ends with
+`PASS with warnings`. Operator can't tell at a glance whether they can
+actually start a mission.
+
+**Design:** doctor ends with one of three explicit verdicts:
+- `READY` — can run missions today
+- `PARTIAL` — engine fine, some optional surfaces missing (Telegram, ...)
+- `NOT READY` — at least one critical surface broken
+
+With a one-liner of what to fix.
+
+### 5. Shell completions (NOT FIXED)
+
+**Pain:** `omega <tab>` doesn't complete. Operators have to remember 30+
+subcommands.
+
+**Design:** ship `omega/Agentik_Tools/completions/{bash,zsh,fish}` files
+generated from the argparse tree (we can use `argcomplete` or hand-roll).
+`omega completions install --shell bash` writes them to the right place.
+
+### 6. Update checker (NOT FIXED)
+
+**Pain:** operator installs v0.3.1, doesn't know v0.4.0 is out three weeks
+later.
+
+**Design:** `omega upgrade --check` queries
+`https://registry.npmjs.org/@agentikos/omega-os` for the latest, prints a
+diff if behind. Optionally wired into the autonomous supervisor as a
+weekly charter.
+
+---
+
+## Tier 2 — would meaningfully harden production
+
+### 7. `omega smoke` — quick post-install verification
+
+A 30-second end-to-end test: run a synthetic mission, check the event log,
+check the .done.json shape, exit code reflects health. CI can call it.
+
+### 8. `omega prune` — bounded growth
+
+The event log + audit history + telegram history all grow forever. Add:
+- `omega prune events --older-than 30d`
+- `omega prune audits --keep-last 100`
+- `omega prune telegram --older-than 90d` (already exists in module, no CLI yet)
+
+### 9. `omega backup` + `omega restore`
+
+Full encrypted snapshot of `$OMEGA_HOME/Agentik_Runtime/` +
+`$OMEGA_HOME/Agentik_Extra/etc/secrets/`. Restore on a new VPS.
+
+**Design:** tar + age-encrypt to a passed recipient (or the operator's
+existing `.vault-pub`). Restore reverses it. Operator can ship the
+single tarball to a new machine and recover.
+
+### 10. Token usage + cost dashboard
+
+We already record per-account usage via `BillingAggregator`. The
+`omega billing` CLI shows raw numbers. Missing:
+- USD projection per provider (with built-in rate cards we update via the
+  `update checker` from tier 1)
+- Weekly trend ("up 23% from last week")
+- Per-mission cost on the mission report
+
+### 11. Web UI / HTTP API (mentioned but not built)
+
+The engine daemon has an HTTP API for dispatch. There's no UI. Even a
+read-only one (`omega status` web-style) would be useful.
+
+### 12. Backup verification — decrypt test
+
+Backups are useless if they don't restore. `omega backup verify` would
+decrypt the latest backup into a temp dir and run `omega doctor` against
+it.
+
+### 13. Pre-commit hooks for projects
+
+`omega project new --name X` could install pre-commit hooks that run
+`omega audit run codeaudit --scope .` before commits land. The dispatcher
+contract already speaks the same .done.json schema.
+
+---
+
+## Tier 3 — nice-to-have
+
+### 14. Stack-aware project bootstrap
+
+`omega project new <name> --stack nextjs` could:
+- Run `npx create-next-app`
+- Wire Convex / Clerk / Stripe MCP secrets if detected
+- Add the project's CWD to the topology's `files_owned` defaults
+
+### 15. Slack / Email bridges
+
+Same shape as `TelegramBridge` — abstract surface. Useful for orgs
+that don't run Telegram.
+
+### 16. Webhooks IN (GitHub, Linear, Stripe)
+
+The autonomous supervisor already has a `wake_webhook` trigger. We
+need:
+- A small HTTP listener
+- Signature verification per source
+- A `webhooks: [...]` block in the manifest
+
+### 17. Mission rerun from history
+
+`omega mission <id> rerun` would replay an old mission's intent with
+fresh state — useful when you upgrade the engine and want to verify
+nothing regressed.
+
+### 18. SSH key rotation automation
+
+The autonomous supervisor + cadence are perfect for this — define an
+SSH key rotation charter, run quarterly. Same idea for any API key
+rotation.
+
+### 19. Cross-audit correlation
+
+Findings from `/perfaudit` (Core Web Vitals) inform `/seoaudit`.
+Findings from `/dataaudit` (schema) inform `/apiaudit` (contracts).
+This was mentioned earlier and skipped because the ROI was unclear —
+still skipped, but documented here so we don't lose it.
+
+### 20. Audit "diff" view
+
+`omega audit history codeaudit` shows scores over time. Missing:
+`omega audit diff <run-id-1> <run-id-2>` that compares the actual
+findings between two runs — what was fixed, what's new, what
+regressed.
+
+### 21. Multi-VPS deployment (federation)
+
+The whole engine assumes one machine. For an operator who runs
+multiple VPS, no story exists yet for `omega run` on machine A
+delegating to a worker on machine B.
+
+---
+
+## Tier 4 — really polish, low value
+
+- ANSI colour control + `--no-color` flag
+- Custom themes for pdfgen reports
+- `omega telegram say <topic-name> "..."` — manual post helper
+- Auto-detection of orphaned worker session dirs
+- Tab-completion for project slugs in `omega project secret`
+
+---
+
+## Anti-features — things we intentionally do NOT add
+
+| Idea | Why we say no |
+|---|---|
+| Direct npm/pip install of arbitrary packages from skill bodies | Defeats the auditor; attack surface explodes |
+| Auto-rollback on deploy failure | Already documented (`ship-config.json` opt-in) — making it default hides the real cause |
+| AI-decides-when-to-Stop | The Stop hook is deterministic ("audit fails → deny"). AI deciding when to give up is exactly what we're fixing. |
+| One-binary distribution | Two reasons not to: (1) `uv venv` keeps the Python clean; (2) operators want to inspect the source. |
+
+---
+
+## Roadmap as a graph
+
+```
+v0.3.x  (now)         tier 1: history + DM-refusal + uninstall + Agent Teams flag
+v0.3.x  (next)        tier 1: API-key validation + Ready/Not Ready verdict + completions
+v0.4.0                tier 2: smoke + prune + backup/restore
+v0.5.0                tier 2: cost dashboard + read-only web UI + pre-commit
+v1.0                  full coverage of tier 1+2; tier 3 selected based on real demand
+```
+
+Anything in tier 3 should be requested with a use case, not built
+speculatively. Tier 4 is documented so we don't lose it but we won't
+build any of it until something else moves first.

package/docs/INSTALL.md

@@ -7,7 +7,8 @@
 ## 1. Requirements
 
 - **OS** — Ubuntu 22.04+ (VPS) or macOS 13+ (workstation).
-- **Access** — a non-root user with `sudo` (for system packages only).
+- **Access** — either a non-root user with `sudo`, or `root` if you want the
+  installer to create a fresh user for you (see §3).
 - **Accounts** — a Telegram bot token (from `@BotFather`) and at least one LLM
   provider credential (Claude / GLM / OpenAI). None are shipped; you connect
   your own.
@@ -36,7 +37,40 @@ 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
+## 3. User modes — who Omega OS runs as
+
+Omega OS never assumes a username. The installer has three modes, picked on
+the CLI (or via `user:` in the manifest):
+
+| Mode | Flag | When to use |
+|---|---|---|
+| **Current** *(default)* | *(no flag)* | Your normal user on a Mac or an SSH'd VPS. `OMEGA_HOME=$HOME/Omega`. |
+| **Adopt existing** | `--user <name>` | A pre-existing service user (e.g. `agentik`) on a server. The installer re-execs as them. |
+| **Create new** | `--create-user [<name>]` | Root on a fresh VPS, you want isolation. Default name: **`omega`** (Linux only; macOS is refused). |
+
+Example — fresh root VPS, full isolation under a new `omega` user:
+
+```bash
+ssh root@your-vps
+git clone https://github.com/agentik-os/OmegaOS && cd OmegaOS
+bash install.sh --create-user                  # creates user 'omega', re-execs
+# … or with a custom name …
+bash install.sh --create-user agentik
+```
+
+Example — adopt an existing user:
+
+```bash
+sudo bash install.sh --user agentik
+```
+
+The installer **refuses to install as `root`** unless you explicitly set
+`OMEGA_ALLOW_ROOT=1` (almost always a mistake — file ownership becomes
+unmanageable). The friendly default `omega` matches the install directory
+(`~omega/Omega/`), never collides with stock Linux users, and is easy to
+type — change it if you prefer something else.
+
+## 4. What it does — the 8 steps
 
 | Step | Action |
 |---|---|
@@ -51,8 +85,10 @@ or scripted VPS provisioning.
 
 > `70-autonomous` (register autonomous-agent charters) runs inside `60-services`
 > when the profile enables it.
+> `45-claude-plugins` (read `Agentik_SSOT/claude-plugins/claude-plugins.yaml`
+> and run `claude plugin install …`) sits between `40-mcp` and `50-telegram`.
 
-## 4. Idempotent & resumable
+## 5. 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
@@ -60,7 +96,7 @@ Re-running `install.sh` **skips completed steps** — if it stopped at step 5/8
 
 Force a full re-run: `bash install.sh --force`.
 
-## 5. Profiles
+## 6. Profiles
 
 | Profile | For | Result |
 |---|---|---|
@@ -70,7 +106,7 @@ Force a full re-run: `bash install.sh --force`.
 
 Select with `--profile vps` (default on Linux) or in the manifest.
 
-## 6. The 24/7 layer
+## 7. The 24/7 layer
 
 On the `vps` profile, `60-services` installs three `systemd` user units:
 
@@ -81,14 +117,14 @@ On the `vps` profile, `60-services` installs three `systemd` user units:
 These give Omega OS its "Agent runs 7/7" property: the VPS keeps the engine and
 every autonomous agent alive across reboots.
 
-## 7. Telegram
+## 8. 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
+## 9. Verify
 
 ```bash
 omega doctor      # 8-block tree + event store — must print "doctor: PASS"
@@ -96,11 +132,13 @@ omega status      # every task and its derived state
 omega version
 ```
 
-## 9. Troubleshooting
+## 10. Troubleshooting
 
 | Symptom | Fix |
 |---|---|
-| `preflight: running as root` | create and use a non-root `sudo` user |
+| `running as root with no user mode chosen` | add `--create-user` (default name `omega`) or `--user <existing-name>` |
+| `creating users on macOS is not supported` | install as yourself (no flag), or `--user <existing-mac-user>` |
+| `user '<name>' does not exist` | the name passed to `--user` isn't on the system — use `--create-user <name>` to make one |
 | `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` |

package/docs/MCP-AND-PLUGINS.md

@@ -84,10 +84,37 @@ The installer ships a curated catalog. Defaults marked ✓ are pre-selected:
 | Postgres | data | |
 | Brave Search | search | |
 
-Plus the **Claude Code plugin marketplace** — the same plugins offered in the
-Claude desktop app under *Connectors → Customize*. The installer queries the
-marketplace and lists them in the same checklist, so a fresh VPS can be brought
-up with the full plugin suite in one pass.
+Plus the **Claude Code plugin marketplace** — installed by the dedicated
+`45-claude-plugins` step, which reads its own SSOT catalog at
+`Agentik_SSOT/claude-plugins/claude-plugins.yaml`:
+
+```yaml
+marketplaces:
+  - id: claude-plugins-official     # built-in, always available
+    builtin: true
+  - id: thedotmack                  # add-on marketplaces
+    source: "github:thedotmack/claude-mem"
+catalog:
+  - id: claude-mem
+    marketplace: thedotmack
+    scope: user
+    recommended: true
+  - id: frontend-design
+    marketplace: claude-plugins-official
+    scope: user
+    recommended: true
+```
+
+For each selected plugin, the installer runs:
+
+```
+claude plugin marketplace add <source>     # only for non-builtin marketplaces
+claude plugin install <name>@<marketplace> -s <scope>
+```
+
+The step is interactive by default (whiptail checklist) and headless under
+`--non-interactive --manifest manifest.yaml` (reads `claude_plugins:` from
+the manifest).
 
 ---