core/docs/DESIGN-notes-v011x.md

# DESIGN: Notes Reference Extension — v0.11.x

## Status: Proposed

## Purpose

Notes becomes the first **reference extension** — a first-party package
that exercises every kernel primitive and proves the platform is capable
of delivering a production-quality application. This is not a toy demo;
it is the answer to "what can you build on Armature?"

The v0.11.x series takes the existing notes package (folders, tags,
wikilinks, graph, CM6 editor, three view modes) and builds it into a
full-featured knowledge base comparable to Obsidian, Notion, or Logseq —
but running on Armature's extension architecture.

**The UI must be clean, inviting, and genuinely enjoyable to use.** The
current notes surface is functional but visually mechanical — no
personality, no micro-interactions, no sense of craft. If the reference
extension feels like a developer prototype, the platform pitch fails
regardless of how many kernel primitives it exercises. v0.11.0 is a
full visual redesign before any feature work begins, and every subsequent
version ships with UX quality built in, not bolted on.

### What Notes Exercises

| Kernel Primitive | How Notes Uses It |
|-----------------|-------------------|
| `db.write` | Notes, folders, tags, links, shares tables |
| `sw.renderers` | Markdown rendering pipeline, custom block renderers |
| `sw.panels` | `notes.reference` panel (from v0.10.4) |
| `sw.slots` | Declares `notes:toolbar-actions`, `notes:note-footer` for extension composition |
| `sw.events` | Realtime updates, panel ↔ surface communication |
| `sw.markdown` | Unified markdown rendering with wikilink extensions |
| `sw.shell.topbar` | Topbar slots for navigation context |
| `sw.storage` | Editor state, sidebar collapse, preferences |
| `sw.actions` | Exports `notes.create`, `notes.search` for cross-package calls |
| Resource grants | Note and folder sharing via kernel permission model |
| Starlark sandbox | All backend logic in `script.star` |
| Settings cascade | Per-user editor mode, default view, daily note folder |
| Surfaces | Multi-surface: full editor + public read-only surface |

---

## What Already Exists (v0.9.0)

### Frontend (1,806 lines — `js/main.js`)

- **NotesApp** — main shell with sidebar + editor layout
- **FolderTree / FolderNode** — tree with expand/collapse, context menu,
  drag-and-drop note→folder, rename, create sub-folder (schema has
  `parent_id`, UI renders depth)
- **NoteCard** — list items with title, snippet, date, tags, drag handle
- **TagInput / TagFilter** — tag CRUD with autocomplete
- **EditorPane** — three view modes (rendered / edit / split), CodeMirror
  6 integration with textarea fallback, auto-save, frontmatter parsing
- **BacklinksPanel** — lists notes that link to the current note
- **SidebarTabs** — Notes / Outline tabs
- **SidebarOutline** — heading tree parsed from markdown body
- **GraphPane** — canvas-based force-directed graph with folder coloring,
  orphan hiding, focus mode, pan/zoom
- **Export** — download note as `.md` with frontmatter

### Backend (23K — `script.star`)

- Full CRUD: notes, folders, tags
- Wikilink extraction (`_extract_wikilinks`) and link resolution
  (`_sync_links`) on every note save
- Links / backlinks queries
- Graph data endpoint (nodes + edges)
- Search (title + body substring)
- Stats endpoint
- Folder CRUD with `parent_id`

### Schema (4 tables)

- `notes` — title, body, folder_id, creator_id, updated_at, pinned, archived
- `tags` — note_id, tag
- `links` — source_id, target_id, link_text
- `folders` — name, parent_id, creator_id, sort_order

### Current CSS (795 lines — `css/main.css`)

Functional but visually flat. No animations, no keyframes, no
micro-interactions. Identical `transition: var(--transition)` on every
hover. No typographic hierarchy beyond font-size/weight. No visual
rhythm. Sidebar and editor feel like admin panels, not a writing tool.

---

## Version Plan

### v0.11.0 — UI/UX Foundation

**Goal:** Complete visual redesign of the notes surface. Every pixel
intentional. Every interaction feels crafted. This is the foundation
that all subsequent feature versions build on.

This is NOT a "make it pretty" pass on the existing CSS. It is a
ground-up rethink of the notes UI with the understanding that this is
the first thing people see when evaluating what Armature can do.

**Design principles for notes:**

- **Writing-first.** The editor area dominates. Generous whitespace.
  Nothing competes for attention with the content the user is writing.
