Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Say how this project is developed, and mark the unreleased apps as unreleased (#391)

nyblnet1b6002f19bcd
diff --git a/.gitignore b/.gitignore
index 406e8a4b..50a89549 100644
--- a/.gitignore
+++ b/.gitignore
@@ -73,3 +73,8 @@ home/android/*/build/
# purpose: ~/.zshrc picks the personal gh account by directory, and /tmp gets
# reaped — seven worktrees were lost from it in one day.
.worktrees/
+
+# Local agent/harness config. Populated by tooling outside this repo; the repo
+# itself ships none, so anything here is a working copy, not a shared contract.
+.claude/agents
+.claude/commands/team
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index af0fae2a..65e229b4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,6 +88,37 @@ If you touch the boot, save, or build path, keep these invariants intact — the
release process gates on them. The details are in
[docs/architecture.md](docs/architecture.md).
+## How this project is developed
+
+Bento has a small maintainer-led design process, and it's worth saying plainly
+what that means for anyone reading along.
+
+**What is public:** the source, the format, and the reasoning behind shipped
+behaviour. [docs/DECISIONS.md](docs/DECISIONS.md) is an append-only log of why
+things are the way they are — dated, with the arguments intact — and
+[docs/PLATFORM.md](docs/PLATFORM.md) states the invariants that follow from
+them. If you want to know why a rule exists before you argue with it, that is
+where to look, and those two files are the ones we most want to be worth
+reading.
+
+**What is not:** plans for unreleased work. Design direction for things that
+have not shipped isn't published, there is no public roadmap beyond the one
+paragraph in the README, and there are no dates. That is a deliberate trade —
+publishing analysis of a product that doesn't exist yet commits a one-person
+project to conclusions it hasn't earned, and the reasoning gets published once
+it constrains real code, not before.
+
+**Unreleased apps live in this repo anyway.** `type/` and `dash/` are in the
+tree because the apps share one kernel and one build; each has a README saying
+what state it is in. Source being visible is not the same as a product being
+released: nothing unreleased is published, signed, or reachable through the
+update channel, and rough edges there are expected rather than reportable.
+
+**The most useful contributions**, given all that, are bug reports against
+shipped behaviour, fixes with a test or a reproduction, documentation
+corrections, and templates. For anything larger, the next section is the
+important one.
+
## Before you build something substantial
**Check what's already in flight, and claim it.** Bento moves fast and several
diff --git a/dash/README.md b/dash/README.md
new file mode 100644
index 00000000..c29048db
--- /dev/null
+++ b/dash/README.md
@@ -0,0 +1,39 @@
+# bento/dash
+
+A spreadsheet where **one HTML file is the whole workbook**: the grid, the
+formulas, the charts built from them, the viewer, and the editor.
+
+## Status: in development. Not released.
+
+**This directory is a construction site, not a product.** `bento/dash` has no
+release and nothing published on [bento.page](https://bento.page). A file you
+build from this source is an unsigned local build, and the document format is
+still settling — formula coverage, pivots and conditional formatting are all
+incomplete by design at this stage.
+
+The shell does check `bento.page/releases/dash/` for updates, and there is
+nothing there today. That is worth knowing in both directions: no local build
+updates itself now, and when dash does ship, a file built today would offer the
+real release to itself — the signature and version checks are the same ones
+every shipped bento file uses.
+
+Its entry in the release registry (`scripts/apps.mjs`) exists so the channel is
+ready when it ships; it does not mean it has shipped. No release date. If you
+want the shipped products, they are `slides/` and `spaces/`.
+
+## Run it
+
+```sh
+cd dash
+npm install
+npm run dev
+npm run build:single # a local build; not a release
+```
+
+## Working here
+
+`dash/` is this app's ownership zone. Read `AGENTS.md`, `docs/PLATFORM.md` and
+`docs/PARALLEL-WORK.md` first; `kernel/` is a separate, serialized zone, and
+`docs/dash-collab.md` carries this app's sync design. Correctness here is
+arithmetic, not rendering: a formula or pivot change needs cases, not a
+screenshot.
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 2a33b804..e069732f 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -187,7 +187,7 @@ you sent it to that you had once saved something.
In `kernel/`, not `slides/`: Spaces, Dash and Type have the identical problem
and would each grow their own copy. The kernel owns the remembering and the
policy; the words and the markup are the app's. Spec (gitignored):
-`working/handover-web-demo-return-gate.md`, from the `tray-views` session.
+`working/team/handoffs/handover-web-demo-return-gate.md`, from the `tray-views` session.
NOT done here, and worth weighing first: making **Download** the primary action
on the landing page (it is currently `btn primary` on "Try it in your browser")
@@ -371,7 +371,7 @@ been silently dropping four marks) into marks.ts, over the same run list.
**Decision.** A `table` block: `rows` (row-major, each cell INLINE HTML), `cols`
(fractional column weights), `colAlign` (per COLUMN), `header` (absent = TRUE).
No formulas, no recalculation, no cross-document references — the line from
-`working/spaces-design.md` §2.6. The database case is unaffected: it already
+`working/design/spaces-design.md` §2.6. The database case is unaffected: it already
shipped as the tracker (`doc.fields` + `prop` + `view`), and this is not a
second one.
@@ -1214,7 +1214,7 @@ failing to re-merge after a render split them (423/2,000).
**Pointers.** `type/src/inline.ts` (the argument is in the file header),
`type/src/model.ts` (tagged `parseDoc`, following the spaces load contract:
an unreadable file must never become an empty one), `scripts/test-type-model.ts`.
-Design + the measured spike behind it: `working/type-design.md` and
+Design + the measured spike behind it: `working/design/type-design.md` and
`working/type-spike/RESULTS.md` (gitignored) — Path A, continuous pagination,
Knuth–Plass viable live.
@@ -2421,13 +2421,13 @@ deletion set included `slides/index.html`, the gallery, `agents.md`,
Rig: `scripts/test-publish-gate.mjs`; shared logic `scripts/site-inventory.mjs`.
This is the first half of the multi-app release work
-(`working/spaces-design.md` §6.1); per-app assembly — build one app, restore
+(`working/design/spaces-design.md` §6.1); per-app assembly — build one app, restore
the others byte-identically from the published tree — is the second, and
spaces cannot be released until both exist.
## 2026-08-02 — bento/home runs documents in a per-document origin, or not at all
-`bento/home` is a launcher (`home/`, `working/home-design.md`): it holds no
+`bento/home` is a launcher (`home/`, `working/design/home-design.md`): it holds no
document content, only `FileSystemFileHandle`s in IndexedDB, so a deck you were
working on reopens with write access after one permission click. That part is
measured and built. **How a document is actually OPENED is the hard part, and
@@ -2484,7 +2484,7 @@ cadence and the deploy-order care that implies (`docs/PLATFORM.md` §5).
**To confirm before building** (none of it testable in an automated browser —
permission-gated APIs report `denied` there without prompting,
-`working/home-design.md` §3.2, a trap that already produced two wrong
+`working/design/home-design.md` §3.2, a trap that already produced two wrong
conclusions):
1. Does a `FileSystemFileHandle` survive a cross-origin `postMessage` and stay
@@ -2736,7 +2736,7 @@ old shared-name code (7/8), which is the property that makes it a gate.
## 2026-08-02 — A release seeds from what is published, and builds one app
-Second half of the multi-app release work (`working/spaces-design.md` §6.1).
+Second half of the multi-app release work (`working/design/spaces-design.md` §6.1).
The first half made a destructive publish impossible; this one makes a
non-destructive one possible.
diff --git a/home/webext/README.md b/home/webext/README.md
index e5218ca3..cf7dd56e 100644
--- a/home/webext/README.md
+++ b/home/webext/README.md
@@ -355,7 +355,7 @@ asks where to put the file.
Everything below needs the extension actually loaded — none of it is testable
from a page, and permission-gated behaviour reports `denied` under automation
-(`working/home-design.md` §3.2, a trap that already produced two wrong
+(`working/design/home-design.md` §3.2, a trap that already produced two wrong
conclusions).
~~1. Can an MV3 service worker `createWritable()` on a stored directory
diff --git a/scripts/apps.mjs b/scripts/apps.mjs
index d8a20ca5..c1538d7b 100644
--- a/scripts/apps.mjs
+++ b/scripts/apps.mjs
@@ -41,11 +41,19 @@ export const APPS = {
ownsSiteContent: false,
// No pack catalog yet: build-i18n/sign-packs are slides-hardcoded and the
// channel does not exist. Deferring packs is fine; deferring the CHANNEL
- // would not be (working/spaces-design.md §6.5).
+ // would not be (working/design/spaces-design.md §6.5).
packs: false,
changelog: 'spaces/CHANGELOG.md',
agents: 'docs/spaces-agents.md',
},
+ /** REGISTERED BEFORE IT SHIPS, deliberately — dash has no release and nothing
+ * published at /releases/dash/. Being here is not a claim that it shipped:
+ * `release.mjs` defaults to `--app slides`, so cutting a dash release takes
+ * an explicit `--app dash`. What the entry buys is that
+ * `test-release-apps.mjs` proves the wiring — manifest URL, changelog shape,
+ * unique appId — on every CI run instead of at release time, which is this
+ * registry's entire reason for existing. Its status for readers is in
+ * `dash/README.md`. */
dash: {
appId: 'bento-dash',
dir: 'dash',
diff --git a/scripts/build-guestbook.mjs b/scripts/build-guestbook.mjs
index 8d1319e2..730edf48 100644
--- a/scripts/build-guestbook.mjs
+++ b/scripts/build-guestbook.mjs
@@ -3,7 +3,7 @@
// Copyright (c) 2026 The Bento authors
// U2: the public guestbook deck — one live-collab file anyone can open and
// sign. Minting fresh credentials IS the reset mechanism ("epochs, not
-// moderation" — see working/guestbook-design.md). The deck definition lives
+// moderation" — see working/design/guestbook-design.md). The deck definition lives
// in scripts/guestbook-deck.mjs, shared with the Cloudflare daemon
// (server/guestbook-daemon/) which is the SUSTAINABLE home of rolls and
// snapshots — this local builder remains for seeding and as a fallback.
diff --git a/scripts/probe-origins.mjs b/scripts/probe-origins.mjs
index 7e258023..fc37cef7 100644
--- a/scripts/probe-origins.mjs
+++ b/scripts/probe-origins.mjs
@@ -19,7 +19,7 @@
// without ever prompting, because a driven browser must not be able to hand out
// filesystem write access. So an agent testing this gets `denied` no matter
// what the truth is. That trap already produced two wrong conclusions during
-// this design (working/home-design.md §3.2). Only a human in a real browser
+// this design (working/design/home-design.md §3.2). Only a human in a real browser
// window can answer it.
import { createServer } from 'node:http'
diff --git a/scripts/test-spaces-model.ts b/scripts/test-spaces-model.ts
index 77baba2d..d40ea505 100644
--- a/scripts/test-spaces-model.ts
+++ b/scripts/test-spaces-model.ts
@@ -888,7 +888,7 @@ for (const [label, input, err] of [
}
// ---- the table block -------------------------------------------------------
-// A table is CONTENT (working/spaces-design.md §2.6) — no formulas, nothing
+// A table is CONTENT (working/design/spaces-design.md §2.6) — no formulas, nothing
// that recalculates, and not the database case, which already shipped as the
// tracker. What is pinned here is the part that is PERMANENT: the shape of the
// model, the `html` fallback that is the whole of format additivity for a new
diff --git a/server/guestbook-daemon/README.md b/server/guestbook-daemon/README.md
index 180a99d4..187761e0 100644
--- a/server/guestbook-daemon/README.md
+++ b/server/guestbook-daemon/README.md
@@ -1,6 +1,6 @@
# bento-guestbook-daemon
-The sustainable home of the public guestbook (see `working/guestbook-design.md`):
+The sustainable home of the public guestbook (see `working/design/guestbook-design.md`):
a Cloudflare Worker that serves the current epoch from Workers KV, archives the live
room on a cron (read-only CRDT replay), and rolls epochs with fresh credentials.
Deployed cadence today is every 30 minutes for both — see *Deployed cadence* below.
diff --git a/spaces/README.md b/spaces/README.md
index a0945a27..35e49b90 100644
--- a/spaces/README.md
+++ b/spaces/README.md
@@ -180,7 +180,7 @@ pages are one document rather than one file each.
its model is right, not when its UI is ready.
Tables and databases DID ship, as two separate things, which is the whole of
- working/spaces-design.md §2.6. A **table** is content — a `table` block whose
+ working/design/spaces-design.md §2.6. A **table** is content — a `table` block whose
`rows` are inline html, with no formulas and nothing that recalculates
(`tableOf`/`writeTable` in `src/model.ts`, the pipe-table export in
`src/blocks.ts`). A **database** is the tracker: `doc.fields` is the schema, a
diff --git a/spaces/src/blocks.ts b/spaces/src/blocks.ts
index 618ef072..5f429212 100644
--- a/spaces/src/blocks.ts
+++ b/spaces/src/blocks.ts
@@ -217,7 +217,7 @@ export const SPECS: BlockSpec[] = [
},
{
// A CONTENT table: rows and columns of inline html, no formulas and nothing
- // that recalculates (working/spaces-design.md §2.6). Custom, because a
+ // that recalculates (working/design/spaces-design.md §2.6). Custom, because a
// <table> is structure the default tag-plus-inline-host renderer cannot
// express, and `text: false` because its editable text lives in the CELLS —
// a block-level inline host beside them would be a second place to type
diff --git a/spaces/src/model.ts b/spaces/src/model.ts
index f40d7e8e..31f46ca3 100644
--- a/spaces/src/model.ts
+++ b/spaces/src/model.ts
@@ -749,7 +749,7 @@ export function isRemote(src: string): boolean {
}
// ---- tables ----------------------------------------------------------------
-// A table is CONTENT (working/spaces-design.md §2.6): no formulas, no
+// A table is CONTENT (working/design/spaces-design.md §2.6): no formulas, no
// recalculation, no cross-document references. The line the suite draws is
// "would you print it → folio; does it recalculate → dash; does it link to
// pages → spaces", and a table whose cells are inline html — so a cell can
diff --git a/type/README.md b/type/README.md
new file mode 100644
index 00000000..42e6a4ce
--- /dev/null
+++ b/type/README.md
@@ -0,0 +1,36 @@
+# bento/type
+
+A word processor where **one HTML file is the whole document**: the text, the
+pages it flows into, the reader, and the editor. Same bargain as the rest of
+bento — no account, no server, no sidecar folder.
+
+## Status: in development. Not released.
+
+**This directory is a construction site, not a product.** `bento/type` has no
+release, no version on [bento.page](https://bento.page), and no entry in the
+release registry (`scripts/apps.mjs`). A file you build from this source is an
+unsigned local build: its shell looks for updates at `bento.page/releases/type/`,
+where nothing is published and nothing is planned yet. Pagination, styles,
+citations and math are all still moving, and the document format may change in
+ways that do not migrate.
+
+It is developed in the open because the apps share one tree and one kernel, not
+because it is ready. There is no release date, and issues about missing or rough
+behaviour here are expected rather than useful. If you want the shipped product,
+that is `slides/` — and `spaces/`.
+
+## Run it
+
+```sh
+cd type
+npm install
+npm run dev
+npm run build:single # a local build; not a release
+```
+
+## Working here
+
+`type/` is this app's ownership zone. Read `AGENTS.md`, `docs/PLATFORM.md` and
+`docs/PARALLEL-WORK.md` first; `kernel/` is a separate, serialized zone. The
+format is additive and permanent from the moment anything ships — until then it
+is still being settled, which is the one freedom this stage buys.