create-theokit 1.0.12 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/default/AGENTS.md

@@ -82,6 +82,19 @@ npx drizzle-kit push      # Apply schema changes (dev)
 npx drizzle-kit generate  # Generate migration files (prod)
 ```
 
+## SDK Ecosystem
+
+| Package | Purpose | Install separately? |
+|---------|---------|-------------------|
+| `theokit` | Framework (routes, SSR, client, CLI) | Already installed |
+| `@theokit/sdk` | Agent runtime (Agent.create, defineTool primitive) | Already installed |
+| `@theokit/sdk-tools` | Ready-made tools (readFile, writeFile, search, shell) | Yes — `npm install @theokit/sdk-tools` |
+| `@theokit/agents` | Decorator surface (@Agent, @Tool, @Toolbox) | Already installed |
+| `@theokit/ui` | AI chat UI components (ChatThread, ChatComposer, CodeBlock) | Yes — `npm install @theokit/ui` |
+| `@theokit/di-agent` | DI-powered agent pattern | Yes — when using DI |
+
+**Before writing custom tools, check `@theokit/sdk-tools`** — it likely has what you need.
+
 ## Don't
 
 - Don't use `any` — use Zod schemas + `z.infer<>`
@@ -89,3 +102,5 @@ npx drizzle-kit generate  # Generate migration files (prod)
 - Don't parse request body manually — use `body: z.object(...)` in defineRoute
 - Don't import from `theokit/dist/...` or `theokit/src/...` — use public exports only
 - Don't call LLM APIs directly — use @Agent + @Tool decorators
+- Don't reimplement file/search/shell tools — use `@theokit/sdk-tools`
+- Don't use `npm link` for `@theokit/ui` — causes dual-React; use tarball or npm registry

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

@@ -114,6 +114,19 @@ for await (const event of stream) {
 }
 ```
 
+## SDK Ecosystem — "you are here" map
+
+Before writing custom tools, check if they already exist:
+
+| Package | What it provides | When to use |
+|---------|-----------------|-------------|
+| `@theokit/sdk` | `Agent.create()`, `defineTool()` (primitive), `Run.stream()` | Core agent runtime — always installed |
+| `@theokit/sdk-tools` | Ready-made tools: `createReadFileTool`, `createWriteFileTool`, `createSearchTool`, etc. | **Check here FIRST** before writing custom tools for coding agents |
+| `@theokit/di-agent` | DI-powered agent with decorator injection | When using dependency injection pattern |
+| `@theokit/di` | Core DI container (`@Injectable`, `@Inject`) | When `@theokit/di-agent` needs explicit bindings |
+
+**`defineTool()` in `@theokit/sdk` is the primitive API.** For coding agents, `@theokit/sdk-tools` has batteries-included tools that wrap `defineTool()` with file system access, search, shell execution, etc. Don't reimplement what `sdk-tools` already provides.
+
 ## Rules
 
 - Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
@@ -122,11 +135,13 @@ for await (const event of stream) {
 - `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings)
 - Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch
 - Pick ONE surface per endpoint — don't mix defineAgentEndpoint with @Agent for the same route
+- Check `@theokit/sdk-tools` BEFORE writing custom tools — it may already exist
 
 ## Anti-patterns
 
 - NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent or defineAgentEndpoint
 - NEVER reimplement tool calling loop — the SDK handles it
+- NEVER reimplement file/search/shell tools — use `@theokit/sdk-tools` (readFile, writeFile, search, etc.)
 - NEVER store conversations manually — use @Memory (decorator) or SDK persistence
 - NEVER infer tool capability from method name — always provide explicit `name` + `description`
 - NEVER mix both surfaces for the same endpoint — pick manual OR decorator

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

@@ -21,13 +21,16 @@ paths:
 The published package is `@theokit/ui` (NOT `@usetheo/ui` — that was the old name).
 
 ```bash
-# Install from npm
+# Install from npm (preferred)
 npm install @theokit/ui
 
-# Or link from source (development)
-npm link ../theo-ui    # if you have the source repo
+# Or from local tarball (when using source repo)
+cd ../theo-ui && npm pack    # produces theokit-ui-X.Y.Z.tgz
+cd ../my-app && npm install ../theo-ui/theokit-ui-X.Y.Z.tgz
 ```
 
+**WARNING: NEVER use `npm link ../theo-ui` or `file:../theo-ui`.** The symlink exposes the sibling's nested `node_modules/react` (typically a different version), causing dual-React: "React Element from an older version" errors, broken hooks (`useState` null), and silent render failures. `resolve.dedupe` in Vite does NOT fix this — the pnpm structure physically has two React copies. Use tarball (`npm pack` → `npm install .tgz`) instead.
+
 ## Provider Setup (required before using any component)
 
 ```typescript
@@ -153,5 +156,6 @@ const myTheme = defineTheme({
 - NEVER build a custom markdown renderer — `ChatMessageContent` handles it (including streaming partial fences)
 - NEVER build a custom code highlighter — `CodeBlock` uses shiki (lazy-loaded)
 - NEVER import from `@usetheo/ui` — that's the deprecated package name; use `@theokit/ui`
+- NEVER use `npm link` or `file:../theo-ui` to install — causes dual-React (use tarball or npm registry)
 - NEVER install ALL peer deps — only install the peers for components you actually use
 - NEVER use components without wrapping in `TheoUIProvider` + `ThemeProvider` first