@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/provider-logo.md

@@ -0,0 +1,97 @@
+# Provider logo
+
+The official mark of a service people sign in with or connect, shown unaltered on a white tile beside the service's name.
+
+Kind: component · Group: Content · Status: built, import from @twoux/ui
+
+## When to use
+
+- Identifying a service someone signs in with, such as Google or Microsoft.
+- Identifying a service someone connects, such as Slack or Google Drive, in a list or a connection dialog.
+
+## When not to use
+
+- Marking a competitor or a product we studied as a reference. Those get a text name only.
+- Decoration, avatars or a stand-in for our own brand. Use Avatar (avatar) for people and the product mark for us.
+- Logos of services that are not connectable. A mark implies the connection exists.
+
+## Structure
+
+1. Tile (white in both themes, hairline border)
+2. Official mark (unaltered)
+3. Name or label beside it
+
+## Guidelines
+
+- Use the official mark only for third-party services people sign in with or connect. Never for competitors or reference products.
+- Show the mark unaltered: no recolouring, no cropping, no effects, no new background shapes.
+- Put the mark beside the service's name. When it stands alone, give it a label so the service is still named.
+- Keep the tile white in light and dark themes so dark marks, such as GitHub and Notion, stay visible.
+- To add a provider, add a line to the list in scripts/provider-logos.mjs and run node scripts/provider-logos.mjs. Check the brand's own page for permitted use first.
+- The icon sources are licensed for reuse: Iconify's logos set is CC0, vscode-icons and thesvg-color are MIT. Trademarks stay with their owners, so show a mark only to identify that service.
+
+## Content
+
+- "Continue with Google" and "Connect Slack": the name is always in words, never only in the mark.
+- When alone, label it with the service name only, for example "Google Drive".
+
+## Accessibility
+
+- Beside a visible name the mark is decorative and hidden from assistive technology. Alone, it has role="img" and an aria-label with the service name (SC 1.1.1).
+- The tile keeps the mark's edges distinct from either theme (SC 1.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| None | Not focusable. The button or row that contains it is the focus stop. |
+
+## Examples
+
+### alone-and-sizes
+
+```tsx
+import { ProviderLogo } from "@twoux/ui";
+
+export const meta = { title: "Alone, with a label", description: "When the mark has no name beside it, give it a label. Three sizes; the mark inside is never changed.", order: 2 };
+
+export default function Example() {
+	return (
+		<div className="flex items-center gap-4">
+			<ProviderLogo provider="slack" size="sm" label="Slack" />
+			<ProviderLogo provider="slack" size="md" label="Slack" />
+			<ProviderLogo provider="slack" size="lg" label="Slack" />
+		</div>
+	);
+}
+```
+
+### beside-name
+
+```tsx
+import { PROVIDERS, ProviderLogo, type ProviderId } from "@twoux/ui";
+
+export const meta = { title: "Beside the name", description: "The mark identifies the service and the name says it. On a white tile in both themes, so dark marks stay visible.", order: 1 };
+
+const SHOWN: ProviderId[] = ["google", "microsoft", "github", "slack", "notion", "google-drive"];
+
+export default function Example() {
+	return (
+		<ul className="grid w-full max-w-md gap-1">
+			{SHOWN.map((p) => (
+				<li key={p} className="flex items-center gap-3 rounded-xs px-1 py-1.5">
+					<ProviderLogo provider={p} />
+					<span className="text-base text-ink">{PROVIDERS[p].label}</span>
+				</li>
+			))}
+		</ul>
+	);
+}
+```
+
+## Related
+
+- Connector picker
+- Sign in
+- Connected tools
+- Avatar and avatar stack

package/agent/docs-md/radio.md

