typebulb 0.10.1 → 0.10.3

package/README.md

@@ -122,7 +122,8 @@ typebulb agent                 Start here — how to show a bulb inline or build
 typebulb skill                 Print this README as an Agent Skill on stdout
 typebulb check [file.bulb.md]  Type-check a bulb without running it
 typebulb predict [file]        Report the capability a bulb probably needs, without running it
-typebulb logs [file|pid]       Print a running bulb's captured console (-f follow, -n N tail)
+typebulb models                List AI models for tb.ai, filtered by your .env API keys
+typebulb logs [file|pid]       Print a running bulb's captured console (no arg: list running servers; -f follow, -n N tail)
 typebulb stop [file|pid]       Stop a running bulb (no arg: list this project's running servers)
 typebulb trust [file]          Remember a bulb as trusted (no arg: list trusted bulbs)
 typebulb untrust <file>        Forget a bulb's trust (back to sandboxed)
@@ -156,7 +157,9 @@ TB_AI_PROVIDER=anthropic
 TB_AI_MODEL=claude-haiku-4-5-20251001
 ```
 
-Both can be overridden per-call: `tb.ai({ provider: "gemini", model: "gemini-2.5-flash", ... })`.
+Both can be overridden per-call: `tb.ai({ provider: "gemini", model: "gemini-3.1-flash-lite", ... })`.
+
+Run `typebulb models` to list the available model ids instead of guessing one.
 
 ### Reasoning
 
@@ -233,7 +236,8 @@ To keep this skill on hand across sessions, run `npx typebulb skill` and copy it
 
 ### When Claude should output local vs embedded bulbs
 
-- **First, is anyone watching?** An embed only renders live when the agent viewer is open; with none it shows as raw text. `typebulb agent` tells you which case you're in. If no viewer is up and you want to show something inline, start it yourself — `npx typebulb agent:claude --no-open` — and share the link; don't make the user do it.
+- **First, can it even embed?** A bulb needing `tb.ai`, `tb.fs`, or `server.ts` must be **local** — embeds are client-only, so those calls fail there. The choice below is only for client-only bulbs.
+- **Is anyone watching?** An embed only renders live when the agent viewer is open; with none it shows as raw text. `typebulb agent` tells you which case you're in. If no viewer is up and you want to show something inline, start it yourself — `npx typebulb agent:claude --no-open` — and share the link; don't make the user do it.
 - **Something to see right now, in the flow of the conversation** — a chart of some numbers, a quick simulation, an illustrative widget. → **embedded**: emit it in a `bulb` block so it renders live inline.
 - **A tool worth keeping** — something to reuse, run on its own, or refine over several turns. → **local**: write a `.bulb.md` file run with `npx typebulb`. An embedded block is throwaway and can't be edited in place, so it's the wrong fit for anything iterative.
 
@@ -253,6 +257,8 @@ The agent viewer turns that block into a live, sandboxed app, with a *breakout
 
 ## Tips for Agents
 
+- **`config.json` `description`** is the bulb's SEO meta description — keep it to one or two plain sentences (~150–160 chars), or it gets truncated.
+- **The frontmatter `name:` is the bulb's title** — a few words, not a sentence — and the filename should be its slug (`name: Counter` → `counter.bulb.md`).
 - **Self-testing a local bulb** — To confirm a bulb works, run it, instrument with `tb.server.log(...)` (prints to the server's stdout, captured in the log — and works **even on a sandboxed bulb**), and read it back with `typebulb logs`. That's the loop to verify behaviour without asking the user to copy-paste console output. `tb.fs.write(...)` is handy for dumping large outputs.
 - **Mount to the container your `index.html` declares.** The corpus convention is `<div id="root"></div>` with `createRoot(document.getElementById("root")!)`.
 - **All imports at the top of `code.tsx`.** Bare imports (`react`, `d3`, `three`, …) auto-resolve from a CDN — no install step. Declare them in `config.json` `dependencies` anyway: that's what lets `npx typebulb check` fetch type defs (without it you get errors like `TS2875: react/jsx-runtime`) and pins versions.