- **Quiet chrome, loud content.** Sidebar, toolbar, and navigation fade
  into the background. The note body is the visual anchor — clean
  typography, comfortable line height, readable measure (60–80 chars).
- **Progressive disclosure.** Folder tree, tags, backlinks, graph — all
  there but not all visible simultaneously. Contextual — show what's
  relevant to what the user is doing right now.
- **Micro-interactions that feel alive.** Folder expand/collapse with
  rotation animation. Note cards with subtle lift on hover. Smooth
  sidebar resize. Mode transitions that animate, not snap. Save
  indicator that pulses, not just appears.
- **Personality without kitsch.** The UI should feel like a well-designed
  indie app, not a Material Design template and not a Bootstrap theme.

**Specific deliverables:**

**Typography overhaul:**
- Rendered note body: system serif stack for body text (Georgia, serif
  fallback) at 16px/1.7 line height. Headings in the system sans stack.
  Comfortable reading measure — `max-width: 720px` centered in the
  editor area with generous padding. Code blocks with distinct
  background and a monospace stack.
- Editor (CM6): matching font size and line height so switching between
  rendered/edit mode doesn't jar. CM6 theme tokens aligned with note
  design tokens.
- Sidebar text: smaller (13px), tighter, utility font. Clear hierarchy
  between folder names, note titles, snippet text, dates.

**Sidebar redesign:**
- **Resizable** — drag handle between sidebar and editor. Width persisted.
  Smooth resize with no layout jank.
- **Collapsible** — collapse to a thin icon strip (folder + search +
  graph icons) on narrow viewports or by user choice. Expand on hover
  or click. Collapse state persisted.
- **Folder tree polish:** Indent guides (subtle vertical lines connecting
  parent→child). Folder icons that change on expand (open folder / closed
  folder, not just a triangle). Drop target highlighting with animation
  (not just background color change). Smooth height animation on
  expand/collapse.
- **Note cards:** Subtle left border color-coded by folder (pulls from a
  soft palette, not harsh primaries). Title, snippet, relative date
  ("3h ago" not "2026-04-03T12:34"). Tag pills with rounded, muted
  styling. Pin indicator as a subtle icon, not a text label.
- **Search:** Inline search with clear button. Results highlight matching
  text. Smooth appear/disappear.

**Editor redesign:**
- **Header:** Title input styled as a large heading (not an input field
  with a border). Folder breadcrumb below title in muted text. Toolbar
  actions as icon buttons with tooltips — no text labels cluttering the
  header. Save status indicator (saved ✓ / saving… / unsaved •) as a
  small, elegant badge.
- **Mode switcher:** Segmented control (Read / Edit / Split) replacing
  the cycling button. Clear visual state.
- **Rendered view:** Clean markdown rendering with proper spacing between
  elements. Block quotes with a left accent border. Tables with subtle
  borders and alternating row tinting. Inline code with pill-style
  background. Links with underline on hover only.
- **Empty editor state:** "Select a note or create a new one" with a
  softly illustrated empty state — not a plain text message.

**Graph visual refresh:**
- Dark-on-light node rendering with soft shadows (not flat circles with
  outlines). Node labels that appear on hover with smooth fade-in.
  Edge rendering with slight curves (not straight lines). Background
  subtle dot grid.

**Transitions and animations:**
- Sidebar expand/collapse: 200ms ease-out slide.
- Folder tree expand/collapse: 150ms height animation with children
  fading in.
- Note card hover: subtle translateY(-1px) + box-shadow lift.
- View mode switch: crossfade (100ms fade out → swap → 100ms fade in).
- Save indicator: pulse animation on "saving", check mark with brief
  scale-up on "saved".
- Graph node hover: scale(1.2) with spring easing.
- Panel/dialog open: 150ms slide-up + fade-in (consistent with kernel
  Dialog animation).

**Color and theming:**
- Notes should work beautifully in both light and dark themes.
  Use CSS custom properties (already the pattern via `var(--bg-surface)`,
  etc.) but add notes-specific tokens for accent colors, folder palette,
  and typography:
  ```css
  --notes-body-font: Georgia, 'Times New Roman', serif;
  --notes-body-size: 16px;
  --notes-body-line-height: 1.7;
  --notes-body-measure: 720px;
  --notes-accent: var(--accent);
  --notes-folder-1: #6366f1;  /* indigo */
  --notes-folder-2: #8b5cf6;  /* violet */
  --notes-folder-3: #ec4899;  /* pink */
  --notes-folder-4: #f59e0b;  /* amber */
  --notes-folder-5: #10b981;  /* emerald */
  --notes-folder-6: #06b6d4;  /* cyan */
  ```

