# Note Note — project documentation

These documents are written for whoever works on Note Note next — including
the author six months from now. They record *why* things are the way they
are, and the mistakes that are expensive to repeat.

| Document | Read it when |
|---|---|
| [Business requirements](business-requirements.md) | deciding what the product should or should not do |
| [Technical requirements](technical-requirements.md) | changing the architecture, adding a provider, touching the host |
| [Standalone app and shared hosts](standalone.md) | building, installing or extending either launcher and its platform adapter |
| [Flatpak](flatpak.md) | building or installing the standalone Linux bundle and configuring its sandbox |
| [Themes](themes.md) | selecting colors, authoring JSON themes, and understanding System values |
| [Commands](commands.md) | writing commands and using the generic picker |
| [Application plugins](plugins.md) | installing packages, trust, provider migration, and removal |
| [Editing tools](editing-tools.md) | adding a toolbar action, shortcut, menu or tool panel |
| [Status bar](status-bar.md) | registering a status control or creating a custom one |
| [Security rules](security.md) | writing any code that reads a file, spawns a process, or talks to a network — **and before every release** |
| [Engine notes](engine-notes.md) | fighting Qt, QML, Markdown, Graph or Notion; check here before debugging |
| [Known bugs](known-bugs.md) | seeing odd behaviour that may already be understood, or checking whether a Qt upgrade fixed one |
| [Testing](testing.md) | verifying a change without a keyboard and without touching real notes |
| [Release process](release-process.md) | cutting a release or answering the marketplace |
| [Decisions](decisions.md) | wondering "why wasn't this done the obvious way?" |

The user-facing documentation is [`../README.md`](../README.md); the provider
contract is [`../docs/providers.md`](../docs/providers.md).

## The short version

Note Note shares one workspace between an Omarchy shell plugin (overlay or
detached window) and a standalone Qt 6 Linux application. Both show a sidebar
of notebooks and one always-editable note. Notes come
from **providers** — local Markdown folders, Microsoft Sticky Notes, OneNote,
Notion, and anything a user drops into
the host's external provider directory. The workspace knows nothing about any
backend; providers know nothing about the UI.

Three rules that everything else follows from:

1. **The user's notes are the product.** Never lose, duplicate or corrupt
   them. When in doubt, open read-only rather than risk a bad write.
2. **Every input is bounded and untrusted** — file, HTTP body, page content.
   See [security.md](security.md).
3. **A provider owns its backend**: its own setup, credentials, caches,
   limits and quirks. The host owns the window, the list and the editor.