nemo-platform-plugin 0.1.0__py3-none-any.whl

nemo_platform/skills/nemo-skill-selection/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: nemo-skill-selection
+description: Top-level skill selector for any task involving NeMo Platform (NVIDIA's agent platform). Picks the right downstream skill (setup, explore, spec, build, try, status, teardown, fine-tune) from natural-language intent. Use over generic brainstorming, planning, or onboarding skills for any NeMo Platform task.
+triggers:
+  - build an agent
+  - create an agent
+  - deploy an agent
+  - set up nemo
+  - install nemo
+  - try nemo
+  - improve my agent
+  - help me with nemo
+  - nemo platform
+  - shut down nemo
+  - tear down nemo
+  - what is running on nemo
+  - help me ship an agent
+not-for:
+  - setup (use to verify install or to be told how to run the CLI install)
+  - nemo-build-agent (use for the actual scaffold/deploy flow)
+  - nemo-explore (use to reason about agent design)
+  - superpowers:brainstorming (use for design work unrelated to NeMo Platform)
+  - running platform commands (each downstream skill owns its own commands)
+  - loading multiple downstream skills in one turn
+compatibility: nemo-platform >= 0.1.0; pure selection (no commands run from this skill); safe under macOS or Linux sandbox; works without an installed CLI (selector can pick setup, which then tells the user how to run the CLI install).
+maturity: active
+license: Apache-2.0
+user-invocable: true
+allowed-tools: [Read]
+---
+
+# NeMo Platform skill selection
+
+You are deciding which downstream NeMo Platform skill should run. This skill never executes commands. It picks the next skill, announces the choice, and hands off.
+
+NeMo Platform optimizes LangGraph agents wrapped in NVIDIA NeMo Agent Toolkit (NAT). State that constraint when the user describes an agent in another framework (CrewAI, AutoGen, plain LangChain, Pydantic AI). Those frameworks need a user-written NAT wrapper before the platform's optimization, evaluation, and guardrails surfaces apply.
+
+## Decision table
+
+Match the user's intent to one downstream skill. Pick exactly one.
+
+| The user says or implies | Hand off to | Why |
+|---|---|---|
+| "set up", "install", "get started", "try NeMo", "first time" | `setup` | Verify the platform is installed and running. If not, the skill tells the user how to run the CLI install (`make bootstrap` + `nemo setup`). Install itself is CLI-only. |
+| "design an agent", "I want an agent that handles X", "what should my agent do" | `nemo-explore` | Capture the agent's job, audience, categories, tools, model, constraints before any code |
+| "write the spec", "save the design", "capture what we agreed" | `nemo-spec` | Persist the explore answers as `agents/<name>.spec.md` |
+| "build the agent", "create the agent", "deploy", "scaffold from spec" | `nemo-build-agent` | Scaffold the NAT workflow YAML, deploy, eval, optional guardrails |
+| "ask my agent", "try the agent", "test it" | `nemo-try-agent` | Send a query to a deployed agent or fall back to model chat |
+| "status", "what is running", "platform health", "is the platform up", "what's deployed", "show me what's running" | `nemo-status` | Read-only dashboard: platform, agents, providers, models |
+| "shut down", "stop NeMo", "tear down", "clean up" | `nemo-teardown` | Stop the cluster (keep data, delete platform data, or full cleanup) |
+| "fine-tune", "customize the model", "train on my data" | `nemo-fine-tune` | Fine-tuning is not yet available on NeMo Platform. Pick this so the agent tells the user it's not shipped instead of going off to implement training with some other library. |
+| "optimize my agent", "make it cheaper", "reduce latency", "smaller model", "switchyard", "routing split", "compare against a newer model" | `agents-optimize` (plugin-owned, in `plugins/nemo-agents`) | Cost / latency / quality optimization for a **deployed** agent. Routing splits, skill tuning, prompt tuning, new-model scans. |
+| "secure my agent", "harden my agent", "check for PII", "leaked secrets", "guardrail coverage" | `agents-secure` (plugin-owned, in `plugins/nemo-agents`) | Safety and security audit for a **deployed** agent. Guardrails, PII, secrets scan. |
+| "evaluate my agent", "run a benchmark", "eval suite" | `nemo-evaluator` (plugin-owned, in `plugins/nemo-evaluator`) | Evaluation metrics, LLM-judge, benchmark jobs against a deployed agent or model. |
+
+**Optimize vs build:** Do NOT route optimize asks to `nemo-build-agent`. Build is for creating new agents from a spec; optimize is for tuning **already deployed** agents. If the user says "make my agent faster" or "use a cheaper model," that is `agents-optimize`, not `nemo-build-agent`.
+
+If two rows fit, pick the earliest one in the lifecycle (setup before build before try). If nothing matches, ask one disambiguating question with the relevant rows as a numbered list.
+
+## Pre-flight
+
+Before handing off, run a host-wide platform scan. Three signals, in order — the first one that fires wins:
+
+```bash
+# 1. Ground truth: is anything listening on the canonical port?
+lsof -iTCP:8080 -sTCP:LISTEN 2>/dev/null
+
+# 2. Functional check: does the API actually answer?
+curl -fsS http://localhost:8080/v1/models -o /dev/null -w "%{http_code}\n" 2>/dev/null || echo "no-response"
+
+# 3. Conflict check: other platform processes / data dirs / configs on this host?
+ps -eo pid,user,command 2>/dev/null | grep -E "nemo services (run|start)|nemo-platform run" | grep -v grep
+ls -d ~/.local/share/nemo* 2>/dev/null
+ls ~/.config/nmp*/config.yaml 2>/dev/null
+```
+
+Interpretation:
+
+| What you observe | Hand off to | Why |
+|---|---|---|
+| (1) returns a listener AND (2) returns 2xx/4xx | the requested downstream skill | Platform is up and serving. Skip `setup`. |
+| (1) returns a listener but (2) returns `no-response` or 5xx | `nemo-status` | Something is bound to :8080 but the API is wedged. Do not start a second platform. |
+| (1) empty but (3) finds another `nemo services` process OR more than one data dir / config | **stop, do not hand off yet** | Another install on this host, possibly on a different port. Surface the inventory verbatim. Ask whether to tear that one down first, pick a different port + data dir, or abort. Two installs writing to the same `~/.config/nmp/config.yaml` is how users end up with one Studio frontend pointing at the wrong backend. |
+| (1), (2), and (3) all empty | `setup` | Clean machine, no platform installed. |
+
+Read-only callers (this skill, `nemo-status`, the build/try pre-flights) should not trust `nemo services status` or `nemo services ls` as an up-check. Both report stale "running" from a held instance lock after the underlying process has died. The lock reconciles automatically the next time `nemo services run` is invoked, but until that happens, `lsof` is ground truth. (Tracking a CLI-side fix for this so we can drop the workaround from skills.)
+
+## What to announce
+
+Tell the user, in one sentence, which skill is next and what it will do. For example: "Handing off to `setup` to verify the platform is installed and running. If it isn't, the skill will tell you the CLI command to run; install is a 5-minute shell step that this skill cannot do reliably for you."
+
+Then hand off. Do not run any platform commands from this skill.
+
+## If nothing matches
+
+If the user's intent doesn't fit any row, do not guess. Read out the available skills and ask which one they want:
+
+```
+NeMo Platform skills I can route to:
+  setup           verify install or get the CLI install command
+  nemo-explore    design conversation: capture goal, audience, tools, constraints
+  nemo-spec       write the design to agents/<name>.spec.md
+  nemo-build-agent  scaffold the NAT workflow YAML and deploy
+  nemo-try-agent  query a deployed agent or chat with a model
+  nemo-status     read-only platform health dashboard
+  nemo-teardown   guided shutdown
+  nemo-fine-tune  fine-tuning (not yet shipped; reports that honestly)
+
+Plugin-owned skills:
+  agents-optimize   cost / latency / quality optimization for a deployed agent
+  agents-secure     safety and security audit for a deployed agent
+  nemo-evaluator    evaluation metrics, LLM-judge, benchmark jobs
+  guardrails        content-safety middleware via virtual models
+  auditor           red-team vulnerability scanning (garak)
+  data-designer     synthetic dataset generation
+  anonymizer        PII handling for datasets
+
+Which one fits what you're trying to do?
+```
+
+For things outside this catalog (for example, "show me how Switchyard routes between models"), point at the relevant repo skill (`nemo-evaluator`, `nemo-auditor`, etc.) or tell the user no skill claims that intent yet. Do not invent a path.
+
+If the pre-flight finds no platform but the user insists they have installed one: ask them to report the output of `lsof -iTCP:8080 -sTCP:LISTEN` and `ps -eo pid,user,command | grep -E "nemo services|nemo-platform run" | grep -v grep` from the shell where they ran setup. The platform may be bound to a non-default port, or the install may be in a venv whose `nemo` binary is not on `PATH`.
+
+## If the user asks about Studio (web UI)
+
+Skills route through CLI commands, not Studio. But customers ask "what's Studio?" or "do you have a web UI?" Answer honestly, do not invent capabilities, and do not steer users into the experimental flows.
+
+What to say:
+
+- Studio is the NeMo Platform web UI. When the platform is running locally, it serves at `http://localhost:8080/studio`.
+- Documentation: `docs/studio/index.md` in this repo covers the stable views (Agents, Optimizations, Monitor, Workspaces, Datasets). Point users there rather than enumerating features in-conversation — the docs stay up to date, this skill won't.
+- **Honest caveats to flag every time:**
+  - The **Optimizations "Apply suggestion"** flow is **incomplete today**. Suggestions render, but the apply action is not reliable end-to-end. Tell the user to apply optimizer suggestions via the CLI (`nemo agents …`) instead, using the suggestion's `apply` block as the spec — see `agents-optimize`.
+  - Other views may evolve; refer to the docs for the current state rather than promising specific behavior.
+- For local development on Studio itself, the source lives at `web/packages/studio/`. The `studio-dev` skill (if available) covers that workflow.
+
+Do not proactively suggest Studio as the path for anything a skill already covers (chat, deploy, status, teardown, optimization). The CLI path is what these skills verify and what we can confidently support.
+
+## Gotchas
+
+- **One skill at a time.** Do not load more than one downstream skill in the same turn. Each downstream skill is a full procedure with its own context budget.
+- **Install must happen before any skill can do useful work.** Build, try, and status all assume the platform is up. If the user has not run the CLI install (`make bootstrap` + `nemo setup`), the skills cannot work around that; hand them to `setup` for instructions.
+- **NeMo Platform is the product name.** Capital N, e, M, o, P. Not "nemo" or "Nemo." NAT on first mention is "NVIDIA NeMo Agent Toolkit (NAT)."
+- **Fine-tuning is not yet available.** When the user asks to fine-tune, train, or customize a model, pick `nemo-fine-tune` so the agent tells the user it's not shipped instead of trying to wire up training with some other library. Do not run `nemo customization` CLI commands; the backend is not connected.
+- **Framework honesty.** If the user describes an agent in CrewAI, AutoGen, plain LangChain, or Pydantic AI, tell them up front that NeMo Platform's optimization and evaluation surfaces operate on NAT-wrapped LangGraph agents. They will need to wrap their agent before the build path produces value.

nemo_platform/skills/nemo-spec/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: nemo-spec
+description: Captures a NeMo Platform agent spec as a durable artifact at agents/<name>.spec.md. Reads the template, writes the file, shows it to the user for sign-off, then hands off to nemo-build-agent. Use over generic planning skills for any NeMo Platform agent spec.
+triggers:
+  - write the spec
+  - save the design
+  - capture what we agreed
+  - persist the agent design
+  - nemo spec
+  - write agent spec
+not-for:
+  - nemo-explore (use to gather the design before writing the spec)
+  - nemo-build-agent (use to scaffold and deploy once the spec is signed off)
+  - nemo-skill-selection (use for dispatch when intent is unclear)
+compatibility: nemo-platform >= 0.1.0; writes one markdown file under agents/; no network; safe under any sandbox; idempotent if user confirms overwrite.
+maturity: active
+license: Apache-2.0
+user-invocable: true
+allowed-tools: [Read, Write, Edit, Bash]
+---
+
+# NeMo Platform agent spec
+
+Turn the answers from `nemo-explore` into a durable artifact. The spec is the contract `nemo-build-agent` reads to scaffold the NAT workflow YAML. Without it, the build skill has to re-ask everything.
+
+## Pre-flight
+
+Check whether the spec already exists. If so, ask the user whether to overwrite or pick a different name.
+
+```bash
+ls "agents/${NAME}.spec.md" 2>/dev/null && echo "spec_exists" || echo "spec_new"
+```
+
+## What you do
+
+1. **Confirm the agent name.** Lowercase, hyphens, short: `it-helpdesk`, `support-triage`, `code-reviewer`. If the user has not named it, propose two options based on the job.
+
+2. **Validate the name.** Must match `[a-z][a-z0-9-]*`. Reject and re-ask if not.
+
+3. **Write the file.** Path: `agents/<name>.spec.md`. Create the `agents/` directory if it does not exist. Use the template at `references/templates/agent-spec.md`. Read the template before writing so the structure is right.
+
+4. **Fill every section.** No "TBD" in a saved spec. If a section has nothing, leave a one-line note explaining why ("Prompt-only. No tools beyond clock.").
+
+5. **Show the spec to the user.** After writing, print the full file contents and ask: "Does this match what we agreed? Edit anything you want to change."
+
+6. **Hand off.** Once confirmed, tell the user `nemo-build-agent` will read `agents/<name>.spec.md` and produce the workflow YAML.
+
+## Verification
+
+After writing the file, confirm it exists and is non-empty:
+
+```bash
+test -s "agents/${NAME}.spec.md" && echo "spec_written" || echo "spec_missing"
+```
+
+Do not announce success until this check passes and the user has confirmed the contents match what they agreed.
+
+## If verification fails
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `spec_missing` after write | Wrong working directory or permission denied | Run `pwd`, check the user is in the cloned repo; check `~/.config/nmp/` write grant from `nemo-setup` |
+| User says "this is wrong" | Spec captured the wrong answers | Edit the relevant section in place; do not rewrite the whole file |
+| Name validation keeps failing | User keeps proposing names with underscores or capitals | Pin the regex `[a-z][a-z0-9-]*` and show one example that passes |
+| `nemo-explore` was skipped | User invoked `nemo-spec` cold | Route back to `nemo-explore` and return here when the conversation is done |
+
+## What this skill is not
+
+This skill does not produce NAT workflow YAML. The spec is the human-readable design; the YAML is generated downstream by `nemo-build-agent`. Once the agent is deployed, edits go through a re-spec + re-build, not file surgery on the YAML.
+
+## Gotchas
+
+- **The template is the source of truth for structure.** Do not improvise sections. Read `references/templates/agent-spec.md` and follow it.
+- **Spec lives next to the workflow YAML.** Both files end up in `agents/`. Keep them adjacent so a future read of the directory shows design and implementation together.
+- **Names with underscores or capitals break tools.** Validate against `[a-z][a-z0-9-]*`. Reject and re-ask if not.
+- **Do not write the spec until `nemo-explore` has been run.** If the user invokes this skill cold, route them back to `nemo-explore` first.

nemo_platform/skills/nemo-spec/references/templates/agent-spec.md

@@ -0,0 +1,68 @@
+# Agent Spec: <name>
+
+Date: <YYYY-MM-DD>
+Author: <user>
+
+## Job
+
+One sentence describing what the agent does. Concrete, not aspirational.
+
+## Audience
+
+Who talks to it. Internal employees, external customers, developers, etc.
+Affects tone and what is safe to say.
+
+## Categories
+
+Buckets of questions or tasks the agent handles. Aim for 3 to 6.
+
+- <category 1>
+- <category 2>
+- <category 3>
+
+## Tools
+
+Tools the agent calls beyond the model itself. Default: `current_datetime`.
+
+| Tool | Purpose | Credentials needed |
+|---|---|---|
+| current_datetime | clock for time-sensitive answers | none |
+
+If no tools beyond clock, write: "Prompt-only. No tools."
+
+## Model
+
+Inference target. Cloud (NVIDIA Build API) or local NIM. Specific model id.
+
+- Mode: <cloud | host-gpu | byoe>
+- Model: <model id, e.g., nvidia-llama-3-3-nemotron-super-49b-v1>
+
+## Framework
+
+The agent will be wrapped in NVIDIA Agent Toolkit (NAT) as a LangGraph workflow.
+If the source agent is not LangGraph (CrewAI, AutoGen, plain LangChain,
+Pydantic AI), note the wrapper work needed here.
+
+## Constraints
+
+Negative requirements. Things the agent must not do or say.
+
+- <constraint>
+
+## Success criteria
+
+How we know it works. Two or three concrete check questions and the kind
+of answer that counts as a pass.
+
+1. Question: <question text>
+   Pass criteria: <what a good answer looks like>
+
+2. Question: <question text>
+   Pass criteria: <what a good answer looks like>
+
+## Open questions
+
+Anything the user could not answer yet. These are the items `nemo-build-agent`
+will ask before scaffolding.
+
+- <open question>

nemo_platform/skills/nemo-status/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: nemo-status
+description: Read-only dashboard for NeMo Platform. Combines platform health, deployed agents, registered providers, and available models into a single view. Use over generic status checks for any NeMo Platform dashboard request.
+triggers:
+  - platform status
+  - what is running on nemo
+  - how is the platform
+  - show me nemo health
+  - nemo status
+  - check the platform
+  - nemo dashboard
+not-for:
+  - nemo-setup (use to install or start the platform)
+  - nemo-teardown (use to stop the platform)
+  - nemo-try-agent (use to send a query to a deployed agent)
+  - nemo-skill-selection (use for dispatch when intent is unclear)
+compatibility: nemo-platform >= 0.1.0; read-only CLI calls only; no state changes; safe under any sandbox (requires `lsof`, `curl`, and a venv with the `nemo` binary — no Docker); works whether or not the agents plugin is installed (degrades gracefully).
+maturity: active
+license: Apache-2.0
+user-invocable: true
+allowed-tools: [Bash, Read]
+---
+
+# NeMo Platform status
+
+Single dashboard view of the running platform. Read-only. Never modifies state.
+
+## Pre-flight
+
+Confirm the CLI is installed. If `.venv/bin/nemo` is missing, route to `nemo-setup` and stop:
+
+```bash
+[ -x .venv/bin/nemo ] && echo "CLI_OK" || echo "CLI_MISSING"
+```
+
+## What you do
+
+1. **Check platform up-status first; gate everything else on it.** Use a two-step probe — `lsof` for ground truth, then `curl` for a functional check. If either fails, report "platform down," suggest `nemo-setup`, and stop. Do not run the other three commands.
+
+```bash
+# Ground truth: anything listening on :8080?
+lsof -iTCP:8080 -sTCP:LISTEN >/dev/null 2>&1 || { echo "PLATFORM_DOWN (nothing on :8080)"; exit 1; }
+
+# Functional check: API answers?
+HTTP=$(curl -fsS http://localhost:8080/v1/models -o /dev/null -w "%{http_code}" 2>/dev/null || echo "no-response")
+case "$HTTP" in
+  2[0-9][0-9]|4[0-9][0-9]) echo "PLATFORM_UP (HTTP $HTTP)" ;;
+  *)                       echo "PLATFORM_WEDGED (listener present, API returned $HTTP)"; exit 1 ;;
+esac
+```
+
+Do NOT use `nemo services status` or `nemo services ls` for this check. Both report stale "running" state from a held instance lock after the underlying process has died. `lsof` is ground truth.
+
+Only if both probes pass, run the remaining three to capture the other dashboard rows:
+
+```bash
+.venv/bin/nemo agents deployments list 2>/dev/null
+.venv/bin/nemo inference providers list
+.venv/bin/nemo models list | head -10
+```
+
+2. **Present one summary block.** Illustrative format (adapt fields to whatever the CLI returns; do not invent ones the commands above did not produce):
+
+```
+NeMo Platform status
+
+Platform:   running
+Agents:     <count>
+  <name1> active
+  <name2> stopped
+Providers:
+  <name1> available
+Models (10):
+  <model1>
+  <model2>
+```
+
+Use the actual counts and names. If a section is empty, say "none."
+
+3. **Offer drill-downs.** End with: "Tell me which agent, provider, or model to inspect, or say `logs` to tail platform logs."
+
+For drill-downs:
+
+| Drill-down | Command |
+|---|---|
+| Agent details | `.venv/bin/nemo agents get <name>` |
+| Provider details | `.venv/bin/nemo inference providers get <name>` |
+| Model details | `.venv/bin/nemo models get <name>` |
+| Recent logs | `.venv/bin/nemo services logs -n 50` |
+| Log file path | `.venv/bin/nemo services logs --path` |
+| Known service instances on this host | `.venv/bin/nemo services ls` (advisory — see gotcha on stale locks) |
+
+## Verification
+
+Status is itself a verification: the four commands together prove the platform is reachable, the agents plugin is loaded (or not), the provider is registered, and at least one model has been discovered. If any of the four returns an error, surface it in the summary block rather than hiding it.
+
+## If verification fails
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `PLATFORM_DOWN` from probe | Nothing bound to :8080 | Route to `nemo-setup`; do not run the other three commands |
+| `PLATFORM_WEDGED` from probe | Listener exists, API not answering — likely a crashed or partially-started platform | Tail `.venv/bin/nemo services logs -n 100` and surface the error. Common cause is a stale instance lock; the user can clear it with `nemo services stop --force` then re-run `nemo services run`. |
+| `nemo services ls` shows `running` with empty PID/address column | Held instance lock, no live process | Advisory only — trust the `lsof` probe above. Tell the user the lock is stale; offer `nemo services stop --force` to clear it. |
+| `agents deployments list` returns "no such command" | Agents plugin not installed | Note in the summary: "Agents: plugin not installed"; do not fail the dashboard |
+| `inference providers list` empty | Provider not registered | Route to `nemo-setup` Step 4 (configure) |
+| `models list` empty for more than 60s after setup | Model discovery still running | Re-run after 30s; report the wait time |
+| `nemo --version` exits nonzero | CLI broken or partial install | Route to `nemo-setup` Step 3 and reinstall the four workspace packages |
+
+## Gotchas
+
+- **Read-only means read-only.** Never run `create`, `delete`, `stop`, or any state-changing command from this skill, even if the dashboard suggests something is broken. Route to setup or teardown for state changes.
+- **`agents deployments list` requires the agents plugin.** If it returns "no such command", the user has not installed the agents plugin yet; note that explicitly rather than failing silently.
+- **`nemo services status` and `nemo services ls` lie about liveness.** After a `nemo services run` process dies, the instance lock at `~/.local/state/nemo/instances/<scope>.lock` sticks around. Both commands keep reporting `running` against that stale lock with no PID and no address. Always cross-check against `lsof -iTCP:8080 -sTCP:LISTEN` before believing them.
+- **Status is a snapshot.** A model still discovering will show as missing. Re-run after 30 seconds if the user just finished setup.
+- **Use `.venv/bin/nemo`, not bare `nemo`.** Bash sessions do not carry venv activation across calls.

nemo_platform/skills/nemo-teardown/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: nemo-teardown
+description: "Guided shutdown of NeMo Platform. Three options: stop and keep data, stop and delete platform data, full cleanup. Always confirms before destructive action. Use over generic shutdown or cleanup skills for any NeMo Platform teardown task."
+triggers:
+  - shut down nemo
+  - stop the platform
+  - tear down
+  - clean up nemo
+  - destroy nemo
+  - nemo down
+  - nemo teardown
+not-for:
+  - nemo-setup (use to install or start the platform)
+  - nemo-status (use for read-only health)
+  - nemo-skill-selection (use for dispatch when intent is unclear)
+compatibility: nemo-platform >= 0.1.0; uses `nemo services stop` and a targeted `rm -rf` of the platform's data directory (default `~/.local/share/nemo`, overridable via `$NMP_DATA_DIR`); no Docker, no `pkill`, no `rm` outside the chosen data dir or the working folder; idempotent (re-running after platform is already stopped is a no-op).
+maturity: active
+license: Apache-2.0
+user-invocable: true
+allowed-tools: [Bash, Read]
+---
+
+# NeMo Platform teardown
+
+Shut NeMo Platform down cleanly. Always confirm the destructive choice before running it. Default to the safest option when the user delegates.
+
+## Pre-flight (idempotency check)
+
+Use `lsof` as ground truth. Do not trust `nemo services status` or `nemo services ls` — both report stale "running" from held instance locks after the underlying process has died.
+
+```bash
+lsof -iTCP:8080 -sTCP:LISTEN >/dev/null 2>&1 && echo "RUNNING" || echo "ALREADY_STOPPED"
+```
+
+If `ALREADY_STOPPED`: the platform is not serving. There may still be a stale lock under `~/.local/state/nemo/instances/` from a crashed previous run. Tell the user that, and offer:
+
+- Option 3 (full cleanup of venv + `agents/` + data dir) only if they explicitly want it.
+- Otherwise, just clear the stale lock with `nemo services stop --force` so the next `nemo services run` doesn't refuse to start.
+
+## Step 1: Snapshot state (what's about to be affected)
+
+Show the user EVERYTHING that's currently on this platform so they can decide whether to keep it. Don't ask which option they want until they've seen the snapshot.
+
+```bash
+.venv/bin/nemo services ls
+.venv/bin/nemo agents deployments list 2>/dev/null
+.venv/bin/nemo files filesets list 2>/dev/null
+.venv/bin/nemo jobs list 2>/dev/null
+echo "data dir: ${NMP_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/nemo}"
+ls -la "${NMP_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/nemo}" 2>/dev/null | head -20
+```
+
+Surface, in this order, with counts:
+
+- **Deployed agents** — names + statuses. These stop with the platform regardless of option.
+- **Filesets** — eval datasets, eval results (look for names ending `-eval`, `-eval-out-*`, `-kb`, `-artifacts`), uploaded data. **These live in the data directory and are destroyed by options 2 and 3.**
+- **Jobs** — completed or in-flight eval jobs, optimizer runs. Run history also lives in the data directory.
+- **Local files** — list `agents/*.spec.md`, `agents/*.yml`, `agents/*.dd.py`, `agents/*.json`. These are in the working folder and survive options 1 and 2; option 3 deletes them.
+- **Data directory location.** If `$NMP_DATA_DIR` is set, use that. Otherwise default to `~/.local/share/nemo`. Echo the path explicitly so the user can confirm before any wipe.
+- **CLI config (separate file).** `~/.config/nmp/config.yaml` holds the CLI's locally-cached admin email, default model, and `local_services.data_dir`. It is NOT inside the data directory. **None of the three options touches it by default** — a follow-up `nemo setup` reuses the existing config. If the user wants a full clean slate (e.g. switching admin email or data-dir path), surface this file as a fourth optional wipe target during Step 3.
+
+Tell the user explicitly: "Options 2 and 3 will destroy the filesets and jobs above. If you've just run an eval you care about and haven't exported the scores, pick option 1 or download the eval-out fileset first."
+
+## Step 2: Pick an option
+
+Present these three. If the user says "you decide," pick option 1 and announce it.
+
+**Option 1: Stop, keep data.** Service processes go down. **Everything from the snapshot above is preserved on disk**: configs, secrets, providers, agents, deployed-agent definitions, filesets (eval datasets, eval results, KBs), job history, local files. Restart with `nemo services run` (foreground) or `nemo services start` (background) and the platform comes back exactly as it was.
+
+**Option 2: Stop and delete platform data.** Service processes go down. **The data directory at `${NMP_DATA_DIR:-~/.local/share/nemo}` is removed — this destroys the entity-store DB, encryption key, filesets, eval results, job history, secrets, registered providers, deployed-agent definitions, and any data uploaded to the Files service.** Local files under `agents/` and the venv stay on disk. Next `nemo setup` reconfigures from scratch. **Pick this only if the snapshot above has nothing you care about, or you've already exported what you need.**
+
+**Option 3: Full cleanup.** Same as option 2, plus removes the venv and the local `agents/` directory. Local spec files, generated YAMLs, DD configs, and downloaded eval results in `agents/` are also destroyed.
+
+### Exporting before option 2 or 3
+
+If the user wants to wipe the platform but keep eval scores or generated KBs, export the relevant filesets first. For each fileset they want to preserve:
+
+```bash
+.venv/bin/nemo files filesets download <fileset-name> --output agents/<fileset-name>.json
+```
+
+Then option 2 or 3 is safe to run.
+
+## Step 3: Execute
+
+Confirm before running:
+
+> "Running option <N>: <one-line summary>. Proceed?"
+
+Wait for "yes" or equivalent. Then:
+
+**Option 1 — stop only:**
+
+```bash
+# If the platform was started in the background (`nemo services start`), this stops it.
+# If it was started in the foreground (`nemo services run`), the running process is
+# protected; tell the user to Ctrl-C in the terminal where they ran it.
+.venv/bin/nemo services stop || {
+  echo "background stop failed — likely a foreground instance."
+  echo "Ask the user to Ctrl-C the terminal running 'nemo services run',"
+  echo "or pass --force if they explicitly want to kill a foreground process."
+}
+```
+
+If the user confirms they want to kill a foreground instance from this skill (rare; usually they should Ctrl-C in their own terminal), pass `--force`:
+
+```bash
+.venv/bin/nemo services stop --force
+```
+
+**Option 2 — stop + wipe data:**
+
+```bash
+.venv/bin/nemo services stop || true            # tolerate already-stopped
+DATA_DIR="${NMP_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/nemo}"
+# Safety guard: refuse to wipe obviously-unsafe paths (empty, root, $HOME, cwd).
+# Catches accidental NMP_DATA_DIR misconfigurations before they delete user data.
+case "$DATA_DIR" in
+  ""|"/"|"$HOME"|"$HOME/"|"."|"./"|"$PWD"|"$PWD/")
+    echo "REFUSING_UNSAFE_DATA_DIR: '$DATA_DIR' — abort"; exit 1 ;;
+esac
+# Verify the platform is fully down BEFORE wiping; otherwise the running process keeps
+# its file descriptors open against the old inode (the "macOS unlinked-inode gotcha"
+# in SETUP.md) and the next run sees ghost state.
+lsof -iTCP:8080 -sTCP:LISTEN >/dev/null 2>&1 && { echo "PLATFORM_STILL_RUNNING — abort before wipe"; exit 1; }
+rm -rf "$DATA_DIR"
+```
+
+**Option 3 — full cleanup:**
+
+```bash
+.venv/bin/nemo services stop || true
+DATA_DIR="${NMP_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/nemo}"
+case "$DATA_DIR" in
+  ""|"/"|"$HOME"|"$HOME/"|"."|"./"|"$PWD"|"$PWD/")
+    echo "REFUSING_UNSAFE_DATA_DIR: '$DATA_DIR' — abort"; exit 1 ;;
+esac
+lsof -iTCP:8080 -sTCP:LISTEN >/dev/null 2>&1 && { echo "PLATFORM_STILL_RUNNING — abort before wipe"; exit 1; }
+rm -rf "$DATA_DIR" .venv agents
+```
+
+Never delete a directory the user did not name or that the snapshot above didn't surface. Never `rm -rf` outside the working folder and the explicit data dir.
+
+## Step 4: Verify
+
+For all three options, the up-check is `lsof`:
+
+```bash
+lsof -iTCP:8080 -sTCP:LISTEN >/dev/null 2>&1 && echo "PLATFORM_STILL_RUNNING" || echo "platform stopped"
+```
+
+For option 2:
+
+```bash
+[ ! -d "${NMP_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/nemo}" ] && echo "data dir cleared" || echo "OPTION2_INCOMPLETE"
+```
+
+For option 3 (`.venv` is gone, so use absolute paths):
+
+```bash
+[ ! -d "${NMP_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/nemo}" ] && [ ! -d .venv ] && [ ! -d agents ] && echo "platform stopped, local files cleared" || echo "OPTION3_INCOMPLETE"
+```
+
+Verification passes only when `lsof` reports nothing on :8080 and (for options 2 and 3) the data directory is gone.
+
+## If verification fails
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `lsof` still shows a listener on :8080 after `services stop` | The instance was started in the foreground (`nemo services run`) and `stop` refused to kill it | Tell the user to Ctrl-C in the terminal running `nemo services run`. Only pass `--force` if they explicitly authorize killing the foreground process from this skill. |
+| `services stop` errors with "no instance" but `lsof` shows a listener | Lock state and reality diverged (foreground process with no registered instance, or instance was started in a different working directory / port scope) | Run `nemo services ls` to see what scopes the CLI knows about; the listener may belong to a different scope. Identify the PID from `lsof -iTCP:8080 -sTCP:LISTEN` and ask the user before sending SIGTERM. |
+| `services stop` says "stopped" but `lsof` still shows a listener | Process didn't honor SIGTERM in time | Re-run `nemo services stop --timeout 60`; if still alive, surface the PID and ask the user. Do not silently SIGKILL. |
+| `rm -rf` data dir fails with permission denied | Data dir owned by a different user, or a process still has it open | Surface the error; do not retry with sudo. Confirm `lsof -iTCP:8080` is empty and `lsof +D "$DATA_DIR" 2>/dev/null` shows nothing before retrying. |
+| `nemo services ls` shows `running` with empty PID/address after teardown | Stale lock leftover from a crashed `services run` | `nemo services stop --force` clears the lock. Then re-verify with `lsof`. |
+| User says "I changed my mind" mid-step | Confirmation came back ambiguous | Stop immediately; re-prompt. |
+
+## Gotchas
+
+- **`lsof` is ground truth.** `nemo services status` and `nemo services ls` report stale "running" from held instance locks after the underlying process has died. Always cross-check against `lsof -iTCP:8080 -sTCP:LISTEN` before believing them.
+- **Foreground vs background instances.** `nemo services run` runs in the foreground and is protected from `nemo services stop` (stop refuses unless `--force`). `nemo services start` runs in the background and is the right target for `stop`. If `stop` refuses, ask the user where they ran `services run` so they can Ctrl-C it themselves.
+- **Wipe AFTER stop, not before.** On macOS especially, running `rm -rf ~/.local/share/nemo` while a `nemo services run` process is still alive leaves the running process holding the old inode while a freshly-spawned platform sees the new (empty) inode. Always confirm `lsof -iTCP:8080` is empty before the wipe.
+- **No `pkill`.** Don't grep for "nemo-platform" or "nemo services" and send SIGTERM blindly — the kernel doesn't know which instance is the user's and which belongs to a coworker on the same box. Use `nemo services stop` (or, with user confirmation, kill a specific PID surfaced by `lsof`).
+- **`agents/` is local, not platform state.** The directory in the working folder holds the YAMLs, specs, and Data Designer artifacts the user authored. Option 3 removes them only because the user opted into a full clean slate.
+- **`.venv` is reusable.** A new `nemo-setup` after option 1 or 2 does not require reinstalling. Option 3 is the only path that wipes it.
+- **Data directory is configurable.** The default is `~/.local/share/nemo`, but the user may have overridden via `$NMP_DATA_DIR` or `$XDG_DATA_HOME`. Always echo the path being wiped before the wipe so the user can confirm.