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.claude/skills/notes-actions/SKILL.md
GitHubNotes 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-actionsskill. - The live-chat message bar (
AssistantActionBar/messageActionRegistry) →overlay-systemskill, "Message actions (chat)" section. - Overlay rendering/registration mechanics (how the
saveToNotesoverlay actually renders) →overlay-systemskill.
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:
- New action created → add row to exports table, set usage count to 0
- Action consumed in a new file → increment count, add file path
- Consumer removed → decrement count, remove file path
- Action renamed/deleted → update or remove rows everywhere
saveToNotesoverlay usage changed → update its dedicated section
Key Files
- (Barrels removed — import action components and
NotesAPIfrom their source files underfeatures/notes/.) features/notes/actions/notes-actions.md— living usage referencefeatures/notes/service/notesApi.ts—NotesAPI(programmatic CRUD)features/notes/context/NotesContext.tsx— shared state + realtimefeatures/overlays/host/OverlayWorldHost.tsx— overlay host for modal/sheet (see theoverlay-systemskill)@ai-matrx/summon—openOverlay({ overlayId: 'saveToNotes' }); the definition isfeatures/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) |