Repository navigation
v0.20.0
Reload open tabs after the upgrade. A tab that still runs 0.19 or older cannot show columns, and its editor
would delete a group of columns with everything inside it. 0.20 lets such a tab read pages with columns but not
edit them, until it is reloaded (below and docs/adr/2425-*).
A minor release with columns, charts on public links and better find_context answers for Korean questions. Blocks can sit side by side in
two to four columns (/2단, /3단); agents, Markdown downloads, zip export and vault sync carry them as comment
markers. A tab of an older release can no longer delete them: each client tells the server which document schema it
knows, and the server takes edits only from clients that know every node on the page. find_context counts the
shorter form of a long Korean word in titles and headings, prefers sections with the question's rarest word and
gives title words their real weight. A public link can now show the page's charts, drawn as charts from labels and
numbers, once an owner or admin turns it on for that link; public pages also draw callouts (icon, then text) and
text and background colours as the editor does. One database migration, additive: 0061_share_include_charts (three
columns on pages; a 0.19 database goes from 61 to 62 applied migrations, and every existing link keeps charts off).
No new dependency, two optional settings (EMBEDDING_QUERY_PREFIX, EMBEDDING_PASSAGE_PREFIX). The MCP tool list keeps its 48 tools
(32 in core) and their descriptions; every tool now carries its annotation hints (+468 tokens full, +324 core). Upgrade matrix adds v0.19.0 and v0.19.1.
Checked in Chrome only (desktop and a 390 px window): the columns check (31 steps), a 0.19.1 build against the 0.20
server (10 steps), public charts (27 steps), public callouts and colours (16 steps) and the 0.19 browser checks passed; none of it was tried in Safari, Firefox or on a touch device
(docs/KNOWN-ISSUES.md, "Added in 0.20.0").
Upgrade notes
- Tabs left open over the upgrade (docs/adr/2425-*). Pages without columns: nothing changes, a 0.19 tab edits
them as before. Pages with columns: a 0.19 tab gets a read-only connection. It shows the page without the group,
under its lock line ("Locked · … You can read and comment, but not edit": 0.19 reads a read-only connection as a
lock), next to its own "A new version is available. Reload" notice; typing does nothing and nothing it does
reaches the page. When someone adds columns to a page a 0.19 tab has open, that tab turns read-only the same way
within a moment; what it sent in that moment is dropped. After Reload the tab runs 0.20 and edits normally. A 0.19
tab with offline copies on (the installed app) keeps its editor's deletion of the group as an unsent edit; 0.20
keeps that edit as a recovery item ("Made by an older version of the app") instead of sending it. A row template
body with columns refuses saves from a 0.19 tab (409SCHEMA_OUTDATED). - Proxies: the collaboration socket URL now carries a query string (
/collab?schema=2). Path rules such as
Caddy's or nginx'slocation /collabneed nothing; a rule that compares the whole request URI must allow it. A
proxy that strips the query makes every 0.20 tab look like 0.19: read-only on pages with columns. - Migration 0061 (the only one) adds
pages.share_include_charts(boolean, default false),pages.share_charts_by
(uuid, references users, on delete set null) andpages.share_chart_sources(jsonb, the approved chart sources).
Additive; every existing link keeps its behaviour (charts off) until a manager turns them on in the share dialog.
Chart numbers on public pages can be up to 10 minutes old (the public render cache); the switch and the person's
membership apply at once. - No re-index: the new
find_contextrules work at query time. Answers to Korean questions can be ordered
differently from 0.19; answers cached in memory are dropped by the restart. - Going back to 0.19.1 should need no database restore: 0.19 does not read the three new columns (0061 stays
applied); starting 0.19.1 on a database with 0061 was not tried. But
0.19 does not know columns and has no guard: its editor deletes a group with its content as soon as someone opens
the page; do not go back once columns are in use. A page whose link showed charts, published again while 0.19
runs, keeps the chart setting on for its new link once 0.20 runs again (KNOWN-ISSUES SHARE-9). Not checked beyond
that. - Semantic search:
EMBEDDING_QUERY_PREFIXandEMBEDDING_PASSAGE_PREFIXare empty by default, so nothing
changes. Setting, changing or removing one re-embeds every section atEMBEDDING_REQUESTS_PER_MINUTE; until that
finishes, sections without a new vector are found by their words only (docs/OPERATIONS.md). - API:
GET /api/pages/:id/sync-check?schema=N(new query) answersneedswhen N is below the server's document
schema;PATCH /api/collection-row-templates/:idtakesschema(409SCHEMA_OUTDATED); page bodies with columns
carry<!-- inkling:columns -->marker lines in every Markdown format;PATCH /api/pages/:id/sharetakes
includeChartsandapproveChartSources,ShareStatusDTOandPublicPageDTOgain chart fields (docs/API.md,
"v0.20.0 additions").
Added
- Columns (docs/adr/2420-* .. 2424-*). Put blocks side by side:
/2단or/3단in the slash menu (English "2
columns", "3 columns";/columnsand/단find them too) turns an empty line into a group of empty columns with
the caret in the first one (on a line with text the group goes below it). Any ordinary block goes in a column:
text, headings, lists, to-dos, images, code, callouts, toggles, tables, embeds. Drag the boundary between two
columns to change their widths (each keeps at least 15%), double-click it to make them equal. The block menu (⋮⋮)
of a block in a column adds Add column (up to four), Delete this column (its blocks move to the column on
its left) and Unwrap columns (everything back as ordinary blocks, in order). Nothing tidies a group on its
own: an empty column stays until you delete it; Backspace in a group whose columns are all empty removes it.
Below 640 px of width (phones, a side peek) the columns stack in order. Public links, presentation mode, PDF and
print, page embeds and the offline copy show the columns, and the image viewer opens on images inside them;
agents, Markdown downloads, zip export/import and vault sync write them as<!-- inkling:columns -->/
<!-- inkling:column -->/<!-- /inkling:columns -->lines. A heading inside a column is not a section.
Written against @blocknote/core's public API; BlockNote's GPL multi-column package is not used. No new
dependency. - Charts on public links (docs/adr/2440-* .. 2444-*). A public link can now show the page's charts: the share
dialog says "N charts on this page do not show on the public link" and offers Show charts on the public page
(owners and admins; off by default, per link, audited). When it is on, each chart's labels and numbers are
published — worked out with the access of the person who turned it on, while they are a member of the workspace,
and only for the databases and queries the charts used when it was turned on (a chart added later over another
database waits: "N newly added charts are not public yet", Publish these charts too) — never the rows behind
them, the database's or view's name, or any id or query text. Public pages draw charts with the app's own chart
component (also in presentation mode, print and "Save as PDF"; scaled to the paper), with the table underneath for
screen readers, readers without scripts and the Markdown download. A chart inside a column stands in that column
(its title and table too). The chart code loads only on pages that have a chart. Without the switch, a folder
link's charts of its own databases are now drawn as charts instead of tables; everything else is as before. - Document schema version (docs/adr/2425-*). Every client says on its collaboration socket which document
schema it knows (0.20 = 2; none = 0.19 and older = 1). On a page that holds a node type the client does not
know, its connection is read-only, from the start or from the moment such a node arrives, so an older editor
never deletes what it cannot show. 0.20 shows "This page has content that only a newer version of the app can
edit. Reload to update." when that happens to it in a later release. - Role prefixes for embedding models:
EMBEDDING_QUERY_PREFIXandEMBEDDING_PASSAGE_PREFIX(optional, empty
by default) for models that expect them, such as the e5 family ("query: ","passage: "). Changing either one
re-embeds every section, as a model change does (docs/adr/2404-*). - Developers: a recall evaluation set for
find_context(32 questions written the way people remember pages, over
three workspaces) with page@1, page@3 and page MRR inapps/server/scripts/context-bench.tsand
context-tune.ts(docs/adr/2400-*). - Korean guides:
deploy/DEPLOY.ko.md,docs/OPERATIONS.ko.md,docs/BACKUP.ko.md,docs/MCP.ko.md,
docs/QUERY.ko.md,docs/TEMPLATES.ko.md,docs/ARCHITECTURE.ko.md,docs/WEBHOOKS.ko.md,docs/VAULT-SYNC.ko.md,
docs/PLUGINS.ko.md,docs/API.ko.md,docs/KNOWN-ISSUES.ko.md,docs/PERFORMANCE.ko.mdanddocs/ROADMAP.ko.md,
with the same sections, anchors and code blocks as the English files. The Korean README and user guide link to them;
each English file links to its Korean one.
Changed
- find_context finds pages people describe with a longer word than the page uses (docs/adr/2401-* .. 2403-*):
a Korean query word of three or more syllables also counts, with a discount, when its shorter form (the word
without the last syllable, e.g. 택배함 → 택배, 회의록 → 회의) is in a page title or heading. Sections that miss the
question's clearly rarest word rank a little lower (×0.75), and words that appear only in titles now carry their
real weight instead of the "unknown word" minimum. Query time only: no migration, no re-index. On the new recall
evaluation (32 questions over three workspaces): tuning (dev) questions page@3 0.875 → 1.000 (own workspaces) and
0.813 → 0.938 (with a 5,000-page workspace); held-out (test) questions page@3 unchanged at 0.938 in both, page@1
0.750 → 0.813 and page MRR 0.844 → 0.885 with the large workspace, unchanged on own workspaces. Existing questions
unchanged or better except one test question that loses its second relevant section; latency unchanged. - patch_section on a section that holds columns keeps the group: sent back unchanged it stays as it is (same
block ids), with any change inside it is replaced whole (the blocks in it get new ids); it is never merged with
an ordinary block.update_pagereplace of a page with columns keeps the blocks around the group instead of
rewriting the page (docs/adr/2424-*). - find_context's section text writes columns with read_page's marker lines, without indenting the blocks
inside, so a section copied from find_context into patch_section keeps its group (docs/adr/2424-*). - Every MCP tool states all four annotation hints (
readOnlyHint,destructiveHint,idempotentHint,
openWorldHint) from one table, so clients no longer fall back to the spec's defaults ("may be destructive",
"open world") for tools that only add (docs/adr/2460-*). Before, 21 of 48 tools were marked read-only and 11 had a
destructive hint. Now 20 are read-only; of the writes, 11 are destructive (includingmore_tools, which can run
any hidden tool) and 18 only add or flip a flag; none is open world. Two verdicts changed:catch_upis no longer
read-only (withoutpeekit moves the connection's "last catch_up" marker; read-only connections still call it),
andupdate_rowis destructive (it overwrites values;nullclears).more_tools(tool=…)prints the tool's true
hints after its name (readOnly,destructive,idempotent). tools/list leaves out hints equal to the MCP
defaults (a read-only tool listsreadOnlyHintandopenWorldHint; a write tooldestructiveHint,openWorldHint
andidempotentHintwhen true). Tool names, descriptions and schemas are unchanged. - Project site (
site/) rewritten for 0.20. The first screen is about agents and MCP: quick start, connecting,
realfind_contextandpatch_sectionoutput with the measured numbers, suggestions and ranges. The language
switch goes to a page per language and works fromfile://too. The version is read from
apps/server/package.jsonat build time.llms.txtand links to each document's Markdown source. 0.20
screenshots and a new intro video.
Fixed
- Public links: a callout shows as in the editor, its type's icon and then the text, with line breaks, inline code,
bold and links flowing inside the tinted box. Since 0.12.0 the text took the icon's place and stood in narrow
side-by-side columns that ran out of the box (and widened the page on phones) (docs/adr/2387-*). - Public links: each callout type has its own tint again (note, tip, warning, danger, info), not the note blue for
all (docs/adr/2387-*). - Public links: text colour and background colour, on words, whole blocks and table cells, show as in the editor in
the light and dark themes; printed or saved as PDF they use the light colours (docs/adr/2387-*). - A section patch that the server refuses no longer shows up as an unhandled promise rejection in the server log
(gatedTransact, docs/adr/2424-*). - Documentation: deploy/DEPLOY.md gives the language menu as Settings › Appearance › Language and the sign-in link
as "Forgot your password?", writes every menu path with ›, says plainly why plain HTTP (3-A) is for testing only,
and tiesdeploy/local.sh's missing setup link to an image older than 0.17 instead of an unpublished one.
docs/BACKUP.md namesSHA256SUMSas the file a tamperer would have to rewrite. docs/OPERATIONS.md points at the
BACKUP.md sections that exist, giveseffective_cache_sizeas at mostPG_MEM_LIMITminusshared_buffers(as
both example columns already were), says that edits made offline are kept on the device when offline copies are
on, that it is a new VAPID key (notAPP_SECRET_KEY) that voids push subscriptions, who a "manager" of public
charts is (a workspace owner or admin), and thatdeploy/local.shmakes a hexPOSTGRES_PASSWORDand a base64
APP_SECRET_KEY. The user guide and docs/MCP.md say what the untrusted-content marking does not do: it helps an
agent tell notes from instructions but does not stop an injection by itself; read-only connections, ranges, edit
locks, suggestions and version history are what limit an agent. The Korean files carry the same fixes.
Performance
- Web bundle against 0.19.1 (365b664), both built from
git archiveand measured back to back: entryindex-*.js
447,198 → 449,412 B (122,995 → 123,356 B gzip); entry plus modulepreload 1,374,102 → 1,381,039 B (404,604 →
406,213 B gzip); entry CSS 19,717 → 20,944 B gzip (column, public callout and colour styles); the column code sits
in the editor chunk (CollabEditor, 126,070 → 130,001 B gzip, after the chart adapter left it); precache 107 → 109
entries, +36,890 B (docs/PERFORMANCE.md). - Public charts (docs/adr/2442-*): a public page with charts loads
PublicChartMount(1,392 B gzip) and its CSS
(226 B), the chart adapter (961 B) andChartRender(50,822 B, the app's chart chunk) only when the page has a
chart; a page without charts requests none of them. The share dialog's chart count of a folder link with 300 large
pages that all hold a chart takes about 0.36 s (26 ms with one chart page) (docs/PERFORMANCE.md). - MCP tools/list with the annotations (
scripts/mcp-tools-list-cost.ts, read-write connection, no database): full
48 tools 51,059 → 52,932 characters, ~12,777 → ~13,245 tokens (+468, +3.7%); core 32 tools 30,093 → 31,391
characters, ~7,533 → ~7,857 tokens (+324, +4.3%). Listing all four hints on every tool would have cost +960 / +641
tokens. Server instructions unchanged (1,965 characters, ~492 tokens) (docs/PERFORMANCE.md). find_contextlatency with the new word rules is unchanged (p50 36.2 → 34.6 ms, p95 102.2 → 90.8 ms on 15.8k
sections, interleaved runs). The document schema guard costs current clients one comparison per message; on the
server a keystroke costs nothing measurable and a new block in a 2,000-block group about 50 µs
(docs/PERFORMANCE.md).- Measured and not adopted: semantic search with
multilingual-e5-smalland the role prefixes above, fused by the
0.20 code as it is. With 5,000 extra pages, page@1 on the held-out questions went 0.848 → 0.939 but on the tuning
questions 0.867 → 0.844; on the private check 0.944 → 0.917 (page@3 0.972 → 1.000). Answers took 1.7× (private) to
7.5× (benchmark) the tokens, and each question 33–40 ms more at p50. Nothing changes in the code or the defaults
(docs/PERFORMANCE.md, "Rejected / no effect").