**Responsive:**
- Below 768px: sidebar collapses to overlay (slide-in from left).
  Editor goes full-width. Split view disabled. Touch-friendly tap
  targets (44px minimum on all interactive elements).
- Between 768px and 1024px: sidebar narrower (220px). Editor gets
  remaining space.
- Above 1024px: full layout with comfortable sidebar width.

**What this version does NOT change:**
- No new features. Same note CRUD, same folders, same tags, same
  wikilinks, same graph, same three view modes.
- No backend changes. No schema changes.
- The existing JS components are restructured for the new layout but
  retain their current behavior.

**Deliverable:** Complete CSS rewrite (`css/main.css`), targeted JS
changes for new layout structure (resizable sidebar, collapsible sidebar,
mode switcher component, animation hooks), and updated component
templates where the HTML structure needs to change for the new design.

---

### v0.11.1 — Deep Folders + Navigation

**Goal:** Folders become a real hierarchy with breadcrumbs, not just a
flat tree with parent_id.

**Features:**

- **Breadcrumb navigation** in editor header showing the folder path.
  Click any segment to navigate to that folder's note list. Styled
  consistently with the v0.11.0 muted-text breadcrumb design.
- **Drag folder→folder** to reparent. Animated drop indicator shows
  nesting target with indent guide preview. Depth limit: 5 levels.
- **Folder sort** — drag to reorder within a level. Smooth reorder
  animation. Persists via `sort_order` column (already in schema).
- **Collapse/expand persistence** — expanded folder set stored in
  `sw.storage` keyed by user.
- **Move dialog** — select destination folder from a tree picker when
  moving notes (alternative to drag for accessibility / many folders).
  Uses `sw.ui.Dialog` with the new folder tree component inside.

**UX standard:** All folder interactions use the animation language
established in v0.11.0. Drop targets highlight with the folder color
from the palette. Reparent shows a brief connection-line animation.

**Backend changes:**

- Validate `parent_id` chain on create/update (no cycles, depth ≤ 5).
- Folder delete: require empty or offer cascade (move children to parent,
  or move contained notes to Unfiled).
- `_list_folders()` returns full tree with `children_count` and
  `note_count` for each folder.

**Schema:** No changes.

---

### v0.11.2 — Wikilinks + Backlinks

**Goal:** `[[wikilinks]]` become a first-class editing and navigation
primitive with autocomplete, previews, and unresolved link handling.

**Features:**

- **CM6 autocomplete** — typing `[[` triggers a fuzzy note title picker
  with a clean dropdown styled consistently with the notes design
  language (not browser-default autocomplete). Shows note title, folder
  path, and snippet preview. Keyboard navigable.
- **Wikilink rendering** — rendered markdown converts `[[Title]]` to
  internal links with a subtle notes-specific style (dotted underline,
  small link icon). Distinct from external URLs.
- **Hover preview** — hovering a wikilink shows a floating card with
  the target note's title, first ~200 chars rendered as markdown, and
  folder/tag metadata. Smooth fade-in, positioned to avoid viewport
  overflow. Same visual language as graph node hover cards.
- **Unresolved links** — `[[Nonexistent Note]]` renders with a dashed
  styling and a muted color. Click to create the note with that title
  (pre-filled). Small "+" indicator on hover.
- **Backlinks panel improvements:**
  - Show context snippet (surrounding text with the `[[link]]`
    highlighted).
  - Group by folder with folder color indicators.
  - Count badge in sidebar tab (animated increment on new backlinks).
  - Navigate to the linking note and scroll to the link location.
- **Aliases** — new `aliases` column on `notes` table. Autocomplete
  searches both title and aliases.

**UX standard:** Autocomplete dropdown uses the notes card styling.
Hover preview card shares visual language with graph tooltips. Unresolved
link creation is a smooth inline experience, not a navigate-away-and-back.

**Backend changes:**

- `_sync_links()` resolves aliases as well as titles.
- New endpoint: `GET /autocomplete?q=...` — fast title+alias prefix
  search (limit 10).
- Backlinks response includes `context_snippet` field.

**Schema changes:**

