Omniscio

KMS Quick Reference Wizard

A seven-step walkthrough that introduces the KMS vault to someone opening it for the first time — what the vault is, how notes and organisation work, how to find things, the agent tools, asking your vault a question, and setting up the vault folder. It changes nothing except that folder, and can be replayed whenever you like.

On this page

What it is

A 7-step educational wizard that walks first-time KMS users through the core concepts: what KMS is, how notes and organization work, how to find things, what agent tools are available, how Ask Your Vault works, power features like pop-out windows and AI summaries, and an interactive vault folder setup step — first in the tour, before Welcome, when no folder is set yet, and last once one is. It auto-opens the first time a user enables KMS and is replayable from Settings at any time.

The wizard does not change any settings or create any data (except the vault root on the folder step). It is purely educational; closing it early is fine and the user can replay it whenever they want.

Where to find it

It opens by itself the first time you visit the Vault panel after enabling it. Afterwards it is replayed from Settings → Setup Wizards, where a Vault Quick Reference card carries a Take / Retake button and a tick once you have been through it.

How it behaves

How to use it

First-time auto-open

When a user enables the Vault for the first time (installs The Vault from Marketplace → Inbuilt), the wizard auto-opens the moment they navigate to the Vault panel. This happens exactly once; the nothariQuickReferenceCompleted setting flag prevents it from re-opening on subsequent visits.

Replay from Settings

Two replay entry points exist:

  1. Settings > Setup Wizards -- a "Vault Quick Reference" card with a Take/Retake button. Shows a green checkmark if the wizard has been completed before.
  2. Settings > Features > Vault -- a "Quick Reference Guide" card near the top of the Vault feature settings.

Both navigate to the KMS panel first (via activateVirtualProject), then open the wizard. This is necessary because the wizard component is mounted inside KmsView, not globally.

Inbox alert for existing users

Users who already had KMS enabled before the wizard was added receive a one-shot inbox alert: "Your knowledge base just got a guide." The alert has a primary action button that navigates to Settings > Setup Wizards where the user can launch the wizard. The alert uses the kmsWizardAlertSeen system setting as a one-shot flag.

Reset via CLI

An agent can reset the wizard so it auto-opens again:

curl -X PATCH http://127.0.0.1:19519/settings/nothariQuickReferenceCompleted \
  -H "Authorization: Bearer $AMC_CLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": false}'

The 7 steps

The seven steps sit in five labelled phases (the first and last are unlabelled):

Phase Step Content
— Welcome Cinematic dark backdrop intro; "Let's Go" button
The Basics Notes & Organization Rich editor, wiki-links, tags, file tree, bookmarks
The Basics Finding Things Ctrl+P quick switcher, Ctrl+Shift+P command palette, Ctrl+F find
AI Integration Your Agents, Your Knowledge How agents reach your notes through the /kms/* control API, and that any session can read and write them as ordinary Markdown files
AI Integration Ask Your Vault Sessions tab, ask anything, full context
Beyond the Editor More Superpowers Pop-out window, AI summaries, image analysis, custom themes
— Set Up Your Vault Interactive folder picker with real-time validation

The Vault Setup step is the only one that writes state: it validates and persists the user's chosen vault folder path via KMS_VALIDATE_VAULT_ROOT.

Where that step sits depends on whether a folder is already set. With no vault folder configured the Vault does nothing at all, so the folder step moves to first, ahead of Welcome, and Welcome and the five read-only slides follow it — burying the one step that fixes an empty Vault behind six slides meant the tour could finish without the Vault ever working. Once a folder is set the tour keeps the order in the table and ends with it. getKmsWizardSteps takes that state as an argument, and KmsQuickReferenceWizard reads it once when it mounts, which KmsView does each time the tour opens, so the folder step cannot move out from under someone on the step itself; the next open picks up the new value.

A click on the backdrop no longer closes this tour: a stray mis-click used to end it before the folder step while the tour had already recorded itself as seen, so it never came back. X and Escape still close it.

On a phone or in the browser

The wizard is mounted inside KmsView, which also renders on the phone and in the web client, so it opens there too — but a phone cannot browse the computer's folders. In the web client the wizard therefore shows a short "Open {appName} on your computer to set your vault folder" note where the folder picker would be, and the Vault Setup step never calls DIALOG_OPEN_FOLDER. The same desktop-only affordances are left out rather than advertised: the Ctrl+P / Ctrl+Shift+P / Ctrl+F key-caps are hidden on the Finding Things step (the feature descriptions stay), and the pop-out window row is hidden on the Power Features step. The rest of the tour reads the same in both places.

  • first-time-setup.md -- the app-level onboarding wizard (different feature, same <Wizard> primitive)
  • inbox-alerts.md -- the inbox alert primitive used for the existing-user notification
  • .claude/memory/contracts/kms-wizard-contract.md -- the feature contract

Last verified 2026-11-17