The shell is the
address bar.

§Six tenets

1. An app is identity, not a URL.

   Ports are plumbing, and plumbing that surfaces is a defect. The premise cuts deeper than convenience: an app’s origin is <id>.reef.localhost:<port>, and the browser keys storage to that origin, so identity is also where the user’s data lives. The gateway port is pinned and persisted for exactly this reason. A port that drifts is not a port conflict; it is silent data loss.

2. A folder is the whole format.

   The manifest is optional because “I don’t have to think about it” is the entire pitch: index.html means static, a dev script means server, and reef.json exists only to override. The constraint that keeps this honest: an app that works in Local Reef still runs standalone outside it. Nothing is locked into the shell.

3. The obvious design is a hypothesis.

   app://notes/ was the original addressing scheme, and it does not work: Chromium custom schemes cannot carry a WebSocket. The cookie handshake was the original auth, and the cookie is stored and then never sent back. listen(0) was the original port strategy, and it stranded a real user’s data. Each obvious approach was tried, each died on contact, and each is written down where it fell, so the next person does not pay twice.

4. Honesty is a method, not a tone.

   TODO.md leads with unverified claims, because a claim that could invalidate a decision matters more than a feature gap. The security model states what it does not cover: the threat model is “apps I or my agent wrote,” not hostile third-party code, and the docs say so rather than implying a sandbox that has not been earned.

5. Assert the effect, not the mechanism.

   A test that checks the state your code sets will pass while the user watches the feature fail. Minimize shipped broken with a green test asserting el.hidden === true while display: flex kept the window fully on screen. The suites here measure bounding boxes, HTTP statuses and pixels, and the desktop photographs itself so a claim about the UI can be checked by looking.

6. Wrong costs more than slow.

   Three agents edit real files: generation, fixing, and the edit chat. All three run the strongest model available, because a wrong edit to a folder that is the user’s real project checkout is worse than a slow one. Generation owns the folder it created and deletes it on failure; a fix operates on a folder that is already the user’s, and a fix must never delete anything.