@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/mcp-setup/SKILL.md

@@ -0,0 +1,131 @@
+# MCP Setup
+
+## Overview
+
+The SDK reaches an agent through an MCP server, and there are two ways to run it: the editor
+spawns it, or it runs as a persistent background process. They are not alternatives to choose
+between once. The spawned entry looks for a running server on every request and forwards to it,
+so the config decides how the client reaches the tools, and whether a server is running decides
+which tools answer. Write the spawned entry, then start a server if the task needs one.
+
+## When to Use
+
+- an agent session with no Roku tools in it, or an editor that has never been configured
+- a client that will not connect, or connects and lists nothing
+- deciding between the spawned entry and a persistent server, and how to move between them
+- finding the port a running server chose, or fixing it so it can be written down
+- a call refused with a message about requiring server mode
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Tools answer, and one call fails over targeting, a device, or the app | The `mcp-ai-dev-loop` skill | Setup finished when the client listed tools. A refusal that names server mode is the exception and stays here, because the fix is to start a server |
+| Which call reports whether the server is up, from inside a working session | The `mcp-ai-dev-loop` skill | Reading the session's own state is that skill's loop; starting what is missing is this one |
+| Deploying, screenshotting, driving the app or reading its logs | The `mcp-ai-dev-loop` skill | This skill ends at the connection |
+| Configuring an MCP server that is not the SDK's | That server's own documentation | Nothing here generalises past `rk` |
+| A shell script, a CI step, or anything with no agent in it | The `cli-dev-loop` skill | MCP exists to give an agent the tools; a runner calls `rk` itself, and needs none of this |
+| `rk` itself does not resolve yet | The `sdk-installation` skill | There is nothing to configure until the package is installed |
+
+## Quick Reference
+
+| Goal | Do |
+|---|---|
+| Let the editor run the server | A config entry invoking `rk mcp` through the project's own runner |
+| Run one persistently | `rk server start --daemon` |
+| Find the port, and confirm it is up | `rk server status` |
+| Fix the port so it can be written down | `--port <n>` on `rk server start` |
+| Stop it | `rk server stop` |
+| Test the install without the editor | Run `rk mcp` in a terminal; it should sit waiting on stdin |
+
+## Instructions
+
+1. **Write the spawned entry first.** It is the whole of setup for most work, and it is the
+   half that survives every later change. What matters is that the entry reaches the *installed*
+   binary in `node_modules/.bin`: `npx rk mcp` and `pnpm exec rk mcp` both do that in a project
+   that depends on `@roku-sdk/tooling`, so use whichever runner the project already uses. What
+   fails is an entry that can miss it — a bare `rk` that is not on `PATH`, or a runner invoked
+   outside the project directory, which sends it to the registry for a package it could have
+   read from disk.
+
+2. **The key and the fields differ by editor, and a wrong key fails silently.** VS Code reads
+   `.vscode/mcp.json` under a `servers` key and wants a `type`. Cursor reads `.cursor/mcp.json`
+   under `mcpServers` and does not. A client handed the other shape finds no entry, so it
+   reports no error and lists no tools — which looks exactly like a broken install.
+
+3. **Start a server only when the task needs one.** Most tools run in process. `logs`,
+   `get_server_health`, `stop_dev_session`, the three Perfetto tools (`perfetto_enable`,
+   `perfetto_start`, `perfetto_stop`) and the CDP and DAP debugger families require a server
+   and say so when there is none, naming `rk server` in the failure.
+
+4. **Never hardcode the port.** It is derived from a hash of the workspace root path, so it
+   differs per checkout and even between two clones of the same repo, landing somewhere in
+   3737–4236 (Fetch-blocked ports such as 4045 and 4190 are skipped). `rk server status`
+   prints the one in use. If a port has to be written into a config file, make it true by
+   starting the server with `--port` rather than by guessing.
+
+5. **Moving from spawned to persistent is starting a server, not rewriting the config.**
+   Because `rk mcp` forwards to a live server when it finds one, a stdio entry plus a running
+   server already has the full tool surface. Point the client at an HTTP URL only when
+   something other than that editor needs the same backend.
+
+6. **`--daemon` is what makes it outlive the terminal.** Without it the server stops with the
+   shell that started it. It also exits after 240 idle minutes, which `--timeout` changes; a
+   morning's server being gone after lunch is that, not a crash.
+
+7. **When no tools appear, test the install before touching the config again.** Run `rk mcp`
+   from the workspace root, through the same runner the config entry uses: it should start and
+   sit waiting on stdin. That separates the two failures — if it runs, the config is wrong; if it
+   reports that `rk` was not found, the tooling is not installed and no config would have helped.
+   Read the message rather than the exit status: a runner reports a missing binary with its own
+   code, and only a bare shell returns the 127 people expect.
+
+8. **In spawned mode nothing may write to stdout.** That stream carries JSON-RPC and nothing
+   else. A wrapper script that echoes a line, or a shell profile that prints a banner, corrupts
+   the first message and the client drops the connection — usually reported as the server
+   exiting immediately. Invoke the binary directly rather than through a wrapper.
+
+## Example
+
+A Cursor setup that starts spawned and gains the server-only tools without the config changing.
+
+`.cursor/mcp.json` — written once:
+
+```json
+{
+    "mcpServers": {
+        "roku-sdk-tools": {
+            "command": "pnpm",
+            "args": ["exec", "rk", "mcp"]
+        }
+    }
+}
+```
+
+`"command": "npx"` with `["rk", "mcp"]` is the same entry for a project on npm; the runner has
+to match the project, not this page.
+
+Later, when the task needs log collection or a trace:
+
+```bash
+npx rk server start --daemon
+npx rk server status
+# rk server running at http://localhost:3941/api (pid 12345, rkRoot: /Users/you/workspace)
+```
+
+The config above is unchanged and now reaches that server. The printed port matters only if
+another client has to be pointed at the same backend; for this editor, nothing needs it.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| No tools at all, and no error anywhere | The config uses the other editor's key | `servers` for VS Code, `mcpServers` for Cursor |
+| Tools appear, but every connection is slow | The runner is reaching the registry because it cannot see the project's `node_modules` | Give the entry the project directory, so `rk` resolves from disk |
+| The server exits the moment the client starts it | Something wrote to stdout ahead of the protocol | Drop the wrapper script; invoke the binary |
+| Connection refused on the URL that worked yesterday | The port was hardcoded and is derived per workspace | `rk server status`, or pin it with `--port` |
+| Every request answers `403` with `HOST_NOT_ALLOWED` or `ORIGIN_NOT_ALLOWED` | The URL names the server by something other than a loopback name (`host.docker.internal`, the machine's LAN address), or a browser-based client sends an `Origin` from another port | Use `localhost` or `127.0.0.1`, through a port forward if the client runs elsewhere (`ssh -L`, an editor's port forwarding, `docker -p` all work, since only the `Host` name is checked); a browser client has to be served from the server's own port |
+| An HTTP client gets `404` with `MCP_SESSION_UNKNOWN` | Its `Mcp-Session-Id` was not issued on this machine: made up or altered, from another machine, or signed with a session key file (`roku-rce-mcp-session-secret`, beside the RCE token) that was since deleted or replaced. A restart alone does not cause it | Reconnect the client so it sends `initialize` again; `rk mcp` does this on its own |
+| A call refuses, naming server mode, while others work | No server is running | `rk server start --daemon`; the config needs no change |
+| The server is gone after a few hours | The idle timeout, or it was started without `--daemon` | Restart with `--daemon`, and raise `--timeout` if the gap is expected |
+| Running it by hand reports that `rk` was not found | The tooling is not installed in this workspace | Install dependencies, and confirm `node_modules/.bin/rk` exists |

