@softize/opus 8.6.6

package/src/ui/docs/content/select.md

@@ -0,0 +1,342 @@
+## Básico
+
+Um componente para toda escolha em lista. As opções são DADO (`options`), não JSX: `{ value, label }` — o `label` é o que o campo mostra, o que a busca casa e o que o leitor de tela lê. O `id` pareia com o `htmlFor` do Label.
+
+```tsx preview col md
+const [role, setRole] = useState('')
+
+render(
+  <div className="grid gap-2">
+    <Label htmlFor="agent-role">Papel do agente</Label>
+    <Select
+      id="agent-role"
+      value={role}
+      onChange={setRole}
+      placeholder="Selecione o papel"
+      options={[
+        { value: 'designer', label: 'Designer' },
+        { value: 'developer', label: 'Developer' },
+        { value: 'reviewer', label: 'Revisor' },
+      ]}
+    />
+  </div>,
+)
+```
+
+## Com busca (searchable)
+
+`searchable` transforma o próprio campo na busca: digitou, a lista filtra embaixo (fuzzy do cmdk, casando label, hint e value). É o que resolve a **achabilidade** — a régua é essa, não performance: 200 itens sem busca é embaçado, achar é rolar até cansar.
+
+```tsx preview col md
+const [issue, setIssue] = useState('')
+
+render(
+  <div className="grid gap-2">
+    <Label htmlFor="issue">Issue da sessão</Label>
+    <Select
+      searchable
+      id="issue"
+      value={issue}
+      onChange={setIssue}
+      placeholder="Buscar issue…"
+      options={[
+        { value: '412', label: 'Ajustar microcopy do handoff', hint: 'SOF-412' },
+        { value: '418', label: 'Preview da sessão cai após deploy', hint: 'SOF-418' },
+        { value: '425', label: 'Sincronizar skills com o registry', hint: 'SOF-425' },
+      ]}
+    />
+  </div>,
+)
+```
+
+## Múltiplo (chips)
+
+`multiple` muda o contrato (`value` e `onChange` viram `string[]`): os escolhidos viram chips removíveis e a lista fica aberta pra seleção em sequência. Com a busca vazia, o topo do dropdown oferece Selecionar tudo / Limpar seleção (só no modo client — com filtro ativo ou `onSearch`, "tudo" seria ambíguo).
+
+```tsx preview col md
+const [skills, setSkills] = useState<string[]>(['clean-code'])
+
+render(
+  <div className="grid gap-2">
+    <Label htmlFor="agent-skills">Skills do agente</Label>
+    <Select
+      multiple
+      searchable
+      id="agent-skills"
+      value={skills}
+      onChange={setSkills}
+      placeholder="Adicionar skill…"
+      options={[
+        { value: 'clean-code', label: 'clean-code' },
+        { value: 'code-style', label: 'code-style' },
+        { value: 'ddd', label: 'ddd' },
+        { value: 'test', label: 'test' },
+      ]}
+    />
+  </div>,
+)
+```
+
+## Nativo (native)
+
+`native` renderiza o `<select>` do sistema (só com a seta restilizada — a nativa cola na borda e ignora o tema). Ganha o picker do próprio SO: roda de scroll no iOS, teclado do Android, zero JS. Use em **lista curta e sabida** (2–8 itens que a pessoa já conhece: Sim/Não, prioridade, ambiente). Item rico, busca ou multi não existem aqui — pra isso, o modo default.
+
+```tsx preview col md
+const [env, setEnv] = useState('preview')
+
+render(
+  <div className="grid gap-2">
+    <Label htmlFor="env">Ambiente</Label>
+    <Select
+      native
+      id="env"
+      value={env}
+      onChange={setEnv}
+      options={[
+        { value: 'dev', label: 'Dev local' },
+        { value: 'preview', label: 'Preview da sessão' },
+        { value: 'prod', label: 'Produção' },
+      ]}
+    />
+  </div>,
+)
+```
+
+## Grupos
+
+`group` na opção agrupa a lista — bloco nomeado nos dois modos (`<optgroup>` no nativo, heading no custom). Pra listas com origens distintas (membros × agentes).
+
+```tsx preview col md
+const [reviewer, setReviewer] = useState('')
+
+render(
+  <Select
+    value={reviewer}
+    onChange={setReviewer}
+    placeholder="Escolha o revisor"
+    options={[
+      { value: 'joao', label: 'João Campos', group: 'Membros' },
+      { value: 'rafa', label: 'Rafa', group: 'Membros' },
+      { value: 'developer', label: 'Developer', group: 'Agentes' },
+      { value: 'reviewer', label: 'Revisor', group: 'Agentes' },
+    ]}
+  />,
+)
+```
+
+## Busca server-side
+
+Com `onSearch` o filtro do cmdk desliga: o pai busca (debounced, ao abrir e ao digitar) e devolve `options`; `loading` mostra Buscando… enquanto o fetch corre. Implica campo buscável (não precisa repetir `searchable`).
+
+```tsx preview col md
+const ASSIGNEES = [
+  { value: 'joao', label: 'João Campos', hint: 'humano' },
+  { value: 'designer', label: 'Designer', hint: 'IA' },
+  { value: 'developer', label: 'Developer', hint: 'IA' },
+  { value: 'reviewer', label: 'Revisor', hint: 'IA' },
+]
+
+const [assignee, setAssignee] = useState('')
+const [results, setResults] = useState(ASSIGNEES)
+const [loading, setLoading] = useState(false)
+
+// Simula a busca no servidor — no app real, aqui vai o fetch.
+const searchAssignees = (query: string): void => {
+  setLoading(true)
+  setTimeout(() => {
+    setResults(ASSIGNEES.filter((a) => a.label.toLowerCase().includes(query.toLowerCase())))
+    setLoading(false)
+  }, 400)
+}
+
+render(
+  <Select
+    value={assignee}
+    onChange={setAssignee}
+    options={results}
+    onSearch={searchAssignees}
+    loading={loading}
+    searchPlaceholder="Buscar responsável…"
+  />,
+)
+```
+
+## Ícone dentro do campo
+
+`icon` põe o ícone DENTRO do controle, antes do texto (e dos chips, no multi) — identifica o campo numa barra de filtros. Ícone AO LADO do campo é o antipadrão: desalinha na quebra de linha e some no responsivo. Vale nos dois modos.
+
+```tsx preview col-start
+const [task, setTask] = useState('')
+
+render(
+  <Select
+    icon={<Ticket />}
+    value={task}
+    onChange={setTask}
+    placeholder="Vincular task"
+    options={[
+      { value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' },
+      { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
+    ]}
+  />,
+)
+```
+
+## Densidade (size)
+
+O controle segue a altura do design system: default é h-9 (a mesma do Input e do Button) e `size="sm"` dá h-8 pra barra de filtros/toolbar densa.
+
+```tsx preview col-start
+const [a, setA] = useState('gra-2')
+
+render(
+  <div className="flex items-center gap-2">
+    <Select
+      size="sm"
+      icon={<Ticket />}
+      value={a}
+      onChange={setA}
+      options={[{ value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' }]}
+    />
+    <Button size="sm" variant="outline">Filtrar</Button>
+  </div>,
+)
+```
+
+## Limpar (clearable)
+
+`clearable` põe o X no controle quando há seleção — limpa num clique (single volta a vazio, multi a `[]`), sem abrir a lista. Bom pra filtro, onde "sem valor" é um estado de uso frequente; os filtros do ActionList já vêm assim.
+
+```tsx preview col md
+function Demo() {
+  const [values, setValues] = useState(['developer', 'reviewer'])
+  return (
+    <Select
+      multiple
+      clearable
+      value={values}
+      onChange={setValues}
+      options={[
+        { value: 'developer', label: 'Developer' },
+        { value: 'reviewer', label: 'Reviewer' },
+        { value: 'designer', label: 'Designer' },
+      ]}
+      placeholder="Papéis…"
+      className="w-72"
+    />
+  )
+}
+render(<Demo />)
+```
+
+## Item rico (content)
+
+`label` é sempre string (é o que o campo mostra e a busca casa); `content` é o render RICO do item na lista — ícone, avatar, duas linhas. Assim o item pode ser elaborado sem estragar busca nem a11y.
+
+```tsx preview col md
+const [agent, setAgent] = useState('developer')
+
+render(
+  <Select
+    value={agent}
+    onChange={setAgent}
+    className="w-72"
+    options={[
+      {
+        value: 'developer',
+        label: 'Developer',
+        content: (
+          <span className="flex items-center gap-2">
+            <Bot className="size-4 text-muted-foreground" />
+            <span>
+              Developer <span className="text-muted-foreground">· implementa</span>
+            </span>
+          </span>
+        ),
+      },
+      {
+        value: 'reviewer',
+        label: 'Revisor',
+        content: (
+          <span className="flex items-center gap-2">
+            <ShieldCheck className="size-4 text-muted-foreground" />
+            <span>
+              Revisor <span className="text-muted-foreground">· contesta</span>
+            </span>
+          </span>
+        ),
+      },
+    ]}
+  />,
+)
+```
+
+## Barra do composer (variant ghost)
+
+`variant="ghost"` tira moldura e padding: o seletor discreto que vive na barra de ações do Composer/Chat (app, task, agente), à esquerda do enviar. `triggerLabel` na opção encurta o gatilho quando o rótulo da lista é longo (o título inteiro fica só na lista).
+
+```tsx preview col-start
+const [task, setTask] = useState('GB-42')
+
+render(
+  <Select
+    variant="ghost"
+    value={task}
+    onChange={setTask}
+    options={[
+      { value: '', label: 'Sem task' },
+      { value: 'GB-42', label: 'Trocar o FAB por botão no header', hint: 'GB-42', triggerLabel: 'GB-42' },
+      { value: 'GB-51', label: 'Anexo no composer de criação', hint: 'GB-51', triggerLabel: 'GB-51' },
+    ]}
+  />,
+)
+```
+
+## Ação no fim do campo (trailing)
+
+`trailing` põe uma ação custom DENTRO do controle, no fim (antes do chevron) — um botão que age sobre o valor escolhido, sem virar um irmão solto ao lado do campo. O clique no trailing **não** abre a lista (o slot para a propagação).
+
+```tsx preview col-start
+const [task, setTask] = useState('gra-2')
+
+render(
+  <Select
+    icon={<Ticket />}
+    value={task}
+    onChange={setTask}
+    className="w-72"
+    options={[
+      { value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' },
+      { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
+    ]}
+    trailing={
+      <Button variant="ghost" size="icon-xs">
+        <FileText />
+      </Button>
+    }
+  />,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `options` | `SelectOption[]` | | As opções: `{ value, label, hint?, content?, triggerLabel?, group?, disabled? }`. |
+| `value` | `string \| string[]` | | O selecionado: string no single, string[] no multiple. |
+| `onChange` | `(value: string) => void \| (value: string[]) => void` | | Chamado ao escolher (e ao remover chip, no multiple) — a assinatura segue o modo. |
+| `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, multi e ghost (o browser é quem desenha a lista). |
+| `searchable` | `boolean` | `false` | O campo vira busca: filtra a lista enquanto digita. |
+| `multiple` | `boolean` | `false` | Chips removíveis, lista que permanece aberta e Selecionar tudo. |
+| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, pra barra do composer. |
+| `placeholder` | `string` | `'Selecione…'` | Texto do campo vazio. |
+| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai pro `placeholder` se ausente. |
+| `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
+| `onSearch` | `(query: string) => void` | | Busca server-side (debounced, ao abrir e ao digitar): desliga o filtro do cmdk — o pai atualiza `options`. |
+| `loading` | `boolean` | | Mostra Buscando… enquanto o fetch corre (use com `onSearch`). |
+| `clearable` | `boolean` | `false` | X no controle quando há seleção — limpa num clique. |
+| `icon` | `React.ReactNode` | | Ícone leading DENTRO do controle (decorativo) — herda `size-4` e o tom muted. |
+| `trailing` | `React.ReactNode` | | Ação custom no FIM do controle (antes do chevron) — o clique não abre a lista. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) pra toolbar densa. |
+| `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
+| `id` | `string` | | Vai pro campo — pra parear com o `htmlFor` do Label. |

