# Ymer Node v0.2.1 - Table of Contents

> Headless local MCP node providing notebook, references and script capability to LLM workers

## Pages

- [README](readme.md)
- [Glossary](glossary.md)
- [Scripts — batteries and their boundary](scripts.md)

## Modules

- [YmerNode](YmerNode.md): This module is the **map** — what exists and why. Each entry defends a module's
existence; how a module is designed lives in its own `@moduledoc`.
- [YmerNode.Mcp](YmerNode.Mcp.md): The MCP mount — the node's entire external surface.
- [YmerNode.Mcp.Endpoint](YmerNode.Mcp.Endpoint.md): The HTTP entry point: routes paths to `YmerNode.Mcp`, and answers 404 to
everything else.
- [YmerNode.Mcp.McpServer](YmerNode.Mcp.McpServer.md): The instructions the node hands every MCP client at connect.
- [YmerNode.Mcp.Tools.Helpers](YmerNode.Mcp.Tools.Helpers.md): The four helpers a tool's action and format layers share, and nothing else.
- [YmerNode.Mcp.Tools.Notebook](YmerNode.Mcp.Tools.Notebook.md): Wymcp tool `notebook` — an open SQL surface over `notebook.db`, the node's own
private store, together with the actions that keep it safe.
- [YmerNode.Mcp.Tools.Notebook.Actions](YmerNode.Mcp.Tools.Notebook.Actions.md): Action implementations for the `notebook` MCP tool
(`YmerNode.Mcp.Tools.Notebook`, which calls `run/2`) — a thin boundary over
`YmerNode.Notebook` and `YmerNode.Notebook.Backup`. This is a trust boundary:
`sql`, `table` and `id` are guarded `is_binary` in each head because nothing
downstream validates them — the MCP dispatch layer checks that a parameter is
present but never what type it holds — so `sql` and `table` flow straight into
SQLite and `id` flows into filename construction. Each action returns
`{:ok, data, hint_ctx}` or `{:error, {reason, ctx}}` — and, where the error is one
the caller can act on, `{:error, {reason, ctx}, hint_ctx}`, the three-element form
that puts a follow-up hint on the error payload rather than only in its prose.
- [YmerNode.Mcp.Tools.Notebook.Errors](YmerNode.Mcp.Tools.Notebook.Errors.md): Translates `YmerNode.Notebook` and `YmerNode.Notebook.Backup` error reasons into
LLM-readable messages. SQLite errors are surfaced verbatim so the agent can read
and fix its own SQL; backup failures never are, because their detail carries
filesystem paths the caller must not see.
- [YmerNode.Mcp.Tools.Notebook.Format](YmerNode.Mcp.Tools.Notebook.Format.md): Shapes `YmerNode.Notebook` and `YmerNode.Notebook.Backup` results into
JSON-serialisable maps for MCP responses.
Query results pass through as parallel `columns`/`rows` arrays (compact and
order-preserving) rather than per-row maps.

- [YmerNode.Mcp.Tools.Notebook.Hints](YmerNode.Mcp.Tools.Notebook.Hints.md): Follow-up hints for the `notebook` tool, keyed off the hint_context maps
`YmerNode.Mcp.Tools.Notebook.Actions` produces. After `execute` creates schema, the
natural next steps are describing or querying it; after a capture the natural
next step is confirming it. A completed restore needs no follow-up either, since
the roll-back is already done — but a restore that failed recoverably does: the
hint carries the id of the backup to restore, or of the restore to retry, so the
recovery is one call away instead of a re-read of the error text. Everything else
falls through to none — including every answer about a notebook that cannot take
the call, whose next action is a person's and not another tool call, and a
backup that will not open, whose next action is a different id this module has
no way to choose.

- [YmerNode.Mcp.Tools.Notebook.Schemas](YmerNode.Mcp.Tools.Notebook.Schemas.md): Schema definitions for the `notebook` tool's actions. The `:notes`/`:examples` are the
agent's primary documentation for sqlite-vec usage and the INTEGER-PRIMARY-KEY
join discipline — they surface via the `help` tool.

- [YmerNode.Mcp.Tools.References](YmerNode.Mcp.Tools.References.md): Wymcp tool `references` — the registry of pointers at where knowledge lives.
- [YmerNode.Mcp.Tools.References.Actions](YmerNode.Mcp.Tools.References.Actions.md): Action implementations for the `references` tool — the boundary over the
`YmerNode.References` context.
- [YmerNode.Mcp.Tools.References.Errors](YmerNode.Mcp.Tools.References.Errors.md): Translates the `references` tool's error reasons, optionally with context,
into messages a worker can act on. Called by
`YmerNode.Mcp.Tools.References`'s `c:Wymcp.Tool.handle_error/1`.
- [YmerNode.Mcp.Tools.References.Format](YmerNode.Mcp.Tools.References.Format.md): Response shaping for the `references` tool.
- [YmerNode.Mcp.Tools.References.Hints](YmerNode.Mcp.Tools.References.Hints.md): Follow-up hints for the `references` tool, keyed off the hint_context maps
`YmerNode.Mcp.Tools.References.Actions` produces.
- [YmerNode.Mcp.Tools.References.Schemas](YmerNode.Mcp.Tools.References.Schemas.md): Action schemas for the `references` tool. The `notes` surface through the
`help` tool and are the worker-facing contract documentation — the mode
contract, the duplicate rule, and the membrane.

