# Tasks: assistant AI Elements

Spec: `specs/assistant-ai-elements/spec.md`. One task per Sonnet agent. Paths are under `crates/ui-egui/src/panels/assistant_panel/` unless marked (`P/` = that prefix). Every task: read `AGENTS.md`, `docs/CODE-MAP.md`, skills `notescraft-agent-workflow`, `notescraft-rust-safety`, `notescraft-egui-screen`, `notescraft-verify-loop`. Strings go to `crates/ui-egui/src/text/assistant_panel.rs` + `crates/i18n/locales/en.toml` (append at the END of the table); `rustfmt --edition 2024 <your files>` only (never `cargo fmt --all`); do not commit; do not touch files of other agents (check `git status`).

Common TESTS recipe (egui_kittest, copy `crates/ui-egui/tests/assistant_flow.rs` and `P/tests.rs`): build an `AssistantPanel`, feed `Event`s through `apply_event`, draw at `Vec2::new(320.0, 700.0)` panel width, assert with queries on labels and with real clicks (`Action` pushed), assert no horizontal overflow (content rect right <= panel right). Common PNG render: add the scenario to `P/chat/demo.rs` and run `cargo run -p notescraft-ui-egui --example snapshot -- --vault <v> --out ui.png --size 1440x900` plus a 320 wide variant (`--size 320x700`), `--theme catppuccin-latte` once, then READ the PNG and compare with the spec section.
Common VERIFY: `cargo test -p notescraft-ui-egui assistant`, `cargo clippy -p notescraft-ui-egui --all-targets -- -D warnings`, `cargo xtask i18n`, `cargo xtask tree`, `cargo xtask layers`.

> T0 note (aiA, 2026-10-21): trace widget landed, uncommitted. Module `P/chat/trace/{line,view}.rs`, state `P/state/trace.rs`.
> `trace::TraceStatus {Running, Done, Failed}` (`from_acp`); NO `Pending` yet. `line::Header {salt, status, title, description: Option<&str>, badge: Option<&str>, nested}`, shown with `line::show(ui, tokens, &header, |ui| body)`.
> Open state lives in egui memory under the line id; there is no `default_open` argument yet (T7/T4 add it when needed).
> `view::tool(ui, tokens, &ToolLine, actions)` and `view::subagent(ui, tokens, panel, &Subagent, actions)`; `conversation::show_tool` feeds them.
> New `Message` variant: `Subagent(Box<trace::Subagent>)` (id, title, status, started, nested calls). Strings: `text/panels/assistant_trace.rs`, `[ui.assistant-trace]`.
> T1-T3 status: see the checkboxes below.

## Order and parallelism

```
T0 (gate: subagent trace task landed)
 -> T1 split conversation.rs                      [chat/conversation.rs, new chat/message/]
     -> T2 Message turns + footer                 [chat/message/*, state/model.rs (turn index)]
     -> T3 Chat scroll + empty state              [chat/view.rs, chat/scroll/*]
     -> model.rs chain, strictly in sequence: T4 Reasoning -> T5 Plan+Queue -> T6 Confirmation -> T7 Work summary
 parallel with the chain (disjoint files, after T1):
     T8 Context card            [chat/usage.rs]
     T9 Changed notes tree      [state/review.rs, new chat/changes/*, chat/view.rs strip call]
     T10 Citations + Sources    [chat/sources*.rs, new chat/cite/*]
     T11 Prompt Input restyle -> T12 Suggestions -> T13 Model Selector UI   [input/composer.rs chain, header.rs]
     T14 ACP config options (crates/acp, then wire into T13)
     T15 Engine checkpoint journal + commands  [crates/engine only] -> T16 Checkpoint UI [needs T9, T2]
 last: T17 Bases table in message [needs T7], T18 docs/status
```
Same-file conflicts: `chat/view.rs` = T3, T9 (one line), T12, T16: run in that order. `state/model.rs` = T2, T4, T5, T6, T7, T16: sequential. `input/composer.rs` = T11, T12, T13: sequential. `chat/header.rs` = T13 only. Tasks with disjoint OWNS may run in parallel: {T8}, {T9}, {T10}, {T11->T12->T13}, {T14}, {T15}, and the model chain.

