Bento, the office suite that fits in a file
bento/spaces — for AI agents
Guide version __APP_VERSION__ · document format bento/spaces (v1).
A space (*.bento.html) is a self-contained HTML file holding a tree of
pages. The document lives in ONE plaintext block near the top:
<script type="application/bento+json" id="bento-doc">
{ "format": "bento/spaces", ... }
</script>
Two ways to work with it:
- File harness — edit the JSON inside
#bento-docin place. Escape every<as<so the block can never contain a literal</script>. Leave the rest of the file alone. - In the browser —
window.bento(below). Prefer the patch calls overloadDoc: rewriting the whole document to append a paragraph clobbers concurrent edits and flattens undo to one entry.
curl -fsSL https://bento.page/releases/spaces/Bento_Spaces.bento.html -o "<Name>.bento.html"
The downloaded file's #bento-doc block is empty. Opened in a browser it
mints a starter space; on disk there is nothing to copy from. Write your
document into the empty block.
The shape
{
"format": "bento/spaces", "version": 1,
"docId": "…", // minted once, NEVER regenerate it
"title": "Team handbook",
"home": "p-intro", // the page a reader lands on
"theme": { "background": "#FFFFFF", "color": "#1E2A3A", "accent": "#F7A600",
"fontFamily": "…", "measure": 720 },
"pages": [ // FLAT, in pre-order
{
"id": "p-intro", "title": "Introduction", "icon": "👋",
"parent": "p-parent", // optional — omit for a root page
"blocks": [ // FLAT, in pre-order
{ "id": "b1", "type": "p", "html": "Hello <b>world</b>." }
]
}
]
}
Designs
"design": "almanac" sets how the pages look. Leave it out for the default
look — never write "" or null. Built-ins: ledger, almanac, studio,
broadsheet, typescript, riso. The author picks the design; each reader's
light/dark setting picks between the design's two palettes. An unknown name
renders the default look, is kept, and validate() reports unknown-design.
A space can carry its own design in "designs", as overrides on a built-in:
"design": "harbour",
"designs": { "harbour": {
"label": "Harbour", "base": "almanac",
"light": { "accent": "#0f6e63", "paper": "#f3f1ea" }, // #rgb or #rrggbb only
"dark": { "accent": "#4fc2b1" },
"fonts": { "body": "news", "display": "asset:<key>" }, // a name, or an embedded font
"props": { "callout": "fill", "quote": "bar", "radius": 4 }
} }
Every value is validated, never interpreted. Colours must be hex; fonts
take a name (system grotesk humanist condensed transitional oldstyle news mono typewriter rounded) or asset:<key> naming a data:font/… asset; props
take the words and ranges listed in spaces/src/designs.ts PROPS. Palette
roles: paper ink muted rule soft accent accentInk onAccent tile tileInk cell1 cell2 cell3 toneNote toneTip toneImportant toneWarning toneCaution (the five
callout tones must stay distinct — design-contrast if they collapse). A value that fails is dropped to the base design's and reported as
bad-design-value; a colour that would put text under 4.5:1 is dropped as
design-contrast. There is no free CSS anywhere in a design. A name that is
also a built-in's is never used (design-shadows-builtin).
A page can name its own design with the same kind of value:
{ "id": "p-…", "title": "Q3 figures", "design": "ledger", … }. Absent means
inherit: a page wears its own design, else its nearest ancestor's, else the
space's design, else the default look — so a design on a section restyles
its whole subtree. Leave the key out to inherit (never "" or null). An
unknown name renders the DEFAULT look on that page (it does not fall through
to the parent's), is kept, and validate() reports unknown-design with that
page's id. Custom designs a page uses live in the space's "designs" like any
other. Embedded content — a gallery card, a view's rows, a page card, an
embed block showing another page — wears the design of the page it is shown
ON, not the page it points at.
The Markdown export opens with the design as front matter. The whole-space
file says design: <space's design> plus a one-line designs: {…} JSON
carrying every custom design the space or any page names; a single page's note
("Export page as Markdown…") says design: only when that page sets one
itself — an inherited design is not written. Import reads design: back onto
EACH note's own page and adds the carried designs: entries to the space's
registry (never over a name the space already uses); it does not change the
space's own design.
Both arrays are flat and in pre-order; nesting is a parent field. A child
always follows its parent, which is what lets one forward pass rebuild the
tree. Do not nest arrays inside arrays.
Every id is unique across the WHOLE document and is never reused. Links, backlinks and (later) collaboration key on them. A duplicate is repaired deterministically at load and reported — but a repaired id is a new id, so anything pointing at the old one is now pointing at the wrong node. Emit unique ids the first time.
Block types
type |
fields | renders as |
|---|---|---|
p |
html |
<p> |
h1 h2 h3 |
html |
<h1>…<h3> |
bullet number |
html |
<li> inside a <ul>/<ol> — adjacent siblings group automatically |
todo |
html, done |
<li> with a checkbox |
toggle |
html, open |
a fold; blocks whose parent is its id are its body |
callout |
html, tone, icon |
a boxed note; blocks whose parent is its id are inside it |
quote |
html |
<blockquote> |
code |
html (plain text), lang |
<pre><code>, syntax-coloured |
divider |
— | <hr> |
image |
src (see below), alt, caption, width (10–100 %), w/h (intrinsic px) |
<figure> |
pagelink |
page |
a card linking to another page |
embed |
page, anchor, html |
a live view of another page, or one section of it — see Embeds |
link |
url, title, desc, site, icon, image, html |
a card linking OUT of the space — see Link cards |
prop |
key, value, html |
one field value — see The issue tracker |
view |
layout, groupBy, source, filter, sort, html |
a board, list, table, gallery, timeline or workload chart of this space's pages |
view |
layout, span, groupBy, html |
a board, list, table, gallery or calendar of this space's pages |
view |
layout, groupBy, sort, source, filter, html |
a board or list of this space's issues |
chart |
kind (burndown/burnup/cfd), period, html |
a progress chart over doc.trail — see Progress charts |
type is a string, not a closed set: an unknown type survives a round trip
and renders its html as a fallback. Properties are flat on the block —
there is no props object.
Link cards
A link block is a card for somewhere on the web. Every field is stored in
the file and nothing is ever fetched — there is no server to read a url's
OpenGraph tags with, and opening a space must never contact a third party
(PLATFORM §1). So write the card yourself:
{ "id": "b7", "type": "link",
"url": "https://example.com/docs", // https:, http: or mailto: — nothing else is made clickable
"title": "The guide", // absent falls back to the url
"desc": "Everything about the thing",
"site": "example.com", // absent is derived from the url's host
"icon": "📘", // one emoji
"image": "asset:<key>", // OPTIONAL, and asset:/data: only — a remote one is DROPPED
"html": "<a href=\"https://example.com/docs\">The guide</a> — Everything about the thing" }
Write html too: it is what a build that predates this type renders, exactly
as it is for prop. A javascript: or data: url renders as a dead card that
keeps its title rather than as a link — validate() reports both that and a
remote image. Use pagelink, not this, for a page inside the space.
Embeds
An embed block shows another page live. It stores a reference and never a
copy: the source page is the truth, and editing it changes every embed of it.
{ "id": "b9", "type": "embed",
"page": "p-design", // the target page id, exactly as pagelink means it
"anchor": "Rollout", // OPTIONAL — one heading on that page, matched by NAME
"html": "<a href=\"#p/p-design\">Design notes</a>" }
Write html too, for the reason link and prop do: it is what a build that
predates this type renders, so an older shell shows a link to the source page
instead of a blank.
anchor names an h1/h2/h3 on the target, case- and
whitespace-insensitively, and the section runs to the next heading of the same
or higher rank — so an h2 takes its h3s with it. Leave it out for the whole
page; a name that matches nothing is reported by validate(), never quietly
widened back to the whole page.
Two limits, both deliberate and both visible to the reader rather than silent:
a page cannot embed itself or anything that leads back to it (the loop renders
as a named placeholder), and an embed chain is followed at most three pages
deep. validate() reports both, plus a target that is not a page.
An embed produces a backlink on its target, exactly as a pagelink does —
it is the strongest reference in the model, since the page it names is being
shown somewhere else. In Markdown it is Obsidian's ![[Page]] / ![[Page#Section]],
in both directions: a vault's embeds import as embeds and export as themselves.
Callouts
tone is one of note tip important warning caution — GitHub's alert
names, so a callout exports as > [!WARNING] and reads back as the same tone.
Absent means note. Like type, it is an open string: a tone this build does
not know is kept, styled neutrally and labelled with its own word, so writing
one is lossy in appearance only.
icon is optional and is an override. Leave it out and the mark is derived
from the tone, which is what keeps every warning in a document looking alike;
set it to an emoji when the callout is not really about severity.
{ "id": "b7", "type": "callout", "tone": "warning",
"html": "The key is not recoverable." },
{ "id": "b8", "type": "bullet", "parent": "b7", "html": "inside the box" }
A code block carrying frontmatter: true (usually lang: "yaml", inside a
collapsed toggle at the top of a page) is YAML frontmatter from an imported
markdown file, kept verbatim. It is not a properties model — spaces has
none yet — so read it if you like, but do not invent fields from it.
Images: embed them, don't link them
src takes three forms, and only two of them display without asking:
src |
on open |
|---|---|
asset:<key> — a key in doc.assets |
displays |
data:image/…;base64,… |
displays |
https://…, //host/…, or a relative path |
placeholder until the reader clicks "Load this image" |
A remote url is not fetched when a space is opened. Opening a document must never tell a third party that it was opened — in a format built to be mailed, that is a tracking pixel — and PLATFORM §1 requires that no network be needed to open a file. The reader's consent is per-url, per-session, and never stored in the document.
So embed the bytes. Put a data: URI in doc.assets under a key and
reference it as asset:<key>:
{
"assets": { "img1": "data:image/webp;base64,UklGR…" },
"pages": [{ "id": "p1", "title": "…", "blocks": [
{ "id": "b1", "type": "image", "src": "asset:img1",
"alt": "Revenue by quarter", "w": 1200, "h": 800 }
] }]
}
Give w/h (the intrinsic pixel size) so the page does not reflow while the
image decodes, and always write alt — it is what a reader sees if the image
is remote and unloaded.
Keep images to 1600px on the longest edge and use WebP: that is what the editor's own downscale does, and it is the difference between a space someone can mail and one they cannot.
Code blocks
html is the source as plain text, html-escaped (& < > only) — never
markup. Colour is applied when the page is drawn, so the document is identical
whether or not this build can highlight the language.
lang is a free string and is stored exactly as you write it. These tags
are highlighted:
js ts py sh json yaml sql html css
plus the aliases you would reach for anyway — javascript jsx typescript
tsx python bash zsh shell yml postgres mysql xml svg. Any
other tag (rust, go, …) renders plain and is preserved: it exports as its
own fence and starts highlighting by itself if a later build learns it. So tag
the block honestly — never re-tag it as something close.
{ "id": "b4", "type": "code", "lang": "sh",
"html": "curl -fsSL https://bento.page/… -o Notes.bento.html" }
Rich text
html is inline only: b i u s em strong code a span mark sub sup br.
Block structure is type, never markup — a <p> or <div> inside html is
always a mistake and is unwrapped at load.
Links are same-document fragments:
{ "id": "b7", "type": "p", "html": "see <a href=\"#p/p-intro\">the intro</a>" }
href must match ^(https?:|mailto:|#p/). Anything else is stripped.
Footnotes
A footnote reference is the literal text [^label] inside a block's html,
and the notes live in one document-level table:
{
"pages": [{ "id": "p1", "title": "Coffee", "blocks": [
{ "id": "b8", "type": "p", "html": "Coffee grows in the tropics.[^1]" }
] }],
"footnotes": { "1": "Between Cancer and Capricorn." }
}
The reference is text, not markup — no tag, no attribute, nothing for the
sanitizer to allow — so it survives every edit and every sanitize pass exactly
the way the word beside it does, and a build that predates footnotes shows the
sentence with [^1] in it and round-trips the footnotes key untouched.
A label is [A-Za-z0-9_-]{1,32}. It is an identifier, not a number: notes
are numbered by order of appearance and the number is derived when the page is
drawn, so inserting a reference earlier on the page renumbers everything after
it and nothing in the file changes. Never write a number into the model and
never expect [^1] to render as 1.
Numbering is per page — the page is what prints and what a reader reads.
The section at the foot of a page is derived too: it is that page's references,
in order, so there is no block to add and nothing to keep in step. A note's
value is inline html, under the same allowlist as a block's.
[^label] inside a code block is left alone. It is not scanned in one and
never becomes a reference.
Markdown import and export both speak [^1] and [^1]: the note., so an
Obsidian or Pandoc vault keeps its footnotes in both directions.
Markdown in and out
"Download as Markdown" writes every page as one .md file, and "Import
Markdown" reads .md files, a folder of them or an Obsidian vault. For every
block type except prop, a block that goes out comes back as the same block,
with the same JSON apart from its id and the same text on the next export
(scripts/test-spaces-md-strict.ts holds that bar type by type). You can
write these forms by hand or generate them, and they are what this app reads.
The rule behind every choice: use a syntax other Markdown tools already read, so the file still makes sense on GitHub, in Obsidian and in a plain editor. Invent syntax only where nothing exists, and then use a fenced block, which everything else shows as code.
| block | Markdown |
|---|---|
p, h1–h3, lists, todo, quote, code, divider |
CommonMark / GFM, as you would write it |
table |
a GFM pipe table; an empty header row means header: false |
callout |
a GitHub alert, > [!WARNING], with the body inside the blockquote |
toggle |
<details open> (or <details> when folded), <summary>text</summary>, the children, then </details> |
image |
{width=60% w=640 h=300}. The size is a Pandoc attribute list: width is the column percentage (10–100), and w/h are the intrinsic pixels, both or neither |
link |
[title](url) — description <!-- bento:card site="…" icon="…" image="…" -->. The comment makes the line a card, and every renderer hides it. A lone link without it stays a paragraph |
media |
<video src="…" controls loop muted poster="…" title="alt" width="…" height="…" data-width="…" data-caption="…" data-autoplay><a href="…">alt</a></video>, or <audio …> |
pagelink |
[[Page title]] alone on its line |
view |
a fence ```bento-view holding ONE JSON line, {"name":"Issues","layout":"board","groupBy":"status"}, which may be followed by // lines (ignored) |
canvas |
a fence ```bento-canvas holding {"name":"Map","ratio":1.6,"cards":[[40,60],null]}, then the cards as the next blocks at the same level, one per cards entry |
prop |
**Status:** In progress, which comes back as a paragraph. Fields will move to front matter |
Inline marks: **bold**, *italic*, ***both***, ~~strike~~,
`code`, ==highlight==, and <u>, <sub> and <sup> as raw html.
A palette colour is raw <span class="sp-fg-red"> or
<mark class="sp-bg-yellow">, and on import the Pandoc forms
[words]{color=red} and [words]{bg=yellow} also work. Only the nine
palette names count: gray, brown, orange, yellow, green, blue, purple, pink
and red.
Block ids. {#id} at the end of a block's line (for a fence, on its
opening line; for a toggle, on the <details> line) gives the block that id.
The exporter writes one only on blocks that something points at: a comment
thread, or a #p/<page>/<block> link. On import an id that is already used,
in the note, in the import or in the space, is replaced with a fresh one.
Tables and dividers never carry an id.
Everything imported is untrusted. Links, clip sources, posters and card
thumbnails go through the same allowlists as the editor: https:, http: and
mailto: for links; asset:, an inline file of the right kind or http(s)
for media; and never javascript:, svg data or a relative path for a player.
No attribute is copied from html by name. Fences are read with JSON.parse,
and a fence cannot set id, type, parent, html or comments.
Reserved syntax, for features not yet on main
These features exist only on unmerged branches. When they land, their Markdown form is this one, so every branch reads the same file the same way:
| feature | Markdown | why |
|---|---|---|
| math | $…$ inline, $$…$$ on its own lines for a display block |
what GitHub, Obsidian, Pandoc and KaTeX-based tools read |
| diagram | a ```mermaid fence holding the source |
GitHub and Obsidian render it, and it is a code block with lang: "mermaid" today, so nothing changes in the format |
| chart | ```chart bar (or line, pie …), holding a GFM table or CSV of the data |
everything else shows the data as a readable table. The chart type is the word after chart |
| transclusion | ![[Page]], or ![[Page#Section]] for part of a page, alone on its line |
Obsidian's embed. ![[picture.png]] stays an image |
| footnotes | [^1] in the text and [^1]: the note. below |
GFM footnotes, which GitHub renders |
| layout | :::columns, :::hero and :::card fenced divs, closed by ::: |
Pandoc and markdown-it-container read them, and anything else shows the markers as text around readable content |
The issue tracker
An issue is a page. There is no issue type and no flag: a page carrying a
status field is an issue, and a page that loses its status is a document again
with everything else about it intact.
A field VALUE is a prop block on that page. The SCHEMA is
document-level — doc.fields, absent means the built-in seven.
{
"fields": [ // document-level, optional
{ "key": "status", "label": "Status", "vt": "select", "def": "todo",
"options": [
{ "id": "backlog", "label": "Backlog", "color": "#8B95A5", "group": "unstarted" },
{ "id": "todo", "label": "Todo", "color": "#5B8DEF", "group": "unstarted" },
{ "id": "doing", "label": "In progress", "color": "#F7A600", "group": "started" },
{ "id": "review", "label": "In review", "color": "#A97BE0", "group": "started" },
{ "id": "done", "label": "Done", "color": "#2FA37C", "group": "done" },
{ "id": "cancelled", "label": "Cancelled", "color": "#98A2B3", "group": "cancelled" }
] },
{ "key": "priority", "label": "Priority", "vt": "select", "def": "none",
"options": [ { "id": "urgent", "label": "Urgent" }, { "id": "high", "label": "High" },
{ "id": "medium", "label": "Medium" }, { "id": "low", "label": "Low" },
{ "id": "none", "label": "No priority" } ] }, // every option needs a label
{ "key": "assignee", "label": "Assignee", "vt": "person" },
{ "key": "estimate", "label": "Estimate", "vt": "number" },
{ "key": "labels", "label": "Labels", "vt": "labels" },
{ "key": "start", "label": "Start", "vt": "date" },
{ "key": "due", "label": "Due", "vt": "date" },
{ "key": "project", "label": "Project", "vt": "text" }
],
"pages": [{ "id": "i-42", "title": "Search drops a keystroke", "blocks": [
{ "id": "b1", "type": "prop", "key": "status", "value": "doing", "html": "Status: In progress" },
{ "id": "b2", "type": "prop", "key": "assignee", "value": "ana", "html": "Assignee: ana" },
{ "id": "b3", "type": "p", "html": "Only on iOS, and only when typing fast." }
] }]
}
value is the option id; html is the readable form, and you write BOTH.
html is what an older build, a file-manager thumbnail, a grep and the
markdown export see, and it is all they see — a value written without it is
invisible to every one of them. The form is exactly <Label>: <shown>, where
shown is the option's label for a select, the values joined by , for
labels, the value as text otherwise, and — when it is unset. Use
bento.setField() and this is not something you can get wrong; hand-editing the
file, it is the thing to get right. bento.validate() reports a mismatch as
prop-html-stale.
Fields render as a header strip by POSITION: the prop blocks before the
first non-prop block are drawn as one row under the title. There is no flag —
put them first.
Unknown values and unknown keys are kept, never corrected. A status this
build cannot name is shown verbatim and grouped as unknown; a field key that
is in no schema keeps rendering its own html. That is how a document written
by a newer build survives an older one, so never "fix" one by blanking it.
A board or list is a view block, and it stores a query, never a membership
list: { "type": "view", "layout": "board", "groupBy": "status", "html": "Issues by status" }. Put it on a page of its own — a page carrying a
view is laid out wide.
layout is one of board (the default, and the ABSENT key — never write
"board"), list, table, gallery, gantt and workload. A chart is a
layout here, not a block type, so every shape reads the same four keys and a
build that predates a shape draws a board of the same pages rather than a
fallback line of text.
ganttdraws one bar per page, from itsstartdate to itsduedate, with today marked and overdue work outlined. A page with only ONE of the two dates gets a milestone diamond at the date it has — which is what every issue written beforestartexisted looks like, so do not add a made-upstartto "fix" one. A page with neither is left out and counted.workloadadds up the firstvt:"number"field in the schema per bucket and draws a bar chart. The bucket isgroupBy; absent, it is the firstvt:"person"field. A negative or non-numeric estimate is excluded and reported rather than summed — do not write one expecting it to subtract.
Both honour source and filter, so "the workload for this project" is
{ "layout": "workload", "source": { "under": "<page id>" }, "filter": { "open": true } }
and needs no key of its own.
layout is one of list, table, gallery, calendar — or absent, which
means a board. Never write "layout": "board": absence is what every view
written before layouts existed carries, and a stored "board" is a byte
difference that says nothing.
A calendar lays the view's pages out by date, and has two shapes: a month
grid (span absent) and a chronological agenda, newest first. The agenda is
stored as span: "timeline" — write that value; the UI calls it "Agenda", but
the stored name predates the label and does not change. Which date a page sits
on is a fixed rule, not a setting — its journal date if it has one,
otherwise its due date (when the schema declares due as a date field),
otherwise the first other date-typed field, in schema order, that it carries
a real YYYY-MM-DD value for. A page the rule finds no date
for is listed under "No date" rather than dropped, and a value that is
digit-shaped but not a real day (2026-13-99) counts as no date rather than
being rolled into some other day. Month names, weekday names and the first day
of the week come from the reader's locale at display time; nothing formatted is
ever stored.
A view's source says which pages it holds: { "has": "<fieldKey>" },
{ "under": "<pageId>" }, or { "tag": "<tagKey>" }. Absent means the
backlog. The tag key is lower-case and reaches nested tags, so
{"tag":"project"} also holds the pages carrying #project/bento.
Tags
Write #tag in a block's html — that is the whole storage. There is no
tags field on a page and you must not invent one: the index is derived from
the prose every time it is asked for, exactly as backlinks are, so a stored
list would be a second copy that goes wrong the first time anything edits
html without knowing tags exist. Nothing to maintain, nothing to keep in
step.
What is and is not a tag, since a # means several things:
| written | read as |
|---|---|
#recipe, #work-in-progress, #レシピ |
a tag |
#project/bento |
ONE nested tag, also counted under project |
# Title |
a Markdown heading — a tag never has a space after the hash |
#42, #404 |
an issue number, not a tag |
#fff, #f7a600 |
a CSS colour, not a tag |
C#, a#b |
a # inside a word |
<code>#include</code> |
code |
https://x.example/p#top |
a URL fragment |
<a href="#p/abc">…</a> |
a page link — the href is an attribute, never text |
Tags are case-folded for matching and keep the casing you typed for display.
Narrowing a view
filter is optional and every key inside it is too. Absent means everything,
and so does an absent key — a view with no filter shows every row, forever.
Write no filter key at all rather than an empty object.
{ "type": "view", "layout": "table", "filter": {
"open": true,
"is": { "labels": ["ui"] },
"where": [
{ "key": "due", "op": "in", "v": "past" },
{ "key": ":title", "op": "contains", "v": "onboarding" }
]
} }
open— only rows whose status phase is neitherdonenorcancelled.is—{ fieldKey: [values] }, membership; a row passes a key if it holds any of the listed values. An empty list is no constraint, not "nothing passes".where— a flat list of conditions, ANDed. Set"any": truealongside it to OR them instead;anyreacheswhereonly, andopen/isalways AND.- Each condition is
{ key, op, v? }.keyis a field key, or":title"for the page title.
op |
means | v |
|---|---|---|
eq / ne |
exact match on the STORED value; membership for a list-valued field | string or number |
gt gte lt lte |
numeric for a number field, otherwise text — and a date field's YYYY-MM-DD sorts chronologically as text |
string or number |
contains / notContains |
case-insensitive substring of the READABLE value (a select's label, a labels list joined) | string |
empty / notEmpty |
the value is unset — absent, "" or [] |
— omit v |
in |
a date within a window resolved against the READER's today | "today" "week" "month" "past" "future" |
Two conditions on one number make a range. "past" on a due date is "overdue".
Relative windows are stored as the WORD and resolved when the view is drawn, in
the reader's own timezone and week — a stored {"op":"lt","v":"2026-09-10"}
would be right on the day you wrote it and wrong every day after.
An operator a build cannot evaluate is not applied and reported, so the view shows a superset with a banner over it rather than the wrong rows. That is the same trade the format makes everywhere: never silently narrow.
Not in this format, deliberately: teams, per-user permissions, notifications, automation. The file is the team boundary and the capability.
Progress charts
A chart block draws burndown, burnup or cumulative flow from
doc.trail — a record the file keeps of itself, one row per local day:
{
"trail": { // document-level, optional
"2026-09-08": {
"n": { "todo": 3, "doing": 2, "done": 1 }, // issues per STATUS OPTION id
"e": { "todo": 11, "doing": 8, "done": 4 }, // summed estimate, absent if nothing is estimated
"x": 2 // issues counted that carried no estimate
}
},
"periods": { // the windows charts are drawn over
"pd-1": { "label": "Sprint 12", "from": "2026-09-01", "to": "2026-09-20",
"base": { "at": "2026-09-01", "n": 6, "e": 23 } }
}
}
Three things to know before you touch either of them.
Do not write past rows. The app writes TODAY's key and only today's; a row, once written, is immutable for the rest of the file's life. Rewriting yesterday from today's numbers is the one thing the whole design exists to prevent.
A missing key is a GAP and is drawn as one — a broken line and a hatched
band labelled "not recorded". Do not fill gaps in, and never carry a value
forward: a carried value looks exactly like data. A row carrying s stands for
that many days ending on its own key and draws dashed, so a weekly sample is
never mistaken for a daily reading.
A row holds counts and nothing else. No page ids, no assignee breakdown, no
per-issue anything — that is a budget rule and a privacy rule at once, and it
is not an oversight to be helpfully corrected. What a trail discloses is the
team's cadence, so trail is version history in the copy rules: the file, a
duplicate and an invite keep it; a view-only copy, the reading copy, Copy
document JSON, a template and a page extract carry none of it. It is never
synced either — each copy records what it saw. periods is ordinary content:
it syncs, and every copy keeps it.
Both keys are absent until something is recorded, and a cleared space deletes
the key rather than storing {}. A chart block whose period names nothing
renders "this chart's period is gone" rather than an empty graph.
What makes a space good rather than merely correct
| When the material is… | Reach for | Why |
|---|---|---|
| more than one topic | separate pages, not headings in one long page | the sidebar, ⌘K and backlinks all key on pages |
| a topic that belongs under another | parent on the page |
the tree is the navigation |
| a reference to another page | an inline #p/ link |
it produces a backlink on the target automatically, at no cost |
| a list of sub-pages | one pagelink block each |
a visible card beats a bare link for a hub page |
| one page's material that belongs on another too | an embed, narrowed with anchor |
the source stays the single copy — a pasted duplicate is what goes stale |
| steps someone will tick off | todo |
state lives in the document, so it survives sharing |
| an aside, or detail most readers skip | toggle with its body as parent children |
folds away, and always PRINTS expanded |
| a warning the reader must not miss | callout with the tone that fits |
it is boxed, named and legible in print and without colour vision — but three per page and none of them registers |
| anything you would print | remember toggles print open and archived pages are excluded |
| a topic that recurs across pages | an inline #tag in the sentence | the index, ⌘K's # mode, a view sourced on it and the graph all derive from it |
The most-missed feature is backlinks. They are derived — link to a page and it lists the linker, with no maintenance. A space where pages only link down the tree wastes the one thing this format does that a folder of files cannot.
Give a page aliases when people call it more than one thing. aliases: ["NYC", "the Big Apple"] on a page titled New York makes all three names reach
it from a [[wikilink]], from ⌘K and from the [[ picker — and makes prose
that says "NYC" show up as an unlinked mention on that page. It costs one array
and it is the cheapest way to make a space find things for its reader.
window.bento
// read
bento.doc // the live document
bento.pages() // [{id, title, parent, archived, blocks}]
bento.getPage(id) // one page, with its blocks
bento.search(q) // [{pageId, title, blockId}]
bento.outline() // the whole space as a tree
bento.mentions(pageId?) // where a page is named but not linked
bento.validate() // what is wrong or suspect
bento.stats() // pages, blocks, words, bytes, biggest assets
bento.comments(query?) // review threads, flat, with a typed anchor
// write — each one is ONE undoable step
bento.fields() // the field schema in force
bento.issues(query?) // the backlog, as data
// write — each one is ONE undoable step
bento.setField(pageId, key, value) // → {ok:true, …, warning?} | {ok:false, err}
bento.newIssue({title, ...fields}) // → {ok:true, id, blocks, warnings?}
bento.newPage(title, parent?) // → new page id, or null
bento.insertBlocks(pageId, afterId, [...]) // → new block ids, or null
bento.updateBlock(id, patch) // → {ok:true, id, page} | {ok:false, err}
bento.removeBlocks([ids]) // → {ok:true, removed, missing, added}
bento.moveBlock(id, {pageId?, afterId?, beforeId?, parent?})
bento.updatePage(id, patch) // → {ok:true, id} | {ok:false, err}
bento.removePage(id, {descendants?}) // → {ok:true, removed, rehomed, links}
bento.loadDoc(json) // replace the content (one undo step); docId, collab, readonly, template and revisions stay
bento.serialize() // the whole .bento.html file
bento.undo() / bento.redo()
bento.readonly // true = a locked or frozen file; every write returns err:'readonly'
Use the patch verbs, not loadDoc. Rewriting the document to add a paragraph
flattens undo to one entry and overwrites anything a person typed while you
were thinking.
A refused write changes nothing at all — including undo history. Every verb validates before it touches the document, so a rejected patch does not leave an empty step for someone to undo.
Results are tagged
The verbs added after 0.1.0 return {ok: true, …} or {ok: false, err, detail}
rather than null. err is one of readonly, no-such-block, no-such-page,
no-such-field, bad-patch, immutable, not-serializable, cycle,
last-page.
insertBlocks and newPage keep their original shapes (ids, or null),
because files and scripts already depend on them.
Nothing is ever silently ignored. Sending id in a patch is an error, not a
no-op; so is blocks in a page patch (block structure goes through the block
verbs, which keep ids, nesting and undo coherent). In a patch, null deletes
a field.
bento.validate()
const { ok, counts, findings } = bento.validate()
findings.filter(f => f.severity === 'error')
Each finding is {code, severity, message, fix, page?, block?, path?}. It
reports duplicate and missing ids, a page inside its own subtree (which is the
one way a page becomes unreachable), parents naming nothing, #p/ links and
pagelink cards and embed blocks pointing at pages that do not exist
(broken-embed), embeds that loop back to their own page (embed-cycle) and
embed anchors that name no heading (no-section), unknown block types, block
markup inside inline html (and markup that is dropped whole), hrefs outside the
allowlist, images with no alt, no size, a missing asset: or a remote src,
a home naming nothing, pages with no blocks, and assets nothing references.
On footnotes it adds dangling-footnote (warning: a [^label] with no
note behind it — the reference still renders, numbered, into an empty note),
orphan-footnote (info: a note in doc.footnotes that nothing references,
so it is never numbered and never printed — it is kept, never deleted) and
unreachable-footnote (warning: a label outside the grammar above, which
no [^label] can ever match).
On the tracker it adds: prop-html-stale (a value whose readable html says
something else — the check worth running after any hand edit),
unknown-field-value and unknown-field-key (info, because that is how a
newer build's data arrives — the value is kept), duplicate-prop (two values
for one field on one page; a reader takes the last), prop-no-key, and
bad-field-schema for a doc.fields entry with no string key and label,
which is an error: writing a value for that field throws.
ok means no errors; warnings and info do not make a document invalid.
Severity is meant literally, so that a clean document is silent: validate()
reports nothing at all on the space a fresh file opens with, and the rig
enforces that. If you get findings, they are about your document.
It only reads. A finding is advice, never a refusal — parseDoc remains the
thing that decides whether a document opens at all.
Unknown property names are deliberately not reported: unknown fields are how this format carries a future version's data, and how you can park your own metadata on a block.
bento.outline()
The whole space in one call instead of one getPage per page:
bento.outline()
// { title, docId, pages, blocks, words,
// tree: [{ id, title, depth, parent?, icon?, archived?, home?,
// blocks, words, headings: [{id, level, text}], links: [pageId] }] }
In sidebar order (depth-first). Headings carry their block id, so what comes
back can be handed straight to updateBlock or moveBlock. links is what
that page points at, which is the other half of the backlinks a reader sees.
bento.mentions()
bento.mentions('p-abc') // that page's unlinked mentions
bento.mentions() // every page's, as { pageId: Mention[] }
// Mention: { pageId, fromPage, fromBlock, matched, htmlStart, htmlEnd, snippet }
Where a page's title or aliases appear as plain words in some other page
without a link. matched is the text as it was actually written, and
htmlStart/htmlEnd are offsets into fromBlock's html, so a link can be
spliced in exactly where the words are rather than found again by string search
— which would hit the wrong occurrence when the name appears twice.
It never reports a name inside a code block, a code span, a link that already exists, a URL or a mail address; nor in a block that already links to the target; nor in the page's own text; nor as part of a longer word. Names under three characters (two, for a name written in Han, kana or Hangul) are not scanned for at all.
READ ONLY on purpose. Deciding that a sentence meant that page is a
judgement, and an agent that rewrote a hundred blocks on a guess would be
unreviewable. Link the ones you are sure of with updateBlock, and leave the
rest to the panel, where a person can see the sentence before deciding.
bento.stats()
bento.stats()
// { pages, archived, blocks, words, characters, blockTypes, todos,
// assets: {count, bytes, orphans, orphanBytes},
// bytes: {document, assets, text},
// biggest: [{key, bytes, mime, used}] }
This answers "why is this file 30 MB". It is always the images: prose is free
(2,000 pages of it is about 5 MB). used is how many blocks reference that
asset — 0 means it is dead weight, and deleting the key is pure savings. The
app shell adds a fixed ~80 KB on top of bytes.document.
bento.comments()
bento.comments({ resolved, pageId })
// [{ id, anchor:'block'|'page', pageId, pageTitle, blockId?, url:'#p/<id>',
// author, at, text, resolved, replies:[{id, author, at, text}] }]
What a person flagged, from every page, in document order. anchor says what
the thread is about: a block (and blockId names it) or the page as a
whole. text is plain text — never html, in or out. Start with
bento.comments({ resolved: false }): those are the ones still asking for
something.
It is read-only, deliberately. Acting on a remark is your job; marking it resolved is the commenter's, and an agent that closed the thread it was asked to address would make the record untrue. Say what you did in a block, and leave the thread open.
The patch verbs, exactly
bento.insertBlocks(pageId, afterId, blocks)
Mints fresh ids — never yours — and inserts after afterId (null = the end of
the page). An afterId that is not on that page is an error; it does not
append somewhere else and report success. Blocks in one batch may nest inside
each other: give them temporary ids and use those as parent, and the
references are remapped to the minted ids.
bento.updateBlock(id, {html, type, done, open, src, alt, …})
Changes fields on one block. null deletes a field. id is refused. parent
must name a block on the same page and may not be inside the block's own
subtree.
bento.removeBlocks([id, …])
Takes the nested blocks with it — deleting a toggle deletes its body, because
leaving blocks pointing at an id that no longer exists means they reappear,
un-nested, at the next load. Ids that were not there come back in missing. If
this empties a page, one blank paragraph is created and returned in added (a
page with no blocks has nothing to put a caret in — nobody can type in it).
bento.moveBlock(id, {pageId, afterId | beforeId, parent})
Moves a block and everything nested under it. Neither anchor = the end of the
page. Moving across pages drops a parent that does not exist there; pass
parent to re-nest deliberately, or null to un-nest.
bento.updatePage(id, {title, icon, parent, archived, …})
title is plain text (it renders as text, so markup would show literally).
parent may not be one of the page's own descendants. archived: false
removes the key, which is what the editor writes.
bento.removePage(id, {descendants: false})
By default the pages inside it move up a level rather than disappearing with it;
{descendants: true} takes the subtree. links in the result counts the
inbound links that just went dead. Removing every page is refused.
The tracker verbs, exactly
bento.fields()
// [{ key: 'status', label: 'Status', vt: 'select', def: 'todo',
// options: [{ id: 'todo', label: 'Todo', color: '#5B8DEF', group: 'unstarted' }, …] },
// { key: 'assignee', label: 'Assignee', vt: 'person' }, …]
Call this first. A value is set by option id, and the ids are not the
labels: doing, not In progress. The schema is the document's own
(doc.fields), so a space may declare fields these defaults never had.
bento.setField(pageId, key, value)
// {ok:true, pageId, key, value, html, blocks:[id], created, removed, warning?}
Writes value and its readable html together, which is the only reason
this verb exists: write a prop block yourself through insertBlocks and you
will eventually get that pairing wrong, and then the file says one thing to this
build and another to every older build, every thumbnailer, every grep and the
markdown export — silently, forever.
The page need not be an issue: setting status is what makes it one. A
value for a field the page does not carry yet is created in the header strip
(created: true). null clears the field, block and all — clear the status
and the page is an ordinary document again, body intact.
It refuses no-such-page, no-such-field (the key is in no schema) and
not-serializable, and returns err: 'readonly' on a locked file. A value that
is not one of a select's options is written, not refused — the format is
permanent and additive, so a status a newer build declared has to survive this
one — but it comes back with warning: {code:'unknown-option', options:[…]}.
If you see that warning and you did not mean it, you typed a label where an id
belongs.
bento.issues({ where, group, archived })
// [{ id, title, url:'#p/<id>', archived?, group, fields:{status, priority, …} }]
where is field equality: a value, an array for any-of, or null for not
set (which covers both an absent field and an empty one). group is the
status phase — unstarted started done cancelled, plus unknown for a
status no option declares, and open, which means "not finished" and is the
one you want. Archived issues are excluded unless you ask for them.
bento.newIssue({ title, ...fieldValues }) // → {ok:true, id, blocks, warnings?}
One page, one undoable step, every value written through the same path. title
and parent are the page's; every other key is a field key, and one that is
not in the schema is refused rather than parked on the page (an unknown key in
an argument is a typo, not additivity). It does not navigate — make twenty and
the person's cursor stays where it was.
Triage, worked
const ids = new Set(bento.fields().find(f => f.key === 'status').options.map(o => o.id))
// → {'backlog','todo','doing','review','done','cancelled'}
// everything open and unassigned, oldest first in page order
const inbox = bento.issues({ group: 'open', where: { assignee: null } })
for (const it of inbox) {
const body = bento.getPage(it.id).blocks.map(b => b.html).join(' ')
if (/crash|data loss/i.test(body)) {
bento.setField(it.id, 'priority', 'urgent') // an id, never 'Urgent'
bento.setField(it.id, 'assignee', 'ana')
}
}
// a new one, complete, in one call
const { id } = bento.newIssue({
title: 'Search drops the last keystroke on iOS',
status: 'todo', priority: 'high', estimate: 2,
})
bento.insertBlocks(id, null, [{ type: 'p', html: 'Steps: type fast in ⌘K…' }])
bento.validate().findings.filter(f => f.code.startsWith('prop-') || f.code.includes('field'))
Every setField and newIssue is its own undo step, so a person watching can
take back exactly the one they disagree with. Check the warning/warnings on
what comes back before you move on: they are how you find out you set something
nothing will ever group.
What you may write
Everything an agent writes goes through the same sanitizer the editor uses, on
the way IN: an agent cannot put into a file something this build could not have
produced. html is reduced to the inline allowlist (a <script> does not
survive), a code block's html is escaped text rather than markup, and a patch
value JSON cannot carry — a function, a Date, a Map, a cycle — is refused
rather than vanishing quietly at save time.
Before you finish — self-audit
-
bento.validate()clean of errors, and every warning either fixed or a deliberate choice you could defend? - More than one topic? Separate pages, not headings in one long scroll.
- Does anything link across the tree, or does everything only link down? Backlinks are the feature a folder of files cannot have.
- Every image
alt-texted and embedded as anasset:? - Have you opened it? Click through the pages, fold the toggles, follow the links. A space nobody read is not finished.
Gotchas
- Escape
<as<when writing the file block. - Don't invent property names — unknown keys are preserved but ignored, so a typo means your styling silently does nothing.
docIdis the document's identity. Never regenerate it when editing.- A
parentnaming something that does not exist is dropped at load: the page becomes a root page, the block re-homes. Not fatal, but not what you meant.validate()names every one of them. - Never write a page with an empty
blocksarray. Nothing in it can take a caret, so it is a page nobody can type in. Give it[{ "type": "p", "html": "" }]—bento.newPage()does exactly that. doc.revisionsis the space's version history, kept inside the file: oldest first, each entry{ id, at, label?, body }wherebodyis the change from the entry before it. Leave it alone. Saving appends to it; only Save ▾ → Versions in this file… → Clear history removes it.bento.loadDockeeps the open space's history whatever the JSON you pass carries, so a whole- document rewrite cannot delete it, and cannot plant one either. If you write#bento-docfrom outside the app, copy the field across unchanged; an entry this build cannot read makes the whole list read-only (kept, never extended).readonly: truemarks a READING COPY: the file opens in the reader (no editing tools, no comment markers, a Previous/Next pair under each page) andbento.readonlyis true, so every write returnserr: 'readonly'. (A view-only copy that follows a live session —collab.role: 'reader'— may carry the flag too; it opens locked but stays the live viewer.) Apolicythis build does not know opens frozen for a different reason — we do not understand the file — and is likewise refused. In both cases the document round-trips byte-exact.readonlyis INTENT, not a lock: the document block is plaintext, so anyone can clear the flag. What a reading copy actually guarantees is what it does not contain — nocollabblock (every room credential), no comment thread, no in-file version history and no top-level field the writing build did not declare.- A remote image
srcshows a placeholder until the reader asks for it. Embed the bytes as anasset:instead — see Images above. - A shared space (its
collabnames a room) syncs between open copies, and a saved copy carries its sync state incollab.syncso it can rejoin the session later as a fork. Leavecollabalone. An edit written into#bento-docfrom outside the app is not in that state, so it is not reliably carried to the other copies when the file next joins — edit a shared space throughwindow.bentoin the open file instead.