# Fastpad documentation

Source: https://www.fastpad.ai/en/docs — this file is the same content, concatenated.
Agent-facing identifiers (tool names, scopes, error type URIs, HTTP paths) are English and stable.

---
# Getting started

Write a note, connect an agent, and see how its edits reach your notes only through you or a grant you made.

## Your first note

Open Fastpad and start typing. The first note exists before you have an account: it lives in a CRDT in your browser and is adopted into a workspace when you sign up. Nothing is lost in between, and nothing about that first note is a demo.

Every block — every paragraph, heading, list item, code fence — is given a stable identifier the moment it is created. That identifier is what lets a comment, a citation or a link point at the middle of a note and still be pointing at the right thing after the note is rewritten around it.

- Press `/` for the block menu: headings, lists, tables, code, callouts, toggles, columns.
- Press `Cmd/Ctrl-K` for the command palette.
- Type `[[` or `@` to mention another note. The link is a real edge, not a string.
- Press `Cmd/Ctrl-Z` as usual. Undo is local and never fights a sync.

## Organizing without deciding first

There is no database to create before you can write. Notes are notes. When a set of them turns out to be the same kind of thing, apply a type — `#Person`, `#Meeting`, `#Project` — and that type brings its properties with it.

Typing is optional, retroactive, and multiple: a note can carry several types at once, and untyped notes are completely first-class. Once notes share a type you can save a view over them — table, board, calendar, gallery, list or timeline — and embed that view inside any other note. See [Concepts](/en/docs/concepts).

## Connect an agent

Fastpad speaks the Model Context Protocol. Point any MCP client at the endpoint below and it can search, read, traverse links and propose edits.

```text
https://mcp.fastpad.ai
```

Mint a token in Settings → Agents & tokens (also linked from the Agent activity page), where you choose its scopes and autonomy and can revoke it later, or run `fp login` in a terminal. An unauthenticated request answers 401 with a challenge telling the client exactly where to authenticate.

> **Important:** By default an agent's edits are proposals: it hands you a review URL and nothing reaches the note until you accept. When you mint a token you can grant more — `turns:accept` lets the agent accept its own proposals, marked as agent-accepted, and auto-apply lets its edits land without a proposal. Either way every such write stays marked and is listed on the Agent activity page for you to review or revert. See [Agents](/en/docs/agents).

## Your notes are files you can read

Everything serializes to CommonMark with YAML frontmatter and a `{#blockId}` anchor after each block. That is one canonical format, used by the export, the API, the agent tools and the on-disk mirror — there is no second, lossier one.

```bash
fp pull ./my-notes     # the whole workspace, as Markdown
fp push ./my-notes     # send your local edits back
```

Because each block carries its anchor, `fp push` reads which paragraph is which block rather than guessing. See [Markdown](/en/docs/markdown) and the [CLI](/en/docs/cli).

## Where to go next

- [Concepts](/en/docs/concepts) — notes, blocks, types, collections and links
- [Agents](/en/docs/agents) — what an agent can and cannot do, and why
- [MCP](/en/docs/mcp) — the tool surface, in detail
- [CLI](/en/docs/cli) — `fp`, for terminals and CI
- [API](/en/docs/api) — the HTTP surface

---

# Concepts

Notes, blocks, types, properties, collections and links — the six ideas everything else is built from.

## Notes and blocks

A note is a page. It is the unit of permission, of publishing, of search scope, and of the collaborative document underneath.

A block is one paragraph, heading, list item, table row or code fence. Each has a ULID minted when it is created, and that ULID survives splitting a block, joining two, pasting, and sending an exported or pulled file back into its note with `fp push`. Importing an export through the Import dialog creates new notes, whose blocks get new ULIDs. Everything durable points at a block: comment anchors, agent citations, the `{#blockId}` in your exported Markdown, and the chunks search returns.

> **Note:** When you split a block in two, the identifier stays with the first half. Anything anchored to it stays anchored to the text it was about.

## Types are tags, and tags are classes

Applying `#Person` to a note does two things: it gives the note that type’s properties, and it makes the note a member of a collection you can query. A type can extend others, so `#Audiobook` can be a `#Book` and a `#MediaObject` at once.

This is not Notion’s model. Notion makes you choose a database before you write. Fastpad lets you write first and classify later, including in bulk and including long after the fact.

