Why I made Lucid, in the first person; the accessibility page folded into dictation

CHANGELOG.md

@@ -17,7 +17,7 @@ PDFs and dictation can be set up the way you like them, the Mac window is cleane
 ### Changed
 
 - **A clean top of the window on a Mac.** The grey title bar with the name in it is gone: the page's top row takes its place, with the three round buttons at its left. Windows and Linux keep their own window frame.
-- **A short README**, with the details in `docs/` (installing, what Lucid does, the note formats, accessibility, dictation), and a few words on why Lucid exists: so that notes can be taken by voice, or with one hand. The website says the same.
+- **A short README**, with the details in `docs/` (installing, what Lucid does, the note formats, dictation), and, in the README, why I made Lucid: so that notes can be taken by voice, or with one hand. The website says the same.
 - Tables in the PDF are set ragged right with a little more room between rows, and the bars of a chart use the same greys as on screen.
 - Dictation: the docs say that any app that pastes works, and list the free and open-source ones (OpenWhispr, VoiceNative) next to Wispr Flow.
 - The picture of each note format (`docs/format-samples`) is made with the real app, with real diagrams and every section filled.

README.md

@@ -31,14 +31,35 @@
   </picture>
 </p>
 
-## Why
-
-- **Speech becomes structure, not a wall of text.** Dictation apps give you the words. Lucid gives you the document: an outline
-  of sections, a list of options with the rejected ones crossed out, a table that compares them, a diagram of how the parts
-  connect.
-- **Hands-free, or one-handed.** Lucid began when its author broke their right hand and still wanted to take notes while learning
-  system design. Notes, commands (*"cross out Memcached"*, *"add a CDN in front of the web server"*, *"undo"*) and even diagrams
-  can be spoken. [More on accessibility](docs/accessibility.md).
+## Why I made it
+
+I'm the author. For a while I couldn't type comfortably. I wasn't working, but I still wanted to use the time to keep learning,
+so I went back to system design and other concepts I wanted to revise. Taking notes was the hard part.
+
+There are good open-source tools that turn voice into text, and others that draw diagrams. I couldn't find one project where I
+could just speak and get something *structured*: sections, a list of options with the rejected ones crossed out, a table, a
+diagram. I like minimal themes, so I built the one I wanted, for myself first.
+
+This is the first version, and it doesn't listen by itself. You dictate with an app that pastes text, like
+[Wispr Flow](https://wisprflow.ai), [OpenWhispr](https://github.com/OpenWhispr/openwhispr) or
+[VoiceNative](https://github.com/triggeredcode/voicenative) (my own open-source voice-to-text for macOS), and Lucid turns what
+lands in the box into the page. A fully local voice pipeline will take me some time to get right; you can start with those.
+
+The hardest part was the drawing: a diagram engine and a table engine good enough to build from speech. Command mode edits the
+page by talking to it, and the history keeps what you said, what the model understood and what it changed, so you can always see
+why a page looks the way it does. The model runs on your own computer. I hold it to a bar of 90% on my own evaluation
+([docs/evals.md](docs/evals.md)), and Edit mode and undo are for the rest.
+
+Where it might go, in no particular order: a faster, more live mode with smaller local models (5B to 8B, maybe Gemma) or with
+cloud models through Ollama; fine-tuned models; and fields other than system design. Voice stays in its own project,
+VoiceNative, and I may integrate the two without merging them. These are ideas, not promises.
+
+## What you get
+
+- **Speech becomes structure, not a wall of text.** Dictation gives you the words. Lucid gives you the document: an outline of
+  sections, a list of options with the rejected ones crossed out, a table that compares them, a diagram of how the parts connect.
+- **By voice or by keyboard.** Notes, commands (*"cross out Memcached"*, *"add a CDN in front of the web server"*, *"undo"*),
+  diagrams and tables can all be spoken. See [dictation](docs/dictation.md) for the apps and for using Lucid with one hand.
 - **Made for system design, open to other fields.** The note formats are plain data: a concept note, a system design, a
   comparison, an inference-maths note, a benchmark, and one more entry for anything else. [See them](docs/formats.md).
 - **You stay in charge.** Every change by the model is one undo step, any earlier change can be reverted on its own, and your
@@ -78,8 +99,7 @@ To dictate, use any app that pastes text: [Wispr Flow](https://wisprflow.ai),
 | [User guide](docs/guide.html) | the whole app on one page (also in the app: Help → Lucid Guide) |
 | [What Lucid does](docs/features.md) | typed blocks, three modes, diagrams and tables by voice, history, export and the PDF look |
 | [Note formats](docs/formats.md) | the five formats, with the PDF of a sample of each |
-| [Dictation](docs/dictation.md) | which apps to speak with, and a ten-minute check-list |
-| [Accessibility](docs/accessibility.md) | why Lucid exists, and using it by voice or with one hand |
+| [Dictation](docs/dictation.md) | which apps to speak with, using Lucid by voice or with one hand, and a ten-minute check-list |
 | [For AI agents](docs/mcp.md) | the MCP tools and how to connect Claude Code |
 | [Installing](docs/install.md) | steps for each system, checksums, troubleshooting |
 | [Architecture](docs/architecture.md) · [Evals](docs/evals.md) | how it fits together; how the model is scored |

docs/dictation.md

@@ -1,4 +1,4 @@
-# Dictating into Lucid
+# Dictating into Lucid, and using it by voice
 
 Lucid does no speech recognition. A dictation app turns your voice into text and pastes it, and Lucid's input box takes the
 paste. Any app that pastes (or types) into the focused window works; you do not need to pick one of these.
@@ -22,6 +22,33 @@ Two things to know:
 - Lucid's own command key is the **right ⌥ key** (right Alt on Windows and Linux). Choose another key for your dictation app's
   push-to-talk (VoiceNative's is right Shift) so they do not meet.
 
+## Using Lucid by voice, or with one hand
+
+Lucid began because for a while I couldn't type comfortably (see [the README](../README.md#why-i-made-it)), so this is what works by
+voice today:
+
+- **Notes without pressing Enter.** A pasted dictation is sent by itself about half a second after the last piece arrives.
+  Settings → **Dictation** makes the pause 1 s or 2 s (slower speech), or turns it off so the words wait in the box until you
+  press Enter and you can read them first.
+- **Commands by voice.** In Command mode, say what to change: *"cross out Memcached, we are choosing the local LRU"*, *"add a
+  CDN in front of the web server"*, *"undo"*. Say *"command mode"*, *"input mode"* or *"edit mode"* to change mode.
+- **One key for one command.** Hold the **right ⌥ key** (right Alt on Windows and Linux) and everything you dictate while it is
+  held is one command. It is a single key, which you can reach with one hand.
+- **Diagrams and tables without a mouse.** Say *"diagram mode"*, then the components, then the connections (*"client to
+  server"*), then fix them by number (*"rename 3 to Cache"*). *"Done"* inserts it. Tables work the same way.
+- **Pointing by number.** Every block has a number in the margin; say *"in block 3, add a row for cost"*.
+- **Everything can be taken back.** Every change by the model is one undo step, and the history lists each change, so a
+  misheard word never costs more than one *"undo"*.
+- **Shortcuts for one hand.** ⌘1 to ⌘5 switch the modes and open the builders, ⌘/ switches between Input and Command, Esc and ⌘L
+  go back to the input box, and ⌘+, ⌘− and ⌘0 zoom the page. The full list is in the [guide](guide.html#keys). Choose a
+  push-to-talk key for your dictation app that you can press with one hand, and not the right ⌥.
+
+What it does not do yet: it does not listen by itself (it needs a dictation app); speech mistakes (a name, a tool) are kept as
+heard, and Settings → **Words to expect** keeps the names you list as you wrote them; the model is usually right, not always, and
+Edit mode is for the rest. The buttons and fields have names a screen reader can read and the app is tested through them, but I
+have not used it with a screen reader for real work and it has not been audited: if you do, please
+[tell me what happens](https://github.com/triggeredcode/lucid/issues/new/choose).
+
 ## Try it with your voice (a check-list)
 
 The automated tests paste with ⌘V, which is what these apps do; only you can check it with your voice. About ten minutes.

docs/features.md

@@ -92,8 +92,7 @@ plain files in `~/Lucid` (one JSON file per page).
 
 A **note format** is the skeleton of a page. See [formats](formats.md).
 
-## Agents, dictation, accessibility
+## Agents and dictation
 
-- [Dictation](dictation.md): which apps to speak with, and a ten-minute check-list.
-- [Accessibility](accessibility.md): why Lucid exists, and how to use it by voice or with one hand.
+- [Dictation](dictation.md): which apps to speak with, how to use Lucid by voice or with one hand, and a ten-minute check-list.
 - [For AI agents](mcp.md): Lucid is an MCP server.

site/index.html

@@ -182,9 +182,9 @@ <h3>## The database</h3>
             <p class="kicker">Why it exists</p>
             <h2>Made so you can take notes without typing.</h2>
             <p class="section-lead">
-              Lucid began when its author broke their right hand and still wanted to take notes
-              while learning system design. A dictation app gives you a wall of text; Lucid gives
-              you the structure.
+              For a while I couldn't type comfortably, but I still wanted to keep learning system
+              design. A dictation app gives you a wall of text, so I built Lucid to give me the
+              structure.
             </p>
           </div>
           <div class="facts">
@@ -206,8 +206,8 @@ <h3>Speak the changes</h3>
               <h3>Always one step back</h3>
               <p>
                 Every change by the model is one undo step, so a misheard word costs one “undo”.
-                <a href="https://github.com/triggeredcode/lucid/blob/main/docs/accessibility.md"
-                  >Read more</a
+                <a href="https://github.com/triggeredcode/lucid/blob/main/README.md#why-i-made-it"
+                  >Read the story</a
                 >.
               </p>
             </div>