@@ -0,0 +1,83 @@
+# Radio
+
+Lets people choose exactly one option from a short, visible list in a form.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To pick one option from two to seven, when seeing all options helps the decision: Full time or Part time.
+- When both choices need a visible explanation, which a single checkbox cannot give.
+- Inside a form that is applied with a Save or Publish button.
+
+## When not to use
+
+- For eight or more options. Use a select or Dropdown menu.
+- For several choices at once. Use Checkbox.
+- To switch the view of data outside a form. Use Segmented control.
+- For a single on/off setting. Use Checkbox or Switch.
+
+## Structure
+
+1. Group label (legend)
+2. Radio circle (15px)
+3. Option label
+4. Option hint (optional)
+
+## Guidelines
+
+- Circle is 15px; selected shows a thick primary ring.
+- Preselect the most likely or safest option. Never preselect a risky one.
+- Add None when no choice is valid, since a radio group cannot be cleared.
+- Stack options vertically. Inline is allowed for two short options, as in Full time / Part time.
+- Order from most to least likely, or least to most risky.
+
+## Content
+
+- Labels short and parallel, ideally under three words.
+- The legend asks or names the choice: Contract type.
+- Avoid overlapping ranges in number options.
+
+## Accessibility
+
+- Native radios share a name, wrapped in fieldset and legend (or role="radiogroup" with a label).
+- Tab enters the group on the selected option; arrow keys move and select.
+- Labels are clickable so the target exceeds the 15px circle.
+- Ring and border have 3:1 contrast against white.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move into the group, onto the selected option |
+| Arrow keys | Move to and select the next or previous option |
+| Space | Select the focused option if not selected |
+
+## Examples
+
+### group
+
+```tsx
+import { RadioField, RadioGroup } from "@twoux/ui";
+export const meta = {"title": "Radio group", "description": "One choice from a short, visible list. Arrow keys move and select; Tab leaves the group.", "order": 1};
+
+export default function Example() {
+	return (
+		<fieldset className="grid gap-2">
+			<legend className="mb-1 text-sm font-medium text-ink">Contract</legend>
+			<RadioGroup defaultValue="full">
+				<RadioField id="r-full" value="full" label="Full time" />
+				<RadioField id="r-part" value="part" label="Part time" hint="Under 30 hours a week." />
+				<RadioField id="r-fixed" value="fixed" label="Fixed term" />
+				<RadioField id="r-zero" value="zero" label="Zero hours" disabled />
+			</RadioGroup>
+		</fieldset>
+	);
+}
+```
+
+## Related
+
+- Checkbox
+- Segmented control
+- Form validation

package/agent/docs-md/ranked-list.md

@@ -0,0 +1,102 @@
+# Ranked list
+
+Ranked rows with a series dot or icon, name, value and change, optionally a sparkline. Beside a stacked chart it is the chart's legend; each row links to the record.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- As the legend of a stacked chart when people also need the ranking and values for the latest period.
+- A dashboard list of the top items by one measure, each opening its record.
+
+## When not to use
+
+- To compare many attributes per row or sort by them. Use the TwoUX List table.
+- For a price or index list where the code and unit matter. Use the TwoUX Change list.
+
+## Structure
+
+1. Heading that names the moment, such as Top models on 28 Apr
+2. Rank
+3. Series dot (or icon)
+4. Name
+5. Optional sparkline
+6. Value, tabular
+7. Change: arrow, sign and percentage
+
+## Guidelines
+
+- Rank by the value shown, highest first, and say which period ranks it in the heading.
+- When the list is a legend, each dot keeps its series colour from the chart; never recolour by rank.
+- Show change with an arrow and a sign; colour it green or red only when the direction means good or bad, otherwise grey.
+- Hovering or focusing a row highlights that series in the chart, and the chart's crosshair can highlight the row.
+- Each row is one link or one button for the whole row, never several actions.
+
+## Content
+
+- Values carry their unit (bn tokens, £); changes say the comparison in the heading or subtitle.
+- Keep names short enough to fit; the full name goes in the record.
+
+## Accessibility
+
+- 1.4.1 Use of Color: change is an arrow, a sign and a word read out (up or down), not colour.
+- 1.3.1 Info and Relationships: the list is an ordered list, so rank is announced.
+- 4.1.2 Name, Role, Value: each row is a single link or button whose name includes the label, value and change.
+- 2.4.7 Focus Visible: rows show the focus ring inside their edge.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the next row |
+| Enter | Open the row's record |
+
+## Examples
+
+### top-models
+
+```tsx
+import { useState } from "react";
+import { CartesianChart, ChartFrame, type ChartSeries, chartTable, RankedList } from "@twoux/ui";
+
+export const meta = { title: "Top models beside a stacked chart", description: "The ranked list is the legend: each row's dot matches its series, ranked by the last day, with the change since the week before.", order: 1 };
+
+const DAYS = ["22 Apr", "23 Apr", "24 Apr", "25 Apr", "26 Apr", "27 Apr", "28 Apr"];
+const SERIES: ChartSeries[] = [
+	{ id: "atlas", label: "Atlas 3", data: [3.1, 3.4, 3.3, 3.8, 2.9, 2.6, 4.2] },
+	{ id: "nimbus", label: "Nimbus Pro", data: [2.4, 2.5, 2.7, 2.6, 2.1, 1.9, 2.8] },
+	{ id: "kestrel", label: "Kestrel 2", data: [1.2, 1.4, 1.5, 1.7, 1.3, 1.2, 1.9] },
+	{ id: "orbit", label: "Orbit Mini", data: [1.6, 1.5, 1.4, 1.4, 1.1, 1.0, 1.3] },
+	{ id: "other", label: "Others", data: [0.9, 0.9, 1.0, 1.1, 0.8, 0.7, 1.0] },
+];
+const CHANGE = [12.4, 6.1, 31.0, -9.7, 4.2];
+const tokens = (n: number) => `${n.toFixed(1)}bn`;
+
+export default function Example() {
+	const [active, setActive] = useState<string | null>(null);
+	return (
+		<ChartFrame className="w-full" title="Tokens by model" description="Daily tokens, last 7 days" table={chartTable("Day", DAYS, SERIES)}>
+			<div className="grid grid-cols-[minmax(0,1fr)_minmax(0,18rem)] gap-6 max-lg:grid-cols-1">
+				<CartesianChart kind="bar" stacked x={DAYS} series={SERIES} format={(n) => `${n}bn`} aria-label="Tokens by model, stacked by day" />
+				<div className="grid content-start gap-1">
+					<h4 className="px-2 text-sm font-medium text-ink-2">Top models on 28 Apr</h4>
+					<RankedList
+						aria-label="Top models on 28 April, by tokens"
+						items={SERIES.map((s, i) => ({ id: s.id, label: s.label, value: s.data[6] ?? 0, change: CHANGE[i], colorIndex: i, href: `#${s.id}` }))}
+						format={tokens}
+						upIs="neutral"
+						activeId={active}
+						onActiveChange={setActive}
+					/>
+				</div>
+			</div>
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Stacked area chart
+- Change list
+- Stat card with comparison

