@palate/cli 0.0.0-stage → 0.0.1

package/kb/moves/waitlist-position-live.md

@@ -0,0 +1,60 @@
+---
+id: waitlist-position-live
+name: Your place in line, for real
+kind: data
+fits: [waitlist, launch, saas, ai, developer, community, honest, consumer]
+avoid: [enterprise-compliance, government, clinical, luxury]
+signature: false
+effort: m
+perf: "one POST on submit returns the position; no polling; the success panel swaps in place with no layout jump"
+a11y: "a polite status region says 'Joining the waitlist…'; on success focus moves to the result panel (tabIndex -1) so keyboard and screen-reader users stay where the form was"
+pairs_with: [referral-reward-reveal, copy-confirmation, made-with-proof]
+deps: "none; motion (small) only if the project already uses it for the swap"
+---
+
+## What it is
+
+When someone joins the waitlist, the form turns into the answer in the same place: "You're #1,284 on the list. Watch for your invite." The number is their real position, computed by the server at that moment, with their own share link right under it.
+
+## Why it works
+
+- A confirmation that says *where you are* turns a dead-end ("Thanks!") into a status you care about and come back to.
+- A real, specific number is believable; a vague "you're on the list" is forgettable.
+- It sets up the referral reward: once you know your place, "move up" means something.
+- Swapping in place keeps context: the reader's eyes and focus never leave the spot they acted on.
+
+## When to use / when not
+
+Use for invite-only launches, beta waitlists and pre-orders where people genuinely wait in an order you control.
+
+Not for: lists where order doesn't decide anything (then don't imply it does), enterprise sales, regulated sign-ups, or a list so small the number embarrasses. When the position is small and early (#12), it's fine: early is a feature; say "You're #12. Early." When order isn't decided by the queue, show no number.
+
+## Recipe
+
+1. **The server decides the number.** The join endpoint returns `{ ok, already, position, shareUrl }`. Position is the visitor's row in the real queue at that moment (palate orders by counted referrals, then sign-up time, then id). Never compute or fake it on the client.
+2. **Privacy for repeats.** Signing up again with the same email returns the existing record, but the position and link go only to the browser that signed up (a signed httpOnly cookie); anyone else gets `already: true` with nulls, so the form can't be used to look up someone's place.
+3. **Server-side validation mirrored on the client** (same email regex), so most mistakes are caught before a request; field errors (422) refocus the field, rate limits (429) say to wait, network failures say to check the connection. Each message says what happened and what to do.
+4. **Loading floor.** Keep the loading state for at least ~450 ms on both success and failure, so it reads as a state, not a flicker.
+5. **Swap in place.** The form and the result share a container of the same width; cross-fade (300 ms, ease-out, a small 12 px rise and 4 px blur in and out). The check icon arrives 120 ms later with a short spring. Under reduced motion it's a plain opacity cross-fade.
+6. **Copy by state.** New: "You're #N on the list. Watch for your invite." Already joined with a known place: "You're already on the list, #N." Already joined from another browser: "You're already on the list. We'll email you when your invite is ready." Format with `toLocaleString` and `tabular-nums`.
+7. **One result, every form.** If the page has two signups (hero and close), share the joined state through a tiny external store (`useSyncExternalStore`) so both show the result, and the header's "Join" link disappears once there is nothing left to do.
+8. **Focus.** Move focus to the result panel only in the form that was submitted (`tabIndex={-1}`, `focus({ preventScroll: true })`).
+9. **No JS:** the form posts normally and the server renders a result page with the same copy.
+
+## Pitfalls
+
+- Inflating positions ("#48,000") to seem in demand, or starting the count at a made-up offset.
+- Showing position to anyone who types an email (a privacy leak).
+- A success message that replaces the form with a different height, so the page jumps.
+- Confetti for joining a waitlist (see `confetti-free-celebration`).
+- Losing the result on reload; keep it for the session where possible.
+
+## How to verify
+
+- API tests: new, repeat-same-browser and repeat-other-browser return the right fields.
+- `palate states`: idle, loading, field error, rate-limited, offline and success all render at 390 and 1440 with no layout jump.
+- Keyboard: submit with Enter; focus lands on the result; screen reader announces the status.
+
+## Examples
+
+- palate's own site (`Waitlist.tsx`, `api/waitlist/route.ts`): the result panel swaps in where the form was, shows "You're #N on the list" from the real queue, and the share link below says each designer who joins with it moves you up.

package/kb/patterns/app-team-members.md

@@ -0,0 +1,27 @@
+---
+id: p.app.team-members
+kind: pattern
+title: Team members, roles and invites
+scope: [app]
+role: settings-members
+tags: [team, members, invite, roles, seats, permissions, workspace, admin, users, settings]
+answers: Who has access, what can they do, and what needs my attention (expired invites, seats)?
+use_when: [a workspace admin manages people, roles and invites]
+avoid_when: [a single-user product, a public directory of people]
+seen_in: [Linear workspace members, Vercel team settings, Notion members, GitHub org people]
+---
+
+**The job:** admins come here rarely, with one task (invite someone, fix a role, clean up). Make the current state readable at a glance, and the task one step away.
+
+**Blueprint (desktop, content 960–1100px)**
+1. **Header row:** title "Members" (20px/600) + a one-line state summary in muted text ("9 of 10 paid seats · 1 invite pending · 1 expired") on the left; primary button "Invite people" on the right. The invite form opens in a dialog or an inline expanding row, it does not sit permanently at the top.
+2. **Attention strip (only if needed):** expired invites, members without 2FA, seat limit reached. One line each with the fix inline ("Resend", "Buy a seat").
+3. **Members table:** person (avatar 28px + name 14/500 + email 13 muted), role (inline Select, disabled with a tooltip for the Owner and yourself), last active (relative, absolute in title), 2FA (only show when off, as a warning badge), row menu (Remove). Rows 52px. Search above the table when more than ~10 members.
+4. **Pending invites:** same table style, smaller section below: email, role, invited by, "Expires in 3 days" or "Expired 9 Oct" (danger text), actions Resend / Revoke.
+5. **Roles reference:** collapsed help ("What can each role do?") or a side note, not a big grid.
+
+**Seats:** the summary line is enough for most products. If seats are the product's billing unit, use the **seat strip** signature: one 24px cell per paid seat, filled (member), outlined dashed (held by invite), empty (free); a 1-line legend. Viewers that don't use seats are counted beside it.
+
+**Behaviour:** role change applies immediately with an undo toast; remove asks inline ("Remove Daniel? They lose access now." Remove / Cancel); revoke and resend are instant with undo.
+
+**Mistakes:** the invite form as the hero of the page; giant seat avatars; a role-description grid larger than the member list; Title Case everywhere; red for anything that isn't a problem.

package/kb/patterns/chat-agent-approvals.md

@@ -0,0 +1,31 @@
+---
+id: p.chat.agent-approvals
+kind: pattern
+title: Agent runs and human approvals
+scope: [chat, app, dashboard]
+role: review-queue
+tags: [agents, ai, approvals, review, runs, human in the loop, diff, changes, queue, log, cost, automation]
+answers: What do the agents want to change, should I let them, and what have they been doing?
+use_when: [AI agents or automations propose changes that a person must approve; a run log with costs]
+avoid_when: [fully automatic systems with nothing to approve (use a plain activity log)]
+seen_in: [GitHub pull request review, Linear triage, Stripe Radar review queue, n8n execution log]
+---
+
+**The job:** clear the queue quickly and safely, then glance at what ran. The approvals are the focal point; the log is reference.
+
+**Blueprint (1100–1280px; 8/4 split)**
+1. **Header:** "Agents" 20px + the state as the headline in body size: "2 changes waiting for you · 1 running · 1 failed overnight".
+2. **Queue (left, 8 cols):** one card per pending item, oldest first, expanded.
+   - Card header: what and where ("Enrichment wants to update 4 fields on **Granite Robotics**"), who triggered it, when, cost.
+   - **Diff body (signature):** a 3-column grid: field · old → new · source. Old value struck through in muted text; new value in foreground with a tinted background (success at 10%). Each field has a checkbox so people can apply some changes.
+   - Drafted messages show as the actual message (To, Subject, body) in an editable textarea, not a summary.
+   - Actions at the bottom right: secondary "Reject", primary "Apply 4 changes" (the count updates with the checkboxes). After deciding, the card collapses to one line with the outcome and Undo for 10 seconds.
+3. **Rail (right, 4 cols, sticky):** what's running now (steps with a progress bar and "28 of 40"), spend this month as a thin meter against the budget with the projected pace, failures needing action (with the error and Retry).
+4. **Log (below):** table of recent runs: agent, target, status dot, started (relative), duration, cost (tabular), expandable steps.
+
+**Rules**
+- Status colours: waiting = warning, running = info, failed = danger, done = muted. The primary button is the only accent.
+- Don't fake liveness: a running bar only for the actually running item; no pulsing "Live" badges.
+- Show sources for every proposed value; trust comes from provenance.
+
+**Mistakes:** approvals buried below stats; diffs as paragraphs; approve-all without per-field control; a dashboard of KPI cards on top.

package/kb/patterns/commerce-product-page.md

@@ -0,0 +1,34 @@
+---
+id: p.commerce.product-page
+kind: pattern
+title: Product detail page (small brand shop)
+scope: [commerce]
+role: product-detail
+tags: [product, pdp, shop, ecommerce, buy, basket, cart, gallery, price, maker, handmade, candle]
+answers: What is it, is it for me, what does it cost, how do I get it?
+use_when: [a single product page in a shop]
+seen_in: [Diptyque, Aesop, East Fork, Trudon, Haunt, Lady Moon (see design-reference Part 4.4)]
+---
+
+**The job:** the first screen must show the product, its name, price and the buy action. Everything else supports the decision below.
+
+**Blueprint (1200–1280px, 7/5 split)**
+- **Left (7 cols):** the product image large, on a consistent backdrop (arch or soft frame fits handmade brands), thumbnails or alternate views below. Image area roughly 600×700.
+- **Right (5 cols, sticky buy box):** in this order:
+  1. Collection label (12px, muted, links to the collection)
+  2. Name (display face, 40–48px)
+  3. Rating ★ 4.9 · 241 reviews (link)
+  4. One-sentence story in the brand voice (italic or regular body)
+  5. Price (24–28px) + size/variant facts in muted ("220 g · about 45 hours")
+  6. Stock signal only when true ("Only 3 left in this batch")
+  7. Quantity stepper + primary button with the total ("Add to basket · £28"), full width of the box
+  8. Delivery promise in one line (free over £45, cut-off time)
+  9. Accordions: Scent notes, Details & materials, Care, Delivery & returns
+- **Below:** story or process section ("From the workbench"), then "More from this collection" (3–4 cards).
+- **Phone:** swipeable image, then name/price/button; sticky bottom bar with price + Add to basket after scrolling past the main button.
+
+**Signature options:** lit vs unlit candle toggle; scent notes as a top/heart/base progression; burn time as evenings. Pick one.
+
+**Rules:** use the brand's tokens and type; one accent for the buy button; sold-out keeps the page with a "Notify me" action; price and button never below the first screen at 1440×900.
+
+**Mistakes:** a colour field with the product small in a corner; the name as giant wallpaper pushing price below the fold; stock badges that aren't true; hard-coded oranges outside the palette.

package/kb/patterns/dashboard-entity-table.md

@@ -0,0 +1,37 @@
+---
+id: p.dashboard.entity-table
+kind: pattern
+title: Dense entity table (CRM, admin, records)
+scope: [dashboard, app]
+role: data-table
+tags: [table, list, crm, companies, deals, records, admin, filter, sort, search, pipeline, dense, data grid]
+answers: Find a record, compare many records, decide which one to act on next.
+use_when: [more than ~10 records people scan and compare every day]
+avoid_when: [fewer than ~8 items (use a list), visual items like products (use a grid), mobile-first consumer UI]
+seen_in:
+  - { source: kargulstudio/sales-crm, license: MIT, observed: 2026-10 }
+  - Attio list views
+  - Linear issue lists
+---
+
+**The job:** this is a working surface used all day. Density, scannability and speed beat decoration.
+
+**Blueprint (full width, 24–32px gutters)**
+1. **Header (one line):** title 20px/600 · a live summary in muted text that answers the screen's question ("30 open · £1.39m pipeline · 20 quiet for 14+ days") · primary action on the right ("New company").
+2. **Toolbar (one 36–40px row):** search (with `/` shortcut hint), segmented stage filter with counts, owner select, a "needs attention" toggle, sort. Filters are chips/selects in a row, never a side panel for 3 filters. Saved in the URL.
+3. **Table:** header row 36–38px, 12px/500 muted labels, sticky. Body rows 40–44px, 14px text, `px-3` cells. 1px row dividers one step above the surface; hover = surface at 60%; selected = surface.
+   - First column: name 14/500 + one muted meta line (industry · city) only if rows are 52px+.
+   - Numbers right-aligned, `tabular-nums`, currency symbol muted.
+   - Status as a small dot + label or a compact track, not big coloured pills.
+   - Dates relative ("12 days ago"), turning warning/danger past thresholds that matter for the job.
+   - Tags capped at 2 with "+N".
+   - Owner: 20px avatar + first name.
+4. **Footer:** row count and totals for the filtered set.
+
+**Signature options (pick one):** a stage track per row (5 dots along the deal path), a "days quiet" column that heats from muted to warning to danger, an inline 14px segmented win-probability meter (17 segments, `role="meter"`).
+
+**Phone:** two-line rows (name + value on line one, stage + last contact on line two), filters in a sheet.
+
+**Keyboard:** `/` search, `j/k` or arrows move, Enter opens, Esc clears.
+
+**Mistakes:** coloured pills in every column; centred numbers; zebra stripes plus borders plus hover; KPI cards above a table nobody asked for; 13 columns at 1440 with horizontal scroll.

package/kb/patterns/dashboard-home-today.md

@@ -0,0 +1,24 @@
+---
+id: p.dashboard.home-today
+kind: pattern
+title: Home dashboard that says what to do today
+scope: [dashboard, app]
+role: dashboard-home
+tags: [dashboard, home, overview, kpi, today, tasks, pipeline, metrics, morning, summary]
+answers: Is everything OK, what changed, and what should I do first this morning?
+use_when: [the first screen after login in a work tool]
+avoid_when: [analytics exploration (that needs a report view)]
+seen_in: [Linear Inbox and My issues, Stripe dashboard home, Attio home]
+---
+
+**Blueprint (1200–1320px, 12 columns)**
+1. **Greeting is not a feature.** A 20px title with the date, or nothing.
+2. **Focal block (8 cols): "Needs you"** — overdue tasks, stale deals, approvals, alerts, each a row with the reason and a direct action. If empty: a calm "Nothing needs you" line.
+3. **Side rail (4 cols):** progress against the target (one meter: won £86,500 of £140,000 this month, with days left), one comparison that the data supports (pipeline vs same day last month).
+4. **Below:** one chart that answers a real question (won by month with the partial month marked), recent activity as a compact feed.
+
+**Rules:** at most one row of 3–4 KPIs and only with real comparisons from the data (never invented % changes); each KPI has its period and comparison; charts have labelled axes and the partial period visibly different.
+
+**Signature:** the "Needs you" list with one-click actions.
+
+**Mistakes:** four equal KPI cards with made-up trends; decorative gradient tiles; charts with no axis; a 👋 greeting as the biggest text.

package/kb/patterns/docs-api-reference.md

@@ -0,0 +1,31 @@
+---
+id: p.docs.api-reference
+kind: pattern
+title: API reference
+scope: [docs]
+role: api-reference
+tags: [api, reference, docs, documentation, endpoints, developer, code, curl, parameters, errors]
+answers: How do I call this endpoint, with what parameters, and what comes back?
+use_when: [documenting HTTP endpoints, SDK methods or CLI commands]
+seen_in: [Stripe API reference, Resend docs, Linear API docs, GitHub REST docs]
+---
+
+**The job:** developers arrive from search wanting one endpoint, then keep the page open while they code. Findability and copyability beat everything.
+
+**Blueprint (full width)**
+- **Left nav (240–280px, sticky):** filter input (`/` to focus) · Basics · groups (Flags, Rollouts…) each listing endpoints with a small method badge (GET/POST/PATCH/DELETE in a 11px mono pill, colour-coded subtly) and name · Errors. Active item follows the scroll.
+- **Content column (680–760px):** per endpoint:
+  - H2 name (24px/600) with a hover anchor link.
+  - Request line in mono: `POST /flags/{key}/rollouts` with path params highlighted; base URL in muted; copy button.
+  - One-paragraph description.
+  - Parameter tables grouped Path / Query / Body: name (mono 13px) · type (muted mono) · required badge · description. 
+- **Code column (440–520px, sticky per endpoint):** dark or tinted panel with tabs (curl / JS / Python if available), request on top, response below, copy buttons, 13px mono, line height 20px.
+- **Basics first:** base URL, auth, rate limits, versioning as a compact definition list, not hero copy.
+- **Errors:** table of status · code · meaning.
+- **Narrow screens:** nav becomes a top "Contents" sheet; code moves under each section.
+
+**Signature:** the request line with highlighted path parameters plus a copy-as-curl that already includes the right headers.
+
+**Rules:** URL hash per endpoint; deep link scrolls and briefly highlights; examples are real and runnable; consistent layout for every endpoint (people learn it once).
+
+**Mistakes:** marketing hero on a reference page; emoji headings; code samples without copy; parameters as prose; every endpoint styled differently.

package/kb/patterns/marketing-product-led-landing.md

@@ -0,0 +1,30 @@
+---
+id: p.marketing.product-led-landing
+kind: pattern
+title: Product-led landing page for a SaaS tool
+scope: [marketing]
+role: landing-page
+tags: [landing, homepage, marketing, hero, saas, b2b, product, redesign, sections, pricing, cta]
+answers: What is it, how does it work, can I trust it, what does it cost, how do I start?
+use_when: [a homepage or landing page for a software product]
+avoid_when: [a shop (see p.commerce.product-page), documentation]
+seen_in: [Linear, Attio, Stripe, Cal.com, Resend, ElevenLabs (see design-reference Parts 2–3, 12)]
+---
+
+**The job:** in three seconds say what it is and for whom; in thirty, show it working; then answer trust and price.
+
+**Section order (each answers the visitor's question at that depth)**
+1. **Nav:** wordmark · 3–5 links · "Log in" (ghost) · one primary CTA.
+2. **Hero (split 5/7 or centred-over-product):** H1 that names the category and audience in under 10 words; one muted sentence of specifics; primary + ghost CTA; microcopy ("14-day trial, no card"). The right side or below: **the real product UI built in HTML from real data** (not a screenshot, not illustration), cropped so it reads at a glance. The product window is the hero.
+3. **How it works:** 3 steps or the core loop, each with a small product fragment.
+4. **Feature depth:** 2–3 alternating split sections, each one idea, each with a working UI fragment.
+5. **Proof:** only real proof. No customers yet? Show honest product facts (sources, approval rules, cost per run) and the deliverable; never fake logos or numbers.
+6. **Pricing:** plans with a monthly/annual toggle, "everything in X, plus", FAQ below.
+7. **Final CTA:** one line + one button.
+8. **Footer:** columns of links, small print.
+
+**Rules:** one CTA label everywhere; light base with at most one dark band for the "technical" moment; serif or sans by brand; section padding 96–128px; every section's heading readable alone.
+
+**Signature:** an interactive product moment in the hero (approve a change, play a sample, tick a task).
+
+**Mistakes:** centred gradient headline with three CTAs and floating blobs; six identical icon cards with buzzword copy; invented stats; the product never shown.

package/kb/patterns/mobile-daily-checklist.md

@@ -0,0 +1,26 @@
+---
+id: p.mobile.daily-checklist
+kind: pattern
+title: Daily checklist on a phone (habits, routines, tasks today)
+scope: [mobile, app]
+role: daily-checklist
+tags: [mobile, phone, habits, today, checklist, streak, tick, check off, routine, tasks, progress]
+answers: What's left today, and let me tick it off in one tap.
+use_when: [a phone screen opened several times a day to complete items]
+seen_in: [Things 3 Today, Streaks, Apple Reminders, Habitify]
+---
+
+**The job:** open, tick, close in under five seconds. The list is the screen; everything else is small.
+
+**Blueprint (390px)**
+1. **Top (compact, 88–120px):** date in muted 14px, then the progress as the focal point: "2 of 6" at 32–40px with a thin segmented bar (one segment per item) or a small ring. No big coloured header block.
+2. **List grouped by time of day** (Morning / Afternoon / Evening / Anytime) with the current part of the day first or marked "now"; completed groups collapse or sink.
+3. **Rows 64–72px, the whole row is the tap target:** name 16px/500, target in 13px muted ("20 pages"), a 7-day strip (7 small squares, today outlined), streak count with a small flame or number, and a 32–36px check circle on the right in thumb reach.
+4. **Checking off:** the circle fills and the check draws in (200ms), a light haptic where supported, the streak and progress update immediately, the row stays in place (no reflow under the thumb). Undo by tapping again.
+5. **Bottom:** this week's summary in one line; tab bar if the app has one.
+
+**Rules:** inputs and body at 16px minimum; tap targets 44px+; one accent (the done colour); dark mode; reduced motion keeps fades only; content readable at 320px wide.
+
+**Signature options:** the 7-day strip per row; a stamp-style check; the segmented day bar. Pick one and make it excellent.
+
+**Mistakes:** a full-width purple header taking a third of the screen; small checkboxes; rows that jump when ticked; streaks shown with fire emoji everywhere.