Research pages and notes

Writing the page

A page’s body is written in place: click into it and type. The page saves
itself about a second after you stop, and again when you leave; the status
beside the body says Editing, Saving and Saved, so there is no save
button to forget. Closing the tab, switching away from it or navigating
elsewhere sends what is unsaved as the page goes. That last save is sent,
not confirmed: if someone else saved the page in the meantime it is refused
like any other, and you see their version the next time you open the page. If you can only read or comment on a page, you see it
rendered instead, with the comment threads under each block.

Everything you write is a block: a paragraph, a heading, a callout, a
quote, a code block, a list, a table, a divider, an image, a file, or one
of the blocks that name something on chain (a transaction, a block, an
address, a live value, a price series, a query result, a citation; see
Blocks that name something on chain below). A block is the unit a
comment attaches to and a version is kept for,
so one claim per block reads well and reviews well. Three blocks hold other
blocks: a toggle folds a section away behind its summary line, and
columns put blocks side by side in two or three columns. The keys:

Enter starts a new block. Shift-Enter starts a second paragraph in
the same block, for when two paragraphs are one claim. In a toggle’s
summary, Enter opens the section; on an empty last list item it leaves
the list.
Backspace at the start of a block joins it to the one above. At the
start of a heading, a callout, a quote, a toggle’s summary or a list’s
first item it turns the block back into plain text.
Tab and Shift-Tab indent and outdent a list item; in a table they
move between cells, and past the last cell Tab adds a row.
Alt-Up and Alt-Down move the block. So does dragging its handle.
Cmd-B, Cmd-I, Cmd-K for bold, italic and a link on the selection;
Cmd-Z undoes, across blocks and across saves. Escape leaves the editor.

Type / at the start of a line, or after a space, for the list of blocks:
text, the three heading levels, the four callout tones by name, the three
lists, a toggle, a quote, code, a table, two or three columns, an image, a
file, a divider, and then a transaction, a block, an address, a live value,
a price series, a query result and a citation, and last a derived value
(a figure computed over a dataset, cited in the sentence; see Putting a
reference in without leaving the page below). Keep typing to narrow it,
arrow keys to choose, Enter to insert, Escape to close. The markdown you
would type anyway also works: # , ## and ### make a heading, > a
finding, three backticks a code block, --- a divider, - a bulleted
list, 1. a numbered one and [] a to-do list.

