@sema-agent/server 1.196.0 → 1.197.0

package/skills/run-skill-generator.md

@@ -0,0 +1,493 @@
+---
+name: run-skill-generator
+description: Author or improve the run-<unit> skill - a per-project skill that tells agents how to build, launch, and drive this project's app. Use when the user asks to set up the project, get it running, write run instructions, or verify build/run steps work from a clean environment.
+---
+
+Your job is to produce a **skill** at `<unit>/skills/run-<unit-name>/`
+that lets a future agent build, launch, and **drive** this project from
+a clean machine.
+
+The skill has two parts that live together:
+
+```
+<unit>/skills/run-<unit-name>/
+  SKILL.md      ← agent-facing instructions — SHORT. Points at the driver.
+  driver.mjs    ← (or driver.py, smoke.sh, … — or none: web apps use
+                   browser-cli off-the-shelf, and the heredoc in
+                   SKILL.md is the script)
+```
+
+(*browser-cli* here = your environment's off-the-shelf headless-browser
+driver CLI, e.g. Playwright-based; if none ships, a small Playwright
+script is the driver.)
+
+That almost always means **writing code**, not just prose. If the app
+has any interactive surface (GUI, TUI, long-running server, REPL), the
+future agent needs a programmatic way to poke it. A markdown file by
+itself cannot click a button — but sometimes the button-clicker
+already exists: for web apps it's `browser-cli`, for servers it's
+`curl`. You build (or script) that harness now, commit it alongside
+the skill, and the `SKILL.md` documents how to use it.
+
+## Definition of done
+
+You are done when **all** of these are true:
+
+1. **You launched the app in this container and interacted with it** —
+   not its test suite, the actual running app. For anything with a GUI,
+   that means you have a screenshot file on disk that you took.
+2. **The interaction harness is committed** next to the skill. A driver
+   script, a REPL wrapper, a smoke test, or the `browser-cli` heredoc
+   inline in `SKILL.md` — whatever you used to drive the app in step 1.
+   (Graduated into `scripts/`/`e2e/`? — fine, point at it. Web app with
+   `browser-cli` off-the-shelf? — the inline script is the harness; no
+   separate file.)
+3. **The `SKILL.md` documents the harness** as the primary agent path —
+   the section a future agent reads first is "run this driver / pipe
+   these commands to `browser-cli`," not "run `npm start` and a window
+   opens."
+4. **Every code block in `SKILL.md` is a command you ran that worked.**
+   This session. This container. Not from the README, not inferred.
+
+If you're about to write the skill and you don't have (1), **stop.** You
+are about to paraphrase existing docs. That document already exists —
+it's called the README, and the whole reason you're here is that it
+wasn't enough.
+
+## The deliverables are code AND docs
+
+Typical output is a skill directory containing both:
+
+```
+<unit>/skills/run-<unit>/
+  SKILL.md         ← SHORT. Points at the driver. Has the frontmatter
+                     that lets the agent auto-load it when someone asks
+                     to "run <unit>" or "screenshot <unit>".
+  driver.mjs       ← (or driver.py, smoke.sh, … — or none: web apps
+                     use browser-cli off-the-shelf, and the heredoc
+                     in SKILL.md is the script)
+```
+
+The driver lives **inside the skill directory** by default. They are a
+pair — the skill's instructions and the code that implements them. A
+driver that lives here is allowed to be a bit messier than production
+code; it's agent tooling, not product surface.
+
+**Graduation:** if the driver grows into something the project's own
+test suite wants to reuse — shared launch helpers, a real e2e harness —
+move it to `scripts/` or `e2e/` and update `SKILL.md` to reference the
+new path. The skill stays; the driver finds a better home.
+
+The exact shape depends on the project, but the principle is constant:
+**the driver is the deliverable.** The `SKILL.md` is its man page. For
+a web app, the driver already exists — `browser-cli`
+(see the `run` skill's browser-driven pattern) — and the skill is
+the script that runs it. For a desktop app
+(see the `run` skill's GUI pattern), the driver is a custom
+REPL under tmux that exposes `launch`/`ss`/`click`/`eval`. For a server,
+the driver is `curl`. Whatever shape it takes, without something that
+reaches into the running app, the skill is a description of a window
+nobody can touch.
+
+## Where the skill goes
+
+The skill lives at `<unit>/skills/run-<unit-name>/`, where
+`<unit>` is the directory for **one deployable thing** — an app, a
+service, a library.
+
+The agent shell **discovers** project skills from nested `skills/`
+directories (discovery root is shell/deployment-configurable - adjust
+paths to where your shell loads project skills): an agent working
+anywhere inside `<unit>` will see
+`/run-<unit-name>` as an available skill, and it auto-loads when the
+request matches its description (e.g. "run the desktop app," "take a
+screenshot of billing").
+
+- **Single-project repo:** `skills/run-<repo-name>/` at repo root.
+- **Large repo with many apps:** one per app, colocated —
+  `apps/billing/skills/run-billing/`,
+  `apps/desktop/skills/run-desktop/`.
+- **App with multiple binaries:** still **one** skill at the app's
+  root with a section per binary. They share setup. Start from the
+  closest single-binary example and add a `## Run: <name>` section
+  per binary.
+
+If you're not sure where the unit boundary is, **ask the user.**
+
+Slugify the directory name: lowercase, dashes for spaces, no slashes
+(`run-billing-api`, not `run-billing/api`). The directory name and
+the frontmatter `name:` should match — that's the slash command.
+
+## Process
+
+### 0. Find any existing skill about running this app
+
+List the project's skills with their descriptions (same probe `/run`
+uses — users name these variously, so match on description, not name):
+
+```bash
+d=$PWD; while :; do
+  grep -Hm1 '^description:' "$d"/skills/*/SKILL.md 2>/dev/null
+  [ -e "$d/.git" ] || [ "$d" = / ] && break
+  d=$(dirname "$d")
+done
+```
+
+If one is about launching/driving this app — whatever it's named —
+**refine, don't rewrite**: verify its claims, fix what's wrong, add
+what's missing, preserve what works. Re-run the driver if there is
+one. Keep its existing name.
+
+If none exists, decide where to create it (see above) and continue.
+
+### 1. Discover — and treat every claim as disprovable
+
+Figure out what you're authoring for:
+
+- Manifest right here (`package.json`, `go.mod`, `pyproject.toml`…) and
+  it's one self-contained thing → this is the unit.
+- Looks like a mega-repo root (`apps/`, `packages/`, `services/`) →
+  **ask which one.** List candidates, let them pick, `cd` there.
+- Genuinely ambiguous → ask.
+
+Survey the usual places: `README.md`, `package.json` scripts,
+`Dockerfile`, `Makefile`, `.github/workflows/`, `CONTRIBUTING.md`. CI
+configs are often more accurate than READMEs.
+
+**Every claim in existing docs is a hypothesis.** Especially the
+negative ones:
+
+| When docs say… | What you do |
+|---|---|
+| "Requires macOS/Windows" | Launch it on Linux anyway. Apps rarely refuse to start — they crash on a missing `.so`, which `apt-get` fixes. Native modules for *your host's* keychain/notifications may no-op; the core usually runs. |
+| "Requires a GPU" | Try software rendering. Electron/Chrome fall back with `--disable-gpu`. |
+| "Requires a paid account / feature flag" | The gate is code you can read. Find it (env var? build define? SSR-embedded JSON?) and patch it for your local run. Document the patch. |
+| "Run `npm start`" | That's the human path (spawns a window, waits forever). Find or build the *programmatic* path — `electron-forge start` to build then launch via Playwright, or equivalent. |
+
+"Not supported on Linux" in a README written by a macOS developer
+means "I never tried." You're about to try. **If you give up here, the
+skill you write is the README with extra steps.**
+
+### 2. Execute — and BUILD the harness you need
+
+You're in a headless Linux container. The app is going to fight you.
+That fight is the content of the skill.
+
+Keep a running `NOTES.md` as you go. Every error → every fix → every
+command that finally worked. This scratchpad becomes the
+Troubleshooting section.
+
+**Work up to a real interaction:**
+
+- **Install + build.** When something's missing, note the exact
+  `apt-get` / `npm install` that fixed it.
+- **Launch the app.** Not the test suite — the app. A desktop GUI
+  (Electron, native) needs `xvfb-run` and a handful of `lib*`
+  packages; a web app driven by `browser-cli` runs headless and
+  needs neither. Launch timeouts and cryptic crashes are normal at
+  this stage. Read the stack trace, install the missing thing, try
+  again.
+- **Build a harness to drive it.** You need a handle on the running
+  app that lets you send input and observe output programmatically.
+  The shape depends on the project (see table below).
+
+  **Cover the layer(s) PRs actually touch.** A tmux driver that pokes
+  the CLI's user surface is the right handle for UI changes — and the
+  wrong one for a PR that touches one internal function. For the
+  latter an agent wants `NODE_ENV=test bun run script.ts` (or
+  equivalent): import the function, call it, observe. If most PRs
+  here touch internals, that direct-invocation path is the driver's
+  main entry point, and the tmux launch is secondary. Look at recent
+  merged PRs: what layer do they touch? Cover that.
+
+  For a **web** app, `browser-cli` is the driver — you script it,
+  you don't write it (see the `run` skill's browser-driven pattern).
+  For a **desktop** GUI (Electron), write a REPL driver (stdin
+  commands → click/type/screenshot), run it inside tmux, and use
+  `send-keys` / `capture-pane`. You will iterate on that driver — it
+  starts minimal (`launch`, `ss`, `quit`) and grows whatever commands
+  you need to reach the interesting part of the app.
+- **Do one real user flow end-to-end.** Click the button. Fill the
+  form. See the result in the DOM. Take a screenshot. **Actually look
+  at the screenshot.** If it's blank or showing an error page, you're
+  not done.
+- **Then run the tests.** Unit tests are a sanity check, not the main
+  event.
+- **Stop cleanly.**
+
+**Obstacles are content.** You will hit weird ones — coordinate systems
+that don't line up, APIs that return empty on this Electron version,
+feature gates that hide the thing you need to test. Each of these gets
+a bullet in Gotchas and (often) a helper in your driver. The gold
+standard is a Gotchas section full of things nobody could have guessed.
+
+**The driver script gets committed alongside the skill.** It is not
+scaffolding. It is the way future agents (and humans) will drive this
+app. It defaults to living inside the skill directory (for a web app
+using `browser-cli`, that means inline in `SKILL.md` — the heredoc
+is the script). If it outgrows that — if the project's real test
+suite wants to import from it — move it to `scripts/` or `e2e/` and
+update `SKILL.md` to point there.
+
+### 3. Write SKILL.md
+
+Short. Point at the driver. Use the template in the Appendix at the end of this document as the
+starting structure — it has the frontmatter shape.
+
+**The frontmatter matters.** The `name:` becomes the slash command
+(`/run-billing`). The `description:` is what the agent scans to decide
+whether to auto-load this skill — put the **verbs an agent would
+actually type** in it: "run," "start," "build," "test," "screenshot."
+Generic descriptions ("helpful utilities for billing") won't match.
+
+Body structure:
+
+1. One-paragraph intro: what this app is, how it's driven —
+   `<driver-path>` under xvfb/tmux for desktop, `browser-cli` for
+   web, `curl` for a server.
+2. **Prerequisites** — the exact `apt-get install` line you ran.
+3. **Build** — the exact commands, in order. Include any patches you
+   had to apply (feature gates, config overrides) with the exact `sed`
+   or edit.
+4. **Run (agent path)** — FIRST. How to launch the driver, what
+   commands it accepts, where screenshots land. If it's a REPL, show
+   the tmux wrapping. This is the section the next agent will actually
+   use.
+5. **Run (human path)** — SECOND, if different. `npm start` → window
+   opens → Ctrl-C. Brief. Note that it's useless headless.
+6. **Gotchas** — the battle scars. The things that look like they
+   should work but don't, and the workaround. If this section is
+   generic, you didn't fight hard enough.
+7. **Troubleshooting** — symptom → fix. Only errors you actually hit.
+
+Keep it **verified** (you ran it), **prescriptive** (one path, not
+options), **honest** (flaky? slow? say so).
+
+**Paths in SKILL.md are relative to `<unit>/`,** not to the skill
+directory. State this at the top if there's any ambiguity. When the
+driver lives inside the skill, its path from `<unit>` is
+`skills/run-<unit-name>/driver.mjs` — it's long, but explicit.
+
+### 4. Verify
+
+Fresh shell, `cd` into the unit, follow the skill's `SKILL.md`
+line-by-line without deviating. Any improvisation = a gap. Fix it.
+
+## Project-type patterns
+
+Pick a starting shape for your driver. These per-project-type patterns
+are shared with the `run` skill (they are its fallback when no
+project-specific run skill exists) — if you're authoring a new one,
+start from the matching pattern documented there.
+
+| Project type | Driver shape |
+|---|---|
+| Web server / API | Background-launch + `curl`-based smoke script |
+| CLI tool | Representative-args smoke script, check exit codes + output |
+| TUI / interactive terminal | tmux wrapper: `send-keys` / `capture-pane` |
+| Electron / desktop GUI | Playwright `_electron` REPL driver under xvfb, screenshots, tmux-wrapped |
+| Browser-driven | dev server + `browser-cli` script |
+| Library / SDK | Import-and-call smoke script |
+
+For a web app, start from the `run` skill's browser-driven pattern —
+drive it with `browser-cli`, no custom driver needed. For a desktop
+app, write a Playwright `_electron` REPL driver (launch/ss/click/eval
+commands over stdin), run it under xvfb inside tmux, and grow it as
+you fight the app.
+
+## What to include
+
+- **Prerequisites** — OS packages, runtimes, tools. Ubuntu `apt-get`
+  lines. The exact ones.
+- **Setup** — install deps, configure, any patches.
+- **Build** — compile/bundle.
+- **Run (agent path)** — the driver. Commands. Screenshot location.
+- **Direct invocation** — if callable: how to import and run internal
+  code without the full app. The env var / flag that bypasses init
+  guards. Many PRs need only this.
+- **Run (human path)** — if meaningfully different.
+- **Test** — the test suite command.
+- **Gotchas** — non-obvious traps you hit.
+- **Troubleshooting** — error → fix.
+- **The driver itself** — committed in the skill dir (or graduated
+  to `scripts/`/`e2e/`), or inline in `SKILL.md` for `browser-cli`
+  web apps; referenced from `SKILL.md` either way.
+
+## What to leave out
+
+- **Anything you didn't run.** If the README says `yarn start:prod` and
+  you never ran it, it's not in the skill. Full stop.
+- **Documented happy paths for platforms you're not on.** You're in a
+  Linux container. A macOS-only section you can't verify is
+  speculation. Mention it exists; don't elaborate.
+- **Exhaustive options.** One working path.
+- **Architecture prose.** That's other docs.
+- **Generic troubleshooting.** "If the build fails, check your Node
+  version" — useless. Only include errors you actually hit and fixed.
+
+## Red flags — you are about to ship the wrong thing
+
+Stop and reconsider if:
+
+- **You haven't taken a screenshot** of a GUI app. You didn't run it.
+- **Your skill has no driver/smoke script** to point at, and the app
+  is interactive. The next agent has no way to drive it. (Web app
+  using `browser-cli`? — the heredoc in `SKILL.md` is the driver;
+  no separate file needed.)
+- **Your skill reads like the README.** Same structure, same
+  commands, same caveats. You paraphrased.
+- **Your Troubleshooting section is generic.** Real execution produces
+  specific, weird errors. Generic errors = you didn't execute.
+- **You wrote "not supported on this platform"** without trying to
+  launch it. The README author was on a Mac. You are not. Try.
+- **Everything worked first try.** Either this project is trivially
+  simple, or you ran the test suite and called it done.
+
+---
+
+## Appendix — template.md
+
+````markdown
+---
+name: run-<unit-name>
+description: Build, run, and drive <unit-name>. Use when asked to start <unit-name>, run its tests, build it, take a screenshot of its UI, or interact with the running app.
+---
+
+<One-sentence description: what this is and how an agent drives it.
+Name the handle here — "drive it via
+`skills/run-<unit-name>/driver.mjs` under xvfb" for a desktop
+app, or "start the dev server then drive it via `browser-cli`" for a
+web app — so an agent knows where to look first.>
+
+<If the unit isn't at repo root:>
+All paths below are relative to `<unit-dir>/`.
+
+## Prerequisites
+
+<System-level requirements. The exact `apt-get install` line you ran —
+not a generic list, the one that actually worked. Target Ubuntu.>
+
+```bash
+sudo apt-get update
+sudo apt-get install -y <packages-you-actually-installed>
+```
+
+<Runtime versions if they matter:>
+
+```bash
+# Example: Node 20 via nvm, Python 3.12 via uv, etc.
+```
+
+## Setup
+
+<One-time setup after clone: install deps, configure, apply any
+patches (feature-gate overrides, config stubs) with the exact command.>
+
+```bash
+<commands>
+```
+
+<Env vars — required vs optional, with sensible defaults:>
+
+```bash
+export FOO_API_KEY=...   # required — get from <where>
+export BAR_MODE=dev      # optional — default is prod
+```
+
+## Build
+
+<Skip if no separate build step. Otherwise the exact command:>
+
+```bash
+<command>
+```
+
+## Run (agent path)
+
+<This is the section a future agent actually uses. If you built a
+driver/REPL/smoke script, this documents how to launch it and what it
+does. If the app is simple enough that `curl` or a one-liner suffices,
+that one-liner goes here.>
+
+```bash
+<launch-the-driver-or-smoke-script>
+```
+
+<For REPL-style drivers, show the tmux wrapping. Poll for a ready marker
+between send-keys and capture-pane — faster than a fixed sleep and fails
+loudly instead of capturing a half-rendered screen:>
+
+```bash
+tmux new-session -d -s app -x 200 -y 50
+tmux send-keys -t app '<launch command>' Enter
+timeout 30 bash -c 'until tmux capture-pane -t app -p | grep -q "<ready-marker>"; do sleep 0.2; done'
+tmux send-keys -t app '<first driver command>' Enter
+tmux capture-pane -t app -p
+```
+
+<Where artifacts land (screenshots, logs) — absolute paths:>
+
+Screenshots → `/tmp/shots/`. Logs → `/tmp/<app>.log`.
+
+<If the driver has commands, a table:>
+
+| command | what it does |
+|---|---|
+| `<cmd>` | <description> |
+
+## Run (human path)
+
+<If meaningfully different from the agent path. Brief — agents won't
+use this, humans can figure it out.>
+
+```bash
+<command>   # → <what happens>. <how to stop>.
+```
+
+## Test
+
+```bash
+<command>
+```
+
+<Expected result — "N suites pass", or specific known-flaky tests.>
+
+---
+
+<Optional sections below — include only if relevant and only with
+content you actually hit, not generic advice.>
+
+## Gotchas
+
+<Non-obvious traps. The things that look like they should work but
+don't, with the workaround. If this section is generic, delete it.>
+
+- **<specific thing>** — <why it breaks> → <what to do instead>
+
+## Troubleshooting
+
+<Symptom → fix. Only errors you actually encountered.>
+
+- **<exact error message or symptom>**: <cause>. <fix>.
+
+<---
+
+NOTE ON THE FRONTMATTER ABOVE:
+- Replace <unit-name> in both `name:` and `description:`. The `name:`
+  becomes the slash command (/run-<unit-name>) and must match the
+  directory name.
+- The `description:` is what the agent scans to decide whether to load this
+  skill automatically. Keep the verbs — "start," "run," "build," "test,"
+  "screenshot" — they're what an asking agent will actually type.
+
+NOTE ON THE DRIVER:
+- If you wrote a driver script, it lives in this same directory (next
+  to this file) by default. Reference it from the Run section.
+- For a web app there's usually no driver file — the `browser-cli`
+  heredoc in the Run section is the harness.
+- If the driver grows into something the project's test suite wants —
+  shared launch helpers, a real e2e harness — move it to scripts/ or
+  e2e/ in the unit, and update the paths here. The skill stays put.
+
+Delete everything from `---` above onwards before committing. --->
+````

package/skills/run.md

@@ -0,0 +1,148 @@
+---
+name: run
+description: Launch and drive this project's app to see a change working. Use when asked to run, start, or screenshot the app, or to confirm a change works in the real app (not just tests). First looks for a project-provided launch recipe; otherwise falls back to built-in patterns per project type (CLI, server, TUI, desktop GUI, browser-driven, library).
+---
+
+**Running means launching the actual app and interacting with it** —
+not the test suite, not an `import` of an internal function and a
+`console.log`. The app as a user (human or programmatic) would meet
+it: the CLI at its command, the server at its socket, the GUI at its
+window.
+
+## First: does a project recipe already cover this?
+
+A project-provided recipe that launches this app is the repo's
+verified path — its author already cold-started and committed what
+worked: the exact install line, the env vars, the patches, the
+driver. Use it instead of rediscovering. Look in, roughly in order:
+
+- your available skills (a launch/verify recipe for this project or
+  this kind of app);
+- the repo's own entry points: README "getting started", Makefile /
+  justfile targets, package.json scripts, docker-compose files,
+  CI workflow steps that boot the app.
+
+- **One describes launching/driving this app** → follow it verbatim.
+  Don't paraphrase; don't skip the patches.
+- **Mega-repo, several plausible, no clear match** → ask the user
+  which unit to run.
+- **Stale** (fails on mechanics unrelated to your task) → tell the
+  user; offer to refresh it.
+- **Nothing about running** → fall back to the patterns below.
+
+## Otherwise: match the shape, use the pattern
+
+Pick the row closest to your project.
+
+| Project type | Handle | Pattern |
+|---|---|---|
+| CLI tool | direct invocation, exit code, stdin/stdout | invoke it below |
+| Web server / API | background launch + `curl` smoke | lifecycle below |
+| TUI / interactive terminal | tmux `send-keys` / `capture-pane` | tmux pattern below |
+| Desktop GUI | drive it headless (xvfb + an automation driver), screenshot | adapt the browser pattern |
+| Browser-driven web app | dev server + headless browser script | browser pattern below |
+| Library / SDK | import-and-call smoke script at the package boundary | library pattern below |
+
+If nothing fits, start from the closest match and adapt.
+
+### CLI
+
+No lifecycle, no ports. Get the binary runnable (build, or install in
+editable/dev mode so it lands on PATH), confirm with `--version` or
+`--help`, then run a representative command and check exit code and
+output:
+
+```bash
+mytool process input.json
+# → Processed 42 records, wrote output.json
+echo $?   # meaningful exit codes are part of the interface
+```
+
+If the tool reads stdin, pipe test data in.
+
+### Web server / API
+
+Start in the background with logs captured, poll for readiness (never
+a fixed sleep), then hit the routes:
+
+```bash
+<start-command> &> /tmp/server.log &
+SERVER_PID=$!
+for i in {1..30}; do curl -sf localhost:PORT/health >/dev/null && break; sleep 1; done
+curl -si localhost:PORT/api/thing      # status + headers + body
+kill $SERVER_PID
+```
+
+No health endpoint? Poll the route you're about to test until it
+stops returning connection-refused.
+
+### TUI / interactive terminal app
+
+Interactive terminal apps (editors, REPLs, curses UIs) take over the
+terminal — you can't drive them directly from a shell tool. Wrap them
+in tmux: start detached, send keystrokes, capture the pane, kill the
+session when done.
+
+```bash
+tmux new-session -d -s app -x 120 -y 40 './myapp'
+
+# poll until the ready marker appears (fails loudly if it never does)
+timeout 10 bash -c 'until tmux capture-pane -t app -p | grep -q "Ready"; do sleep 0.2; done'
+tmux capture-pane -t app -p
+
+# send input and wait for the screen to reflect it
+tmux send-keys -t app 's'
+timeout 5 bash -c 'until tmux capture-pane -t app -p | grep -q "Settings"; do sleep 0.2; done'
+tmux send-keys -t app 'Down' 'Down' 'Space'
+tmux capture-pane -t app -p
+
+# quit
+tmux send-keys -t app 'q'
+tmux kill-session -t app 2>/dev/null || true
+```
+
+Details that matter: pick a known-good terminal size (`-x`/`-y` —
+some TUIs break at small widths); poll for a ready string rather than
+sleeping; learn the app's keybindings (they're its API); always
+`kill-session` as a fallback exit. If `capture-pane` output is hard
+to read, `-e` keeps escape sequences and `-J` joins wrapped lines.
+Use a private socket (`tmux -L name`) so you don't collide with other
+sessions on the box.
+
+### Browser-driven web app
+
+Start the dev server (background + readiness poll, as above), then
+drive the page with a headless browser script (e.g. Playwright):
+navigate, click the flow the change touches, screenshot. **Look at
+the screenshot** — a blank frame is a failure to launch, not a pass.
+
+### Library / SDK
+
+There's no process to start. "Running" it is: build from source, then
+a minimal smoke program that imports the library **through its public
+package boundary** and does one real thing:
+
+```bash
+python -c '
+from mylib import Client
+print(Client().ping())
+'
+# → pong
+```
+
+## Drive it, don't just launch it
+
+Launching with no interaction proves the entrypoint resolves. That's
+not running the app — it's typechecking with extra steps. Drive it to
+a point where a user would see something:
+
+- CLI → type a representative command, check the exit code and output.
+- Server → hit the route the diff touches with `curl`, read the body.
+- TUI → `send-keys` a navigation, `capture-pane` the result.
+- GUI → click the button, screenshot the window. **Look at the
+  screenshot.** A blank frame is a failure to launch.
+
+If the fallback pattern didn't work out of the box — you had to
+install packages, set env vars, patch config, or write a driver —
+record the exact recipe that worked in your report so it can be
+captured as a project skill. If it just worked, don't.