## [x] T0 Gate: confirm the subagent/trace work landed (no code)
GOAL: read the other agent's result (`git log -5`, `git status`, grep for the trace widget under `P/chat/`). Record in a 10-line note at the top of this file: widget module path, its API (status enum, description, open state), `Message` variants it added. Every later task uses that widget; if it lacks `Pending` status, a description line or `default_open`, T1 adds them (report to owner first, it is the other agent's file).
OWNS: this file only. DO NOT: edit source.

## [x] T1 Split `chat/conversation.rs` (437 lines) with no behaviour change
OWNS: `P/chat/conversation.rs` (keep as thin dispatcher), new `P/chat/message/{mod,markdown,system,typing}.rs`; `P/chat/mod.rs` (one `mod message;`).
FILES TO OPEN: `P/chat/conversation.rs`, `P/chat/view.rs` (callers), `P/mod.rs` (the flat `use chat::conversation` aliases; add `use chat::message;` only if needed).
GOAL: move `markdown*`, `fenced_blocks` (with its test), `system`, `typing`, to `chat/message/`. `conversation.rs` < 400 lines. Move strings it moves into the text table. Public paths unchanged.
TESTS: existing tests unchanged and green (`P/tests.rs`, `chat/view_tests.rs`, `tests/assistant_flow.rs`).
VERIFY: common + before/after snapshot PNG identical.
DO NOT: change layout or behaviour; add features; touch `model.rs`.

## [x] T2 Message: turns and reply footer
Docs: https://ui.shadcn.com/docs/ai-elements/base/message
OWNS: new `P/chat/message/{turn,footer}.rs`, `P/chat/conversation.rs` (call), `P/state/actions.rs` (Action::EditPrompt(index) if needed), `P/state/model.rs` (helper `turn_of(index)` only).
FILES TO OPEN: `P/chat/conversation.rs::{item, reply_actions}`, `P/state/actions.rs`, `P/state/model.rs`, `P/input/composer.rs` (`prefill`).
GOAL: footer (icon buttons, tooltips) under EVERY finished agent reply, not only the last: Copy (icon swaps to check for 2 s, `crate::motion`), Retry only on the last, Edit on user bubbles (puts text in the composer through `prefill`, focus composer). Reply separated from next user turn by consistent spacing. Hidden in history-viewing mode for Retry/Edit.
TESTS: kittest 320 pt: two turns -> two footers; click Copy -> clipboard text equals reply and icon state changes; click Edit -> `panel.composer()` equals the prompt; while `connection.running` no footer on the streaming reply.
DO NOT: add good/bad buttons; change message data layout beyond the helper.

## [x] T3 Chat: scroll anchoring and empty state
Docs: https://ui.shadcn.com/docs/ai-elements/base/chat
OWNS: `P/chat/view.rs`, new `P/chat/scroll/{mod,anchor,empty}.rs`.
FILES TO OPEN: `P/chat/view.rs::show` (scroll area, jump pill), `P/chat/demo.rs`.
GOAL: (1) a new user message settles near the top of the viewport and the reply streams beneath; while the user is at the live edge the view follows, if they scrolled up it does not (keep `stick_to_bottom` semantics, no jitter). (2) The "Jump to latest" text pill becomes an icon button (arrow-down) with a dot when new content arrived while away. (3) Empty state when a connection exists and there are no messages: heading, one line, slot for the suggestion row (T12 fills it). Move `FOOTER_HEIGHT`/jump consts and strings out of `view.rs`; keep file < 400.
TESTS: kittest: push 40 messages, scroll up, stream a chunk -> offset unchanged and dot visible; click jump -> at bottom; new user message -> its top within the first quarter of the viewport.
DO NOT: change the composer, header or review strip.

