Docs/Concepts/Bases and widgets

Bases and widgets

Bases and widgets are Solomon's two ways of building a live view on top of plain notes, without turning any of them into something other than a markdown file.

Bases: a live table over your frontmatter

A base filters, sorts, and groups your notes like rows in a database — without moving or rewriting a single file. The notes stay plain markdown; the base just queries them and re-renders whenever they change. Build one visually (Bases surface → filters, columns, table/kanban view), or write its query directly in the base DSL.

The DSL grammar

Every base compiles down to a small, line-oriented text query (keywords are case-insensitive; # starts a comment):

from notes
where <field> <op> <value> [or <field> <op> <value> ...]
sort <field> [asc|desc]
columns a, b, c            (max 6)
group by <field>
view table|list|cards|kanban|graph
limit N

Multiple where lines AND together; or joins predicates within one line.
Fields are frontmatter keys, plus the meta fields __title, __path, __modified, and __folder (aliased as folder) — the __ prefix matters, since a bare title is a real frontmatter key, not the meta one.
Operators: is, is not, contains, not contains, exists, missing, gt/gte/lt/lte (numeric, or an ISO date/epoch-ms against __modified), and under (folder-hierarchy prefix — where folder under "Projects" matches Projects itself and anything nested below it).
Values are double-quoted strings (quotes optional for a single bare word), numbers, or true/false.

Parse and evaluation errors are never a hard failure — they land as a structured { message, line } so a widget or the builder can render exactly what's wrong and where.

Round-tripping with Obsidian

Bases save to and load from real .base files in the vault (default folder Bases/), compatible with Obsidian's own .base format — export yours, import an existing one, or hand-edit the file since it's just text. Agents and the CLI can run the identical query: the MCP base_query tool and solomon base <dsl> both take the same DSL string.

Widgets: sandboxed HTML mini-apps

A widget is a small, self-contained HTML file at Widgets/<id>.html — a counter, a chart, a live table — that renders inside an iframe, walling its code off from the rest of the vault. You embed one in a note with a solomon-widget code fence naming the widget's id and any per-instance props, so the same widget can appear multiple times with different inputs.

A widget's HTML carries a manifest block:

<script type="application/json" id="solomon-widget">
{ "name": "My Widget", "data": "base", "dsl": "from notes where status is active" }
</script>

Every field in that manifest is optional (name defaults to the widget's id, so an empty {} is a valid manifest) — only a missing or malformed manifest block is refused. The "data": "base" shape is how a widget wires itself to a base query, reading the same DSL grammar described above.

Widgets are quarantined from agents

By design, the general note-reading and note-writing MCP tools (and the solomon CLI) refuse anything under Widgets/ — because a widget's HTML carries executable JavaScript, and the general tools would either be unsafe to expose it through or would mangle the manifest on a naive rewrite. A dedicated widget_write MCP tool exists instead for agents that need to author or update a widget: it validates the manifest block, and — on a force-scoped write that replaces an existing widget — archives the previous file to <id>.html.bak first, so a bad replacement is always recoverable. widget_list gives an agent metadata-only discovery (id, name, description) without ever exposing the HTML/JS itself.

Where the two meet

A widget backed by "data": "base" is the common pattern for building something like a live kanban board or dashboard inside a note: the base DSL does the filtering/sorting/grouping, and the widget supplies the rendering and any interactivity beyond what the built-in Bases surface offers.

[[Query your vault with bases]] — a worked playbook for writing and saving a base query.
[[Agents and skills]] — the propose-vs-force model that also governs widget_write.
[[MCP tool surface]] — the base_query, widget_list, and widget_write tools.