- `notes` table: add `aliases` column (text, comma-separated).

---

### v0.11.3 — Live Preview + Rich Editing

**Goal:** The editor becomes genuinely pleasant to write in — live
preview that scrolls in sync, or an optional inline-formatted mode.

**Features:**

- **Split pane scroll sync** — scrolling the CM6 editor scrolls the
  rendered preview to the corresponding position. Uses heading anchors
  for coarse sync and line-height interpolation for fine sync.
- **Live preview debounce** — rendered pane updates as you type with
  150ms debounce. Smooth content transitions (no jarring reflow).
- **Inline preview** (Obsidian-style) — optional mode where markdown
  syntax hides and formatting appears inline while editing. CM6
  decorations for bold, italic, headings, links, code blocks.
  Syntax reappears when cursor enters the formatted region. This is
  the "fourth mode" alongside rendered / edit / split — a true
  WYSIWYG-ish editing experience without leaving markdown.
- **Image paste** — paste from clipboard, upload via `files` module,
  insert `![](url)` at cursor. Progress indicator during upload.
  Fallback: base64 inline if `files` module unavailable.
- **Table editing** — tab-to-next-cell, auto-expand columns, add
  row/column with floating buttons on hover. Markdown tables become
  usable instead of a formatting chore.

**UX standard:** Split pane has an animated gutter with a subtle drag
handle. Mode switcher expands to accommodate the fourth option (or
becomes a dropdown if space is tight). Image paste shows a smooth
inline loading skeleton.

**Backend changes:**

- Image upload endpoint: `POST /images` — receives multipart, stores
  via `files` module, returns URL.

**Schema:** No changes.

---

### v0.11.4 — Note Sharing + Permissions

**Goal:** Notes become collaborative. Share a note or folder with
a team, group, individual, or the public — with read-only or read-write
permissions.

**Share Model:**

```
┌─────────────────────────────────────────────────────┐
│ Share Scope              │ Granularity │ Permissions │
├──────────────────────────┼─────────────┼─────────────┤
│ Public (anonymous URL)   │ note only   │ read-only   │
│ Team                     │ note/folder │ ro / rw     │
│ Group                    │ note/folder │ ro / rw     │
│ Individual (user)        │ note/folder │ ro / rw     │
└──────────────────────────┴─────────────┴─────────────┘
```

**Folder sharing inherits:** sharing a folder grants access to all notes
in that folder (and sub-folders). Individual note shares override folder
permissions (higher wins).

**Features:**

- **Share dialog** — clean modal (using `sw.ui.Dialog`) with scope
  selector, user/team/group picker (using `sw.ui.UserPicker` or new
  entity picker), permission toggle, and copy-link button. Share URL
  preview with visual indicator.
- **Public notes surface** — new surface at `/s/notes/public/:share_id`.
  Renders a single note in read-only mode with clean, minimal chrome.
  Uses the v0.11.0 typography and rendered view styling. Armature
  branding footer. No authentication required.
- **Shared-with-me view** — sidebar section (new tab) showing notes/folders
  shared by others. Grouped by owner with avatar. Visual distinction
  from your own notes.
- **Share indicators** — shared notes show a subtle share icon on the
  note card. Folder tree shows share badge on shared folders. Hover
  reveals share scope.
- **Permission enforcement** — Starlark backend checks share permissions
  on every read/write.
- **Share revocation** — remove access from share dialog with
  confirmation.

**UX standard:** Share dialog is the most complex new UI in the series
and must feel simple. One-click sharing for common cases (share with
team, make public). Advanced options (specific users, groups) are
available but not in the way. Copy-link button shows a brief "Copied!"
toast. Public note surface is a showcase — the best the notes rendering
can look.

**Backend changes:**

- New `note_shares` table.
- New `folder_shares` table.
- Access check function: `_can_access(user_id, note_id, permission)`.
- `_list_notes()` includes shared notes with `shared_by` metadata.
- Public note endpoint: unauthenticated GET by share_token.

**Schema changes:**

- New table: `note_shares` — note_id, share_type, target_id, permission,
  share_token, created_by, created_at.
- New table: `folder_shares` — folder_id, share_type, target_id,
  permission, share_token, created_by, created_at.

**Manifest changes:**

- New surface: `/notes/public/:share_id` with `auth: "public"`.

---

### v0.11.5 — Graph + Outline Hardening

**Goal:** The graph becomes a genuine navigation and discovery tool.
The outline becomes a reliable TOC.

