# notes

Session-backed pending prompt notes for Pi.

## Install / load

Loaded through the root pi-ext package.
See [root README](../../README.md).

## Commands / tools / settings

Commands:

- `/note` — toggle the notes widget between compact and expanded mode.
- `/note add <text>` — park a non-empty note.
- `/note send <id>`: send one note with Pi prompt expansion and remove it from pending notes.
- `/note clone <id>`: clone the current branch through its leaf and send the note as the next prompt.
- `/note fork <id>`: choose a user message with Pi's fork selector, fork before it, and send the note instead.
- `/note new <id>`: start an independent session and send the note as its first prompt.
- `/note edit <id>` — edit one pending note.
- `/note rm <id>` — remove one pending note.
- `/note clear` — confirm and remove all pending notes.

Shortcuts:

- `alt+n` — same as `/note`.
- `ctrl+enter`: add editor text as a note.
- `ctrl+alt+enter`: send a pending note via picker.

Tools:
none.

Settings:

| Key | Env | Default | Valid values |
| --- | --- | --- | --- |
| `notes.toggleShortcut` | `PI_NOTES_TOGGLE_SHORTCUT` | `alt+n` | non-empty string |
| `notes.addFromEditorShortcut` | `PI_NOTES_ADD_FROM_EDITOR_SHORTCUT` | `ctrl+enter` | non-empty string |
| `notes.sendPickerShortcut` | `PI_NOTES_SEND_PICKER_SHORTCUT` | `ctrl+alt+enter` | non-empty string |

Values are Pi key ids and are trimmed.
Shortcuts register at extension load, before any session exists.
Precedence: env, then `~/.pi/agent/settings.json`, then default.
Project settings are never read, even for trusted projects.
There are no flags.
An invalid value, including an empty env var, never falls through to a lower source; that shortcut keeps its default.
If the three resolved shortcuts are not distinct, all three keep their defaults.
Invalid values and duplicates are reported as warnings at `session_start`.

## Behavior

Store `/template args` with `/note add /template args`; `/note send <id>` expands it at send time.
Plain text is unchanged; busy agents receive `/note send` prompts as follow-ups.
Pi also expands skill commands and dispatches extension commands.

`clone`, `fork`, and `new` require an idle agent, then start the submitted note immediately in the destination session.
A persisted source must already be saved, so wait for the first assistant response before using them in a newly created session.
In-memory sessions are supported, but have no independently resumable source to retain.
`clone` preserves the current branch through its leaf.
`fork` reuses Pi's user-message selector and replaces the selected prompt and its following branch with the note.
`new` creates a root session without a parent or the ordinary notes carry prompt.
Cancelling or vetoing a transition keeps the source note pending.
The destination stages the note before delivery and source consumption.
A delivery failure leaves the destination note pending and leaves any persisted source copy untouched; successful Pi input processing consumes both.
A crash between those operations can duplicate the note but cannot silently destroy the source copy.
Delivery means Pi processed the input normally, not that a model response or invoked extension command succeeded.
Other notes follow normal branch history: clone inherits current notes, fork inherits notes at the selected point, and new inherits none.

Pending notes are persisted as `notes-state` custom session entries.
Custom entries are invisible to the model context.
Notes are branch-local because state is reconstructed from the current session branch, including after `/tree` navigation.
After `/new`, Pi asks whether to copy pending notes into the new session.
The handoff is in memory, so it works before either session file exists.
The widget is compact on reload, resume, or tree navigation.

No persistent project-global storage exists.
No cross-session note list exists.
No system-prompt or model-context injection exists.
No steer mode exists.

## Debugging

Opt-in metadata-only tracing follows [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `note.session_transition.start`, `note.session_transition.finish`, `note.session_transition.error`.