@roku-sdk/ai 0.0.0-stage → 2.18.0

package/skills/cli-dev-loop/SKILL.md

@@ -0,0 +1,217 @@
+# CLI Dev Loop
+
+## Overview
+
+This is the build-install-drive-observe loop run from a shell rather than from an agent session:
+the same operations the MCP tools expose, reached through `rk` directly, which is what a script
+or a CI job needs.
+
+**The normal way to get a channel onto a device is `rk dev`.** With no flags it builds and
+sideloads a debug build in one step; everything else in this loop is a variation on it. Reach for
+`rk dev` first; do not hand-assemble a package or improvise an install path.
+
+Two things about the loop surprise people. The two build commands write to different
+directories and the install command reads only one of them, so the obvious pairing installs the
+wrong thing. And most commands run in process while a few refuse without a server, which turns a
+working local command into a failing CI step.
+
+## When to Use
+
+- a shell script or CI job that has to build an RSG SDK TypeScript app and get it onto a Roku
+- an install that keeps landing an older build than the one just produced
+- sending remote keys, capturing the screen or reading the node tree with no agent involved
+- collecting what the app printed on the device, from a job nobody is watching
+- turning a crash stack back into TypeScript after the run is over
+- a flag one of the two build commands accepts and the other rejects
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| An agent session whose Roku tools already answer | The `mcp-ai-dev-loop` skill | Same loop, different surface: those tools carry their own arguments and their own failure modes |
+| A session with no Roku tools in it at all | The `mcp-setup` skill | Nothing here is the reason an editor lists no tools |
+| What the running app *costs* — dropped frames, slow start, memory | The `app-performance` skill | These commands report what the app did, not what it spent doing it |
+| Registering a Roku, its password, or which one is targeted | The `device-management` skill | Everything here assumes a target already resolves |
+| Signing an app, publishing it, or clearing what is installed | The `app-packaging` skill | Those act on an artifact once this loop has produced one |
+| Writing the app's code, or the project's own configuration | The `sdk-components` and `project-setup` skills | This loop starts once there is something to run |
+
+## Read the reference first for these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| Collecting device logs from a script, or decoding a crash stack outside an agent session | `references/logs-and-crashes.md` |
+
+Both are commands whose shell spelling has options the tool surface does not, and `rk logs` is
+one of the few things here that will not run without a server.
+
+## BrightScript-only channels
+
+A traditional BrightScript/XML app can set `app.brsOnly: true` in
+`roku-config.cjs`. Run `rk build --local` or `rk dev --local`: no tsconfig,
+JavaScript bundle or Hermes bytecode is needed, and stale `ts_path` entries
+are removed. `--no-write-ts-path` alone does not skip bundling. Keep `--local`
+for build/dev until server project discovery supports non-TS configs. Sideload
+and package defaults discover `.ts`, `.cjs`, `.js` and `.mjs`. `entryPoint` is
+optional with `brsOnly`, and `--compile-ts` warns that it is ignored. Pipeline
+plugins anchored to TS build slots are unsupported. Root assets are limited to the native
+channel directories; use `app.staticAssetsDir` for a separate curated channel
+tree. The output/install pairing below is unchanged.
+
+## Quick Reference
+
+| Goal | Do |
+|---|---|
+| **Put a channel on a device (the normal sideload path)** | **`rk dev` — builds and sideloads in one step** |
+| Production build (artifact only) | `rk build` — writes `dist-build` |
+| Dev build and install together | `rk dev` — writes `dist-dev` |
+| Install something already built | `rk dev --no-build` — reads `<out-dir>/pkg-dir`, defaulting to `dist-dev` |
+| Dev build with no device on the network | `rk dev --no-sideload` — writes `dist-dev`, installs nothing |
+| Press one key | `rk ecp keypress <Key>` |
+| Press a whole path | `rk keysequence Down Down Select` |
+| Capture the screen | `rk ecp capture-screen -o shot.png` |
+| Read the live node tree | `rk ecp query/app-ui --json` |
+| Hand the app launch parameters | `rk ecp input --json '<json>'` |
+| Device logs | `rk logs start`, then `get`, `search` or `tail` — needs a server |
+| A crash stack back to TypeScript | `rk decode-stack` |
+| Fresh-checkout `type-check` / XML JSX types without a build | `rk gen-types` — writes gitignored `.xml.d.ts`; app scripts usually run it before `tsc` |
+| Frames from a Dynamic Component Library left unresolved | add `--dcl-dir <libName>=<dir>` — one per library |
+| Start a stopped cloud device and build while it boots | `rk dev --start --device rce:<name>` — then `rk device stop rce:<name>` |
+
+## Instructions
+
+1. **The two build commands write to different directories, and a no-build install reads only
+   one.** `rk build` writes `dist-build`; `rk dev` writes `dist-dev`; `rk dev --no-build` reads
+   `<out-dir>/pkg-dir`, which defaults to `dist-dev`. So `rk build` followed by a bare
+   `rk dev --no-build` still installs out of `dist-dev`. It no longer does so silently: when a
+   newer `pkg-dir` sits in the other directory, the command says which artifact it is installing,
+   which one is newer, and the flag that switches — and when the directory is empty it names a
+   command that can actually create it. Pass `--out-dir` matching the build, or let `rk dev` do
+   both steps.
+
+   A project that sets `outDir` in `roku-config.ts` sidesteps this entirely: the install path now
+   loads project config the way `rk build` and `rk dev` do, so both halves agree by construction.
+   An `outDir` that came from config or a flag is treated as deliberate and draws no warning.
+
+2. **One command puts an app on a box: `rk dev`.** With no flags it builds and installs; with
+   `--no-build` it installs what already exists. There is no `rk deploy`, no `rk install` and no
+   `rk push` — the CLI rejects an unknown command rather than guessing, so a script written
+   against a remembered name fails on its first line.
+
+   Two older spellings still work and print the replacement on stderr: `rk start-dev` is now
+   `rk dev`, and the top-level `rk sideload` is now `rk dev --no-build`. Both are deprecated and
+   will be removed; `rk sideload`'s own options are unchanged in the meantime.
+
+   `--no-build` rejects every option that only shapes a build — `--watch`, `--debug`,
+   `--inspect`, `--inspect-persist`, `--drop-console`, `--drop-debugger`, `--solid-dev-mode`,
+   `--no-write-ts-path`, `--no-typecheck`, `--build-type` and the `--perfetto-*` set —
+   rather than accepting and ignoring them. Device targeting (`--device`, `--host`, `--password`,
+   `--dap-debug`) and launch options (`--launch-params`, `--no-launch`, `--console`) still apply.
+
+   `--no-sideload` is the inverse: it builds and stops before the sideload, so it rejects the
+   device-facing set instead (`--device`, `--host`, `--password`, `--dap-debug`,
+   `--launch-params`, `--no-launch`, `--console`, `--auto-console-close`) and keeps every build
+   option, `--watch` included. The two are opposites and cannot be combined.
+
+3. **A dev build that needs no Roku at all is `rk dev --no-sideload`.** This is the one worth
+   knowing for CI: plain `rk dev` resolves a device *before* it builds and exits non-zero when
+   none is active and no password is stored, so a job that only wants to prove the dev bundle
+   compiles fails on infrastructure it does not need. `--no-sideload` never reaches that step.
+   Output still lands in `dist-dev` unless `--out-dir` moves it, and the artifact is what a
+   normal `rk dev` would have installed. For a *production* package it is still `rk build`.
+   The other way round, a build that compiles but never reaches the box fails the step: without
+   `--watch`, `rk dev` exits 1 with `SIDELOAD_FAILED` when the install failed, and with
+   `LAUNCH_FAILED` when the app installed but did not launch — the box then holds the new build,
+   and `rk dev --no-build` retries without rebuilding.
+
+4. **A few commands need a server; most do not.** `build`, `dev`, `device`, `package`,
+   `dcl` and `perfetto` try a running server first and fall back to an in-process
+   path, so they work either way; `--local` skips the discovery and is accepted by exactly those
+   six. `rk logs` and `rk cdp` have no in-process path and refuse when no server is running,
+   which is why a log step that works on a laptop with an editor open fails in CI. Start
+   `rk server` in the job first. The one exception is a cloud device's firmware log,
+   `rk logs tail --source firmware`, which runs in process.
+
+5. **Flags do not carry between the two build commands.** `--metafile` belongs to `rk build`
+   alone. `--watch` is not compatible with `--archive`, and `--output`, `--bump-minor` and
+   `--bump-build` mean nothing without it. Both `rk build` and `rk dev` accept `--drop-console` and `--drop-debugger`.
+
+6. **`--inspect-persist` outlives the run that set it.** Every later launch waits for a debugger
+   until the app is reinstalled *without* the flag, so a box left in that state looks hung. It
+   also needs firmware 16.0 or later; on anything earlier the field is ignored during sideload
+   and nothing persists.
+
+7. **`--auto-console-close` is turned off unless `--console` is set.** Nothing warns about it —
+   the flag is simply cleared, so on its own it has no effect at all.
+
+8. **`ecp input --json` takes a JSON string, not a boolean.** Almost everywhere else in the CLI
+   `--json` is a switch that changes the output format; on this one subcommand it carries the
+   payload.
+
+9. **Key arguments take the wire name, not the runtime one.** `Select` (not `OK`), `Rev` (not
+   `rewind`), `Fwd` (not `fastforward`), `Info` (not `options`). The two vocabularies are
+   inverted for exactly these four: the name a script passes to `rk ecp` is the enum member,
+   while the string the firmware delivers to `onKey` is the other one. A key is validated
+   before anything is sent, so a wrong name fails the command outright rather than pressing
+   nothing.
+
+11. **A Roku Cloud Emulator device is billed while it runs, and a job has to stop what it
+   starts.** Nothing in the loop starts a stopped one on its
+   own: every command that needs it fails with `RCE_DEVICE_NOT_RUNNING` until `rk device start` or
+   `rk dev --start` does. Plain `rk dev --start` leaves the device running when it exits — only
+   with `--watch`, or `--console` without `--auto-console-close`, does it stop the device on the
+   way out — so end the job with
+   `rk device stop`, from a `trap` so a failed step still reaches it. A run this machine did not
+   start asks for confirmation before stopping, and refuses without `--yes` when there is no
+   terminal to ask on. The run is also capped by its maximum runtime — `--max-runtime` on
+   `rk dev --start` or `rk device start`, else the registration's, else an hour — but billing can
+   outlast the cap by minutes. In CI give the
+   job its token through `RK_RCE_TOKEN`. Interrupted while still holding a device they started,
+   `rk dev` and `rk device start` stop it and exit 130 (143 on `SIGTERM`), so a step the runner
+   cancelled does not read as an ordinary failure.
+   The device and its registration are the `device-management` skill's subject.
+
+## Example
+
+A CI step that builds, installs the artifact it just built, drives the app to a known screen and
+captures evidence — with the server started because the log step needs one.
+
+```bash
+rk server start --daemon
+
+rk build --out-dir dist-ci
+rk dev --no-build --out-dir dist-ci --device ci-box
+
+rk logs start --device ci-box
+rk keysequence Down Down Select --device ci-box
+rk ecp capture-screen -o evidence.png --device ci-box
+rk logs get --lines 500 --output run.log --device ci-box
+```
+
+Both `--out-dir` values have to agree. Dropping it from just the install line is the failure in
+instruction 1: it would install from `dist-dev`, which this job never wrote. That case now fails
+with an error naming `dist-ci` as the directory that does hold a `pkg-dir`, rather than
+succeeding against a stale one.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The device runs an older build after a green build step | The install read `dist-dev` while `build` wrote `dist-build` | Give both the same `--out-dir`, or use `rk dev`. The install now warns when a newer build sits elsewhere |
+| A script fails on its very first command | It was written against a `deploy` subcommand that does not exist | `rk dev` to build and install, `rk dev --no-build` to install |
+| `[deprecated]` on stderr from a working command | `rk start-dev` and top-level `rk sideload` are aliases now | `rk dev` and `rk dev --no-build` |
+| The log command works locally and refuses in CI | `rk logs` is server-mode only | `rk server start --daemon` earlier in the job |
+| `--metafile` rejected | It belongs to `rk build` | Move the analysis to the production build |
+| `--watch` and `--package` together do nothing sensible | They are not compatible | Watch while developing, package when releasing |
+| A build flag rejected next to `--no-build` | There is no build for it to shape | Drop the flag, or drop `--no-build` to build too |
+| A CI job that only compiles fails on "no active device" | Plain `rk dev` resolves a device before it builds | `rk dev --no-sideload` — it contacts nothing |
+| `--host` or `--console` rejected next to `--no-sideload` | No device is contacted, so they would be ignored | Drop the flag, or drop `--no-sideload` to install too |
+| Every launch hangs waiting for a debugger | `--inspect-persist` is still set on the box | Reinstall without the flag |
+| `--inspect-persist` appears to do nothing | Firmware is older than 16.0 | Nothing persists there; use `--inspect` per run |
+| `--auto-console-close` has no effect | It is cleared unless `--console` is set | Pass `--console` as well |
+| `ecp input --json` rejects a bare `true` | Here the option carries a JSON string | Pass the payload, quoted |
+| The app's own frames decode but a Dynamic Component Library's do not | A DCL is built separately, so its maps are not under the app's build directory | `--dcl-dir <libName>=<dir>`, naming the library — a bare path is rejected |
+| `rk dev` fails with `LAUNCH_FAILED` after a green build | The app installed, but launching it failed; the reason is printed above the error | Fix what the reason names, then `rk dev --no-build` to install and launch the same build without rebuilding |
+| A finished CI job left a cloud device running, and billing | `rk dev --start` stops it only while `--watch`, or `--console` without `--auto-console-close`, keeps it running | `trap 'rk device stop rce:<name> --yes' EXIT` before the start |
+| `rk ecp capture-screen` fails with `SCREENSHOT_NOT_OK` on a cloud or secure retail device | It captures through the installer, which works only while the sideloaded app is in front | Install or relaunch the app, then capture; `Home` breaks it as well |
+| `rk ecp capture-screen` on a LAN device fails with `ECP_ENDPOINT_NOT_FOUND`, naming an auth token | A secure device, every retail Roku among them, serves no ECP capture without a Roku-issued token, and no developer password was at hand for the installer fallback | `rk device update <device> --password <password>` once, then capture again |
+| Every capture after some point in a key sequence shows the wrong thing, or the same thing | `Home` was sent expecting the app's own home screen — the remote's `Home` exits to the Roku home screen, and every capture after it is of that | Move within the app with `Back`; install again to relaunch one that was exited |

