- 
-
- 
-
- 
-
'Options are Redis and Memcached…'"] --> model["A local model
(LM Studio)"] + model --> page + subgraph page["A Lucid page"] + direction TB + H["Heading
## High-level design"] --> SH["Subheading
### Data model"] + H --> D["Diagram
components and connections"] + SH --> L["List
options, rejected ones crossed out"] + SH --> T["Table
option against option"] + end + page --> out["PDF · Markdown
.lucid file · AI agents"] +``` + +## Typed blocks + +Everything on a page is a **typed block**. The model only chooses which block fits what you said and fills it in; Lucid draws +and typesets it, so the result looks the same every time. + +| Block | What it holds | How it is drawn | +|---|---|---| +| **Heading, subheading** | the outline: title, sections, sub-sections | numbered sections in the PDF | +| **List** | options, steps, trade-offs; bullets, numbered steps and checklists, each item on its own so one can be crossed out | bullets, struck-through when rejected | +| **Table** | a comparison: properties by options | a typeset table | +| **Diagram** | how parts connect: architecture, request flow, sequence, entities | drawn from components and connections, a database as a cylinder, a queue as a pipe | +| **Callout** | the key takeaway, a decision, a trade-off, a warning, an open question | a highlighted box | +| **Formula** | back-of-the-envelope maths (KV-cache size, FLOPs, bandwidth) | typeset LaTeX maths | +| **Chart** | numbers you dictated: bars or lines | a labelled chart | +| **Code** | an API request, a query, a shell command | a code listing | + +What stays true whatever you say: + +- **The model never writes LaTeX or drawing code.** It fills blocks; a fixed house style does the typography. +- **You stay in charge.** Every change by the model is exactly one undo step, any earlier change can be reverted on its own, and + your words are never lost: if the model cannot use them, they are kept as written. +- **One view.** The page, one input box under it, an optional history panel. It scales to a full-screen window. + +## Three modes, one box + +| Mode | Your words are | Switch | +|---|---|---| +| **Input** | notes, written into the page and structured | ⌘1 | +| **Command** | instructions about the page: "add a CDN in front of the web server", "undo" | ⌘2, or hold the right ⌥ key for one command | +| **Edit** | typing in the page itself | ⌘3 | + +⌘4 opens the diagram builder and ⌘5 the table builder. Each mode can also be chosen by voice ("command mode"). Changes that +would throw something away wait for a yes; when Lucid is unsure which thing you mean, it asks. + +## Diagrams and tables by voice + +A diagram of ten parts is hard to say in one breath, so there is a guided builder: say the **components**, then the +**connections** ("client to server"), then fix them **by number** ("rename 3 to Cache", "reverse 2"). A database is drawn as a +cylinder, a queue as a pipe, a CDN as a cloud, a load balancer as a hexagon. Big diagrams stay readable in the page and in the +PDF. Tables have a builder in the same spirit. + + + +## Say which block you mean + +Every block has a light number in the margin (B1, B2, …). Click one to see its parts, then say *"in block 3, add a row for +cost"* or *"cross out item 2 of block 6"*. The numbers can be hidden in Settings. + + + +## History you can trust + +The panel on the right lists what you said and every change to the page: by Lucid, by a builder, by an AI agent, or a revert. +**Show** scrolls to what a change touched. **Revert** takes back *one earlier* change, not just the last, and leaves later +changes to other blocks alone. + +## Export, and how the PDF looks + +- **PDF**, typeset with Tectonic in a fixed house style (numbered sections, real tables and figures, formulas). Settings → + **PDF look** changes the paper (A4 or Letter), the text size, the typeface, the margins, an accent colour, whether headings + are numbered and whether the date shows. +- **Markdown** (diagrams as Mermaid blocks). +- **A `.lucid` file**, the whole note with its history, to back up, move to another computer or share. + + + +Light and dark themes, three typefaces for the page on screen, and a zoom for the page (⌘+, ⌘−, ⌘0) are in the app. Pages are +plain files in `~/Lucid` (one JSON file per page). + +## Note formats + +A **note format** is the skeleton of a page. See [formats](formats.md). + +## Agents, dictation, accessibility + +- [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. +- [For AI agents](mcp.md): Lucid is an MCP server. diff --git a/docs/formats.md b/docs/formats.md new file mode 100644 index 0000000..7c0a1b6 --- /dev/null +++ b/docs/formats.md @@ -0,0 +1,44 @@ +# Note formats + +A **note format** is the skeleton of a page: its sections, a hint for each saying what belongs there, and which blocks suit it. +Start a page from one with **New from a format…**; Lucid suggests one from what you say, and you always choose. A page of a +format starts as its section headings, and what you dictate goes under the right one. Sections left empty are not printed. + +| Format | For | Sections | +|---|---|---| +| **Concept note** | one computer-science or system-design idea | Definition · Intuition · How it works · Example · Pitfalls and gotchas · Related concepts | +| **System design** | designing a system end to end | Requirements · Capacity estimates · API · High-level design · Data model · Deep dives · Trade-offs and decisions · Open questions | +| **Comparison** | choosing between technologies | Context · Options · Comparison · Pros and cons · Decision | +| **Inference engineering** | KV cache, FLOPs, bandwidth, batching | Intuition · The math · Numbers to remember · Hardware implications · Pitfalls | +| **Benchmark** | recording an experiment | Goal and hypothesis · Setup · Method · Results · Observations · Next experiments | + +## What the PDFs look like + +Each picture is the PDF of a sample note, made with the real app ([how](format-samples/README.md); the numbers in them are made up). + +**Concept note** + + + +**System design** + + + +**Comparison** + + + +**Inference engineering** + + + +**Benchmark** + + + +## Open to other fields + +The formats lean towards engineering because that is what Lucid was made for, but nothing else in Lucid does. A format is a +small data entry in [`packages/kit/src/formats/index.ts`](../packages/kit/src/formats/index.ts): an id, a description, keywords +for the suggestion, the sections and the blocks that suit them. A lab notebook, a reading log or a study plan is one more +entry. New block types (one folder each) work the same way. See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-note-format). diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..58da2d8 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,92 @@ +# Installing Lucid + +Lucid runs on **macOS** (Apple Silicon, macOS 13 or newer), **Windows** (Windows 10 or newer, 64-bit) and **Linux** (64-bit). +The [website](https://triggeredcode.github.io/lucid/#download) offers the right download for your computer; all of them are on +the [latest release](https://github.com/triggeredcode/lucid/releases/latest). + +| System | Download | Notes | +|---|---|---| +| **macOS** | `Lucid-
Free and open source · local-first · macOS, Windows, Linux
-A structured document, built while you think.
+Voice to structured notes and diagrams.
- Say or type your thoughts. Lucid arranges them as headings, lists, tables and diagrams, - and typesets them. The language model runs on your own computer, so nothing leaves it. + Talk, and Lucid builds the headings, lists, tables and diagrams while you think, then + typesets a PDF. Made to work hands-free or one-handed. The language model runs on your + own computer, so nothing leaves it.
+
+
+
+
+ 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. +
+
+
+
+
+ Speak the notes
++ Dictate with any app that pastes text. The notes are sent by themselves a moment + after you stop, so no Enter is needed. +
+
+
+ Speak the changes
++ “Cross out Memcached.” “Add a CDN in front of the web server.” “Undo.” Hold one key + and everything you say is a command. Even diagrams can be said. +
+
+
+ Always one step back
++ Every change by the model is one undo step, so a misheard word costs one “undo”. + Read more. +
+What a page is made of
@@ -305,7 +345,7 @@Code
-How it works
@@ -455,7 +495,7 @@Typeset, not screenshotted.
-Made for system design, open to other fields
@@ -544,7 +584,7 @@Your own
-Download
@@ -840,7 +880,7 @@Lucid for Linux
-
@@ -898,11 +938,11 @@
- A toolbox, not just an app.
Privacy
-Your notes stay on your Mac.
+Your notes stay on your computer.
@@ -928,7 +968,7 @@
+
Plain files
-Questions