paneltir 0.12.1 → 0.13.0

package/dist/index.d.ts

@@ -451,792 +451,825 @@ interface DropTarget {
  */
 declare function dropIndex(source: DropTarget, target: DropTarget): number | null;
 
-interface DetailSheetProps {
-    open: boolean;
-    onClose: () => void;
-    children: React.ReactNode;
-    ariaLabel?: string;
-}
 /**
- * Below 760px this is a sheet rising from the bottom; from 760px up the same
- * markup becomes a centred floating dialog. The breakpoint is handled in CSS,
- * so there are not two different components.
+ * A board is read in one language and written in another.
+ *
+ * This is the mechanism only — the types and the resolution. The panel's own
+ * wording lives with the panel: a library that shipped its copy would be a
+ * library deciding what a project's board says.
  */
-declare function DetailSheet({ open, onClose, children, ariaLabel }: DetailSheetProps): React.JSX.Element | null;
-interface DetailSectionProps {
-    title: string;
-    /** Clarifying phrase in lowercase, printed after an em dash. */
-    subtitle?: string;
-    children: React.ReactNode;
-}
-declare function DetailSection({ title, subtitle, children }: DetailSectionProps): React.JSX.Element;
-
+type Lang = 'en' | 'es';
+declare const LANGS: Lang[];
+declare const LANG_LABELS: Record<Lang, string>;
 /**
- * Whether a note has been dismissed, and how to dismiss it.
+ * A string, or the same string per language.
  *
- * Starts as "shown but not yet decided" so the first paint matches the server
- * and nothing flashes into place; the stored answer arrives on the first
- * effect.
+ * A plain string is a claim: this text is right in either language — true for
+ * a product name, a number, a file id, and almost never for prose. An object
+ * is the honest shape for a sentence, and one that carries a single language
+ * says "written, not translated yet", which is exactly what the next session
+ * needs to know.
  */
-declare function useGuideNote(id: string, remember?: boolean): {
-    visible: boolean;
-    dismiss: () => void;
-};
-/** Clears every dismissal, so the guidance can be asked for again. */
-declare function resetGuide(): void;
-interface GuideNoteProps {
-    /** Stable across releases: changing it makes the note reappear for everyone. */
+type Text = string | Partial<Record<Lang, string>>;
+declare function text(value: Text | undefined, lang: Lang): string;
+/** True when a sentence exists in one language only. */
+declare function untranslated(value: Text | undefined): boolean;
+/**
+ * Writing replaces the language being typed and drops the other copy of that
+ * field. Deliberate: a translation of a sentence somebody just rewrote is a
+ * lie about what the card says, and the gap is the panel telling the next
+ * session what to fill in.
+ */
+declare function writeText(lang: Lang, value: string): Text;
+
+type Weight = 'primary' | 'secondary' | 'off';
+type Severity = 'high' | 'medium' | 'low';
+type SuggestionStatus = 'new' | 'doing' | 'done' | 'dismissed';
+interface Goal {
     id: string;
-    title: React.ReactNode;
-    children: React.ReactNode;
-    /** Wording of the dismiss button. Say what it does, not "OK". */
-    dismissLabel?: string;
-    /** Shown after the note, for the one thing it wants the reader to do. */
-    action?: {
-        label: string;
-        onClick: () => void;
-    };
-    /** Position in a sequence, so a first session reads as a tour, not a pile. */
-    step?: {
-        index: number;
-        total: number;
-    };
-    /** Told after the note is dismissed, so a sequence can move on. */
-    onDismissed?: () => void;
-    /**
-     * Whether to record the dismissal in localStorage. False when the caller
-     * keeps that answer itself, so the two cannot disagree.
-     */
-    remember?: boolean;
+    label: Text;
+    weight: Weight;
 }
-declare function GuideNote({ id, title, children, dismissLabel, action, step, onDismissed, remember, }: GuideNoteProps): React.JSX.Element | null;
-interface GuideTourProps {
-    /** Notes in order. Only the first undismissed one shows, so it reads as a tour. */
-    notes: Array<Omit<GuideNoteProps, 'step' | 'onDismissed'>>;
-    /**
-     * Which notes are already dismissed, when the caller keeps that somewhere
-     * durable. Leave it out and each reader's browser remembers, which is the
-     * right home for a fact about one browser — and the wrong one for a panel
-     * with a single owner, who would be told the same tour again on a new
-     * machine. Passing it does not switch the browser off: a note dismissed
-     * here is written to both, because a caller whose store needs saving would
-     * otherwise lose the dismissal on reload.
-     */
-    dismissed?: string[];
-    /** Told when a note is dismissed. Required for `dismissed` to mean anything. */
-    onDismiss?: (id: string) => void;
+interface Constraint {
+    id: string;
+    label: Text;
+    on: boolean;
+}
+interface Reading {
+    date: string;
+    value: number;
+    note?: Text;
+}
+interface Metric {
+    id: string;
+    label: Text;
+    unit: string;
+    /** Which direction counts as better. A reading against it is what "drifting" means. */
+    goal: 'up' | 'down';
+    readings: Reading[];
+}
+interface Strategy {
+    id: string;
+    title: Text;
+    thesis: Text;
+    horizon: Text;
+    /** 0–10, so three bars can be compared at a glance rather than read. */
+    effort: number;
+    risk: number;
+    upside: number;
+    moves: Text[];
+}
+interface Suggestion {
+    id: string;
+    area: string;
+    severity: Severity;
+    status: SuggestionStatus;
+    date: string;
+    text: Text;
 }
 /**
- * One note at a time, in order.
+ * A question the owner answers and Claude reads.
  *
- * Five notes at once is a wall nobody reads. Shown one at a time, dismissing
- * each reveals the next, and a reader who dismisses all of them has been
- * through the tour rather than having closed a box.
+ * This is the whole point of the analysis view. A board says what to do; a
+ * choice says how the project wants it done, in the owner's words, once —
+ * instead of being asked again on every card. Claude reads these before
+ * deciding anything, so answering one here is worth more than answering it
+ * in a message that scrolls away.
+ *
+ * `value` of null is not missing data. It means nobody has decided, which is
+ * information: Claude must not guess an answer to a question the owner has
+ * deliberately left open.
  */
-declare function GuideTour({ notes, dismissed, onDismiss }: GuideTourProps): React.JSX.Element | null;
-
-type NotificationTone = 'info' | 'attention';
-interface PanelNotification {
-    /**
-     * Stable for the life of the event. Two different events must never share
-     * one, or marking the first seen silences the second; the same event must
-     * never change it, or it comes back every time the page loads.
-     */
+interface Choice {
     id: string;
-    title: React.ReactNode;
-    detail?: React.ReactNode;
-    /** Shown as given, so the caller decides the format its readers expect. */
-    at?: string;
-    /** `attention` for something waiting on the reader, `info` for the rest. */
-    tone?: NotificationTone;
-    /** Where this leads. Called before the notification is marked seen. */
-    onOpen?: () => void;
+    question: Text;
+    /** What actually changes depending on the answer. Never "choose an option". */
+    why?: Text;
+    options: ChoiceOption[];
+    value: string | null;
+    decidedAt?: string;
+    decidedBy?: string;
 }
-interface NotificationLabels {
-    /** Names the control for a screen reader and on hover. */
-    title: string;
-    empty: string;
-    markAll: string;
-    /** Given the count, e.g. (n) => `${n} unread`. */
-    unread: (count: number) => string;
+interface ChoiceOption {
+    id: string;
+    label: Text;
+    /** What picking this commits the project to. */
+    detail?: Text;
 }
-interface NotificationBellProps {
-    notifications: PanelNotification[];
-    labels?: Partial<NotificationLabels>;
-    /**
-     * What this reader has already seen, when the caller keeps it somewhere
-     * durable. Leave it out and the bell remembers in localStorage, which is the
-     * right home for a fact about one browser.
-     *
-     * A panel with one password has one owner, and there "this reader" and "this
-     * project" are the same person — so a panel that saves its board can keep
-     * this in it and have it survive a new browser. That is the caller's call to
-     * make, not the component's, which is why both work.
-     */
-    seen?: string[];
+/** Who the work is for, and against what. */
+interface Market {
+    audience: Text;
+    positioning: Text;
+    competitors: Competitor[];
+    pricing?: Text;
+    notes?: Text[];
+}
+interface Competitor {
+    id: string;
+    name: string;
+    /** What they do better. Written honestly or it is worthless. */
+    strength: Text;
+    /** Where they leave room. */
+    gap: Text;
+}
+/** The four things the analysis is about, each its own screen. */
+type AnalysisSection = 'board' | 'project' | 'strategy' | 'market';
+declare const ANALYSIS_SECTIONS: AnalysisSection[];
+interface Analysis {
+    brief: Text;
+    stage: string;
+    goals: Goal[];
+    constraints: Constraint[];
+    metrics: Metric[];
+    strategies: Strategy[];
+    /** The path the owner picked. Null is a decision waiting, and it is theirs. */
+    chosen: string | null;
+    suggestions: Suggestion[];
+    /** Who this is for and against what. Optional: not every board is a product. */
+    market?: Market;
     /**
-     * Told which ids were just seen. Required for `seen` to mean anything —
-     * though the bell also remembers in localStorage either way, so a caller
-     * that has not saved yet does not show the same notifications again.
+     * Standing answers, grouped by the screen they belong to. Claude reads them
+     * before deciding anything the board does not already settle.
      */
-    onSeen?: (ids: string[]) => void;
+    choices?: Partial<Record<AnalysisSection, Choice[]>>;
 }
-declare function NotificationBell({ notifications, labels, seen: given, onSeen }: NotificationBellProps): React.JSX.Element | null;
+/** Everything the owner has actually decided, newest first. */
+declare function decided(analysis: Analysis): {
+    section: AnalysisSection;
+    choice: Choice;
+    option: ChoiceOption;
+}[];
+/** Questions still open. A count of these is the honest state of the analysis. */
+declare function undecided(analysis: Analysis): {
+    section: AnalysisSection;
+    choice: Choice;
+}[];
+/**
+ * What the board itself says, counted rather than declared.
+ *
+ * These are not stored: a number typed into the analysis is a number that
+ * disagrees with the board the moment a card moves. They are derived on every
+ * render from the cards, so they cannot be wrong.
+ */
+interface BoardFacts {
+    total: number;
+    open: number;
+    byColumn: {
+        id: string;
+        title: Text;
+        count: number;
+    }[];
+    waitingOnOwner: number;
+    orders: number;
+    highRisk: number;
+    /** Cards claiming to be finished that were never picked up. */
+    claimed: Pick<Card, 'id' | 'title'>[];
+    /** Age of the oldest card still open. Null when nothing is open. */
+    oldestOpenDays: number | null;
+    oldestOpen: Pick<Card, 'id' | 'title'> | null;
+}
+/**
+ * Counts the board rather than believing a number somebody typed.
+ *
+ * `today` is passed in so the same cards always produce the same answer — a
+ * function that reads the clock cannot be checked.
+ */
+declare function boardFacts(cards: Card[], columns: ColumnDef[], today: string): BoardFacts;
+interface Trend {
+    latest: Reading | undefined;
+    previous: Reading | undefined;
+    delta: number | null;
+    /** True when the last move went against the metric's declared direction. */
+    against: boolean;
+}
+declare function trendOf(metric: Metric): Trend;
+/**
+ * Points for a sparkline in a 0–1 box, so the caller only decides the size.
+ * A flat series sits on the middle line rather than collapsing to the floor.
+ */
+declare function sparkPoints(readings: Reading[]): {
+    x: number;
+    y: number;
+}[];
 
+type Level = 'high' | 'medium' | 'low';
+type Owner = 'claude' | 'you';
 /**
- * A block of text whose whole purpose is to end up somewhere else.
+ * What the owner wants done with a card next, in one tap.
  *
- * Anything a panel tells someone to paste — a settings fragment, two commands,
- * a shell line — is read once and copied. So the copy is the primary action
- * and the text is selectable underneath it, rather than the other way round.
+ * Free text would be clearer to write and useless to obey: "solve it if you
+ * can" and "solve it yourself" are the same sentence and different
+ * instructions. A fixed set gives each one an exact, documented meaning, so a
+ * tap is a contract rather than a hint. Absent is a real state: no
+ * instruction, use judgement.
  *
- * The clipboard API is not always there. It needs a secure context and can be
- * refused outright, and a copy button that silently does nothing is worse than
- * no button at all: the reader walks away believing they have the text. So the
- * failure falls back to selecting the block, and says which of the two
- * happened.
+ * Three of them — explain, askme, hold — are refusals to act. Honouring them
+ * exactly matters more than the work: they are the only way to say "not yet".
  */
-interface CopyBlockProps {
-    /** Exactly what lands on the clipboard. Shown verbatim. */
-    text: string;
-    /** What this block is, above it. */
-    label?: React.ReactNode;
-    /** Why the reader wants it, and anything they must know before pasting. */
-    note?: React.ReactNode;
-    /** Wording, so the kit stays language-agnostic. */
-    labels?: Partial<CopyBlockLabels>;
+declare const INTENTS: readonly ["decide", "explain", "solve", "do", "cheap", "safe", "fast", "askme", "hold"];
+type Intent = (typeof INTENTS)[number];
+interface IntentCopy {
+    label: Record<Lang, string>;
+    meaning: Record<Lang, string>;
+}
+declare const INTENT_COPY: Record<Intent, IntentCopy>;
+interface Check {
+    id: string;
+    text: Text;
+    done: boolean;
+}
+interface Note {
+    id: string;
+    by: Owner;
+    date: string;
+    text: Text;
+}
+interface Card {
+    id: string;
+    column: string;
+    title: Text;
+    body: Text;
+    area: string;
+    priority: Level;
+    risk: Level;
+    owner: Owner;
+    /** The one flag that means "I am asking you to do this". */
+    order: boolean;
+    intent: Intent | null;
+    checks: Check[];
+    notes: Note[];
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Stamped by the board when the card enters the working column, and when it
+     * reaches a done column. They are written by the move, never typed, so a
+     * card that carries `completedAt` with no `startedAt` is one that was
+     * declared finished without ever being picked up — which is exactly the
+     * thing worth being able to see.
+     */
+    startedAt?: string | null;
+    completedAt?: string | null;
 }
-interface CopyBlockLabels {
-    copy: string;
-    copied: string;
-    /** Used when the clipboard refused and the text was selected instead. */
-    selected: string;
+interface ColumnDef {
+    id: string;
+    title: Text;
+    /** What the column means, shown on hover. Two words cannot say whether a
+        card sitting here is waiting on you or on Claude. */
+    hint?: Text;
+    /** Work in flight: entering this column stamps the card as started. */
+    active?: boolean;
+    /** Cards here are finished: they leave the open counts alone. */
+    done?: boolean;
 }
-declare function CopyBlock({ text, label, note, labels }: CopyBlockProps): React.JSX.Element;
-
 /**
- * What the panel needs in order to work, and what to do about what is missing.
- *
- * A panel with no token does not look broken — it looks fine until the moment
- * someone presses Save, and then it fails with something the person reading it
- * did not cause and cannot place. This turns that into a list they can read
- * before it happens, and act on without leaving the panel.
- *
- * The status comes from the server, which is the only place that can see the
- * environment. It reports *whether* a variable is set and never its value, so
- * this component has nothing worth leaking.
+ * One pass over the board: what a session changed, and which cards it
+ * touched. Written at the end of a run, so the panel keeps the account
+ * rather than the account living in a chat nobody can re-read.
  */
-type SetupStatus = 'ok' | 'missing' | 'unknown';
-interface SetupRequirement {
+interface Run {
     id: string;
-    /** What it is, in the reader's terms rather than the variable's. */
-    label: React.ReactNode;
-    status: SetupStatus;
-    /** The environment variable behind it, when there is one to name. */
-    variable?: string;
-    /** What it lets the panel do — so a missing one has a visible cost. */
-    enables?: React.ReactNode;
-    /** Exactly what to do, shown only when it is missing. */
-    fix?: React.ReactNode;
-    /**
-     * Information rather than a gate: drawn in the list, never walked as a step.
-     *
-     * Every other requirement here is an environment variable, and the
-     * walkthrough's one action — re-read the environment from the server —
-     * is what clears it. A requirement that action cannot clear parks the
-     * walkthrough on it for ever, and because `unknown` is judged across the
-     * whole list, one advisory row that nobody wired made every step answer a
-     * successful check with "the panel could not ask its own server". That is
-     * what the copied gate did the day it was added.
-     */
-    advisory?: boolean;
+    date: string;
+    by: Owner;
+    summary: Text;
+    /** Card ids this run touched, so a claim can be checked against the board. */
+    cards: string[];
+    /** The kit fingerprint at the time, twelve characters is enough to compare. */
+    fingerprint?: string;
 }
-interface SetupGuideProps {
-    requirements: SetupRequirement[];
-    /** Shown when everything is in place, instead of an empty list. */
-    readyMessage?: React.ReactNode;
-    /** Wording, so the kit stays language-agnostic. */
-    labels?: Partial<{
-        ok: string;
-        missing: string;
-        unknown: string;
-        whatToDo: string;
-    }>;
+interface HealthFact {
+    label: Text;
+    value: Text;
+    status: 'ok' | 'warning' | 'bad' | 'unknown';
 }
-declare function SetupGuide({ requirements, readyMessage, labels }: SetupGuideProps): React.JSX.Element;
-
 /**
- * The setup, walked one step at a time.
- *
- * `SetupGuide` is the list: the right shape for somebody auditing a panel that
- * already works. This is the other reader — the one who installed it twenty
- * minutes ago, has four things missing and no idea which to do first. A wall
- * of four is not four times as useful as one; it is the thing people close.
+ * A theme Claude derived from the project it is installed in.
  *
- * Two rules hold it honest. It **checks rather than asks**: every step ends in
- * a button that re-reads the environment from the server, so the reader is
- * told whether it worked instead of ticking a box themselves. And it **never
- * claims what it cannot see**: a panel that could not reach its own endpoint
- * says the check failed, never that a variable is missing, because telling
- * somebody to add a token they already added is the worse of the two wrong
- * answers.
+ * Stored with where it came from, not only with its colours. "Update the
+ * theme" is only a meaningful request if the next answer can be compared with
+ * this one — otherwise a regenerated theme is a different theme for reasons
+ * nobody can see. `from` is what makes the difference readable.
  *
- * There is no copy of the values here and nothing is written: the panel cannot
- * set an environment variable, and a button that appeared to would be the same
- * fault as one that appeared to install an update.
+ * `refreshRequested` is a message, not a trigger: a panel cannot run Claude.
+ * Tapping Update writes the date here, the bell shows it, and the next session
+ * regenerates. Pretending the button does the work itself would leave the
+ * owner waiting for something that was never going to happen.
  */
-interface SetupWizardLabels {
-    title: string;
-    /** `(index, total)` — "Step 2 of 5". */
-    progress: (index: number, total: number) => string;
-    /** Shown above the one step in hand. */
-    nowDo: string;
-    /** The button that re-reads the environment. */
-    check: string;
-    checking: string;
-    /** Said when a check ran and the step is still not in place. */
-    stillMissing: string;
-    /** Said when the panel could not ask its own server. */
-    cannotTell: string;
-    /** The heading over the finished steps. */
-    doneTitle: string;
-    /** Shown in place of a step when every requirement is in place. */
-    readyTitle: string;
-    readyBody: string;
-    /** The two things to try before trusting the gate, as list items. */
-    verify: string[];
-    /** Closes the wizard. */
-    close: string;
-    /** The escape hatch: heading, explanation, and the prompt to copy. */
-    stuckTitle: string;
-    stuckBody: string;
-    stuckPrompt: string;
-    copy: string;
-    copied: string;
-}
-interface SetupWizardProps {
-    /** In the order they are to be done. The caller owns that order. */
-    requirements: SetupRequirement[];
-    labels: SetupWizardLabels;
-    /** Re-reads the environment. Resolves when the answer has been applied. */
-    onCheck: () => Promise<void> | void;
-    /** Told when the reader closes it. */
-    onClose?: () => void;
+interface ImportedTheme {
+    /** What to call it in the theme list. */
+    label: Text;
+    tokens: Record<string, string>;
+    form?: Record<string, string | number>;
+    from: {
+        /** Files the colours were read out of, so the claim can be checked. */
+        files: string[];
+        /** The colours actually found, before they were mapped to tokens. */
+        colours: string[];
+        /** Why these tokens and not others. One or two sentences. */
+        reasoning: Text;
+    };
+    importedAt: string;
+    importedBy: 'claude';
+    /** Set by the panel when the owner asks for it to be derived again. */
+    refreshRequested?: string | null;
 }
-declare function SetupWizard({ requirements, labels, onCheck, onClose }: SetupWizardProps): React.JSX.Element;
-
 /**
- * Where a reader is in the setup, as one answer instead of a list to read.
+ * What the owner has chosen, kept in the board so it survives a new browser.
  *
- * `SetupGuide` draws every requirement at once, which is the right shape for
- * somebody checking a panel that already works. It is the wrong shape for
- * somebody who has just installed one: five things at once, four of them
- * missing, and no order to do them in reads as a wall rather than as a first
- * step. So the same requirements are walked one at a time, and this is the
- * function that decides which one.
+ * The kit's default is to remember these per browser, in localStorage, because
+ * for a component "which notes this reader dismissed" is a fact about a reader
+ * and not about a project. A panel with one password is the case where those
+ * two are the same person: keeping it here means the theme, the language and
+ * what has already been read follow the owner to a new machine instead of
+ * greeting them with a tour they finished months ago.
  *
- * The order the caller gives is the order they are done in — a token that
- * cannot be scoped before the repository is named is a step in the wrong
- * place, and that is the caller's knowledge, not this function's.
+ * The cost is real and worth naming: anyone who shares the password shares
+ * this. It holds a theme name and a list of ids — nothing worth stealing, and
+ * nothing anyone else would want.
  */
-interface WizardStep {
-    /** The requirement to show, or null when nothing is left to do. */
-    current: SetupRequirement | null;
-    /** 1-based, for "step 2 of 5". Zero when there is nothing left. */
-    index: number;
-    /** How many steps this setup has in total. */
-    total: number;
-    /** Every requirement that is in place, in the caller's order. */
-    done: SetupRequirement[];
-    /** True when every requirement is `ok`. */
-    ready: boolean;
+interface Preferences {
+    theme?: string;
+    lang?: Lang;
+    /** Ids of notifications already read. Bounded when saved. */
+    seen?: string[];
+    /** Ids of guide notes already dismissed. */
+    guideDismissed?: string[];
     /**
-     * True when the panel could not ask the server, so nothing is claimed.
+     * Whether an update card is written as an order rather than a suggestion.
      *
-     * This is not "not ready": a panel that cannot reach its own endpoint knows
-     * nothing about the environment, and telling somebody to add a token they
-     * already added is worse than saying the check itself failed.
+     * It does not make anything automatic — the panel cannot run npm, and this
+     * changes `order` on the card it offers to write, nothing else. Off means
+     * the card asks; on means it tells.
      */
-    unknown: boolean;
+    updateAsOrder?: boolean;
 }
-declare function wizardStep(requirements: SetupRequirement[]): WizardStep;
+interface PanelState {
+    v: 2;
+    project: string;
+    environment: Text;
+    updatedAt: string;
+    notice?: Text;
+    columns: ColumnDef[];
+    areas: {
+        id: string;
+        label: Text;
+    }[];
+    health: HealthFact[];
+    cards: Card[];
+    /** Newest first. Capped when saving, so the file cannot grow without end. */
+    runs: Run[];
+    /** What any of the work is for: goals, constraints, metrics, strategies. */
+    analysis?: Analysis;
+    /** The owner's choices, so they survive a new browser. */
+    preferences?: Preferences;
+    /** A theme Claude derived from this project, with where it came from. */
+    importedTheme?: ImportedTheme;
+}
+declare const LEVELS: Level[];
+declare const OWNERS: Owner[];
+declare function newId(): string;
+declare function today(): string;
+/** A card is created empty and named second — the same as tapping "+" on paper. */
+declare function emptyCard(column: string, area: string): Card;
+/**
+ * How long a finished card stays on the board before it becomes history.
+ *
+ * A done column only grows. It is the one column nothing ever removes from,
+ * so a board that is being worked turns into a wall of things already
+ * finished, and the three columns that need reading get a third of the screen
+ * between them. A week is the window in which "what did we ship" is still a
+ * live question; after that it is a record, and a record does not need to be
+ * in the way.
+ */
+declare const ARCHIVE_AFTER_DAYS = 7;
 /**
- * Whether this panel has never been worked, which is what "first install"
- * means here.
+ * Whether a finished card has been finished long enough to stop being drawn.
  *
- * `paneltir init` writes a board with the columns already there and nothing
- * on them, so a board carrying no cards and no runs is one nobody has used
- * yet. That is a better signal than a version on disk: a project can install
- * the package, never open the panel, and update three times before anyone
- * sees it — and it is still that reader's first run.
+ * Derived on every render and never written, which is the arrangement
+ * `boardFacts()` already uses: a flag stored on the card would be wrong the
+ * day after it was set, and setting it would mark the panel dirty for the
+ * passage of time. Here the answer simply becomes true on its own.
  *
- * A panel that has been worked and then loses a variable is deliberately not
- * this. It needs the same instructions and gets them from the same wizard,
- * but it is told rather than taken over: somebody mid-sentence on a board
- * they know does not want a walkthrough opening on top of it.
+ * **A card with no `completedAt` is never archived**, whatever column it sits
+ * in. It reached done without being stamped — a board edited by hand, or one
+ * from before the stamp existed — so its age is not known, and hiding a card
+ * whose age nobody knows is the same mistake as reporting a token missing
+ * because the check could not run. `unknown` is not `old`.
  */
-declare function isFirstRun(board: {
-    cards?: unknown[];
-    runs?: unknown[];
-}): boolean;
-
-type Handler = (payload: Record<string, string>, event: MouseEvent) => void;
+declare function isArchived(card: Card, doneColumns: ReadonlySet<string>, now?: string, afterDays?: number): boolean;
 /**
- * A single click listener on document that dispatches by data-* attributes,
- * instead of one handler per element. Meant for a project's own actions; the
- * Board does not use it internally.
- *
- * Example: useDelegatedClick('data-action', (payload) => { if (payload.action === 'delete') ... })
- * with buttons such as <button data-action="delete" data-id="42">
+ * Applies the column's own meaning to a card that just moved into it: a card
+ * entering the working column is started, one reaching a done column is
+ * finished, and one dragged back out of done is not finished any more.
  */
-declare function useDelegatedClick(attribute: string, handler: Handler): void;
-
-declare function useMediaQuery(query: string): boolean;
-
+declare function stampForColumn(card: Card, columns: ColumnDef[]): Card;
 /**
- * A board is read in one language and written in another.
+ * Where a card the panel writes on the reader's behalf goes.
  *
- * This is the mechanism only — the types and the resolution. The panel's own
- * wording lives with the panel: a library that shipped its copy would be a
- * library deciding what a project's board says.
+ * The update card and the four "ask for this again" cards used to be born in
+ * a column literally called `next`. The default board has one; a board whose
+ * owner renamed it does not, and a card in a column that does not exist is
+ * the exact fault `validateBoard` names — drawn nowhere, and refused by the
+ * write path, so one tap on a button turned a saveable board into one that
+ * could not be saved and said so about a column the reader had never heard of.
+ *
+ * `next` when there is one, because that is what the button means. Otherwise
+ * the first column that is neither in flight nor finished nor the owner's:
+ * queued work goes where queued work already sits. And the first column of
+ * all when nothing else fits, since a board with no columns cannot pass the
+ * validator either way.
  */
-type Lang = 'en' | 'es';
-declare const LANGS: Lang[];
-declare const LANG_LABELS: Record<Lang, string>;
+declare function queueColumn(columns: ColumnDef[]): string;
+/** A card claiming to be finished that was never picked up. */
+declare function claimedWithoutStarting(card: Card): boolean;
+interface Counts {
+    open: number;
+    orders: number;
+    yours: number;
+    decisions: number;
+    highRisk: number;
+    done: number;
+}
+declare function countCards(state: PanelState): Counts;
+/** How many checklist steps are ticked, for the counter on a card. */
+declare function checkProgress(card: Card): {
+    done: number;
+    total: number;
+} | undefined;
+
 /**
- * A string, or the same string per language.
- *
- * A plain string is a claim: this text is right in either language — true for
- * a product name, a number, a file id, and almost never for prose. An object
- * is the honest shape for a sentence, and one that carries a single language
- * says "written, not translated yet", which is exactly what the next session
- * needs to know.
+ * Cards the panel writes when the owner asks for something it cannot do.
+ *
+ * The panel runs nothing. It cannot bump a version, install a plugin or
+ * produce a market report, and a button that appeared to would be the fault
+ * this project keeps refusing. What it can do is write the request down where
+ * work reaches Claude — an order card on the board — and open it, so the tap
+ * is visibly a request and the next session carries it out.
+ *
+ * Two rules live here rather than in the component, because they are the part
+ * with decisions in it and a component cannot be tested in this repository:
+ *
+ * - **One open request per subject.** A second tap while the first is still
+ *   waiting opens the card already asked for. Two version bumps queued at
+ *   once is a project two versions ahead of where anybody meant, and two
+ *   install cards for one tool is the same edit made twice.
+ * - **A finished request does not block a new one.** Once the card reaches a
+ *   done column the subject is free again: next week's bump is a new card.
  */
-type Text = string | Partial<Record<Lang, string>>;
-declare function text(value: Text | undefined, lang: Lang): string;
-/** True when a sentence exists in one language only. */
-declare function untranslated(value: Text | undefined): boolean;
+
+/** The kinds of request the panel writes. */
+type RequestKind = 'version-bump' | 'install';
+/** `version-bump-2026-09-26`, `install-deploybudget-2026-09-26`. */
+declare function requestId(kind: RequestKind, day: string, subject?: string): string;
 /**
- * Writing replaces the language being typed and drops the other copy of that
- * field. Deliberate: a translation of a sentence somebody just rewrote is a
- * lie about what the card says, and the gap is the panel telling the next
- * session what to fill in.
+ * The request of this kind, for this subject, still waiting on the board.
+ *
+ * "Waiting" is anything outside a done column — queued, in flight, or parked
+ * in the owner's column with a question on it. Only finishing it frees the
+ * subject for a new request.
  */
-declare function writeText(lang: Lang, value: string): Text;
+declare function pendingRequest(cards: Card[], kind: RequestKind, doneColumns: ReadonlySet<string>, subject?: string): Card | undefined;
 
-type Weight = 'primary' | 'secondary' | 'off';
-type Severity = 'high' | 'medium' | 'low';
-type SuggestionStatus = 'new' | 'doing' | 'done' | 'dismissed';
-interface Goal {
-    id: string;
-    label: Text;
-    weight: Weight;
-}
-interface Constraint {
-    id: string;
-    label: Text;
-    on: boolean;
-}
-interface Reading {
-    date: string;
-    value: number;
-    note?: Text;
-}
-interface Metric {
-    id: string;
-    label: Text;
-    unit: string;
-    /** Which direction counts as better. A reading against it is what "drifting" means. */
-    goal: 'up' | 'down';
-    readings: Reading[];
-}
-interface Strategy {
-    id: string;
-    title: Text;
-    thesis: Text;
-    horizon: Text;
-    /** 0–10, so three bars can be compared at a glance rather than read. */
-    effort: number;
-    risk: number;
-    upside: number;
-    moves: Text[];
+interface DetailSheetProps {
+    open: boolean;
+    onClose: () => void;
+    children: React.ReactNode;
+    ariaLabel?: string;
 }
-interface Suggestion {
-    id: string;
-    area: string;
-    severity: Severity;
-    status: SuggestionStatus;
-    date: string;
-    text: Text;
+/**
+ * Below 760px this is a sheet rising from the bottom; from 760px up the same
+ * markup becomes a centred floating dialog. The breakpoint is handled in CSS,
+ * so there are not two different components.
+ */
+declare function DetailSheet({ open, onClose, children, ariaLabel }: DetailSheetProps): React.JSX.Element | null;
+interface DetailSectionProps {
+    title: string;
+    /** Clarifying phrase in lowercase, printed after an em dash. */
+    subtitle?: string;
+    children: React.ReactNode;
 }
+declare function DetailSection({ title, subtitle, children }: DetailSectionProps): React.JSX.Element;
+
 /**
- * A question the owner answers and Claude reads.
- *
- * This is the whole point of the analysis view. A board says what to do; a
- * choice says how the project wants it done, in the owner's words, once —
- * instead of being asked again on every card. Claude reads these before
- * deciding anything, so answering one here is worth more than answering it
- * in a message that scrolls away.
+ * Whether a note has been dismissed, and how to dismiss it.
  *
- * `value` of null is not missing data. It means nobody has decided, which is
- * information: Claude must not guess an answer to a question the owner has
- * deliberately left open.
+ * Starts as "shown but not yet decided" so the first paint matches the server
+ * and nothing flashes into place; the stored answer arrives on the first
+ * effect.
  */
-interface Choice {
-    id: string;
-    question: Text;
-    /** What actually changes depending on the answer. Never "choose an option". */
-    why?: Text;
-    options: ChoiceOption[];
-    value: string | null;
-    decidedAt?: string;
-    decidedBy?: string;
-}
-interface ChoiceOption {
-    id: string;
-    label: Text;
-    /** What picking this commits the project to. */
-    detail?: Text;
-}
-/** Who the work is for, and against what. */
-interface Market {
-    audience: Text;
-    positioning: Text;
-    competitors: Competitor[];
-    pricing?: Text;
-    notes?: Text[];
-}
-interface Competitor {
+declare function useGuideNote(id: string, remember?: boolean): {
+    visible: boolean;
+    dismiss: () => void;
+};
+/** Clears every dismissal, so the guidance can be asked for again. */
+declare function resetGuide(): void;
+interface GuideNoteProps {
+    /** Stable across releases: changing it makes the note reappear for everyone. */
     id: string;
-    name: string;
-    /** What they do better. Written honestly or it is worthless. */
-    strength: Text;
-    /** Where they leave room. */
-    gap: Text;
-}
-/** The four things the analysis is about, each its own screen. */
-type AnalysisSection = 'board' | 'project' | 'strategy' | 'market';
-declare const ANALYSIS_SECTIONS: AnalysisSection[];
-interface Analysis {
-    brief: Text;
-    stage: string;
-    goals: Goal[];
-    constraints: Constraint[];
-    metrics: Metric[];
-    strategies: Strategy[];
-    /** The path the owner picked. Null is a decision waiting, and it is theirs. */
-    chosen: string | null;
-    suggestions: Suggestion[];
-    /** Who this is for and against what. Optional: not every board is a product. */
-    market?: Market;
+    title: React.ReactNode;
+    children: React.ReactNode;
+    /** Wording of the dismiss button. Say what it does, not "OK". */
+    dismissLabel?: string;
+    /** Shown after the note, for the one thing it wants the reader to do. */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    /** Position in a sequence, so a first session reads as a tour, not a pile. */
+    step?: {
+        index: number;
+        total: number;
+    };
+    /** Told after the note is dismissed, so a sequence can move on. */
+    onDismissed?: () => void;
+    /**
+     * Whether to record the dismissal in localStorage. False when the caller
+     * keeps that answer itself, so the two cannot disagree.
+     */
+    remember?: boolean;
+}
+declare function GuideNote({ id, title, children, dismissLabel, action, step, onDismissed, remember, }: GuideNoteProps): React.JSX.Element | null;
+interface GuideTourProps {
+    /** Notes in order. Only the first undismissed one shows, so it reads as a tour. */
+    notes: Array<Omit<GuideNoteProps, 'step' | 'onDismissed'>>;
     /**
-     * Standing answers, grouped by the screen they belong to. Claude reads them
-     * before deciding anything the board does not already settle.
+     * Which notes are already dismissed, when the caller keeps that somewhere
+     * durable. Leave it out and each reader's browser remembers, which is the
+     * right home for a fact about one browser — and the wrong one for a panel
+     * with a single owner, who would be told the same tour again on a new
+     * machine. Passing it does not switch the browser off: a note dismissed
+     * here is written to both, because a caller whose store needs saving would
+     * otherwise lose the dismissal on reload.
      */
-    choices?: Partial<Record<AnalysisSection, Choice[]>>;
+    dismissed?: string[];
+    /** Told when a note is dismissed. Required for `dismissed` to mean anything. */
+    onDismiss?: (id: string) => void;
 }
-/** Everything the owner has actually decided, newest first. */
-declare function decided(analysis: Analysis): {
-    section: AnalysisSection;
-    choice: Choice;
-    option: ChoiceOption;
-}[];
-/** Questions still open. A count of these is the honest state of the analysis. */
-declare function undecided(analysis: Analysis): {
-    section: AnalysisSection;
-    choice: Choice;
-}[];
 /**
- * What the board itself says, counted rather than declared.
+ * One note at a time, in order.
  *
- * These are not stored: a number typed into the analysis is a number that
- * disagrees with the board the moment a card moves. They are derived on every
- * render from the cards, so they cannot be wrong.
+ * Five notes at once is a wall nobody reads. Shown one at a time, dismissing
+ * each reveals the next, and a reader who dismisses all of them has been
+ * through the tour rather than having closed a box.
  */
-interface BoardFacts {
-    total: number;
-    open: number;
-    byColumn: {
-        id: string;
-        title: Text;
-        count: number;
-    }[];
-    waitingOnOwner: number;
-    orders: number;
-    highRisk: number;
-    /** Cards claiming to be finished that were never picked up. */
-    claimed: Pick<Card, 'id' | 'title'>[];
-    /** Age of the oldest card still open. Null when nothing is open. */
-    oldestOpenDays: number | null;
-    oldestOpen: Pick<Card, 'id' | 'title'> | null;
+declare function GuideTour({ notes, dismissed, onDismiss }: GuideTourProps): React.JSX.Element | null;
+
+type NotificationTone = 'info' | 'attention';
+interface PanelNotification {
+    /**
+     * Stable for the life of the event. Two different events must never share
+     * one, or marking the first seen silences the second; the same event must
+     * never change it, or it comes back every time the page loads.
+     */
+    id: string;
+    title: React.ReactNode;
+    detail?: React.ReactNode;
+    /** Shown as given, so the caller decides the format its readers expect. */
+    at?: string;
+    /** `attention` for something waiting on the reader, `info` for the rest. */
+    tone?: NotificationTone;
+    /** Where this leads. Called before the notification is marked seen. */
+    onOpen?: () => void;
+}
+interface NotificationLabels {
+    /** Names the control for a screen reader and on hover. */
+    title: string;
+    empty: string;
+    markAll: string;
+    /** Given the count, e.g. (n) => `${n} unread`. */
+    unread: (count: number) => string;
+}
+interface NotificationBellProps {
+    notifications: PanelNotification[];
+    labels?: Partial<NotificationLabels>;
+    /**
+     * What this reader has already seen, when the caller keeps it somewhere
+     * durable. Leave it out and the bell remembers in localStorage, which is the
+     * right home for a fact about one browser.
+     *
+     * A panel with one password has one owner, and there "this reader" and "this
+     * project" are the same person — so a panel that saves its board can keep
+     * this in it and have it survive a new browser. That is the caller's call to
+     * make, not the component's, which is why both work.
+     */
+    seen?: string[];
+    /**
+     * Told which ids were just seen. Required for `seen` to mean anything —
+     * though the bell also remembers in localStorage either way, so a caller
+     * that has not saved yet does not show the same notifications again.
+     */
+    onSeen?: (ids: string[]) => void;
 }
+declare function NotificationBell({ notifications, labels, seen: given, onSeen }: NotificationBellProps): React.JSX.Element | null;
+
 /**
- * Counts the board rather than believing a number somebody typed.
+ * A block of text whose whole purpose is to end up somewhere else.
  *
- * `today` is passed in so the same cards always produce the same answer — a
- * function that reads the clock cannot be checked.
+ * Anything a panel tells someone to paste — a settings fragment, two commands,
+ * a shell line — is read once and copied. So the copy is the primary action
+ * and the text is selectable underneath it, rather than the other way round.
+ *
+ * The clipboard API is not always there. It needs a secure context and can be
+ * refused outright, and a copy button that silently does nothing is worse than
+ * no button at all: the reader walks away believing they have the text. So the
+ * failure falls back to selecting the block, and says which of the two
+ * happened.
  */
-declare function boardFacts(cards: Card[], columns: ColumnDef[], today: string): BoardFacts;
-interface Trend {
-    latest: Reading | undefined;
-    previous: Reading | undefined;
-    delta: number | null;
-    /** True when the last move went against the metric's declared direction. */
-    against: boolean;
+interface CopyBlockProps {
+    /** Exactly what lands on the clipboard. Shown verbatim. */
+    text: string;
+    /** What this block is, above it. */
+    label?: React.ReactNode;
+    /** Why the reader wants it, and anything they must know before pasting. */
+    note?: React.ReactNode;
+    /** Wording, so the kit stays language-agnostic. */
+    labels?: Partial<CopyBlockLabels>;
 }
-declare function trendOf(metric: Metric): Trend;
-/**
- * Points for a sparkline in a 0–1 box, so the caller only decides the size.
- * A flat series sits on the middle line rather than collapsing to the floor.
- */
-declare function sparkPoints(readings: Reading[]): {
-    x: number;
-    y: number;
-}[];
+interface CopyBlockLabels {
+    copy: string;
+    copied: string;
+    /** Used when the clipboard refused and the text was selected instead. */
+    selected: string;
+}
+declare function CopyBlock({ text, label, note, labels }: CopyBlockProps): React.JSX.Element;
 
-type Level = 'high' | 'medium' | 'low';
-type Owner = 'claude' | 'you';
 /**
- * What the owner wants done with a card next, in one tap.
+ * What the panel needs in order to work, and what to do about what is missing.
  *
- * Free text would be clearer to write and useless to obey: "solve it if you
- * can" and "solve it yourself" are the same sentence and different
- * instructions. A fixed set gives each one an exact, documented meaning, so a
- * tap is a contract rather than a hint. Absent is a real state: no
- * instruction, use judgement.
+ * A panel with no token does not look broken — it looks fine until the moment
+ * someone presses Save, and then it fails with something the person reading it
+ * did not cause and cannot place. This turns that into a list they can read
+ * before it happens, and act on without leaving the panel.
  *
- * Three of them — explain, askme, hold — are refusals to act. Honouring them
- * exactly matters more than the work: they are the only way to say "not yet".
+ * The status comes from the server, which is the only place that can see the
+ * environment. It reports *whether* a variable is set and never its value, so
+ * this component has nothing worth leaking.
  */
-declare const INTENTS: readonly ["decide", "explain", "solve", "do", "cheap", "safe", "fast", "askme", "hold"];
-type Intent = (typeof INTENTS)[number];
-interface IntentCopy {
-    label: Record<Lang, string>;
-    meaning: Record<Lang, string>;
-}
-declare const INTENT_COPY: Record<Intent, IntentCopy>;
-interface Check {
-    id: string;
-    text: Text;
-    done: boolean;
-}
-interface Note {
-    id: string;
-    by: Owner;
-    date: string;
-    text: Text;
-}
-interface Card {
+type SetupStatus = 'ok' | 'missing' | 'unknown';
+interface SetupRequirement {
     id: string;
-    column: string;
-    title: Text;
-    body: Text;
-    area: string;
-    priority: Level;
-    risk: Level;
-    owner: Owner;
-    /** The one flag that means "I am asking you to do this". */
-    order: boolean;
-    intent: Intent | null;
-    checks: Check[];
-    notes: Note[];
-    createdAt: string;
-    updatedAt: string;
+    /** What it is, in the reader's terms rather than the variable's. */
+    label: React.ReactNode;
+    status: SetupStatus;
+    /** The environment variable behind it, when there is one to name. */
+    variable?: string;
+    /** What it lets the panel do — so a missing one has a visible cost. */
+    enables?: React.ReactNode;
+    /** Exactly what to do, shown only when it is missing. */
+    fix?: React.ReactNode;
     /**
-     * Stamped by the board when the card enters the working column, and when it
-     * reaches a done column. They are written by the move, never typed, so a
-     * card that carries `completedAt` with no `startedAt` is one that was
-     * declared finished without ever being picked up — which is exactly the
-     * thing worth being able to see.
+     * Information rather than a gate: drawn in the list, never walked as a step.
+     *
+     * Every other requirement here is an environment variable, and the
+     * walkthrough's one action — re-read the environment from the server —
+     * is what clears it. A requirement that action cannot clear parks the
+     * walkthrough on it for ever, and because `unknown` is judged across the
+     * whole list, one advisory row that nobody wired made every step answer a
+     * successful check with "the panel could not ask its own server". That is
+     * what the copied gate did the day it was added.
      */
-    startedAt?: string | null;
-    completedAt?: string | null;
-}
-interface ColumnDef {
-    id: string;
-    title: Text;
-    /** What the column means, shown on hover. Two words cannot say whether a
-        card sitting here is waiting on you or on Claude. */
-    hint?: Text;
-    /** Work in flight: entering this column stamps the card as started. */
-    active?: boolean;
-    /** Cards here are finished: they leave the open counts alone. */
-    done?: boolean;
-}
-/**
- * One pass over the board: what a session changed, and which cards it
- * touched. Written at the end of a run, so the panel keeps the account
- * rather than the account living in a chat nobody can re-read.
- */
-interface Run {
-    id: string;
-    date: string;
-    by: Owner;
-    summary: Text;
-    /** Card ids this run touched, so a claim can be checked against the board. */
-    cards: string[];
-    /** The kit fingerprint at the time, twelve characters is enough to compare. */
-    fingerprint?: string;
+    advisory?: boolean;
 }
-interface HealthFact {
-    label: Text;
-    value: Text;
-    status: 'ok' | 'warning' | 'bad' | 'unknown';
+interface SetupGuideProps {
+    requirements: SetupRequirement[];
+    /** Shown when everything is in place, instead of an empty list. */
+    readyMessage?: React.ReactNode;
+    /** Wording, so the kit stays language-agnostic. */
+    labels?: Partial<{
+        ok: string;
+        missing: string;
+        unknown: string;
+        whatToDo: string;
+    }>;
 }
+declare function SetupGuide({ requirements, readyMessage, labels }: SetupGuideProps): React.JSX.Element;
+
 /**
- * A theme Claude derived from the project it is installed in.
+ * The setup, walked one step at a time.
  *
- * Stored with where it came from, not only with its colours. "Update the
- * theme" is only a meaningful request if the next answer can be compared with
- * this one — otherwise a regenerated theme is a different theme for reasons
- * nobody can see. `from` is what makes the difference readable.
+ * `SetupGuide` is the list: the right shape for somebody auditing a panel that
+ * already works. This is the other reader — the one who installed it twenty
+ * minutes ago, has four things missing and no idea which to do first. A wall
+ * of four is not four times as useful as one; it is the thing people close.
  *
- * `refreshRequested` is a message, not a trigger: a panel cannot run Claude.
- * Tapping Update writes the date here, the bell shows it, and the next session
- * regenerates. Pretending the button does the work itself would leave the
- * owner waiting for something that was never going to happen.
+ * Two rules hold it honest. It **checks rather than asks**: every step ends in
+ * a button that re-reads the environment from the server, so the reader is
+ * told whether it worked instead of ticking a box themselves. And it **never
+ * claims what it cannot see**: a panel that could not reach its own endpoint
+ * says the check failed, never that a variable is missing, because telling
+ * somebody to add a token they already added is the worse of the two wrong
+ * answers.
+ *
+ * There is no copy of the values here and nothing is written: the panel cannot
+ * set an environment variable, and a button that appeared to would be the same
+ * fault as one that appeared to install an update.
  */
-interface ImportedTheme {
-    /** What to call it in the theme list. */
-    label: Text;
-    tokens: Record<string, string>;
-    form?: Record<string, string | number>;
-    from: {
-        /** Files the colours were read out of, so the claim can be checked. */
-        files: string[];
-        /** The colours actually found, before they were mapped to tokens. */
-        colours: string[];
-        /** Why these tokens and not others. One or two sentences. */
-        reasoning: Text;
-    };
-    importedAt: string;
-    importedBy: 'claude';
-    /** Set by the panel when the owner asks for it to be derived again. */
-    refreshRequested?: string | null;
+interface SetupWizardLabels {
+    title: string;
+    /** `(index, total)` — "Step 2 of 5". */
+    progress: (index: number, total: number) => string;
+    /** Shown above the one step in hand. */
+    nowDo: string;
+    /** The button that re-reads the environment. */
+    check: string;
+    checking: string;
+    /** Said when a check ran and the step is still not in place. */
+    stillMissing: string;
+    /** Said when the panel could not ask its own server. */
+    cannotTell: string;
+    /** The heading over the finished steps. */
+    doneTitle: string;
+    /** Shown in place of a step when every requirement is in place. */
+    readyTitle: string;
+    readyBody: string;
+    /** The two things to try before trusting the gate, as list items. */
+    verify: string[];
+    /** Closes the wizard. */
+    close: string;
+    /** The escape hatch: heading, explanation, and the prompt to copy. */
+    stuckTitle: string;
+    stuckBody: string;
+    stuckPrompt: string;
+    copy: string;
+    copied: string;
+}
+interface SetupWizardProps {
+    /** In the order they are to be done. The caller owns that order. */
+    requirements: SetupRequirement[];
+    labels: SetupWizardLabels;
+    /** Re-reads the environment. Resolves when the answer has been applied. */
+    onCheck: () => Promise<void> | void;
+    /** Told when the reader closes it. */
+    onClose?: () => void;
 }
+declare function SetupWizard({ requirements, labels, onCheck, onClose }: SetupWizardProps): React.JSX.Element;
+
 /**
- * What the owner has chosen, kept in the board so it survives a new browser.
+ * Where a reader is in the setup, as one answer instead of a list to read.
  *
- * The kit's default is to remember these per browser, in localStorage, because
- * for a component "which notes this reader dismissed" is a fact about a reader
- * and not about a project. A panel with one password is the case where those
- * two are the same person: keeping it here means the theme, the language and
- * what has already been read follow the owner to a new machine instead of
- * greeting them with a tour they finished months ago.
+ * `SetupGuide` draws every requirement at once, which is the right shape for
+ * somebody checking a panel that already works. It is the wrong shape for
+ * somebody who has just installed one: five things at once, four of them
+ * missing, and no order to do them in reads as a wall rather than as a first
+ * step. So the same requirements are walked one at a time, and this is the
+ * function that decides which one.
  *
- * The cost is real and worth naming: anyone who shares the password shares
- * this. It holds a theme name and a list of ids — nothing worth stealing, and
- * nothing anyone else would want.
+ * The order the caller gives is the order they are done in — a token that
+ * cannot be scoped before the repository is named is a step in the wrong
+ * place, and that is the caller's knowledge, not this function's.
  */
-interface Preferences {
-    theme?: string;
-    lang?: Lang;
-    /** Ids of notifications already read. Bounded when saved. */
-    seen?: string[];
-    /** Ids of guide notes already dismissed. */
-    guideDismissed?: string[];
+interface WizardStep {
+    /** The requirement to show, or null when nothing is left to do. */
+    current: SetupRequirement | null;
+    /** 1-based, for "step 2 of 5". Zero when there is nothing left. */
+    index: number;
+    /** How many steps this setup has in total. */
+    total: number;
+    /** Every requirement that is in place, in the caller's order. */
+    done: SetupRequirement[];
+    /** True when every requirement is `ok`. */
+    ready: boolean;
     /**
-     * Whether an update card is written as an order rather than a suggestion.
+     * True when the panel could not ask the server, so nothing is claimed.
      *
-     * It does not make anything automatic — the panel cannot run npm, and this
-     * changes `order` on the card it offers to write, nothing else. Off means
-     * the card asks; on means it tells.
+     * This is not "not ready": a panel that cannot reach its own endpoint knows
+     * nothing about the environment, and telling somebody to add a token they
+     * already added is worse than saying the check itself failed.
      */
-    updateAsOrder?: boolean;
-}
-interface PanelState {
-    v: 2;
-    project: string;
-    environment: Text;
-    updatedAt: string;
-    notice?: Text;
-    columns: ColumnDef[];
-    areas: {
-        id: string;
-        label: Text;
-    }[];
-    health: HealthFact[];
-    cards: Card[];
-    /** Newest first. Capped when saving, so the file cannot grow without end. */
-    runs: Run[];
-    /** What any of the work is for: goals, constraints, metrics, strategies. */
-    analysis?: Analysis;
-    /** The owner's choices, so they survive a new browser. */
-    preferences?: Preferences;
-    /** A theme Claude derived from this project, with where it came from. */
-    importedTheme?: ImportedTheme;
+    unknown: boolean;
 }
-declare const LEVELS: Level[];
-declare const OWNERS: Owner[];
-declare function newId(): string;
-declare function today(): string;
-/** A card is created empty and named second — the same as tapping "+" on paper. */
-declare function emptyCard(column: string, area: string): Card;
-/**
- * How long a finished card stays on the board before it becomes history.
- *
- * A done column only grows. It is the one column nothing ever removes from,
- * so a board that is being worked turns into a wall of things already
- * finished, and the three columns that need reading get a third of the screen
- * between them. A week is the window in which "what did we ship" is still a
- * live question; after that it is a record, and a record does not need to be
- * in the way.
- */
-declare const ARCHIVE_AFTER_DAYS = 7;
+declare function wizardStep(requirements: SetupRequirement[]): WizardStep;
 /**
- * Whether a finished card has been finished long enough to stop being drawn.
+ * Whether this panel has never been worked, which is what "first install"
+ * means here.
  *
- * Derived on every render and never written, which is the arrangement
- * `boardFacts()` already uses: a flag stored on the card would be wrong the
- * day after it was set, and setting it would mark the panel dirty for the
- * passage of time. Here the answer simply becomes true on its own.
+ * `paneltir init` writes a board with the columns already there and nothing
+ * on them, so a board carrying no cards and no runs is one nobody has used
+ * yet. That is a better signal than a version on disk: a project can install
+ * the package, never open the panel, and update three times before anyone
+ * sees it — and it is still that reader's first run.
  *
- * **A card with no `completedAt` is never archived**, whatever column it sits
- * in. It reached done without being stamped — a board edited by hand, or one
- * from before the stamp existed — so its age is not known, and hiding a card
- * whose age nobody knows is the same mistake as reporting a token missing
- * because the check could not run. `unknown` is not `old`.
- */
-declare function isArchived(card: Card, doneColumns: ReadonlySet<string>, now?: string, afterDays?: number): boolean;
-/**
- * Applies the column's own meaning to a card that just moved into it: a card
- * entering the working column is started, one reaching a done column is
- * finished, and one dragged back out of done is not finished any more.
+ * A panel that has been worked and then loses a variable is deliberately not
+ * this. It needs the same instructions and gets them from the same wizard,
+ * but it is told rather than taken over: somebody mid-sentence on a board
+ * they know does not want a walkthrough opening on top of it.
  */
-declare function stampForColumn(card: Card, columns: ColumnDef[]): Card;
+declare function isFirstRun(board: {
+    cards?: unknown[];
+    runs?: unknown[];
+}): boolean;
+
+type Handler = (payload: Record<string, string>, event: MouseEvent) => void;
 /**
- * Where a card the panel writes on the reader's behalf goes.
- *
- * The update card and the four "ask for this again" cards used to be born in
- * a column literally called `next`. The default board has one; a board whose
- * owner renamed it does not, and a card in a column that does not exist is
- * the exact fault `validateBoard` names — drawn nowhere, and refused by the
- * write path, so one tap on a button turned a saveable board into one that
- * could not be saved and said so about a column the reader had never heard of.
+ * A single click listener on document that dispatches by data-* attributes,
+ * instead of one handler per element. Meant for a project's own actions; the
+ * Board does not use it internally.
  *
- * `next` when there is one, because that is what the button means. Otherwise
- * the first column that is neither in flight nor finished nor the owner's:
- * queued work goes where queued work already sits. And the first column of
- * all when nothing else fits, since a board with no columns cannot pass the
- * validator either way.
+ * Example: useDelegatedClick('data-action', (payload) => { if (payload.action === 'delete') ... })
+ * with buttons such as <button data-action="delete" data-id="42">
  */
-declare function queueColumn(columns: ColumnDef[]): string;
-/** A card claiming to be finished that was never picked up. */
-declare function claimedWithoutStarting(card: Card): boolean;
-interface Counts {
-    open: number;
-    orders: number;
-    yours: number;
-    decisions: number;
-    highRisk: number;
-    done: number;
-}
-declare function countCards(state: PanelState): Counts;
-/** How many checklist steps are ticked, for the counter on a card. */
-declare function checkProgress(card: Card): {
-    done: number;
-    total: number;
-} | undefined;
+declare function useDelegatedClick(attribute: string, handler: Handler): void;
+
+declare function useMediaQuery(query: string): boolean;
 
 /**
  * Reads a board and says what is wrong with it, in words.
@@ -1471,6 +1504,18 @@ interface UiStrings {
     releaseNone: string;
     updateCardTitle: (version: string) => string;
     updateCardBody: (version: string) => string;
+    versionBumpAsk: string;
+    versionBumpOpen: string;
+    versionBumpHow: string;
+    versionBumpTitle: string;
+    versionBumpBody: string;
+    versionBumpChecks: string[];
+    installAsk: string;
+    installAskOpen: string;
+    installAskHow: string;
+    installCardTitle: (tool: string) => string;
+    installCardBody: (tool: string, file: string, snippet: string) => string;
+    installCardChecks: string[];
     cardDetail: string;
     panelSettings: string;
     title: string;
@@ -2004,8 +2049,15 @@ interface MarketplaceViewProps {
     ui: UiStrings;
     /** Absent where there is no server to ask, so no dead button is drawn. */
     onRefresh?: () => void;
+    /**
+     * Writes a card asking Claude to install a plugin. Absent where the board
+     * cannot be saved, so the button is not drawn where the card would be lost.
+     */
+    onRequestInstall?: (tool: MarketplaceTool, marketplace: Marketplace) => void;
+    /** Whether an install card for this tool is already waiting on the board. */
+    installRequested?: (toolId: string) => boolean;
 }
-declare function MarketplaceView({ report, loading, failure, lang, ui, onRefresh }: MarketplaceViewProps): React.JSX.Element;
+declare function MarketplaceView({ report, loading, failure, lang, ui, onRefresh, onRequestInstall, installRequested, }: MarketplaceViewProps): React.JSX.Element;
 
 interface CardSheetProps {
     card: Card | null;
@@ -2018,4 +2070,4 @@ interface CardSheetProps {
 }
 declare function CardSheet({ card, state, lang, ui, onChange, onDelete, onClose }: CardSheetProps): React.JSX.Element | null;
 
-export { ANALYSIS_SECTIONS, ARCHIVE_AFTER_DAYS, AlertBanner, type AlertBannerProps, type Analysis, type AnalysisSection, AnalysisView, BOARD_VERSION, Board, type BoardCardData, type BoardCheck, type BoardColumnData, type BoardFacts, type BoardMoveResult, type BoardProblem, type BoardProps, type BoardTag, CAPABILITIES, type Capability, Card$1 as Card, type CardProps, CardSheet, type Check, type Choice, type ChoiceOption, type ColumnDef, type Competitor, type Constraint, CopyBlock, type CopyBlockLabels, type CopyBlockProps, type Counts, DashboardHeader, type DashboardHeaderProps, type DashboardThemeForm, DashboardThemeProvider, type DashboardThemeTokens, DetailSection, type DetailSectionProps, DetailSheet, type DetailSheetProps, FilterChip, type FilterChipProps, FilterChipRow, type GateReading, type GateStamp, type GateVerdict, type Goal, GuideNote, type GuideNoteProps, GuideTour, type GuideTourProps, type HealthFact, HealthPill, type HealthPillProps, HealthPillRow, type HealthStatus, INTENTS, INTENT_COPY, type ImportedTheme, type InstallState, type Intent, type IntentCopy, LANGS, LANG_LABELS, LEVELS, type Lang, type Level, MARKETPLACE_NAME, MARKETPLACE_URL, type Market, type MarketplaceReport, type MarketplaceTool, MarketplaceView, type Metric, type Note, NotificationBell, type NotificationBellProps, type NotificationLabels, type NotificationTone, OWNERS, type Owner, PANELTIR_FILE_COUNT, PANELTIR_FINGERPRINT, PANELTIR_TEMPLATE_HASH, PANELTIR_VERSION, PRESET_PANEL_THEMES, PanelApp, type PanelAppProps, type Card as PanelCard, type PanelNotification, type PanelState, type PanelTheme, type PanelThemes, type Preferences, type Reading, type Run, SetupGuide, type SetupGuideProps, type SetupRequirement, type SetupStatus, SetupWizard, type SetupWizardLabels, type SetupWizardProps, type Severity, type SituationItem, SituationRow, type SituationRowProps, type SituationTone, StatTile, StatTileGrid, type StatTileProps, type Strategy, type Suggestion, type SuggestionStatus, THEME_FORMS, THEME_PRESETS, type Text, type ThemeFormName, type ThemePresetName, type Trend, UI, type UiStrings, type Weight, type WizardStep, applyMove, boardFacts, checkProgress, claimedWithoutStarting, claudeTheme, commandSnippet, countCards, cyberpunkTheme, decided, dropIndex, emptyCard, explainBoard, gateStatus, isArchived, isCard, isFirstRun, ledgerForm, midnightTheme, moveCardInColumns, newId, offeredThemes, oldMoneyTheme, panelForm, paneltirBuild, paperForm, queueColumn, readBoard, readStoredLang, repositorySnippet, resetGuide, sparkPoints, stampForColumn, storeLang, text, today, trendOf, undecided, untranslated, useDashboardForm, useDashboardTheme, useDelegatedClick, useGuideNote, useMediaQuery, validateBoard, warRoomForm, wizardStep, writeText };
+export { ANALYSIS_SECTIONS, ARCHIVE_AFTER_DAYS, AlertBanner, type AlertBannerProps, type Analysis, type AnalysisSection, AnalysisView, BOARD_VERSION, Board, type BoardCardData, type BoardCheck, type BoardColumnData, type BoardFacts, type BoardMoveResult, type BoardProblem, type BoardProps, type BoardTag, CAPABILITIES, type Capability, Card$1 as Card, type CardProps, CardSheet, type Check, type Choice, type ChoiceOption, type ColumnDef, type Competitor, type Constraint, CopyBlock, type CopyBlockLabels, type CopyBlockProps, type Counts, DashboardHeader, type DashboardHeaderProps, type DashboardThemeForm, DashboardThemeProvider, type DashboardThemeTokens, DetailSection, type DetailSectionProps, DetailSheet, type DetailSheetProps, FilterChip, type FilterChipProps, FilterChipRow, type GateReading, type GateStamp, type GateVerdict, type Goal, GuideNote, type GuideNoteProps, GuideTour, type GuideTourProps, type HealthFact, HealthPill, type HealthPillProps, HealthPillRow, type HealthStatus, INTENTS, INTENT_COPY, type ImportedTheme, type InstallState, type Intent, type IntentCopy, LANGS, LANG_LABELS, LEVELS, type Lang, type Level, MARKETPLACE_NAME, MARKETPLACE_URL, type Market, type MarketplaceReport, type MarketplaceTool, MarketplaceView, type Metric, type Note, NotificationBell, type NotificationBellProps, type NotificationLabels, type NotificationTone, OWNERS, type Owner, PANELTIR_FILE_COUNT, PANELTIR_FINGERPRINT, PANELTIR_TEMPLATE_HASH, PANELTIR_VERSION, PRESET_PANEL_THEMES, PanelApp, type PanelAppProps, type Card as PanelCard, type PanelNotification, type PanelState, type PanelTheme, type PanelThemes, type Preferences, type Reading, type RequestKind, type Run, SetupGuide, type SetupGuideProps, type SetupRequirement, type SetupStatus, SetupWizard, type SetupWizardLabels, type SetupWizardProps, type Severity, type SituationItem, SituationRow, type SituationRowProps, type SituationTone, StatTile, StatTileGrid, type StatTileProps, type Strategy, type Suggestion, type SuggestionStatus, THEME_FORMS, THEME_PRESETS, type Text, type ThemeFormName, type ThemePresetName, type Trend, UI, type UiStrings, type Weight, type WizardStep, applyMove, boardFacts, checkProgress, claimedWithoutStarting, claudeTheme, commandSnippet, countCards, cyberpunkTheme, decided, dropIndex, emptyCard, explainBoard, gateStatus, isArchived, isCard, isFirstRun, ledgerForm, midnightTheme, moveCardInColumns, newId, offeredThemes, oldMoneyTheme, panelForm, paneltirBuild, paperForm, pendingRequest, queueColumn, readBoard, readStoredLang, repositorySnippet, requestId, resetGuide, sparkPoints, stampForColumn, storeLang, text, today, trendOf, undecided, untranslated, useDashboardForm, useDashboardTheme, useDelegatedClick, useGuideNote, useMediaQuery, validateBoard, warRoomForm, wizardStep, writeText };