| Property type | Holds |
| --- | --- |
| `text`, `number`, `url` | scalars |
| `date`, `datetime` | points in time; sortable and filterable |
| `checkbox` | a boolean |
| `select`, `multi_select` | one or many of a defined option set |
| `person` | a member of the workspace |
| `relation` | another note, constrained to a type |
| `file` | an uploaded attachment |

Two types can define the same property name without colliding: `Person.email` and `Contact.email` are different properties on the same note.

## Collections

A collection is a saved view over a type: filters, sorts, grouping and a layout. Six layouts — table, board, list, gallery, calendar and timeline — over rows that already existed as notes.

A view embedded in a note and a view opened from the sidebar are the same object. An embedded collection stores the view, never the rows, because a collection is a saved question and rows in a block would be a stale copy of the answer.

## Links and the graph

Typing `[[` or `@` creates a typed edge, not a piece of text that happens to look like a link. Every note shows its backlinks, and edges carry evidence — which is why a link can answer “why is this connected?” rather than only “that it is”.

Some edges are asserted by you and some are inferred by the system. Inferred edges decay; asserted ones do not. Promoting an inferred edge is one gesture, and until you make it, no agent search will walk that edge to reach content through it.

## Trash, archive and delete

| Action | What happens | Reversible |
| --- | --- | --- |
| Archive | The note stays open, linkable, greppable and exportable. It drops out of search results. | yes |
| Move to trash | The note leaves the sidebar. Its blocks, history and links all stay. | yes, from the trash |
| Purge | The rows are removed after the retention window. | no |

Archiving is something a person does, never something a model decides. Lost notes are the single largest source of one-star reviews in this category, which is why restore was built before hard delete was.

---

# Markdown and export

One canonical serialization, with block anchors, used by the export, the API, the agent tools and the disk mirror.

## The format

CommonMark, with YAML frontmatter for note metadata and a `{#blockId}` anchor after each block.

```markdown
---
title: Retrieval design
types: [Project]
status: active
---

# Retrieval design {#01JB2K7Q9XN4M8YV3TD0FZ5ERW}

Four arms, fused by weighted RRF. {#01JB2K7Q9XN4M8YV3TD0FZ5ESX}

- lexical {#01JB2K7Q9XN4M8YV3TD0FZ5ETY}
- dense {#01JB2K7Q9XN4M8YV3TD0FZ5EUZ}
```

The anchor is the point. It is what makes a Markdown file a faithful representation of the document rather than a printout of it: the file says which block each paragraph is, so edits made on disk map back exactly.

## The disk mirror

```bash
fp pull ./notes            # write the mirror
$EDITOR ./notes/…
fp push ./notes --dry-run  # see what would change, offline
fp push ./notes            # send it back
```

A push is a diff against known identifiers, never a guess: an anchor whose text changed is an edit to that block; an anchor that vanished is a deletion; a paragraph with no anchor is something new.

File names are built from each note’s title after any credential in it is redacted and any URL neutralized, whoever pulls, so a key pasted into a title never becomes the name of a file on disk. The note’s identifier is part of the name, so two notes with the same title are two files.

> **Important:** `fp pull` refuses to overwrite local edits unless you pass `--force`. Pull into a directory you are not also editing in another window.

## Published notes

Publishing a note makes it readable at `fastpad.ai/n/{id}` with no account. The same URL serves HTML to a browser and Markdown to anything that asks for it.

```bash
curl -H 'Accept: text/markdown' https://www.fastpad.ai/n/01JB2K…
```

Only a signed-in person can publish — no agent credential can, because an agent that could publish could exfiltrate a workspace by making it public and reading it back from outside. An unpublished note, a deleted note and a note that never existed are indistinguishable to an anonymous caller.

## What round-trips

- Headings, paragraphs, lists, tasks, quotes, callouts, code fences, dividers.
- Tables, including cells containing an escaped pipe.
- Links, mentions and the edges behind them.
- Note properties, as frontmatter.
- Block identifiers, on everything.

Attachments are referenced by URL rather than inlined. An export is a directory of text you can read with anything, which is the test this format exists to pass.

---

# Agents

How an agent reads, how it proposes, what it takes for one to accept — and how you see every time it does.

## Proposals, not writes

An agent with `notes:write` cannot change a note directly. It commits to a sibling suggestion container and you get a reviewable diff. Accepting is a separate transaction — yours, from a signed-in session, or the agent's own, but only under a token you minted with the `turns:accept` scope.