package/skills/project-setup/SKILL.md

@@ -0,0 +1,210 @@
+# Project Setup
+
+## Overview
+
+`npx rk create <app-name>` scaffolds an RSG SDK TypeScript app that already builds and
+runs. Five things then own the project: `roku-config.ts` (app config and manifest entries),
+`tsconfig.json` (one `extends` line), `package.json` (the `@roku-sdk/*` dependencies),
+`src/` (TypeScript and imported images) and `pkg/` (static assets copied verbatim).
+
+## Read the reference first for these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| Any `roku-config.ts` field this body does not itself show | `references/roku-config.md` |
+
+This body shows `app.entryPoint` and `manifestEntries`, plus the `images` and `logger` blocks in
+the Example. For any other field, open the reference and name the field from it. If it is not
+there either, the authority is `RokuConfig` — the type already annotating the app's own
+`roku-config.ts` — because the schema gains fields faster than either page. This table routes;
+there is nothing in it to answer from.
+
+## When to Use
+
+- creating a new app, or adding one to an existing repo
+- the app title, version, splash screen or supported resolutions have to change
+- a new image, font or static asset has to be added and referenced from code
+- an `@roku-sdk/*` package the app imports is missing from its `package.json`
+- the app's TypeScript setup is wrong: JSX or SDK types not resolving
+- declaration generation stops on an XML component base the SDK does not map, or whether built-in mappings still apply alongside yours in `dtsOptions`
+- `rk` cannot find the config, or a first run on a device is not working yet
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Building, deploying, sideloading, or reading logs from an app that already runs, inside an agent session | The `mcp-ai-dev-loop` skill | Those are build and deploy operations, not project configuration |
+| The same operations from a shell script or a CI job | The `cli-dev-loop` skill | Same reason, different surface — and the CLI's directories and flags are not the ones the tools expose |
+| An `@roku-sdk` package that will not resolve at all, moving the versions of ones that do, a peer one of them requires the app to declare, or a `workspace:*` range that will not resolve | The `sdk-installation` skill | Reaching the registry, and which version line arrives from it, comes before any of this |
+| Registering a Roku, storing its password, or choosing which one a command reaches | The `device-management` skill | That store lives outside the repository and is not project configuration |
+| A legacy BrightScript channel with XML components | Roku's BrightScript documentation | This SDK's project shape does not apply there |
+| How the app behaves at runtime — focus, layout, data | The skill for that area | Setup ends where the app's own code begins |
+| A convention that holds only in one repo | That repo's `AGENTS.md` | Repo-specific facts do not belong in a portable skill |
+
+## Quick Reference
+
+| Task | Do this |
+|---|---|
+| Create an app | `npx rk create my-app` — name lowercase, letters, digits, hyphens |
+| Change title, version, splash, resolutions | `manifestEntries` in `roku-config.ts` |
+| An XML base declaration generation does not recognise | `dtsOptions.componentMapping` in `roku-config.ts`; keep sibling `includeDefaults` on so the SDK's own mappings still merge |
+| Configure anything else in `roku-config.ts` | `references/roku-config.md` — the field names are only there |
+| Register a Roku, store its password, or pick which one commands reach | The `device-management` skill |
+| Keep the device developer password out of git | it lands in `.roku/roku-dev-config.json`, which the scaffold already covers by ignoring `.roku/` — that entry is also the only one it writes, not even build output |
+| Build the app, install it, drive it or read its logs from a shell | The `cli-dev-loop` skill |
+| Find any flag | `npx rk <command> --help` — the help text is the contract |
+
+## Instructions
+
+1. **Scaffold with `npx rk create my-app`**, then `cd my-app && npx rk dev`. It
+   installs dependencies, generates the app icons and drops the SDK's agent skills into the
+   new repo. Needs Node >= 24 and pnpm. Do **not** assemble a project by hand, and do
+   **not** reach for `brighterscript`, `roku-deploy` or `ropm` — a different toolchain that
+   does not apply to this SDK.
+
+   A standalone app also gets a `pnpm-workspace.yaml` whose `allowBuilds` block allows
+   `@roku-sdk/tooling`'s install script and denies `esbuild`, `unrs-resolver` and
+   `@parcel/watcher`. pnpm 11 fails every install and every `pnpm run` without a decision
+   for each, so keep the file. Created inside an existing pnpm workspace, the app gets no
+   file and the root's `allowBuilds` has to cover those four.
+
+   The `.gitignore` it writes holds a single entry, `.roku/`. That is the entry that matters —
+   the device developer password lands in `.roku/roku-dev-config.json` in clear text, so without
+   it `git add -A` would commit a credential — but it is also the only one, so build output and
+   `node_modules` still want adding before the first commit.
+
+2. **Configure the app in `roku-config.ts`** at the app root — see the Example. Only
+   `app.entryPoint` is required. Let `manifestEntries` write the manifest, and never hand-write
+   one alongside it. The build does read a `manifest` file when the app ships one, keeping its
+   comments, its line order and any key `manifestEntries` leaves alone — but every key set in
+   both is overwritten from `roku-config.ts`, with a warning. Two sources for one file that
+   only ever resolves one way is a file that drifts. `rk` finds `roku-config.ts` by walking up
+   from the current directory, so run commands from inside the app or pass `--config <path>`.
+
+3. **Know the chain that starts the app**, because nothing under `src/` runs until all of it is
+   in place. BrightScript's `Main()` creates the SceneGraph screen and instantiates a Scene
+   **by name**; that Scene is the root node, and the app's anchor node is a child of it, not
+   the root itself. The app's entry point then calls `main()` and registers the anchor node
+   with `registerAnchorNode` **inside** that callback. The Scene's generated XML has to be
+   imported for its side effect — `import "./compiled-components/<Scene>.xml";` — or the name
+   `Main()` asks for does not exist at runtime and the app comes up as an empty screen with no
+   build error.
+
+4. **Keep `tsconfig.json` to one `extends` line**, by package alias:
+
+```json
+{
+    "extends": "@roku-sdk/rsg-ts/tsconfig.json",
+    "compilerOptions": { "rootDir": "src", "baseUrl": "." },
+    "include": ["src/**/*"]
+}
+```
+
+   Never extend by a relative path — it breaks as soon as the app moves. `jsx`,
+   `jsxImportSource: "@roku-sdk/solid"` and the SDK's `types` all arrive from that config,
+   so do not re-declare them. If you must add to `types`, re-list
+   `@roku-sdk/interfaces/global` and `@roku-sdk/components/jsx` beside your addition,
+   because the array **replaces** the inherited one.
+
+5. **Declare every package the app imports** in its own `package.json`, including one you
+   only take a type from — pnpm does not hoist. Use `"workspace:*"` inside the SDK's pnpm
+   workspace and one shared caret version for a standalone app, since `@roku-sdk/*`
+   packages are released together; which line that is, and any peer a package requires on top,
+   belong to the `sdk-installation` skill. Into a standalone app, `rk create` writes
+   `@roku-sdk/common`, `@roku-sdk/components`, `@roku-sdk/interfaces`, `@roku-sdk/native`,
+   `@roku-sdk/rsg-ts`, `@roku-sdk/sdk-config`, `@roku-sdk/solid`, `@roku-sdk/testing-library`,
+   `@roku-sdk/tooling` and `@roku-sdk/ts-core`, plus `@roku-sdk/dev-tools` as a dev
+   dependency. The `rk` launcher loads `tsx` from tooling itself; do not add `tsx`
+   merely to run `npx rk`. Run inside the SDK's own workspace it scaffolds from a different app and the
+   set differs, so read the `package.json` it generated before concluding anything is missing.
+   What is not there is on you to add: `@roku-sdk/navigation` the moment the screen needs
+   focus, `@roku-sdk/flex-grid` for a shelf or poster grid. `solid-js` is deliberately
+   not in that set and must not be added: SolidJS reaches the app through `@roku-sdk/solid`,
+   which re-exports the part of it that works under the SceneGraph renderer. Import every
+   SolidJS primitive from there, never from `solid-js`. Declaring a package is not the same as
+   being able to install it — if one of these will not resolve at all, that is the
+   `sdk-installation` skill.
+
+6. **Put app images in `src/` and import them by relative path.** The import gives you
+   `uri`, plus `dimensions` when the intrinsic size is needed:
+
+```tsx
+import { Poster } from "@roku-sdk/components";
+
+import { dimensions, uri } from "../images/logo-fhd.png";
+
+<poster uri={uri} width={dimensions.fhd.width} height={dimensions.fhd.height} />;
+```
+
+   Alias them — `import { uri as logoUri }` — in a module that imports more than one image.
+   Never hardcode a `pkg:/` URI for an app image: that opts out of the path rewrite, the
+   webp conversion and the copy into the package. Importable extensions are `.png`, `.jpg`,
+   `.jpeg` and `.webp`.
+
+7. **For one image per resolution, put the placeholder in the specifier** —
+   `import { uri } from "../images/logo-*.png"`. The `*` is **not** a glob: it is the
+   `uri_resolution_autosub` placeholder and is substituted literally, so the files must be
+   named exactly `logo-fhd.png` and `logo-hd.png`. A 9-patch (`logo-*.9.png`) fails the
+   build outright without a hand-authored `logo-hd.9.png`.
+
+8. **Put the icons and splash named in `manifestEntries` under `pkg/images/`** and reference
+   them as `pkg:/images/...`. Everything under `pkg/` is copied into the package verbatim,
+   which is what makes it the one place a `pkg:/` URI is written by hand.
+
+## Example
+
+```ts rsg-skill=complete
+import { getBuildType, type RokuConfig } from "@roku-sdk/rsg-ts/roku-config";
+
+const buildType = getBuildType();
+
+const configuration: RokuConfig = {
+    app: {
+        entryPoint: "src/index.ts",
+        images: { convertToWebp: true, generateHd: true },
+        logger: { baseLogLevel: "INFO", currentLogLevel: "ERROR" },
+        manifestEntries: {
+            title: buildType === "production" ? "My App" : `My App (${buildType})`,
+            major_version: 1,
+            minor_version: 0,
+            build_version: 0,
+            ui_resolutions: "fhd",
+            uri_resolution_autosub: "*,sd,hd,fhd",
+            mm_icon_focus_hd: "pkg:/images/app-icon-hd.png",
+            mm_icon_focus_fhd: "pkg:/images/app-icon-fhd.png",
+            splash_screen_hd: "pkg:/images/splash_hd.jpg",
+            splash_color: "0x000000FF",
+            splash_min_time: 1,
+            rsg_version: "2.0"
+        }
+    }
+};
+
+export default configuration;
+```
+
+`ui_resolutions` also fixes the space the app is **authored** in. With `"fhd"`, every
+coordinate, width and height in the code is in a 1920×1080 design space whatever the device
+turns out to be, and an HD box scales the whole tree down as it renders. So write one set of
+numbers and never branch on the device's resolution. Reading a measurement back *off* a device
+runs the other way — a 720p screenshot's pixels are two-thirds of the number the code used —
+and that direction belongs to the `mcp-ai-dev-loop` skill.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| An image import resolves to the wrong file, or to nothing | `*` was read as a glob | Name the files `-fhd` and `-hd` exactly |
+| `HD image not found for 9-patch image` | A `.9.png` has no HD variant | Author `-hd.9.png` by hand; it is not generated |
+| SDK types vanished after editing `types` in `tsconfig.json` | The array replaced the inherited one | Re-list `@roku-sdk/interfaces/global` and `@roku-sdk/components/jsx` |
+| Builds fine, but no icon on the device | `mm_icon_focus_hd` / `mm_icon_focus_fhd` name files that are not there | Put them under `pkg/images/` |
+| `git status` offers to commit `.roku/roku-dev-config.json`, which holds the password | The project was not scaffolded by `rk create`, so nothing ignores `.roku/` | Ignore `.roku/`, and `git rm --cached` it if it was already committed |
+| `.roku/` is git-ignored but `rk` still warns that it is not | The check recognises `.roku`, `/.roku`, `.roku/` and `/.roku/`, and no other pattern | Use one of those four forms rather than a glob such as `**/.roku` |
+| The build stops on an XML component whose base the declaration generation does not recognise, and no SDK version ever mapped it | The base is the app's own, so only the app can declare it | Add it under `dtsOptions.componentMapping` in `roku-config.ts`, and leave the sibling `includeDefaults` on so the SDK's own mappings still merge in |
+| `rk` cannot find the config | It walks up from the current directory | Run from inside the app, or pass `--config` |
+| The build fails on something the installed version handles — a base component the SDK maps itself, a define it sets itself — or otherwise behaves like an older SDK | `rk` prefers a running `rk server`, which executes the build with the tooling it loaded at startup, from whatever project it was started in. Reinstalling the app's packages cannot change code already resident in that process | `rk server status` to see it, `rk server stop` then start it again from this app, or pass `--local` to skip server discovery for one command |
+| A package you import is missing at build time | pnpm does not hoist it in | Declare it in the app's own `package.json` |
+| An import of `solid-js` does not resolve, or its API does nothing on the device | `solid-js` belongs to `@roku-sdk/solid`, not to the app, and only the re-exported part drives the SceneGraph renderer | Import from `@roku-sdk/solid` |
+
+Every config field is typed with TSDoc in `@roku-sdk/sdk-config` — `UserSdkConfig`,
+`UserSdkAppConfig`, `RokuManifestEntries`. Read a field there rather than guessing its name.