## [x] T4 Reasoning on the trace widget
Docs: https://ui.shadcn.com/docs/ai-elements/base/reasoning
OWNS: `P/state/model.rs` (`Message::Thought` gets `started: Instant`, `secs: Option<u32>`; `chunk()`; close on next non-thought event), `P/chat/transcript.rs` (`line_for` unchanged text), new `P/chat/message/reasoning.rs`, `P/chat/conversation.rs` (one arm).
FILES TO OPEN: `P/state/model.rs::{Message, chunk, apply_update}`, trace widget (T0), `P/state/model_tests.rs`.
GOAL: "Thinking" + spinner + shimmer while the last message is the Thought and the turn runs; open while streaming, auto-closes when it finishes, a manual toggle wins (store in egui memory by message index); finished = "Thought for 5s" (under 1 s: "Thought"). Empty text = plain line, not expandable. Respect `motion::enabled`.
TESTS: unit: duration is set when an Agent chunk or ToolCall follows; kittest: label "Thinking" while running, "Thought for" after; user closed state survives a later chunk.
DO NOT: change `crates/acp` or persisted format (transcript keeps role Thought).

## [x] T5 Plan + Queue (one widget, two placements)
Docs: https://ui.shadcn.com/docs/ai-elements/base/plan , https://ui.shadcn.com/docs/ai-elements/base/queue
OWNS: `P/state/model.rs` (`apply_update` Plan arm: replace the existing `Message::Plan` of the current turn in place instead of pushing), new `P/chat/message/plan.rs`, new `P/chat/message/queue.rs` (sticky strip), `P/chat/view.rs` (one call above composer; sequence after T3).
FILES TO OPEN: `P/state/model.rs`, `P/chat/conversation.rs` Plan arm, `crates/acp/src/events.rs::PlanEntry` (statuses pending/in_progress/completed), `P/chat/transcript.rs::line_for` (Plan -> text line).
GOAL: in-thread Plan: title "Plan · 2 of 5 done", rows via trace widget (done check, running dot + shimmer, pending circle), collapsed automatically when all done, one per turn. Queue strip above the composer while the turn runs and entries are not all complete: sections "To do" and "Completed" (collapsible, completed collapsed), hidden when no plan. Unknown status string = pending.
TESTS: unit: two Plan events in one turn -> one `Message::Plan`; a new user turn starts a new one. kittest 320 pt: counts text, sections, strip hidden after `PromptDone`. Persisted-transcript view still shows the plan text.
DO NOT: add a Queue data source; change ACP parsing.

## [x] T6 Confirmation (permission requests)
Docs: https://ui.shadcn.com/docs/ai-elements/base/confirmation
OWNS: `P/state/model.rs` (`Message::Permission` gets `answer: Option<String>` option name; `expire_permissions` only expires UNANSWERED ones), `P/state/actions.rs` (AnswerPermission records the answer), new `P/chat/message/permission.rs`, `P/chat/conversation.rs` arm, `P/state/permission_tests.rs`.
FILES TO OPEN: those, `P/chat/view.rs::write_requested`, `P/chat/header.rs` (grant), `crates/engine/src/ai/assistant_gate.rs` (read only).
GOAL: card = title (tool title via `tool_title`), what it touches (locations as note links), consequence line per twist (writes off / review on / review off), buttons Deny / Allow once / Always allow ordered by option kind (allow primary, reject outline). After answer the card collapses to one line "Allowed once" / "Always allowed" / "Denied" in success/muted/danger tone and stays in the thread; expired unanswered becomes "No answer" (not the current generic System line). Disabled in history mode.
TESTS: kittest 320 pt: three options -> three buttons, click maps to the right option id; after click, line text; permission for kind `edit` with `capabilities.read_only` shows the grant consequence; `PromptDone` before answer -> "No answer".
DO NOT: change the ACP answer call or the gate.