package/agent/docs-md/reasoning-progress.md

@@ -0,0 +1,72 @@
+# Showing reasoning and progress
+
+While working, say the current step in words with a running timer and a Stop; when done, collapse to "Thought for 2.1s · 4 steps" that opens on request.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** A bare spinner for ten seconds makes people think the assistant is stuck, and a wall of reasoning buries the answer. Without one rule, each surface shows progress differently.
+
+**Solution:** Thinking shows "Thinking" with a timer, then step titles with one line of detail. Send becomes Stop. When the answer starts, the steps collapse into one summary line that stays in the history.
+
+**Built from:** Thinking and steps, Assistant side panel, Agent run timeline, Step card, Message composer
+
+## How it works
+
+1. Under about one second, show nothing; stream the answer straight away.
+2. Otherwise show "Thinking" with a running timer and the send button becomes Stop.
+3. Each step appears with a short title and one line of detail: "Reading 9 listings".
+4. Beyond about ten seconds, show the current step with an estimate, or a progress bar when the total is known ("3 of 50 rows").
+5. When the answer starts, collapse to "Thought for 2.1s · 4 steps", expandable on click.
+6. Stop keeps what was done so far, marks the run as stopped, and offers Regenerate.
+
+## When to use
+
+- Any assistant answer, agent run or AI column run that takes more than a second.
+
+## When not to use
+
+- To justify an answer. Step text is a progress report, not proof; use citations for evidence.
+
+## Guidelines
+
+- Show what was read and done, with counts and time, in neutral words. No first-person "I'm thinking hard".
+- Keep proposed, done and evidence apart: plan steps, completed steps, and citations are three different things.
+- Step states have one look everywhere: queued, running, waiting for you, done, skipped, failed, stopped.
+- Stop is always visible while anything runs and acts at once.
+- Never show credentials, token counts or raw system prompts in steps.
+- Collapsed by default in the side panel, where the answer is the main content.
+- Two stages: working (nothing to show yet: step text and timer) and writing (the answer streams). Keep a small working indicator until the last part has arrived, so a pause in streaming doesn't look like the end.
+- Stream only prose. Tables, lists of records and files render in place as a skeleton with "Loading 12 listings" until complete, then appear whole.
+- Thinking is reasoning; steps that read or change data are execution. Execution goes in the agent run or step card, never inside "Thinking".
+- Offer "Answer now" only when a useful answer exists from the work so far; what was done stays visible.
+- Show thinking expanded by default only where the answer isn't the main content, such as a generated column cell's detail.
+- Summaries count honestly: "2 of 5 steps" for steps in order, "3 done · 1 running · 1 queued" for parallel steps; add failed and stopped only when non-zero, and end with why it stopped: "2 of 5 steps · stopped".
+- A group's status is its most urgent child's: failed over waiting over running over done. Nest steps two levels at most.
+
+## Content
+
+- Step titles are present participles while running ("Reading 9 listings") and past tense when done ("Read 9 listings").
+- Duration uses rounded values: "Thought for 7s".
+
+## Accessibility
+
+- Announce the current step politely and the finished state once; don't announce every token.
+- Step state uses icon shape as well as colour.
+- The working label stays the same text ("Thinking") while it runs, so screen readers aren't re-reading a changing label.
+
+## Do
+
+- Do name the current step in words.
+- Do keep the collapsed summary in the conversation history.
+
+## Don't
+
+- Don't show a bare looping animation for long waits.
+- Don't swap the label for streaming reasoning text; it flickers.
+
+## Related
+
+- Propose, then apply
+- Agents acting on your behalf
+- Generated table columns and enrichment
+- Thinking and steps

