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)