From 4cd87c40adcfd0e15d371268994e1aa60c952773 Mon Sep 17 00:00:00 2001 From: Omkar Tripathi <38633467+triggeredcode@users.noreply.github.com> Date: Mon, 12 Oct 2026 19:44:21 +0530 Subject: [PATCH] docs: why I made Lucid, in the first person; the accessibility page folded into dictation The README says in my own words, right after the intro and the pictures, why Lucid exists (for a while I couldn't type comfortably, I still wanted to learn, nothing did "speak, get structure"), what the first version is and is not (it does not listen by itself: Wispr Flow, OpenWhispr or VoiceNative), what was hardest, and where it might go, as ideas. The separate accessibility page is gone: what works by voice and with one hand is a section of docs/dictation.md, with the limits stated. The site's "why it exists" block is in the first person too. Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 2 +- README.md | 40 +++++++++++++++++++++++++++---------- docs/accessibility.md | 46 ------------------------------------------- docs/dictation.md | 29 ++++++++++++++++++++++++++- docs/features.md | 5 ++--- site/index.html | 10 +++++----- 6 files changed, 66 insertions(+), 66 deletions(-) delete mode 100644 docs/accessibility.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a5eb665..bf02f79 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index a603b4a..9c6fd30 100644 --- a/README.md +++ b/README.md @@ -31,14 +31,35 @@

-## 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 | diff --git a/docs/accessibility.md b/docs/accessibility.md deleted file mode 100644 index 2066077..0000000 --- a/docs/accessibility.md +++ /dev/null @@ -1,46 +0,0 @@ -# Lucid and accessibility - -## Why Lucid exists - -Lucid started because its author broke their right hand and still wanted to take notes while learning system design. Typing -with one hand is slow, and a dictation app on its own gives you a wall of text, when what you want is the structure: headings, -the options with the rejected ones crossed out, a table, a diagram. So Lucid takes what you say and builds the structured -document while you talk. - -It is not a medical or assistive device, and it has not been audited with screen readers or checked against accessibility -standards. What follows is what it does today, so you can judge whether it helps you. - -## Using it by voice - -Lucid does no speech recognition itself: a dictation app turns your voice into text and pastes it into Lucid's input box (see -[dictation](dictation.md) for free and open-source choices). From there: - -- **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"*. - -## Using it with one hand - -- The three modes and both builders have shortcuts (⌘1 to ⌘5, ⌘/ to switch between Input and Command), and Esc and ⌘L go back to - the input box. Zoom for the page is ⌘+, ⌘− and ⌘0. 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. Lucid's own command key is the right ⌥, - so pick another for dictation (VoiceNative's default, the right Shift, does not meet it). -- Light and dark themes, three typefaces for the page and a zoom for the page are in Settings and the View menu. - -## What it does not do yet - -- It does not listen to you itself; it needs a dictation app. -- Speech recognition mistakes (a name, a tool) are kept as heard. Settings → **Words to expect** lists names that should be kept - as written, and *Edit and send again* in the history puts your words back in the box to fix. -- The language model is usually right, not always. Edit mode is there for the rest. -- Buttons and fields have names that a screen reader can read and the app is tested through those names, but nobody has used it - with a screen reader for real work. If you do, please [say what happens](https://github.com/triggeredcode/lucid/issues/new/choose). diff --git a/docs/dictation.md b/docs/dictation.md index 10974a3..cac6d81 100644 --- a/docs/dictation.md +++ b/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. diff --git a/docs/features.md b/docs/features.md index 316216b..15f3934 100644 --- a/docs/features.md +++ b/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. diff --git a/site/index.html b/site/index.html index 231f876..54262ee 100644 --- a/site/index.html +++ b/site/index.html @@ -182,9 +182,9 @@

## The database

Why it exists

Made so you can take notes without typing.

- 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.

@@ -206,8 +206,8 @@

Speak the changes

Always one step back

Every change by the model is one undo step, so a misheard word costs one “undo”. - Read moreRead the story.