User Guide

Current — this is the living version. Historical snapshots are linked from Index-Releases.

Motion User Guide

Motion is a local-first technical writing IDE. It edits markdown that lives on your own disk, renders diagrams and runs SQL inline, and can generate both from plain-language prompts.

This guide covers the app as it behaves after the v0.1.0 validation loop and the post-release dogfood fixes (labeled Save, new-note persistence, dataset/SQL install coverage). Where something is incomplete, it says so.

---

Two ways to run, and why it matters

bun tauri dev   # desktop app
bun run dev     # browser at http://localhost:3000

Desktop is the real product. A native folder picker, and full read/write access to any file inside the folder you open.

Browser runs against a fixed workspace directory instead of a folder picker, set by the MOTION_WORKSPACE environment variable (defaulting to public/demo):

MOTION_WORKSPACE=~/notes bun run dev

Both modes now read and write real files through the same rules, so behaviour you see in the browser is behaviour the desktop app is held to. Browser mode exists so the interface can be driven by automated tests (Playwright E2E) before anyone opens the app.

---

Getting started

1. Click Open Folder. On desktop you pick a folder; in the browser it opens the configured workspace.
2. The sidebar lists every .md file underneath it, including nested folders (flat list of basenames). Use Search notes to filter by filename.
3. Click a note to open it. Use the arrow keys and Enter if you prefer the keyboard — the list is fully navigable.
4. Edit, then press ⌘S (Ctrl+S) or click the labeled Save button in the editor toolbar. The status area shows Saving… / Saved / Save failed.

New Note creates a timestamped untitled-*.md in the open workspace and writes a stub # New Note immediately. Keep editing, then Save so your changes are on disk.

Motion cannot read or write anything outside the folder you opened. Paths are resolved to their real location first, so a symbolic link pointing elsewhere is refused rather than followed.

---

View modes

Mode	What you get
WYSIWYG	Rendered editing — headings, lists, diagrams in place
Markdown	The raw source in a plain text area
Split	Rendered editor beside the markdown source

Switch freely; your edits carry across. Split view shows the markdown source, not a second rendered preview.

---

Content blocks

Five block types. Insert them from the toolbar, or type / at the start of an empty line and pick from the menu.

Mermaid

A diagram from Mermaid source. Click it to edit; it re-renders as you go. Invalid syntax shows an error in the block instead of replacing your content.

Dataset

Registers a local .csv, .json or .jsonl file as a named table:

source: data/sales.csv
name: sales
limit: 5

Use the file picker to choose a source. Store the path relative to your workspace — a document written that way opens correctly on any machine.

Query

SQL against the tables your Dataset blocks registered, run in-browser by DuckDB-WASM:

sql: SELECT name, score FROM sales ORDER BY score DESC

Only SELECT and WITH are permitted, identifiers are validated, and the row limit is clamped. The query box cannot modify your data — by construction, not by convention.

Image gen

Generates an image from a prompt using the imagen CLI, embedded as a data URI.

Diagram gen

Generates a Mermaid diagram from a prompt using the claude CLI. The result is validated as Mermaid before it is accepted, so a bad generation cannot corrupt the document.

Both generative blocks need their CLI on your PATH. Without it the block reports the failure rather than silently doing nothing.

---

Workspace synthesis

Synthesize (next to New Note) reads every note in the workspace, summarizes each one, clusters them by topic, and writes two documents back into the folder:

• TOC.md — a table of contents with a short summary under each note.
• SKILL.md — a synthesized guide to what the workspace is about.

Progress is reported in a bar under the header, and both files appear in the sidebar when it finishes. It re-runs safely: its own output is excluded from the input, so a second run summarizes your notes and not the index it just wrote.

Each note costs one call to the claude CLI, so this is slower and more expensive than the other actions — and it processes at most 40 notes per run, telling you when it has skipped some rather than silently truncating.

Needs claude on your PATH. Without it the status bar reports the failure.

---

Known limitations

Stated here so you meet them on your terms:

• Sidebar is flat — every markdown file under the workspace, not a directory tree. Sort is by name; there is no search inside file contents yet.
• Welcome demo data (sample-data.csv, sample-events.jsonl) only loads when those files exist in the open workspace (they ship under public/demo/). Open an unrelated project folder and the welcome Dataset/Query blocks will error until you pick real files or open a folder that includes the samples.
• No hot reload. The dev server rebuilds when files change but does not refresh the page — reload manually.
• Markdown tables are not supported. Pipe-table syntax renders as plain text; no table extension is registered.
• Synthesize / generative blocks need claude and/or imagen on your PATH.

---

Troubleshooting

"Access denied: path is outside the opened workspace" — you are reaching for a file outside the folder you opened. Open the containing folder instead.

A Dataset block cannot find its file — check the source: path. Relative paths resolve against the workspace root; a path that was absolute on another machine will not exist on yours.

Generative blocks fail immediately — confirm claude or imagen is installed and on your PATH.

Saving appears to do nothing in the browser — this was true before v0.1.0 and is fixed. If you see it now, it is a bug worth reporting.

---

See the Changelog for release history and the Roadmap for what is planned.