That scope is a grant, not a setting. It is never implied by another scope, never in a CLI's default grant, and only a person can mint a token that carries it. An agent may accept only turns it opened itself, and only prose: proposed links and calendar events wait for you on every path.

The reason the default is propose-only is specific to how Fastpad syncs. An edit committed to a note is durable and on every one of your devices immediately. If a poisoned web page or a malicious note steered the agent, the injected text would be everywhere before anyone saw a diff — and no interface can retract bytes that are already on a second device. Granting accept is you deciding that risk is worth it for that token, by name, and the trail below is what you get in return.

## Reviewing a proposal

A proposal arrives in your inbox and at a URL of its own. You see a per-block diff: what the agent read, what it wants to change it to, and which blocks it says it drew from.

1. Accept — the change is applied, marked as reviewed by you, and the sources it cited become real links.
2. Accept some — the rest stay pending.
3. Reject or abandon — nothing was ever applied, so there is nothing to undo.
4. Revert, later — undoes the whole proposal as one unit, keeping any edit you made on top of it.

> **Note:** If you edited the text while the proposal was waiting, accept refuses to overwrite you. You get a three-way merge instead — your version is never discarded silently.

When an agent accepts its own proposal, you see it afterwards instead of before. The Agent activity page, at `/agent-activity` in the app, lists every turn that reached a note on an agent's authority — accepted under `turns:accept`, or auto-applied — with who did it, which notes it touched, and how many blocks. Each accept is also written to the audit log under the agent and the token that made it.

- Mark reviewed — the blocks the agent accepted are promoted to reviewed-by-you, the same state a proposal you accepted yourself gets. Auto-applied blocks stay unreviewed; the turn still leaves the queue.
- Revert — undoes the whole turn as one unit, keeping any edit you made on top. Reverting is yours alone: no token of any scope can do it.
- Open the diff — the same per-block view a pending proposal has.

## What a token can reach

A token resolves to a concrete set of notes when it is created, never to a live tag query. Otherwise an agent holding `notes:write` could widen its own reach simply by tagging a note it wanted to read.

| Scope | Grants |
| --- | --- |
| `notes:read` | read note bodies |
| `notes:propose` | create proposals — never apply them |
| `notes:write` | write note content directly (properties, types, comments) |
| `notes:delete` | move to trash and restore |
| `search:read` | search, and titles and snippets with it |
| `graph:read` | traverse links |
| `schema:write` | define note types and their properties |
| `export` | pull the whole workspace as Markdown |
| `turns:accept` | accept its own proposals; every accept is listed for you to review |

Accepting is on that list, and nothing else on it implies it: a token holding every other scope still cannot accept. What is not on the list, and cannot be, is reverting, reviewing, publishing and verifying — those need a signed-in person.

## Trust is two questions, not one

Every piece of content carries where it came from and whether a person ratified it. Those are separate axes, and keeping them separate is what makes “an agent wrote this and I read the diff” different from “an agent wrote this and nobody looked”.

| Origin | Means |
| --- | --- |
| `human_typed` | a person typed it, or a terminal they were holding did |
| `agent_written` | an agent authored it |
| `inbound_untrusted` | it arrived from outside a keystroke — a capture, an import, an email |

By default an agent searching your workspace sees only content a human authored. Agent-written text nobody reviewed is excluded, and so is anything untrusted. An agent has to ask for a lower floor explicitly.

A block an agent accepted under `turns:accept` carries the review state `agent_accepted`. That is not treated as human-reviewed: every trust floor above the lowest excludes it exactly as it excludes unreviewed agent text, so an agent cannot ratify its own work into what the next agent is told is established fact. It becomes `human_accepted` only when you mark the turn reviewed.

## Autonomy, for the cases that earn it

A token can be given auto-apply, scoped to its note set or to the workspace. Its edits then land without review — and stay marked unreviewed forever, so the cost of that decision is visible in the data rather than only in a settings page.

Auto-apply and accept are different grants. Auto-apply skips the proposal entirely; accept ratifies one that was made. Neither turns a token into a person: an accept is marked as an agent's, an auto-applied write is marked unreviewed, both land on the Agent activity page, and reverting either is yours.

---

# MCP

Connect an MCP client: the endpoint, the twelve tools, sessions, anchor handles and budgets.

## Connecting

```text
https://mcp.fastpad.ai
```