**Graph improvements:**

- **d3-force layout** — replace hand-rolled force sim with d3-force.
  Better convergence, collision avoidance, centering. ~15KB optional
  vendor (same pattern as CM6).
- **Zoom controls** — explicit +/- buttons (styled as floating pills) plus
  scroll-to-zoom. Reset-to-fit button.
- **Minimap** — small overview in corner with viewport rectangle.
  Draggable to navigate large graphs.
- **Cluster by folder** — visual grouping with soft convex hulls in
  folder colors (from the v0.11.0 palette). Toggle on/off.
- **Filter by tag** — highlight matching nodes, dim others. Smooth
  opacity transition.
- **Search in graph** — highlight and smooth-pan to matching nodes.
- **Hover card** — note title, snippet, folder, tag count. Same visual
  language as wikilink hover preview (v0.11.2).

**Outline improvements:**

- **Scroll sync** — active heading highlights as user scrolls. Uses
  `IntersectionObserver`. Smooth highlight transition.
- **Click-to-scroll** — smooth scroll with brief heading highlight pulse.
- **Indent levels** — h1→h6 with subtle indent guides matching the
  folder tree style.
- **Collapse/expand** — heading sections collapsible in outline.
  Animated, consistent with folder tree animations.

**UX standard:** The graph should feel like a discovery tool, not a tech
demo. Interactions should be fluid — pan, zoom, hover, click — with no
jank. The outline should feel like a table of contents in a well-typeset
book.

---

### v0.11.6 — Quick Switcher + Commands

**Goal:** Keyboard-driven navigation. Power users never touch the mouse.

**Features:**

- **Quick switcher** (`Cmd+O` / `Ctrl+O`) — centered overlay with fuzzy
  search. Clean design: large input field, results below with note
  title, folder path, and snippet. Recent notes above search results.
  Arrow keys + Enter. Smooth open/close animation. Matches the visual
  language of command palettes in VS Code / Raycast.
- **Command palette** (`Cmd+Shift+P`) — same overlay style, listing all
  available note actions as searchable commands. Extensible via
  `sw.actions`.
- **Keyboard shortcuts:** Registered via a central keymap.

  | Shortcut | Action |
  |----------|--------|
  | `Cmd+O` | Quick switcher |
  | `Cmd+Shift+P` | Command palette |
  | `Cmd+N` | New note |
  | `Cmd+S` | Save (in edit mode) |
  | `Cmd+E` | Toggle edit/rendered |
  | `Cmd+Shift+E` | Toggle split view |
  | `Cmd+D` | Open today's daily note |
  | `Cmd+G` | Toggle graph view |
  | `Cmd+B` | Toggle backlinks panel |
  | `Escape` | Close active panel/dialog |

**UX standard:** The quick switcher is a high-frequency interaction —
it must open instantly (no perceptible delay), search results must
appear as-you-type, and the whole flow (Cmd+O → type → Enter) should
take under 2 seconds for a user who knows what they want.

---

### v0.11.7 — Daily Notes + Templates

**Goal:** Recurring note patterns that lower friction.

**Daily notes:**

- Auto-created daily note — navigating to "today" creates a note titled
  `YYYY-MM-DD` in a configurable daily notes folder.
- Daily note template — configurable template body.
- **Calendar picker** — small, beautiful calendar widget in the sidebar.
  Days with notes dot-marked. Styled as a subtle, compact component
  (not a full-page calendar). Click a date to open that day's note.
- Previous/next day nav arrows in editor header for daily notes.

**Templates:**

- Notes in a "Templates" folder are templates. No special type.
- "New Note" dropdown offers template selection with preview.
- Template variables: `{{date}}`, `{{time}}`, `{{title}}`, `{{folder}}` —
  simple string replacement.
- **Slash commands** in CM6 — typing `/` at line start shows a styled
  command menu: `/template`, `/date`, `/time`, `/todo`, `/callout`,
  `/table`, `/code`, `/divider`. Extensible via `sw.slots`.

**UX standard:** The calendar picker should feel like a subtle,
integrated part of the sidebar — not a jarring widget. Template
selection should show a live preview of the template content.
Slash commands should appear fast and be keyboard navigable.

**Settings additions:**

- `daily_note_folder` — folder name for daily notes.
- `daily_note_template` — template body.
- `template_folder` — folder name for templates.

---