package/skills/project-setup/references/roku-config.md

@@ -0,0 +1,120 @@
+# `roku-config.ts` beyond the manifest
+
+The skill body covers the part of this file every app touches: `app.entryPoint`, and the
+`manifestEntries` block that *is* the manifest. This file covers the rest — the blocks that
+exist for a specific job, and the rules for which value wins when more than one place sets it.
+
+Every field is typed with TSDoc in `@roku-sdk/sdk-config` (`UserSdkConfig`, `UserSdkAppConfig`,
+`RokuManifestEntries`). Read a field's type there; read the behaviour here.
+
+## Code that must not reach production
+
+`app.buildVariables` injects build-time constants, and two names are supplied whether or not
+you declare them.
+
+`__DEV__` is `true` under `rk dev` and `false` under `rk build`, except for
+`rk build --debug`. It is **reserved**: declaring it in `buildVariables` does not override it.
+Guarding with it is what removes code from a production build, because the branch is
+tree-shaken away rather than merely skipped.
+
+```ts
+if (__DEV__) {
+    // dev-only logic, absent from a production bundle
+}
+```
+
+Naming reactive work is a different switch, and it is not a build variable. `solidDevMode`
+sits at the top level beside `app` (or comes from `--solid-dev-mode`) and resolves solid through
+its development build, which is what gives `createSignal`, `createMemo` and `createEffect`
+their names in traces and Solid devtools — without it reactive work is anonymous, which is
+usually discovered halfway through reading a trace. The config field takes effect only on
+`rk dev --debug`; `--solid-dev-mode` works on any JavaScript build. Plain `rk dev` and
+`rk build` ignore the config field, and bytecode builds skip it, so a production trace stays
+anonymous however this is set.
+
+`buildVariables: { __SIGNAL__: true }` is the legacy spelling of the same switch. Reach for
+`solidDevMode` instead: values are JSON-stringified on the way through, so the bare `true`
+reaches the switch as `true` and matches, while `"true"` reaches it still quoted and turns
+nothing on. Both spellings are legal build variables, so the compiler stays silent on the
+one that does nothing.
+
+```ts rsg-skill=complete
+import { type RokuConfig } from "@roku-sdk/rsg-ts/roku-config";
+
+const configuration: RokuConfig = {
+    solidDevMode: true,
+    app: {
+        entryPoint: "src/index.ts",
+        // Not a build variable: the two log-level keys are written by the build
+        // itself, so setting them in `buildVariables` is silently discarded.
+        logger: { baseLogLevel: "INFO" }
+    }
+};
+```
+
+The log levels are the one pair that does not belong in `buildVariables`. `__BASE_LOG_LEVEL__`
+and `__CURRENT_LOG_LEVEL__` are set by the build from `app.logger` and overwrite whatever you put
+there, with no warning — see the `logging-and-errors` skill for what each level actually does.
+
+## Seeing inside a function without editing it
+
+`app.perfetto` wraps eligible named functions in trace slices at build time.
+
+| Field | Effect |
+|---|---|
+| `instrumentPaths` | Folder prefixes to instrument, matched as **substrings** of the source path. Empty or absent disables instrumentation |
+| `exclude` | Babel visitor shapes to skip: `"FunctionDeclaration"`, `"VariableDeclarator"`, `"FunctionExpression"`, `"ObjectMethod"` |
+| `filter` | Trace-name substrings to keep. Absent instruments every eligible name; an **empty array instruments none** |
+
+The substring match is the trap: `"src"` also matches `resource/data` and `other-src/utils`,
+so give a prefix specific enough to mean what you intended.
+
+`--perfetto-paths`, `--perfetto-exclude` and `--perfetto-filter` override the corresponding
+field for one run. Each is repeatable and each value may be comma-separated. Passing an empty
+value disables that dimension rather than falling back to the config.
+
+## An XML component whose base the SDK does not know
+
+A build that fails asking for a missing base-component mapping is asking for `dtsOptions`.
+Declaration generation maps every base an XML component extends; a base outside the merged
+mapping — the SDK's defaults plus yours — stops the build rather than emitting a `.d.ts` with a
+hole in it.
+
+```ts
+import { type RokuConfig } from "@roku-sdk/rsg-ts/roku-config";
+
+const configuration: RokuConfig = {
+    app: { entryPoint: "src/index.ts" },
+    dtsOptions: {
+        includeDefaults: true,
+        augmentJSX: true,
+        componentMapping: {
+            MyCustomBase: {
+                interface: "IMyCustomBaseProps",
+                module: "./src/components/MyCustomBase.xml"
+            }
+        }
+    }
+};
+```
+
+Keep `includeDefaults` on unless you intend to replace the SDK's mappings wholesale; the
+`componentMapping` object merges with them rather than shadowing the file.
+
+## Signing, and the one value that must not be here
+
+`package.devId` is the developer ID expected after a re-key, and `package.outDir` is where a
+signed package lands. The signing password is **not** a config field: pass
+`--signing-password`, or set `ROKU_SIGNING_PASSWORD`. A password written into `roku-config.ts`
+is a credential in the repository.
+
+## Publishing
+
+`roku-config.ts` accepts a `publishing` block, but `rk` does not currently read it, so editing
+it changes nothing a command does. A version reaches a channel by uploading the signed `.pkg` in
+the Roku Developer Dashboard; getting that `.pkg` is the `app-packaging` skill's subject.
+
+## Which value wins
+
+Perfetto instrumentation takes the CLI flag first, then the `app.perfetto` field. There is no
+environment layer, so a stale environment variable cannot outrank a value you just edited.

