---
title: KMS Quick Reference Wizard
---

# KMS Quick Reference Wizard

## 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 a final interactive vault folder setup step. 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 final 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 KMS panel after enabling KMS. Afterwards it is replayed from **Settings → Setup Wizards**, where a **KMS 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 KMS for the first time (flips **Enable KMS** in Settings > Features), the wizard auto-opens the moment they navigate to the KMS 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 "KMS Quick Reference" card with a Take/Retake button. Shows a green checkmark if the wizard has been completed before.
2. **Settings > Features > KMS** -- a "Quick Reference Guide" card near the top of the KMS 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:

```bash
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 wizard progresses through 5 phases:

| Phase | Step | Content |
|-------|------|---------|
| Welcome | Welcome | Cinematic dark backdrop intro; "Let's Go" button |
| Notes & Organization | Notes & Organization | Rich editor, wiki-links, tags, file tree, bookmarks |
| Finding Things | Finding Things | Ctrl+P quick switcher, Ctrl+Shift+P command palette, Ctrl+F find |
| Agent Tools | Agent Tools | The 8 MCP tools agents use to read your vault |
| Agent Tools | Ask Your Vault | Sessions tab, ask anything, full context |
| Power Features | Power Features | Pop-out window, AI summaries, image analysis, custom themes |
| Vault Setup | Set Up Your Vault | Interactive folder picker with real-time validation |

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

## For agents

### How it works

The wizard uses the shared `<Wizard>` + `<WizardStepLayout>` + `createWizardStore()` pattern (the same primitive as the app onboarding wizard). Step definitions are in `src/renderer/src/features/kms/wizard/kms-wizard-steps.ts`; each step component lives in `src/renderer/src/features/kms/wizard/steps/`. The wizard shell is `KmsQuickReferenceWizard.tsx`, mounted inside `KmsView.tsx`.

The auto-open gate is a pure function `shouldAutoOpenKmsWizard(settings)` that checks `nothariEnabled && !nothariQuickReferenceCompleted`. On finish, the wizard persists `nothariQuickReferenceCompleted: true` via IPC.

The inbox alert producer (`src/main/services/kms/kms-wizard-alert.ts`) runs at startup with a 3-second delay, mirroring the `hardware-spec-alert.ts` one-shot pattern. It checks three gates: `kmsWizardAlertSeen` > `nothariEnabled` > `nothariQuickReferenceCompleted`.

## Related

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