@nullplatform/mcp 0.1.2 → 0.1.3

package/dist/i18n.js

@@ -160,6 +160,7 @@ const english = {
     "builds.commit": "Commit",
     "builds.released": "Released",
     "builds.none": "**{app}** has no builds yet.",
+    "builds.noneForCommit": "No build in **{app}** for commit `{commit}` — it may not have built yet, or the commit isn't on a built branch.",
     "builds.noneHint": "push a commit so CI produces one, then `application_deployment_create`.",
     "builds.deployHint": "`application_deployment_create build_id:{build}` ships it (cuts the release for you).",
     "builds.waiting": "build #{build} is still running — `application_build_list` again in a moment to check.",
@@ -423,6 +424,7 @@ const spanish = {
     "builds.commit": "Commit",
     "builds.released": "Released",
     "builds.none": "**{app}** todavía no tiene builds.",
+    "builds.noneForCommit": "Ningún build en **{app}** para el commit `{commit}` — puede que todavía no haya buildeado, o que el commit no esté en una branch que buildea.",
     "builds.noneHint": "pusheá un commit para que CI genere uno, después `application_deployment_create`.",
     "builds.deployHint": "`application_deployment_create build_id:{build}` lo publica (crea la release por vos).",
     "builds.waiting": "el build #{build} sigue corriendo — `application_build_list` de nuevo en un momento para chequear.",

package/dist/np/context.js

@@ -12,10 +12,15 @@ export function baseRepoUrl(provider, prefix) {
             : "https://github.com";
     return `${host}/${prefix}`;
 }
-/** Default ceiling for a single app search — used as the per-namespace fetch cap AND the
- *  overall result cap. Beyond it the tool reports truncation and asks the user to narrow.
- *  (The old value of 50 silently hid larger orgs behind a flat "50 applications".) */
-export const DEFAULT_APP_LIMIT = 200;
+/** Org-wide app discovery must fan out across namespaces: the public `/application` endpoint is
+ *  namespace-scoped, with no org-wide list and no name search — so the name filter is client-side
+ *  by necessity. We page each namespace to completion and bound the AGGREGATE at this cap, which
+ *  is generous and lift-able via NP_MAX_APPS, reporting truncation past it instead of silently
+ *  hiding a large org (the old code capped the whole org at 200 with a flat `.slice`). */
+const MAX_APPS = Math.max(1, Number(process.env.NP_MAX_APPS) || 1000);
+export const DEFAULT_APP_LIMIT = MAX_APPS;
+/** Safety ceiling when paging the account/namespace skeleton (both rarely exceed one page). */
+const SKELETON_CAP = 2000;
 /** Concurrency-limited parallel map — fast fan-out without hammering the API. */
 export async function pmap(items, mapItem, limit = 12) {
     const results = new Array(items.length);
@@ -29,6 +34,20 @@ export async function pmap(items, mapItem, limit = 12) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length || 1) }, worker));
     return results;
 }