- [YmerNode.Mcp.Tools.References.Validate](YmerNode.Mcp.Tools.References.Validate.md): Value validation for the `references` tool's params.
- [YmerNode.Mcp.Tools.ScriptAuthor](YmerNode.Mcp.Tools.ScriptAuthor.md): Wymcp tool `script_author` — writing the scripts this node accepts.
- [YmerNode.Mcp.Tools.ScriptAuthor.Actions](YmerNode.Mcp.Tools.ScriptAuthor.Actions.md): Action implementations for the `script_author` tool — the boundary over
`YmerNode.Scripts`'s write verbs.
- [YmerNode.Mcp.Tools.ScriptAuthor.Errors](YmerNode.Mcp.Tools.ScriptAuthor.Errors.md): Translates the `script_author` tool's error reasons into messages a worker can
act on. Called by `YmerNode.Mcp.Tools.ScriptAuthor`'s
`c:Wymcp.Tool.handle_error/1`.
- [YmerNode.Mcp.Tools.ScriptAuthor.Hints](YmerNode.Mcp.Tools.ScriptAuthor.Hints.md): Follow-up hints for the `script_author` tool, keyed off the hint_context maps
`YmerNode.Mcp.Tools.ScriptAuthor.Actions` produces.
- [YmerNode.Mcp.Tools.ScriptAuthor.Schemas](YmerNode.Mcp.Tools.ScriptAuthor.Schemas.md): Action schemas for the `script_author` tool. The `notes` surface through the
`help` tool and are the worker-facing contract of each call — what it does,
what it refuses, what its flags mean. The script contract itself is not
written here: `scripts guide` renders it from `YmerNode.Script`'s own docs,
and the notes of `check` and `create` point there.

- [YmerNode.Mcp.Tools.ScriptFormat](YmerNode.Mcp.Tools.ScriptFormat.md): Response shaping for both script tools — `YmerNode.Mcp.Tools.Scripts` and
`YmerNode.Mcp.Tools.ScriptAuthor`.
- [YmerNode.Mcp.Tools.Scripts](YmerNode.Mcp.Tools.Scripts.md): Wymcp tool `scripts` — the scripts this node has accepted, and running one.
- [YmerNode.Mcp.Tools.Scripts.Actions](YmerNode.Mcp.Tools.Scripts.Actions.md): Action implementations for the `scripts` tool — the boundary over
`YmerNode.Scripts`.
- [YmerNode.Mcp.Tools.Scripts.Errors](YmerNode.Mcp.Tools.Scripts.Errors.md): Translates the `scripts` tool's error reasons into messages a worker can act
on. Called by `YmerNode.Mcp.Tools.Scripts`'s `c:Wymcp.Tool.handle_error/1`.
- [YmerNode.Mcp.Tools.Scripts.Hints](YmerNode.Mcp.Tools.Scripts.Hints.md): Follow-up hints for the `scripts` tool, keyed off the hint_context maps
`YmerNode.Mcp.Tools.Scripts.Actions` produces.
- [YmerNode.Mcp.Tools.Scripts.Schemas](YmerNode.Mcp.Tools.Scripts.Schemas.md): Action schemas for the `scripts` tool. The `notes` surface through the `help`
tool and are the worker-facing contract: what a run costs, what acceptance
means, and why `describe` is the call to make before `run`.
- [YmerNode.Notebook](YmerNode.Notebook.md): The notebook — `notebook.db`, a separate, portable SQLite store of user- and
LLM-governed memories, working and long-term: agent-defined schema, open SQL,
embeddings, backup and restore. Potentially precious (tutoring records,
curated knowledge); the node's obligation is durability — governance stays with
the user and the LLM. This module is its raw-SQL surface (via
`YmerNode.Notebook.Repo`).
- [YmerNode.Notebook.Backup](YmerNode.Notebook.Backup.md): Capture and restore for `notebook.db` — the node's one durable obligation.
- [YmerNode.Notebook.Backup.Lock](YmerNode.Notebook.Backup.Lock.md): Singleton mutex serializing `YmerNode.Notebook.Backup` operations — capture and
restore.
- [YmerNode.Notebook.Repo](YmerNode.Notebook.Repo.md): Ecto repo for `notebook.db` — the node's one deliberate local store.
- [YmerNode.Notebook.VecLoadCheck](YmerNode.Notebook.VecLoadCheck.md): One-shot boot probe that aborts application start when the sqlite-vec `vec0`
extension did not load into `YmerNode.Notebook.Repo`.
- [YmerNode.References](YmerNode.References.md): The registry of pointers at where knowledge lives, served to LLM workers as
the `references` tool; it holds references, never copies of what they point at
(the membrane).
- [YmerNode.References.Reference](YmerNode.References.Reference.md): One row of the registry: a pointer naming where knowledge lives and when to
look, never what it says. The rule that keeps it a pointer — the membrane —
is stated in `YmerNode.References`.
- [YmerNode.References.Search](YmerNode.References.Search.md): The find surface — two composable layers on one call.
- [YmerNode.References.Sources](YmerNode.References.Sources.md): Derives a reference's source and fetch recipe from its uri, at read time and
never from storage.
- [YmerNode.Repo](YmerNode.Repo.md): Ecto repo for `node.db` — the node database, and the rebuildable half of what
the node stores.
- [YmerNode.Secrets](YmerNode.Secrets.md): The values a script resolves by name — one file of `NAME=value` lines,
outside every database.

