Defining the Goal

The scope of a tool like this is decided mostly by what you refuse. I wrote the first AGENTS.md before the first Go file, because the shape of the non-goals is what keeps a knowledge base from turning into an everything-machine.

What It Is

A local desktop knowledge base. It runs as one binary with a tray icon, serves a PWA from a loopback-only HTTP service it owns, and stores everything as Markdown in a vault directory. Sources are read once and distilled—into claims, then into pages—and the result stays current. The connections between notes are as valuable as the notes themselves.

Two users: me, curating sources and asking questions; and the agent, which does all the writing.

What It Is Not

• Not a RAG lookup. No embeddings, no vector database. Retrieval is reasoning over trees, indexes, the link graph, and lexical search. Similarity is not relevance.
• Not a general document tool. Three source kinds—Markdown, PDF, TXT—plus URLs. No .docx, no images, no archives, no audio or video. A smaller input surface is a feature: every format we accept, we accept well.
• Not a server. No LAN exposure, no systemd unit, no daemon, no multi-user. The HTTP service is internal to the app; its only clients are the embedded UI and the CLI.
• Not an authoring IDE. The PWA is a reader. The agent writes; I read and curate. Write endpoints exist for tooling, not as a workflow.
• Not a crawler. It fetches the URLs I hand it, one at a time. No site walking, no feeds.
• No sync in v1. When sync arrives, it is another project’s job.

The “No Silent” Rules

These three rules turned out to be the real spec, because they are what make an agent-driven system trustworthy.

• No silent OCR. If a PDF has no text layer and the OCR tools are missing, the source is flagged unsupported_source —it is never quietly empty.
• No silent writes. Every agent mutation goes through the same use cases as any other write, and every run is recorded with its tool calls and token usage. There is no back door into the vault.
• No silent degradation. If FTS5 is unavailable, the app logs loudly, the status report shows search: degraded, and search falls back to LIKE. It tells you; it does not pretend.

Slogans as Constraints

Settled early and never revisited: “Markdown-based notes and knowledge database” for the outside, and for the inside, “if losing it would lose knowledge, it belongs in the vault; if it can be recomputed, it belongs in the index.” That one sentence later decided where the database, the trees, and the favicons live.

Scope is defined here by refusal rather than ambition. The chapter fixes what the app is—a local desktop reader over an owned vault—and what it is not: a RAG pipeline, a server, a multi-user product. Each exclusion becomes a rule that can be quoted later, which is the difference between a boundary and a preference. The ‘no silent’ rules extend the same discipline to failure: a source that cannot be read is flagged, never quietly empty.