package/agent/docs-md/record-detail.md

@@ -0,0 +1,71 @@
+# Record detail: side panel, overlay or full page
+
+Open a record in a side panel that pushes the list by default, overlay it on narrow or wide-content pages, and go to the full page for deep work.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Opening records in modals hides the list people compare against; opening a full page every time loses their place. Teams pick a different container on every screen.
+
+**Solution:** Enter or a click opens the side panel in push mode. J and K move to the next record and the panel follows. Esc closes. Open (⇧↵) goes to the full page. Overlay replaces push below about 1100px or when the content needs width.
+
+**Built from:** Side panel (drawer), List table, Data grid, Page header, Breadcrumb, Tabs (underline)
+
+## How it works
+
+1. Enter or a click on a row opens the side panel. The row stays highlighted and the list stays usable.
+2. The panel has a control bar (previous, next, position, open full page, close), then ID, title and status, then tabs and sections.
+3. J and K move to the next or previous row; the panel follows without closing.
+4. Open (⇧↵) moves to the full record page, with breadcrumbs back to the list and the same filters.
+5. Esc closes the panel and returns focus to the row that opened it.
+
+## When to use
+
+- Push side panel: on list pages people work through one record after another (listings, candidates, inbox).
+- Overlay side panel: when the page is narrower than about 1100px, or holds wide tables or dashboards that pushing would crush.
+- Full page: for long records, history, or editing many related sections.
+
+## When not to use
+
+- Don't use a modal dialog for record detail; it hides the rows people compare against. Modals are for confirmations.
+- Don't open the detail inline as an expanding row; expanded rows pile up and clutter the table.
+
+## Guidelines
+
+- A split view never replaces the full page; the panel is for deciding the next step, the page is for everything about one record.
+- Only one secondary panel of a kind at a time; the assistant and record detail share the same side panel slot.
+- Keep the identifying columns visible next to a pushed panel so people know which row they are on.
+- People can switch push and overlay with ⇧P, and the choice is remembered.
+- With several rows selected, the panel shows a useful summary of the selection, not a list of names.
+- The side panel shares the single right-hand slot with the assistant and help panels; opening one replaces the other, and closing it restores the previous one.
+- If a form in the panel has unsaved changes, J, K, Esc and close ask before discarding (see Unsaved changes). Single-field edits save on Enter and never ask.
+- Section actions sit in each section's header on the right ("Edit details"); record-wide actions sit in the panel footer.
+- The Details section shows absolute timestamps with their source: "Created 6 November 2026, 09:14 GMT by Priya Shah".
+
+## Content
+
+- Empty fields say "Add", so the gap is also the way to fill it.
+- Timestamps are relative with the exact date on hover.
+- Fields the person can't edit are shown as read-only text with the reason on hover, such as "Set by the job board feed".
+
+## Accessibility
+
+- A push panel is non-modal: it sits in the focus order after the list and never traps focus.
+- An overlay panel that covers content behaves as a modal dialog: focus moves in, Tab is trapped, Esc closes and focus returns.
+- The panel must not fully hide the focused row.
+
+## Do
+
+- Do keep J/K working while the panel is open.
+- Do return focus to the row on close.
+
+## Don't
+
+- Don't open record detail in a centred modal.
+- Don't open a second panel on top of the first.
+
+## Related
+
+- Keyboard-first navigation
+- Inline editing and validation
+- Ask about what's on screen
+- Side panel (drawer)

package/agent/docs-md/regenerating-answers.md

