omni

<!-- skills-lint:ignore -->
<!--
  This skill references `omni connect` and other omni subcommands that are
  registered with omni's `advanced` / `standard` visibility categories and
  don't surface in plain `omni --help` (which shows the curated `core`
  subset only). The skills-lint script collects subcommands by parsing
  `omni --help`, so it reports false positives for any non-core call.
  The skill correctly declares allowed-tools for `omni *` and `genie *`.
  Drop this marker once skills-lint learns to probe each subcommand
  individually (or omni exposes a richer `--help --all` mode that
  enumerates every visibility category).
-->

# /genie:omni — Canonical Genie ↔ Omni Wiring

Single-command wizard that takes an operator from "no agent yet" (or "an existing genie agent") to "agent answering messages on a channel". Wraps `genie agent register` + `omni connect` + verification into one conversational flow so operators don't have to remember two systems' command surfaces.

## When to Use

- Adding a new agent to a connected Omni channel.
- Wiring an existing genie agent dir to a fresh Omni instance.
- Verifying that an existing wire still works end-to-end.
- Operator types `/genie:omni` and expects the assistant to drive.

If the legacy multi-command chain (`omni providers create` + `omni agents create` + `omni instances update --agent` + `omni routes create`) is what you reach for first — stop and use this skill instead. The legacy chain still works for power users / CI but emits stderr deprecation nudges pointing here.

## Pre-conditions (verify before driving)

These checks are quick and tell you which Phase to start in. Always run them up front:

```bash
omni auth status      # Phase 1 needed if missing or invalid
genie serve status    # Phase 4 verification needs this green
omni instances list   # at least one connected instance needed for Phase 3
```

## Flow

### Phase 1 — Omni installed and authenticated?

**Entry:** Always (first thing to check).

**Steps:**

1. Run `omni auth status`. If it reports a valid connection, **skip to Phase 2**.
2. If not authenticated or omni is not installed:
   - Tell the operator that omni needs a one-time bootstrap and instruct them to run `omni install` **in a separate terminal** (do NOT nest two interactive flows from inside this skill — the omni installer is itself a wizard).
   - Wait for the operator to confirm `omni install` completed.
   - Re-run `omni auth status` to verify, then continue to Phase 2.

**Exit:** `omni auth status` succeeds.

### Phase 2 — Pick or scaffold the genie agent dir

**Entry:** Phase 1 passed.

**Steps:**

1. Ask the operator: *"Which genie agent are we wiring? Existing one, or do we scaffold a new dir?"*
2. If existing:
   - Ask for the agent name.
   - Run `genie dir ls <name>` to confirm it's already registered. If yes, skip to Phase 3.
   - If not registered, ask for the agent's home directory — the path that contains a real `AGENTS.md`. Validate up front:
     - The path must exist.
     - `<dir>/AGENTS.md` must be a real file, **not** a symlink. If it's a symlink, ask whether the operator wants to register the dir the symlink points to instead (almost always the right answer), or pass `--allow-symlink` (only if intentional template-sharing layout).
   - Run `genie agent register <name> --dir <validated-path>`. The default flow auto-registers the agent in Omni (creates the agent record). Do **NOT** pass `--skip-omni` here — Phase 3 uses `omni connect` which expects the agent record to exist.
3. If scaffolding new:
   - Direct the operator to `/genie:wizard` (which scaffolds an agent identity and AGENTS.md), then come back to this Phase 2 with the freshly-scaffolded dir.

**Exit:** `genie dir ls <name>` returns a clean entry with the correct `Dir:` field.

### Phase 3 — Bind to an Omni instance

**Entry:** Phase 2 passed.

**Steps:**

1. Run `omni instances list` and show the operator the connected instances (those with `ACTIVE=yes`). Highlight the channel and profile name so the operator picks the right one.
2. If there are no connected instances, point the operator at `/omni:omni-setup` (the omni plugin's connect-channel wizard) and pause this flow until an instance is connected.
3. Once the operator picks an instance:
   - Run `omni connect <instance-id> <agent-name>` — this is the canonical command. It:
     - reads `genie dir ls <name> --json` (so the agent must have been registered in Phase 2),
     - creates (or reuses) a `nats-genie` provider,
     - creates (or reuses) the omni agent record bound to that provider,
     - updates the instance with `agentId`, `agentProviderId`, `agentReplyFilter`, and `triggerMode`.
   - The operator can pass `--mode turn-based` (default, recommended for chat) or `--mode fire-and-forget` if they have a reason. Default `--reply-filter all` is fine for KHAL-V1-LAUNCH-style group bots.
4. Confirm the success summary printed by `omni connect` — note the agent ID, provider ID, and the NATS subjects (`omni.message.<inst>.*` inbound, `omni.reply.<inst>.*` outbound).

**Exit:** `omni connect` exits 0 with the configuration summary.

### Phase 4 — Verify the round-trip

**Entry:** Phase 3 passed.

**Steps:**

1. Confirm the bridge daemon is running:
   ```bash
   genie serve status
   ```
   If not running, start it:
   ```bash
   genie serve start --headless
   ```
2. Confirm the bridge is subscribed to the right NATS subjects:
   ```bash
   nats --server localhost:4222 server report connections | grep genie-omni-bridge
   ```
   Should show 7+ subscriptions with non-zero uptime.
3. Run a synthetic round-trip:
   - Tell the operator to send a real test message in the chat that's now wired (e.g. a WhatsApp group).
   - Watch the omni-api log: `tail -f ~/.pm2/logs/omni-api-out.log | grep <chat-id>` — expect `Received → Dispatching → Published to NATS → Agent response` within a few seconds.
   - On the genie side: `genie agent ls` should show a new per-chat agent (e.g. `<name