A personal computer you actually own.

Overview

A document-native computing environment

There are no drawers in Lucia OS. Everything you keep is a Prism document: a small, typed, time-carrying unit. Documents are built from one another, and your own threads lead you back to them.

Two programs make up the running system, and the split is the whole security story. The terminal is the trusted environment: it holds your keys, does all plaintext work, and renders your world. The realm is a blind relay: an always-on home for your documents that stores only ciphertext it cannot read, routes what you send, and hands it back when you sync.

Storage and communication use one format, Prism: .prisma in readable ASCII, .prism in binary. The same format is the wire protocol, the storage journal, and the app manifest. One format, everywhere.

The document

Elements, paths, properties, values

Every document in Lucia has the same shape, and it is worth stating exactly once, precisely:

A Document is a set of Elements indexed by Path, each carrying typed Propertys; a Property is a Value, optionally varying over time.

An element's Path is its identity inside the document. A property is a typed slot on an element; a value can be a scalar, an array, or a curve that varies over time: a document remembers its own history natively, not as a bolted-on log.

Elements connect to one another through typed slots: a connection is the capability to send along a wire, and the slot's declared type is the contract. That is how a document composes from others: the scholar's library, not a pile of copies.

Two-layer namespace

Where a document lives, and what is inside it

These are two different questions, so Lucia gives them two different namespaces and one explicit boundary, the #. Conflating them is what breaks the moment real host files enter the picture.

A Ref joins the layers with the explicit boundary, so nothing is ever inferred from disk:

/home/dy/notes                              a document (locator)
/home/dy/notes#/body/[3]                    an element inside it
/volumes/home/scene.prisma#/world/sphere.radius   a slot inside a host file

The invariant that removes all ambiguity: a locator never contains a slot; a content path never contains a filename; the layer boundary is always the explicit #.

The layer stack

One foundation everything stands on

Libraries are separate packages, stacked in dependency order. Products link only the OS facade; the siblings are linked by the OS and by each other. The foundation stays portable and crypto-free, because it runs inside the terminal where it is already safe.

Why core is crypto-free: it operates on documents whose values are opaque strings: diff, merge, and conflicts behave identically on sealed and cleartext values. So the foundation stays pure and trivially auditable; the only place a signature meets the data is storage's acceptance rule, one layer up.

Trust model

Only trust the terminal

A user trusts their terminal and nothing else. The realm, the network, and every intermediary are assumed hostile and must be irrelevant to the user's security. This is not a promise about the node's good behavior. It is a property of how the thing is made.

Because keys and authorship live only in the terminal, remoting needs no new protocol. A mirror carries sealed frames through the realm's blind relay to terminal.luciaos.com: the web seat is eyes and hands, every verb executes on your own machine, and the relay reads nothing. The mirror credential is forward-secret: each session rides a fresh key.

Storage

A signed journal, folded into state

The realm is a forest of documents. Its state is the fold of a signed EventLog: one totally ordered log of commits, where a commit is a transaction of ops: revise a document, make a folder, remove, or move, each naming one locator.

• The acceptance rule admits a commit only on the author's own signature plus a write grant covering every op's locator (or the exact canonical registration op-set). It runs on every terminal's fold, so it is the terminals' rule, so a hostile node cannot slip a commit past it.
• Sealing is per document, under labels bound to (locator, inner path), so a document cannot be relocated to lie about itself and resealing on share rotates one envelope.
• Grants, history, and merge are per document. Three-way merge, conflicts(), and compact() live in core; a rebase names every divergent slot rather than silently losing an edit. at <version> time-travels the whole realm.

Services

Namespace providers and an API bus

A service is a named capability the OS hosts, deployed into /sys/services and reached over the one Prism request→response protocol. It fills one or both roles:

• A namespace provider backs a subtree of the document space. Reads and writes under its mount point route to the service. Host volumes are the first one: /volumes/home binds a real directory on your machine as a live view: presented as documents, never journaled or sealed, confined to /volumes and to the trusted terminal.
• An API answers named verbs: service call <name> <verb> → a response document, without owning any part of the namespace.

This is one seam with many bottoms: the host filesystem today, a database or a remote realm tomorrow, with no change above the provider interface. A guest reaches a provider-backed document only through a grant, exactly as it reaches a journaled one.

Command levels

Three levels, one job each

The terminal speaks three levels of command. Each has one vocabulary and one trust posture.

A seat is where you type; the home machine is where the keys and the plaintext live. The native terminal, the web seat, and a guesting terminal are all the same seat over the same sealed frames; a remote seat is eyes and hands only.

The build agent

A coding agent that lives in the document world

Lucia build is a coding agent whose working directory is a Locator, not a filesystem path. Its file tools speak Session refs, so the same tools read realm documents and volume files through one door: cd /volumes/home, launch build, and it reads and writes your real files, grant-checked, from inside the OS abstraction.

Its tool calls are gated by a permission mode, and its reach is exactly the volumes the seat has mounted. Because a build session is just another transcript, it mirrors to the web through the same blind relay as any other: you can watch and drive a running build from the road, and the relay still reads nothing.