docs(cef:develop): typegen model I/O + finding models in ROC

plugins/cef/skills/develop/SKILL.md

@@ -27,15 +27,19 @@ lives inside that sandbox — the constraints below are hard rules, not style.
 6. **Respect the runtime constraints on every edit** — no Node built-ins, string
    literals for `@OnEvent` / `ctx.publish` / `ctx.cubby`, declared aliases only.
 
-After changing `cef.config.ts`, run `cef typegen` so `@OnEvent` / `ctx.publish`
-literals autocomplete and type their payloads. Then `cef build` to lint + bundle.
+**Run `cef typegen` after any `cef.config.ts` change** — adding/changing a
+**model**, cubby, engagement, or `eventSchemas` entry. It types `ctx.models.*`
+(both **input and output** of `infer`/`stream`), `@OnEvent`, and `ctx.publish`
+from the declared model specs + event schemas; skip it and those stay untyped.
+(Model refs come from ROC — see `references/engagements.md`.) Then `cef build`
+to lint + bundle.
 
 ## ROUTING — read the reference before you edit that layer
 
 | You are… | Read | Covers |
 |---|---|---|
 | Orienting in an unfamiliar project | [anatomy.md](./references/anatomy.md) | file layout, `defineAgent` fields, manifest/`__handlers` model, build→push→publish→deploy |
-| Writing handlers / lifecycle / multi-engagement | [engagements.md](./references/engagements.md) | `@Engagement`/`@OnEvent`/`@OnStart`/`@OnClose`, `Event<P>`, the `ctx` surface, selection decorators |
+| Writing handlers / lifecycle / multi-engagement / using models | [engagements.md](./references/engagements.md) | `@Engagement`/`@OnEvent`/`@OnStart`/`@OnClose`, `Event<P>`, the `ctx` surface, `ctx.models` (+ typegen types, ROC refs), selection knobs |
 | Adding or querying persistent state | [cubbies.md](./references/cubbies.md) | `cubbies[]` decl, SQL migration ordering, `.query`/`.exec`, alias lint |
 | Shipping a static UI | [widgets.md](./references/widgets.md) | `WidgetDecl`, self-contained dirs, `cef push` DAG, `window.WidgetRuntime` |
 | Writing tests | [testing.md](./references/testing.md) | `testAgent`, `testPlatform`, model mocks, `dispatch`/`published`, harness members |

plugins/cef/skills/develop/references/anatomy.md

@@ -85,8 +85,9 @@ preserves literal types. Key `AgentConfig` fields:
   `@Condition`/`@Priority`/`@Weight`/`@Limit`/`@Params` class decorators).
 - **`cubbies`** — `[{ alias, migrations? }]`. `alias` must match every
   `ctx.cubby("alias")` call (build lints this).
-- **`models`** — `Record<alias, modelId>`; used via `ctx.models.<alias>` (lint
-  requires declared aliases).
+- **`models`** — `Record<alias, ref>`; used via `ctx.models.<alias>` (lint
+  requires declared aliases). Copy a model's `ref` from **ROC** (no CLI lists
+  them); `cef typegen` then types each handle's input/output. See engagements.md.
 - **`params`** — `Record<name, ParamDecl>` (`type`, `default`, `min`/`max`/`enum`;
   `"modelAlias"` must enumerate `models` keys). Resolved per Job as
   `manifest defaults ⊕ deployment ⊕ engagement` and surfaced as `ctx.params`.

plugins/cef/skills/develop/references/engagements.md

@@ -99,11 +99,18 @@ it out-of-band) and `fetch` for HTTP. Do not expect `ctx.log`/`ctx.fetch`.
   (per-agent scoped SQLite-style storage; alias must be declared in `cef.config.ts`).
 - `ctx.models` → model handles keyed by manifest-declared alias. Each is a
   `ModelHandle` with `infer(input)` (single-shot) and `stream(input)` (async
-  iterable). Aliases are typed via `KnownModels` (filled by `cef typegen`):
+  iterable). `cef typegen` fetches each declared model's spec and fills
+  `KnownModels`, so **both the input and the output** of `infer`/`stream` are
+  typed (e.g. `ModelHandle<GemmaInput, GemmaOutput>`) — not just the alias.
+  Without typegen the handle falls back to an untyped `ModelHandle`, so run
+  `cef typegen` after adding a model to get correct input/output types.
   ```ts
   const reply = await ctx.models.llm.infer({ prompt: event.payload.text });
   await ctx.publish("assistant_message", { text: reply.text });
   ```
+  **Finding models:** browse the available models and copy a model's `ref` from
+  **ROC** (there's no CLI command to list them). Paste it into `models` in
+  `cef.config.ts` — `models: { llm: "<ref-from-ROC>" }` — then run `cef typegen`.
 - `ctx.publish(type, payload)` → publish an event (awaitable).
 - `ctx.settings` → frozen `ConnectionSettings` the user supplied at connect time.
 - `ctx.params` → frozen effective params (manifest ⊕ deployment ⊕ engagement,