diff --git a/skills/ns-advanced-memory-leak-hunter/SKILL.md b/skills/ns-advanced-memory-leak-hunter/SKILL.md index d3216db..9306596 100644 --- a/skills/ns-advanced-memory-leak-hunter/SKILL.md +++ b/skills/ns-advanced-memory-leak-hunter/SKILL.md @@ -8,7 +8,7 @@ This skill reads N|Solid data through the N|Solid MCP server (`nsolid`) and bund ### Phase 0: Reuse Evidence and Resolve Target 1. If the user already supplied both baseline and peak evidence (asset IDs or local files), skip straight to Phase 4. -2. The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. Pass it to every call, and set `NSOLID_TENANT` for the scripts. +2. Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. Pass the same tenant to every tenant-scoped call, and set `NSOLID_TENANT` for the scripts. 3. If no `agentId` is supplied, call `fleet_snapshot` with `where: 'app == ""'` and `sort: "used_heap_size"` to find the process; keep the exact `appName` for downloads. Stop if no matching process is connected. 4. A leak can sit in a worker thread while the main thread looks fine: `list_threads` with the `agentId` shows each thread's heap. Capture the thread that grows (`threadId`). diff --git a/skills/ns-analyze-asset/SKILL.md b/skills/ns-analyze-asset/SKILL.md index 904f885..dbc3b9c 100644 --- a/skills/ns-analyze-asset/SKILL.md +++ b/skills/ns-analyze-asset/SKILL.md @@ -11,7 +11,7 @@ This skill reads assets through the N|Solid MCP server (`nsolid`) and bundled sc When the user asks to restore a deleted profile or snapshot, pick the tenant (step 1), then go straight to [Restoring a Deleted Asset](#restoring-a-deleted-asset) instead of steps 2–10. Every other request follows the steps below. ### 1. Pick the Tenant -- The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. Pass the same tenant to every call, and set `NSOLID_TENANT` for the scripts. +- Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. Pass the same tenant to every tenant-scoped call, and set `NSOLID_TENANT` for the scripts. ### 2. Identify the Asset - The user should provide an asset ID or an app name with asset type. diff --git a/skills/ns-analyze-behaviors/SKILL.md b/skills/ns-analyze-behaviors/SKILL.md index afe2a75..98d70ab 100644 --- a/skills/ns-analyze-behaviors/SKILL.md +++ b/skills/ns-analyze-behaviors/SKILL.md @@ -4,7 +4,7 @@ description: >- Investigates what N|Solid's behavioral watch found: npm packages that newly run programs, compile code, use the network, start threads or touch the file system in production, packages that start running at all, release regressions and dependency drift. Use when the user asks about supply-chain attacks at run time, a compromised or suspicious dependency, what a package started doing, a behavior alert, or dependencies that changed without a release. --- -This skill works through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. +This skill works through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. The watch learns what each app's packages do from its CPU profiles, and reports a package doing something it never did before in that app, once the app has a history without it. diff --git a/skills/ns-analyze-event/SKILL.md b/skills/ns-analyze-event/SKILL.md index 8fa94ed..3c18af7 100644 --- a/skills/ns-analyze-event/SKILL.md +++ b/skills/ns-analyze-event/SKILL.md @@ -4,7 +4,7 @@ description: >- Investigates an existing N|Solid event or N|Solid alert and correlates the relevant evidence from N|Solid. Use when the user provides or references an event or alert such as a blocked event loop, a process exit or crash, an uncaught exception, a new vulnerability, a new package behavior, a stack trace, or span data. Also use when the user asks why an agent dropped, disconnected or reconnected, even without a specific event or alert. Routes follow-up to CPU, memory, vulnerability, or tracing workflows when needed. --- -This skill reads N|Solid data through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the event or user names. +This skill reads N|Solid data through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the event or user names. **No event, just a drop or reconnect.** When the user asks why an app or process dropped, disconnected or reconnected without giving an event or alert, skip parsing: resolve the app or process they name with `find_agents` to get its actual `agentId` (ask only for the missing app or process when they named neither), then go straight to **Lifecycle** in step 2. Use the time window they gave for `list_events`, or say which recent window you used (such as `-1h`) when they gave none; `agent_sessions` takes no `from`/`to`. diff --git a/skills/ns-analyze-logs/SKILL.md b/skills/ns-analyze-logs/SKILL.md index 92e5bc2..9919856 100644 --- a/skills/ns-analyze-logs/SKILL.md +++ b/skills/ns-analyze-logs/SKILL.md @@ -4,7 +4,7 @@ description: >- Searches and analyzes the logs N|Solid keeps from Node.js apps (nsolid.logger and OpenTelemetry logs): errors and warnings by app, process, text or severity, a request's logs (by its trace, for OpenTelemetry logs), and how they line up with exits, blocked loops and slow traces. Use when the user asks what an app logged, to find errors in production logs, what happened around an incident, or for the logs of a specific request or trace. --- -This skill reads logs through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. +This skill reads logs through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. N|Solid keeps logs for 14 days by default. Apps send them through the N|Solid logger (`nsolid.logger`) or an OpenTelemetry SDK. Only OpenTelemetry logs carry trace and span ids: `nsolid.logger` lines have none yet, so they are found by process and time rather than by trace. @@ -14,7 +14,7 @@ N|Solid keeps logs for 14 days by default. Apps send them through the N|Solid lo - `severity`: the least severe to include (e.g. `warn`); - `agentId`: one process (`find_agents` finds them by app or host); - `traceId`: one request's logs (OpenTelemetry logs only); - - `where`: an expression, e.g. `level >= "error" && service == "checkout"`, `body.contains("ECONNREFUSED")`, `attr["http.route"] == "/orders"` (`expression_help` with context `log` lists the fields). + - `where`: an expression, e.g. `level >= "error" && service == "checkout"`, `body.contains("ECONNREFUSED")`, `attr["http.route"] == "/orders"` (`expression_help` with context `log` lists the fields; it takes no `tenant`). - Start narrow (an app, errors, the incident's window) and widen only as needed. ### 2. Correlate diff --git a/skills/ns-analyze-release/SKILL.md b/skills/ns-analyze-release/SKILL.md index fa0f8aa..6987daa 100644 --- a/skills/ns-analyze-release/SKILL.md +++ b/skills/ns-analyze-release/SKILL.md @@ -4,7 +4,7 @@ description: >- Explains what a release of a Node.js app changed in production, from N|Solid's CPU profiles and package inventories: CPU by package and function against the release before (with confidence), calls between packages that are new or gone, packages added, removed or upgraded, regressions and dependency drift. Use when the user asks whether a deploy made things slower, what changed in version X, why the app behaves differently since a release, or wants releases marked or sourcemaps uploaded from CI. --- -This skill works through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names (production and staging are usually separate tenants). +This skill works through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names (production and staging are usually separate tenants). A release is a version of the app as its processes report it (`package.json`'s `version`). N|Solid records a release when its processes first report it, and CI can mark a deploy with its commit and a link. diff --git a/skills/ns-analyze-tracing/SKILL.md b/skills/ns-analyze-tracing/SKILL.md index be888a9..4e50c25 100644 --- a/skills/ns-analyze-tracing/SKILL.md +++ b/skills/ns-analyze-tracing/SKILL.md @@ -4,7 +4,7 @@ description: >- Analyzes N|Solid/OpenTelemetry tracing evidence from N|Solid for request latency, HTTP errors, and service dependencies. Use when the user asks about slow endpoints, API timeouts, distributed traces/spans, N+1 queries, await chains, microservice latency, cascading failures, or trace IDs. Query N|Solid only when no trace data was provided. --- -This skill reads traces through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. +This skill reads traces through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. ### 1. Use Provided Trace Data First - Treat the prompt as primary evidence. Parse any provided trace ID, span list, app name, endpoint name, status code, duration, or error stack before calling tools. @@ -13,7 +13,7 @@ This skill reads traces through the N|Solid MCP server (`nsolid`). The N|Solid t ### 2. Discover Services Only When Needed - **Skip this step if sufficient host-provided trace data is present**, or when the user names the service or app. -- Call `list_apps` for the app names. A span's `service` is its app's name. +- Call `list_apps` for the app names. A span's `service` is its app's name. An app missing from an omitted or truncated answer is not proven absent: if the user gave its exact name, pass it straight to the tools that take it; otherwise ask for the exact name rather than guess. - The N|Solid server doesn't collect AWS Lambda functions; if the user asks about a serverless function, say so. ### 3. Find Slow Requests Only If No Trace Was Supplied diff --git a/skills/ns-analyze-vulnerabilities/SKILL.md b/skills/ns-analyze-vulnerabilities/SKILL.md index d06bbf5..bda7a3d 100644 --- a/skills/ns-analyze-vulnerabilities/SKILL.md +++ b/skills/ns-analyze-vulnerabilities/SKILL.md @@ -4,13 +4,14 @@ description: >- Analyzes live runtime vulnerabilities in the packages connected N|Solid Node.js processes run, from N|Solid. Use when the user wants to know which CVEs are actually present in running apps, active exploitable/live vulnerabilities, malicious packages, zero-day exposure, supply-chain risk in production, Node.js runtime advisories, or production package risk. For static npm-audit-style project dependency scans, use ns-audit-dependencies instead. --- -This skill reads vulnerability findings through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names (production and staging are usually separate tenants). +This skill reads vulnerability findings through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names (production and staging are usually separate tenants). ### 1. High-Level Overview - Call `list_vulnerabilities`: open findings, most severe first. Each names its advisory (GHSA, a malicious-package report MAL, or a Node.js core advisory NODE-CORE), the app, severity, the vulnerable packages with the version that fixes them, the app's own dependencies that bring each in (`via`), and the runtime evidence: `installed`, `loaded` (required by the app) or `running` (seen in CPU profiles). A finding whose CVE CISA lists as exploited in the wild carries `knownExploited`: the CVE, when CISA listed it, its remediation due date, and whether ransomware campaigns use it. -- Narrow large fleets with `app`, `severity` (at least), or `where`, e.g. `severity >= "high" && evidence >= "loaded"`, or `knownExploited` (`expression_help` with context `finding` lists the fields). +- Narrow large fleets with `app`, `severity` (at least), or `where`, e.g. `severity >= "high" && evidence >= "loaded"`, or `knownExploited` (`expression_help` with context `finding` lists the fields; it takes no `tenant`). +- A result that fills its `limit` or carries a cut notice is partial: the findings it shows stand, but more may exist, so it cannot support an app all-clear or a complete ranking. - Summarize which app has the most critical issues. Lead with malicious packages (MAL-…) when there are any, then known exploited findings in loaded or running code: attackers use those now, whatever their severity. -- Before saying an app has nothing to fix, `vulnerability_data` shows whether the advisory data is current: when the OSV mirror and CISA's catalog were last checked, and any sync error. Say so when it is stale. +- Before saying an app has nothing to fix, `vulnerability_data` (it takes no `tenant`) shows whether the advisory data is current: when the OSV mirror and CISA's catalog were last checked, and any sync error. Say so when it is stale. - For the Node.js runtime itself, `list_runtimes` gives each Node.js version in use: its core advisories, the release that fixes them, and whether its line is at or near end of life. ### 2. Detail Per App diff --git a/skills/ns-configure-agents/SKILL.md b/skills/ns-configure-agents/SKILL.md index e383d4f..9bb2767 100644 --- a/skills/ns-configure-agents/SKILL.md +++ b/skills/ns-configure-agents/SKILL.md @@ -4,18 +4,20 @@ description: >- Changes how N|Solid agents run, safely: tracing on or off, continuous CPU profiling, the metrics interval, the blocked-loop threshold, trace sampling, snapshot redaction, tags. Use when the user wants tracing turned on for an app, continuous profiling for a while, a different metrics interval, asks why a process has a setting, or asks for a named config's history: who changed it and what it held before. Previews every change, prefers changes that expire, and explains where each running value came from. --- -This skill works through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. Changing configuration needs the `nsolid:dynamic-configuration` permission; without it the change tools are missing, and the skill can still explain and preview. +This skill works through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. Changing configuration needs the `nsolid:dynamic-configuration` permission; without it the change tools are missing, and the skill can still explain and preview. N|Solid keeps agents at **desired configs**: each targets processes by an expression (or an app, tags or one agent), has a priority, and can expire. Processes started later get them too, and N|Solid confirms each change from the agent's own report. That beats changing one process once, which a restart forgets. ### 1. Understand What Runs Now -- `list_desired_configs`: the configs the tenant keeps, with their targets, settings and priority; ones with `expiresAt` are temporary overrides. +- `list_desired_configs`: the configs the tenant keeps, with their targets, settings (as `config`) and priority; ones with `expiresAt` are temporary overrides. - `agent_config` with an `agentId`: what that process reports, what it should have and which config set each key, what is still to apply, and whether it has converged. Use it to answer "why does this process have that setting?" - `desired_config_history` with a config's `name`: its 50 newest saves and deletes, each with the settings, target, priority, expiry, who made it and when. Deleted configs keep their history. Read it before changing or deleting a named config, to see who set it and what it held before. No tool restores an earlier version: to go back to one, make it a new change and preview and apply it as below. ### 2. Shape the Change +- `preview_desired_config` and `set_desired_config` accept exactly one of `settings` or its alias `config`, never both. - Settings: `tracingEnabled`, `traceSampleRate` (0 to 1), `contCpuProfile` (continuous CPU profiling), `interval` (metrics, ms), `blockedLoopThreshold` (ms), `pauseMetrics`, `promiseTracking`, `redactSnapshots`, `assetsEnabled`, `tags`. Turning `contCpuProfile` on needs the tenant's continuous-profiling feature: where N|Solid has it off, the save is refused, and processes stay off whatever a config says. -- Target: `app`, `tags`, one `agentId`, or `where`, an expression over what a process is (`app == "checkout" && hostname.endsWith(".prod")`, `nodeVersion >= "22"`; `expression_help` with context `selector` lists the fields). Every process of the tenant needs `allAgents: true` and the user's explicit agreement. +- Target: `app`, `tags`, one `agentId`, or `where`, an expression over what a process is (`app == "checkout" && hostname.endsWith(".prod")`, `nodeVersion >= "22"`; `expression_help` with context `selector` lists the fields; it takes no `tenant`). Every process of the tenant needs `allAgents: true` and the user's explicit agreement. +- A `where` expression is limited to 4,000 characters, 256 nodes, 32 levels of depth, 500 characters per string literal and 200 values per `in` list. - **Prefer an expiring override** for anything diagnostic: `expiresInMinutes` makes it stop applying, and the processes go back to what they had. Tracing or continuous profiling "for the next hour" is an override of 60 minutes. - `priority`: higher wins where configs disagree. - Names use letters, digits, `.`, `_` and `-`: `checkout-tracing-1h`. diff --git a/skills/ns-cpu-spike-analysis/SKILL.md b/skills/ns-cpu-spike-analysis/SKILL.md index 04e23b1..17c2744 100644 --- a/skills/ns-cpu-spike-analysis/SKILL.md +++ b/skills/ns-cpu-spike-analysis/SKILL.md @@ -18,7 +18,7 @@ when the token can use several tenants). - If the user explicitly says read-only, offline, or "analyze this data", never capture a new profile unless they later approve it. ### 2. Pick the Tenant -- The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user or alert names (production and staging are usually separate tenants). Pass the same tenant to every call, and set `NSOLID_TENANT` for the scripts. +- Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user or alert names (production and staging are usually separate tenants). Pass the same tenant to every tenant-scoped call, and set `NSOLID_TENANT` for the scripts. ### 3. Discover Connected Agents Only When Needed - Call `fleet_snapshot` with `sort: "cpu_percent"` to list connected processes, hottest first, with their live metrics. When the user named an app, add `where: 'app == ""'`. diff --git a/skills/ns-download-asset/SKILL.md b/skills/ns-download-asset/SKILL.md index efb30bc..60effff 100644 --- a/skills/ns-download-asset/SKILL.md +++ b/skills/ns-download-asset/SKILL.md @@ -10,7 +10,7 @@ This skill downloads N|Solid assets with a bundled script, finding them through ### 1. Pick the Tenant -- The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. Set `NSOLID_TENANT` for the script. +- Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. Set `NSOLID_TENANT` for the script. ### 2. Identify the Asset diff --git a/skills/ns-fleet-health/SKILL.md b/skills/ns-fleet-health/SKILL.md index 2d70100..51a5c4c 100644 --- a/skills/ns-fleet-health/SKILL.md +++ b/skills/ns-fleet-health/SKILL.md @@ -4,29 +4,33 @@ description: >- Gives a health check of the Node.js processes N|Solid watches: what is hot or growing, what is crashing or blocking its event loop, what is alerting, and new vulnerabilities, risky Node.js versions and suspicious dependency behavior. Use when the user asks how production (or an app) is doing, what needs attention, for a daily or weekly briefing, or to find processes matching a condition such as "high memory on Node 20". --- -This skill reads N|Solid through its MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and check each tenant the user cares about (production and staging are usually separate tenants). +This skill reads N|Solid through its MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and check each tenant the user cares about (production and staging are usually separate tenants). ### 1. Scope -- The whole tenant by default, or the app the user names. `list_apps` lists the apps with their processes by status and the app, N|Solid and Node.js versions in use. +- The whole tenant by default, or the app the user names. `list_apps` lists the apps (50 by default) with their processes by status and the app, N|Solid and Node.js versions in use. + +### Bounded Lists +- Read `total`, `returned`, `truncated`, `more`, `totalAtLeast`, `appsOmitted`, any `outputCut` notice and any cut notice in each content block before drawing conclusions. `more: true` means the entries are a sample, not the whole set; `totalAtLeast` is a lower bound, not a count. List results stay within 20,000 serialized UTF-8 bytes, so fewer entries may fit than the requested limit. An omitted app or process is not proof that it is absent or healthy; say when the briefing covers only part of the tenant. +- Narrow with arguments the tool takes. `list_apps` has no app filter or cursor; for a named app, use the app-scoped calls below. Full lists that cannot be narrowed through MCP need the Console or REST API. Cursor-paginated lists refuse an oversized page whole: retry the same request and cursor with a lower `limit`; if limit 1 still fails, read that record through REST. ### 2. Gather the Picture Run what fits the question; for a full briefing, all of it: - **Hot processes:** `fleet_snapshot` with `sort: "cpu_percent"`, then `sort: "used_heap_size"` and `sort: "loop_estimated_lag"` (limit 5 each; add `where: 'app == ""'` for one app). Note anything far from its peers. - **Growing memory:** `query_metric` with `metric: "used_heap_size"`, `groupBy: "app"` and `from: "-24h"`: a series that only climbs needs a look (`ns-memory-spike-analysis`). - **Latency:** `query_metric` with `metric: "http_server"` (the p99) and `groupBy: "app"`. -- **Crashes and restarts:** `list_ended_processes` with `byApp: true` and `from: "-24h"`: how many processes of each app ended and how the latest did, lost ones (gone without an exit: killed, or the host lost) included. `event_stacks` with `type: "exit"` groups exits by error; `event_histogram` with `types: ["exit", "lost"]` shows when they came. +- **Crashes and restarts:** `list_ended_processes` with `byApp: true` and `from: "-24h"` (25 apps by default): how many processes of each app ended and how the latest did, lost ones (gone without an exit: killed, or the host lost) included. Beyond `tenant` and `byApp`, it takes only `from`, `to` and `limit`; `app`, `host` and `ending` are refused, so for one app pass `app` without `byApp`. `truncated` or `totalAtLeast` means some apps were left out, so an app missing from the list isn't zero. `event_stacks` with `type: "exit"` groups exits by error; `event_histogram` with `types: ["exit", "lost"]` shows when they came. - **Blocked event loops:** `event_stacks` (default `loop_blocked`) over the last day: where loops blocked, how often and how long. - **Alerts:** `list_alerts` with `state: "firing"`. `list_alert_rules` shows each rule's `health`: a rule that is `no-data`, `failing` or `stale` protects nothing, so name it under Needs attention. -- **Vulnerabilities:** `list_vulnerabilities` with `severity: "high"` (and `where: 'evidence >= "loaded"'` for the ones whose code is in use); malicious packages first, then findings marked `knownExploited` (CISA lists them as exploited in the wild), whatever their severity: `where: "knownExploited"`. -- **Node.js runtimes:** `list_runtimes`: versions at or near end of life, and core advisories with the release that fixes them. +- **Vulnerabilities:** `list_vulnerabilities` with `severity: "high"` (and `where: 'evidence >= "loaded"'` for the ones whose code is in use); malicious packages first, then findings marked `knownExploited` (CISA lists them as exploited in the wild), whatever their severity: `where: "knownExploited"`. A result that fills its `limit` or carries a cut notice is partial, never an all-clear. +- **Node.js runtimes:** `list_runtimes`: versions at or near end of life, and core advisories with the release that fixes them (`upgradeTo`). Each version names at most 20 apps, and `appsOmitted` counts the rest: an app it doesn't name may still run that version. - **New behaviors:** `list_behaviors`: dependencies doing something new, release regressions and drift. - **Agent credentials** (admins, on request): the web UI's Connect agents page, or `GET /v1/tenants//ingest-tokens`, shows ingest tokens due for rotation (`rotationDueAt`) and rotated ones still in use; rotation is covered in `ns-configure-agents`. - **How the team uses N|Solid** (admins, on request): the web UI's Activity page, or `GET /v1/tenants//activity?by=area|tool|clientName|person`, shows which features, pages and AI assistants and tools people use; `ns-activity-report` writes it as a page to share. It is off where N|Solid hasn't enabled it for the tenant. -- **Custom conditions:** `fleet_snapshot` takes an expression mixing metrics and what a process is, e.g. `rss > 1GiB && nodeVersion < "22"`, `cpu_percent > 80 && "canary" in tags`. `expression_help` with context `fleet` lists the fields. `save_view` keeps a useful expression under a name for people and tools (with the user's agreement). +- **Custom conditions:** `fleet_snapshot` takes an expression mixing metrics and what a process is, e.g. `rss > 1GiB && nodeVersion < "22"`, `cpu_percent > 80 && "canary" in tags`. `expression_help` with context `fleet` lists the fields (it takes no `tenant`). `save_view` keeps a useful expression under a name for people and tools (with the user's agreement). ### 3. Prioritize - Order by impact: crashes and firing critical alerts, then malicious or loaded high-severity vulnerabilities and end-of-life runtimes, then resource and latency outliers, then the rest. -- Say plainly when everything looks fine. +- Say plainly when everything looks fine, and name any check whose results were partial. ### 4. Present the Briefing - `# Fleet Health — — ` diff --git a/skills/ns-generate-asset/SKILL.md b/skills/ns-generate-asset/SKILL.md index ff2ad4a..12a8657 100644 --- a/skills/ns-generate-asset/SKILL.md +++ b/skills/ns-generate-asset/SKILL.md @@ -7,7 +7,7 @@ description: >- This skill captures assets through the N|Solid MCP server (`nsolid`) and saves them with a bundled script. The script needs the server's settings: `NSOLID_API_URL` and `NSOLID_API_TOKEN` in the environment, or `~/.agents/.nsolid-auth.json` with `apiUrl` and `token` (plus `tenant` when the token can use several tenants). ### 1. Pick the Tenant -- The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names (production and staging are usually separate tenants). Pass the same tenant to every call, and set `NSOLID_TENANT` for the script. +- Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names (production and staging are usually separate tenants). Pass the same tenant to every tenant-scoped call, and set `NSOLID_TENANT` for the script. ### 2. Resolve Scope - The target app is already resolved (workspace mapping, explicit `Application: `, or user confirmation). Do not switch apps. diff --git a/skills/ns-generate-sbom/SKILL.md b/skills/ns-generate-sbom/SKILL.md index 2bedc59..97debe9 100644 --- a/skills/ns-generate-sbom/SKILL.md +++ b/skills/ns-generate-sbom/SKILL.md @@ -9,11 +9,11 @@ This skill reads SBOMs through the N|Solid MCP server (`nsolid`) and a bundled s ## Instructions ### 1. Pick the Tenant -- The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. Set `NSOLID_TENANT` for the script. +- Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. Set `NSOLID_TENANT` for the script. ### 2. Identify Target Application - Determine the specific `app` name you need the SBOM for. -- If the app name is unknown, call `list_apps` for the apps and their process counts. +- If the app name is unknown, call `list_apps` for the apps and their process counts. An app missing from an omitted or truncated answer is not proven absent: if the user gave its exact name, pass it straight to `get_sbom`; otherwise ask for the exact name rather than guess. - An app's SBOM covers its connected processes together. For one process instead, find its `agentId` with `find_agents` (`app`). ### 3. Know What It Contains diff --git a/skills/ns-manage-alerts/SKILL.md b/skills/ns-manage-alerts/SKILL.md index d1e0024..d5e6e38 100644 --- a/skills/ns-manage-alerts/SKILL.md +++ b/skills/ns-manage-alerts/SKILL.md @@ -4,12 +4,14 @@ description: >- Defines, reviews, tunes and triages N|Solid alert rules and alerts. Use when the user wants to be alerted or paged on something (CPU, memory, event loop lag, latency, crashes or a crash loop, a process killed or lost, an app that stops reporting, blocked loops, new or known exploited vulnerabilities, a dependency's new behavior or a release regression), asks what alerts exist, which are firing or whether a rule is working, wants to acknowledge or silence an alert or end a silence early, switch a rule off, or wants a noisy rule fixed. Writes rules in N|Solid's expression language and checks what each would have caught before saving it. --- -This skill works through the N|Solid MCP server (`nsolid`). The N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user names. Saving rules, acknowledging or silencing alerts and ending a silence need the `nsolid:manage-alerts` permission; without it those tools are missing, and the skill can still review and draft. +This skill works through the N|Solid MCP server (`nsolid`). Most N|Solid tools take a `tenant`: when the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user names. Saving rules, acknowledging or silencing alerts and ending a silence need the `nsolid:manage-alerts` permission; without it those tools are missing, and the skill can still review and draft. + +When `list_alert_rules` comes back cut, too large or with an error, a name missing from it is not proof the name is free: don't claim a rule is absent from a partial list, and don't save under that name as a new rule until the exact name is verified unused. ## Start a Newly Connected Service's Baseline -When setting up alerts for a newly connected service, call `list_alert_starters`. -It returns the same starters the web editor offers, each with an id, title, +When setting up alerts for a newly connected service, call `list_alert_starters` +(it takes no `tenant`). It returns the same starters the web editor offers, each with an id, title, reason (`why`) and a `spec` in `set_alert_rule`'s terms. Read the current list; do not keep copies of starter definitions or reconstruct their thresholds. @@ -51,7 +53,7 @@ do not keep copies of starter definitions or reconstruct their thresholds. - **Event rule**: something that happens ("a process crashes", "the loop blocks over a second"). `event.where` over agent events: `type == "exit" && exitCode != 0`, `exitSignal == "SIGABRT"`, `type == "loop_blocked" && blockedFor > 1s`, `type == "lost"` (a process gone 15 minutes without an exit: SIGKILL, the out-of-memory killer, its host lost; the alert comes 15 minutes after it was last heard from). `resolveAfterMinutes` closes it after a quiet spell. `count` with `withinMinutes` fires only once that many matching events of a group came within the window ("3 exits in 10 minutes": `count: 3`, `withinMinutes: 10`); until then it is pending. - **Finding rule**: new vulnerability findings. `finding.where`, e.g. `severity >= "high" && evidence >= "loaded"`, `knownExploited` (CISA lists its CVE as exploited in the wild), `kind == "malicious"`, `kind == "end-of-life"`, `"express" in via`. Only findings that open after the rule is saved alert. - **Behavior rule**: a dependency doing something new, a release regression, or dependency drift. `behavior.where`, e.g. `kind == "capability" && severity >= "high"`, `kind == "regression" && severity >= "medium"`, `kind == "drift" && severity >= "high"`, `versionChange`. -- `expression_help` (contexts `agent`, `event`, `finding`, `behavior`) lists every field when the request needs one this skill doesn't name. +- `expression_help` (contexts `agent`, `event`, `finding`, `behavior`; it takes no `tenant`) lists every field when the request needs one this skill doesn't name. ### 2. Scope It - `scope` limits metric and event rules to some processes, as an agent expression: `app == "checkout"`, `"canary" in tags`, `hostname.endsWith(".prod")`. Finding and behavior rules take no scope: put `app == "…"` in their `where`. @@ -78,7 +80,7 @@ Before saving, show the user what the rule would have done: - Names use letters, digits, `.`, `_` and `-`: `checkout-p99-latency`. ## Reviewing and Tuning -- `list_alert_rules` lists every rule with its condition, scope, channels, diagnostics and `health`, which tells a quiet rule from a broken one: +- `list_alert_rules` lists rules with their condition, scope, channels, diagnostics and `health`, which tells a quiet rule from a broken one: - `ok`, with what the last check saw: the groups with a value and how many held (`groups`, `holding`), or for an event rule when an event last came and last matched (`checkedAt`, `matchedAt`); - `no-data`: no process in scope reports the metric (a misspelled name, an empty scope); - `failing`: its last check failed, and `lastError` says why; diff --git a/skills/ns-memory-spike-analysis/SKILL.md b/skills/ns-memory-spike-analysis/SKILL.md index b58b9bd..364382a 100644 --- a/skills/ns-memory-spike-analysis/SKILL.md +++ b/skills/ns-memory-spike-analysis/SKILL.md @@ -13,7 +13,7 @@ This skill reads N|Solid data through the N|Solid MCP server (`nsolid`) and bund - If the user explicitly says read-only, offline, or "analyze this file", do not capture a new heap asset unless they later approve it. ### 2. Pick the Tenant -- The N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` once and use the tenant the user or alert names. Pass the same tenant to every call, and set `NSOLID_TENANT` for the scripts. +- Most N|Solid tools take a `tenant`. When the token can use one tenant it is the default; otherwise call `list_tenants` (it takes no `tenant`) once and use the tenant the user or alert names. Pass the same tenant to every tenant-scoped call, and set `NSOLID_TENANT` for the scripts. ### 3. Find the Bottleneck Only If You Still Need a Target - If no agent is known, call `fleet_snapshot` with `where: 'app == ""'` and `sort: "used_heap_size"`, and keep the exact app name. diff --git a/skills/ns-node-upgrade/SKILL.md b/skills/ns-node-upgrade/SKILL.md index e600800..49e52ae 100644 --- a/skills/ns-node-upgrade/SKILL.md +++ b/skills/ns-node-upgrade/SKILL.md @@ -35,8 +35,8 @@ Otherwise, check in order: **At the start of your response**, briefly tell the user which source was used to determine the current version (one sentence). If the project-pinned version and the runtime on PATH disagree, treat the project pin as authoritative and note the mismatch. ### 2b. Check What Production Runs (when N|Solid is available) -If the `nsolid` MCP server is available, call `list_runtimes` (it takes a `tenant` when the token can use several: `list_tenants`). For each Node.js version the tenant's processes run, it gives the apps and process counts, whether its line is at or within 90 days of end of life (and which line to move to), the Node.js security team's core advisories that affect it, and the lowest release of its line that fixes them all (`upgradeTo`). -- Find the project's app among them (its `package.json` `name` or `NSOLID_APPNAME`). Production may run a different version than the workspace pins: say so, and plan from what runs. +If the `nsolid` MCP server is available, call `list_runtimes` (pass a `tenant` when the token can use several; `list_tenants` takes no `tenant` and lists them). For each Node.js version the tenant's processes run, it gives the apps and process counts, whether its line is at or within 90 days of end of life (and which line to move to), the Node.js security team's core advisories that affect it, and the lowest release of its line that fixes them all (`upgradeTo`). +- Find the project's app among them (its `package.json` `name` or `NSOLID_APPNAME`). Production may run a different version than the workspace pins: say so, and plan from what runs. Each version names at most 20 apps, and `appsOmitted` counts the rest: an app it doesn't name may still run that version. - Core advisories with an `upgradeTo` on the same line call for a patch upgrade first, whatever the line move: it is the smallest change that fixes them. - If the server isn't available, continue from the workspace alone. diff --git a/skills/ns-switch-org/SKILL.md b/skills/ns-switch-org/SKILL.md index 4e5e26b..0fd29b8 100644 --- a/skills/ns-switch-org/SKILL.md +++ b/skills/ns-switch-org/SKILL.md @@ -59,10 +59,11 @@ work around a failed OAuth flow (e.g. by editing The skills that read N|Solid data use the N|Solid MCP server (`nsolid`), which has settings of its own: switching NodeSource organizations doesn't change it. A N|Solid token can reach several tenants, such as an organization's production and -staging. Its tools take a `tenant`, and `list_tenants` shows the tenants the -token reaches. If the user wants N|Solid data from another tenant: +staging. Most of its tools take a `tenant`, and `list_tenants` (which takes +none) shows the tenants the token reaches. If the user wants N|Solid data from +another tenant: -- Pass that tenant to the tools from now on. +- Pass that tenant to the tenant-scoped tools from now on. - To change the default the skills' scripts use, the user sets `NSOLID_TENANT`, or `tenant` in `~/.agents/.nsolid-auth.json`. Tell them; don't edit the file yourself.