### v0.11.8 — Transclusion + Embeds

**Goal:** Notes reference and embed each other's content.

**Features:**

- **Transclusion** (`![[Note Title]]`) — embeds referenced note content
  inline in a clean bordered container with source title as header link.
- **Section transclusion** (`![[Note Title#Heading]]`) — embeds content
  under specified heading only.
- **Block transclusion** (`![[Note Title^block-id]]`) — single paragraph
  by block ID.
- **Recursion guard** — depth limited to 3. Circular references show
  a clean warning card, not an error.
- **File attachments** — drag-and-drop files onto editor to upload.
  Non-image files render as styled download cards (file icon, name,
  size).
- **Embed preview in editor** — CM6 decoration shows read-only preview
  below `![[...]]` line. Collapsible with smooth animation.

**UX standard:** Transclusions should feel like natural parts of the
document, not foreign inclusions. The border and header link should be
subtle. Embedded content uses the same typography as the host note.
Collapse animation is smooth.

---

### v0.11.9 — Composability: Slots + Actions

**Goal:** Notes becomes a host surface that other extensions enhance.

**Slot declarations:**

```json
{
  "slots": {
    "notes:toolbar-actions": {
      "description": "Action buttons in the note editor toolbar",
      "context": {
        "noteId": "string",
        "getContent": "function — returns markdown body",
        "setContent": "function — replaces markdown body",
        "getTitle": "function — returns title"
      }
    },
    "notes:note-footer": {
      "description": "Content rendered below the note body",
      "context": { "noteId": "string", "content": "string — HTML" }
    },
    "notes:sidebar-tabs": {
      "description": "Additional tabs in the notes sidebar",
      "context": { "activeNoteId": "string or null" }
    },
    "notes:slash-commands": {
      "description": "Additional slash commands in the editor",
      "context": { "insertText": "function(text)" }
    }
  }
}
```

**Exported actions:**

```json
{
  "exports": {
    "actions": {
      "notes.create": "Create note (params: title, body, folder_id)",
      "notes.search": "Search notes (params: query, limit)",
      "notes.get": "Get note by ID (params: note_id)"
    }
  }
}
```

**UX standard:** Slot contributions must fit visually. Toolbar action
buttons contributed by other extensions inherit the notes icon-button
styling. Sidebar tabs contributed by extensions match the built-in tab
design. The notes surface should not look different when extensions
contribute to its slots.

---

### v0.11.10 — Panel Enhancement + Quality Gate

**Goal:** The `notes.reference` panel (shipped in v0.10.4) inherits
the v0.11.x features. Final quality gate.

**Panel updates:**

- Reference panel gets the v0.11.0 visual design language.
- Search, folder filter, tag filter in panel.
- Preview pane shows rendered note content (v0.11.0 typography).
- Click-to-insert: emits `panel.notes.reference.selected` for host.
- Wikilink resolution works within panel preview.

**Quality gate criteria:**

- All v0.11.x features exercised in SDK test runner.
- Notes-runner surface tests cover: CRUD, sharing, wikilinks, daily
  notes, templates, transclusion.
- Graph renders correctly with 200+ nodes at 60fps.
- Public note surface renders without authentication.
- At least one slot contribution demonstrated.
- Panel reference works in at least one other surface.
- **UX review:** every screen, every interaction, every empty state
  reviewed against v0.11.0 design principles. No "placeholder" UI
  surviving to this point.
- **Responsive:** full experience on mobile (sidebar overlay, touch
  targets, no horizontal scroll).
- **Accessibility:** keyboard navigation through all views. ARIA labels.
  Focus management on panel/dialog open/close.
- **Performance:** virtual scrolling on note list for 1000+ notes.
  Graph 60fps with 500+ nodes. Lazy-load graph and CM6.

---

## Uniquely Armature

| Feature | Obsidian/Notion | Armature Notes |
|---------|-----------------|----------------|
| Extension slots | Plugin API (Obsidian) | Kernel-level composability — any package contributes to any slot without coupling |
| Sharing | Obsidian Publish (paid), Notion sharing | Built on kernel resource model — same permission patterns as every other extension |
| Panels | N/A | Notes is a panel provider — embed a notes view inside chat, dashboard, or any surface |
| Multi-surface | Single window | Full surface + public surface + reference panel, all from one package |
| Server-side logic | Local only (Obsidian) | Starlark backend — search, link resolution, access control run server-side |
| Realtime | N/A (Obsidian), built-in (Notion) | Via `sw.realtime` — same primitive available to all extensions |
| Cross-extension actions | Plugin API | `sw.actions` — any package can call `notes.create` or `notes.search` |
| Self-hosted | Obsidian Sync (paid) | Runs on your infrastructure, your data, your rules |