package/src/ui/docs/content/separator.md

@@ -0,0 +1,33 @@
+## Horizontal
+
+Divide blocos empilhados — ocupa a largura toda do contêiner.
+
+```tsx preview col
+<div>
+  <h4 className="text-sm font-medium">Empresa X</h4>
+  <p className="text-sm text-muted-foreground">Workspace do cliente Empresa X.</p>
+</div>
+<Separator />
+<p className="text-sm text-muted-foreground">Última sessão há 2 horas.</p>
+```
+
+## Vertical
+
+Entre itens de uma linha. O vertical herda a altura do contêiner — dê altura à linha (ex.: h-4 no flex).
+
+```tsx preview
+<div className="flex h-4 items-center gap-3 text-sm">
+  <span>2 repositórios</span>
+  <Separator orientation="vertical" />
+  <span>3 agentes</span>
+  <Separator orientation="vertical" />
+  <span>6 skills</span>
+</div>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. Vertical precisa de altura vinda do contêiner. |
+| `decorative` | `boolean` | `true` | Decorativa some da árvore de acessibilidade. Use false quando a divisão é semântica. |

package/src/ui/docs/content/sidebar.md

@@ -0,0 +1,38 @@
+## Sidebar
+
+`Sidebar` é uma coluna de chrome e navegação. Ela não escolhe a posição: entra em qualquer `Pane` de um `Split`. A mesma forma serve para a sidebar global do app e a navegação interna de Configurações.
+
+```tsx preview
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Split resizable>
+      <Pane initialSize={32} minSize={20} inset="none">
+        <Sidebar divider={false} className="w-full">
+          <PaneHeader className="px-4 py-3 text-sm font-semibold">Projeto</PaneHeader>
+          <PaneContent>
+            <SidebarNav
+              groups={[{ label: 'Design', items: [{ id: 'preview', label: 'Preview' }, { id: 'code', label: 'Código' }] }]}
+              activeId="preview"
+              onSelect={() => {}}
+            />
+          </PaneContent>
+          <PaneFooter><span className="text-xs text-muted-foreground">Configurações</span></PaneFooter>
+        </Sidebar>
+      </Pane>
+      <Pane grow inset="lg"><p className="text-sm text-muted-foreground">Conteúdo da tela.</p></Pane>
+    </Split>
+  </div>,
+)
+```
+
+## Colapso
+
+`collapsed` pertence à própria `Sidebar`; `SidebarItem` e `SidebarNav` adaptam-se automaticamente para botões `size-9` centralizados, ícones e tooltips. `PaneHeader`, `PaneContent` e `PaneFooter` são slots do pane: a aplicação mantém a identidade e ações que lhe pertencem sem atribuí-las artificialmente à sidebar. `SidebarHeader`, `SidebarContent` e `SidebarFooter` seguem como aliases deprecated durante a migração.
+
+```tsx
+<Sidebar collapsed={collapsed}>
+  <PaneHeader><MySidebarHeader onToggle={() => setCollapsed(!collapsed)} /></PaneHeader>
+  <PaneContent><SidebarNav groups={groups} activeId={active} onSelect={go} /></PaneContent>
+  <PaneFooter><UserMenu /></PaneFooter>
+</Sidebar>
+```

package/src/ui/docs/content/skeleton.md

@@ -0,0 +1,34 @@
+## Linha de lista com avatar
+
+O skeleton imita a forma do conteúdo: círculo pro avatar (rounded-full), barras com a largura aproximada do texto.
+
+```tsx preview col
+<div className="flex items-center gap-3">
+  <Skeleton className="size-10 rounded-full" />
+  <div className="space-y-2">
+    <Skeleton className="h-4 w-48" />
+    <Skeleton className="h-3 w-32" />
+  </div>
+</div>
+```
+
+## Card em carregamento
+
+O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — pra tela não pular quando os dados chegarem.
+
+```tsx preview col
+<Card>
+  <CardHeader>
+    <Skeleton className="h-5 w-40" />
+    <Skeleton className="h-4 w-56" />
+  </CardHeader>
+  <CardContent className="space-y-2">
+    <Skeleton className="h-4 w-full" />
+    <Skeleton className="h-4 w-3/4" />
+  </CardContent>
+  <CardFooter className="gap-2">
+    <Skeleton className="h-8 w-28" />
+    <Skeleton className="h-8 w-24" />
+  </CardFooter>
+</Card>
+```

package/src/ui/docs/content/slider.md

@@ -0,0 +1,64 @@
+## Básico
+
+defaultValue é um array — [n] pra um thumb. min, max e step delimitam a faixa; aqui de 0 a 100 em passos de 5.
+
+```tsx preview col
+<Slider defaultValue={[40]} min={0} max={100} step={5} />
+```
+
+## Controlado
+
+onValueChange recebe o array atualizado — leia value[0] pra um thumb. Bom pra mostrar o valor escolhido ao lado do rótulo.
+
+```tsx preview col
+const [parallelism, setParallelism] = useState([4])
+
+render(
+  <div className="grid w-full gap-3">
+    <div className="flex items-center justify-between">
+      <Label>Sessões em paralelo</Label>
+      <span className="text-sm text-muted-foreground">{parallelism[0]}</span>
+    </div>
+    <Slider value={parallelism} onValueChange={setParallelism} min={1} max={8} step={1} />
+  </div>,
+)
+```
+
+## Intervalo
+
+value com dois números rende dois thumbs e a faixa fica entre eles — o jeito de filtrar por um intervalo, como o custo estimado de uma task.
+
+```tsx preview col
+const [budget, setBudget] = useState([20, 60])
+
+render(
+  <div className="grid w-full gap-3">
+    <div className="flex items-center justify-between">
+      <Label>Custo estimado (US$)</Label>
+      <span className="text-sm text-muted-foreground">{budget[0]} – {budget[1]}</span>
+    </div>
+    <Slider value={budget} onValueChange={setBudget} min={0} max={100} step={5} />
+  </div>,
+)
+```
+
+## Desabilitado
+
+disabled esmaece o trilho e o thumb e bloqueia o arraste — o valor fica congelado no defaultValue.
+
+```tsx preview col
+<Slider defaultValue={[70]} min={0} max={100} disabled />
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` | `number[]` | | O valor no modo controlado — [n] pra um thumb, [a, b] pra um intervalo. Pareie com onValueChange. |
+| `onValueChange` | `(value: number[]) => void` | | Chamado a cada arraste, com o array atualizado. |
+| `defaultValue` | `number[]` | | Valor inicial no modo não controlado. |
+| `min` | `number` | `0` | Limite inferior da faixa. |
+| `max` | `number` | `100` | Limite superior da faixa. |
+| `step` | `number` | `1` | Incremento entre valores possíveis. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do trilho — vertical exige altura no container. |
+| `disabled` | `boolean` | `false` | Esmaece e bloqueia o arraste. |

package/src/ui/docs/content/spinner.md

@@ -0,0 +1,37 @@
+## Tamanhos
+
+Divergência da casa: o shadcn atual só tem size-4 fixo; mantivemos sm/default/lg pra cobrir botão
+(sm) e estados maiores (lg). O aria-label Carregando já vem embutido.
+
+```tsx preview
+<Spinner size="sm" />
+<Spinner />
+<Spinner size="lg" />
+```
+
+## No botão
+
+Ação em andamento: disabled + Spinner sm + verbo no gerúndio — substitui o Loader2Icon inline
+repetido.
+
+```tsx preview
+<Button disabled><Spinner size="sm" /> Publicando…</Button>
+```
+
+## Em carga de conteúdo
+
+Espera curta sem forma definida. Quando o conteúdo tem forma conhecida (lista, card), prefira
+Skeleton.
+
+```tsx preview
+<div className="flex items-center gap-2 text-sm text-muted-foreground">
+  <Spinner />
+  <span>Carregando sessões…</span>
+</div>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | O tamanho — sm pra dentro de botão, lg pra estados de página. |

