@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/command-palette.md

@@ -0,0 +1,126 @@
+# Command palette (⌘K)
+
+A searchable list of actions and destinations, scoped to the current selection, opened with ⌘K from anywhere.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Run any action by name without hunting through menus, especially on a selection of rows.
+- Jump to a record or page by typing part of its name.
+- Learn shortcuts: every action shows its key, so the palette teaches the faster path.
+
+## When not to use
+
+- As the only way to reach an action. Every command also exists as a visible button or menu item.
+- Filtering the table. Use Filter (F) and its type-ahead field list.
+- Confirming irreversible actions. A destructive command picked in the palette still opens the Confirmation dialog.
+
+## Structure
+
+1. Search input with a scope chip ("2 listings") and Esc hint
+2. Group: Actions on selection, each with its shortcut
+3. Group: Go to (records and pages)
+4. Footer hints: ↑ ↓ navigate, ↵ run, Tab change scope
+
+## Guidelines
+
+- Opens centred near the top, up to 560px wide, with focus in the search input.
+- Scope defaults to the current selection and shows it as a chip; Tab switches to the whole workspace.
+- Order results with actions on the selection first, then Go to; show the most used actions before typing.
+- Results update with each keystroke, within 400 ms.
+- Enter runs the highlighted item and closes the palette; reversible results offer Undo in a toast.
+- Esc closes it and focus returns to where it was.
+
+## Content
+
+- Commands start with a verb and name the object: "Extend end by 30 days", "Export 2 rows as CSV".
+- Commands that need more input end with an ellipsis: "Extend end to a date…".
+- Use the same command names as the buttons and menus they mirror.
+- Placeholder text says what can be typed: "Search or run a command".
+
+## Accessibility
+
+- Built as a modal dialog containing a combobox with a listbox popup; DOM focus stays in the input and aria-activedescendant points to the highlighted item.
+- Group headings are exposed as group labels and each option's shortcut is part of its accessible description (1.3.1).
+- ⌘K uses a modifier, so it stays on when single-key shortcuts are turned off (2.1.4).
+- Announce the number of results through a polite live region as the person types (4.1.3).
+- Esc always exits; there is no keyboard trap (2.1.2).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘K / Ctrl+K | Open or close the palette |
+| ↑ / ↓ | Move through results |
+| Enter | Run the highlighted command |
+| Tab | Switch scope between selection and workspace |
+| Esc | Close and return focus |
+
+## Examples
+
+### dialog
+
+```tsx
+import { Button, CommandDialog, CommandGroup, CommandInput, CommandItem, CommandList, CommandShortcut, Kbd } from "@twoux/ui";
+import { Search, Settings, Users } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "As a dialog (⌘K)", description: "Opens over the page, traps focus, and returns it to where it came from on close (Radix Dialog). Press the button to try.", order: 2 };
+
+export default function Example() {
+	const [open, setOpen] = useState(false);
+	return (
+		<>
+			<Button shortcut="⌘K" onClick={() => setOpen(true)} variant="outline"><Search />Search</Button>
+			<CommandDialog open={open} onOpenChange={setOpen}>
+					<CommandInput placeholder="Search or run a command…" />
+					<CommandList>
+						<CommandGroup heading="Go to">
+							<CommandItem onSelect={() => setOpen(false)}><Users />Members</CommandItem>
+							<CommandItem onSelect={() => setOpen(false)}><Settings />Settings<CommandShortcut><Kbd>G</Kbd><Kbd>S</Kbd></CommandShortcut></CommandItem>
+						</CommandGroup>
+					</CommandList>
+			</CommandDialog>
+		</>
+	);
+}
+```
+
+### inline
+
+```tsx
+import { Command, CommandEmpty, CommandFooter, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, Kbd } from "@twoux/ui";
+import { Briefcase, Clock, Copy, Plus, Users } from "lucide-react";
+
+export const meta = { title: "Commands and pages", description: "One line per item: icon, label, shortcut on the right. Groups have quiet sentence-case labels. Type to filter; arrows and Enter to run.", order: 1 };
+
+export default function Example() {
+	return (
+		<Command className="w-full max-w-md rounded-sm border border-line shadow-card">
+			<CommandInput placeholder="Search or run a command…" />
+			<CommandList>
+				<CommandEmpty>No results. Try “extend” or “listings”.</CommandEmpty>
+				<CommandGroup heading="Actions on 2 listings">
+					<CommandItem><Clock />Extend by 30 days<CommandShortcut><Kbd>T</Kbd></CommandShortcut></CommandItem>
+					<CommandItem><Copy />Duplicate<CommandShortcut><Kbd>D</Kbd></CommandShortcut></CommandItem>
+				</CommandGroup>
+				<CommandSeparator />
+				<CommandGroup heading="Go to">
+					<CommandItem><Briefcase />Listings<CommandShortcut><Kbd>G</Kbd><Kbd>L</Kbd></CommandShortcut></CommandItem>
+					<CommandItem><Users />Pipeline<CommandShortcut><Kbd>G</Kbd><Kbd>P</Kbd></CommandShortcut></CommandItem>
+					<CommandItem><Plus />New listing<CommandShortcut><Kbd>C</Kbd></CommandShortcut></CommandItem>
+				</CommandGroup>
+			</CommandList>
+			<CommandFooter><span className="flex items-center gap-1"><Kbd>↵</Kbd> run</span><span className="flex items-center gap-1"><Kbd>esc</Kbd> close</span></CommandFooter>
+		</Command>
+	);
+}
+```
+
+## Related
+
+- Shortcut sheet (?)
+- App shell and sidebar navigation
+- Page header
+- Toast