package/skills/cli-dev-loop/references/logs-and-crashes.md

@@ -0,0 +1,114 @@
+# Logs and crashes from a shell
+
+What a device printed, and what a crash stack means, reached through `rk` rather than through an
+agent's tools. The reasoning about crashes — which route a stack arrives by, why a bytecode frame
+cannot be read directly, and when exception tagging is needed — belongs to the `mcp-ai-dev-loop`
+skill's `crash-and-console.md` and is not repeated here. This page is the shell surface: which
+command, which option, and what only exists here.
+
+## `rk logs` needs a server
+
+`rk logs` is server-mode only. Every other command in this loop runs in process, so a log step is
+the one that works on a laptop with an editor open and fails in a CI job that never started a
+server. Start one first:
+
+```bash
+rk server start --daemon
+```
+
+Collection is a session, not a stream you attach to. Nothing is buffered until `start` runs, so a
+job that reproduces a fault and *then* asks for lines gets nothing.
+
+| Subcommand | What it is for |
+|---|---|
+| `start` | Begin buffering. `--buffer-size <lines>` sizes the circular buffer |
+| `list` | Sessions that exist. `--verbose` adds metrics |
+| `get` | Pull the last N lines. `--lines`, `--output <file>`, `--append`, `--format <txt\|json>` |
+| `search` | Query the buffer for terms. `--case-sensitive` |
+| `tail` | Follow in real time. `--prefix` stamps each line with the time and the device |
+| `stop` | End one session, or every session with `--all` |
+| `ports` | The log ports the CLI knows about |
+
+Nothing enforces which subcommand an option belongs to: one allow-list covers `rk logs` as a
+whole, so `--lines` passed to `start` parses fine and is then ignored rather than rejected.
+`--lines`, `--output`, `--append` and `--format` act on `get`, `--case-sensitive` on `search`,
+`--all` on `stop`, `--prefix` on `tail`, `--buffer-size` on `start` and `--verbose` on `list`.
+`--port` overrides the device's log port, which defaults to 8085.
+
+One exception needs no server: on a Roku Cloud Emulator device, `rk logs tail --source firmware
+--device rce:<name>` streams the device's firmware log in process — system output, not the app's
+console, which still comes from a server session. It accepts only `--device` and `--from-start`,
+and rejects anything else rather than ignoring it.
+
+Writing to a file is `get --output <file>`, not a shell redirect: `--append` then adds to it
+across several calls in the same job instead of truncating.
+
+## `rk decode-stack`, and what the flags are called
+
+The same decode the tool surface performs, with the parameters spelled as CLI options:
+
+| Tool parameter | CLI option |
+|---|---|
+| `stackTrace` | the input — `--file <path>`, or piped in with `--stream` |
+| `buildDir` | `--build-dir`, `-b` |
+| `sha` | `--sha` |
+| `context` | `--context`, `-c` |
+| `dclDirs` | `--dcl-dir` |
+
+The input has two shell spellings the tool parameter does not, both standing in for `stackTrace`:
+
+- `--stream` reads the trace from standard input line by line, so a live log can be piped straight
+  in without landing it somewhere first.
+- `--file <path>` reads it from a file, which is the pairing for `rk logs get --output`.
+
+Three options have no counterpart in the tool surface at all, and they are what make the command
+usable from a script rather than a session:
+
+- `--output <path>`, `-o` writes the decoded result to a file instead of the terminal. It also
+  switches the format to `plain` unless `--format` or `--json` was passed too, so a job that wants
+  JSON in the file has to ask for it explicitly.
+- `--format` and `--json` choose the shape of that result, so a job can parse it.
+- `--timeout`, `-t` bounds the wait for a trace on standard input and nothing else — it defaults
+  to 30s, and with `--file` or `--stream` it is a no-op that warns on stderr. It is not a cap on
+  how long the decode itself may take.
+
+Two options validate their input rather than accepting anything:
+
+- `--sha` must be a hexadecimal string of at least 8 characters. A shorter or non-hex value is
+  rejected outright, which is the good case — see the warning below for the bad one.
+- `--context` must be a non-negative integer no greater than 50.
+
+`--dcl-dir` is the option to reach for when frames name a Dynamic Component Library instead of
+`index`: it points the decoder at that library's own build output, which its separate build left
+outside the app's. Its value is not a bare path but `libName=/path/to/dir`, and a value with no
+`=` in it is rejected saying so; repeat the option once per library. A library whose frames stay
+unresolved after the option is passed is usually a `libName` that does not match the one the frames
+name, rather than a wrong path.
+
+## The failure that looks like success
+
+A `--sha` naming a build directory that is not there does not fail. The decoder falls back to
+detecting a build automatically and resolves against whichever one is newest on disk, so the
+result is confident, complete, and about the wrong code. In a CI job that rebuilds between the
+crash and the decode, this is the likely outcome rather than an unlikely one.
+
+Two habits avoid it: decode before rebuilding, and treat a decoded frame that does not match the
+code you believe ran as a suspect `--sha` before suspecting the frame.
+
+## The pairing a job actually uses
+
+```bash
+rk server start --daemon
+rk logs start --device ci-box
+
+# ... run whatever reproduces the fault ...
+
+rk logs get --lines 2000 --output device.log --device ci-box
+rk logs stop --all
+rk decode-stack --file device.log --build-dir dist-ci/bundle --output decoded.txt
+```
+
+`--build-dir` is not optional in a monorepo. `decode-stack` never goes through the server, so both
+the automatic build detection and a relative `--build-dir` are anchored at the directory the
+command is run from — a job that runs it from the repo root while the app builds into a
+subdirectory reports no source map for every frame until it is given.