## [x] T7 Per-turn work summary (Chain of Thought + Task)
Docs: https://ui.shadcn.com/docs/ai-elements/base/chain-of-thought , https://ui.shadcn.com/docs/ai-elements/base/task
OWNS: `P/chat/conversation.rs` (replace `tool_group` call), new `P/chat/turn/{mod,summary}.rs`.
FILES TO OPEN: `P/chat/conversation.rs::{show, tool_group}`, trace widget, T4/T5/T6 results.
GOAL: consecutive non-text items of a turn (Thought, Tool, Plan stays outside) fold under one trace line. Running: present tense of the latest tool by kind ("Searching notes", "Reading Daily/2026-10-21"), spinner. Done: "Searched 3 notes, edited 1" (count by `kind`, max 3 clauses then "and N more"), error tone if any failed ("1 failed"). Auto-open while a call awaits review or permission; user toggle wins. Inside: rows from the Tool restyle (do not redraw them).
TESTS: unit: summary string for mixes of kinds, singular/plural, failure; kittest: running vs done title, auto-open on pending permission.
DO NOT: restyle the tool rows; invent kinds beyond ACP's seven.

## [x] T8 Context card
Docs: https://ui.shadcn.com/docs/ai-elements/base/context
OWNS: `P/chat/usage.rs` (+ its tests), `P/input/composer.rs` one call site only if the signature changes (coordinate: sequence before T11).
GOAL: bar becomes a percent button ("74%") with a ring or bar; click or hover opens a small card: used / max, bar with warn/danger tokens (existing 70/90 rules), cost when > 0, at >= 90% hint "Start a new chat" with a New chat action. Keep `Usage` parsing. No input/output rows (ACP has none).
TESTS: unit: ratio/label unchanged; kittest 320 pt: trigger text at 30/75/92, card opens on click, `Action::NewChat` at 92.
DO NOT: change `Usage::from_update`.

## T9 Changed notes tree (File Tree + review)
Docs: https://ui.shadcn.com/docs/ai-elements/base/file-tree
OWNS: `P/state/review.rs`, new `P/chat/changes/{mod,tree,row}.rs`, `P/chat/view.rs` (replace the strip+scroll block with one call; sequence after T3), `P/state/model.rs` NOT touched (read `panel.pending`).
FILES TO OPEN: `P/state/review.rs`, `P/state/actions.rs` (Accept/Reject/OpenDiff/AcceptAll/RejectAll), `crates/engine/src/ai/assistant_queue.rs::PendingChange`, `P/chat/view.rs` review block.
GOAL: card "Changed notes · 4 waiting" with folder tree built from `PendingChange.path` (folders collapsible, default open under 8 files), row = kind badge (Create/Modify/Delete/Rename + `+a −d` from `diff_view::counts`), click opens diff, hover shows Accept / Reject icon buttons; folder row has Accept folder / Reject folder; footer Accept all / Reject all. One change = plain row without tree. Opaque changes (no path) listed under "Other". Show `pending_errors` per row. Bounded: 200 max (engine cap), render with `show_rows`.
TESTS: unit: tree builder (nesting, sorting, single file, empty path); kittest 320 pt: click Accept on a row -> `Action::Accept(id)`, folder accept -> all ids; error text shown.
DO NOT: change the engine queue or accept semantics; applied-changes list is T16.

## T10 Citations and Sources
Docs: https://ui.shadcn.com/docs/ai-elements/base/inline-citation , https://ui.shadcn.com/docs/ai-elements/base/sources
OWNS: `P/chat/sources_view.rs`, `P/chat/sources.rs` (marker only), new `P/chat/cite/{mod,card,preview,wikilink}.rs`, `P/chat/message/markdown.rs` (hook for chips; sequence after T1).
FILES TO OPEN: `P/chat/sources_view.rs`, `P/chat/sources.rs::MARKER_SCHEME`, `crate::note_view` link result (`clicked_link`), `crates/ui-egui/src/views/share_dialog/mod.rs` (worker pattern), engine `note.read`.
GOAL: Sources line "Used 3 notes" on the trace widget; rows = note name, heading, tokens; click -> `OpenNote` with `open_range`. `[n]` and `[[wikilink]]` in agent text render as chips with a hover card (title, path, heading, first 3 lines). Preview text loaded off the UI thread via the worker pattern, cached per path with a size cap (e.g. 64 entries, 2 KiB each), never `unwrap`. Unresolved link = muted chip, card says not found, no navigation.
TESTS: kittest 320 pt: agent text "see [[Meeting notes]] [1]" -> two chips, hover shows card from a fixture vault note, click -> `Action::OpenNote`; unresolved chip not clickable.
DO NOT: change the knowledge crate or how passages are sent; do not read vault files in the paint path.