@@ -0,0 +1,70 @@
+# Regenerating an answer
+
+Regenerate reruns the same question with the same context and replaces the latest answer, keeping the earlier version one step away. It never touches changes already applied.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** The first answer sometimes takes the wrong angle: too long, the wrong listings, the wrong period. Typing "try again" sends a new message, so the thread fills with near-duplicates and the assistant reads the bad answer as context.
+
+**Solution:** Put a Regenerate button in the answer actions of the latest answer. It reruns the original question with the same context chips and settings, and the new answer takes the old one's place with a "2 / 2" switch to go back. It works the same after a finished answer and after Stop.
+
+**Built from:** Answer actions, Assistant side panel, Message composer, Thinking and steps, Suggested changes, AI origin label
+
+## How it works
+
+1. While the assistant works, the send button becomes Stop. Stop acts at once and keeps what was written so far, marked "Stopped".
+2. Under the latest answer, finished or stopped, show Regenerate in the answer actions next to Copy and feedback.
+3. Regenerate sends the same question with the same context chips, team files and Quick or Thorough setting. Nothing new is typed into the thread.
+4. The new answer replaces the old one in place. A "2 / 2" control under it switches between versions; the thread continues from the version on screen.
+5. If regenerating fails, keep the earlier version on screen and show the error under it with Try again.
+
+## When to use
+
+- When the person asked a question and wants a different take on the same request, such as a shorter summary of why LST-1044 has few applicants.
+- After Stop, when the answer was heading the wrong way and the question itself was fine.
+- For drafts the person will review anyway, such as a job description or an interview question set.
+
+## When not to use
+
+- To change the question. Edit the question or send a new message; regenerate repeats the input exactly.
+- On agent runs or scheduled tasks that changed data. Run them again as a new run under the same permissions.
+- On a single generated table cell. Use Try again on the cell (see Generated table columns).
+
+## Guidelines
+
+- Offer Regenerate on the latest answer only. Regenerating an earlier answer would drop everything after it, which the person can't see coming.
+- Only answers the person asked for get Regenerate. Starters, notices and approval results don't.
+- Regenerating never undoes or repeats applied changes. Changes already applied stay applied; reversing them is Undo's job.
+- Suggested changes in the replaced version are dropped if not yet applied; the new version brings its own proposal.
+- Each version keeps its own citations and origin label, so switching versions never mixes sources.
+
+## Content
+
+- Button tooltip and accessible name: "Regenerate answer". Version control: "2 / 2", with "Previous version" and "Next version" as names.
+- A stopped answer ends with "Stopped" in muted text, not an apology.
+- Failure: "Couldn't regenerate. Your earlier answer is still here." then Try again.
+
+## Accessibility
+
+- Regenerate sits in the answer actions, which follow the answer in tab order, so it is reached right after reading.
+- Focus stays on Regenerate while the new answer is written; announce "Regenerating" and then the finished answer once.
+- The version switch announces the version on screen: "Version 1 of 2".
+
+## Do
+
+- Do let people stop at once and regenerate straight after.
+- Do keep the earlier version reachable.
+- Do keep the same context chips for the rerun, visibly.
+
+## Don't
+
+- Don't put a confirmation or delay on Stop.
+- Don't show Regenerate on every answer in the thread.
+- Don't let regenerate reverse or repeat applied changes.
+
+## Related
+
+- Showing reasoning and progress
+- Propose, then apply
+- Generated drafts and files
+- Answer actions

package/agent/docs-md/run-status-bar.md