JSON-RPC over a single POST. Authenticate with `Authorization: Bearer fpk_live_…`. An unauthenticated call answers 401 with a `WWW-Authenticate` challenge and a link to the protected-resource metadata, so a client can discover how to authenticate without being told.

```bash
fp login      # device flow; approve in a browser
fp mcp --check   # verifies the brokered credential
```

For a local stdio client, `fp mcp` is the command the client launches — it speaks the stdio transport and refuses at a prompt. Configure the client with `command: "fp"` and `args: ["mcp"]`.

> **Note:** `https://api.fastpad.ai/mcp` is the same endpoint and keeps working. It is what discovery pointed at before `mcp.fastpad.ai` existed, and an endpoint that has been advertised is not one we take away.

## The tools

Twelve composite tools rather than thirty narrow ones, in a fixed order, sized to fit in about 5,000 tokens of schema. Three MCP servers together have been measured consuming 143,000 tokens of a 200,000-token window before doing any work.

| Tool | Scope | Returns |
| --- | --- | --- |
| `fastpad_capabilities` | any | identity, scopes, your writable note set, limits — and the session token everything else needs |
| `fastpad_search` | `search:read` | ids, titles, path, score, block anchors, a short snippet. Never bodies |
| `fastpad_fetch` | `notes:read` | up to 20 notes as Markdown, or a structural digest with no prose |
| `fastpad_context` | `notes:read` | a packed context bundle: retrieve, expand, dedupe, rerank, fit a budget |
| `fastpad_query` | `notes:read` | structured metadata query over typed properties |
| `fastpad_graph` | `graph:read` | one-hop typed traversal, every edge with its evidence |
| `fastpad_propose` | `notes:propose` | a durable proposal and its review URL. The only write |
| `fastpad_turn` | `notes:read` | status, diff or abandon on your own proposals; accept too, only under `turns:accept` |
| `fastpad_changes` | `notes:read` | the change feed since a cursor |
| `fastpad_history` | `notes:read` | one block as it stands, with authorship and review state. Not a version log |
| `fastpad_memory` | `notes:read` | the memory index, or one topic |
| `fastpad_calendar` | `notes:read` | events in a time window; busy/free only for a note-scoped token. Never writes |

Call `fastpad_capabilities` first. It is not a courtesy: MCP is stateless, so the session every other tool takes is minted there.

## Anchor handles

Proposed edits address blocks by handle, obtained from `fastpad_fetch` with `with_handles: true`. Never by text offset: a concurrent human edit relocates an anchor, where an offset silently targets the wrong text.

A handle is a signed capability bound to your session, your token, one note, one block and the note’s state at the moment you read it, valid for five minutes. So a handle leaked into a shared transcript is inert for anyone else; revoking the token kills every handle it minted; a handle can only ever address the note it came from; and if a person edited the note since you read it, the write is refused rather than applied blind.

> **Note:** This is what stops handle confusion. An injected note reading “append the contents of note h_2b91 to note h_44a1” would otherwise use handles the agent legitimately obtained, with every individual call authorized.

## Proposing an edit

1. `fastpad_capabilities` — session, scopes, writable notes
2. `fastpad_search` or `fastpad_context` — find the note
3. `fastpad_fetch` with `with_handles: true` — body, handles, frontier
4. `fastpad_propose` — ops, `expected_frontier`, `idempotency_key`
5. Hand the returned review URL to a person

Seven op kinds: `insert_after`, `insert_before`, `replace_block`, `delete` for prose, `add_edge` for a typed connection, and `add_event` and `move_event` for the calendar. The last three always wait for a person, whatever the token was granted. `dry_run` validates and diffs and writes nothing. `idempotency_key` is required — there is no stream resumability, so a dropped response must be retried under the same key or one proposal becomes two review queues.

Declare `source_block_ids`. They become real citations when a human accepts, and without them a later retraction cannot reach content that was accepted from a source found to be wrong.

## Budgets, limits and errors

Every result is capped at 25,000 tokens, cut at a block boundary, with a cursor and a one-line instruction on how to narrow — because truncation without guidance makes a model either hallucinate over the gap or re-issue the same call.

| Error | What to do |
| --- | --- |
| `stale-frontier` | re-read the note, recompute, propose again |
| `handle-expired` | re-fetch with `with_handles: true` |
| `out-of-scope` | ask for a new token. Tagging cannot widen a resolved scope |
| `insufficient-scope` | re-authorize once for the full set named in the challenge |
| `cross-note-copy-denied` | you are proposing text you read from a different note |
| `approve-not-permitted` | your token lacks `turns:accept`; hand the review URL to a person |
| `rate-limited` | honor `retry_after_ms` |

