notes-actions

Cross-app save-to-notes components and patterns. Use when adding save-to-notes to a feature, wiring overlay note capture, editing features/notes/actions/ or its consumers, or using QuickCaptureButton,

SKILL.md

GitHub

Notes Actions (Cross-App Integration)

Scope boundary — which skill owns what

This skill owns the notes-side primitives: the components under features/notes/actions/ and the save-to-notes overlay flow (useOpenQuickNoteSaveOverlay from features/overlays/definitions/saveToNotes.overlay.tsx) — i.e. HOW a save-to-notes capability is built and wired. It does NOT own the surfaces that expose it:

  • An action toolkit on markdown/RichDocument surfaces (where "Save to notes" is one action among many) → rich-document-actions skill.
  • The live-chat message bar (AssistantActionBar / messageActionRegistry) → overlay-system skill, "Message actions (chat)" section.
  • Overlay rendering/registration mechanics (how the saveToNotes overlay actually renders) → overlay-system skill.

Come here when adding/altering a notes action component or its provider/API contract; go to those skills when merely consuming save-to-notes from their surfaces.

Quick Reference

Source: features/notes/actions/ Imports: Direct paths (e.g. @/features/notes/actions/SaveToScratchButton, @/features/notes/service/notesApi) — root and actions/index barrels were removed. Living doc: features/notes/actions/notes-actions.md — must be updated whenever actions are added, removed, or consumed in new files.

Available Actions

Export What it does
QuickCaptureButton Toolbar button opening the saveToNotes overlay (useOpenQuickNoteSaveOverlay)
QuickNoteSaveModal Dialog: edit content, pick folder, create vs update (append/overwrite)
QuickSaveModal Alias of QuickNoteSaveModal
SaveToScratchButton One-click NotesAPI.create into Scratch (no modal)
SaveSelectionButton Reads window.getSelection(), saves to folder, clears selection
QuickNotesButton Icon button calling useQuickActions().openQuickNotes()
QuickNotesSheet In-overlay compact notes UI (editor + picker). Needs NotesProvider
CategoryNotesModal Folder-scoped modal with list/search/CRUD/import + onSelectNote callback. Needs NotesProvider
WindowNotesBody Lightweight single-note editor for windows/panels. Bundles own NotesProvider, auto-save, auto-label, tree-view picker
NotesTreeView VS Code-style folder/note tree. Single-folder expand, inline create note/folder, onSelectNote/onSelectFolder callbacks. Needs NotesProvider
NotesWindow Complete WindowPanel with tree sidebar + editor + header actions. Bundles own NotesProvider. Accepts all WindowPanelProps
SidebarNotesToggle Shell sidebar button that toggles a floating NotesWindow. No provider needed

Integration Patterns

Pattern 1: Redux overlay dispatch (most common)

Many features skip the button entirely and open the saveToNotes overlay directly:

import { openOverlay } from '@ai-matrx/summon';

dispatch(openOverlay({ overlayId: 'saveToNotes', data: { initialContent: content } }));
// or, in a component: useOpenQuickNoteSaveOverlay() from features/overlays/definitions/saveToNotes.overlay

OverlayWorldHost handles dynamic import of QuickNoteSaveModal and wraps it with NotesProvider.

Pattern 2: Drop-in buttons

import { SaveToScratchButton } from '@/features/notes/actions/SaveToScratchButton';

<SaveToScratchButton content={aiResponse} />

No provider or overlay wiring needed — the button calls NotesAPI.create directly.

Pattern 3: Folder-scoped note picker

import { CategoryNotesModal } from '@/features/notes/actions/CategoryNotesModal';

<CategoryNotesModal
  folderName="Prompts"
  onSelectNote={(note) => applyPrompt(note.content)}
/>

Requires NotesProvider ancestor.

Pattern 4: Embedded sheet

import { QuickNotesSheet } from '@/features/notes/actions/QuickNotesSheet';

Used inside OverlayWorldHost or any layout that provides NotesProvider.

Maintenance Rules

Every time you touch this system, update features/notes/actions/notes-actions.md:

  1. New action created → add row to exports table, set usage count to 0
  2. Action consumed in a new file → increment count, add file path
  3. Consumer removed → decrement count, remove file path
  4. Action renamed/deleted → update or remove rows everywhere
  5. saveToNotes overlay usage changed → update its dedicated section

Key Files

  • (Barrels removed — import action components and NotesAPI from their source files under features/notes/.)
  • features/notes/actions/notes-actions.md — living usage reference
  • features/notes/service/notesApi.ts — NotesAPI (programmatic CRUD)
  • features/notes/context/NotesContext.tsx — shared state + realtime
  • features/overlays/host/OverlayWorldHost.tsx — overlay host for modal/sheet (see the overlay-system skill)
  • @ai-matrx/summon — openOverlay({ overlayId: 'saveToNotes' }); the definition is features/overlays/definitions/saveToNotes.overlay.tsx

Provider Requirements

Component Needs NotesProvider?
SaveToScratchButton No (uses NotesAPI directly)
SaveSelectionButton No (uses NotesAPI directly)
QuickCaptureButton No (dispatches Redux action)
QuickNoteSaveModal Yes (OverlayWorldHost provides it)
QuickNotesSheet Yes
CategoryNotesModal Yes
WindowNotesBody No (bundles its own NotesProvider)
NotesTreeView Yes
NotesWindow No (bundles its own NotesProvider + WindowPanel)
SidebarNotesToggle No (renders NotesWindow which bundles everything)