Sources
Docs: Panes, Perceptions, Policies, Preferences, and Plotted Path. Web App: hover a Pane that reads data and choose Plot the path to this….Who reads what you write
Plot the path to this… explains how the thing a reader points at came to be, from the tools its information comes from up to that Pane. Every Parable gets it, and nothing about it is written for one Parable. It is written from what the Parable already says about itself:- each Pane’s name and description;
- which Panes each Pane builds on, through the Panes it declares, the Plots of this Parable its Plot reads, and the Plots its filter conditions name by key. A Plot of another Parable is not part of the path, even when its slug is the same as the slug of one of this Parable’s Plots;
- which Panes have settings people can change;
- the access Policies on the path and on the Page;
- the Provider tools at the bottom.
Write names and descriptions for readers
A Pane’s name and description are the words a reader sees. Write them for the person reading the Parable, not for the person editing it.- Say what the Pane shows or decides, in one or two sentences.
- Leave out how: no queries, joins, columns or function names.
- Leave out detail a reader would not act on.
One Plot per Pane
A Pane owns at most one Plot. A second computation gets a Pane of its own, which the first one declares or reads. The explanation follows Panes, so each step a reader opens is a Pane with a name and a description of its own.Put sources under their type
Model what a Parable is about as Panes of their own, such as a Meeting, a Person or a Message, and put each tool’s source under the type it feeds: a Meeting Pane declares its Google Calendar and Zoom Panes. An explanation can then say “We gather meetings from your calendars and calls” and let a reader open the Meeting Pane, rather than walk every source one by one. Label a row type’s place in that model with@grouping in its Perception’s
doc comment, for example /** A Meeting. @grouping Activity › Meetings */. It
is a convention: Plotted Path does not read it.
Mark plumbing
Some Panes only serve other Panes: shared state, a kit of helpers, a preview. Mark each with@plumbing in the doc comment on its Perception, so the
explanation never offers it to a reader as a part to open:
Name access Policies in plain words
The explanation quotes the filter Policies on the path and on the Page by name, for example “People only see categories and hours within their own reporting line”. Name a Policy for what it does to a reader, such as My reporting line, not for how it works.Words a reader never sees
The explanation never uses database, programming or builder words. It is checked against this list, matched as whole words in any case, and written again once, naming the words it used:jev, row, rows, column, columns, table, tables, schema, data model, query, queries, sql, join, joins, null, kind, kinds, report run, report runs, plot, plots, draws nothing, preview, previews, record type, record types, inline, section, lowercase, lower case, identifier, identifiers, username, usernames, helperProduct words such as Pane, Parable, Perceptions, Policies, Proof, Ponder, Provider, Workspace and Team are not on it: the sheet itself names “The Person Pane”. The explanation is written from your names and descriptions, so keep these words out of them too: the editor names any it finds in a Pane’s name or description, under the description. A step’s linked Pane opens in a side panel with its description. There a reader sees every sentence of it except one that names something from the code, such as a Plot’s handle: “It owns the
personRows list.” is left out,
and a description with nothing else to show shows none. A sentence you wrote
in ordinary words stays, the words of the list above among them: “One row per
person.” is shown as you wrote it.
How the explanation is written
The server builds a map of the Pane for the whole Version: each Pane with its name and description, what it builds on, whether it has settings, the Provider tools at the bottom, and the access Policies in plain words. A@plumbing Pane is left out, and what it builds on passes to the Panes that
read it.
One language call explains the map, through the Workspace’s
model for Ponder’s explanations and summaries. That model is Haiku Latest by
default, routed through OpenRouter with zero data retention, so the
Workspace’s AI processor rules apply. It answers in a few steps, each a
title and short bullets, linking the Panes a reader would open next, written
from where the information comes from up to the Pane: the first step is
always where the information comes from. The sheet numbers them in that
order. An answer that comes back incomplete, such as a single step with no
bullets, is asked for once more, saying what was missing. One still
incomplete is never kept or shown: the reader is told the explanation failed,
and the next open asks again.
The map never names a part fewer people may view than the Pane itself. A part
whose view Policies are stricter, by participation level, people and Roles,
the setting they follow, or a view filter Policy of its own, is left out, with
everything reached only through it, and the access rules say only that some
of what the answer builds on is not described. When the explanation is shown,
each link is checked again against the reader’s own seat, so nobody sees a
link to a part they cannot open.
The platform keeps one explanation per Pane and published Version, with the
map it explains and the version of the instructions that wrote it, and serves
it to everyone who may view the Pane. A new Version whose map for the Pane is
unchanged keeps the explanation it had, with no new call. When the map or the
instructions change, the kept one is shown while a new one is written. An
earlier Version’s explanation is shown that way only when every part it was
written from is still in this reader’s map: its titles and bullets may name a
part whose view has since become stricter, and only links are checked when it
is shown. Otherwise the new one is written before it is shown. A Pane nobody has
opened yet is explained the first time someone does. Someone who publishes the
Parable can ask for it to be written again. A set of unpublished Changes is
explained each time it is asked, and never kept.
Write it ahead
A Pane readers open often can have its explanation written before the first of them opens it. Say when with@plottedPath in its Perception’s doc comment:
@plottedPath publishwrites it as each Version is published from the editor.@plottedPath reportwrites it as each Report run of a Version completes, for a Parable read mostly from its Refreshes.