package/agent/docs-md/confidence-note.md

@@ -0,0 +1,87 @@
+# Confidence note
+
+A short note beside agent output that says, in words, what the agent is unsure about, why, and the safer option or the way to check.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- When the output affects other people, shared records or money and the agent has a real reason to be unsure.
+- When the cause is specific: missing data, out-of-date data, or an ambiguous request.
+- When the agent is unsure whether a change applies to one item, all items or future items. Ask before acting.
+
+## When not to use
+
+- As a standing disclaimer on every answer. Use the caveat line under the message box (assistant-panel).
+- To report an error. Use an error message (error-messages) with the fix.
+- Low-stakes output the person can see and change in a second. A note there is noise people learn to skip.
+
+## Structure
+
+1. Lead line ("Not sure:" and the cause)
+2. Safer option or what to check
+3. Optional actions (for example Check the source, Use the safer option)
+
+## Guidelines
+
+- Say uncertainty in words, never as a percentage. A figure like 72% looks exact and gives people nothing to do.
+- Say what caused it: missing data, out of date, or an ambiguous request.
+- Offer a safer alternative or a concrete way to check, such as the record to open or the filter to apply.
+- Scale to the stakes: use it when the output affects other people, shared records or money, and leave it off elsewhere.
+- When unsure whether a change applies to one item, all items or future items, ask before acting. Do not pick the widest.
+- Place the note next to the output it is about, not in a corner, so it is read together with it.
+
+## Content
+
+- Start with "Not sure:" and the cause: "Not sure: the connection is 35 minutes, and the last export was in March."
+- Follow with what to do, as an instruction: "Check the rail times before sending this to applicants."
+- Avoid "might", "may" and "possibly" on their own. Say which part, and why.
+- Do not apologise. State the cause and the next step.
+
+## Accessibility
+
+- The cause is text with an icon that is hidden from assistive technology, so meaning does not rely on colour or the icon (SC 1.4.1).
+- The note sits next to the output in reading order so it is read with it (SC 1.3.1).
+- Any action in the note is a real button with a visible name (SC 4.1.2).
+- If a note appears after the output has loaded, put it in a role="status" region so it is announced (SC 4.1.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the note's actions, if it has any |
+| Enter / Space | Press the focused action |
+
+## Examples
+
+### note
+
+```tsx
+import { Button, ConfidenceNote, toast } from "@twoux/ui";
+
+export const meta = { title: "Unsure, and why", description: "The cause in words, then the safer option and a way to check. Use it when the output reaches people, shared records or money.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full max-w-xl gap-3">
+			<ConfidenceNote
+				cause="the venue's opening hours are from March, so they may be out of date"
+				action={<><Button size="xs" variant="outline" onClick={() => toast("Opened the venue page")}>Check the venue page</Button><Button size="xs" variant="ghost" onClick={() => toast("Draft saved without a time")}>Send without a time</Button></>}
+			>
+				Check the hours before this goes to 14 applicants. If you cannot, send the invitation without a time and ask them to reply.
+			</ConfidenceNote>
+			<ConfidenceNote cause="your request does not say whether the new closing date applies to the 3 selected listings or to every listing in this view">
+				I have not changed anything. Tell me which, and whether future listings should follow it too.
+			</ConfidenceNote>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Citations and sources
+- Clarifying question card
+- AI origin label
+- Suggested changes
+- Change review

package/agent/docs-md/configurable-dashboard.md

@@ -0,0 +1,76 @@
+# Configurable dashboard
+
+A personal overview where each person adds, removes, moves and resizes items on a board, with an items palette to add from, a saved layout and a reset to the default.
+
+Kind: pattern · Group: Patterns: data and dashboards
+
+**Problem:** Recruiters, hiring managers and the head of talent watch different things. One fixed overview is either too crowded for each of them or missing what one of them needs, so they build their own spreadsheets instead.
+
+**Solution:** Start from the static dashboard layout as the default, then let each person change it on a Board. Add items opens the items palette in a side panel; items move by drag, keyboard or menu; Remove is undoable and puts the item back in the palette; the layout is saved per person and Reset to default layout brings back the original.
+
+**Built from:** Board and board item, Items palette, Side panel (drawer), Page header, Dropdown menu, Toast, Empty state, Stat card with comparison, Line chart card
+
+## How it works
+
+1. Build the default layout first with the static dashboard guidelines; this is what new people see and what Reset returns to.
+2. Put Add items in the page header. It opens the items palette in a side panel that pushes the board, and closes with the same button or Esc.
+3. People add an item by dragging it from the palette onto the board, or by choosing Add to dashboard on the palette item, which places it at the end of the board and moves focus to it.
+4. People move and resize items by dragging the handles, by keyboard on the handle, or from the item menu (Move earlier, Move later, Wider, Narrower, Taller, Shorter).
+5. Remove from dashboard is the last entry in the item menu. It removes at once, shows a toast with Undo, and the item reappears in the palette.
+6. Save every change to the person's layout on the server as it happens; there is no Save button.
+7. Reset to default layout sits in the page header's more menu. It applies at once and offers Undo in a toast.
+
+## When to use
+
+- For a personal home page where people in different roles need different items, such as "My open listings" for a recruiter and "Cost per hire" for the head of talent.
+- When there are more useful items than fit on one screen, and each person only needs some of them.
+- When people use the page for investigation and want related items side by side.
+
+## When not to use
+
+- For a shared report that must read the same for everyone. Use the static dashboard.
+- When there are fewer than about six possible items. Rearranging adds work and little value; fix the layout instead.
+- Inside a side panel or dialog. The board is the main content of its page.
+
+## Guidelines
+
+- Make the whole page configurable or none of it. Don't pin some items in place among movable ones.
+- Moving an item keeps its size, its settings and what it shows, such as the period or the location it is set to.
+- Show a drop preview the size and shape of the item while dragging. Items swap when there is room and push others along when there is not; a drop outside the board puts the item back.
+- The board has 4 columns on wide screens, 2 on tablets and 1 on phones. Store one layout per column count, so a change on a laptop doesn't scramble the phone layout.
+- Layouts are personal. Changing yours never changes a colleague's dashboard or the workspace default.
+- When the board is empty, show an empty state with Add items and Reset to default layout.
+
+## Content
+
+- Header actions: "Add items" and, in the more menu, "Reset to default layout".
+- Removal toast names the item: "Removed Applications this week. Undo".
+- Reset toast: "Dashboard reset to the default layout. Undo".
+- Empty board: "Your dashboard has no items" with "Add items to see your hiring numbers here."
+
+## Accessibility
+
+- Dragging is never the only way: every add, move and resize also works by keyboard and from a menu or button with a single pointer action.
+- Announce each pick-up, move, resize, drop, add and removal in a polite live region, naming the item and its new position: "Applications this week moved to row 1, column 2".
+- After Add to dashboard, move focus to the new item's handle; after Remove, move focus to the next item, or to Add items if the board is now empty.
+- Drag and resize handles have names that include the item title: "Move Applications this week", "Resize Applications this week".
+
+## Do
+
+- Do return a removed item to the palette so it can be added again.
+- Do keep Remove and Add items close in meaning and in place: one undoes the other.
+- Do keep the layout the person made on their next visit and on any device with the same column count.
+
+## Don't
+
+- Don't ask for confirmation before removing an item; offer Undo.
+- Don't show a banner inside the board after a removal. The toast is enough.
+- Don't store the layout only in the browser; it is lost on another device or after clearing data.
+
+## Related
+
+- Static dashboard
+- Dashboard items
+- Board and board item
+- Items palette
+- Undo and destructive actions

package/agent/docs-md/confirmation-dialog.md

@@ -0,0 +1,93 @@
+# Confirmation dialog
+
+A modal question before an irreversible or high-impact action, stating the consequence and offering the safe option first.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Before actions that cannot be undone or that affect other people, such as closing listings that stop taking applications.
+- Bulk actions on many records where a mistake is costly to repair.
+- When the person must read a consequence they could not otherwise see, such as what happens to existing applicants.
+
+## When not to use
+
+- Reversible actions. Do them at once and offer Undo in a Toast.
+- Collecting lots of input or showing a record. Use the Side panel.
+- Reporting an error. Use a Banner or the Error state in place.
+- Low-risk actions that are easy to redo, which need no confirmation at all.
+
+## Structure
+
+1. Title: a question naming the action and count ("Close 2 listings?")
+2. Body: the consequence, and what is kept
+3. Footer: safe secondary button ("Keep open")
+4. Footer: destructive button named after the action ("Close listings")
+
+## Guidelines
+
+- Width up to 420px, centred, with the page dimmed behind it. One dialog at a time; never open a dialog from a dialog.
+- Footer buttons sit on the right: the safe option first, the destructive action last in the destructive colour.
+- On open, focus goes to the safe button, so Enter cannot destroy anything by accident.
+- Esc and the safe button both close it with no change. On close, focus returns to the control that opened it.
+- For the most dangerous, rare actions, require an unusual step such as typing the listing name.
+- After confirming, report the result with a Toast.
+
+## Content
+
+- Title as a specific question with the verb and the object: "Close 2 listings?", never "Are you sure?".
+- Body states the consequence and what stays: "They stop taking applications now. The 140 people who already applied stay in your pipeline."
+- Buttons name the outcome ("Keep open", "Close listings"), never Yes, No or OK.
+- The confirm label matches the title's verb.
+
+## Accessibility
+
+- Use role="alertdialog" with aria-modal="true", aria-labelledby on the title and aria-describedby on the consequence.
+- Tab and Shift+Tab cycle inside the dialog; Esc closes it, so focus is contained but never trapped (2.1.2).
+- Focus returns to the opener on close, or to the next logical row if the opener was removed (2.4.3).
+- Confirming before data changes is one of the three ways to meet 3.3.4 Error Prevention.
+- The destructive button is identified by its label, not only its red colour (1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab / ⇧Tab | Move between the two buttons, wrapping inside the dialog |
+| Enter | Activates the focused button (the safe one on open) |
+| Esc | Closes without changing anything |
+
+## Examples
+
+### close-listings
+
+```tsx
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, Button, toast } from "@twoux/ui";
+
+export const meta = { title: "Close listings", description: "Closing removes listings from job boards and cannot be undone. Focus starts on the safe button, so Enter keeps them open. Esc does the same.", order: 1 };
+
+export default function Example() {
+	return (
+		<AlertDialog>
+			<AlertDialogTrigger asChild>
+				<Button variant="outline">Close 2 listings</Button>
+			</AlertDialogTrigger>
+			<AlertDialogContent>
+				<AlertDialogHeader>
+					<AlertDialogTitle>Close 2 listings?</AlertDialogTitle>
+					<AlertDialogDescription>They come off every job board today. Applicants and notes are kept, but the listings cannot be reopened.</AlertDialogDescription>
+				</AlertDialogHeader>
+				<AlertDialogFooter>
+					<AlertDialogCancel>Keep open</AlertDialogCancel>
+					<AlertDialogAction variant="destructive" onClick={() => toast.success("2 listings closed")}>Close listings</AlertDialogAction>
+				</AlertDialogFooter>
+			</AlertDialogContent>
+		</AlertDialog>
+	);
+}
+```
+
+## Related
+
+- Toast
+- Side panel (drawer)
+- Shortcut sheet (?)

package/agent/docs-md/connected-tools.md

@@ -0,0 +1,80 @@
+# Connected tools
+
+Outside tools listed in the + menu and settings, each with a detail card saying what it can read and change, where data is stored and who connected it.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Connecting a tool at the moment it is needed, from the + menu.
+- Reviewing what a connected tool can access.
+
+## When not to use
+
+- Setting what the agent may do with TwoUX data. Use Agent permissions (agent-permissions).
+- Adding a single file. Use Attach a file in the Message composer (message-composer).
+
+## Structure
+
+1. Tools menu (tool, status, Connect, Browse tools)
+2. Detail card (name, type, status badge, description, Can read, Can change, Data stored, Connected by, Privacy policy, Disconnect, Permissions)
+
+## Guidelines
+
+- Before and after connecting, say in plain words what it can read and change, where data is stored and who connected it.
+- Let people scope a tool to what it needs.
+- Give each tool a consistent icon and name across menus and answers.
+- When a tool fails or is partly loaded, say so inline and offer reconnect or retry; avoid blank states that imply success.
+- Show when data was last synced.
+
+## Content
+
+- "Brings candidates and pipeline stages into TwoUX so the assistant can compare them with your listings."
+- Use "Nothing" rather than leaving Can change empty.
+
+## Accessibility
+
+- The tools list is a menu; each tool is a menuitemcheckbox when it toggles use, or a menuitem when it connects (APG menu).
+- The detail card uses a description list for its fields (SC 1.3.1).
+- Disconnect is a destructive action; confirm with the consequence and keep focus order (SC 2.4.3, 3.3.4).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Right arrow | Open the tools submenu from the + menu |
+| Space | Turn a connected tool on or off for this conversation |
+| Enter | Connect or open the tool |
+| Esc | Close the menu |
+
+## Examples
+
+### tool
+
+```tsx
+import { ConnectedToolCard, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Say what a tool can do", description: "Before and after connecting: what it can read, what it can change, where data is stored and who connected it.", order: 1 };
+
+export default function Example() {
+	const [on, setOn] = useState(true);
+	return (
+		<div className="w-full max-w-md">
+			<ConnectedToolCard
+				tool={{ id: "cal", name: "Google Calendar", kind: "Calendar", connected: on, canRead: "Free and busy times of interviewers", canChange: "Nothing. It suggests interview slots only.", stored: "Not stored; read when you ask", connectedBy: on ? "Priya Shah on 3 Nov" : undefined, privacyHref: "#privacy" }}
+				onConnect={() => { setOn(true); toast.success("Connected Google Calendar"); }}
+				onDisconnect={() => { setOn(false); toast.success("Disconnected Google Calendar", { action: { label: "Undo", onClick: () => setOn(true) } }); }}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Agent permissions
+- Message composer
+- Team instructions and files
+- Connector picker
+- Provider logo

package/agent/docs-md/connector-picker.md

@@ -0,0 +1,127 @@
+# Connector picker
+
+Search and connect outside services. Each row says what connecting lets the product do, and a dialog explains the access before anything is shared.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- Connecting several outside services, from onboarding or from Settings.
+- Showing what is connected and what needs attention in one place.
+
+## When not to use
+
+- Setting what an agent may do with a tool. Use Agent permissions (agent-permissions).
+- Reviewing one tool in depth. Use the detail card in Connected tools (connected-tools).
+
+## Structure
+
+1. Search (with the number of services)
+2. Connected group
+3. All services group
+4. Row (logo, name, what it lets the product do, Connect, Reconnect or Manage)
+5. Connect dialog (access in plain words, who it is shared with, OAuth or API key, Cancel)
+
+## Guidelines
+
+- Add search with the count of services, and put Connected first.
+- Say what connecting lets the product do, in plain words, before connecting: "Read and send email".
+- Say who the connection is shared with, for example "Only you" or "Everyone in TwoUX".
+- OAuth opens the provider in a new window. Say so on the button ("Continue to Slack") and bring people back with a status message.
+- Test an API key before saving it, store it encrypted and never show it again. Say all three beside the field.
+- When a connection expires, show Needs attention with the reason and a Reconnect button, never colour alone.
+- Disconnecting lives in Settings and asks what stops working before it does.
+
+## Content
+
+- "Read your calendar to find free times. Cannot change events."
+- "Slack needs you to sign in again. Reconnect to resume the daily summary."
+
+## Accessibility
+
+- Rows are a list under group headings; the group names are real headings (SC 1.3.1).
+- Buttons repeat the service name for assistive technology: "Connect Slack" (SC 2.4.6, 4.1.2).
+- The dialog traps focus, returns it to the button and announces success with role="status" (APG dialog, SC 4.1.3).
+- Status is carried by words (Connected, Needs attention) as well as colour (SC 1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through the search, then each row's button |
+| Enter or Space | Connect, Reconnect or Manage |
+| Esc | Close the dialog without connecting |
+
+## Examples
+
+### api-key
+
+```tsx
+import { Button, ConnectDialog, type Connector } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Connect with an API key", description: "The key is tested before it is saved. Try any text to see the error, or \"nw-live-key\" to connect.", order: 2 };
+
+const XERO: Connector = { id: "xero", provider: "xero", can: ["Read invoices and payments", "Cannot create or change anything"] };
+
+export default function Example() {
+	const [open, setOpen] = useState(false);
+	return (
+		<>
+			<Button variant="outline" onClick={() => setOpen(true)}>Connect Xero</Button>
+			<ConnectDialog
+				connector={XERO}
+				open={open}
+				onOpenChange={setOpen}
+				method="apikey"
+				scope="Only you"
+				onTestKey={async (key) => { await new Promise((r) => setTimeout(r, 700)); return key === "nw-live-key" ? undefined : "Xero did not accept that key. Check you copied all of it from Settings, API keys."; }}
+				onDone={() => {}}
+			/>
+		</>
+	);
+}
+```
+
+### connect-oauth
+
+```tsx
+import { ConnectDialog, ConnectorPicker, toast, type Connector } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Search, connect, reconnect", description: "Connected first, then everything else. Slack shows Needs attention with Reconnect. Connecting asks first, in plain words.", order: 1 };
+
+const START: Connector[] = [
+	{ id: "gmail", provider: "gmail", can: ["Read and send email as you", "Find threads about a candidate"], connected: true },
+	{ id: "slack", provider: "slack", can: ["Post summaries to channels you pick", "Read messages in those channels"], connected: true, problem: "Your Slack sign-in expired. Reconnect to resume the daily summary." },
+	{ id: "calendar", provider: "google-calendar", can: ["Read free and busy times", "Create interview events"] },
+	{ id: "drive", provider: "google-drive", can: ["Read files you choose", "Never change or delete files"] },
+	{ id: "notion", provider: "notion", can: ["Read pages you share with it", "Add notes to a database"] },
+];
+
+export default function Example() {
+	const [list, setList] = useState(START);
+	const [open, setOpen] = useState<Connector | null>(null);
+	return (
+		<div className="w-full max-w-lg">
+			<ConnectorPicker connectors={list} onConnect={setOpen} onManage={() => toast("Manage opens Settings, Connections")} />
+			<ConnectDialog
+				connector={open}
+				open={!!open}
+				onOpenChange={(o) => !o && setOpen(null)}
+				scope="Everyone in TwoUX"
+				onAuthorise={() => new Promise((r) => setTimeout(r, 1000))}
+				onDone={() => open && setList((l) => l.map((c) => (c.id === open.id ? { ...c, connected: true, problem: undefined } : c)))}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Connected tools
+- Agent permissions
+- Provider logo
+- Empty state
+- Confirmation dialog

package/agent/docs-md/consistency.md

@@ -0,0 +1,53 @@
+# Consistency
+
+TwoUX's first rule: the same job gets the same component, the same token and the same behaviour, on every screen, whether a designer, an engineer or a language model wrote the code. Consistency is what makes a dense product learnable.
+
+Kind: foundation · Group: Key principles
+
+## Principles
+
+- Same job, same component. People should not have to wonder whether different words, situations or actions mean the same thing.
+- Consistency is also a WCAG requirement. Components with the same function are identified the same way (3.2.4) and repeated navigation keeps its order (3.2.3).
+- Learn once, use everywhere. People transfer expectations from what they already know, inside the product as much as between products.
+- A design system manages design at scale with reusable components and patterns; its value is lost the first time someone rebuilds a component by hand.
+
+## Guidelines
+
+- The job to component registry is the source of truth. Each row names a job and the one component that does it. Examples: show a record's state = Badge; confirm a destructive action = Dialog; peek at a record from a list = Side panel; run any command = Command menu (⌘K); ask the assistant = Assistant (⌘J); act on many rows = Bulk bar; show a one-line result with undo = Toast; filter a list = Filter pill.
+- If a job is not in the registry, do not improvise. Propose a new row, or extend an existing component, through design review. Always check for an existing component before building a custom one.
+- No one-off styling. Product code sets no colours, font sizes, radii, shadows or spacing; those come from components and tokens.
+- Same behaviour, too: Esc closes the innermost layer, J and K move through every list, ↵ opens, ⇧↵ opens full page. A component that behaves differently in one place is a different component.
+- Same words: one term per concept (listing, not job post in one place and role in another), and the same button label for the same action.
+
+## Content
+
+- Rules for code written by language models: 1. Import components from the TwoUX package; never recreate a button, badge, menu or panel with raw HTML and CSS.
+- 2. Look up the job in the registry before choosing a component. If two components could fit, the registry decides.
+- 3. Use tokens only. No hex, rgb, raw px font sizes, raw radii, raw shadows or raw durations. Choose the token by its role, not its value.
+- 4. Use the icon meaning table; never pick an icon because it looks right.
+- 5. Copy follows the Writing page: UK English, sentence case, verb-first buttons.
+- 6. Lint must pass. Stylelint and ESLint rules reject raw values and unknown tokens. A generated change that needs a lint exception goes to human review.
+
+## Accessibility
+
+- Predictable components are an accessibility feature: the same icon and the same accessible name for the same function.
+- Navigation and the shell appear in the same order on every page.
+- Reusing tested components carries their keyboard and focus behaviour; custom components lack built-in testing and accessibility.
+
+## Do
+
+- Use the Toast for every 'done, undo?' message, from bulk close to AI actions.
+- Add to the registry when you add a component.
+
+## Don't
+
+- Do not make a 'special' button for one page.
+- Do not copy a component's markup to tweak it; extend the component.
+- Do not accept generated code that hard-codes visual values, even when it looks right.
+
+## Related
+
+- Design tokens
+- Iconography
+- Writing
+- Keyboard model