package/src/ui/docs/content/split.md

@@ -0,0 +1,33 @@
+## Split & Pane
+
+`Split` é o primitive espacial da UI. A ordem dos `Pane` define esquerda→direita (ou cima→baixo); o pane não sabe onde está. Sem `resizable`, é flex simples. Com ele, a fronteira vira arrastável sem trocar o modelo do componente.
+
+```tsx preview
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Split resizable>
+      <Pane initialSize={30} minSize={20} inset="none" className="bg-muted/30">
+        <div className="p-4 text-sm">Navegação</div>
+      </Pane>
+      <Pane grow inset="lg">
+        <p className="text-sm text-muted-foreground">Conteúdo. Arraste a divisória.</p>
+      </Pane>
+    </Split>
+  </div>,
+)
+```
+
+## Inset
+
+O `Pane` traz `inset="md"` por default. Use `none` para chrome, navegação e conteúdo que já possui padding próprio; `sm` e `lg` atendem densidades comuns. `className` sempre pode ajustar o caso específico.
+
+## Rail
+
+Um rail não é uma prop especial: é só o último pane.
+
+```tsx
+<Split resizable>
+  <Pane grow inset="none"><Main /></Pane>
+  <Pane initialSize={28} minSize={20} inset="none"><Inspector /></Pane>
+</Split>
+```

