# Why

The reason for everything else on this site: the problem, who it's for,
what it won't do, what isn't done, what we haven't solved, and what else
you could use. Each part of [Features](/features) serves a story here, and
a story is shown true only by someone doing it, never by a test.

## The problem

Ask where your notes live, who can read them and what happens if the company
holding them changes its mind. The answer is usually one you didn't choose.
Reaching your own laptop from somewhere else means trusting whoever is in
between; an agent given your password gets everything; and changing a page
or an app means waiting on a developer.

youros makes it yours to choose, for each thing you own:

- **Where it lives.** This laptop, that server, a phone, a cloud machine you
  rent. More than one, kept in sync, and movable later. A server of ours is
  just another machine you trust some amount.
- **Who may use it.** A person, a device, an agent, a service, each a key
  granted exactly what it needs, for as long as it needs it, and revocable
  from any of your devices.
- **How it is sealed.** Plaintext where you want speed and search,
  ciphertext everywhere it only passes through.
- **What you can change.** Notes, pages and apps are documents anyone you
  let in edits live, and an edit is data that can't run.

## Who it's for

Each story is someone youros is for, what they do with it, and how we'd
know it worked for them. A line off the right margin goes down to each part
of Features that serves it.

### Your machines and files

#### Alex reaches the laptop at home from a café `story/reach-anywhere`
Alex opens youros in a browser, pastes one line into the laptop at home,
and is in its terminal. The café wifi drops, the phone's hotspot takes
over, and the shell carries on.
Worked if: someone new reaches their own machine's terminal in under a
minute, with no sign-up, and a dropped network doesn't lose their place.
Seen working: not yet.

#### Alex loses a phone, and it opens nothing `story/lost-device`
The phone is gone with youros on it. From the laptop, Alex revokes it; the
server with Alex's notes refuses it the next time it calls, even if that
server was offline when Alex did it, and no other device needs adding
again.
Worked if: the lost device is refused everywhere it tries, and nothing
else had to be set up again.
Seen working: not yet.

#### Jo's notes and code are on every device, and still files `story/files-everywhere`
Jo edits notes on the phone on a train and code on the laptop at home; both
merge when they meet. The files stay files in folders, git still works,
the theme follows Jo and each screen keeps its own zoom.
Worked if: Jo never loses an edit or a commit, and never converts a file to
use it.
Seen working: not yet.

### Pages and apps

#### Sam changes the café's page without waiting on anyone `story/owner-edits`
Sam runs a café whose site a developer built. On a Monday Sam changes the
opening hours, moves the menu above the gallery and swaps a photo, on the
page itself, while the booking form keeps taking bookings.
Worked if: someone who has never seen the editor makes those three
changes in their first ten minutes, without help, and nothing on the page
breaks.
Seen working: not yet.

#### A team gets a launch page ready together `story/team-edits`
Three people work on one page the week before a launch: one rewrites the
words, one changes the colours, one adds sections on a train with no
signal. They comment on the page instead of sending screenshots, and each
undoes their own mistakes.
Worked if: at the end nobody has lost work, and nobody has had to ask
who changed something.
Seen working: not yet.

#### Priya adds what only code can do, and stops being asked for words `story/developer-ships`
Priya is the developer. They build a booking widget in the app's source,
and after a rebuild it's in everyone's library. They read the page's
changes as text in git, like any other change.
Worked if: requests to change words and colours stop reaching them, and
they review a page's changes in the pull request they already use.
Seen working: not yet.

#### Sam lets an AI help, and decides what it sees `story/agent-helps`
Sam selects the menu section and asks for it to be friendlier; the
suggestion arrives beside the page, and Sam takes two changes of three.
Later Sam lets an agent into one folder on the laptop until Friday. Each
sees what Sam gave it and nothing else, and what it changes waits for Sam.
Worked if: Sam keeps the suggestions they want, and can say what each AI
saw, what it changed and until when it could.
Seen working: not yet.

### Anyone deciding to trust it