Every error is an RFC 9457 problem document whose `type` is a URL you can open. The full catalog is at [fastpad.ai/errors](/errors).

---

# CLI

`fp` — headless, scriptable, capture-first, with an exit-code contract you can rely on.

## What it is

A real headless CLI, not a remote control for a running window. It works on a server, in CI and in a container with no display.

The exit code is a published API surface, as stable as the JSON output. Changing what a code means is a breaking change.

```bash
fp login
fp capture "the thing I will otherwise forget"
fp query "meeting notes" --ndjson | jq .title
```

## Commands

| Command | Does |
| --- | --- |
| `fp capture [TEXT…]` | capture to the inbox from arguments, a file or stdin |
| `fp add --last` | capture the previous shell command, its output, exit code and timing |
| `fp ask "QUESTION"` | an answer with block-level citations you can fetch |
| `fp query TEXT` | text search, one page; `--ndjson` streams. Structured filters are MCP-only (`fastpad_query`) |
| `fp watch` | the workspace change feed, as a pipe |
| `fp turns` | proposals waiting for review |
| `fp diff TURN_ID` | one proposal as a per-block diff |
| `fp turn-abandon TURN_ID` | drop a proposal; accepting one needs a grant (below) |
| `fp pull` / `fp push` | the Markdown mirror, out and back |
| `fp mcp` | a local stdio MCP bridge and keychain credential broker |
| `fp agents` | agent principals, scopes, autonomy, last seen |
| `fp commands --json` | the command table, as data |

`--json`, `--ndjson`, `--quiet`, `--dry-run`, `--profile` and `--timeout` work on every command. Prose never touches stdout in either JSON mode.

## Exit codes

| Code | Means |
| --- | --- |
| `0` | the requested effect happened |
| `1` | unclassified failure |
| `2` | usage error — unknown command, bad flag, missing stdin |
| `3` | not authenticated, or the credential was rejected |
| `4` | the target does not exist, or is no longer visible |
| `5` | conflict — stale state, idempotency, ambiguity |
| `6` | rate limited; `retry_after_ms` is on the problem document |
| `7` | accepted locally and spooled for replay. Not a failure |
| `8` | policy denied, including every attempt to approve a proposal |

```bash
fp --exit-codes     # prints the contract
```

## Capture never fails

`fp capture` does not fail on a network error. It writes to a durable local spool with an idempotency key and exits 7, and the next successful command drains it. Capture is the interaction that decides whether you keep using a notes app, so it has to work on a plane.

```bash
fp capture --status    # pending / delivered / failed
fp capture --flush     # drain now; safe from cron or a shell hook
```

## `fp accept` needs a grant

It accepts a turn your credential opened, and only if that credential carries `turns:accept` — which a plain `fp login` never asks for. Log in with `fp login --scope turns:accept` to get it, and the approval page names it. Without the scope, `fp accept` exits 8 with `approve-not-permitted`; run `fp diff` to read the proposal and hand the URL it ends with to a person.

Every accept from the terminal is recorded like any other agent accept: attributed to the credential, marked `agent_accepted`, and listed on the Agent activity page for someone to review or revert.

---

# API

The HTTP surface: authentication, the workspace header, idempotency, errors and OpenAPI.

## Base URL and discovery

```text
https://api.fastpad.ai
```

| Path | Serves |
| --- | --- |
| `GET /openapi.json` | the OpenAPI 3.1 document, strong-ETagged — a polling client costs a 304 |
| `GET /.well-known/oauth-protected-resource` | RFC 9728 protected-resource metadata |
| `GET /health` | liveness plus a database round trip |
| `POST /mcp` | the agent tool surface |

## Authenticating

```bash
curl https://api.fastpad.ai/v1/notes \
  -H 'Authorization: Bearer fpk_live_…' \
  -H 'x-fastpad-workspace: 01JB2K…'
```

Everything is authenticated by default. The only routes reachable without a credential are health, the OpenAPI document, the well-known metadata, the two device-login routes, and published notes under `/v1/public/`.

Requests are rate limited per credential. Each agent has its own per-minute limit, 120 unless it was set otherwise. Each signed-in person may make 1,200 requests a minute, and ask 20 questions a minute on `POST /v1/ask`, shared across their session and every CLI token they hold. The two device-login routes have no credential to count against, so they are limited per address: 20 starts and 60 polls a minute. A refusal is a 429 with `retry_after_ms`; wait that long and try again.

