notescraft/specs/registry/spec.md

NotesCraft registry: separable add-ons, and an honest debloat plan

Status: draft for owner review (2026-10-21). Numbers: measurements.md. Tasks: tasks.md. Owner request: "separate some of the plugins and certain things from the current application, add them to the notescraft registry, to debloat the app so it doesn't feel heavy".

0. Verdict first

1. The registry is the right mechanism for choice and growth, not for the weight the app has today. Measured on this tree: binary 38.4 MiB, RSS 131 MB idle (physical footprint 72 MB), 0.3 s CPU to idle. Everything that could move to a registry today (extra grammars, math font, Lottie icons, Lucide long tail, extra themes) is about 0.7 MiB, 2 % of the binary, and moves no startup or RSS number you can feel.
2. The real, cheap debloat needs no registry and is about 10 MB (25 %): strip symbols on macOS and Windows (-5.4 MB measured), fonts (-0.8 MiB duplicate Inter, about -1 MiB unused egui default fonts, -0.26 MiB duplicate mono), opt-level = "s" (-2.8 MB more, perf unmeasured). Fonts are 4.2 MiB, 11 % of the file, more than all the optional crates together.
3. Why it "feels heavy" is vault data, not features: a 6500-note vault peaks at 494 MB while indexing and settles at 220 to 380 MB. No add-on mechanism changes that; it needs its own spec (open question 9).
4. The wasm plugin host is not wired into the app at all (Session::load_plugins has no non-test caller; wasmi is 0 bytes in the shipped binary). The registry cannot deliver plugins until that is wired, and wiring adds an estimated 0.8 to 1.2 MiB. Order of work matters: do the no-registry savings first, or the registry makes the binary bigger before it makes it smaller.
5. The registry still earns its place: it stops the binary growing (every new grammar, theme, template, small command lands outside it), gives users choice, and finishes a half-built feature (grammar.install, an empty notescraft-registry repo, plugins/dice).

So the plan has three layers, in this order: P0 size fixes without a registry; P1 a small, signed, offline-first registry (one engine module, no new crate); P2 move the few things that fit, to prove the pipeline and bank the 35 ms and 0.7 MiB.

1. What exists today (reuse, do not rebuild)