The thesis: **Notes isn't just a note-taking app — it's proof that
Armature's extension architecture can deliver a production-quality
knowledge base that competes with purpose-built SaaS tools, while
remaining decomposable and extensible.** And it has to *look and feel*
like it competes, not just architecturally compete.

---

## Schema Summary

### Existing tables (no changes)

- `notes` — title, body, folder_id, creator_id, updated_at, pinned, archived
- `tags` — note_id, tag
- `links` — source_id, target_id, link_text
- `folders` — name, parent_id, creator_id, sort_order

### New columns

- `notes.aliases` (text) — comma-separated aliases (v0.11.2)

### New tables

- `note_shares` — note_id, share_type, target_id, permission, share_token, created_by, created_at (v0.11.4)
- `folder_shares` — folder_id, share_type, target_id, permission, share_token, created_by, created_at (v0.11.4)

---

## Settings Summary

### Existing

- `default_view` — "recent" or "pinned"
- `editor_mode` — "rendered", "edit", or "split"

### New

| Setting | Type | Default | Version |
|---------|------|---------|---------|
| `daily_note_folder` | string | "Daily Notes" | v0.11.7 |
| `daily_note_template` | string | `"# {{date}}\n\n"` | v0.11.7 |
| `template_folder` | string | "Templates" | v0.11.7 |
| `inline_preview` | boolean | false | v0.11.3 |
| `graph_hide_orphans` | boolean | false | v0.11.5 |
| `graph_cluster_by` | string | "folder" | v0.11.5 |

---

## Design Decisions

| Decision | Rationale |
|----------|-----------|
| UI redesign as v0.11.0, before features | Every subsequent version builds on the visual foundation. Shipping features on an ugly base means reworking the UI of every feature when the redesign eventually happens. Front-loading avoids double work and ensures every version screenshot looks like a real product. |
| Notes as first reference extension | Exercises more kernel primitives than any other candidate. Complex enough to prove the platform; familiar enough to be immediately useful. |
| Dedicated v0.11.x series (11 versions) | Notes is too large for a single version. Each v0.11.x is independently shippable and CI-green. |
| UX quality threaded through every version | Each version specifies its UX standard, not just functionality. No "make it pretty later" — every feature ships with its final visual quality. |
| Share model via new tables | Notes sharing needs note/folder-specific semantics (inheritance, public URLs, share tokens). Purpose-built tables beat generic resource grants for this use case. |
| Aliases as comma-separated text | Small set (1–3 per note). Separate table adds join complexity for marginal normalization benefit. |
| d3-force for graph | Existing hand-rolled sim has poor convergence at 100+ nodes. d3-force is battle-tested, ~15KB. |
| Transclusion rendered on view, not live-synced | Live-sync requires WebSocket subs per embedded note. Disproportionate complexity pre-MVP. |
| Templates are just notes in a folder | No template schema. KISS. |
| Inline preview as fourth editing mode | Obsidian's killer UX feature. Users who want WYSIWYG-ish editing without leaving markdown get it without a ProseMirror dependency — CM6 decorations handle it. |

---

## Dependency Chain

```
v0.11.0   UI/UX Foundation     ← EVERYTHING depends on this
v0.11.1   Deep Folders         ← foundation for folder sharing (v0.11.4)
v0.11.2   Wikilinks            ← foundation for transclusion (v0.11.8)
v0.11.3   Live Preview         ← foundation for inline preview + embeds (v0.11.8)
v0.11.4   Sharing              ← depends on deep folders (v0.11.1)
v0.11.5   Graph + Outline      ← independent (hardening existing features)
v0.11.6   Quick Switcher       ← independent (keyboard navigation)
v0.11.7   Daily Notes          ← depends on deep folders (v0.11.1) for daily folder
v0.11.8   Transclusion         ← depends on wikilinks (v0.11.2) + live preview (v0.11.3)
v0.11.9   Composability        ← independent (slot/action declarations)
v0.11.10  Polish + Gate        ← depends on all above
```

Versions v0.11.5, v0.11.6, and v0.11.9 are independent and can be
reordered if priorities shift.