`x-fastpad-workspace` names which of your workspaces to act in. It is not an authorization decision: naming a workspace you are not a member of returns nothing rather than someone else’s notes.

## Request shape

- Identifiers are ULIDs — 26 characters, sortable by creation time.
- Timestamps are ISO 8601 with an offset.
- Lists are keyset-paginated; follow `next_cursor` rather than counting pages.
- Bodies are capped at 64 KiB on public routes, 8 MiB on authenticated routes and `/mcp`. A body over 64 KiB must finish arriving within 60 seconds and, after the first 5 seconds, keep up a minimum average rate that scales with its size: 64 KiB a second for a maximal 8 MiB body, proportionally less for a smaller one. A body that falls short gets a retryable 408, whose `min_bytes_per_sec` says which floor applied. Large imports are presigned to object storage instead.
- No array in a request may hold more than 10,000 elements, and no request more than 50,000 values in all. A 422 lists at most 50 `field_errors`, and `field_errors_truncated` counts the rest.
- Every mutation takes `idempotencyKey`. Send one.

An idempotency key replays the first response verbatim. A body that differs under the same key is a 409, never a quiet replay of the wrong answer.

## Errors

Every failure is `application/problem+json` per RFC 9457, with a stable `type` URI, `retryable`, `retry_after_ms` where it applies, `field_errors[]` and a `docs_url` that resolves.

```json
{
  "type": "https://fastpad.ai/errors/stale-frontier",
  "title": "Stale frontier",
  "status": 409,
  "retryable": true,
  "docs_url": "https://fastpad.ai/errors/stale-frontier"
}
```

Every problem names the next call to make. The full catalog is at [fastpad.ai/errors](/errors).

## Writing a note

Note content is a collaborative document, so a write is a batch of CRDT operations plus the state you computed them against.

```text
POST /v1/notes/{id}/ops
{ "ops": "<base64 Loro update>", "peerId": "…", "expectedFrontier": "fp1:…", "idempotencyKey": "…" }
```

If the note moved since you read it, you get `stale-frontier` (409) naming both states — re-read and recompute rather than overwriting. The operation log and the queryable projection are written in one transaction, so a write is visible to a search the instant it is committed.

One save is checked before anything imports it. `ops` must be a Loro update export, never a snapshot, of at most 1 MiB once decoded. It may add at most 100,000 atoms of change the note does not already hold (an atom is one character inserted or deleted), or 200,000 when it is one peer’s edit built on the note’s current version; ops the note already has are not counted. A save past any of these gets a 422 `validation-failed` that is not retryable and names `max_bytes`, `max_atoms` or `mode`. The same bytes are refused every time, so keep the change, re-read the note, and send it again as smaller updates, each exported from the version the server last acknowledged.

> **Note:** If you are an agent, do not use this route. Use `fastpad_propose`, which produces a reviewable diff. Direct writes are for a client acting on behalf of the person at the keyboard.

---

# Search

Four retrieval strategies, fused by rank, with an explanation attached to every hit.

## Four ways of being wrong, combined

| Strategy | Finds |
| --- | --- |
| Lexical | the words that are actually in the document |
| Dense | the meaning, when your words and the note’s words differ |
| Graph | what is attached to what the first two found |
| Recency | the version you were working on this week |

Results are fused by position, not by score. Each strategy returns a number on its own scale, and normalizing three incomparable scales into one is a tuning exercise that has to be redone every time any of them changes; combining ranks is scale-free.

Weights are tuned per kind of query — a quoted phrase leans lexical, a sentence leans dense, a name leans graph — and the classifier is a deterministic rule, never a model. A model on the retrieval path costs a round trip and gets the weighting wrong in a way nobody can reproduce.

## What gets indexed

Notes are indexed in block-aligned chunks: sibling blocks under the same heading, packed to a target size, with one block of overlap so a fact stated across a boundary survives in one piece. A code block or a table row is never split — half a function does not compile and half a row is not a fact, and both would retrieve confidently.

Each chunk is prefixed with where it lives — note title, heading path, type, linked entities, date — before being embedded. A notes app knows that structurally, which is why the prefix costs nothing and is not generated by a model.

Text is searchable the instant it is saved. Semantic search catches up asynchronously; without an embedding provider configured, search runs on the other three strategies rather than returning nothing.