• Registry repo https://git.marcospaulo.dev.br/masi/notescraft-registry (local clone /Volumes/Storage/Projects/notescraft-registry), index.json with four empty lists, README schema. Schema mismatch to fix: the README names the key name, the engine (crates/engine/src/grammars/mod.rs::registry_entry) reads id. No entry was ever published, so no compatibility burden.
• Grammar flow: grammar.info|install|install_text|remove, gates in crates/syntax/src/{fetch,validate}.rs (https only, no credentials or IP literals, host allow-list REGISTRY_HOST, no redirects, 512 KiB cap, sha256, parse and sample), transport Curl (a curl subprocess) behind a Transport trait, state in AppSettings::grammars (max 64) and files in <settings dir>/grammars/.
• Themes: user themes are <settings dir>/themes/*.toml (prefs/themes.rs, max MAX_USER_THEMES, ids may not reuse a built-in).
• Plugins: crates/plugins (wasmi host, ABI v1, manifest with permissions allow-list), folder <vault>/.notescraft/plugins/<id>/{manifest.json,plugin.wasm}, approvals kept in settings, sample plugins/dice (4.8 KB). No view, panel, settings or event hooks (ABI v1); UI-contribution ABI is roadmap item 25.
• sha2 is approved; ureq (rustls, which brings ring) is already linked into the engine; craft-atomic offers atomic_write(path, bytes) and write_new(path, bytes).
• Core plugin cards in Settings (Calendar, Templates, Diagrams, Whiteboard) only toggle features that are compiled in. They are organisational, not size.
• Name clash to avoid: crates/engine/src/registry is the command registry. The new engine module is addons/; command ids are registry.*.

2. Classification of everything that could move

Legend: core always in the binary; lazy stays in the binary, initialised on first use; feature cargo feature (compile-out); pack downloadable assets; wasm plugin on ABI v1; UI-ABI blocked on roadmap item 25. "Effect" is measured unless marked est.

Item	Class	Effect on size / startup / RSS	Honest note
egui, wgpu, winit, text shaping, image codecs, serde, regex, TLS	core	9 MiB of .text	cannot move
ui-egui (4.2 MiB), engine (1.8 MiB), vault, markdown, index, editor, i18n, themes, search, backlinks, links, tags, properties, bases core, templates, tasks, lint, blocks	core		the product
Inter Regular/SemiBold/Medium, JetBrains Mono NoLigatures	core
Duplicate Inter Regular + SemiBold in engine PDF export	fix in place (share one const)	-0.79 MiB	no registry
PDF export JetBrains Mono Regular	fix in place (use NoLigatures)	-0.26 MiB	no registry
egui default_fonts (Hack, Ubuntu-Light, emoji-icon-font; keep NotoEmoji)	fix in place (drop the eframe feature, embed NotoEmoji only)	about -0.95 MiB (est)	needs a snapshot check for tofu
Symbols (__LINKEDIT)	release profile strip = "symbols"	-5.38 MB	losing symbol names in crash backtraces is the cost
opt-level = "s"	release profile	-2.8 MB more	measure index build and scroll first
syntect default pack (75 grammars, 0.37 MiB, built on first fence: 75 ms)	lazy (already)		trimming it needs a custom dump; skip
25 NotesCraft grammars (Twig, Blade, Svelte, Vue, Nix, Zig...)	pack grammar	-69 KB, -35 ms first highlight, repeated at every set_installed	best first mover: tiny, pure text, proves the pipeline
STIX Two Math font (math only)	pack font	-0.36 MiB	math falls back to Inter/JetBrains glyphs and boxes until installed; needs the seed (section 11)
Lottie icon animations (65 JSON, 0.14 MiB)	pack pack	-0.14 MiB	static icons already exist; animation is polish
Lucide long tail (278 catalogue vs the ~89 used)	pack	at most -0.07 MiB	not worth the complexity; skip
en.toml (61 KB)	core		future locales ship as pack (language packs): zero cost now, the one place the registry clearly pays
Extra built-in themes (Frappe, Macchiato, Solarized x2)	pack theme	under -10 KB	worth it only as the first theme entries, for the browser to show
Community-style themes, template sets, snippets	pack / theme / snippet	0 (they never were in the binary)	the real value of a registry
Extra Hebrew/Arabic system fallback read at launch (SFHebrew, SFArabic)	lazy	-0.8 MB RSS, 1 disk read	use the existing script-on-demand loader
CJK and other script fonts	none		already not bundled: fonts::install loads system fonts per script on demand. A Noto download pack is only for Linux without them; defer
Wasm plugin host (wasmi)	feature plugins, default on	0 bytes today (not linked), -37 CPU-s of compile; +0.8 to 1.2 MiB (est) once wired	wire it first (task 12), then the feature exists for CLI/server builds
Dice roller, Citations (roadmap 10), word tools, small text commands	wasm (ABI v1: vault.read, vault.write, editor)	4.8 KB each, 0 in the binary	the only real "plugins" that fit today
Importers (Notion zip, ENEX, Roam)	needs a host call for zip/file import, or stays in-tree		ABI v1 has no file import and no binary input: not wasm yet
Calendar (170 KB + 2.9k UI lines + 2k engine lines), Whiteboard (57 KB + 5.9k UI), Diagrams, Canvas, Graph, Bases Map/Cards, Kanban, Slides, Charts, Mind map, Maps	UI-ABI (item 25) to become wasm; feature to compile out	all optional crates: 1.15 MiB .text; with their UI and engine halves 2.5 to 3.5 MiB (est), 7 to 9 %	extracting them to wasm needs views, panels, settings, events. Cargo features alone save little for the desktop app and cost a large refactor; only do it for the CLI/server builds
Vim, assistant (ACP), knowledge (RAG), pdf export, git, collab	feature candidates	0.1 to 0.4 MiB each, est	organisational for the desktop app; useful for slim CLI/MCP builds
Map tile providers	snippet presets	0	network policy already opt-in (bases D13); a preset list is data
Pandoc	external helper, detected on PATH	0	do not download executables in v1 (open question 5)
Video	external player via shell/app/video/launch.rs	0	already a helper, not bundled
OCR backend (attachment-ocr spec)	helper binary pack, later		needs its own trust model; out of scope here

What actually reduces what:

• Binary size: P0 (about 10 MB), then fonts-as-pack and Lottie (0.5 MiB). Cargo-feature compile-outs are the only big code lever and are a refactor, not a registry job.
• Startup: the grammar rebuild (-35 ms of 110 ms on first fence) and lazy fallback fonts. Nothing else measured moves.
• RSS: nothing in this spec measurably does; the levers are index memory and egui/GPU surfaces.
• Only organisational: core plugin cards, moving crates between folders, the Lucide tail.

3. Goals and non-goals

Goals: a signed, static, offline-first catalogue of add-ons the user installs on purpose; one engine surface (commands, CLI, MCP, UI); zero loss for anyone upgrading; hostile content cannot write outside its own folder or run anything without consent.

Non-goals (v1): third-party publishing flow or accounts; a download counter; payments; automatic code execution; executable downloads (pandoc, ffmpeg); archive formats; plugin sandbox changes; UI-contribution ABI (item 25); a custom registry URL (open question 4).

D1. Hosting and index

• v1 host: the existing Gitea repo masi/notescraft-registry, raw layout raw/branch/main/. No server work, history is the audit log, the host allow-list REGISTRY_HOSTS = ["git.marcospaulo.dev.br"] already exists (becomes a list). Mirror later by adding a host to the allow-list and url in entries.
• Optional later: the sync server serves the same tree from a directory with one read-only route GET /registry/{*path} (about 30 lines in apps/notescraft-sync-server/src/api/routes.rs, public like /p/{slug}, no auth, no vault data, file allow-list by extension, caches by ETag). Not needed for v1; listed because the owner asked whether it could host one: yes, but a git repo is simpler and already trusted.
• Files: index.json at the root; payload files under files/<kind>/<id>/<version>/<name>.
• The app caches the last verified index at <data dir>/registry/index-cache.json with fetched_at and etag; a conditional GET (If-None-Match) keeps checks near-free.
• Index cap 1 MiB, at most 2000 entries; a bigger or non-JSON index is refused and the cache stays.

D2. Index schema v2

{
  "version": 2,
  "generated_at": "2026-10-21T12:00:00Z",
  "entries": [
    {
      "id": "twig",
      "kind": "grammar",
      "title": "Twig",
      "summary": "Twig templates",
      "version": "1.0.0",
      "min_app_version": "0.1.0",
      "license": "MIT",
      "source": "https://github.com/...",
      "aliases": ["twig", "html.twig"],
      "suggested": false,
      "permissions": [],
      "files": [
        { "path": "twig.sublime-syntax", "size": 3912, "sha256": "<64 hex>", "url": "https://git.marcospaulo.dev.br/masi/notescraft-registry/raw/branch/main/files/grammar/twig/1.0.0/twig.sublime-syntax" }
      ],
      "signature": { "key_id": "k1", "sig": "<base64 ed25519>" }
    }
  ],
  "revoked": [ { "id": "old-thing", "version": "0.9.0" } ]
}

Fields (all required unless "optional"): id [a-z0-9-]{1,48} unique per kind; kind one of plugin theme pack grammar font snippet; title 1..80; summary 0..200 (optional); version MAJOR.MINOR.PATCH, each 0..9999, no pre-release; min_app_version same shape; license SPDX-like 1..40; source https URL (optional, display only); aliases (grammar: fence labels; others: search words), at most 16, each [a-z0-9._+-]{1,32}; suggested bool (optional, first-run list); permissions (plugin only, must be a subset of the known Permission strings; unknown rejects the entry); files 1..64, each with path, size, sha256, url; signature. The README's file becomes files[].url relative form is not allowed: urls are absolute https on an allow-listed host.

Derived, never in the file: total size = sum of files[].size.

Caps per kind (sum of file sizes): plugin 4 MiB, theme 64 KiB, grammar 512 KiB (the existing cap), snippet 1 MiB, pack 8 MiB, font 32 MiB. One file at most half of the cap of 32 MiB for fonts, otherwise the whole cap. All checked against both the index size and the bytes actually received.

Validation lives in addons/index.rs; one broken entry is skipped with a diagnostic, the rest of the index loads (same rule as plugin folders). A wrong version at the top rejects the index.

D3. Trust and signatures

• Every entry carries an ed25519 signature by the owner-held key over a canonical text: notescraft-registry-v1\n<id>\n<kind>\n<version>\n then for each file sorted by path: <path>\n<sha256>\n<size>\n. The signature therefore covers every hash and size; the index itself can stay unsigned (tampering with it can only add entries whose signature fails, which is a denial of service, not code execution).
• The app embeds the public keys: addons/keys.rs TRUSTED_KEYS: [(&str, [u8; 32]); N], key_id selects one, so a rotation is a release that adds k2 and later drops k1. The private key never enters this repo; it lives with the owner. Signing happens in the registry repo with a small tool (xtask registry-sign over a directory, task 18).
• revoked lets a release be pulled; an installed revoked version is marked and the UI offers Remove or Rollback. The index is unsigned, so an attacker can hide revoked; stated, accepted for v1, solved by signing the index (open question 2).
• Dependency question for the owner: verification needs an ed25519 implementation. Options: (a) depend on ring directly, already in the lockfile and linked through rustls, adds roughly nothing to the binary; (b) ed25519-dalek; (c) no signatures, rely on HTTPS plus sha256 plus the host allow-list. Recommendation: (a), written approval needed (AGENTS.md rule on new dependencies). Until answered, task 3 is blocked and installs must be refused for entries without a valid signature, so the feature cannot ship half-secure.
• A sideloaded or seed file (section 11) is verified with the same signature check; there is no "trust me" path.
• Integrity beyond signatures: plugin manifests inside the downloaded files must match the index entry (id, version, permissions, commands), or the install fails.

D4. Local layout

All add-on state lives under the app data dir, never in a vault (so a synced vault cannot ship code):

<data dir>/registry/            data dir = craft_settings::paths::data_dir("notescraft"), override NOTESCRAFT_CONFIG_DIR
  state.json                    installed table, written with craft-atomic (version 1)
  index-cache.json              last verified index + fetched_at + etag
  store/<kind>/<id>/<version>/  immutable once state points at it; files exactly as in the entry
  staging/<random>/             downloads in progress; emptied at every start

state.json: { "version": 1, "installed": { "<kind>:<id>": { "version", "previous": "1.0.0"?, "source": "registry|legacy|seed|sideload", "installed_at", "sha256_of_files": "<hex>" } } }. At most 512 installed entries.

Per-vault file <vault>/.notescraft/registry.json (written with Vault::write_private): { "version": 1, "enabled": ["plugin:dice"], "wanted": ["grammar:twig"] }.

• enabled: plugins on in this vault (plugins are the only kind that is per-vault; permissions approvals stay in settings as today).
• wanted: ids this vault has been seen to use (a Twig fence). A new machine opening the vault shows one banner "This vault uses 2 add-ons" with an Install button. Nothing is installed from it automatically.

Grammars, themes, fonts, packs and snippets are global (user level); enabling = installed. Rollback keeps one previous version dir per id.

D5. Network policy

No network unless one of three things happens, all user-initiated:

1. the user opens Settings > Registry (one conditional GET of index.json; not at app start);
2. the user presses Install, Update, Check or an install button on a card;
3. the setting registry.update_checks is on (default off): at most one conditional GET per 24 h, started after the window is idle, no identifiers, User-Agent: NotesCraft/<version>, no vault data, no cookie.

Everything else (search in the browser, first-run suggestions, "this vault uses X") reads the cached or seed index and works offline. A failed fetch leaves the cache and state untouched and shows "Offline" (the offline error code exists). Same gates as grammars on every URL: https only, host allow-list, no credentials, no IP literal, no redirects (syntax::validate::check_url). Transport: ureq (already linked, no subprocess); the Transport trait stays injectable so tests never touch the network.

D6. Install, update, remove, rollback

All entry operations are one function addons::install::run(plan) over an injected Transport:

1. Resolve the entry from the cached or fresh index; refuse if min_app_version is newer than the app, if revoked, if the kind has no consumer yet, if a file list check fails (D7), or if the signature does not verify.
2. Check free disk space (twice the entry size) and the installed-table cap.
3. Download each file to staging/<random>/<path> through the transport: streaming, hard cap per file and per entry, sha256 computed on the bytes actually received (a lying Content-Length does not help), abort on the first mismatch.
4. Per-kind content check on the staged bytes (D8). A failure deletes staging; nothing else changed.
5. Write the final tree store/<kind>/<id>/<version>/<path> with craft_atomic::write_new per file (refuses to overwrite). The version directory is unreferenced until step 6, so a crash leaves garbage, not a half-install. Garbage (version dirs not in state, staging) is removed at the next start.
6. Flip state.json with craft_atomic::atomic_write (the only commit point): set version, keep the old one in previous.
7. Tell consumers to reload (grammar set rebuild, theme list, plugin set).

update = install of a newer version of an installed id. Downgrade is never an update; only rollback. remove deletes the state entry first (commit point), then the store dirs, then reloads consumers; blocks of a removed grammar fall back to plain monospace (existing behaviour), a theme in use falls back to the built-in of the same variant with a notice, a plugin is unloaded. rollback swaps version and previous in state.json (the old dir is still there) and reloads.

D7. Hostile input (no archives by design)

Entries are file lists, not archives: no zip or tar anywhere, which removes zip-slip, symlink and decompression-bomb classes without a parser. What remains, all in addons/fileset.rs, pure and unit-tested:

• path: relative, /-separated, 1..4 components, each [A-Za-z0-9._-]{1,64}, no component empty, . or .., none starting with ., no \, no :, no NUL, no Windows reserved device name (CON, NUL, COM1...) as a component, no case-insensitive duplicates, extension on the allow-list of the kind (plugin manifest.json and plugin.wasm and optional README.md; theme .toml; grammar .sublime-syntax; font .ttf .otf; snippet .md .txt .toml; pack: each file under grammars/, themes/, templates/ or icons/ with its own extension list). The joined path is built by the code from validated components, never by string concat of server text.
• Sizes: per kind caps from D2, at most 64 files, no zero-size file, sum with checked_add.
• URLs: check_url plus url host in the allow-list, length cap, no query string.
• Download: streamed with a hard cap; received bytes and sha256 must match the entry; a body shorter or longer is a failure; slow-loris bounded by a total time limit (30 s per file, 5 min per entry).
• Never execute: nothing from the store is run except plugin.wasm through the existing sandbox (fuel, memory, deadline limits, 3-failure auto-disable) and only after the user approved its permissions.
• Writes go to <data dir>/registry/ only; the reserved vault paths .obsidian/ and .notescraft/ rules are unchanged; .notescraft/registry.json is written only through write_private.
• JSON bounds: index and state parse with the existing serde_json depth limit, strings capped, unknown version is Err, nothing silently repaired.

D8. Kinds

Kind	Installed as	Consumer	Per-kind check
grammar	store/grammar/<id>/<v>/<id>.sublime-syntax	syntax::load::set_installed fed from state (legacy AppSettings::grammars also read)	syntax::validate::check_grammar with the entry's sample
theme	store/theme/<id>/<v>/<id>.toml	Session::user_themes scans state too	Theme::from_toml; zero hard diagnostics; id equals entry id; no built-in id
plugin	store/plugin/<id>/<v>/{manifest.json,plugin.wasm}	the plugin loader reads installed plugins listed in the vault's enabled; approvals as today	Manifest::parse, manifest equals entry, a dry Plugin::load with default limits
pack	several files under grammars/ themes/ templates/ icons/ in one version dir	each consumer reads the pack's subfolder	every file runs its own kind check
font	store/font/<id>/<v>/<file>	the script-on-demand font loader may use it before system fonts; not required for v1 consumers	ttf-parser-free check: magic bytes 00 01 00 00, OTTO or true, size cap (no new dependency)
snippet	store/snippet/<id>/<v>/*.md	templates list (insert from the template picker)	UTF-8, size cap, no NUL

Kinds font and snippet are accepted by the index and the installer so the schema is complete, but a kind with no consumer yet is shown as "Not available in this version" and cannot be installed (D6 step 1). The first consumers to build are grammar, theme, plugin, pack.

D9. Engine commands (all in crates/engine/src/addons/commands.rs)

Group registered by register_addons(reg) called from commands.rs::register_core. Ids use the user-facing prefix registry..

Id	Params	Does	Network	Gate class
registry.list	kind?, query?, state? (installed, updates, available), limit?	cached or seed index joined with state.json; each row: id, kind, title, version, installed version, size, state (available, installed, update, revoked, incompatible, unsupported), permissions	no	READ
registry.info	kind, id	one entry in full: files, sizes, license, source, signature key id, what a plugin may do	no	READ
registry.check	none	conditional GET of the index, verify, replace the cache, return update counts	yes	DELETE-class (see below)
registry.install	kind, id, version?	D6	yes (or seed)	DELETE-class
registry.update	kind?, id? (none = all with updates)	D6 per entry	yes	DELETE-class
registry.remove	kind, id	D6	no	DELETE-class
registry.rollback	kind, id	D6	no	DELETE-class
registry.enable / registry.disable	id (plugin)	per-vault enabled list; enabling asks the existing permission approval	no	WRITE
registry.suggest	label or kind+query	alias lookup in the cached index; used by the grammar card	no	READ

Assistant gate (crates/engine/src/ai/assistant_gate.rs): registry.list, registry.info, registry.suggest join READ_COMMANDS. registry.enable|disable join WRITE_COMMANDS. The five that fetch or remove third-party code (check, install, update, remove, rollback) join DELETE_COMMANDS, so an assistant needs both allow_write and allow_delete, the same treatment as sync.pair and server.connect (trust-expanding actions). Test: tests/core_commands.rs CORE_IDS and a gate test per id.

Errors (CommandError codes): registry_refused (a gate failed, message names it), offline, not_found, incompatible (app too old), revoked, limit, disk_full, needs_dependency (no signature verifier yet). Existing grammar.* commands stay as thin aliases that call the same code and keep their codes.

CLI parity: notescraft run registry.install --params '{"kind":"grammar","id":"twig"}' already works through the generic Run; task 9 adds notescraft registry list|info|check|install|update|remove|rollback as sugar in apps/notescraft-cli/src/args.rs and commands/, printing id, version, size, state. MCP gets them through the registry automatically.

D10. UI (Settings > Registry)

New Settings category in views/settings_view/categories.rs, view folder views/registry_view/ (library components only: Button, Input, Switch, Modal, ConfirmModal; i18n keys under [ui.registry]; theme tokens only).

• Top row: search Input, kind chips (All, Plugins, Themes, Packs, Grammars, Fonts, Snippets), "Check for updates" Button, "Last checked " or "Never", Switch "Check for updates automatically" (off).
• List rows: title, kind chip, version, size, short summary, state: Install Button, Installed check, Update to 1.2.0 Button (accent), Needs NotesCraft 0.3, Revoked, Not available in this version. Update badge: a count dot on the Settings entry and on the category, only after a check.
• Detail drawer: summary, license, source link, files and sizes, permissions as sentences ("Read notes and search", "Create and change notes", "Edit the open note") for plugins, signature key id, Remove and Rollback Buttons.
• Offline banner when the last fetch failed; the list then shows the cache.
• Plugin install ends with the existing permission approval modal, then an Enable Switch for the current vault.
• First-run suggestions: once, after the first vault opens following install or upgrade, a dismissible card "Add-ons you may want" listing the entries with suggested: true from the seed index plus anything registry.suggest found for this vault. It never fetches; its Install buttons do (D5 trigger 2).
• Code card (views/note_view/blocks/code_card.rs): the existing "Add grammar" link becomes "Install Twig grammar (3.9 KB)" when registry.suggest finds the label, falling back to today's dialog (paste a link) when it does not.
• Snapshot example flag --registry for visual checks; the screens follow the PaperCraft tokens (rounded cards on canvas, tone not borders).

D11. Migration: nobody loses anything

Rule: nothing leaves the binary in the same release that adds its registry entry, and every removal ships with a path that needs no thought.

1. Release N adds the registry, adopts legacy grammars (source: legacy, shown as installed, no update), keeps everything bundled.
2. Release N+1 removes an item from the binary only if all hold: its entry is published and signed; the seed copy (below) is in the installer; a migration test exists.
3. Seed: the installer carries registry-seed/{index.json, files/...} next to the binary (macOS Contents/Resources/, Windows and Linux beside the exe), a verified signed snapshot of the moved items only (about 0.6 MiB). install prefers the seed file when its sha256 equals the entry, so moved items install offline, instantly. Seed items are not auto-installed. The DMG size does not change; the binary shrinks.
4. Auto-offer by use, no network:
   • a fence label that is no longer bundled: the code card asks registry.suggest and shows "Install Twig grammar", one click; with registry.auto_install_for_vault on (default off, open question 3) it installs from the seed without asking;
   • first launch of N+1: a background scan (ripgrep crates already in the engine, 3 s budget, once per vault and per registry generation) of fence labels and $ math in the opened vault records wanted in .notescraft/registry.json and shows one banner "This vault uses Twig, Blade (2 add-ons, 7 KB): Install";
   • a selected theme that moved: the app keeps the id, falls back to the built-in of the same variant until installed, and the Settings theme picker shows it with an Install button;
   • math without the font: formulas fall back to the Inter/JetBrains glyph chain (already the last resort) and the math view shows an Install button.
5. Tests (task 19 to 21 each): for every moved id, registry.suggest finds it, the seed verifies, registry.install from the seed in an offline temp session makes grammar.info report installed, and removal returns the old fallback behaviour.

D12. First-party content, ordered by measured benefit

#	Item	Size	Gain	Needs
P0.1	strip = "symbols" in the release profile (macOS, Windows)	-	-5.38 MB	nothing
P0.2	share one Inter Regular/SemiBold const, PDF mono = NoLigatures	-	-1.05 MiB	brief 29
P0.3	drop eframe default_fonts, embed NotoEmoji only	-	about -0.95 MiB	snapshot check
P0.4	opt-level = "s"	-	-2.8 MB	perf measurement
P1.1	wire load_plugins (+ ~1 MiB, est)		enables plugins	task 12
P2.1	pack grammars-extra (25 grammars as 25 grammar entries)	69 KB	-69 KB, -35 ms first highlight	tasks 19
P2.2	font stix-math	376 KB	-0.36 MiB	task 20
P2.3	pack icons-animated (Lottie)	148 KB	-0.14 MiB	task 21
P2.4	plugin dice (exists), then citations	4.8 KB	0 binary, first real plugin	task 22
P2.5	themes Frappe, Macchiato, Solarized	under 10 KB	negligible, fills the browser	task 22
later	language packs when a second locale exists	60 KB each	keeps en-only core

P2.x together: about 0.6 MiB, 1.5 % of the binary. Say it plainly to users: the registry makes the app extensible; the size win is P0.

D13. Tests and acceptance

• Pure: index parse and every rejected shape; fileset table of hostile paths (../x, a/../../b, /abs, C:\x, a\b, .hidden, a//b, names with a space or NUL, Windows reserved names CON, NUL, COM1 as a whole component, duplicates differing only in case, a 65-char component, 5 components, an empty path); caps with u64::MAX sizes (checked add); signature canonical text; version compare; state round trip; unknown version.
• IO (TempDir, fake Transport): happy install of each kind; hash mismatch; short body; long body; lying size; transport error mid-file; crash simulation (stop before the state flip) leaves the old state and GC removes the new dir; update keeps previous; rollback; remove while in use; seed install offline; index with a revoked version; app too old; invalid signature; unknown key id.
• Gate and commands: all ids in CORE_IDS; gate classes; read-only session refuses mutating commands.
• UI (kittest): rows by state; Install sends exactly one command; offline banner; permission sentences; update badge appears only after a check.
• Size acceptance (measured, not promised): after P0.1 to P0.3 the macOS binary is at most 33 MB (from 40.2 MB); the registry module itself adds at most 250 KB (estimate for index, installer, validators, UI) and wiring plugins at most 1.2 MiB; both are re-measured with the commands in measurements.md and written into this file and docs/ARCHITECTURE.md.
• cargo xtask ci, cargo xtask i18n, cargo xtask layers, cargo xtask tree green; no unwrap, [i], [a..b]; every public item documented; files under 400 lines; at most 12 loose .rs per directory (addons/ is grouped into index/, install/, commands/ from the start).

Open questions for the owner

1. Ed25519 dependency: approve ring as a direct dependency of notescraft-engine (already in the lockfile through rustls), or ed25519-dalek, or choose no signatures? Recommendation: ring, plus xtask registry-sign also using it. Blocks task 3 and every install.
2. Sign the index too (one extra detached signature, stops hidden revoked and replay of an old index)? Recommendation yes, 20 lines, after question 1.
3. Auto-install for a vault that uses a moved item: your words were "installed automatically if the vault uses it". This conflicts with "no network unless the user opts in". Proposal: seed files make it offline and instant, so auto-installing from the seed can be on by default (no network), while anything that needs the network asks. Confirm.
4. Custom registry URL / third-party registries: not in v1 (host allow-list is fixed to yours). Allow later with a per-registry key?
5. Executables (pandoc, ffmpeg, OCR engines): not downloaded in v1; they stay "detected on PATH". Confirm, or ask for a separate trust design.
6. Ship seed files in the installer? Costs about 0.6 MiB of installer size, buys offline migration. Alternative: network only.
7. Release profile: approve strip = "symbols" (crash backtraces lose function names; line tables are already debug = line-tables-only in dev only) and, after a perf run, opt-level = "s".
8. Drop the egui default_fonts feature and embed only NotoEmoji (about -0.95 MiB): accept if the snapshot comparison shows no tofu in the UI chrome.
9. Index memory: the 6500-note vault peak of 494 MB and 220 to 380 MB steady is the real "heavy". Want a separate measurement and spec for it?
10. Naming: engine module addons/ and user-facing "Registry" / registry.*: fine?