## [x] T11 Prompt Input restyle
Docs: https://ui.shadcn.com/docs/ai-elements/base/prompt-input
OWNS: `P/input/composer.rs`, new `P/input/bar.rs` (bottom bar split out), `P/input/composer_tests.rs`.
FILES TO OPEN: `P/input/composer.rs`, `P/input/context.rs` (`Chip`), `P/input/composer_keyboard.rs`.
GOAL: chips as pills (kind icon, truncated name, x), consistent height; bottom bar: attach (+), current-note toggle, usage trigger slot, spacer, circular icon send button (arrow) that becomes stop while running and a spinner state while `starting`. Keep Enter / Shift+Enter, mentions, drag-drop. `composer.rs` < 400 lines.
TESTS: existing composer tests green; kittest: running -> stop button sends `Action::Cancel`; chip x removes.
DO NOT: add image attachments (needs `PromptBlock::Image`; separate spec); touch the model selector (T13).

## [x] T12 Suggestions
Docs: https://ui.shadcn.com/docs/ai-elements/base/suggestion
OWNS: `P/input/composer.rs` (remove `QUICK_ACTIONS`; sequence after T11), new `P/input/suggestions.rs`, `P/chat/scroll/empty.rs` (slot from T3), `P/chat/view.rs` (sequence after T9).
GOAL: horizontally scrolling row of outline pills; click SENDS (`Action::Send` with the text) instead of prefilling. Empty state set: "Summarize this note" (only with an active note), "Find notes that link here", "What did I write this week?"; plugin chips (Template, Calendar, Diagram) only when `settings.plugin_tools` enables them. After a finished turn, show agent `available_commands_update` names if T14 parsed them (optional, leave a clear TODO-free seam: a `Vec<String>` argument).
TESTS: kittest 320 pt: row scrolls, click sends exact text, hidden while running and in history mode.
DO NOT: invent LLM-generated follow-ups.

## [x] T13 Model Selector UI
Docs: https://ui.shadcn.com/docs/ai-elements/base/model-selector
OWNS: `P/chat/header.rs` (connection button + menu leave), new `P/input/model_selector.rs`, `P/input/bar.rs` (slot), `views/settings_view/assistant_connections*` NOT touched.
FILES TO OPEN: `P/chat/header.rs::{connection_button, connection_menu}`, `P/backend/prompt.rs::selected`, `crates/engine/src/ai/connections.rs`.
GOAL: popup anchored to the composer bar: groups "Agents" (ACP) and "Endpoints" (OpenAI, model name shown), radio selection, "Manage connections" -> `Action::OpenSettings`. Header keeps only the status dot, new chat, history, overflow. Effort/model menus: render nothing until T14 provides options.
TESTS: kittest 320 pt: popup lists all saved connections grouped, selecting emits the existing select action, popup stays inside the panel rect.
DO NOT: change connection storage or settings UI.

## T14 ACP config options (protocol)
OWNS: `crates/acp/src/events.rs` (new `SessionUpdate::ConfigOptions`, lenient parse), `crates/acp/src/command.rs` + `client/wire.rs` (`session/set_config_option`), `crates/acp/tests/`, then a small wiring in `P/state/model.rs` and `P/input/model_selector.rs` (sequence after T6/T7 and T13).
GOAL: parse `config_option_update` (id, name, category model/thought_level, options, current value) and the options returned by `session/new`; send `session/set_config_option`; selector shows model and effort menus only when the agent lists them. Unknown shapes stay `Other`. Verify the exact field names against the ACP schema (Context7 / agentclientprotocol.com) before coding.
TESTS: `crates/acp/tests/protocol_flow.rs` style with `examples/stub_agent.rs` extended; kittest for menus.
DO NOT: enable `fs` or `terminal` capabilities.