## Why did I get this result?

Every hit carries its own explanation: which strategies contributed, what they scored, which terms matched, the path through the graph that reached it, and any ranking penalty applied.

If a note has been superseded by another, the result says so and names the successor. Agents follow the chain rather than citing the stale note.

## What search will not return

- Archived notes, unless explicitly asked for.
- Notes outside the caller’s resolved scope.
- Content an agent wrote that nobody reviewed — unless the caller lowers the trust floor.
- Anything reached only by an edge an agent asserted and no person confirmed.

That last one is a security rule rather than a quality one. Asserting a link is a cheap write, so if an inferred edge were walkable, an agent could pull arbitrary content into the next agent’s context just by claiming a connection to it.

## Asking a question

`fp ask` and `POST /v1/ask` return a grounded answer with block-level citations. Citations are identifiers drawn from what was actually retrieved — the model chooses which to cite and cannot invent one.

This is the one path that sends note text to a third party. Everything sent is scoped to what you can read, redacted for secrets by deterministic rules, and fenced as data so a note reading “ignore your instructions” is quoted rather than obeyed. A deployment with no model provider configured refuses the route outright rather than pretending.

Each answer is a paid model call, so questions are limited to 20 a minute per person. The allowance is shared across your session and every CLI token you hold, so logging in again does not buy a second one. A token with a spending cap is held to that cap as well.

---

# Sync and offline

What actually happens to a keystroke, what happens on a plane, and what happens to a laptop that was shut for a year.

## What happens to a keystroke

1. Your keystroke changes the screen, immediately and without waiting for anything.
2. It is queued on this device before anything is sent, so a tab that dies before the save lands still has it.
3. It is sent to the server as soon as the network allows, and merged there as a CRDT operation.

Doing the third before the first is a spinner, which is why it is in that order. Step two is the one to read twice, and it is narrower than it sounds: what is kept on this device is the text you typed and the server has not yet accepted. It is replayed when the tab is opened again and deleted the moment the server acknowledges it.

What it does not do is make Fastpad a fully offline editor. Opening a note you have not already opened still needs the network, and a browser that refuses local storage — private browsing, or a policy that blocks site data — has nowhere to put the queue. In that case the editor says so rather than reassuring you: the warning not to reload the tab appears exactly when reloading it would in fact lose work.

Either way it tells you. A save that has not landed is named for what it is — no connection, session ended, note deleted, server fault — with what to do about it, and it keeps trying rather than giving up after a few seconds: the delay between attempts grows, and coming back to the tab or regaining a connection starts it again immediately. The one wait that is not cut short is the one the server itself asked for, because it knows something this tab does not.

## Two people, one paragraph

Notes are CRDTs, so concurrent edits merge without a lock and without asking you to pick a winner. Two people typing in the same note, or the same person on a laptop and a phone, converge to the same document whatever order the edits arrive in.

Structure merges too: reordering blocks on one device while editing them on another does not produce a duplicate or a lost block, because a block’s identity is independent of its position.

## Offline

In the terminal, edits and captures queue to a durable spool on disk and replay when you reconnect, and the replay is idempotent on both ends — a change the server committed just before you lost signal acknowledges rather than duplicating.

`fp capture` never fails offline: it writes to that spool with an idempotency key, exits 7, and the next command that works flushes it.

In the web app, an edit you make while the connection is down is queued on this device and retried with a growing delay for as long as the tab is open, and it is sent as soon as the connection returns — you do not have to type again to restart it. The top bar says which of the two you are in, because a connection that has dropped and a change the server refused have opposite prognoses.

## The laptop that was shut for a year

History is compacted over time, bounded by what your devices have actually acknowledged rather than by a calendar. A device that has not been seen for a long time and comes back holding edits that can no longer be merged gets a designed path, not a shrug.

Its work becomes a new note titled “Unmerged offline edits from <device>, <date>”, with as much recovered as can be. What never happens is the edits being dropped while the sync reports success.

---

# Import

Bring a vault in from Obsidian, Notion or a folder of Markdown — and see exactly what did not come.

## What you can import

| Source | Comes through |
| --- | --- |
| Obsidian | a vault directory or a zip: notes, wikilinks, frontmatter, attachments, canvases |
| Notion | the Markdown & CSV export: pages, and databases as typed notes |
| Markdown | any folder, with or without frontmatter |
| CSV | Notion database CSVs, inside a Notion export |