+/** Page an offset-based list endpoint to completion, bounded by `max` items. No list response
+ *  carries a total, so the boundary is the standard offset heuristic: a page shorter than the
+ *  requested limit is the last one. */
+async function fetchPaged(fetchPage, max, pageSize = 200) {
+    const rows = [];
+    for (let offset = 0; offset < max; offset += pageSize) {
+        const limit = Math.min(pageSize, max - offset);
+        const page = await fetchPage(offset, limit);
+        rows.push(...page);
+        if (page.length < limit)
+            break;
+    }
+    return rows;
+}
 /**
  * The public list endpoints are NRN-authorized and need explicit scoping (account needs
  * organization_id, namespace needs account_id, application needs namespace_id). There is no
@@ -53,16 +72,17 @@ export class NpContext {
         if (!refresh && this.skeleton && Date.now() - this.skeleton.at < NpContext.CACHE_TTL_MS)
             return this.skeleton;
         const orgId = await this.organizationId();
-        const accountsResp = await this.np.get("/account", {
-            organization_id: orgId,
-            limit: 200,
-        });
-        const perAccount = await pmap(accountsResp.results ?? [], async (account) => {
-            const namespacesPage = await this.np
-                .get("/namespace", { account_id: account.id, limit: 200 })
-                .catch(() => ({ results: [] }));
+        const accounts = await fetchPaged((offset, limit) => this.np
+            .get("/account", { organization_id: orgId, offset, limit })
+            .then((page) => page.results ?? [])
+            .catch(() => []), SKELETON_CAP);
+        const perAccount = await pmap(accounts, async (account) => {
+            const accountNamespaces = await fetchPaged((offset, limit) => this.np
+                .get("/namespace", { account_id: account.id, offset, limit })
+                .then((page) => page.results ?? [])
+                .catch(() => []), SKELETON_CAP);
             const accountBaseRepoUrl = baseRepoUrl(account.repository_provider, account.repository_prefix);
-            return (namespacesPage.results ?? []).map((namespace) => ({
+            return accountNamespaces.map((namespace) => ({
                 id: namespace.id,
                 name: namespace.name,
                 nrn: namespace.nrn,
@@ -109,21 +129,12 @@ export class NpContext {
             ? skeleton.namespaces.filter((namespace) => namespace.name.toLowerCase().includes(namespaceFilter))
             : skeleton.namespaces;
         const nameFilter = args.query?.toLowerCase();
-        const perNamespace = await pmap(namespaces, async (namespace) => {
-            try {
-                const query = {
-                    namespace_id: namespace.id,
-                    limit: DEFAULT_APP_LIMIT,
-                };
-                if (args.query)
-                    query["name:contains"] = args.query; // server-side when supported
-                const page = await this.np.get("/application", query);
-                return (page.results ?? []).map((app) => this.mapApp(app, namespace));
-            }
-            catch {
-                return [];
-            }
-        });
+        // `/application` is namespace-scoped with no name filter, so page each namespace to completion
+        // and filter by name client-side (below). This lifts the old silent 200-per-org cap.
+        const perNamespace = await pmap(namespaces, async (namespace) => fetchPaged((offset, limit) => this.np
+            .get("/application", { namespace_id: namespace.id, offset, limit })
+            .then((page) => page.results ?? [])
+            .catch(() => []), MAX_APPS).then((rows) => rows.map((app) => this.mapApp(app, namespace))));
         const seen = new Set();
         return perNamespace
             .flat()

package/dist/np/journey.js

@@ -11,13 +11,22 @@ const TERMINAL = new Set([
 ]);
 export const isDeploymentTerminal = (status) => !!status && TERMINAL.has(status);
 export function bumpSemver(semver) {
-    const parts = /^v?(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
-    return parts ? `${parts[1]}.${parts[2]}.${Number(parts[3]) + 1}` : "0.0.1";
+    // Preserve the optional `v` prefix: an org that enforces a v-prefixed version pattern
+    // rejects a bare bump, and dropping it makes the release history inconsistent.
+    const parts = /^(v?)(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
+    return parts ? `${parts[1]}${parts[2]}.${parts[3]}.${Number(parts[4]) + 1}` : "0.0.1";
 }
-export async function listBuilds(np, applicationId, limit = 10) {
-    const page = await np
-        .get("/build", { application_id: applicationId, sort: "created_at:desc", limit })
-        .catch(() => ({ results: [] }));
+export async function listBuilds(np, applicationId, options = {}) {
+    const query = {
+        application_id: applicationId,
+        sort: "created_at:desc",
+        limit: options.limit ?? 10,
+    };
+    // The public API filters builds by full commit SHA via the `commit.id` query param (in the
+    // canonical OpenAPI contract) — this is how a change is traced from a commit to its build.
+    if (options.commit)
+        query["commit.id"] = options.commit;
+    const page = await np.get("/build", query).catch(() => ({ results: [] }));
     return (page.results ?? []).map((build) => ({
         id: build.id,
         status: build.status,

package/dist/surfaces/developer.js

@@ -6,7 +6,9 @@ import { tools } from "../tools/index.js";
  */
 const INSTRUCTIONS = `nullplatform is where this code gets built, released, deployed and observed — these tools replace its web dashboard for the everyday developer journey.
 
-The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. Start with \`application_get\` — it shows what's live where and suggests the next action.
+The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. "This app", or a request that names nothing, means the repo's app — infer it; pass \`app\` only when the user means a different, explicitly named application. Start with \`application_get\` — it shows what's live where and suggests the next action.
+
+You run in the developer's own environment, so fuse the local repo with platform state. Read the git remote, branch, HEAD commit, the diff being shipped, and config files (\`.env\`, \`package.json\`, Dockerfile), and correlate them with what the platform reports: does the local HEAD match a built or released commit, does a local config value match what a scope resolves. That correlation is this integration's edge over the web dashboard, which only sees the platform half.
 
 Every tool accepts \`language\`: ALWAYS set it to the language the user is conversing in (ISO code, e.g. "es", "en") — answers come back in the user's language.
 

package/dist/tools/builds.js

@@ -12,14 +12,18 @@ import { appArg, requireApp } from "./shared.js";
  */
 export const buildsTool = defineTool({
     name: TOOL.applicationBuildList,
-    title: "List builds",
-    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets.",
+    title: "Builds",
+    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets, or commit:<sha> to find the build for a specific commit (tracing a change to its build and release).",
     annotations: { readOnlyHint: true, openWorldHint: true },
     errorKey: "builds.errorLabel",
     inputSchema: {
         app: appArg,
         build: z.number().optional().describe("Build id — show this build's assets instead of the list"),
         limit: z.number().optional().describe("How many recent builds (default 10)"),
+        commit: z
+            .string()
+            .optional()
+            .describe("Full commit SHA — list only the build(s) for that commit (tracing a change to its build/release)"),
     },
     async handler(args, context) {
         const resolved = await requireApp(context, args);
@@ -43,11 +47,14 @@ export const buildsTool = defineTool({
             return reply(markdown, { build_id: args.build, assets });
         }
         const [builds, releases] = await Promise.all([
-            listBuilds(context.np, app.id, args.limit ?? 10),
+            listBuilds(context.np, app.id, { limit: args.limit ?? 10, commit: args.commit }),
             listReleases(context.np, app.id, { limit: 50 }),
         ]);
         if (builds.length === 0) {
-            return reply(translate("builds.none", { app: app.name }) + next(translate("builds.noneHint")));
+            const empty = args.commit
+                ? translate("builds.noneForCommit", { app: app.name, commit: shortCommit(args.commit) })
+                : translate("builds.none", { app: app.name }) + next(translate("builds.noneHint"));
+            return reply(empty, { app: `#${app.id}`, app_name: app.name, builds: [], commit: args.commit ?? null });
         }
         const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
         const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));