Three more triggers put a reference in from the prose: @ for a page
or something already on chain in your space, [[ for a page by title
(and a new page when none matches), and a pasted hash for what it can
become. They are described below, under Putting a reference in without
leaving the page.

A list is one block however many items it has: nest an item with Tab,
tick a to-do by its box, and switch a list between bulleted, numbered and
to-do from its handle. A table starts with a header row and two
columns; its handle adds and removes rows and columns at the end. A
toggle is a summary line with a section under it; the caret in the
margin folds the section away for you without changing the page for
anyone else. Columns hold blocks side by side (stacked on a phone);
the count is set from the columns’ handle, and going from three to two
moves the third column’s blocks into the second. An image or a
file block takes a file from your computer (PNG, JPEG, GIF or WebP for
an image; those plus PDF, CSV, text or zip for a file), up to your plan’s
size limit (10 MB on Free, 100 MB on a paid plan), with a caption under
it; the file is stored with the page and a reader downloads it from there.

Each block has a handle in the left margin: it appears when you hover
the block, and on a touch screen it stays on the block you are in. Click it
for the block’s settings: heading level, callout tone, code language, a
list’s style, a table’s rows and columns, the column count, a block’s file,
the hash, number, address, citation or query a chain block names; then
Duplicate, Comment and Delete. A settings
change is saved and versioned like any other edit. Delete asks nothing,
because Cmd-Z brings the block back, and the block’s comments and history
are kept with the page rather than thrown away. Deleting a toggle or
columns deletes what they hold.

Two rules keep a page honest under autosave:

A block you empty is deleted, unless someone has commented on it. Then
it keeps its last words and says kept: has comments, because the thread
is about those words. Delete it from its handle if you mean to remove it.
If the page changed elsewhere while you were writing (a colleague, the
API, a tool appending a block), your save is refused rather than
overwriting theirs, and a bar offers Reload to take their version or
Keep mine to combine the two, block by block: a block only you changed
keeps your words, a block only they changed keeps theirs, a block they
added stays, and a block you both changed is kept twice, theirs first,
then a Conflict callout, then yours as a new block, for you to settle.
Nothing is lost either way, and the status line says how many blocks
were changed on both sides.

Verified against chain data

A page can claim to have been checked: verified against chain data as of block
25,600,000. The claim is only worth something because it can be taken
away.

Every night the platform re-derives everything a page rests on: each cited
value from its log, and each cited aggregate by re-running its query.
Decoding fixes, corrected token decimals and reorg repairs all change what a
log says after the fact, and a backfill or a repaired reorg can move an
aggregate. When either stops agreeing, the page stops being verified,
says which claim moved, and emails whoever owns it. Silent expiry would be
worse than no badge at all: the author would go on believing a claim the
platform quietly withdrew.

The two reasons are stated separately, because they are different facts about
a page:

a cited value no longer matches chain data — the log itself now reads
differently
a cited aggregate re-derives to a different answer — the query still runs,
and the number it returns has changed

A dataset being rebuilt is not, by itself, a reason to withdraw a badge.
The Aave health panel gains a cross-section every month and the Maker vault
panel rebuilds monthly; expiring every page resting on them each month would
teach you to re-verify without reading. What is compared is the answer, so
a panel that rebuilds without changing what your page claims leaves the badge
alone.

A check that could not run at all — the warehouse unreachable — is recorded as
unresolved and does not expire anything. “We could not check” is not
“this is wrong”, and the page still shows the block it was verified against.

Two rules keep the badge honest:

You can’t verify a page whose values have already drifted. That would be
a lie at the moment of creation.
Verifying is an owner’s decision, like publishing. It’s a claim made on
behalf of the space, not a personal note.

The workspace index lists what expired, with the reason, beside the pages
touched most recently and the pages waiting on a reader. A verified page
nobody can list is a badge, not a guarantee; an expired one nobody can list
is worse.

Putting a reference in without leaving the page

A research page refers to things: other pages, transactions, one decoded
value of a log, an aggregate over a dataset. Each of these used to mean
leaving the page (the citation picker was a page of its own, off the
explorer), or knowing an id ({{page:12}}, {{derived:3}}). Four
triggers, typed where the reference goes, do it in place. Every one opens
a list at the cursor: arrow keys move, Enter or Tab chooses, Escape keeps
what you typed as text, and a click chooses too.

@ and a few letters lists the pages of your space that match (by
title, and by what their blocks say, the same search as the bar’s), and
under them the things already on chain in the space: the transactions,
blocks and price series on this page, and the items saved to any page of
the space. A page becomes a mention of it (the chip with its title;
see Citing another page). A transaction, a block or a price series
becomes the matching block with the same settings, so nothing already on
the page is typed in twice.
[[ and a title lists the pages that match. When none matches what you
typed, the last row is Create page “…”: it makes the page in the
current project and puts the mention in at once, so a reference to work
you have not written yet is a real page from the first draft. A ]] you
typed after the title is replaced along with it.
A hash. Paste or type 0x and 40 hex characters and the list offers
an address block; 64 characters, a transaction block or Cite a
field; # and a block number, a block. The classification is the
explorer’s search field’s: 40 is an address, 64 a transaction hash (or a
topic0, which only the chain can tell apart), digits a block number.
Nothing is offered at 41 to 63 characters: that is you still typing.
Choosing replaces the hex with the block; Escape leaves it as text.
Cite a field lists every decoded field of the transaction’s logs
(event and field, with the value, grouped by log) and, on choosing one,
creates the citation and puts its live-value chip where the hash was,
in the sentence. The same list opens from a transaction block’s handle
(Cite a field on its settings); the chip then goes into a new text
block under the transaction. A transaction the page has already fetched
is decoded from its snapshot, with the labels the platform knows, so the
list costs no warehouse query; one nobody has fetched is read from the
warehouse. A transaction whose logs are not in the decoded event set
says so and offers nothing: there is no named field to point at.
Derived value (/derived in the slash menu, or Build a derived
value on a live value block’s settings) opens the builder: a dataset
from the catalogue, its protocols, a date window, the aggregate (count,
sum, avg, min, max) and the column. Preview runs the query and shows
the value and the row count before anything is recorded; Insert as
live value records the citation (the spec, the answer and a hash of
both, exactly what the API and the MCP tool record) and puts the chip at
the cursor, or into the live value block it was opened from. The nightly
check re-runs the query like any other derived citation and flags a moved
answer in place.

A citation or a mention made this way lands in the project’s space,
whatever space you have active, because that is the space the page reads
its tokens from. Every one of these is an ordinary token in the row
({{cite:N}}, {{derived:N}}, {{page:ID}}): the export, the API, the
comments and the history see exactly what they would have seen had you
typed the token.

Tags on the page form complete as you type them, from the tags already
in use in the space, most used first; chain:eth completes to
chain:ethereum. The field is still the comma-separated list it was, so
a tag nobody has used yet is typed as before.

Citing another page

Write {{page:ID}} in any block, or choose the page from @ or [[,
and it becomes a link to that page, and, more usefully, the page you cited
grows a “Cited by” entry pointing back at yours.

That is the question a research platform should be able to answer: what rests
on this? A plain text mention can’t answer it, because nothing indexes it and
a rename breaks it. A reference is a row, so renaming the page keeps every link
and every backlink intact.

Two rules the graph keeps:

References stay inside a space. A mention of a page you can’t open shows
[page not available], never its name: a mention must not become a way to
learn what other teams are working on.
A page can’t cite itself. A self-reference in a “what rests on this”
panel is noise.

The graph follows your prose: remove the mention and the reference goes with
it. Exports name the page and its reference (USDC mechanics (RES-12)), since
a link means nothing once the file leaves the platform.

Taking work out, and bringing it in

Three export formats, from the page’s Export menu:

Markdown: the page with every cited value as a numbered footnote
carrying its full transaction hash. It stands on its own, without the
platform, so a reader can verify a figure rather than take it on trust.
Bundle (zip): the markdown plus citations.csv, one row per cited
value, and a manifest saying what each file is. Someone checking your
arithmetic opens a spreadsheet instead of re-querying a chain.
Citations CSV: just that table, when the prose isn’t what you need.

A stale figure never looks like a live one. A value that no longer matches
chain data is marked NO LONGER MATCHES in its footnote, carries
mismatch in the CSV, and raises a warning in the manifest. A citation from a
space you can’t open renders as [missing citation] rather than its value:
an export must not become a way to read work you don’t have access to.

For PDF, print the page from your browser and save as PDF. A browser does that
better than a server-side renderer we would have to keep alive.

Import takes markdown the other way: paste it and it becomes blocks.
Headings, code fences, dividers, callouts, quotes, lists and tables come
back as themselves: a > **Caveat:** … block exported from here re-imports
as a caveat, so the weight you gave a statement survives the round trip,
and a plain > quotation comes back as a quote. A toggle exports as a
heading plus its section and columns as their blocks in order, each fenced
by an HTML comment that no markdown reader shows (,
, ); the import reads those fences and
rebuilds the same nesting, so a page exported from here and imported again
keeps its shape. Images and files export as links (files/…) and the zip
bundle carries the files at those paths; an import of pasted markdown
keeps such a link as prose, since text is all a paste carries. Anything
else the editor doesn’t model is imported as plain prose rather than
dropped: losing a paragraph on import would be worse than importing it
plainly. One import takes up to 500 KB of markdown and up to 1,000 blocks;
past either, import it in parts. Nothing is imported when any block is
refused (a paragraph over 20,000 characters, say): the import is all or
nothing.

Finding a page

The search field in the bar finds research by its title and by what its
blocks say. Type a word, or the start of one: liq finds liquidation and
liquidity, and every word you type has to match. Under Pages are the pages
whose title or description matched; under Blocks, the passages that did,
with the match marked, each opening the page at that block. The last entry,
All research results, opens the long form at Research → Search, which
lists every match with its passages. ⌘K (Ctrl+K) focuses the field from
anywhere.

Only pages in spaces you belong to are searched, and never a colleague’s
private draft: the search applies the same visibility rule as the tree, the
board and the tag filter, in the query itself. A hash, an address or a block
number typed into the same field goes to the explorer instead.

The index is Postgres full text, kept by the database on every write, so a
block saved a second ago is already findable. “Ask your research” is the
other way in: it answers a question from the pages the same search finds.

Structure

Projects hold folders and pages; pages hold saved transactions and blocks. A
project belongs to a space. Your personal space by default, or a shared one
for a team. Access follows the space, so adding someone to a space gives them
everything in it.

Moving and renaming

Drag a page in the Contents tree onto a folder to move it there, or onto the
project root row that appears while you drag to take it out of its folder.
On the pipeline board, drag a card into another column to change its stage:
the same change as the Stage field on the page’s edit form, with the same
rule (editors and owners only). The tree and the board come back from the
server after each drop, so the counts and the order are never guessed.

Names are edited where they are shown. Hover a page or folder in the tree
and click the pencil (or reach it with Tab and press Enter), or click the
pencil beside the page’s title: type, then Enter or leaving the field saves,
Escape puts the old name back. A name left empty is not sent.

A filter is tags, a name and a sort, and a view keeps all three

The filter in the Contents panel narrows the project by tags (each one
added narrows further), by a word the page’s name contains, and sorts the
result most recent first or by name. Filtering replaces the folder tree with
a flat list of matches from the whole project. That is on purpose: a filter
asks “where is this work”, not “where does it sit in the hierarchy”, and
the answer is often spread across folders that were organised for a
different reason. Each match shows the folder it lives in, and clearing the
filter brings the tree back exactly as it was.

Save view keeps the filter as it stands, all three parts, under a name in
the Contents panel. Choosing the view applies them again: the same tags, the
same word, the same order. A view is yours until you share it with the space,
and it belongs to the space of the project you saved it on, whichever space is
active. Only you can share it, take it back or remove it; a colleague who
relies on your shared view still cannot change it.

Properties: the columns your space decides on

A page’s stage, owner and verification are the platform’s facts about it.
The rest — who is reviewing it, which protocol it concerns, the date it is
due, the page it depends on — is yours to decide, and that is what a
property is. A space owner or editor defines them once, on the space’s
page under Page properties: a name and a kind. Six kinds: text, a number,
a date, a select with a fixed list of options, a person (a member of
the space) and a relation (another page in the space). The name and the
options can change later; the kind cannot, because the values already
written were read under it. Removing a property removes every value pages
held for it.

Every page in the space then shows the properties above its body. Click a
value to change it: a select or a member list opens, a date or a number
takes the keyboard, and a relation is found by typing part of a page’s
name and choosing from the matches. A change, Enter or leaving the field
saves it; Escape puts the old value back. A value the kind cannot read
(“heavy” for a number, an option the select does not offer) is refused
with the reason and nothing changes. Anyone who can edit the page can set
its properties; a viewer or a commenter sees them and cannot.

Pages as a table

Table on a project shows its pages as rows, one column per property.
Columns chooses which; a column’s heading sorts by it (once ascending,
again descending: a number as a number, a person or a related page by
name, pages without a value last), and the filter line narrows the rows by
a value per column, together with a word the name contains. A cell is
edited the same way as on the page. The pipeline board can be grouped by
any select property instead of by stage: one column per option and a
last one for the pages without a value, and dragging a card across sets
the value the way it sets the stage.

A view saves all of this: the property filters, the sort, the columns of a
table, the grouping of a board. Choosing a saved view opens the surface it
was saved from, with the same rows in the same order.

In an export, the page’s properties travel as front matter at the top of
the markdown (a person as their email, a related page as its reference)
and are listed in the bundle’s README; an import reads that front matter
back and sets each property the space has, skipping names it does not.

Templates

A new page can start from a template: the three the platform provides
(New analysis, Dataset review, Event study) and any your space has
saved. New page from template on a project lists them; the new-page form
has the same choice under Start from.

To keep a page’s structure for the next one, open the Page menu on the
page and choose Save as template. The page’s blocks, as they are at that
moment, become a template of the page’s space, offered to everyone in it.
The page itself is unchanged, and the template does not follow later edits to
the page. Import markdown is on the same menu.

What a project rests on

A project header says how many of its pages the space currently stands behind,
how many have expired, and when anything underneath them was last checked.

That last number is when the check ran, not when the warehouse last
refreshed. A dataset can rebuild without changing anything your pages claim, so
a refresh date would tell you nothing about whether to trust the work.

Each dataset page lists the pages in your space resting on it, so
“what breaks if this dataset is corrected?” has an answer. A page rests on a
dataset because it cites an aggregate from it: nothing to maintain by hand,
because the citation tokens in your prose are indexed the moment a block is
saved, whichever way it was written (the editor, an import, the API).

Blocks that name something on chain

Seven blocks put a datapoint into the prose rather than a number typed by
hand. Each stores what it names (a hash, a number, an address, a
citation, a query) and never a copy of the data: the thing itself is
fetched by a job, kept as a snapshot, and shown with the block height
the fetch saw. Every one of them ends with a chip: Fetched or Verified,
as of block N, checked on a date, and holds until a date thirty days
on (the page’s verification window). A block that has not been fetched says
Not fetched yet with a Fetch now button; nothing is ever fetched
while the page draws, so a page with twenty transactions opens at once. A
fetch that failed says why, beside the last good data if there was any.

Type / and the block’s name, then open its handle and type in what it
names; Apply checks the shape first, and the server checks it again. An
unusable block is not saved: it says what it needs and waits. Or paste the
hash into the prose and choose the block from what it offers, or pick the
thing from @ (see Putting a reference in without leaving the page).

Transaction (/transaction): a hash and a chain. Shows the transaction
as the explorer does, compactly (the flow, the overview and the decoded
event log, without the input-data and advanced panels), with Open in
explorer and Cite a field. Hover a field for the same local
annotations a saved card had; they belong to the block.
Block (/block): a block number and a chain, shown as the explorer’s
block header, compactly, with annotations on its hashes and miner.
Address (/address): the address, the label the platform knows for
it, how busy it has been lately (the logs it sent, received or emitted
over the last 50,000 blocks of the warehouse, stated with the window) and
the space’s global notes on it. No balance: the platform reads logs,
not balances, and it never estimates one.
Live value (/live): a {{cite:N}} or {{derived:N}} token, shown as
one large figure with its source and the block it was read at. The number
is the citation’s, never typed here; Re-derive now asks the nightly
check to read it again, once a minute per person.
Price series (/price): a pool, a venue, a period and a window, drawn
from the same series the finder and the citations read, on the price
chart. This is the old chart block, generalised: a chart names its
venue now. Pin it to a block and the picture stops moving, so the page’s
picture and its verification badge cannot disagree.
Data charts (/liquidations, /absorptions, /health, /timeline):
what the tracking module computes, on the page. A liquidations chart
is a daily or weekly count and volume for Aave V3, Spark or Morpho Blue
(Morpho counts only: a dollar figure would need every market’s oracle);
an absorptions chart the same for Compound v3, in Compound’s own
figures; a health factor distribution is one cross-section’s
accounts by health-factor band for Aave V3 or Spark, at a block you name
or the latest; timeline events puts the timeline’s events on a date
axis. Any time-axis chart can carry the timeline’s events as markers
(Timeline events: yes on its sheet). Every choice on the sheet is a
pick from a list, never a typed protocol name, and the sheet shows only
the fields the chosen source takes. Each chart is read through the same
report the tracking page reads, by a job, and pinned to the block the
fetch saw: a histogram to its cross-section’s block, a series to the
warehouse head. Under the picture: the query in words, the hash of the
drawn data, and Open the data, which goes to the tracking page. The
camera icon saves a PNG that carries the title, the source line with the
block height, and the hash, so a figure pasted into a paper still says
what it is.
Query result (/query): a dataset from the catalogue, filters as the
data request form writes them, the columns and a row limit of at most
1. Shows the rows as a table with the row count, the hash of the rows
  shown (so a reader with the CSV can check them), and the way to request
  the full export at /data.
Citation (/citation): a dataset or derived citation by its hash,
with its short label and the public resolver link, for a bibliography.

In an export, each of these becomes what it names and the state it was
last checked in, in words; a query result’s rows travel in the bundle
under data/, and citations.csv lists every one of them beside the
inline citations, with its kind and its block height. A chart also exports
the spec that cites the rows behind it (Cite it with:, the body
POST /api/v1/citations takes), and the bundle’s citations.csv carries
that spec and the hash of the drawn data on the chart’s row. The same
series is on the API at GET /api/v1/charts/{source} with the chart’s
params as the query string, for a key or for your own session.

The saved transactions and blocks a page had as cards under the body are
now these blocks, appended at the end of the page with their notes as
captions and their annotations moved with them (the one-off
research:migrate_saved_transactions task). The Add Item dialog still
saves a card for now; @ lists every saved item of the space, so a card
saved from the explorer is one keystroke from becoming a block on the page.

History

Every save that changes the page keeps a version of the whole page. Open
History from the page to see them, newest first, each with who saved,
when, and one line on what changed: how many blocks were added, removed or
edited, and the first changed block’s kind and opening words. Saves you make
within five minutes of one another fold into one version, so the list is the
sequence of sittings rather than of pauses; a colleague’s save is always its
own version.

Name this version, on the page menu, keeps the page as it stands under a
name: sent to review, as submitted. A named version is never folded
into by later saves.

Open a version to read it as it was. Choose one version in the older
column and one in the newer column and Compare the two to see what
changed block by block: the older state on the left, the newer on the right.
Within a paragraph the words that went are struck out and the words that
came are underlined; a chart’s query is compared key by key, so a changed
date range shows as the two dates side by side; a block on one side only was
added or removed and is shown whole. The page now is offered as a state to
compare whenever it differs from the newest version.

Restore puts the whole page back to a version, through the same save the
editor makes, and records what it replaced first as a version of its own,
named Restored from the time. Nothing is deleted by restoring: undoing a
restore is one more restore. An image or file whose file has since been
deleted cannot come back; the notice says how many blocks were left out.

A restore puts back the page you saw. If someone saves the page after you
opened its history, the restore is refused rather than overwriting what they
wrote: open the history again, check the newest version, and restore if you
still want to.

The block by block list under the versions is the older record: each
block as it stood before an edit, with a restore that puts that one block
back. A block deleted since cannot be put back on its own (there is nowhere
for it to go); restore a page version that holds it instead. Both records
are kept for the space’s history window, which is the best plan among the
space’s members, whoever is reading: a student on the free plan in a
department’s paid space sees the department’s window. The history lists only
what falls inside it, a version past it can no longer be opened or restored,
and the nightly retention sweep purges it by the same number, so what you
are shown is exactly what is kept.

Taking a page out

Three formats, from the Export menu:

Markdown — the prose, with citations as numbered footnotes carrying full
transaction hashes. Stands on its own.
Bundle (zip) — the markdown, citations.csv (one row per cited value),
and a data/ folder holding the rows behind each cited aggregate.
Citations CSV — just the rows.

A cited aggregate’s rows are exported up to 25,000 rows. Past that the file
is still written, and says so: it names the dataset and filters and points at
Data Downloads, which runs large queries as a job. A truncated series that
looks complete is the thing worth avoiding — the file tells you it is not
there rather than handing you nine-tenths of it.

Verification state travels with the document. A value that no longer matches
the chain is marked NO LONGER MATCHES in the footnotes, mismatch in the
CSV, and called out in the manifest. A citation from another space renders as
[missing citation] and never as its value.

Two things we deliberately do not generate

PDF. Use your browser’s Print → Save as PDF. It is better at this than a
server-side renderer would be, and there is nothing to keep alive.

Chart images, in the bundle. The charts render in your browser, so putting
them in a server-built zip would mean running a headless browser on the app
host to take a photograph of a page. That host has roughly 300 MB free and is
already swapping; a browser does not fit, and the value is a picture of
something the reader can already open and interact with. Use the camera icon
on the chart itself — it saves exactly what is plotted, styled the same way.

The same reasoning governs per-page social-card images: they need the same
browser for the same reason. Published pages carry title, description and
Open Graph metadata, so a link still previews with its own title and summary;
the picture is the site’s card rather than a rendering of the page.

A referee with no account can be sent a review link for one unpublished
page. Create it from the page, optionally noting who it is for.

What that link is, precisely:

One page. Not the project, not the space, not the page beside it. There
is nothing to walk sideways into.
Time-limited. Two weeks by default, ninety days at the most. You do not
have to remember to close it.
Revocable, immediately, and the page lists what you have issued, whether
each is live, and how many times it was opened — so you can see whether the
review ever happened.

It is not an account. There is nothing for the reviewer to sign up for and
no password anywhere. Revoked, expired and never-existed links all show the
same message: which of the three it was is not a stranger’s business.

Once a page is published, review links are no longer offered — anyone with the
public link can read it, so a review link would be theatre.

Discussion, and who else is reading

Comments come in two shapes:

On a block — a note about one paragraph, figure or claim. It stays next
to the thing it is about, in the rail beside the page, so an objection cannot
drift onto the wrong sentence. Start one from the block’s handle, or add to a
thread where it sits.
On the page — the “is this ready to publish?” conversation, under the
block threads in the same rail. It resolves like any other thread.

The rail also holds the page’s properties, what the page rests on and what
cites it, and the review links. On a phone the rail is a sheet: the
Comments button at the foot of the screen opens it, and the block
handle’s Comment opens it on that block’s thread.

On a phone

Everything above works on a phone; three things look different:

The row of buttons under the title becomes one Page menu with the same
actions in it. The verification chip stays under the title.
The block handle is always drawn on the block your cursor is in, since
there is no pointer to hover with, and holding a finger on a block
opens its settings too. The settings sheet and the block menu (the /
menu) take the full width of the screen.
The rail of properties, comments and references is the sheet described
above, opened from the Comments button.

Both are searchable. A decision argued out in a thread is findable by what was
said in it, not only by the page it sits on — and a comment on a page you
cannot open never appears in your results, the same as the page itself.

Posting, resolving, reopening or deleting a comment never reloads the page:
the thread redraws in place, and everyone else with the page open sees it
change within a moment, in the rail if they are editing and under the block
if they are reading. A mention or a reply to you lands in the bell in the
top bar the same way, without a reload.

When someone else has the page open, their initials appear beside the title.
That is a heartbeat, not a connection: each reader says “I am here” every
few seconds, and stops appearing about a minute after they stop. A closed
laptop, a killed tab and a lost network all clear themselves — nothing is left
behind claiming somebody is reading when nobody is. While the page is open
the heartbeat also travels over the page’s live connection, so someone
arriving or leaving by a link shows up at once; the minute’s wait is only
for a browser that closed without saying goodbye.

Two levels of note

Local annotation: what a value means in this transaction or block on
this page. It lives with the transaction or block block (or the saved
card, for the ones not yet migrated).
Global value note: attached to a value (an address, a topic, a
transaction hash) and shown wherever that value appears, on any page, forever.
Create one from the explorer, or promote a local note by choosing “Global”.

Notes are attributed to their author and visible space-wide. When you belong to
several spaces, the note form names its destination and lets you pick.

Cross-referencing

Values in a transaction are matched against your space automatically: local
matches surface as “research notes in your space” on the explorer, and global
notes render inline next to the value itself. That is how a note written months
ago finds you again when the same address turns up.