## [x] T15 Engine checkpoint journal and commands
OWNS: new `crates/engine/src/ai/checkpoint/{mod,journal,restore,commands}.rs` (<= 400 lines each), `crates/engine/src/ai/mod.rs`, `crates/engine/src/commands.rs` (ONE `register_*` call), `crates/engine/tests/core_commands.rs` (`CORE_IDS`), new `crates/engine/tests/assistant_checkpoint.rs`.
FILES TO OPEN: `ai/assistant_queue.rs` (accept path), `ai/assistant_chat_io.rs` (`write_private` use), `ai/assistant_gate.rs` (READ/WRITE lists), `tests/common/mod.rs`, `history_*` and `trash_*` commands.
GOAL: spec section 4.3. Journal appended in the accept path and direct-write path for `source: "assistant"`; commands `assistant.checkpoint_list`, `assistant.checkpoint_restore` (reverse replay through the normal write path, hash conflict check, report `restored` and `conflicts`, never overwrite a changed note). Not callable by the assistant.
TESTS: engine integration: create/modify/delete/rename turn -> restore -> vault equals before; edited-since note reported as conflict and untouched; over-cap entry marked non-restorable; assistant source denied; restore creates version-history snapshots.
DO NOT: store old text inside notes or outside `.notescraft/`; skip `craft-atomic`; add a dependency.

## T16 Checkpoint UI
Docs: https://ui.shadcn.com/docs/ai-elements/base/checkpoint
OWNS: new `P/chat/changes/checkpoint.rs`, `P/chat/conversation.rs` (marker call), `P/state/actions.rs` (Action::RestoreCheckpoint), `P/state/model.rs` (turn ids; sequential chain), `P/chat/view.rs` (sequence last), engine call via `engine_command`.
GOAL: after each turn that changed notes: separator marker with the file count and a Restore button; click -> `crate::dialog` listing files by kind; confirm runs `assistant.checkpoint_restore` on a worker; result System line with restored and conflicts (conflict row opens version history for the note). Applied-changes list for the turn appears in the Changed notes tree (T9) as "Applied". Not shown for read-only turns or in history mode.
TESTS: kittest with a fixture vault: turn with an accepted modify -> marker visible -> restore -> note text equals old; conflict case shows the error.
DO NOT: truncate the conversation; run IO in the paint path.

## T17 Bases result table in a message
OWNS: new `P/chat/message/base_table.rs`, `P/chat/message/mod.rs`, row hook in the trace tool row (one call).
FILES TO OPEN: `crates/engine/src/bases/` (query result shape), `views/base_view/table/` (read-only reuse if cheap), tool title `notescraft_base_*`.
GOAL: a completed Bases query tool row opens to a bounded table (50 rows x 8 columns, truncated cells, "N more" line) and an "Open in Base" link. Parse defensively; malformed = plain text summary.
TESTS: unit parse of a fixture result; kittest 320 pt table scrolls horizontally inside its own area, page does not.
DO NOT: run queries from the UI; add dependencies.

## T18 Docs and status
OWNS: `ROADMAP.md`, `docs/ARCHITECTURE.md` (assistant panel section), `docs/CODE-MAP.md` (new folders `chat/message`, `chat/turn`, `chat/changes`, `chat/cite`, `chat/scroll`, `input/*`). Update only status, public API, numbers.

## PaperCraft (designs, later, not a coding task)
Project 'NotesCraft Plugins', file id `3accb94a799e7b22`; artboard list in spec section 7. Designs should be done before T3-T13 start if the owner wants pixel parity; otherwise implement from the spec and reconcile after.