docs: document system skills, models recommended, deploy list/show, worker token (#5350)

Fill six documentation gaps: system skills concept in docs/AGENTS.md, nodetool models recommended flags in docs/cli.md, deploy list/show and worker token in docs/cli.md, and NODETOOL_SYSTEM_SKILLS_DIR env var in docs/configuration.md.

Author: claude[bot]

docs/AGENTS.md

@@ -391,6 +391,41 @@ injects selected content into the system prompt under an `# Agent Skills`
 header. Trusted sandbox-pack skills are merged into the same available-skill
 set for the session.
 
+### System Skills
+
+A **system skill** ships with the build instead of living in a row. It is a
+`SKILL.md` — YAML frontmatter naming it, Markdown body — under a directory that
+carries its name, in `packages/system-skills/` in a checkout and staged to
+`_skills/` beside the bundled `server.mjs` in the desktop app and the Docker
+image. `NODETOOL_SYSTEM_SKILLS_DIR` overrides both roots
+([Configuration](configuration.md#environment-variables-index)).
+
+```markdown
+---
+name: launch-commercial
+description: Turn a product page URL into a finished launch commercial — ... Use when someone asks for an ad, a launch spot, a promo or a commercial from a product page or website.
+---
+
+# Product Page → Launch Commercial Agent
+
+You are a single agent. Your job: …
+```
+
+The `description` is what auto-select matches an objective against, so it says
+*when* the skill applies, not what it contains.
+
+`list_skills` and `load_skill` serve both tiers, so a system skill reaches the
+model exactly the way a user skill does. The difference is that it is read-only:
+`create_skill`, `update_skill`, and `delete_skill` refuse a shipped name, naming
+the verb they refused — `"<name>" is a system skill that ships with NodeTool and
+cannot be overwritten. Pick another name; load_skill still reads it.`, and
+likewise `edited`, `renamed over`, and `deleted`. A user row that already held
+the name predates the reservation and wins — reserving names only stops new ones.
+
+Nothing imports these files, so `packages/system-skills` is not a workspace and
+npm links nothing. A file whose frontmatter is missing or malformed, or whose
+`name` disagrees with its directory, is skipped rather than failing the catalog.
+
 ### Skill Resolution
 
 - **Explicit** — pass `skills: ["skill-a"]` in the agent constructor.

docs/cli.md

@@ -1192,6 +1192,42 @@ nodetool models ollama
 nodetool models by-provider openai --kind image
 ```
 
+#### `nodetool models recommended`
+
+The curated shortlist — what to reach for when you want a model id that is known
+to work, rather than everything a provider will sell you. It reads the shipped
+`RECOMMENDED_MODELS` table in-process, so it needs no server, no API key, and no
+network.
+
+- `--category <category>` — one of `all` (default), `image`,
+  `image-text-to-image`, `image-image-to-image`, `language`,
+  `language-text-generation`, `language-embedding`, `asr`, `tts`,
+  `video-text-to-video`, `video-image-to-video`. An unknown value exits `1`
+  listing the valid ones.
+- `--system <darwin|linux|windows>` — keep only models that run on that
+  platform. A model that declares no platforms is kept for all of them.
+- `--limit <n>` — cap the results. Applied after both filters; a value that is
+  not a positive integer exits `1`.
+- `--check-servers` — fetch the list from a running server instead, which also
+  probes whether the local Ollama and llama.cpp servers can serve each entry.
+  This is the only mode that uses `--api-url` (default `http://localhost:7777`,
+  or `NODETOOL_API_URL`).
+- `--json` — the full model records rather than the five-column table.
+
+```bash
+# The top of the curated list, no network
+nodetool models recommended --limit 3
+
+# What to embed with
+nodetool models recommended --category language-embedding
+
+# What a Mac can actually run, machine-readable
+nodetool models recommended --system darwin --json
+
+# Which of them a local Ollama has pulled
+nodetool models recommended --check-servers
+```
+
 ### `nodetool models` — HuggingFace Hub and cache
 
 Five subcommands search the Hub and manage the local HuggingFace cache. They
@@ -1425,6 +1461,27 @@ nodetool deploy logs my-server --follow --tail 200
 nodetool deploy edit
 ```
 
+`list` and `show` answer the two questions you have before naming a target in
+any of the other verbs, and they are the pair to reach for when you have
+inherited a `deployment.yaml` you did not write.
+
+`list` queries each configured target for its live state and prints one row per
+deployment — `name`, `type`, `status`, `last_deployed`, `host`, `container`,
+`pod_id`, `project`, `region`, `service`. With none configured it prints
+`(no deployments configured)`; `--json` gives the same rows for a script.
+`show <name>` reads the file only, printing that one target's config as YAML —
+no remote call, so it works while the host is down.
+
+```bash
+nodetool deploy list
+nodetool deploy list --json
+nodetool deploy show my-server
+```
+
+Both need the file to exist. Without it they exit non-zero with
+`Deployment configuration not found at <path>. Run 'nodetool deploy init' to
+create it.`
+
 The full server walkthrough is [Deployment](deployment.md) and
 [Self-Hosted Deployment](self-hosted-deployment.md).
 
@@ -1506,6 +1563,19 @@ nodetool worker status <instance-id>
 nodetool worker stop --all
 ```
 
+`token <id>` prints one worker's bearer token and nothing else — no table, no
+label — so it pipes into the variable the bridge reads:
+
+```bash
+export NODETOOL_WORKER_TOKEN=$(nodetool worker token <instance-id>)
+```
+
+`list` withholds tokens on purpose; this is the one command that decrypts one,
+and only for the worker you name. Reach for it when a second shell, a CI step,
+or a `--api-url` client has to talk to a worker `--attach` did not configure. A
+worker that carries no token is an error rather than empty output:
+`Worker instance '<id>' has no token (open worker).`
+
 The full walkthrough, including what `--attach` changes locally, is
 [Worker Deployment](worker-deployment.md).
 

docs/configuration.md

@@ -560,6 +560,7 @@ missing binary.
 | `NODETOOL_VIDEO_FRAME_MAX_FPS` | Ceiling on the frame sample rate | no | Default `1`. A clip too long for the frame budget to reach this rate is sampled more sparsely, so the frames still span it |
 | `NODETOOL_VIDEO_FRAME_MAX_DIMENSION` | Longest edge of a sampled frame, in pixels | no | Default `768`. Frames are never upscaled |
 | `NODETOOL_SHIPPED_PACKS_DIR` | Roots the sandbox packs that ship with NodeTool are read from | no | Comma-, semicolon-, or `PATH`-separator-delimited, same as `NODETOOL_PACK_SEARCH_PATHS`. Candidates that do not exist are dropped, so a bad path yields no packs rather than an error. Unset, the loader looks for `_sandbox/` beside the bundled `server.mjs` (packaged desktop app, Docker image), then walks up to `packages/sandbox-packs` (a checkout). Set it only for a host that stages the packs somewhere else. See [Sandbox package design](sandbox-package-design.md) |
+| `NODETOOL_SYSTEM_SKILLS_DIR` | Root the system skills that ship with NodeTool are read from | no | One path, not a list. Unset, the loader looks for `_skills/` beside the bundled `server.mjs` (packaged desktop app, Docker image), then walks up to `packages/system-skills` (a checkout). A path that does not exist means no system skills rather than an error, and so does an unset variable in a build that ships none. Each skill is a `SKILL.md` under a directory that names it — a frontmatter `name` disagreeing with the directory is skipped, as is a file that cannot be parsed. Read once per process. Set it only for a host that stages the skills somewhere else. See [Agent Architecture › Skills](AGENTS.md#skills) |
 | `NODETOOL_SANDBOX_INPROC` | Run every QuickJS guest on the calling thread instead of a worker | no | `1` only. A chosen fallback, so it warns about nothing. A CPU-bound guest then blocks the thread — on the server's main thread that freezes the event loop, including the frame that would have cancelled the run. See [JavaScript sandbox threading](#javascript-sandbox-threading) |
 | `NODETOOL_SANDBOX_WORKER` | Require the sandbox worker path | no | `require` only. A run that cannot reach a worker fails with `the sandbox worker path is required (NODETOOL_SANDBOX_WORKER=require) but unavailable: <reason>` rather than falling back in-process. Runs that stream their inputs never reach a worker, so this fails them |
 | `NODETOOL_GPU_VALIDATE` | Escape hatch for the WGSL linearity validator | no | `off` disables it. The validator rejects a shader module whose WGSL contradicts its declared premultiplied-alpha contract, at module load. Use it to ship a hotfix while the shader is corrected, not as a standing setting; read once per process |