openloomi-tour

# OpenLoomi Tour — Hands-on Walkthrough

This skill is the **canonical first-run experience**. After
`openloomi-setup` finishes and prints its post-ready walkthrough, the
user can type **`@OpenLoomi tour`** (or any of the trigger phrases) and
you'll run the same pipeline live, stopping between phases so the user
can react.

The tour is **interactive, idempotent, and skippable**. Each phase
checks its own prerequisite and lets the user move on with `next` /
`skip` / `back`. Nothing is destructive — if the user already did a
phase, you re-confirm it and move on.

---


## Reference docs

Quick links to the OpenLoomi docs that this tour draws from. Every
phase below cites the relevant entries inline.

| Topic | Doc |
| --- | --- |
| Getting started / install / one-time setup | <https://openloomi.ai/docs/getting-started> |
| What OpenLoomi is (the pipeline in one page) | <https://openloomi.ai/docs/what-is-openloomi> |
| Glossary — every term used here (Connector / Signal / Loop channel / Action Runner / etc.) | <https://openloomi.ai/docs/glossary> |
| Loop engine — ticks, Decisions, cards, channels, classifier rules | <https://openloomi.ai/docs/loop> |
| Loop — Approve / Edit Draft / dry-run anatomy of a Card | <https://openloomi.ai/docs/loop#approvals-and-dry-run> |
| Memory — people / projects / notes / insights / Screen Capture | <https://openloomi.ai/docs/memory> |
| Knowledge Base / Library — uploaded documents (PDF, DOCX, MD, …) | <https://openloomi.ai/docs/library> |
| Connectors — Slack / Gmail / GitHub / Linear / Notion / HubSpot / … | <https://openloomi.ai/docs/connectors> |
| Native messaging bots — Telegram / WhatsApp / iMessage / Feishu / DingTalk / QQ / WeChat | <https://openloomi.ai/docs/messaging-apps> |
| Composio / Loop channel — OAuth broker for 1000+ apps | <https://openloomi.ai/docs/glossary#composio--loop-channel> |
| Attention Agent — Loomi the fox, card bubbles, sprite states | <https://openloomi.ai/docs/attention-agent> |
| Agent Runtimes — Claude / Codex / OpenCode / Hermes / OpenClaw | <https://openloomi.ai/docs/reference/agent-runtimes> |
| Plugins — bridge from Claude Code / Codex into OpenLoomi | <https://openloomi.ai/docs/plugins> |
| Automation / Proactive Tasks — recurring scheduled work | <https://openloomi.ai/docs/automation> |
| Chat — conversational entry point (not Loop) | <https://openloomi.ai/docs/chat> |
| Skills — reusable capabilities inside OpenLoomi | <https://openloomi.ai/docs/skills> |
| Audit Log — every consequential moment recorded | <https://openloomi.ai/docs/privacy-security#audit-logs> |
| Privacy & Security — local-first, AES-256, what's stored where | <https://openloomi.ai/docs/privacy-security> |
| Changelog — what's new in each release | <https://openloomi.ai/docs/changelog> |

## Phase 0 — Pre-flight

Before running any phase, do **three** things in this exact order:

```bash
# 1. Readiness (sandbox-aware)
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" setup-status

# 2. If loopbackAccessAmbiguous: true, refresh host probe outside sandbox
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" run-host-probe

# 3. Confirm Codex runtime is the active default agent
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" codex-runtime-info
```

Decision tree:

| Pre-flight outcome | Tour action |
| --- | --- |
| `ready: true`, `defaultAgent: codex` | Proceed straight to Phase 1 |
| `ready: false`, `nextAction: setup` | Tell the user setup hasn't run yet. Offer to invoke `openloomi-setup` first, then return to tour |
| `ready: false`, `OPENLOOMI_API_UNREACHABLE` | Re-run `run-host-probe` outside the sandbox; if still unreachable, surface the bridge's `hints[]` and stop |
| `defaultAgent != codex` | Ask the user whether to switch to Codex runtime or tour anyway with the current provider |

Print the user's current state in one line (mode, installed, default
agent) before announcing Phase 1.

---

## Phase 1 — Pet reaction (always run)

The pet is the **fastest, cheapest, safest** proof that the desktop is
listening. Run all four "sight" states in sequence so the user sees the
sprite set:

```bash
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" pet happy
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" pet thinking
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" pet working
node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" pet juggling
```

After each, say "Loomi just showed the `<state>` sprite — that proves
the desktop is watching the pet watcher and accepting state changes
from Codex." End by leaving the pet at `happy` (success-state feel).

For the full state taxonomy, see the [Attention Agent](https://openloomi.ai/docs/attention-agent) doc; for the broader pipeline see the [Glossary](https://openloomi.ai/docs/glossary).

If `POST /api/pet/state` returns "would have set state to X — pending
OpenLoomi endpoint", note that the runtime is older than the bridge
expects; the pet widget will catch up via the `~/.openloomi/loop/`
file watcher anyway.

---

## Phase 2 — Onboarding & input sources (interactive)

This is the first **real** action and the first place the user may have
to do something in another window. There are **three** input paths;
offer them all and let the user pick:

> **A. Native bot** ([Telegram / WhatsApp / iMessage / Feishu / DingTalk
> / QQ / WeChat](https://openloomi.ai/docs/messaging-apps)) — fastest, no browser OAuth. Best if you already use
> one of those.
>
> **B. [Composio OAuth](https://openloomi.ai/docs/glossary#composio--loop-channel)** (Gmail / Slack / GitHub / Google Calendar /
> Notion / Linear / HubSpot / LinkedIn / Jira / Asana / Discord / X) —
> one browser click, works for the apps most people already have. Full list at [Connectors](https://openloomi.ai/docs/connectors).
>
> **C. [Screen memory](https://openloomi.ai/docs/memory) (macOS only)** — right-click the Loomi pet on the
> desktop → **Open Settings** → enable **Screen Capture**. The global
> capture shortcut (configurable in the same panel) summarises the
>