Guided steps (a steps window that follows you around the app)

What it is

Some jobs an agent is not allowed to do for you: a setting kept for you to decide on purpose, a sign-in only you can give, a panel only you can fill in. The agent used to write the steps in the chat, and they were out of sight the moment you left it. Now the agent hands the steps to Omniscio, and they travel with you as a small checklist window.

It works anywhere in the app, not only in Settings. A step can point at a setting, or at a panel or page such as the Password Vault.

Where to find it

• In a chat: the agent asks How would you like to do it? with two choices. A. Give me guided steps (recommended) and B. Just list the steps here in the chat. Pick A and press Send and the window opens. Clicking the A link directly opens it too.
• Opening it twice: opening the same steps again brings the window back with your ticks kept.
• On the screen: the window is a 380 pixel column on the right edge of every screen. The screen narrows to make room, so nothing is covered. On a phone it is a fold-out card at the bottom instead.
• The on/off switch: Settings → Lab → Guided steps. It is on by default.

How it behaves

What the window shows

The header says GUIDED STEPS with Shrink and Close buttons. Below it:

• The steps' title, and a From <chat name> link that takes you back to the chat.
• A progress bar reading N of M done.
• The numbered steps. The current step is open and the others are folded to one line.

Shrink turns the window into a slim 44 pixel strip at the screen edge that shows how far you are, such as 2/5. Click it to open the window again. If your app window is narrower than 1200 pixels, the window starts shrunk. Close throws the steps away.

The window hides itself while the chat that wrote the steps is on screen, because the steps are already in front of you there. It comes back as soon as you leave that chat.

How the steps behave

• Show me opens the step's own place: the setting, or the panel or page. It never starts anything.
• Steps tick themselves when the agent named an exact setting and value. Change the setting and the step shows Done, ticked automatically. Change it back and it un-ticks.
• Mark done appears on a step that cannot check itself, such as a step about a panel. Once ticked it says Done, with an Undo button.
• The next step opens by itself once the current one is done.
• The setting is marked. While Settings is open and the current step is about a setting, that setting's row gets a coloured ring and a small Step N tag, so you can find it at a glance.
• Back to chat returns to the chat that wrote the steps and leaves the window open.
• Finish is greyed out until every step is done. It then closes the window and opens that chat. The chat gets a line, Guided steps finished · N of N done, and "I've finished the guided steps." is typed into its message box, but only if the box is empty. Nothing is sent for you. The line goes only to the chat that wrote the steps.

Limits

The steps are kept in the app's memory, not on disk. They last up to 7 days, at most 50 sets at a time with the oldest dropped first, and an app restart clears them. A link whose steps are gone says "These guided steps have expired. Ask the chat to send them again." and still opens Settings, so a click is never silent.

Switch the feature off in the Lab and the link still takes you to the first step's place. There is just no window.

For agents

Use this whenever you need the user to do steps by hand anywhere in the app, not only in Settings. Create the steps with POST /settings/guide on the local control server, using your own session's token and X-AMC-Source-Session-Id. Only an agent session can call it, and that session is the chat Finish returns to. It changes no setting and starts nothing.

{
  "title": "Set up your vault",
  "steps": [
    { "text": "Turn on hardcore mode", "setting": "hardcore mode", "key": "hardcoreModeEnabled", "value": true },
    { "text": "Add your first password", "link": "omniscio://session/__plugin_team-password-vault__" }
  ]
}

• title is plain text on one line, up to 80 characters.
• steps holds 1 to 8 steps. text (up to 200 characters) is what the window shows.
• Each step names either setting or link, never both and never neither.
• setting is the plain-English setting name Show me opens, matched the same way as GET /settings/open?q=. key and value are optional and only go with setting. Name a real setting key and the value it should reach, and the step ticks itself. Secret settings such as API keys, unknown keys, settings that are not a simple on/off, number or text, and a value of the wrong type are refused with a 400 naming why.
• link may only open a place: omniscio://session/__<panel id>__ for a panel (for example __plugin_team-password-vault__), omniscio://page/<id>, omniscio://setting/<query> or omniscio://inbox. Anything else is refused with "a step link can only open a panel, a page or a setting". A link step has no value to check, so you tick it by hand.
• Every field is plain text with no line breaks or markup, and unknown fields are refused.

The reply is 200 with { ok: true, data: { guideId, url, markdown, questionMarkdown } }.

• url is the omniscio://settings-guide/<id> link, in the scheme of the running copy of Omniscio.
• markdown is a plain link to it.
• questionMarkdown is the numbered question described above, with the link already inside option A. Paste it as your question card and wait for the answer. If the user picks B, list the steps in the chat.

A call that names no session of your own is refused with a 400. If the route refuses you, fall back to a plain GET /settings/open?q= link. The link carries only the id, never the steps, so nothing outside the app can put words in the window. The rules are in the guided steps contract: settings-guided-steps-contract.md.

Related

The Settings system page explains how Settings and its search are organised, and the deep links page lists every omniscio:// link, including this one. The control-server reference (part 3) covers GET /settings/open, the one-step version of this link that only opens a setting.