package/skills/cpu-and-heap-profiling/SKILL.md

@@ -0,0 +1,108 @@
+# CPU and Heap Profiling
+
+## Overview
+
+The server's CDP profiler answers "which JavaScript function is burning the time" and "what is
+holding memory" against the running app, and writes the result to a file you then read. It rides
+on a debug session, so the loop is fixed: create the session, drive the app to the state worth
+measuring, start a capture, drive the interaction, stop it, read the file. A CPU capture only
+names functions on an unminified build, which is the precondition to settle before recording.
+
+## When to Use
+
+- a screen, key press or list that is slow and the question is which TypeScript function is hot
+- JS memory that grows and the question is what is retaining it
+- comparing a `.cpuprofile`, `.heapprofile` or `.heapsnapshot` before and after a change
+- profiling while also evaluating expressions in the same app (`cdp_eval`)
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Frames dropped, a transition janks, the render thread is the suspect | The `app-performance` skill | A Perfetto trace shows the render and transaction threads; a CPU profile only sees JavaScript |
+| Only total and used heap bytes are wanted, or whether they climb the longer the app runs | `cdp_heap_usage` in `app-performance` | A capture is heavier than the question; read the size first, and capture only once the question becomes what holds it |
+| The app crashed and there is a stack | The `mcp-ai-dev-loop` skill | Crashes are decoded, not profiled |
+| No profiling tools in the session | The `mcp-setup` skill | These tools exist only against a running `rk server` |
+| No agent session, a shell script or CI job | Nothing here drives it from a shell | The tools are MCP and REST; the loop below is what a script would have to reproduce |
+
+## Quick Reference
+
+| Question | Call | Gives |
+|---|---|---|
+| Open the session | `cdp_session_create { root }` | Builds and sideloads a debug build, connects |
+| Which functions are hot | `cdp_profile_start`, then `cdp_profile_stop` | A `.cpuprofile` file |
+| Profile the next N ms in one call | `cdp_profile_start { durationMs }` | The server stops and writes it; no stop call |
+| What retains memory right now | `cdp_heap_snapshot` | A `.heapsnapshot`, blocks until written |
+| Which call sites hold allocations | `cdp_heap_sampling_start`, then `cdp_heap_sampling_stop` | A `.heapprofile` |
+| Release the device | `cdp_session_end` | One session per device |
+
+Every response is metadata (`filePath`, byte and node counts, a `captureId`), never the profile.
+Read the file at `filePath`. Steps 4 and 5 below, and the shape of each file, are in
+`references/reading-profiles.md`: read it before summarising a profile, because the two
+mistakes that make one wrong — reading self time as total time, and reading a minified
+build — both look like a finished answer.
+
+## Instructions
+
+1. **Profile a debug build.** `cdp_session_create` builds in debug mode, which is unminified
+   JavaScript, so frames keep their function names; no config change is needed. From a terminal
+   the same build is `rk dev --debug`. If every frame is a short renamed symbol, the profile came
+   from a minified build (`rk dev --release`, or `--minify`): rebuild with `--debug`. Profile
+   timings from a debug build have no Hermes bytecode: use them to rank functions against each
+   other, not to quote milliseconds.
+2. **Create the session.** `cdp_session_create { root }` with the absolute app root. It needs a
+   running `rk server`. A second session for the same device is refused until `cdp_session_end`.
+3. **Drive the app to the starting state before recording.** Use `ecp`, `capture_screen`, or
+   `cdp_eval` to reach the screen, so the capture holds the interaction and not the navigation to it.
+4. **Start, drive, stop.** `cdp_profile_start`, perform the interaction, `cdp_profile_stop`.
+   Keep the window to the interaction; a long capture buries it. For "the next N ms", pass
+   `durationMs` and skip the stop call: the file appears at the `filePath` the start returned,
+   and a later `cdp_profile_stop` answers `CAPTURE_NOT_ACTIVE`.
+5. **Read the file, then answer.** Open `filePath`, rank functions by self time, and map the
+   top ones back to source with `cdp_source_grep` or `cdp_source_get`.
+6. **Change one thing, capture again.** One profile is not evidence: the sampler is a few
+   hundred hertz at best, so a function that shows once may be noise. Repeat the same
+   interaction and compare what repeats.
+7. **End the session and redeploy.** `cdp_session_end`, then redeploy normally so the next
+   person does not measure your debug build.
+
+### Profiling and evaluating in one session
+
+`cdp_eval`, `cdp_profile_*` and `cdp_heap_*` interleave freely on one session: eval, profile,
+eval again needs no reconnect. The exception is any `cdp_debugger_*` tool, including arming a
+breakpoint: after the first one, `cdp_eval` is disabled for that connection for good, while the
+profiler tools keep working. So a session that already ran a debugger tool cannot combine
+profiling with evaluation. `cdp_session_end`, then `cdp_session_create` a fresh one, and do
+the eval and profile work in it without touching a debugger tool.
+
+## Example
+
+Profiling a slow screen transition, then checking the heap:
+
+```text
+# cdp_session_create builds a debug (unminified) build; no config change needed
+cdp_session_create   { root }                        -> sessionId
+ecp                  { keypress: Select }             -- reach the screen
+cdp_profile_start    { samplingHz: 200 }              -> captureId, filePath
+ecp                  { keypress: Right }              -- the slow transition
+cdp_profile_stop     {}                               -> filePath, nodeCount, sampleCount, durationMs
+cdp_heap_snapshot    {}                               -> filePath, bytes, nodeCount, edgeCount
+cdp_session_end      {}
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Frames are single letters or `(anonymous)` | The build was minified (`--release` or `--minify`) | Rebuild with `--debug` (or a fresh `cdp_session_create`), capture again |
+| `NO_CDP_SESSION` | Session missing, or created with `rk cdp` rather than `cdp_session_create` | `cdp_session_create`; the aliased tools cannot see a REST-created one |
+| `CAPTURE_ALREADY_ACTIVE` / `SAMPLING_ALREADY_ACTIVE` | A capture is open on this session | Stop it, or pass its `captureId` to the stop call |
+| `CAPTURE_NOT_ACTIVE` on stop | `durationMs` already stopped it | Read the file the start returned |
+| `cdp_eval` refused after profiling worked | A `cdp_debugger_*` tool ran on this session | Fresh session, above |
+| `samplingHz` made no difference | Older firmware may ignore it and sample at its own rate | Compare captures at the same rate; do not tune it |
+| Heap sampling profile is nearly empty | It shows only allocations still live at stop; the collector ran | Stop earlier, or use `cdp_heap_snapshot` for retained memory |
+| `SNAPSHOT_TIMEOUT` | A large heap took over two minutes | Retry once idle; an immediate retry can come back incomplete |
+| Timings look worse than users report | Debug build, no bytecode | Rank, don't quote; confirm with a normal build's trace |
+
+The tool descriptions from the server's `tools/list` carry each parameter and response field;
+enumerate them rather than trusting this table.

package/skills/cpu-and-heap-profiling/references/reading-profiles.md

@@ -0,0 +1,52 @@
+# Reading a profile file
+
+The tools write Chrome DevTools formats verbatim, so each file also opens in Chrome DevTools
+(Performance for `.cpuprofile`, Memory for `.heapprofile` and `.heapsnapshot`). An agent reads
+them as JSON.
+
+## CPU: `.cpuprofile`
+
+`nodes[]` is a call tree: each node has `id`, `callFrame` (`functionName`, `url`, `lineNumber`,
+`columnNumber`) and `children` (ids). `samples[]` is the node id hit at each sample and
+`timeDeltas[]` the microseconds since the previous one.
+
+- **Self time** is the sum of `timeDeltas` for samples landing on a node. Rank on it to find
+  what burns the time itself.
+- **Total time** is self plus all descendants. A framework wrapper has large total and tiny
+  self; reading it as the culprit is the usual wrong answer. Descend to the child with the
+  self time.
+- Line and column refer to the generated bundle. Take `functionName`, then find it with
+  `cdp_source_grep`.
+
+```js
+// node top-self.js file.cpuprofile
+const p = JSON.parse(require("fs").readFileSync(process.argv[2], "utf8"));
+const self = new Map();
+p.samples.forEach((id, i) => self.set(id, (self.get(id) ?? 0) + (p.timeDeltas[i] ?? 0)));
+const byId = new Map(p.nodes.map(n => [n.id, n]));
+const total = [...self.values()].reduce((a, b) => a + b, 0);
+[...self].sort((a, b) => b[1] - a[1]).slice(0, 15).forEach(([id, us]) => {
+    const f = byId.get(id).callFrame;
+    console.log(`${((us / total) * 100).toFixed(1)}%`, f.functionName || "(anonymous)", `${f.url}:${f.lineNumber}`);
+});
+```
+
+`(idle)`, `(program)` and `(garbage collector)` rows are the runtime, not app code: a high
+`(idle)` share means the capture window was mostly waiting, not that the app is fast.
+
+## Heap sampling: `.heapprofile`
+
+`head` is a tree of `callFrame`, `selfSize` (bytes) and `children`. Sum `selfSize` down each
+branch to rank call sites by bytes still live at the stop call. Zero for a site means its
+objects were collected, not that it never allocated.
+
+## Heap snapshot: `.heapsnapshot`
+
+A large graph (`nodes`, `edges`, `strings` arrays). Do not read it whole. Load it in Chrome
+DevTools' Memory panel and use the Comparison view between two snapshots taken around the
+suspect interaction; growth in a class or closure count is the finding.
+
+## Comparing two runs
+
+Same interaction, same session state, same `samplingHz`. Compare self-time shares, not
+absolute microseconds: sampling rate and the debug build shift the totals but not the ranking.

package/skills/data-entry-keyboards/SKILL.md

@@ -0,0 +1,160 @@
+# On-screen keyboards and PIN entry
+
+## Overview
+
+Five components collect typing from a remote: `DynamicKeyboard` and `DynamicMiniKeyboard` for
+prose, `DynamicPinPad` for a code, `CustomKeyboard` for an arrangement you define, and
+`DynamicKeyGrid` when the keys are choices rather than characters.
+
+Two things decide how one is wired. The `Dynamic*` family reports the **whole string so far**
+through `onText`, so app state follows the field rather than accumulating keys. And a
+`CustomKeyboard` reports **which key** was pressed, which is what makes shift and
+language keys the app's job rather than the component's.
+
+## When to Use
+
+| If the request is | Then |
+|---|---|
+| Reading what a viewer has typed, as they type it | Here — `onText` |
+| Hiding the characters of a code while still showing its length | Here — `secureMode` |
+| An arrangement of keys the defaults do not cover | Here — a key definition file |
+| Whether the SDK already ships the layout you were about to author | Here — the packaged KDFs |
+| Shift or language keys that appear to do nothing | Here — the app drives the mode |
+| Suiting the arrangement to an email address or a URL | Here — the domain |
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Which pre-assembled dialog wraps a field, or which item type goes in a composed one | The `sdk-components` skill, and the dialog reference it declares | That skill owns which component and how a dialog is composed. This one owns the entry itself, wherever it sits |
+| Opening and closing the dialog the field sits in, or chaining a step after it | The `dialogs-and-modals` skill | Lifecycle is above the field. This skill has nothing to say about when the dialog is up |
+| Moving focus between the keyboard and the rest of the screen | The `focus-management` skill | Handing focus between regions is its subject. A keyboard is just one region |
+| How to spell these exports in JSX, or why they keep their backing asset | The `sdk-components` skill | It owns the spelling table and the tree-shaking rule for them |
+
+## Quick Reference
+
+| Component | Collects | Reports through |
+|---|---|---|
+| `DynamicKeyboard` | Prose, full-width | `onText` |
+| `DynamicMiniKeyboard` | Prose, compact | `onText` |
+| `DynamicPinPad` | Digits | `onText` |
+| `CustomKeyboard` | Whatever the layout defines | `onKeySelectedValue` |
+| `DynamicKeyGrid` | A choice among keys | `onKeySelected` |
+
+Props worth knowing before reaching for the source:
+
+| Prop | On | Does |
+|---|---|---|
+| `onText` | the `Dynamic*` family | The full string so far, on every change |
+| `secureMode` | `DynamicKeyboard`, `DynamicPinPad` | Masks the characters; length stays visible |
+| `hintText` | all | Guidance shown while the field is empty |
+| `maxTextLength` | all | Caps the entry |
+| `showUnderscores`, `centerUnderscores` | `DynamicPinPad` | How the unfilled positions are drawn |
+| `domain` | `DynamicKeyboard`, `DynamicMiniKeyboard`, `CustomKeyboard` | Suits the arrangement to a kind of value; typed by `KeyboardDomain` |
+| `keyDefinitionUri` | `CustomKeyboard`, `DynamicKeyGrid` | The layout to use |
+| `mode` | `CustomKeyboard`, `DynamicKeyGrid` | Which arrangement inside that layout is showing |
+| `jumpToKey` | `CustomKeyboard` | Moves the highlight to a key by position |
+| `horizWrap`, `vertWrap` | `DynamicKeyGrid` | Whether movement wraps at an edge |
+
+## Instructions
+
+1. **Take the value from `onText`, not by accumulating presses.** It hands over the whole
+   string each time it changes, so the signal behind the field is a mirror of the field rather
+   than a log of keys. Appending on every call is how a field ends up with doubled characters.
+
+2. **Mask with `secureMode`.** It hides the characters and leaves the length visible, which is
+   what a viewer needs to see that a press registered. Do not build masking yourself by
+   holding the real value beside a row of asterisks.
+
+3. **Before authoring a layout, check whether one ships.** `@roku-sdk/components/kdfs` exports
+   packaged key definitions — an address layout, a MOP PIN pad, a phone pad and a Wi-Fi
+   layout — as URIs ready for `keyDefinitionUri`. **Import only the ones you use**: an unused
+   export is what keeps the rest of the files out of the build.
+
+4. **Author your own as a `.keyboard.json` and import it.** The build rewrites that import to
+   the packaged URI, so what you pass to `keyDefinitionUri` is the imported value rather than a
+   path you construct. Declaring several arrangements in one file is what makes shift and
+   alphabet switching possible at all.
+
+5. **Drive `mode` yourself in response to `onKeySelectedValue`.** This is the step that is
+   easy to miss: a shift or language key is **suppressed by the component** so it is not typed
+   into the field, and nothing switches the arrangement on your behalf. Watch for those keys in
+   the handler and set the `mode` signal — the component renders whichever arrangement `mode`
+   names.
+
+6. **Set `domain` when the value has a shape.** It suits the arrangement to what is being
+   collected rather than making the viewer hunt for `@` on a prose layout. The choices are
+   typed by `KeyboardDomain`.
+
+7. **Let `focus-management` put focus on the keyboard.** These components take key presses once
+   focused; getting focus to them, and back out afterwards, is not their concern.
+
+## Example
+
+A PIN pad that masks its entry, and a custom keyboard whose shift key the app has to honour.
+
+```tsx rsg-skill=complete
+import { CustomKeyboard, DynamicPinPad, IKeyHandlerData } from "@roku-sdk/components";
+import { Component, createSignal } from "@roku-sdk/solid";
+
+export const ParentalCode: Component<{ onComplete: (code: string) => void }> = props => {
+    const [code, setCode] = createSignal("");
+
+    return (
+        <DynamicPinPad
+            secureMode
+            maxTextLength={4}
+            hintText="Enter your 4-digit code"
+            text={code()}
+            onText={value => {
+                // The whole string so far — assign it, never append to it.
+                setCode(value);
+                if (value.length === 4) {
+                    props.onComplete(value);
+                }
+            }}
+        />
+    );
+};
+
+const LOWER = "lower";
+const UPPER = "upper";
+
+export const NameField: Component<{ layoutUri: string }> = props => {
+    const [mode, setMode] = createSignal(LOWER);
+    const [text, setText] = createSignal("");
+
+    return (
+        <CustomKeyboard
+            keyDefinitionUri={props.layoutUri}
+            mode={mode()}
+            text={text()}
+            onText={value => {
+                setText(value);
+            }}
+            // A shift key is suppressed rather than typed, so the arrangement
+            // only changes if this handler changes it.
+            onKeySelectedValue={(data: IKeyHandlerData) => {
+                if (String(data.key).toLowerCase().startsWith("caps")) {
+                    setMode(current => (current === LOWER ? UPPER : LOWER));
+                }
+            }}
+        />
+    );
+};
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Characters appear doubled or the field grows too fast | `onText` was treated as one key and appended to state | It is the whole string; assign it |
+| A code is readable over the viewer's shoulder | Masking was not turned on | `secureMode` |
+| A viewer cannot tell whether a press registered on a masked field | Masking hid the length too, because it was hand-built | `secureMode` keeps the length visible |
+| A shift or language key does nothing, and is not typed either | The component suppresses it; nothing switched the arrangement | Watch for it in `onKeySelectedValue` and set `mode` |
+| A hand-written layout URI does not resolve | A path was constructed rather than using the value the import produced | Import the `.keyboard.json` and pass what it yields |
+| The build carries layouts the app never shows | Every packaged KDF was imported, or a barrel pulled them in | Import only the ones used from `@roku-sdk/components/kdfs` |
+| An email field puts the viewer on a prose arrangement | `domain` was left unset | Set it from `KeyboardDomain` |
+
+Props are documented with TSDoc in `@roku-sdk/components`; read a field's exact shape and the
+full `KeyboardDomain` list there rather than inferring either from here.