--- title: Mind Map (build a map with the keyboard or the mouse) --- # Mind Map (gated feature) ## What it is > **Status: in-development (gated).** Hidden by default; revealed by the > **Settings → Features → "Mind Map"** toggle or by launching with > `AMC_SHOW_MINDMAP=1`. Until a developer flips it to shipped, most users won't > see it. (The toggle moved out of the experimental Lab section on 2026-07-07 — the > feature is still in-development and off by default; only the toggle's home changed.) ### What it is A standalone **mind-mapping canvas** built into Omniscio — separate from the coding sessions. You build a single-rooted tree of text ideas, the app auto-arranges it, and you can save a whole library of maps, theme them, import and export them, get AI help filling them out, and publish a read-only share link. The drawing surface is a pan/zoom canvas (powered by React Flow); the layout arranges itself automatically (powered by d3) so you never drag boxes around just to keep things tidy — you focus on the ideas and the map lays itself out in one of four directions (left→right by default, plus right→left, top→bottom, bottom→top). ## Where to find it The **Mind Map** panel in the sidebar — its own feature, and it has to be enabled before it appears. Opening it lands you on the saved-maps library. ### Opening it & the saved-maps library - Open it from the **toolbar** (a network-of-nodes icon) — or from anywhere with **Ctrl+M** (rebindable in Settings → Keyboard Shortcuts; it does nothing until the feature is on). Either way it opens **docked inside the app** by default: project bars on the far left, your **saved-maps list** in the session-sidebar slot, and the editor (header + toolbar + canvas) filling the main panel. A **maximize** button in the header flips to a **full-screen** view and back; your choice is remembered. Opening always lands you on your current map, or a fresh blank one if none is open. Opening the Mind Map closes an open Whiteboard — the two share the same docked slot, so only one shows at a time. - **New to it? Take the guided tour.** A quick walkthrough is offered automatically the first time you open the Mind Map, and you can replay it anytime from the **"Take a tour"** button in the toolbar (next to the "?") or from **Settings → Tours → Mind Map**. (The tour only appears while the feature is on.) - Every map **auto-saves** a moment after you stop editing (to a local database) — there's no Save button. - **Manage a saved map from its row.** The rows carry no always-visible buttons — **right-click a map** (or **press-and-hold** on touch) opens a small menu with **Rename** and **Delete**. Delete still asks you to confirm ("Delete mind map?"); there's no separate undo, so the confirmation is the safety net. (Renaming from the menu is the same inline edit as double-clicking the title.) - **Search your maps.** A search box under the "Mind Maps" heading (shown whenever you have at least one map) filters the list by title as you type; an ✕ clears it, and a query that matches nothing shows "No maps match your search." - A new map **opens with the cursor already in the root ("main") node** — a blank, focused field — so you can type the title the instant it appears, no click first. - A new map is titled **"Untitled"** until you type into the **root node** — then the title auto-derives from the first 40 characters of that text plus the map's created date (e.g. `Project plan — Jun 6, 2026`). Renaming the map yourself — **single-click the title in the editor header** to edit it inline (Enter or click-away saves, Esc cancels), or double-click it in the saved-maps list — **locks** the title so editing the root no longer changes it. ## How it behaves ### Building a map with the keyboard The canvas is keyboard-first. With a node selected: | Key | Does | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Tab` | Add a **child** of the selected node | | `Shift+Tab` | Add a **parent** _behind_ the node — it slides in between this node and its parent (on a left→right map's **center node** it makes a **left** branch instead — see the note below) | | `Enter` | Add a node **at the current level** (a sibling below; the root adds a child instead) | | `Enter` _while editing_ | Commit the text **and** open a fresh sibling below — so you can type a list quickly (an empty `Enter` ends the run) | | `Tab` _while editing_ | Commit the text **and** open a fresh **child** one level deeper (an empty `Tab` ends the run; the parent expands) | | `Shift+Tab` _while editing_ | Commit the text **and** open a fresh **parent** behind it to name (an empty `Shift+Tab` ends the run) | | `Shift+Enter` | Add a sibling **above** the current node | | `Space` / `F2` / double-click | Edit the selected node | | `Delete` / `Backspace` | Delete the node (and its branch) | | Arrow keys | Move the selection (parent / child / sibling — **mapped to the map's flow direction**, see note) | | `/` · `f` · `c` | Collapse / expand the node's children | | `V` | **Fit** the whole map into view (the keyboard twin of the toolbar's Fit button) | | `Ctrl+↑` / `Ctrl+↓` | **Move** the node up / down (reorder among siblings) | | `Ctrl+←` / `Ctrl+→` | **Move** the node out a level (`←`, outdent) or in under the previous idea (`→`, indent) | | `Ctrl+Z` / `Ctrl+Y` | Undo / redo | | `Ctrl+X` / `Ctrl+C` / `Ctrl+V` | Cut / copy / paste a node (and its branch) | | `Ctrl+N` | Start a brand-new map (the current one autosaves and stays in the saved-maps list) | | `l` | Open the selected node's **layer** (creates a blank one first if it has none — see **Layers** below) | | `]` / `[` | **Swap** between the base map and the node's layer (a toggle) | | `n` | Add or edit a **hidden note** on the selected node (see **Hidden notes** below) | | `Esc` | Deselect (or cancel an in-progress edit) | | `?` | Show the **keyboard shortcuts** cheat-sheet (this list, grouped by category) | > **The table above shows the default left→right map. Everything the keyboard does — > the arrows, the Move chords, and `Tab`/`Enter` — rotates with the map's flow direction** > so a key matches what you see. On a **top-down** map, `↓` walks _into_ a child, and > **`Tab` adds a sibling while `Enter` dives into a child** (the same while you're typing). > On a **four-sided spider** map, each branch is driven by the way it grows, and from the > center an arrow jumps to the branch on that side. > **From the center ("main") node, the four create keys fan out in four directions.** On a > left→right map with the center node active, `Tab` / `Shift+Tab` / `Enter` / `Shift+Enter` > shoot a **new branch to the right / left / down / up** — building the four-sided **spider** > with no dragging. Each press _from the center_ adds another branch on that side (so to grow > a second arm you come back to the center and press again), and it works the same whether the > center node is selected **or** you're still typing its label (the key saves the label first). > `Tab` → right is just the ordinary "add child"; the other three are the new directions. This > is a left→right-map, center-node-only behavior — **branch nodes and the other flow directions > keep the meanings in the table above.** Every **Move** shortcut also works with **`Alt+Shift`** held instead of `Ctrl` (e.g. `Alt+Shift+←` outdents the node) — a handy alternate when your OS already uses `Ctrl+Arrow`. **Don't remember the shortcuts?** Press `?` on the canvas — or click the faint **"Press ? for shortcuts"** hint in the bottom-left corner — to pop open a tidy cheat-sheet of everything above, the same way `?` opens the shortcuts list elsewhere in the app. (Desktop only; on a phone or tablet there's no physical keyboard, so the on-screen buttons below take over instead.) **A collapsed node carries a small count circle** on the side its children branch from — the number inside is how many direct children are hidden, so you can see there's more (and roughly how much) without expanding. It appears only when something's actually hidden; expand the node (`c` or the toolbar) and it's gone. **Connection dots appear only where a line actually connects.** A node shows a small filled dot on each side a line meets it — incoming from its parent, and outgoing to its children. A dead-end (leaf) node has nothing leaving it, so it shows no outgoing dot at all (the canvas never draws an empty circle on a leaf); give it a child and the outgoing dot appears. **An "Expand all" toolbar button** (an unfold icon) appears on the canvas toolbar **only while at least one branch is collapsed** — one click reveals every collapsed branch at once (a single Undo step), and the button disappears again once everything's open. It's the discoverable, do-it-all-at-once companion to per-node `c` — handy when a big map has several folded branches and you want the whole picture back without hunting them down. **Undo and redo are also toolbar buttons** (near the top-left of the canvas toolbar) — the discoverable version of `Ctrl+Z` / `Ctrl+Y`, so you don't have to know the shortcut. They grey out when there's nothing to undo or redo, drive the exact same history the keyboard does, and clicking one hands keyboard focus back to the map so the next `Ctrl+Z` still works. ### Building a map with the mouse (drag) Drag a node and **what the drop means depends on where you release it**, and every drop is **hold-to-commit** so nothing happens by accident — a candidate shows a **faint** green hint while you drag, and only after you **hold ~0.25s on the same target** does it lock in (full highlight = release now and it happens). Brush past and it clears. You can move **any node onto any other node**, anywhere in the map: - **Onto another node's body** → **nest** it as that node's child (snaps to the nearest valid node; never onto its own descendant). This includes dropping onto the central **"main" node** to make a new **top-level branch** — works in every layout direction. - **At any node's top/bottom edge** → **slot it in right there**, just above or below that node, in that node's list (a thin line shows where it lands). This works **across branches** too: pull a node out of one branch and drop it between two children of another, and it auto-nests into that list at the spot you choose. - **Into the empty space on any side of the root** — above, below, left, or right (left→right view only) → make it a **top-level branch on that side**. Pull branches to different sides and the root re-centers into a **spider**, arms radiating in all four directions (a diagonal drag lands on whichever side you pull it furthest toward). Each branch remembers its side. ### Editing text & the node menu - Editing opens an inline field. A node still showing its **"Untitled"** placeholder opens **blank**; a node with real text opens pre-filled and selected. Commit with `Enter` or by clicking away; `Esc` cancels. - **Exactly one node is ever selected.** Moving the selection finishes the node you were editing, and a node you opened but never named auto-removes itself — so an empty box can't linger and two selection rings can never both show. - **Abandoning a brand-new node returns you to where you were.** If you add a node (`Enter`/`Tab`/`Shift+Enter`) and then bail without typing — a blank `Enter`/`Tab`, or `Esc` — the empty node disappears and the highlight goes back to the node you were on _before_ you created it (not its parent). Emptying an existing node still drops the highlight to its parent as before. (A node inserted with `Shift+Tab` is the exception — it already has a child, so an un-named one stays put as "Untitled" rather than vanishing; you placed it deliberately.) - **Right-click a node** for a menu with **Cut / Copy / Paste** (each showing its shortcut) — the discoverable version of the keyboard clipboard. It greys out what doesn't apply (Cut/Copy on the root, Paste with nothing copied). The menu also has **Add note / Edit note** (see **Hidden notes** below), available on any node. - Node labels support **inline markdown** — `**bold**`, `*italic*`, `~~strike~~`, and `` `code` `` render in the node (editing shows the raw text). - **Long labels wrap.** A label grows to a max width (~240px) and then **wraps onto multiple lines**, growing the node's height to fit — up to **4 lines**, after which it ends with an ellipsis (so a runaway label can't make one giant node). **Every node's box hugs its text** — there's no empty space to the right: a wrapped node hugs its longest line (it doesn't stay stuck at the full ~240px), and a one-line node hugs its single line too (it sizes to its content, not the max width). The auto-layout keeps the **same visible gap between stacked nodes no matter how tall each one is**, so a wrapped node never crowds or overlaps its neighbour, and a one-line node keeps the original gap. The editor **wraps as you type** — the field grows wider with short text and, once it reaches the node's max width, wraps onto new lines and grows taller, matching the finished node (you're still editing one string; pasted line breaks become spaces). The share page and exported PNG wrap to match the canvas. - **Lines get evened out automatically.** When a label wraps, the lines are **balanced** instead of cramming line 1 full and leaving a bare scrap on line 2: a word drops to the short line and the box gets more compact (on the canvas **and** the shared map). It leans fairly even by default, and evening the lines never adds a line, so nothing shifts or overlaps. ## Related - [Mind Map part 2](mindmap-part-2.md) — hidden notes, layers, look and layout, importing and sharing, the AI features, touch, and the internals. - [mermaid-diagrams.md](mermaid-diagrams.md) — the same shared diagram engine, drawing a map as text. - [mind-map skill](use-skills.md) — the bundled skill that builds a map from a conversation. ### Related - Omniscio’s unreleased-feature (“Lab”) gate — how a hidden in-development feature like this one is revealed and eventually shipped. - Developer reference (invariants + the tests that lock them): `.claude/memory/contracts/mindmap-contract.md` (the canvas) and `.claude/memory/contracts/mindmap-list-row-actions-contract.md` (the saved-maps list — row right-click/long-press menu + title search). Build/bug history: `.claude/memory/postmortems/mindmap-postmortem.md`.