package/dist/tools/create-release.js

@@ -24,7 +24,7 @@ export const createReleaseTool = defineTool({
         let buildId = args.build_id;
         let buildNote = "";
         if (!buildId) {
-            const builds = await listBuilds(context.np, app.id, 5);
+            const builds = await listBuilds(context.np, app.id, { limit: 5 });
             const successful = builds.find((build) => build.status === "successful");
             if (!successful)
                 return fail(translate("createRelease.noBuilds", { app: app.name }));

package/dist/tools/deploy.js

@@ -15,7 +15,7 @@ async function resolveRelease(context, applicationId, args) {
     // code under its name — so search deep enough that only pathologically active apps miss.
     const [releases, builds] = await Promise.all([
         listReleases(context.np, applicationId, { status: "active", limit: 200 }),
-        listBuilds(context.np, applicationId, 5),
+        listBuilds(context.np, applicationId, { limit: 5 }),
     ]);
     const successfulBuild = builds.find((build) => build.status === "successful");
     if (args.release_id) {

package/dist/tools/find-apps.js

@@ -7,7 +7,7 @@ import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 export const findAppsTool = defineTool({
     name: TOOL.applicationList,
-    title: "Find applications",
+    title: "Applications",
     description: "Search applications across the whole organization by partial name (and optionally namespace). Fast (parallel + cached). Use when the repo isn't linked or the user names an app you don't know.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "find-apps",

package/dist/tools/logs.js

@@ -7,7 +7,7 @@ import { TOOL } from "../tool-names.js";
 import { appArg, chooseScope, requireApp } from "./shared.js";
 export const logsTool = defineTool({
     name: TOOL.applicationLogList,
-    title: "Read logs",
+    title: "Logs",
     description: "Read recent application logs (optionally for one scope). Returns the latest lines, newest last — good for a quick 'why is it failing?' look.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "logs",

package/dist/tools/params.js

@@ -6,7 +6,7 @@ import { TOOL } from "../tool-names.js";
 import { appArg, requireApp } from "./shared.js";
 export const paramsTool = defineTool({
     name: TOOL.applicationParameterList,
-    title: "List parameters",
+    title: "Parameters",
     description: "List an application's configuration parameters (env vars / files; secret values are masked). Use application_parameter_create to add or change them.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "params",

package/dist/tools/playbook.js

@@ -13,8 +13,8 @@ import { TOOL } from "../tool-names.js";
 const playbookBody = (markdown) => markdown.replace(/^---\n[\s\S]*?\n---\n?/, "").trim();
 export const playbookGetTool = defineTool({
     name: TOOL.playbookGet,
-    title: "Read an operating playbook",
-    description: "Read a nullplatform operating playbook — the methodology to follow before the matching non-trivial work: deploying-safely before a deploy/rollout, incident-response when something is broken, platform-conventions for entity/versioning/traffic semantics. Call with no name to list the available playbooks.",
+    title: "Operating playbooks",
+    description: "Read a nullplatform operating playbook — the methodology to follow BEFORE the matching non-trivial work (e.g. deploying-safely before a deploy, incident-response when something is broken, configuring-safely before changing parameters or secrets). The server instructions carry the full catalog; call this with no name to list them too.",
     annotations: { readOnlyHint: true },
     errorKey: "playbook.errorLabel",
     inputSchema: {

package/dist/tools/status.js

@@ -26,7 +26,7 @@ async function scopeViews(context, applicationId) {
 }
 export const statusTool = defineTool({
     name: TOOL.applicationGet,
-    title: "nullplatform status",
+    title: "Application status",
     description: "THE place to start. Shows an application's full picture: scopes with what's live on each (release + traffic), latest build, latest release, and the one obvious next action. Call with no arguments inside a repo to use the linked app. Pass deployment:<id> to watch one rollout in detail.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "np-panel",
@@ -54,7 +54,7 @@ export const statusTool = defineTool({
             return resolved.out;
         const [views, builds, releases, orgSlug] = await Promise.all([
             scopeViews(context, resolved.app.id),
-            listBuilds(context.np, resolved.app.id, 5),
+            listBuilds(context.np, resolved.app.id, { limit: 5 }),
             listReleases(context.np, resolved.app.id, { limit: 5 }),
             context.org.organizationSlug(),
         ]);

package/dist/tools/traffic.js

@@ -8,8 +8,8 @@ import { TOOL } from "../tool-names.js";
 import { appArg, delays, requireApp, sleep } from "./shared.js";
 export const trafficTool = defineTool({
     name: TOOL.applicationDeploymentUpdate,
-    title: "Traffic / finalize / rollback",
-    description: 'Drive an in-flight rollout: move traffic to the new version (percent snaps to 1,5,10,25,50,75,90,95,99,100), finalize it (action:"finalize" — retire the old version), or roll it back (action:"rollback" — traffic returns to the old version). Finds the app\'s active deployment automatically.',
+    title: "Update traffic",
+    description: 'Drive an in-flight rollout: move traffic to the new version (percent snaps to 0,1,5,10,25,50,75,90,95,99,100), finalize it (action:"finalize" — retire the old version), or roll it back (action:"rollback" — traffic returns to the old version). Finds the app\'s active deployment automatically.',
     annotations: { destructiveHint: true, openWorldHint: true },
     widget: "np-panel",
     errorKey: "traffic.errorLabel",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "nullplatform from your code assistant — an MCP server that replaces the dashboard for the everyday developer journey",
   "license": "MIT",
   "author": "nullplatform",

package/skills/configuring-safely/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: configuring-safely
+description: Use when setting, changing, or rotating an application's parameters or secrets (env vars / files) on nullplatform — what is safe, what only takes effect on the next deploy, and how to rotate without downtime.
+---
+
+# Configuring safely on nullplatform
+
+A parameter change is **inert until you redeploy**. Setting it is half the job; the value
+reaches running instances only when each scope that uses it deploys again. Secret values are
+encrypted and shown masked — but they are versioned, not write-once.
+
+## What a parameter is
+
+- An environment variable or a file (`type:"ENVIRONMENT"|"FILE"`), defined on the application
+  and resolved per scope at deploy time. Mark credentials `secret:true`.
+- `application_parameter_create` is an upsert and convergent: re-running with the same name
+  changes the value (it reports created vs updated) and never duplicates. Each change is kept
+  as a new version platform-side (history lives in the dashboard).
+- Secret values are masked in `application_parameter_list` and in tool output. Revealing the
+  real value needs the `parameter:read-secrets` permission (often itself approval-gated) and is
+  done in the dashboard — this integration never prints a secret back.
+
+## Setting a value
+
+1. Treat the repo as the source of truth for what the value should be — a local `.env` or config
+   file is the usual reference. Never paste a secret's value into chat, a commit, or a log.
+2. `application_parameter_create` writes the **application-level** value. Per-scope and
+   per-dimension overrides (a different value in production) are managed in the dashboard. So if
+   a value seems not to take effect, a more specific override may be shadowing it — the effective
+   value is the most specific: scope override → dimension match → application default.
+
+## Making it live (the step that's easy to forget)
+
+3. Nothing changes until each scope redeploys. List the scopes with `application_get` and
+   redeploy every one that should pick the value up — metric-gated, per `deploying-safely`.
+   Reporting "parameter updated" without the pending redeploy is misleading.
+
+## Rotating a secret
+
+4. There is no in-place rotate. Set the new value (`application_parameter_create`, same name) →
+   redeploy **every** scope that uses it → verify each is healthy → only then revoke the old
+   credential upstream. Order matters: a scope left un-redeployed is still serving the old value,
+   and revoking it first breaks that scope.
+
+## Gotchas & don'ts
+
+- A parameter's `type`, `name`, and `secret` flag are fixed once created. To change those, create
+  a new parameter and remove the old one (then redeploy).
+- Don't echo a secret value anywhere. Don't treat a value as live before the redeploy. Don't
+  assume the application-level value is what production serves — check for a scope override first.

package/skills/deploying-safely/SKILL.md

@@ -16,6 +16,8 @@ over in steps you control, and nothing is destroyed until you finalize. Rollback
      rejects overlapping deploys).
    - What will ship: if the latest successful build is newer than the latest release,
      `application_deployment_create` will cut the release automatically — say so before doing it.
+     Running in the repo, read `git log` / the diff since the live release's commit to tell the
+     user what this deploy actually changes.
    - The target scope: when several exist, pick by dimension (`scope:"environment=production"`),
      never by guessing. Production-dimension scopes deserve a confirmation from the user.
 2. If the change involved parameters (`application_parameter_create`), remember values only apply on this
@@ -30,7 +32,7 @@ over in steps you control, and nothing is destroyed until you finalize. Rollback
      (dashboard → Approvals). Don't retry; watch with `application_get deployment:<id>`.
 2. Wait for `running` (instances healthy). `waiting_for_instances` lasting more than ~5
    minutes usually means a failing health check — check `application_log_list` before pushing traffic.
-3. Walk traffic in steps — allowed marks are 1, 5, 10, 25, 50, 75, 90, 95, 99, 100:
+3. Walk traffic in steps — allowed marks are 0, 1, 5, 10, 25, 50, 75, 90, 95, 99, 100:
    - Low-risk/dev: 25 → 100 is fine.
    - Production: 5 or 10 → 25 → 50 → 100, pausing 2–5 minutes per step.
 4. **Gate every step on metrics** (`application_metric_list`, 1h window, compare against pre-deploy):
@@ -50,5 +52,6 @@ Prefer a needless rollback over a defended bad deploy. After rolling back, captu
 ## First-ever deploy on a scope
 
 There is no old version to fall back to: traffic semantics don't apply, the deployment
-finalizes on its own once instances are healthy, and "rollback" means cancel. Verify with
-the scope's domain URL from `application_get` once finalized.
+finalizes on its own once instances are healthy, and "rollback" means cancel — which ends in
+`failed`, leaving the scope to be recreated rather than reverted. Verify with the scope's
+domain URL from `application_get` once finalized.

package/skills/incident-response/SKILL.md

@@ -34,6 +34,8 @@ to the last known-good version.
   - throughput cliff to ~0 → upstream/routing problem; the app may be healthy.
 - `application_log_list` (the affected scope; filter for `ERROR`, `FATAL`, stack traces):
   - note the FIRST error timestamp and correlate with the deploy time from `application_get`.
+  - running in the repo: map the suspect release to its build commit and read `git log` around
+    it — the changes between the last-good and the current release are the prime suspects.
 - `application_parameter_list` — config is a top cause: was a parameter changed before the last deploy?
   Secret values are masked, but names + the deploy timing tell the story.
 
@@ -47,6 +49,7 @@ and the evidence — and leave the bad release identified so it isn't redeployed
 ## Don'ts
 
 - Don't deploy a "quick fix" forward while the incident is open — roll back first.
-- Don't finalize anything during an incident.
+- Don't finalize during an incident — once a deploy is `finalizing` it can't be cancelled or
+  rolled back; it only retries forward.
 - Don't restart/recreate scopes as a first move; that destroys the evidence and rarely
   fixes the cause.

package/skills/managing-environments/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: managing-environments
+description: Use when adding or changing a nullplatform deploy target (scope / environment / region) — identifying existing scopes, carrying the org's dimensions, and the first deploy to a fresh scope.
+---
+
+# Managing environments on nullplatform
+
+A scope IS an environment, and creating one **provisions real infrastructure asynchronously**.
+Identify before you create, carry the org's dimensions, and mirror a sibling.
+
+## 1. Identify before creating
+
+`application_get` first — list the existing scopes and their dimensions. "Add staging" often
+means a scope that already exists; match by **dimension** (`environment=staging`), not by display
+name. `application_scope_create` is convergent (an existing name returns that scope), but a
+near-duplicate under a different name is a real-infrastructure mistake.
+
+## 2. Dimensions
+
+In orgs that use runtime dimensions a new scope must carry them (e.g. `environment`, `country`).
+`application_scope_create` borrows the shape of an existing scope when you don't pass
+`dimensions` — usually what you want. Set them right at creation: the dashboard locks dimensions
+afterwards, so treat them as fixed even though the platform technically allows edits. A
+production-dimension scope deserves an explicit confirmation from the user.
+
+## 3. Create
+
+`application_scope_create name:"…"` (it lists the scope types to choose from if the org has
+several). It returns immediately with the scope **provisioning** — the infrastructure comes up
+out of band. Poll with `application_get` until it's active before deploying; the create response
+is accepted intent, not a ready environment.
+
+## 4. Mirror config, then first deploy
+
+- A new environment with missing parameters will misbehave. Bring the sibling's configuration
+  across (`application_parameter_create`, per `configuring-safely`) before the first deploy.
+- The first deploy to a fresh scope is special: there's no previous version, so traffic-splitting
+  doesn't apply — it finalizes on its own once instances are healthy, and a cancel ends in
+  `failed` (the scope must be recreated, since there's nothing to fall back to). Verify via the
+  scope's domain URL from `application_get`.
+
+## Sizing & later edits
+
+Sizing/capabilities and post-creation dimension edits aren't exposed by this integration — set
+what you can at creation and deep-link to the dashboard for the rest. An under-sized scope shows
+up later as CPU/memory near limits in `application_metric_list`.
+
+## Don'ts
+
+- Don't create a duplicate of an existing scope; identify first.
+- Don't guess dimension values — borrow a sibling's (the tool does this by default).
+- Don't treat scope creation as cheap or instant: it's real infrastructure, provisioned
+  asynchronously.

package/skills/platform-conventions/SKILL.md

@@ -30,29 +30,39 @@ Scopes carry org-defined dimensions like `environment` and `country`
 
 ## Versioning
 
-- Releases use semver, optionally `v`-prefixed; orgs may enforce a pattern.
-- Auto-cut releases bump the patch. "Deploy 1.4.0" targets the EXISTING 1.4.0 release —
+- Releases use semver, optionally `v`-prefixed; an org may enforce a pattern
+  (`settings.releases.versionPattern`). Whoever cuts the release chooses the semver.
+- When a tool cuts a release for you (deploy, `application_release_create`) it defaults to
+  bumping the patch of the latest release. "Deploy 1.4.0" targets the EXISTING 1.4.0 release —
   that's also how you roll back after a finalize.
 
 ## Parameters
 
-- Env vars or files, app-NRN scoped, optionally secret (values never readable again).
+- Env vars or files, app-NRN scoped, optionally secret. Secret values are masked by default;
+  reading the real value needs the `parameter:read-secrets` permission (often itself
+  approval-gated) and is not exposed by this integration — a value is versioned, not write-once.
 - Changes take effect ONLY on the next deploy of each scope — saying "parameter updated"
   without mentioning the pending redeploy is misleading.
+- The effective value for a scope is the most specific one: scope override → dimension match →
+  application default.
 
 ## Traffic & lifecycle semantics
 
-- Traffic percentages snap to: 1, 5, 10, 25, 50, 75, 90, 95, 99, 100.
+- Traffic percentages snap to: 0, 1, 5, 10, 25, 50, 75, 90, 95, 99, 100 (0 drains the new version).
 - Deployment statuses: `creating → waiting_for_instances → running (traffic phase) →
-  finalizing → finalized`; terminal also includes `failed`, `cancelled`, `rolled_back`,
-  `creating_approval_denied`. `creating_approval` means a human approval gate.
+  finalizing → finalized`; a rollback runs `cancelling → rolling_back → rolled_back`; terminal
+  also includes `failed`. `creating_approval` means a human approval gate (denied →
+  `creating_approval_denied`). A separate axis, `statusInScope` (active/candidate/inactive),
+  is what the scope actually serves. Once a deploy is `finalizing` it can't be cancelled — it
+  only retries forward.
 - One active rollout per scope.
 
 ## Gotchas worth knowing
 
-- Multi-asset builds (e.g. docker + lambda) need an asset choice per scope; the platform's
-  error for a wrong/missing choice misleadingly says "scope and release belong to
-  different applications".
+- Multi-asset builds (e.g. docker + lambda) need an asset choice per scope (set the scope's
+  asset when a build emits more than one; a single-asset build needs no choice). A wrong or
+  missing choice is rejected with a misleading "scope and release belong to different
+  applications" — it actually means "pick the asset" (a real runtime error, verified live).
 - Logs and metrics are per-scope, never app-wide.
 - Approvals can gate deploys org-wide; a "stuck" deploy in `creating_approval` is waiting
   for a human, not broken.

package/skills/promoting-across-environments/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: promoting-across-environments
+description: Use when moving a validated release from one environment to the next (dev → staging → production) on nullplatform, or when two environments behave differently — promote the same release, and tell release drift from config drift.
+---
+
+# Promoting across environments on nullplatform
+
+Build once, deploy the same release everywhere. A release is an immutable, application-wide
+pointer to a build, so promoting to the next environment means **deploying the release you
+already validated** onto that environment's scope — never rebuilding, never cutting a new release
+per environment. What you tested is then exactly what ships.
+
+> "Promote" here is the developer sense: move a release to the next environment. The platform
+> also uses "promote" for *finalize* — promoting a deployment's candidate over the old version
+> within one rollout. Different operation; don't conflate them.
+
+## Promoting a release
+
+1. Validate on the lower environment first. With `application_get`, confirm which release is live
+   on (say) the `environment=staging` scope and that it's healthy — metrics and logs per
+   `deploying-safely`.
+2. Deploy that **same** release to the next scope by version:
+   `application_deployment_create version:"1.4.2" scope:"environment=production"`. Passing the
+   existing version deploys it as-is; it does not cut a new release. Do NOT deploy "latest" here —
+   a newer build may exist between staging and prod, and "latest" would ship something you never
+   validated.
+3. Walk traffic and gate exactly as in `deploying-safely`. A production-dimension scope deserves
+   an explicit confirmation. Repeat environment by environment.
+
+## When an environment behaves differently (drift)
+
+Two scopes running "the same app" can differ in exactly two ways — establish which before acting:
+
+- **Release drift** — they're on different releases. `application_get` shows the live release per
+  scope; staging on 1.4.2 and prod on 1.3.0 is the whole story. The fix is promotion (above), not
+  debugging.
+- **Config drift** — same release, different configuration. A parameter can be overridden per
+  scope or dimension (effective value: scope → dimension → application), so prod may resolve a
+  different value than staging. `application_parameter_list` shows the names; per-scope override
+  values live in the dashboard. Fuse with the repo — a local `.env` or config file is the
+  reference for what each environment *should* carry.
+
+Promoting a release won't fix a config difference, and changing config won't close a release gap —
+so name the drift before you touch anything.
+
+## Don'ts
+
+- Don't rebuild per environment, and don't cut a separate release for prod — promote the one you
+  validated.
+- Don't deploy "latest" to production when you mean "the release that passed staging".
+- Don't assume parity: two scopes can drift on release, on config, or both.

package/skills/tracing-a-change/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: tracing-a-change
+description: Use to answer "is this ticket / PR / commit live, and where?" on nullplatform — walk a commit from the issue key to the scopes serving it.
+---
+
+# Tracing a change on nullplatform
+
+Intent and delivery join on the **commit**. Given a ticket, a PR, or a commit, walk it forward to
+the environments actually serving it — and be precise about the gap, because *merged* is not
+*deployed*.
+
+## The walk
+
+1. **Work item → commit.** Get the commit SHA the change landed in: from the issue's linked PR in
+   the tracker, or in the repo with `git log --grep="PROJ-123"` (the issue key on the commit). Use
+   the full SHA.
+2. **Commit → build.** `application_build_list commit:"<sha>"` returns the build(s) for that exact
+   commit (a build records its commit). No build → it hasn't built yet, or the commit isn't on a
+   built branch.
+3. **Build → release.** A build ships only once someone has cut a release from it;
+   `application_build_list` flags whether each build is released and with which semver.
+4. **Release → scopes.** `application_get` shows the live release per scope. If the change's
+   release is on staging but not production, that is the precise answer — and the next action is
+   `promoting-across-environments`.
+
+## Answer with a position, not a yes/no
+
+State where the change *is*: "PROJ-123 is in release 1.4.2 — live on staging since Tuesday, not
+yet on production." If it hasn't built or been released, say which step it's stuck at. Never equate
+a merged PR with a deployed change; the gap between them is the whole point of the trace.