- Scripts
  - [YmerNode.Script](YmerNode.Script.md): The contract a script implements — its description, its actions and their
read/write marks, its declarations — and the version `use YmerNode.Script`
stamps into its row.
  - [YmerNode.Script.Context](YmerNode.Script.Context.md): What the node hands every run — Req, `JSON`, the notebook, secrets, the
throttles it declares, the node's time zone, the files directory and the
Typst renders — provided by the node rather than declared by the script.
  - [YmerNode.Scripts](YmerNode.Scripts.md): The scripts this node has accepted, and every door they arrive and leave
through — the context both script tools wrap and the node's own callers use.
  - [YmerNode.Scripts.CLI](YmerNode.Scripts.CLI.md): The operator's verbs, run on the machine the node runs on — the node's own
human door, beside the client's approval.
  - [YmerNode.Scripts.Compiler](YmerNode.Scripts.Compiler.md): Turns a script's code into a loaded module tree, or into a refusal that names
what is wrong with it.
  - [YmerNode.Scripts.Guide](YmerNode.Scripts.Guide.md): The text `scripts guide` renders — the script contract and the batteries a
script is handed — read at the call from the docs the release keeps.
  - [YmerNode.Scripts.Loader](YmerNode.Scripts.Loader.md): Owns the VM's script module trees: every compile and every purge goes through
this process, and it remembers what each one produced.
  - [YmerNode.Scripts.PackageDocs](YmerNode.Scripts.PackageDocs.md): A promised package's own documentation, rendered from this release — what
`scripts info <name>` answers.
  - [YmerNode.Scripts.Runner](YmerNode.Scripts.Runner.md): One run of one action — what is checked before it, the process it happens in,
and the shape of every answer that comes back.
  - [YmerNode.Scripts.Script](YmerNode.Scripts.Script.md): An Elixir module stored as a row in the node database — its code, the hash of
that code and the hash this node has accepted — compiled into the VM and
reachable through the `scripts` tool and by the node itself; `Script.<Name>`,
named after its module.
  - [YmerNode.Scripts.Throttle](YmerNode.Scripts.Throttle.md): One throttle on this node: the process that holds its bucket, its breaker and
the requests waiting on it — and the two request steps that put a request
naming it through that process.
  - [YmerNode.Scripts.Throttle.Bucket](YmerNode.Scripts.Throttle.Bucket.md): A throttle's token bucket as a value: a rate per minute, a burst, the tokens it
holds and the instant it last counted them.
  - [YmerNode.Scripts.Throttle.Error](YmerNode.Scripts.Throttle.Error.md): A throttle's refusal of a request — the exception `YmerNode.Script.Context.request/2`
answers as `{:error, exception}` when a request never left the node.

## Mix Tasks

- [mix ymer_node.build](Mix.Tasks.YmerNode.Build.md): Build the release image and tag it with the commit it was built from.
- [mix ymer_node.build.live_output](Mix.Tasks.YmerNode.Build.LiveOutput.md): A subprocess's output reaching the terminal as it is produced — faithful
for valid UTF-8, with anything unreadable shown as `�`, and unable to stop
the task that runs it, whatever bytes it carries.
- [mix ymer_node.deploy](Mix.Tasks.YmerNode.Deploy.md): Deploy: move the checkout's committed `main` into the install — name the
rollback target, build, carry the compose file, recreate the install's
container on the image, and verify it came up on it.