package/skills/screen-navigation/SKILL.md

@@ -0,0 +1,166 @@
+# Moving between screens
+
+## Overview
+
+`@roku-sdk/navigation`'s screen controller owns which whole view is on screen. It offers two
+styles that mix freely: a **stack**, where a pushed view layers over the previous one and the
+one below stays mounted, and a **replace**, where the outgoing view is torn down.
+
+Two things about it are not guessable from the API and cause most of the surprises. It renders
+**no background of its own**, so a pushed view does not hide what is under it. And it exposes
+**no hook** — a screen reads the context directly.
+
+## When to Use
+
+| If the request is | Then |
+|---|---|
+| Opening a whole view over another, and getting back to the first with its state intact | Here — the stack |
+| Swapping the current view for a sibling, with the old one torn down | Here — replace |
+| Dropping everything a viewer had open and returning to the app's starting view | Here — reset |
+| Releasing work while a view is covered and resuming when it is on top again | Here — the cover callbacks |
+| A pushed view through which the previous one is still visible | Here — the controller draws no background |
+| Handing a value to the view being opened | Here — props on the factory's element |
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Focus or D-pad movement inside a view, or handing focus between regions of one | The `focus-management` skill | Screen routing is not a focus concern. Focus work starts once the view is up |
+| A view that comes up blank with no crash and no stack | The `logging-and-errors` skill | That is a component that threw, not a navigation problem. The controller will happily mount a screen that renders nothing |
+| A dialog or overlay over the current view | The `dialogs-and-modals` skill for its lifecycle, `sdk-components` for what it is made of | A dialog leaves the view underneath mounted *and* claims focus through a native modal. Pushing a screen does neither |
+| The app's directory layout, or which packages it declares | The `project-setup` skill | The scaffold already lists `@roku-sdk/navigation`, so there is nothing to add before using this |
+| Moving along a shelf or grid, or off its edge onto something else | The `flex-grid` skill | A grid owns its own movement keys and its own edges |
+
+## Quick Reference
+
+Read the context to get these. Every one is a member of the controller.
+
+| Member | Does |
+|---|---|
+| `pushScreen(factory)` | Layers a view on top. The one below stays mounted, so its state survives |
+| `popScreen()` | Drops the top one; the one below reappears untouched |
+| `setScreen(factory)` | Replaces the top entry. **The outgoing instance is destroyed and its local state is gone** |
+| `resetScreen(factory?)` | Clears the whole history. With no argument, lands on the provider's fallback |
+| `getScreen()` | The element for the current stack, which the root scene renders |
+| `onScreenCovered(callback)` | Fires when something is pushed over this view |
+| `onScreenUncovered(callback)` | Fires when the thing above it is popped and it is top again |
+
+`ScreenControllerProvider` takes `children` and a required `fallback` — the factory used when
+the stack is empty, when an entry's factory is `null`, and when `resetScreen()` is called bare.
+
+## Instructions
+
+1. **Mount `ScreenControllerProvider` once, near the root, and give it a `fallback`.** The
+   fallback is not an error path — it is the app's starting view, and three different calls
+   land on it.
+
+2. **Reach the controller with `useContext(ScreenControllerContext)`.** That is the whole
+   access pattern. Its default value throws if it is read outside the provider, so a missing
+   provider fails loudly rather than silently doing nothing.
+
+3. **Choose the style by what should survive.** `pushScreen` / `popScreen` for drilling in and
+   coming back, because the view underneath stays mounted and Solid keeps its state for free.
+   `setScreen` for siblings — tabs, wizard steps — because only one should be alive.
+   `resetScreen` to clear history.
+
+4. **A pushed view does not hide the one below it.** The controller paints nothing, so unless
+   the new view covers the screen with something opaque, the old one shows through. Either give
+   the pushed view an opaque background, or set the lower one invisible from its
+   `onScreenCovered`.
+
+5. **Pass data as props on the element the factory returns.** The factory closes over whatever
+   is in scope, so no parameter mechanism is needed. But those props are a **snapshot taken at
+   navigation time** — mutating the source afterwards does not reach the mounted view. Pass an
+   accessor when the view has to track a value that keeps changing.
+
+6. **Register the cover callbacks from `onMount`.** They unregister themselves when the calling
+   owner is disposed, so there is no matching teardown to write. What belongs in them is work
+   that costs something while nobody is looking: polling, timers, heavy textures.
+
+7. **Return to the start with `setScreen(null)` or a bare `resetScreen()`.** Both render the
+   provider's fallback; `resetScreen()` also empties the history so there is nothing left to
+   pop back to.
+
+## Example
+
+A provider, a list that drills in, and a details view that releases work while it is covered.
+
+```tsx rsg-skill=complete
+import { ScreenControllerContext, ScreenControllerProvider } from "@roku-sdk/navigation";
+import { Component, createSignal, JSX, onMount, useContext } from "@roku-sdk/solid";
+
+interface DetailsProps {
+    itemId: string;
+}
+
+const DetailsScreen: Component<DetailsProps> = props => {
+    const screens = useContext(ScreenControllerContext);
+    const [live, setLive] = createSignal(true);
+
+    onMount(() => {
+        // Both callbacks unregister with this owner — nothing to undo by hand.
+        screens.onScreenCovered(() => setLive(false));
+        screens.onScreenUncovered(() => setLive(true));
+    });
+
+    return (
+        <group>
+            {/* Opaque, because the controller paints no background of its own. */}
+            <rectangle width={1920} height={1080} color="0x101018FF" />
+            <label text={`Details for ${props.itemId}`} translation={[96, 96]} />
+            <label text={live() ? "streaming" : "paused"} translation={[96, 160]} />
+        </group>
+    );
+};
+
+const HomeScreen: Component = () => <label text="Home" translation={[96, 96]} />;
+
+/** Renders whichever entries are on the stack. One of these, under the provider. */
+const ScreenHost: Component = () => {
+    const screens = useContext(ScreenControllerContext);
+    return <group>{screens.getScreen()}</group>;
+};
+
+export const RootScene: Component = (): JSX.Element => (
+    <ScreenControllerProvider fallback={() => <HomeScreen />}>
+        <ScreenHost />
+    </ScreenControllerProvider>
+);
+
+export { DetailsScreen };
+```
+
+Drilling in and coming back, from anywhere under the provider:
+
+```tsx
+import { ScreenControllerContext } from "@roku-sdk/navigation";
+import { useContext } from "@roku-sdk/solid";
+
+import { DetailsScreen } from "./details-screen";
+
+const screens = useContext(ScreenControllerContext);
+
+// `itemId` is captured here; changing it afterwards does not reach the mounted view.
+const openItem = (itemId: string) => screens.pushScreen(() => <DetailsScreen itemId={itemId} />);
+
+const goBack = () => screens.popScreen();
+```
+
+Going back is `popScreen()`, and the list returns with its position and focus intact because
+it was never unmounted.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The previous view is readable through the one just opened | The controller renders no background, and the new view does not cover the screen | Give the pushed view an opaque background, or hide the lower one from its `onScreenCovered` |
+| Coming back from a details view resets the list | `setScreen` was used where a drill-down was meant, so the list was destroyed | `pushScreen` to go in, `popScreen` to come back |
+| A view shows a stale value that has since changed | Props on the factory's element are a snapshot at navigation time | Pass an accessor rather than the value |
+| Memory and network keep growing as a viewer drills deeper | Every pushed view stays mounted and keeps working | Release what is expensive from `onScreenCovered` and restore it from `onScreenUncovered` |
+| Reading the controller throws on mount | The component is outside the provider | Mount `ScreenControllerProvider` above it. The throw is deliberate — a silent no-op would be worse |
+| Back leaves the app instead of returning | Nothing was on the stack to pop, so the key reached the platform | Push before expecting to pop, and treat the fallback as the floor |
+| Sibling tabs slow down as the viewer cycles them | Each tab was pushed, so they accumulate | `setScreen` for siblings — only one should be alive |
+
+Provider and context types are exported from `@roku-sdk/navigation` and documented with TSDoc
+there — `IScreenControllerContext` and `IScreenControllerProviderProps`. Read a member's exact
+signature there rather than inferring it from here.