package/skills/schedule.md

@@ -0,0 +1,48 @@
+---
+name: schedule
+description: Create, list, or delete scheduled tasks that fire on a cron schedule, at an absolute time, or after a delay, via the sema scheduler. - When the user wants to schedule recurring work ("every morning run X"), a one-time reminder ("remind me at 3pm", "in 30 minutes check Y"), or to inspect/cancel existing scheduled tasks. Tasks run locally through the sema scheduler daemon, not in a cloud service.
+---
+
+# /schedule — sema scheduled tasks
+
+sema schedules work through three engine tools backed by the local scheduler daemon: `CronCreate`, `CronList`, `CronDelete`. There are no cloud routines: a scheduled task fires on THIS machine while sema's scheduler daemon is running, in a fresh unattended run — it will not see this conversation.
+
+## Creating a task: CronCreate
+
+Parameters:
+
+- `prompt` (string, required): fully self-contained instructions for the future task. It runs unattended — inline every path, id, and acceptance criterion it needs; never reference "the file we discussed".
+- `schedule` (union, required) — pick the kind by intent:
+  - Recurring: `{ "kind": "cron", "expr": "M H DoM Mon DoW" }` — standard 5-field cron in the user's LOCAL timezone (a 6-field form with leading seconds is also accepted). `"0 9 * * *"` means 9am local; no timezone conversion needed.
+  - One-shot at a wall-clock time: `{ "kind": "at", "atMs": <epoch ms> }`.
+  - One-shot after a delay: `{ "kind": "delay", "delaySec": <seconds> }`.
+- `label` (string, optional): short name. Also the dedup key — creating again with the same schedule+label upserts (idempotent), so use a stable label when updating a task instead of piling up duplicates.
+
+Examples:
+
+- "check the deploy in 30 minutes" → `{ "kind": "delay", "delaySec": 1800 }`
+- "tomorrow at 8:57am run the smoke test" → `{ "kind": "at", "atMs": <epoch ms of that local time> }`
+- "every 5 minutes" → `{ "kind": "cron", "expr": "*/5 * * * *" }`
+- "weekdays around 9am" → `{ "kind": "cron", "expr": "57 8 * * 1-5" }`
+
+**Avoid the :00 and :30 minute marks when the request is approximate.** Every user who asks for "hourly" gets `0 *`, so the fleet stampedes on the hour. Nudge a few minutes early or late (`7 * * * *`, `57 8 * * *`) unless the user names an exact time and clearly means it.
+
+Invalid cron expressions are rejected with a specific field error, including calendar-impossible dates ("Feb 31") that would never fire — fix and retry rather than switching kinds.
+
+## Inspecting and cancelling
+
+- `CronList` (no parameters): lists your scheduled tasks — `id`, human-readable schedule, `label`. It deliberately does NOT return each task's prompt (security boundary); track what a task does via its label.
+- `CronDelete` with `{ "id": "<id from CronCreate/CronList>" }`: cancels a task. Idempotent — deleting an already-gone id reports that instead of erroring.
+
+## Execution model and limits
+
+- **Backend**: the sema shell scheduler daemon persists tasks to `scheduled_tasks.json` under the sema config home (`SEMA_CONFIG_DIR`, default `~/.sema`), so durable tasks survive shell restarts; the daemon polls the store and launches each firing as a new unattended run.
+- **Scope isolation**: list/cancel only see tasks in your own scope; the task runs as the principal that scheduled it (pinned at schedule time — a task cannot escalate privileges).
+- **Default caps** (deployment-tunable): at most 32 scheduled tasks per scope, minimum delay 10s, minimum cron interval 60s, scheduling horizon 30 days.
+- **Locality caveat**: if the machine (or the scheduler daemon) is off at fire time, the task does not run in a cloud fallback. Tell the user this when they schedule something that clearly assumes an always-on service.
+
+## When NOT to use this
+
+- One-off work the user wants NOW — just do it.
+- Recurring-interval loops phrased as "/loop" or "keep checking X" — use the loop skill, which layers parsing and self-pacing (ScheduleWakeup) on top of these same tools.
+- Fleet/server-side scheduling for TOB deployments — that is service-plane configuration, not a session tool call.