package/src/ui/docs/content/storage.md

@@ -0,0 +1,69 @@
+---
+title: Armazenamento
+---
+
+# Armazenamento
+
+> **Experimental.** Superfície mínima, sem consumidor interno ainda — cresce por
+> reincidência de caso real, não por especulação.
+
+Upload, download, remoção e URL de acesso — o que backoffice precisa de arquivos
+(anexo de nota, foto de produto, contrato). O contrato é um adapter do core
+(`StorageAdapter`): a key é um **caminho lógico** (`clientes/123/contrato.pdf`) e o
+driver resolve onde ela mora.
+
+## O contrato
+
+```ts
+interface StorageAdapter {
+  put(key, data: Uint8Array, opts?: { contentType?: string }): Promise<void>
+  get(key): Promise<{ data: Uint8Array; contentType?: string } | null>
+  delete(key): Promise<void>            // idempotente
+  url(key, opts?: { expiresInSeconds?: number }): Promise<string>
+}
+```
+
+Keys passam pela mesma régua em todo driver (`normalizeKey`): relativas, sem `..`,
+sem `\` — traversal é barrado no contrato, não em cada driver.
+
+## Drivers
+
+```ts
+import { fsStorage } from '@softize/opus/storage/fs'
+import { s3Storage } from '@softize/opus/storage/s3'
+import { S3Client } from '@aws-sdk/client-s3'
+
+// Dev / single-host: arquivos sob um root local; url() exige baseUrl (o app serve o root).
+const dev = fsStorage({ root: './var/arquivos', baseUrl: 'http://localhost:5173/arquivos' })
+
+// Produção: S3 e compatíveis (MinIO, R2…). O client é seu — região/endpoint/credencial.
+const prod = s3Storage({
+  client: new S3Client({ region: 'us-east-1' }),
+  bucket: 'meu-app',
+  prefix: 'uploads',
+})
+```
+
+Os peers do S3 são **opcionais** (`@aws-sdk/client-s3`; `s3-request-presigner` pro
+`url()`): quem não usa o driver não os instala — importados sob demanda.
+
+## No runtime
+
+```ts
+const runtime = createRuntime({
+  // …server/data/auth…
+  storage: prod,
+})
+
+// No handler: ctx.storage (null quando não configurado).
+handler: async (ctx, input) => {
+  await ctx.storage!.put(`notas/${input.id}.pdf`, bytes, { contentType: 'application/pdf' })
+  return { url: await ctx.storage!.url(`notas/${input.id}.pdf`, { expiresInSeconds: 300 }) }
+}
+```
+
+## Limites (por enquanto)
+
+Bytes em memória (`Uint8Array`), sem streams — arquivo gigante ainda não é o caso;
+sem `list`, sem metadata rica. Cada um entra quando um projeto real cobrar — é a
+régua do Opus: comportamento vira peça na reincidência.