Wikilinks are resolved to real edges. Block identifiers are minted during the import and reused if the import is retried, so a link written by the first attempt is never orphaned by the second.

## The ledger is the product

Every import produces a row for every item the archive contained, whatever happened to it — and every skip carries a reason.

| Reason | Means |
| --- | --- |
| `encrypted_note` | we cannot read it, and will not guess |
| `unsupported_attachment` | the file type is not one we store |
| `database_view` | a saved view, not content |
| `path_too_long` | a linked page’s path is over the Windows 260-character limit, so the export is missing it; or a file’s own path is over 4,096 characters or 256 levels deep, so it was not read |
| `unresolved_wikilink` | the link had no target in the archive |
| `ambiguous_wikilink` | more than one target matched |
| `comments_not_in_export` | Notion comments are not imported; the Markdown & CSV export does not carry them |
| `parse_error` | the file was not what its extension claimed |

Links are reported per target, not per occurrence. A note gets one row for each distinct target it could not link to, up to 100, and past that a single row saying how many more links went unresolved. A note that links to the same missing page two thousand times has one row for it, not two thousand. An import lists at most 10,000 rows about links in all. Past that, a note’s link rows are left out whole, and one final row says how many were left out and from how many notes. The row for each item the archive contained is always listed.

“We imported 4,812 of 5,003 notes, and here is each of the 191 we did not” is the difference between a trustworthy import and a black box. “Expect some failed imports”, with no reason per item, is the bar this clears.

## While it runs

Notes become readable as they land rather than at the end, and an import can be canceled without losing what has already committed. Search over the imported vault becomes useful before the import finishes.

> **Note:** Imported content is marked as arriving from outside a keystroke. It is fully yours and fully searchable; it is simply distinguishable from what you typed, which is what lets an agent tell your words from a web page you saved.

---

# Security and your data

Who can read what, what leaves the machine, and what deletion actually removes.

## Isolation

Every workspace-scoped table in the database carries a row-level security policy, forced even for the account the application connects as. The policies fail closed: a query that does not establish which workspace it is acting for returns zero rows rather than somebody else’s.

Which workspace a request acts in comes from your credential, never from the request body or a query parameter. Naming a workspace you are not a member of returns nothing.

## Credentials

- Tokens are shown once, at creation, and stored only as a hash.
- Tokens always expire. There is no non-expiring agent credential.
- A token’s prefix is greppable and self-identifying, so a leak is easy to recognize. Settings → Agents & tokens lists every live token by label, scopes and last use, and revokes it there.
- Revoking a token revokes every token delegated from it, and every outstanding write handle it minted.
- A delegated token can only ever narrow its parent.

`fp login` uses the device authorization flow, so a terminal never holds your password. Approval happens in a browser, and the workspace comes from the approving session rather than from the device asking.

## Secrets in your notes

Developers keep credentials in notes. Fastpad detects them with deterministic rules — the same rules a secret scanner uses — and masks them on the way out, never in the document.

Two parts of that matter. It is never a model deciding: a probabilistic safety property is not a safety property. And it never edits your note: redaction happens when content leaves, so your own note keeps saying what you wrote.

A false positive becomes a visible placeholder you can expand, never silent loss.

## What leaves the machine

Outbound access is denied by default. A tool returning a link from your notes hands back a neutralized reference rather than a live URL unless the token carries an explicit host allowlist.

Note content is treated as data everywhere it reaches a model — fenced, quoted, and never as instructions. That is the premise behind the whole proposal model: a note can say anything, including “ignore your instructions”, and it is text either way.

## Publishing

A published note is readable by anyone with the link, and nothing else in the workspace is. Only a signed-in person can publish — an agent that could publish could exfiltrate a workspace by making it public and reading it back.

To an anonymous caller, a note that is unpublished, a note that was deleted and a note that never existed are indistinguishable. The public route cannot be used to find out which identifiers are real.

## Deletion and erasure

Trash is reversible and keeps everything. Purging removes the rows after the retention window. Those two are what “delete” normally means.

Erasure is a stronger claim and a different mechanism: each note’s content is encrypted under its own key, so erasing means destroying that key. It is the only way to make the copy on a laptop that has been offline for a year unreadable — and it is why deletion and erasure are named separately here rather than treated as the same act.

Your notes leave whole, at any time, as Markdown you can read with anything: [the mirror](/en/docs/markdown), the export, or the API.