Skip to content

Commit 52bbbca

Browse files
nyblnetnyblnet
committed
docs: reframe bento/vault around the AI broker
Supersedes the 2026-07-25 vault entry. Two files: a DECISIONS.md entry and a rewrite of docs/vault-design.md. The reframe came from subtraction. Of the five promises in the old entry, four were met or taken while it sat unbuilt — mobile reach by tray plus any existing File Provider, sharing by the collab relay, per-device version history by autosave.ts, and plain file sync was never ours. Search alone survived, and it is measured rather than assumed. Control test in an indexed folder: a plain HTML file with a phrase in <body> is found by Spotlight; the same phrase inside a <script> is not; a real deck is not found, though grep finds it instantly. Bento libraries are invisible to OS search. Before any indexer is built, the cheap avenue gets tested: text in <noscript> IS indexed, and every save already writes a page-one render there. What makes vault necessary is the AI broker. A travelling document can never carry a model credential, and under tray localStorage is per-DOCUMENT — the origin is SHA256(path) truncated, verified at EditorViewController.swift:55-58. The only place a credential can live once and serve a library is a server the user runs. Two claims that reached the draft were wrong and are corrected in the doc rather than repeated. Ollama does not blanket-refuse file:// — its default allow-list includes file://* (envconfig/config.go:100-106); the real issue is that browsers send Origin: null and gin-contrib/cors matches by exact string or regex (config.go:128-140), so null won't match file://*. That one is marked reasoned, not measured. And LiteLLM's virtual keys, budgets and spend attribution are stock behaviour, not an add-on. Cut as deferred architecture: backup and version history (autosave.ts already covers it, and the audience runs restic and git), SSO beyond key distribution and forward revocation, and — with the org profile as destination rather than first build — NAT traversal, hole-punching, the dead-drop and the portable relay twin, all of which existed to serve a laptop asleep behind a home NAT. New invariant: AI is additive, never load-bearing. Every app stays fully functional with no vault and no model, or PLATFORM.md §1 is gone.
1 parent b61580f commit 52bbbca

2 files changed

Lines changed: 222 additions & 217 deletions

File tree

‎docs/DECISIONS.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,69 @@ Decision. Why. Pointers.
1414

1515
---
1616

17+
## 2026-07-27 — bento/vault is the ORG service point, and the AI broker is what forces it
18+
19+
**Supersedes the 2026-07-25 "personal server" entry.** Vault is not a personal
20+
document library. It is the **service point for a group of people and their
21+
documents**, self-hosted on hardware that group owns.
22+
23+
The reframe came from subtraction. Of the five promises in the old entry, four
24+
were met or taken while it sat unbuilt: mobile reach went to `bento/tray` plus
25+
any existing File Provider (iCloud Drive, Dropbox), sharing went to the collab
26+
relay (the file IS the capability), per-device version history went to
27+
`kernel/src/autosave.ts`, and plain file sync was never ours. What survived
28+
personally was **search alone** — measured, not assumed: Spotlight indexes
29+
rendered HTML text, so a deck whose content lives in the `#bento-doc` script
30+
block is invisible to it (a control file with the same words in `<body>` is
31+
found; the deck is not). One real problem does not need a personal server.
32+
33+
**The AI broker is the pillar that makes vault necessary rather than nice.** A
34+
self-contained document travels, so it can never carry a model credential — that
35+
is emailing your API key to everyone you share the deck with. `localStorage` is
36+
per-device, and under tray it is per-DOCUMENT (the origin is
37+
`bento-tray://<sha256 of path>`, `EditorViewController.swift`), so it degenerates
38+
into configuring a key per deck. The only place a credential can live once and
39+
serve a whole library is a server the group runs. **In-app AI is architecturally
40+
impossible without something vault-shaped**, and the same index serves both
41+
search and retrieval. Points a local model (Ollama on the same box) at the
42+
library without anything leaving the network, which is the existing README claim
43+
made real.
44+
45+
**SSO gates distribution, never the file.** Once someone holds the bytes they
46+
open them forever, offline, with no server — that is the product, not a bug. SSO
47+
can gate access to the vault and the distribution of decryption keys (the
48+
`bento/enc` envelope and the owner→invite→member chain already exist for this).
49+
Revocation is therefore FORWARD-ONLY: a revoked member keeps what they already
50+
downloaded, exactly as `collab-design.md` already documents for devices. Say this
51+
before an enterprise security review discovers it.
52+
53+
**The org profile deletes most of the hard design.** NAT traversal,
54+
hole-punching, WebRTC, the dead-drop and the portable relay twin all exist to
55+
serve one case: a personal laptop asleep behind a home NAT. A company vault is a
56+
box on a network with a hostname and a certificate, reached directly. So
57+
`relay-design.md` steps 2–5 and `vault-design.md` steps 2–4 are NOT v1.
58+
59+
Corollary worth stating plainly: the org vault **is** a custody service, and that
60+
is correct — central custody is the point of centralising. The personal vault
61+
explicitly was not. Those were two products wearing one name; we are building the
62+
org one.
63+
64+
**New invariant — AI is additive, never load-bearing.** Every app stays fully
65+
functional with no vault and no model, the same rule as "vault is optional". If
66+
an AI feature ever becomes required to edit, `PLATFORM.md` §1 is gone.
67+
68+
**Sequencing: the org deployment is the DESTINATION, not the first build.**
69+
Architecturally this costs nothing — a single-user vault IS the org vault with
70+
one user: same index, same key chain, same broker. Build that, design toward
71+
multi-user, promise neither.
72+
73+
**Licence:** the runtime stays MIT (`THIRD_PARTY_NOTICES.md` is embedded in every
74+
saved file, so copyleft on the shell would attach to every document a user
75+
emails). Vault is a separate repo with its licence chosen at commit #1. Never
76+
relicense slides.
77+
78+
Design details in `docs/vault-design.md`.
79+
1780
## 2026-07-26 — File-manager thumbnails: a `<noscript>` render of page one, written at save time
1881

1982
**Decided:** 2026-07-26. Kernel zone (`kernel/src/save.ts`), so it binds every

0 commit comments

Comments
 (0)