@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/pagination.md

@@ -0,0 +1,88 @@
+# Pagination and counts
+
+The footer that says which rows are showing and how many exist ("1–100 of 1,262"), with previous and next controls and the selection count.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- A collection is too large for one page or one view.
+- Lists over 20 items, with pagination at the bottom.
+- People need to know where they are and return to a section, which pagination supports better than endless scroll.
+
+## When not to use
+
+- Collections under five items.
+- Steps in a flow. Use buttons or a progress control.
+- When the total cannot be known, do not invent one; use an open-ended count such as "100+".
+
+## Structure
+
+1. Range and total ("Showing 1–9 of 24")
+2. Selection count when rows are selected
+3. Previous page
+4. Page numbers or compact "1 of 3"
+5. Next page
+
+## Guidelines
+
+- Show the range and the total. When rows are selected, put the selected count first.
+- Use the compact "1 of 3" form where a row of page numbers does not fit, and offer jump to page past about 9 pages.
+- Previous is inactive on the first page and Next on the last.
+- Show pagination even when everything fits on one page, so the layout does not shift.
+- Changing page clears the selection; say so in the selection count.
+
+## Content
+
+- Show the current range and the total together, for example "1–100 of 1,262", with an en dash and thousands separators.
+- Name controls by destination, "Previous page", "Page 6", not "left".
+- Do not show a count while the table is loading.
+
+## Accessibility
+
+- Wrap page links in a nav landmark with an aria-label, and mark the current page with aria-current="page".
+- Give previous, next and page buttons labels; set them explicitly for non-English interfaces.
+- 4.1.3 Status Messages: the range and selection count update as status text, "2 of 24 selected".
+- After a page change, move focus and scroll to the top of the new content.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Reach the pagination controls |
+| Enter / Space | Go to the previous, next or chosen page |
+
+## Examples
+
+### footer
+
+```tsx
+import { Checkbox, TablePagination } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Table footer", description: "Range and total always show, even on one page. With rows selected, the count comes first. Previous is off on the first page, Next on the last.", order: 1 };
+
+export default function Example() {
+	const [page, setPage] = useState(0);
+	const [selectSome, setSelectSome] = useState(true);
+	return (
+		<div className="grid w-full max-w-xl gap-3">
+			<label className="flex items-center gap-2 text-base text-ink-2">
+				<Checkbox checked={selectSome} onCheckedChange={(v) => setSelectSome(v === true)} />
+				Show with 2 rows selected
+			</label>
+			<div className="overflow-hidden rounded-sm border border-line bg-surface">
+				<div className="grid h-24 place-items-center text-base text-ink-3">Page {page + 1} of the listings table</div>
+				<TablePagination page={page} pageCount={14} pageSize={100} total={1262} selected={selectSome ? 2 : 0} noun="listings" onPageChange={setPage} />
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- List table
+- Data grid
+- Columns menu
+- Bulk action bar

package/agent/docs-md/pane-layout.md

@@ -0,0 +1,105 @@
+# Pane layout
+
+A workspace that fills the screen with columns of panes people resize with splitters and rearrange by dragging, for tool pages such as trading screens and editors where everything has to stay in view.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Tool pages where people watch and act on several regions at once and need them all in view, such as a trading screen.
+- Letting people give more room to the region they work in and put regions where they expect them.
+
+## When not to use
+
+- List, record and dashboard pages. Use the app shell with one side panel, or a Configurable dashboard for movable items.
+- Content people read top to bottom. Let the page scroll instead.
+
+## Structure
+
+1. Columns of panes, edge to edge, divided by 1px splitters
+2. Pane header: grip, title or a view switch, one action, ⋯ menu
+3. Pane body that scrolls on its own
+4. Splitter: 1px line with an 8px grab area, primary on hover and focus
+5. Drop line in primary where a dragged pane will land
+6. Collapsed: header only, or a 36px strip with the name when the whole column is collapsed
+
+## Guidelines
+
+- Fit the viewport: panes scroll inside, and charts and lists size themselves to their pane with usePaneSize.
+- Every drag has a keyboard path and a menu path: Move up, down, left, right and Wider, Narrower, Taller, Shorter.
+- Splitters follow the window splitter pattern: role separator, a value from 0 to 100, arrow keys, Home and End.
+- Save the layout per person, and offer Reset layout with Undo, never a confirmation.
+- One action at most in a pane header; switch views with a segmented control in place of the title.
+- Below the stack width, panes stack in one column and the page scrolls.
+- Let people collapse a pane they don't need right now; it keeps its header so it is one click from coming back.
+- Put a pane's own options, such as Show as table, at the top of its ⋯ menu rather than as more header buttons.
+- Put a strip of at most six key figures above the panes, the ones people check first, and keep the panes for detail.
+- Keep secondary detail behind a request: an expandable row, a tooltip or the pane's ⋯ menu (Show as table, View all), so the panes show what people watch.
+- Keep panes people use all the time, such as filters, as panes rather than drawers, so they never hide the controls they hold.
+
+## Content
+
+- Name every pane with a noun people use for that region: Markets, Order book, Place order.
+
+## Accessibility
+
+- 2.5.7 Dragging movements: moving and resizing work from the pane's menu with single clicks.
+- Each pane is a section named by its title; each move and resize is announced.
+- 1.4.10 Reflow: below the stack width the panes stack and nothing scrolls sideways.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ← → (column splitter), ↑ ↓ (pane splitter) | Resize by 16px; with Shift, 64px |
+| Home End | Smallest or largest size |
+| Space or Enter on a grip | Pick up or drop the pane |
+| ← → ↑ ↓ while picked up | Move the pane to another column or position |
+| Esc while picked up | Put the pane back |
+
+## Examples
+
+### workspace
+
+```tsx
+import { PaneLayout, type PaneLayoutValue, toast, usePaneSize } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Resize and rearrange panes", description: "Three panes in two columns. Drag a splitter or use its arrow keys to resize; drag a pane's grip, or press Space on it and use the arrow keys, to move it; or use Move, Wider and Taller in the pane's menu. Each pane reports its own size.", order: 1 };
+
+const DEFAULT: PaneLayoutValue = [
+	{ id: "left", size: 2, panes: [{ id: "list", size: 1 }] },
+	{ id: "right", size: 3, panes: [{ id: "detail", size: 2 }, { id: "log", size: 1 }] },
+];
+
+function Size() {
+	const { width, height } = usePaneSize();
+	return <p className="p-3 text-sm text-ink-2 tabular">{width} × {height} px</p>;
+}
+
+export default function Example() {
+	const [layout, setLayout] = useState(DEFAULT);
+	return (
+		<div className="h-96 w-full overflow-hidden rounded-sm border border-line">
+			<PaneLayout
+				aria-label="Example workspace"
+				stackBelow={480}
+				value={layout}
+				onValueChange={setLayout}
+				onReset={() => { const before = layout; setLayout(DEFAULT); toast.success("Layout reset", { action: { label: "Undo", onClick: () => setLayout(before) } }); }}
+				panes={{
+					list: { title: "Requests", children: <Size /> },
+					detail: { title: "Request detail", children: <Size /> },
+					log: { title: "Activity", children: <Size /> },
+				}}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- App shell and sidebar navigation
+- Side panel (drawer)
+- Board and board item

package/agent/docs-md/period-comparison.md

@@ -0,0 +1,66 @@
+# Comparison over time
+
+Every headline number says what it compares against: this period vs the previous period of the same length, with arrow, sign and colour.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** "312 applications" means nothing on its own. Teams add comparisons in different ways (vs last month, vs last year, percentage or absolute), so numbers on different screens can't be read together.
+
+**Solution:** TwoUX compares the current period with the previous period of the same length by default. Stats show the number, then the change with arrow, sign and colour, then what it is compared with. Charts draw the previous period as a dashed grey line behind the current one.
+
+**Built from:** Stat card with comparison, Line chart card, Breakdown table, Bar chart, Segmented control, Data visualisation colours
+
+## How it works
+
+1. Pick the period with one control above the chart: 7d, 30d, 90d. It drives every chart and stat on the page.
+2. The stat leads with the number, then the change ("↑ 18%"), then the comparison in words ("vs 264 the 30 days before").
+3. The line chart shows the previous period as a dashed grey line behind the current period, with a legend naming both.
+4. Under the chart, the breakdown table shows current and previous side by side and the change in both units.
+5. Every chart can switch to a table, which is also its accessible version.
+
+## When to use
+
+- For any KPI or trend on a dashboard, report or record header.
+- Next to a single figure in a record, compare with the board median instead of time, so people can judge it without opening a report.
+
+## When not to use
+
+- When there is no previous period (new listing, new team). Show a dash, not "+100%".
+- To compare categories in one period. Use a bar chart or breakdown, not a time comparison.
+
+## Guidelines
+
+- Never rely on colour alone for up or down; always add an arrow and a sign.
+- Green and red follow meaning, not direction. A fall in time to first apply is good.
+- Bars start at zero. Line charts may start elsewhere, but say so on the axis.
+- One y-axis per chart. Two measures with different scales get two charts side by side.
+- Keep each series the same colour on every chart; status colours never colour a series.
+- The current, incomplete period is marked as incomplete so a half week does not look like a drop.
+
+## Content
+
+- Change text: "↑ 18% vs 264 the 30 days before". Units are always stated.
+- Chart footer names the source and when it updated: "updated 12 min ago".
+
+## Accessibility
+
+- The change is read as text ("up 18 percent"), not only drawn as an arrow.
+- Chart points are reachable with the arrow keys, and the table view carries every number.
+
+## Do
+
+- Do say what every number is compared against.
+- Do use the previous period of the same length.
+
+## Don't
+
+- Don't use two y-axes.
+- Don't show a percentage change from zero.
+
+## Related
+
+- Data export
+- Filtering and search
+- Stat card with comparison
+- Line chart card
+- Breakdown table

package/agent/docs-md/plan-card.md

@@ -0,0 +1,120 @@
+# Plan preview
+
+The plan an agent shows before a multi-step or costly run: numbered steps people can remove, risky steps marked in words, and nothing running until it is approved.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Before any run with several steps, or one that costs time or money, so people can see it first.
+- When a step reaches people outside the workspace (an email, a message to a candidate) or cannot be undone (a close, a delete).
+- When the agent was started by a schedule or a request people did not write step by step.
+
+## When not to use
+
+- A single, small change. Use Suggested changes (suggested-changes), which is the review step for one proposal.
+- Questions whose answer would change the plan. Ask first with a Clarifying question (clarifying-question); show the plan once the answer is known.
+- Work that has already started. Show progress in the Agent run (agent-run) and use PlanChange only if the plan itself changes.
+
+## Structure
+
+1. Header (plan title, origin label with what it is based on)
+2. Step rows (number, step, optional detail, risk line, Remove or Put back)
+3. Footer (count "3 of 4 steps", note "nothing runs until you approve", Cancel, Approve plan)
+4. Plan change line (PlanChange) in the run if the plan changes later
+
+## Guidelines
+
+- Show the plan before any multi-step or costly run. Nothing runs until the person approves, and never on a timeout.
+- Each step is a plain action with its detail underneath. People can remove a step, and put it back, before approving.
+- Mark steps that reach people outside the workspace or cannot be undone, with an icon and words, not colour alone.
+- The footer counts what will run ("3 of 4 steps") and updates as steps are removed. Approve is disabled when no steps are left.
+- When any step is high-stakes, Approve and Cancel carry equal weight. This is the one exception to one primary action: both are outline buttons, so neither is nudged.
+- If the plan changes mid-run, add a PlanChange line saying what changed and why. Never reroute silently.
+- Ask clarifying questions first only if the answer changes the plan. Otherwise show the plan and let people adjust it.
+
+## Content
+
+- Title the plan by its outcome ("Close three expired listings and tell applicants"), not by the agent's method.
+- Write steps as actions in the order they happen. Put the consequence in the detail line: "Sends an email to 14 applicants".
+- Name the risk in words: "Reaches people outside the workspace" or "Can't be undone". Do not soften it.
+- PlanChange reads as what changed, then why: "Plan changed: skipped the email step. The listing has no applicants."
+
+## Accessibility
+
+- The plan is an ordered list, so the number of steps and each position are announced (SC 1.3.1).
+- Risk is shown by an icon and a line of text, not colour alone (SC 1.4.1).
+- Remove and Put back are real buttons with the step number in their hidden label, and a removed step carries the hidden word "removed" (SC 4.1.2).
+- Nothing starts on a timer, so there is no time limit to adjust (SC 2.2.1). Approving is the review step for work that records data (SC 3.3.4).
+- PlanChange is a role="status" line, so a plan change is announced without moving focus (SC 4.1.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through Remove buttons, then Cancel and Approve plan |
+| Enter / Space | Remove or put back the focused step, or press the focused button |
+
+## Examples
+
+### low-stakes
+
+```tsx
+import { PlanCard, PlanChange, toast } from "@twoux/ui";
+
+export const meta = { title: "A plan, then a change to it", description: "With no risky step, Approve is the one primary action. If the plan changes during the run, a PlanChange line says what and why.", order: 2 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full max-w-xl gap-3">
+			<PlanCard
+				title="Tidy the Operations Coordinator listing"
+				from="Your request, listing LST-1041"
+				steps={[
+					{ id: "1", title: "Rename the listing", detail: "Operations Coordinator (hybrid)" },
+					{ id: "2", title: "Add the salary range", detail: "£32,000 to £36,000" },
+					{ id: "3", title: "Extend the closing date by 30 days", detail: "21 Nov to 21 Dec" },
+				]}
+				onApprove={(kept) => toast.success(`Approved ${kept.length} steps`)}
+				onCancel={() => toast("Plan cancelled. Nothing ran.")}
+			/>
+			<PlanChange what="Skipped the salary step" why="The listing already shows a range." />
+		</div>
+	);
+}
+```
+
+### plan
+
+```tsx
+import { PlanCard, toast } from "@twoux/ui";
+
+export const meta = { title: "A plan with a risky step", description: "Steps can be removed. The step that emails applicants is marked, so Approve and Cancel carry equal weight. Nothing runs until you approve.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-xl">
+			<PlanCard
+				title="Close three expired listings and tell applicants"
+				from="Weekly listing check, 3 listings past their closing date"
+				steps={[
+					{ id: "1", title: "Find listings past their closing date", detail: "Filter: Closes is before today · 3 listings" },
+					{ id: "2", title: "Close the 3 listings", detail: "Hides them from the careers page", risk: "irreversible" },
+					{ id: "3", title: "Email 14 applicants that the role has closed", detail: "Uses the template Role closed", risk: "external" },
+					{ id: "4", title: "Post a summary to #hiring" },
+				]}
+				onApprove={(kept) => toast.success(`Approved ${kept.length} steps`)}
+				onCancel={() => toast("Plan cancelled. Nothing ran.")}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Agent run timeline
+- Clarifying question card
+- Agent permissions
+- Suggested changes
+- Step card

package/agent/docs-md/popover-rules.md

@@ -0,0 +1,88 @@
+# Popover rules
+
+Shared behaviour for every floating layer (menus, filters, snooze, selectors): one open at a time and never cut off.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- For short supporting content or a small set of controls tied to a trigger: filter values, snooze times, column choices.
+- When the person must stay in context and the page behind stays usable.
+
+## When not to use
+
+- For long reading or a multi-step task. Use a dialog or side panel.
+- For a one-line label. Use Tooltip.
+- Inside another popover. Open a submenu (one level) or a dialog instead.
+- For required fields that would be lost on outside click. Use a dialog.
+
+## Structure
+
+1. Trigger (aria-expanded)
+2. Floating panel (10px radius, shadow)
+3. Header (when dismissible)
+4. Body
+5. Footer actions (optional)
+
+## Guidelines
+
+- Only one popover is open at a time; opening a menu, filter, snooze or selector closes any other.
+- Popovers open on a user action, never on page load.
+- Placement flips and shifts to stay inside the panel and the screen, 8px from the edge. Nothing is ever cut off.
+- Open 4 to 6px from the trigger, aligned to its start edge.
+- Close on outside click, Esc, or when focus leaves; return focus to the trigger.
+- Only the body scrolls, never sideways.
+
+## Content
+
+- Header in sentence case, one short line, when the popover can be dismissed.
+- No help articles or Learn more links inside; keep help at page level.
+- Footer buttons follow Button wording: Cancel and Apply.
+
+## Accessibility
+
+- Triggers set aria-expanded (and aria-haspopup for menus). Enter or Space opens.
+- Give the panel a role (menu or dialog) and a label.
+- Esc closes and focus returns to the trigger.
+- The popover must not hide the focused element.
+- At 320px width it fits without sideways scrolling.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter / Space | Open or close from the trigger |
+| Esc | Close and return focus to the trigger |
+| Tab | Move through controls inside; leaving closes it |
+
+## Examples
+
+### one-at-a-time
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, FilterBar, FilterPill } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "One at a time, never cut off", description: "Open the Status filter, then the menu: the first closes. Each opens 4px from its trigger, flips and shifts to stay 8px inside the screen, and Esc returns focus to the trigger.", order: 1 };
+
+const OPTIONS = ["Open", "Closing soon", "Draft", "Closed"].map((v) => ({ value: v, label: v }));
+
+export default function Example() {
+	const [status, setStatus] = useState<string[]>([]);
+	return (
+		<div className="flex w-full items-center justify-between gap-3">
+			<FilterBar><FilterPill field="Status" options={OPTIONS} selected={status} onChange={setStatus} /></FilterBar>
+			<DropdownMenu>
+				<DropdownMenuTrigger asChild><Button variant="outline" size="sm">Actions</Button></DropdownMenuTrigger>
+				<DropdownMenuContent align="end"><DropdownMenuItem>Duplicate</DropdownMenuItem><DropdownMenuItem>Archive</DropdownMenuItem></DropdownMenuContent>
+			</DropdownMenu>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Dropdown menu
+- Tooltip
+- Button

package/agent/docs-md/prompt-editor.md

@@ -0,0 +1,90 @@
+# Prompt editor with fields
+
+An editor where row fields and team files are removable chips, inputs and outputs are listed with types, and the prompt is tested on a few rows before running on the whole table.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Defining the prompt behind an AI column or a per-row agent.
+- When the output must have a type (text, person, link) to land in the table.
+
+## When not to use
+
+- Asking a question once. Use the Message composer (message-composer).
+- Repeated tasks with filter inputs. Use the Task builder (task-builder).
+
+## Structure
+
+1. Hint line ({{ for a field, @ for a team file, ⌘K to rewrite)
+2. Prompt text with field chips
+3. Inputs list with types
+4. Output (one field or several) with types
+5. Suggest outputs from prompt
+6. Test on 3 rows
+
+## Guidelines
+
+- Fields are chips you can remove, not hidden syntax.
+- List inputs and outputs with their type.
+- Test on a few rows before running on the whole table; show the per-row cost.
+- Let the prompt return "Not found" when it is unsure, rather than forcing an answer.
+- ⌘K rewrites selected text as a suggestion, not an overwrite.
+
+## Content
+
+- Use plain headings in the prompt ("Your task", "Rules").
+- Field names match the column names people see.
+
+## Accessibility
+
+- Each chip's remove button is named ("Remove field listing.title") (SC 4.1.2).
+- {{ and @ open a combobox list of fields or files, with arrow keys and Enter (APG combobox).
+- Output type is a radiogroup with a label (APG radio).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| {{ | Add a field from the row |
+| @ | Add a team file |
+| ⌘K / Ctrl+K | Rewrite the selected text |
+| Enter | Insert the highlighted field |
+| Esc | Close the field list |
+
+## Examples
+
+### editor
+
+```tsx
+import { PromptEditor } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Prompt with fields as chips", description: "Fields from the row are removable chips, not hidden syntax. Inputs and outputs are listed with their type, and Test on 3 rows comes before running on the whole table.", order: 1 };
+
+export default function Example() {
+	const [segs, setSegs] = useState<(string | { field: string })[]>(["List the 3 key requirements in ", { field: "description" }, " for the role ", { field: "role" }, ", in under 12 words."]);
+	const [testing, setTesting] = useState(false);
+	const [results, setResults] = useState<{ row: string; value: string }[]>();
+	return (
+		<div className="w-full max-w-xl">
+			<PromptEditor
+				segments={segs}
+				onRemoveField={(i) => setSegs((s) => s.filter((_, j) => j !== i))}
+				inputs={[{ name: "description", type: "Long text" }, { name: "role", type: "Text" }]}
+				outputs={[{ name: "key_requirements", type: "Text" }]}
+				testing={testing}
+				results={results}
+				onTest={() => { setTesting(true); setTimeout(() => { setTesting(false); setResults([{ row: "LST-1040", value: "Portfolio, Figma, hybrid in Leeds" }, { row: "LST-1041", value: "React, TypeScript, 3+ years" }, { row: "LST-1045", value: "Playwright, CI, test plans" }]); }, 800); }}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- AI column
+- Task builder
+- Templates gallery
+- Change review

package/agent/docs-md/propose-apply.md

@@ -0,0 +1,65 @@
+# Propose, then apply
+
+The assistant never edits on its own: it lists suggested changes with checkboxes, the person applies them in one step, each change shows its progress, and Undo reverses all of it.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** When AI edits records directly, people can't see what changed or trust it with real data. When every feature invents its own approval flow, nobody knows whether clicking a suggestion has already changed something.
+
+**Solution:** Changes arrive as a Suggested changes card: one row per change with what changes, an Edit and a Dismiss. Apply N changes (⌘↵) turns the card into a step card that ticks off each change as the table updates. A toast offers Undo.
+
+**Built from:** Suggested changes, Step card, Assistant side panel, Toast, Agent permissions, AI origin label
+
+## How it works
+
+1. The answer ends with "Suggested changes · 2", each a row with a checkbox, the change and its effect ("New closing date 6 Dec").
+2. "Nothing changes until you apply" sits next to the buttons: Dismiss, Edit, Apply 2 changes ⌘↵.
+3. The person unticks, edits or dismisses individual changes without regenerating the whole proposal.
+4. Apply turns the card into a step card: each change gets a spinner then a tick, with a counter "1 / 2". The table updates row by row.
+5. When done, a toast confirms ("2 changes applied") with Undo; ⌘Z also works.
+6. If a change fails, its step says why and offers Retry; the others stay applied.
+
+## When to use
+
+- Whenever the assistant or an agent would change records: rename, extend, close, reassign.
+
+## When not to use
+
+- For answers that change nothing; just answer.
+- For actions the person set to Allow in agent permissions; those run and are logged, with Undo where possible.
+- For changes that reach people outside the workspace, such as emailing candidates. Those also need explicit approval of the message itself (see Agents acting on your behalf).
+
+## Guidelines
+
+- A proposal shows the consequence of each change before it runs, including whether it can be undone.
+- Approve is never pre-selected or auto-focused for risky changes.
+- If applying needs to deviate from the proposal, stop and explain rather than change something else.
+- The proposal is the same component everywhere: assistant answers, agent runs and the Inbox.
+
+## Content
+
+- Each change is a verb and object with its effect: "Extend Operations Coordinator by 30 days. New closing date 6 Dec."
+- Apply button says the count: "Apply 2 changes".
+
+## Accessibility
+
+- Step progress and completion are announced as status messages.
+- Apply has a keyboard shortcut (⌘↵) and focus does not jump to it automatically.
+
+## Do
+
+- Do let people untick individual changes.
+- Do offer Undo after applying.
+
+## Don't
+
+- Don't apply anything from inside the answer text.
+- Don't regenerate the whole proposal to fix one change.
+
+## Related
+
+- Undo and destructive actions
+- Agents acting on your behalf
+- Showing reasoning and progress
+- Suggested changes
+- Step card