@@ -0,0 +1,94 @@
+# Run status bar
+
+The bottom bar of a sheet: Table up to date, or how far the run is with a meter, the credits spent so far and Stop; run history; and Auto-run with its cost per row.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- At the bottom of a sheet with computed columns, so people always see what is running and what it costs.
+
+## When not to use
+
+- For credits against a monthly limit. Use the Usage meter.
+- For one agent run with steps. Use Agent run.
+
+## Structure
+
+1. Status: icon, words, rows done of total, percentage and meter
+2. Credits so far
+3. Errors link
+4. Stop while running, or Run remaining with its cost
+5. Auto-run switch with the cost per row
+6. History popover
+
+## Guidelines
+
+- Stop is always available while anything runs, and stopping keeps the finished cells.
+- Show progress as rows and a percentage, with a meter, never a bare spinner.
+- State the credits spent so far while running, and the cost of Run remaining before it starts.
+- Auto-run states its cost per row next to the switch, before anyone turns it on.
+- History lists each run with rows, credits, outcome and when.
+
+## Content
+
+- Running: "1,240 of 2,000 rows · 62%". Stopped: "Stopped at 62%". Done: "Table up to date".
+- Costs use the unit: "≈ 1.5 credits / row".
+
+## Accessibility
+
+- The progress is a progressbar with its value; the status line is a live region.
+- Errors are words with an icon, not a red dot.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Reach Stop, Auto-run and History |
+
+## Examples
+
+### running
+
+```tsx
+import { RunStatusBar, Timestamp } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "A run with cost and Stop", description: "Progress, credits so far and Stop while running. Stop keeps finished rows; Run remaining states its cost first. Auto-run shows its cost per row before it is turned on.", order: 1 };
+
+const TOTAL = 2000;
+
+export default function Example() {
+	const [done, setDone] = useState(1240);
+	const [running, setRunning] = useState(true);
+	const [autoRun, setAutoRun] = useState(false);
+	useEffect(() => {
+		if (!running) return;
+		const t = window.setInterval(() => setDone((d) => { const n = Math.min(TOTAL, d + 20); if (n === TOTAL) setRunning(false); return n; }), 300);
+		return () => window.clearInterval(t);
+	}, [running]);
+	return (
+		<RunStatusBar
+			className="w-full rounded-sm border border-line"
+			running={running}
+			label="Work email"
+			done={done}
+			total={TOTAL}
+			errors={3}
+			creditsUsed={done * 0.5}
+			costPerRow={0.5}
+			onStop={() => setRunning(false)}
+			onRunRemaining={() => setRunning(true)}
+			autoRun={autoRun}
+			onAutoRunChange={setAutoRun}
+			history={[{ id: "1", label: "Work email · test on 10 rows", rows: 10, credits: 5, outcome: "Done", when: <Timestamp value={new Date(Date.now() - 3600_000)} /> }]}
+		/>
+	);
+}
+```
+
+## Related
+
+- Sheet grid
+- Usage meter
+- Agent run timeline

package/agent/docs-md/saved-tasks-schedules.md

@@ -0,0 +1,63 @@
+# Saved tasks and schedules
+
+Turn repeated requests into a task sentence with editable slots, test it once, then save it and optionally run it on a schedule.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** Teams retype the same long prompt every Monday, with slightly different wording each time and different results. Scheduled automation that has never been tested surprises people.
+
+**Solution:** The task builder writes the task as a sentence with slots ("Find [Live listings] with [apply rate under 3%]..."). Slots reuse filter values. An empty slot blocks Run and says which one. Test runs once in the assistant; Save as task adds an optional schedule.
+
+**Built from:** Task builder, Templates gallery, Prompt editor with fields, Agent run timeline, Agent permissions, Previous conversations
+
+## How it works
+
+1. Start from a template, a past answer ("Save as task") or a blank builder.
+2. The task is a sentence with slots; slots reuse filter values and record pickers.
+3. An empty slot is dashed and blocks Run, with a message naming it: "Choose who gets the titles before you run this."
+4. Run once (⌘↵) to test. The result arrives as a normal answer with proposals.
+5. Save as task, then optionally add a schedule ("Every Monday") and check the permissions the task will use.
+6. Scheduled runs appear first in previous conversations, notify before changing anything, and wait in the Inbox when they need approval.
+
+## When to use
+
+- For tasks repeated with the same structure and different values: weekly reviews, renaming, chasing hiring managers.
+
+## When not to use
+
+- For one-off questions; just ask.
+
+## Guidelines
+
+- Slots are the parts that change; the rest of the sentence is fixed so results are consistent.
+- Keep slots few; too many raise effort and reduce quality.
+- A task must run successfully once before it can be scheduled.
+- Scheduled tasks use the same agent permissions, shown explicitly when the schedule is set; changes default to Ask first.
+- Picking a template opens it as a draft task, never runs it.
+
+## Content
+
+- Tasks read as one sentence starting with a verb: "Find ..., then suggest ... and send them to ...".
+
+## Accessibility
+
+- Each slot is a button with its field name and current value, and opens a popover with one field.
+- Empty required slots are announced with the error message, not only shown dashed.
+
+## Do
+
+- Do reuse filter values in slots.
+- Do test before scheduling.
+
+## Don't
+
+- Don't save free prompts as scheduled tasks.
+- Don't let a schedule change records without a notice or approval.
+
+## Related
+
+- Agents acting on your behalf
+- Onboarding to an empty workspace
+- Propose, then apply
+- Task builder
+- Templates gallery