create-theokit 1.23.11 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.23.11",
+  "version": "1.24.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "repository": {

package/templates/default/README.md.tmpl

@@ -79,6 +79,24 @@ your environment.
 Deeper detail lives in [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md);
 customization and environment variables have their own pages beside it.
 
+## What is already installed
+
+Two component libraries come with this template, and the split is by **what a component is for**,
+not by how generic it looks:
+
+| You need | Import from | Examples |
+| --- | --- | --- |
+| Agent surfaces — chat, streaming, tool calls, approvals | **`@theokit/ui`** | `ChatThread`, `ChatMessage`, `ChatComposer`, `ToolCallCard`, `AgentStream` |
+| App chrome — shell, navigation, tables, forms, feedback | **`@usetheo/ui`** | `Sidebar`, `PageShell`, `DataTable`, `Select`, `FormField`, `Badge`, `EmptyState`, `Alert`, `Dialog`, `CommandPalette` |
+
+This template uses a handful of them. The rest are installed and waiting — **check before you write
+markup by hand.** A real app built on this scaffold hand-wrote around 600 lines of navigation, rows,
+filters, badges and empty states that already existed in these two packages
+(usetheokit/theokit#471).
+
+The catalogue is `node_modules/@theokit/ui/llms.txt` — written to be read by an agent, and it
+carries the routing table above in full.
+
 ## Adding a screen
 
 Routing is file-based: a screen is a folder under `app/` with a `page.tsx`.

package/templates/default/app/layout.tsx

@@ -15,13 +15,23 @@ export default function RootLayout() {
     <div className="grid h-screen w-screen grid-rows-[auto_1fr] bg-background text-foreground">
       <Header />
       {/*
+        `<main>` SCROLLS. The shell pins itself to the viewport (`h-screen`), so the document never
+        scrolls and something inside has to — and the default is here, where an ordinary page gets
+        it for free. It used to be `overflow-hidden`, which is right for the chat and wrong for
+        every other page: content below the fold was simply unreachable, with nothing to explain it
+        (usetheokit/theokit#484). A page with the unusual requirement declares it; the common one
+        should not have to.
+
+        `min-h-0` is the non-obvious half. This is a grid child, and a grid/flex child defaults to
+        `min-height: auto` — it refuses to shrink below its content, so `overflow-y-auto` alone does
+        nothing at all. Whatever you scroll, it needs both.
+
         `data-theo-scroll` marks this as a scroll container, so its offset is restored on back
         navigation (usetheokit/theokit#421). Browsers and react-router only ever restore the
-        DOCUMENT; in a shell like this one the document never scrolls, so without the marker there
-        is nothing to restore. The value is the id — add the attribute to any other element you
-        scroll, with a different value.
+        DOCUMENT, which here never scrolls, so without the marker there is nothing to restore. The
+        value is the id — add the attribute to any other element you scroll, with a different value.
       */}
-      <main data-theo-scroll="main" className="flex h-full flex-col overflow-hidden">
+      <main data-theo-scroll="main" className="min-h-0 overflow-y-auto">
         <Outlet />
       </main>
     </div>

package/templates/default/app/page.tsx

@@ -39,21 +39,31 @@ export default function Page() {
   return (
     <>
       <Metadata title="TheoKit agent" description="Chat with your TheoKit agent." />
-      <ChatPanel
-        thread={thread}
-        isStreaming={isStreaming}
-        onlyGreeting={onlyGreeting}
-        onStarter={handleSubmit}
-      />
-      <Composer
-        value={composerValue}
-        onValueChange={setComposerValue}
-        onSubmit={handleSubmit}
-        running={isStreaming}
-        hasError={hasError}
-        error={error}
-        onNewChat={newChat}
-      />
+      {/*
+        The chat is the page that does NOT want the shell's scroll: the log scrolls inside itself
+        and the composer stays pinned to the bottom, which `overflow-hidden` is what produces. So it
+        declares that here rather than imposing it on every other page from the layout (#484).
+
+        `h-full` fills the routed slot; `min-h-0` lets this box shrink below its content so the
+        child's own scroll works — the same pair the layout comment describes.
+      */}
+      <div className="flex h-full min-h-0 flex-col overflow-hidden">
+        <ChatPanel
+          thread={thread}
+          isStreaming={isStreaming}
+          onlyGreeting={onlyGreeting}
+          onStarter={handleSubmit}
+        />
+        <Composer
+          value={composerValue}
+          onValueChange={setComposerValue}
+          onSubmit={handleSubmit}
+          running={isStreaming}
+          hasError={hasError}
+          error={error}
+          onNewChat={newChat}
+        />
+      </div>
     </>
   )
 }

package/templates/default/dot-claude/skills/theokit-frontend/SKILL.md

@@ -25,17 +25,21 @@ paths:
 ```typescript
 import { theoFetch } from 'theokit/client'
 
-// Typed fetch — params and response inferred from server routes
+// The URL is used literally — build it yourself for a dynamic route.
 const tasks = await theoFetch('/api/tasks')
-const task = await theoFetch('/api/tasks/:id', { params: { id: 1 } })
+const task = await theoFetch(`/api/tasks/${id}`)
 
-// POST with body
+// POST with body. `method` is REQUIRED when the route declares one.
 const created = await theoFetch('/api/tasks', {
   method: 'POST',
   body: { title: 'New task' },
 })
 ```
 
+`theoFetch` has **no `params` option.** Its options are `RequestInit` minus `body`/`method`, plus a
+conditional `query` and `body` — nothing interpolates a `:id` segment for you. Reach for the
+generated client below when you want that; it is the half that knows your route tree.
+
 ## App Client (proxy-based)
 
 ```typescript
@@ -43,11 +47,22 @@ import { createAppClient } from 'theokit/client'
 
 const client = createAppClient()
 
-const tasks = await client.tasks.GET()
-const task = await client.tasks[':id'].GET({ params: { id: 1 } })
-const created = await client.tasks.POST({ body: { title: 'New' } })
+const tasks = await client.tasks.get()
+const task = await client.tasks.id.get({ params: { id: '42' } }) // → GET /api/tasks/42
+const created = await client.tasks.post({ body: { title: 'New' } })
 ```
 
+Three details the generator decides for you, and each is easy to guess wrong:
+
+- **methods are lowercase** — `get`, `post`; the export in your route file stays `GET`
+- **a dynamic segment loses its colon** — `app/tasks/[id]` is reached as `client.tasks.id`, not
+  `client.tasks[':id']`
+- **`params` values are strings** — `{ id: '42' }`; a URL segment has no other type
+
+Segments are otherwise kept **literal**, so a hyphenated route needs bracket access:
+`client['agents-config'].get()`. The client mirrors your URLs rather than prettifying them — a
+camelCased key once produced a request to a path no route served.
+
 ## Agent Streaming
 
 Two client APIs from `theokit/client`:

package/templates/default/dot-claude/skills/theokit-ui/SKILL.md

@@ -16,9 +16,25 @@ paths:
 
 `@theokit/ui` is an optional peer dependency. If installed, it provides ready-made AI components for chat + coding-agent surfaces (chat thread, agent events, tool calls, diff viewer, build logs), plus theming. **Never build custom equivalents** of components it provides. Generic primitives (Button, Input, Card, CodeBlock, PageShell, Sidebar, Avatar, Alert, etc.) live in `@usetheo/ui`, which `@theokit/ui` depends on — import those from `@usetheo/ui`.
 
+## Read the catalogue before writing markup
+
+`@theokit/ui` ships **`llms.txt`** — a file written for an agent to read, at
+`node_modules/@theokit/ui/llms.txt`. It lists every component with its purpose and, in a
+**"Which package has what"** table, routes each need to the right package. Read it before building a
+sidebar, a table, a select, a badge or an empty state by hand.
+
+That is not a style preference. A real app built on this scaffold hand-wrote ~600 lines of markup —
+navigation, queue rows, filters, status badges, empty states, a composer — and **every one of them
+already existed** in the two packages the scaffold had installed (usetheokit/theokit#471). The
+components were there; nothing pointed at them.
+
+`@usetheo/ui` has no `llms.txt`; its surface is in its own README and its type definitions.
+
 ## Package Identity
 
-`@theokit/ui` (AI-native, currently `1.0.0`) provides the AI-agent-surface components. Its generic foundation was split into `@usetheo/ui` in the 2026-07-03 AI-exclusive pivot; `@theokit/ui` depends on `@usetheo/ui`, so installing `@theokit/ui` pulls the foundation transitively.
+`@theokit/ui` provides the AI-agent-surface components. (The version this project uses is in
+`package.json`; a number written here goes stale the first time anyone upgrades, and this one
+said `1.0.0` while npm served `1.5.1`.) Its generic foundation was split into `@usetheo/ui` in the 2026-07-03 AI-exclusive pivot; `@theokit/ui` depends on `@usetheo/ui`, so installing `@theokit/ui` pulls the foundation transitively.
 
 ```bash
 # Install from npm (preferred)

package/templates/default/package.json.tmpl

@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.52.0",
+    "theokit": "^0.55.0",
     "@theokit/agents": "^10.1.0",
     "@theokit/sdk": "^4.52.1",
     "@theokit/ui": "^1.1.0",

package/templates/default/tsconfig.json

@@ -19,6 +19,7 @@
     "server/**/*.ts",
     "agents/**/*.ts",
     "shared/**/*.ts",
+    ".theokit/**/*.d.ts",
     "types/**/*.d.ts"
   ]
 }