#### Someone checks every claim before trusting it `story/checker`
An engineer deciding whether to use youros, or to work on it, wants to
know whether it really does what this site says: which test shows each
promise, whether it passed, which code keeps it, and how small the part
they have to trust is.
Worked if: they answer "does it really do this?" from the site alone,
without asking us.
Seen working: not yet.

## What it won't do

- **Un-read.** What someone already read, they keep. Revoking decides what
  happens next.
- **Search on our servers.** We can't index what we can't read. Search runs
  on your machines.
- **Make a browser tab as safe as a laptop.** Any script on a page can read
  that page's key, so a tab is your least trusted device and is granted the
  least.
- **Let an edit run code.** Behaviour comes only from source, through a
  build; an edit is data.
- **Replace your developer.** What only code can do stays code, and reaches
  the library through the developer.

## Not yet

- **Seen working.** Every story above is a guess until someone does it;
  nobody has yet.
- **Your browser as a device, and the first minute.** The core, sessions,
  accounts, the relay and a Linux machine's terminal and files are built
  and tested; the browser node and the end-to-end test that fails if a
  relay sees anything you typed are next.
- **Editing between devices.** The editor's promises hold between tabs of
  one browser. Between devices waits for docs to travel over the relay;
  until then a page moves as a saved file.
- **Later:** an agent door (MCP), remote browsing, your own domain, and
  machines as small as an ESP32.

What could still go wrong is under each part of How it works, such as the
editor's [risks](/how-it-works/shell#risks).

## Open problems

What we want solved and haven't: what a solution would have to do, and
where we'd start.

### Proving it's you without giving the secret away

Alex is at a borrowed laptop, with no phone and no key: only what Alex
knows. Whatever is typed or clicked there may be recorded, and a password
typed once on a recorded keyboard is a password given away. Can you prove
you know a secret so that a recording of the proof doesn't let anyone
prove it again?

A solution would:

- **Survive being watched.** A recording of one login, or of many, doesn't
  let anyone log in later.
- **Need nothing carried**, and be learnable by anyone, in a minute a login.
- **Be checked by your own machine**, not by us.

It can't make that laptop safe while you use it; whatever it shows you, it
sees. So a login there gets little, briefly, and your other devices hear
about it. Adding a device never happens this way: it takes a passkey or a
device you already trust.

Where we'd start:

- **Questions about what you did lately.** Your machine knows what you
  worked on, so it asks an open question ("what were you fixing on Thursday
  evening?") and checks the answer against what happened. A recorded answer
  is stale by next week, and there's nothing to learn. Open: people close
  to you know the answers too, and the checker must compare facts, not be
  talked into a yes.
- **Sums done in your head** (Blocki, Blum, Datta and Vempala, *Towards
  Human Computable Passwords*). You learn a secret list of pictures and
  digits; a login shows rows of pictures, and you answer each row with a
  digit from a few lookups and two additions. Two pictures in the row pick
  which other picture counts, using your secret, so a recording gives no
  equations to solve: hundreds of recorded rows aren't enough. Open:
  learning a hundred pairs takes days, and one slip fails a row.
- **Rows answered wrong on purpose.** A secret rule, such as "any row with
  this picture, type any digit", makes some recorded answers garbage, and a
  watcher can't tell which. Our idea, untested.
- **Access that grows with each check.** An emailed code and a PIN let you
  read for an hour; answering more lets you do more; each step is announced.

## Compare

You may already use something that does part of this. So far this compares
the editor with page builders; tools for reaching your machines and
syncing files aren't written up yet. Find your tool, or what you need; each
tool says what it is better at, and when to use it instead. Built from one
file (`compare.json`), every row dated and marked *searched* (checked
against a source that day) or *from memory* (not yet re-checked).

<CompareSummary />

### By tool

<CompareTools />

### By need

<CompareNeeds />

### What we found

No tool we found is open source, keeps edits as data, merges concurrent
moves safely and keeps the page off any server, on a real app. The
nearest are **Builder.io**, shipped and closest in feel, where edits become
code on a hosted service, and **Puck**, whose model of data plus your own
components is ours, for one editor at a time. Not finding a tool is not
proof there isn't one: tell us.