makersclaw 0.8.0 → 0.8.2

package/registry/blocks/agent-dock/README.md

@@ -0,0 +1,210 @@
+# AgentDock
+
+Where an app's agent lives (0.8.1): a column on the right, beside the work,
+like the desk's own agent sidebar.
+
+The founder, testing an app: "why are we still using this weak ai sidebar
+component? I thought we had created the original agent sidebar as component
+in the template". We had: `agent-pane` is the desk's sidebar. What was
+missing was its host. Every app invented one: a modal `Sheet` that dimmed
+the work, an inspector tab, a card. So no two apps felt alike, and none felt
+like the sidebar. This is the host, once.
+
+- A **column beside the content**, under the top bar and right of the rail.
+  The work reflows beside it. Nothing is dimmed.
+- **Resizable.** A quarter of the body until dragged, never under 280 px,
+  never over half. The divider is a separator a keyboard can move: arrows
+  nudge it, Home goes back to a quarter, End to the widest.
+- **Remembered.** The open state and the width are kept in this browser, per
+  app (`storageKey`), in `localStorage` with a `try/catch`; with no storage
+  it still works.
+- **A sheet where there is no room.** Where the body is under `columnAt`
+  (900 px; a measure of the frame's own width, never the window) the dock is
+  a sheet laid over the app from the right. Escape folds it. The chat is not
+  remounted on the way: a turn in flight survives a resize.
+- **The pane keeps its head.** The `agent-pane` inside draws title, New chat,
+  Chats and the close; its empty state lists the past chats (or "No chats
+  yet"), then the app's suggestions, then the box: the desk's message box
+  (the `chat-pane` block's), with the words on top and + to attach and a
+  round send under them. The dock only tells the pane how to close, and
+  hands it a starting line when a "have the agent do it" button asked for one.
+- **Stays mounted once opened**, so a draft and a running turn survive
+  folding the column.
+
+```jsx
+import { AgentDock, useAgentDock } from "../components/blocks/agent-dock";   // a Makersclaw app ("./blocks/agent-dock" from components/)
+import { AgentDock, useAgentDock } from "@/components/makersclaw/blocks/agent-dock";   // a shadcn project
+```
+
+A client component. It needs the kit's `AppLayout` with its `dock` slot
+(0.8.1), or any flex row it is the last child of.
+
+## Adopting it in a shell (a few lines)
+
+The shell is the app's one `AppLayout`. Give it the dock, and make every Ask
+button open it: the top bar's own Ask does that when the shell wraps the
+layout in `AskProvider` (blocks/top-bar).
+
+```jsx
+"use client";
+import { AppLayout } from "../components/ui";
+import { AgentDock, useAgentDock } from "../components/blocks/agent-dock";
+import { AskProvider } from "../components/blocks/top-bar";
+import { AskPanel } from "../components/ask-panel";   // the app's own pane over AgentPane
+
+export default function Shell({ children, budget }) {
+  const dock = useAgentDock({ storageKey: "crm" });   // { open, setOpen, toggle }
+  return (
+    <AskProvider dock={dock} allowance={{ used: budget.used, cap: budget.cap }} findEvent="crm:find">
+      <AppLayout
+        navigation={<Rail />}
+        dock={
+          <AgentDock dock={dock} label="Ask the agent">
+            <AskPanel />   {/* useAgentPane({ row }) inside, AgentPane (not bare) */}
+          </AgentDock>
+        }
+      >
+        {children}   {/* each screen draws its own <TopBar crumb=… action=…/> */}
+      </AppLayout>
+    </AskProvider>
+  );
+}
+```
+
+Delete the shell's old `<Sheet>` for the agent, and drop `bare` from the pane
+(the dock's pane has its own head).
+
+**One dock per app, in the shell.** A record's own pane (a meeting, a
+person) is this same dock with a chat scoped to the open record: make the
+`AskPanel` read the record the page has open and pass it as
+`useAgentPane({ row })`. The thread follows the record; the column stays
+where it is. Do not add a second column.
+
+Also set `"agent_pane": true` in the package's blueprint (see `agent-pane`)
+so the desk draws no second sidebar for the window.
+
+## Just open it
+
+**To open the dock and send nothing, call `openAgent()` with no line.** One
+way, from anywhere on the page:
+
+```jsx
+import { openAgent } from "../components/blocks/agent-dock";
+
+<Button variant="link" onClick={() => openAgent()}>Talk to the agent</Button>
+```
+
+- `openAgent()` and `openAgent({ ask: "" })` open the dock (column or sheet),
+  put the cursor in the box, send nothing and start no chat. It returns
+  `true` when a dock took it.
+- It only ever **opens**. The top bar's Ask **toggles** (it also closes);
+  `useAsk()` is for reading whether the agent is open (`open`) and for that
+  toggle, not for opening it from a screen.
+- From the shell, where `useAgentDock()` is held, `dock.setOpen(true)` is the
+  same thing, and `dock.openAgent()` too. A screen far from the shell uses the
+  exported `openAgent()`: do not write your own event, ref or context for it.
+- With a line, it is the next section: the dock opens and the pane sends it.
+
+## Have the agent do it
+
+**Every button that says the agent will do the work calls `openAgent`.** It
+never opens a form, a route or a sheet first. The founder, on a project
+planner whose "Have the agent draft it" first asked for a name, a code and
+two dates: "the agent should be able to create these".
+
+```jsx
+import { openAgent } from "../components/blocks/agent-dock";
+
+<Button variant="primary" icon="sparkles" onClick={() => openAgent("Draft a project plan for me")}>
+  Have the agent draft it
+</Button>
+```
+
+`openAgent("…")` opens the dock and hands the pane its first line. The pane
+starts a new chat and sends the line as the member's first words; the agent
+asks only for what it is missing (the name, the target date), in the chat
+as a question the member answers there; then it creates the record through
+the app's own actions. A form stays only for "type it yourself".
+
+- `openAgent("Draft a project plan for me")`, or an object:
+- `ask`: the starting line. Say what the member wants done, in their words.
+  Left out or empty, the dock only opens ("Just open it", above).
+- `send`: `true` (the default) sends it. `false` puts it in the box for the
+  member to finish: `openAgent({ ask: "Draft a project plan for ", send: false })`.
+- `fresh`: `true` (the default) is a new chat, so it is its own ask and not a
+  follow-up to the last one. `false` carries on in the chat that is open.
+- `storageKey`: only that app's dock (default: any dock on the page, and an
+  app has one).
+- It returns `true` when a dock took it and `false` when the page has none.
+  Do not use the `false` to open a form: an app that has an agent has the dock
+  in its shell (AppLayout's `dock` slot). `npm run check` (rule `agentfirst`)
+  refuses a button whose words say the agent will do the work ("Have the
+  agent draft it", "Let the agent plan it") when it submits a form, follows a
+  link or only changes a step; it must call `openAgent` or ask the agent
+  (`ask`, `chat.send`). A choice labelled that way inside a form fails too.
+
+From the shell, where `useAgentDock()` is held, `dock.openAgent(ask)` does the
+same without the page event. A screen far from the shell uses the exported
+`openAgent`; a line the member is shown first (a chip, an ask bar) uses
+`chat.send` as before.
+
+The agent's side: its brief names the app's create actions in
+`references/actions.md`, and the draft action takes its inputs as optional
+(`name`, `start`, `target`), so a line like "Draft a project plan for me"
+reaches it with nothing and it asks. Write the line so it carries what the
+screen already knows ("Draft a project plan for the Pinewood launch").
+
+## Props
+
+- `dock`: what `useAgentDock()` returns (`open`, `setOpen`, `storageKey`,
+  `asked`, `start`, `startTaken`). Or pass the parts:
+- `open`, `onOpenChange`: the dock is yours to open and close.
+- `storageKey`: where the width is kept (default the dock's, else `"app"`).
+- `label`: the column's name for a screen reader. Default `"Agent"`.
+- `columnAt`: body width in px from which it is a column. Default `900`.
+- `children`: the pane. Your own component over `AgentPane` (the app's yes
+  card, its titles). Without children the dock draws an `AgentPane` from:
+- `chat`, `title`, `suggestions`, `empty`, `placeholder`, `yes`, `mark`,
+  `onOpen`, `recent`: the `AgentPane`'s own props.
+- `className`: the column's layout. Never colour.
+
+### useAgentDock({ storageKey, defaultOpen, listen })
+
+Returns `{ open, setOpen(bool | fn), toggle(), openAgent(ask), storageKey,
+asked, start, startTaken }`. `listen` (default true) is whether it hears
+`openAgent()` calls from anywhere on the page; the shell's one hook is the
+one that does. The
+choice is read from storage after the first paint (so the server's and the
+browser's first render agree) and written when the member changes it.
+`defaultOpen` (false) holds until they choose. `asked` counts the member's
+opens: when it rises the dock puts the cursor in the box. A restored open
+dock never steals focus. Folding the dock gives focus back to what had it
+when it opened (the Ask button), unless the member has gone elsewhere.
+
+### The model (plain functions)
+
+`MIN_W`, `COLUMN_AT`, `maxWidth(body)`, `clampWidth(w, body)`,
+`storedWidth(raw)`, `columnWidth(width, body)`, `hasRoom(body, columnAt)`,
+`dragged(startWidth, startX, x, body)`, `nudged(key, now, body)`,
+`dockKeys(storageKey)`, `openRequest(input)`, `OPEN_EVENT`.
+
+## Example
+
+```jsx
+// Without an app-owned pane: the dock draws the AgentPane itself.
+const dock = useAgentDock({ storageKey: "notes" });
+const chat = useAgentPane();
+<AppLayout
+  dock={<AgentDock dock={dock} chat={chat} title="Ask about your notes" suggestions={["Summarise this week"]} />}
+>
+  …
+</AppLayout>;
+```
+
+## States drawn in the demo
+
+Closed (nothing drawn but the app); open as a column at 1100 px with past
+chats, and with "No chats yet"; dragged and nudged; a sheet at 700 px with
+Escape; a chat answering; "Have the agent draft it" on the page, which opens
+the dock with its line already sent in a new chat (and "Start a line" beside
+it, which puts the line in the box instead).

package/registry/blocks/agent-dock/agent-dock.jsx

@@ -0,0 +1,356 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { cx } from "../../ui";
+import { AgentDockContext, AgentPane } from "../agent-pane";
+import { COLUMN_AT, MIN_W, OPEN_EVENT, carriesLine, columnWidth, dockKeys, dragged, hasRoom, nudged, openRequest, storedWidth } from "./dock-model";
+
+// AgentDock — where the app's agent lives: a column on the right, beside the
+// work, like the desk's own agent sidebar (2026-10-12). The founder: "why are
+// we still using this weak ai sidebar component?" The pane was the desk's
+// sidebar, but every app invented its own host for it (a modal sheet that
+// dimmed the work, an inspector tab), so none felt like the sidebar. This is
+// the host, once.
+//
+//   const dock = useAgentDock({ storageKey: "crm" });   // dock.open, dock.toggle
+//   <AppLayout dock={<AgentDock dock={dock}><AskPanel /></AgentDock>} …>…</AppLayout>
+//   <Button onClick={dock.toggle}>Ask</Button>
+//
+// It draws the head-less shell around the pane: the column (a quarter of the
+// body until dragged, never under MIN_W, never over half), the divider that
+// is dragged or nudged with the arrow keys (width kept in this browser, per
+// app), the work reflowing beside it, and a sheet laid over the app where the
+// body has no room for both. The pane inside draws its own head (title, New
+// chat, Chats, close); the dock only tells it how to close, through
+// AgentDockContext. The chat stays mounted once opened, so a turn in flight
+// and a draft survive folding the column.
+//
+// A button that says the agent will do the work calls openAgent("Draft a
+// project plan for me") (X9): the dock opens and the pane sends that line in
+// a new chat, and the agent asks only for what it is missing. Never a form
+// first.
+
+const readKey = (key) => {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+};
+const writeKey = (key, value) => {
+  try {
+    if (value === null) localStorage.removeItem(key);
+    else localStorage.setItem(key, value);
+  } catch {
+    /* private mode, blocked storage */
+  }
+};
+
+/**
+ * Whether the dock is open, remembered in this browser per app.
+ *
+ *   storageKey   the app (a short word: "crm"); the open state and the
+ *                width are kept under it
+ *   defaultOpen  until the member has chosen (default false)
+ *   listen       hear openAgent() calls from anywhere on the page (default
+ *                true; the one dock in the shell is the one that listens)
+ *
+ * Returns { open, setOpen(bool), toggle(), openAgent(ask), storageKey,
+ * asked, start, startTaken }. `asked` counts the member's opens: the dock
+ * puts the cursor in the box when it rises, never on a page load that
+ * restores an open dock. `start` is the starting line an openAgent call
+ * left for the pane, until the pane takes it (`startTaken`).
+ */
+export function useAgentDock({ storageKey = "app", defaultOpen = false, listen = true } = {}) {
+  const [open, setOpenState] = useState(defaultOpen);
+  const [asked, setAsked] = useState(0);
+  const [start, setStart] = useState(null);
+  const now = useRef(open);
+  now.current = open;
+  // The stored choice is read after the first paint, so the server's and the
+  // browser's first render agree.
+  useEffect(() => {
+    const v = readKey(dockKeys(storageKey).open);
+    if (v === "1") setOpenState(true);
+    else if (v === "0") setOpenState(false);
+  }, [storageKey]);
+  const setOpen = useCallback(
+    (next) => {
+      const v = Boolean(typeof next === "function" ? next(now.current) : next);
+      now.current = v;
+      setOpenState(v);
+      if (v) setAsked((n) => n + 1);
+      writeKey(dockKeys(storageKey).open, v ? "1" : "0");
+    },
+    [storageKey],
+  );
+  const toggle = useCallback(() => setOpen(!now.current), [setOpen]);
+  // "Have the agent do it": open, and leave the pane its first line.
+  const openWith = useCallback(
+    (request) => {
+      setOpen(true);
+      if (carriesLine(request)) setStart(request);
+    },
+    [setOpen],
+  );
+  const openHere = useCallback((input) => openWith(openRequest(input)), [openWith]);
+  const startTaken = useCallback((nonce) => setStart((s) => (s && s.nonce === nonce ? null : s)), []);
+  useEffect(() => {
+    if (!listen || typeof window === "undefined") return undefined;
+    const on = (e) => {
+      const d = e.detail;
+      if (!d || (d.storageKey && d.storageKey !== storageKey)) return;
+      d.handled = true;
+      openWith(d);
+    };
+    window.addEventListener(OPEN_EVENT, on);
+    return () => window.removeEventListener(OPEN_EVENT, on);
+  }, [listen, storageKey, openWith]);
+  return { open, setOpen, toggle, openAgent: openHere, storageKey, asked, start, startTaken };
+}
+
+/**
+ * "Have the agent do it": open the agent with its first line already in
+ * hand. Call it from anywhere on the page (a button on a screen, a card's
+ * action); the app's one dock hears it.
+ *
+ *   openAgent("Draft a project plan for me")
+ *   openAgent({ ask: "Draft a project plan for …", send: false })
+ *
+ * The line is sent as the member's first words in a new chat, and the agent
+ * asks for only what it is missing, in the chat; it then does the work with
+ * the app's own actions. `send: false` puts the line in the box instead, to
+ * finish. `fresh: false` carries on in the open chat. `storageKey` aims at
+ * one app's dock. → true when a dock took it; false when the page has none
+ * (the caller's own fallback, e.g. a form, may run then).
+ *
+ * With no line (`openAgent()`, or `{ ask: "" }`) it only opens the dock: it
+ * sends nothing and starts no chat. That is the one way to open the agent
+ * from a screen far from the shell (a "Talk to the agent" link, an empty
+ * state). Ask in the top bar toggles; this only ever opens.
+ */
+export function openAgent(input) {
+  if (typeof window === "undefined") return false;
+  const detail = { ...openRequest(input), handled: false };
+  window.dispatchEvent(new CustomEvent(OPEN_EVENT, { detail }));
+  return detail.handled;
+}
+
+/**
+ *   dock          what useAgentDock() returns: the open state, its setter and
+ *                 the storage key. Or pass the parts:
+ *   open, onOpenChange   the dock is yours to open and close (controlled)
+ *   storageKey    where the width is kept (default "app", or dock's)
+ *   label         the column's name for a screen reader (default "Agent")
+ *   columnAt      the body width in px from which it is a column beside the
+ *                 work; under it, a sheet over the app (default 900)
+ *   children      the pane: your own component over AgentPane (the app's
+ *                 yes card, its title). Without children the dock draws an
+ *                 AgentPane from chat and the props below
+ *   chat, title, suggestions, empty, placeholder, yes, mark, onOpen, recent
+ *                 the AgentPane's own (see agent-pane)
+ *   className     the column's own layout. Never colour.
+ */
+export function AgentDock({
+  dock,
+  open: openProp,
+  onOpenChange,
+  storageKey: keyProp,
+  label = "Agent",
+  columnAt = COLUMN_AT,
+  children,
+  chat,
+  title,
+  suggestions,
+  empty,
+  placeholder,
+  yes,
+  mark,
+  onOpen,
+  recent,
+  className,
+}) {
+  const storageKey = keyProp ?? dock?.storageKey ?? "app";
+  // Without a dock from the shell the column keeps its own state (and hears
+  // openAgent); with one, the shell's hook is the one that listens.
+  const own = useAgentDock({ storageKey, listen: !dock });
+  const open = Boolean(openProp ?? dock?.open ?? own.open);
+  const setOpen = onOpenChange ?? dock?.setOpen ?? own.setOpen;
+  const asked = (dock ?? own).asked;
+  const start = (dock ?? own).start ?? null;
+  const startTaken = (dock ?? own).startTaken;
+  // A controlled dock (open + onOpenChange, no dock) is told when openAgent
+  // asks it to open.
+  const ownAsked = useRef(own.asked);
+  useEffect(() => {
+    if (ownAsked.current === own.asked) return;
+    ownAsked.current = own.asked;
+    if (!dock && openProp !== undefined) onOpenChange?.(true);
+  }, [own.asked, dock, openProp, onOpenChange]);
+
+  const asideRef = useRef(null);
+  const bodyRef = useRef(null);
+  const [body, setBody] = useState(0);
+  const [width, setWidth] = useState(null);
+  const widthRef = useRef(null);
+  const [mounted, setMounted] = useState(open);
+  const column = hasRoom(body, columnAt);
+
+  useEffect(() => {
+    if (open) setMounted(true);
+  }, [open]);
+
+  // The width this browser kept for this app.
+  useEffect(() => {
+    const w = storedWidth(readKey(dockKeys(storageKey).width));
+    widthRef.current = w;
+    setWidth(w);
+  }, [storageKey]);
+  const keepWidth = useCallback(
+    (w) => {
+      widthRef.current = w;
+      setWidth(w);
+      writeKey(dockKeys(storageKey).width, w === null ? null : String(w));
+    },
+    [storageKey],
+  );
+
+  // The body it sits beside (the frame's row), measured, never the window.
+  useEffect(() => {
+    const el = asideRef.current?.parentElement;
+    if (!el) return undefined;
+    bodyRef.current = el;
+    const measure = () => setBody(el.clientWidth);
+    measure();
+    if (typeof ResizeObserver === "undefined") return undefined;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // The member opened it: the cursor goes to the box. The pane mounts on the
+  // same render that opens the column, so the box may not exist for a frame or
+  // two: try on each frame until it does (and give up after a second). What
+  // had focus (the Ask button) is remembered, and folding the dock gives focus
+  // back to it.
+  const firstAsk = useRef(asked);
+  const opener = useRef(null);
+  useEffect(() => {
+    if (asked === firstAsk.current || !open) return undefined;
+    firstAsk.current = asked;
+    const here = document.activeElement;
+    if (here && here !== document.body && !asideRef.current?.contains(here)) opener.current = here;
+    let id = 0;
+    let tries = 0;
+    const attempt = () => {
+      const box = asideRef.current?.querySelector("textarea:not([disabled])");
+      if (box) {
+        box.focus({ preventScroll: true });
+        if (document.activeElement === box) return;
+      }
+      if (++tries < 60) id = requestAnimationFrame(attempt);
+    };
+    id = requestAnimationFrame(attempt);
+    return () => cancelAnimationFrame(id);
+  }, [asked, open]);
+  const wasOpen = useRef(open);
+  useEffect(() => {
+    const was = wasOpen.current;
+    wasOpen.current = open;
+    if (!was || open) return;
+    const back = opener.current;
+    opener.current = null;
+    const active = document.activeElement;
+    // Only when focus was inside the dock (or lost): never steal it from
+    // somewhere the member has since gone.
+    if (back && back.isConnected && (!active || active === document.body || asideRef.current?.contains(active))) back.focus({ preventScroll: true });
+  }, [open]);
+
+  // A sheet lays over the app, so Escape folds it.
+  useEffect(() => {
+    if (!open || column) return undefined;
+    const onKey = (e) => {
+      if (e.key === "Escape" && !e.defaultPrevented) setOpen(false);
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, column, setOpen]);
+
+  const bodyWidth = () => bodyRef.current?.clientWidth ?? body;
+  const onPointerDown = (e) => {
+    if (e.button !== 0) return;
+    e.preventDefault();
+    const b = bodyWidth();
+    const startWidth = asideRef.current?.offsetWidth ?? columnWidth(widthRef.current, b);
+    const startX = e.clientX;
+    try {
+      e.currentTarget.setPointerCapture(e.pointerId);
+    } catch {
+      /* a pointer the runtime does not know */
+    }
+    const onMove = (ev) => {
+      const w = dragged(startWidth, startX, ev.clientX, b);
+      widthRef.current = w;
+      setWidth(w);
+    };
+    const onUp = () => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+      window.removeEventListener("pointercancel", onUp);
+      keepWidth(widthRef.current);
+    };
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    window.addEventListener("pointercancel", onUp);
+  };
+  const onKeyDown = (e) => {
+    const b = bodyWidth();
+    const next = nudged(e.key, asideRef.current?.offsetWidth ?? columnWidth(widthRef.current, b), b);
+    if (next === undefined) return;
+    e.preventDefault();
+    keepWidth(next);
+  };
+
+  const ctx = useMemo(() => ({ close: () => setOpen(false), mode: column ? "column" : "sheet", start, taken: startTaken }), [setOpen, column, start, startTaken]);
+  const pane =
+    children ??
+    (chat ? (
+      <AgentPane chat={chat} title={title} suggestions={suggestions} empty={empty} placeholder={placeholder} yes={yes} mark={mark} onOpen={onOpen} recent={recent} />
+    ) : null);
+
+  return (
+    <AgentDockContext.Provider value={ctx}>
+      {open && column ? (
+        <div
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize the agent column"
+          aria-valuemin={MIN_W}
+          aria-valuenow={width ?? undefined}
+          title="Drag to resize · ← → to nudge · Home for a quarter"
+          tabIndex={0}
+          onPointerDown={onPointerDown}
+          onKeyDown={onKeyDown}
+          className="group relative z-10 -mx-[3px] w-1.5 shrink-0 cursor-col-resize touch-none outline-none print:hidden"
+        >
+          <span aria-hidden="true" className="absolute inset-y-0 left-[2px] right-[2px] rounded-sm transition-colors group-hover:bg-border group-focus-visible:bg-ring group-active:bg-ring motion-reduce:transition-none" />
+        </div>
+      ) : null}
+      <aside
+        ref={asideRef}
+        aria-label={label}
+        data-agent-dock={column ? "column" : "sheet"}
+        data-open={open ? "" : undefined}
+        style={column ? { width: "clamp(280px, var(--agent-dock-w, 25%), 50%)", "--agent-dock-w": width !== null ? `${width}px` : undefined } : undefined}
+        className={cx(
+          open ? "flex" : "hidden",
+          "min-h-0 min-w-0 flex-col border-l border-border bg-background text-foreground print:hidden",
+          column ? "shrink-0" : "fixed inset-y-0 right-0 z-40 w-[min(100%,26rem)] shadow-xl",
+          className,
+        )}
+      >
+        <div className="flex min-h-0 flex-1 flex-col">{mounted ? pane : null}</div>
+      </aside>
+    </AgentDockContext.Provider>
+  );
+}

package/registry/blocks/agent-dock/block.json

@@ -0,0 +1,47 @@
+{
+  "name": "agent-dock",
+  "title": "AgentDock",
+  "description": "Where an app's agent lives, as the desk's agent sidebar does: a column on the right beside the work, under the top bar, with the content reflowing beside it. A quarter of the body until the member drags the divider (never under 280 px, never over half), the width and the open state remembered in this browser per app; the divider is a separator a keyboard can move (arrows nudge, Home goes back to a quarter, End to the widest). Where the body is under 900 px (a container measure, not the window) the dock becomes a sheet laid over the app from the right, folded by Escape, and the chat does not remount on the way. It is the host only: the pane inside draws its own head (title, New chat, Chats, close) and its empty state (past chats listed, suggestions, the box); the dock tells the pane how to close. The pane stays mounted once opened, so a turn in flight and a draft survive folding. It sits in the `dock` slot of the kit's AppLayout. useAgentDock() holds the open state for the app's Ask button, remembered per app, and puts the cursor in the box when the member opens it. openAgent({ ask }) is how every \"have the agent do it\" button works (X9): it opens the dock with the agent's first line already sent in a new chat (or put in the box), so the agent asks only for what it is missing, in the chat, and no form comes first.",
+  "useWhen": "Any app that has an agent the member asks from the shell: the top bar's Ask, a chip that sends a question, a record whose Ask follows the open record. One dock per app, in the shell; the record's own pane is the same dock with a chat scoped to that record (useAgentPane({ row })), never a second column. Replaces a modal Sheet or an inspector tab as the agent's place. Not for work the member commissions from a verb and watches land (job-panel), and not for a conversation that fills a whole screen (agent-pane in a page of its own).",
+  "tags": [
+    "dock",
+    "sidebar",
+    "column",
+    "ask",
+    "chat",
+    "copilot",
+    "resize",
+    "panel",
+    "sheet",
+    "shell"
+  ],
+  "exports": [
+    "AgentDock",
+    "useAgentDock",
+    "openAgent",
+    "COLUMN_AT",
+    "DEFAULT_SHARE",
+    "MIN_W",
+    "OPEN_EVENT",
+    "STEP",
+    "carriesLine",
+    "clampWidth",
+    "columnWidth",
+    "dockKeys",
+    "dragged",
+    "hasRoom",
+    "maxWidth",
+    "nudged",
+    "openRequest",
+    "storedWidth"
+  ],
+  "files": [
+    "index.js",
+    "agent-dock.jsx",
+    "dock-model.js"
+  ],
+  "requires": [
+    "agent-pane"
+  ],
+  "offer": { "since": "0.8.1", "why": "where the app's agent lives, a column beside the work, with openAgent() for every have-the-agent-do-it button" }
+}