@nullplatform/mcp 0.1.0

package/dist/tools/shared.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { next, table } from "../md.js";
+import { resolveApp } from "../np/context.js";
+import { fail, reply } from "../tool.js";
+export { errorMessage, fail, reply } from "../tool.js";
+/** Pauses between mutate-then-refetch, tunable so tests don't wait. */
+export const delays = { afterDeploy: 1200, afterTraffic: 1000, appPoll: 2000 };
+export const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+export const appArg = z
+    .string()
+    .optional()
+    .describe('Application name or "#id". Omit it to use the app linked to the current repo (git remote).');
+export function httpsRepoUrl(url) {
+    const trimmed = url.trim().replace(/\.git$/, "");
+    const sshForm = /^git@([^:]+):(.+)$/.exec(trimmed);
+    return sshForm ? `https://${sshForm[1]}/${sshForm[2]}` : trimmed;
+}
+export function renderAmbiguous(matches) {
+    return [
+        translate("resolve.ambiguous"),
+        table([
+            translate("header.app"),
+            translate("header.id"),
+            translate("header.namespace"),
+            translate("header.status"),
+        ], matches
+            .slice(0, 10)
+            .map((candidate) => [
+            candidate.name,
+            `#${candidate.id}`,
+            candidate.namespace ?? "",
+            candidate.status ?? "",
+        ])),
+    ].join("\n\n");
+}
+function notFoundMessage(resolution) {
+    switch (resolution.cause) {
+        case "id":
+            return translate("resolve.noId", { id: resolution.ref ?? "?" });
+        case "name":
+            return translate("resolve.noMatch", { ref: resolution.ref ?? "?" });
+        case "repo_unlinked":
+            return translate("resolve.repoUnlinked", { url: resolution.url ?? "?" });
+        case "no_input":
+            return translate("resolve.noInput");
+    }
+}
+/** Resolve the target app or produce the user-facing miss/ambiguity answer. */
+export async function requireApp(context, args) {
+    const resolution = await resolveApp(context.org, args, context.repoUrl);
+    if (resolution.ok)
+        return { app: resolution.app };
+    if (resolution.reason === "ambiguous") {
+        return {
+            out: reply(renderAmbiguous(resolution.matches), { ambiguous: true, matches: resolution.matches }),
+        };
+    }
+    return { out: fail(notFoundMessage(resolution), { not_found: true }) };
+}
+/**
+ * Match scopes by name OR by dimensions: "dev" (name substring), "production"
+ * (dimension value substring), "environment=production" (exact key=value).
+ */
+export function matchScopes(scopes, wanted) {
+    const query = wanted.trim().toLowerCase();
+    const keyValue = /^([a-z0-9_-]+)\s*=\s*(.+)$/.exec(query);
+    if (keyValue?.[1] && keyValue[2] !== undefined) {
+        const [, dimensionKey, dimensionValue] = keyValue;
+        return scopes.filter((scope) => (scope.dimensions?.[dimensionKey] ?? "").toLowerCase() ===
+            dimensionValue.trim());
+    }
+    const exactNames = scopes.filter((scope) => scope.name.toLowerCase() === query);
+    if (exactNames.length)
+        return exactNames;
+    return scopes.filter((scope) => scope.name.toLowerCase().includes(query) ||
+        Object.values(scope.dimensions ?? {}).some((value) => value.toLowerCase().includes(query)));
+}
+export function dimsLabel(dimensions) {
+    const entries = Object.entries(dimensions ?? {});
+    return entries.length ? entries.map(([key, value]) => `${key}=${value}`).join(" · ") : "";
+}
+const scopeRow = (scope) => [scope.name, `#${scope.id}`, scope.status, dimsLabel(scope.dimensions)];
+const scopeHeaders = () => [
+    translate("header.scope"),
+    translate("header.id"),
+    translate("header.status"),
+    translate("header.dimensions"),
+];
+/** Pick the scope to act on (writes): by name/dimension, the sole scope, or ask. */
+export function pickScope(scopes, wanted) {
+    if (wanted) {
+        const matches = matchScopes(scopes, wanted);
+        if (matches.length === 1 && matches[0])
+            return { scope: matches[0] };
+        if (matches.length === 0) {
+            return {
+                out: fail(`${translate("scope.noMatchDetailed", { wanted })}\n\n${table(scopeHeaders(), scopes.map(scopeRow))}` +
+                    next(translate("scope.createHint", { name: wanted }))),
+            };
+        }
+        return {
+            out: reply(`${translate("scope.which")}\n\n${table(scopeHeaders(), matches.map(scopeRow))}`),
+        };
+    }
+    if (scopes.length === 1 && scopes[0])
+        return { scope: scopes[0] };
+    if (scopes.length === 0) {
+        return { out: fail(translate("scope.none") + next(translate("scope.noneHint"))) };
+    }
+    return {
+        out: reply(`${translate("scope.which")}\n\n${table(scopeHeaders(), scopes.map(scopeRow))}` +
+            next(translate("scope.deployHint"))),
+    };
+}
+/**
+ * Pick the scope to read from (logs/metrics): like pickScope but the ask-back carries a
+ * `choose_scope` payload the widgets render as a clickable list.
+ */
+export function chooseScope(scopes, wanted, options) {
+    const askData = (candidates) => ({
+        app: `#${options.app.id}`,
+        app_name: options.app.name,
+        choose_scope: candidates.map((scope) => ({ name: scope.name, status: scope.status })),
+    });
+    const ask = (candidates) => reply(`${translate("scope.perScope", { noun: translate(options.nounKey) })}\n\n${table([translate("header.scope"), translate("header.status")], candidates.map((scope) => [scope.name, scope.status]))}${next(translate("scope.readHint", { tool: options.tool, name: candidates[0]?.name ?? "" }))}`, askData(candidates));
+    if (wanted) {
+        const matches = matchScopes(scopes, wanted);
+        if (matches.length === 1 && matches[0])
+            return { scope: matches[0] };
+        if (matches.length === 0) {
+            return {
+                out: fail(translate("scope.noMatch", { wanted, names: scopes.map((scope) => scope.name).join(", ") })),
+            };
+        }
+        return { out: ask(matches) };
+    }
+    if (scopes.length === 1 && scopes[0])
+        return { scope: scopes[0] };
+    return { out: ask(scopes) };
+}

package/dist/tools/status.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { dashboardLink } from "../md.js";
+import { pmap } from "../np/context.js";
+import { getDeployment, getScope, isDeploymentTerminal, listBuilds, listReleases, listScopeDeployments, listScopes, } from "../np/journey.js";
+import { renderRollout, renderStatus } from "../render.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+async function scopeViews(context, applicationId) {
+    const [scopes, releases] = await Promise.all([
+        listScopes(context.np, applicationId),
+        listReleases(context.np, applicationId, { limit: 25 }),
+    ]);
+    const releasesById = new Map(releases.map((release) => [release.id, release]));
+    return pmap(scopes, async (scope) => {
+        const deployments = await listScopeDeployments(context.np, scope.id, 5);
+        const current = deployments.find((deployment) => !isDeploymentTerminal(deployment.status)) ??
+            deployments.find((deployment) => deployment.status === "finalized") ??
+            deployments[0];
+        return {
+            scope,
+            current,
+            live_release: current?.release_id ? releasesById.get(current.release_id) : undefined,
+        };
+    });
+}
+export const statusTool = defineTool({
+    name: TOOL.applicationGet,
+    title: "nullplatform 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",
+    errorKey: "status.errorLabel",
+    inputSchema: {
+        app: appArg,
+        deployment: z.number().optional().describe("Deployment id — show that rollout's live detail instead"),
+    },
+    async handler(args, context) {
+        if (args.deployment) {
+            const deployment = await getDeployment(context.np, args.deployment);
+            const [scope, orgSlug] = await Promise.all([
+                deployment.scope_id ? getScope(context.np, deployment.scope_id).catch(() => undefined) : undefined,
+                context.org.organizationSlug(),
+            ]);
+            const { md, structured } = renderRollout({
+                deployment,
+                scope,
+                dashboard: dashboardLink(orgSlug, scope?.nrn),
+            });
+            return reply(md, structured);
+        }
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const [views, builds, releases, orgSlug] = await Promise.all([
+            scopeViews(context, resolved.app.id),
+            listBuilds(context.np, resolved.app.id, 5),
+            listReleases(context.np, resolved.app.id, { limit: 5 }),
+            context.org.organizationSlug(),
+        ]);
+        const { md, structured } = renderStatus({
+            app: resolved.app,
+            views,
+            builds,
+            releases,
+            dashboard: dashboardLink(orgSlug, resolved.app.nrn),
+        });
+        return reply(md, structured);
+    },
+});

package/dist/tools/traffic.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, table } from "../md.js";
+import { deploymentAction, getDeployment, getScope, isDeploymentTerminal, listScopeDeployments, listScopes, snapTraffic, switchTraffic, } from "../np/journey.js";
+import { renderRollout } from "../render.js";
+import { defineTool, fail, reply } from "../tool.js";
+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.',
+    annotations: { destructiveHint: true, openWorldHint: true },
+    widget: "np-panel",
+    errorKey: "traffic.errorLabel",
+    inputSchema: {
+        app: appArg,
+        deployment_id: z.number().optional().describe("Deployment id (default: the app's single active rollout)"),
+        percent: z.number().min(0).max(100).optional().describe("Desired traffic % on the new version"),
+        action: z.enum(["finalize", "rollback"]).optional(),
+    },
+    async handler(args, context) {
+        if (args.percent === undefined && !args.action) {
+            return fail(translate("traffic.sayWhat"));
+        }
+        let deploymentId = args.deployment_id;
+        let scope;
+        if (!deploymentId) {
+            const resolved = await requireApp(context, args);
+            if ("out" in resolved)
+                return resolved.out;
+            const scopes = await listScopes(context.np, resolved.app.id);
+            const activeRollouts = [];
+            for (const candidate of scopes) {
+                const deployments = await listScopeDeployments(context.np, candidate.id, 3);
+                const active = deployments.find((deployment) => !isDeploymentTerminal(deployment.status));
+                if (active)
+                    activeRollouts.push({ deploymentId: active.id, scope: candidate, status: active.status });
+            }
+            if (activeRollouts.length === 0) {
+                return fail(translate("traffic.noActive", { app: resolved.app.name }));
+            }
+            if (activeRollouts.length > 1) {
+                return reply(`${translate("traffic.several")}\n\n${table([translate("header.deployment"), translate("header.scope"), translate("header.status")], activeRollouts.map((rollout) => [`#${rollout.deploymentId}`, rollout.scope.name, rollout.status]))}`);
+            }
+            const only = activeRollouts[0]; // length === 1 checked above
+            deploymentId = only.deploymentId;
+            scope = only.scope;
+        }
+        if (args.action === "finalize")
+            await deploymentAction(context.np, deploymentId, "finalize");
+        else if (args.action === "rollback")
+            await deploymentAction(context.np, deploymentId, "cancel");
+        else {
+            const snapped = snapTraffic(args.percent);
+            await switchTraffic(context.np, deploymentId, snapped);
+        }
+        await sleep(delays.afterTraffic);
+        const deployment = await getDeployment(context.np, deploymentId);
+        if (!scope && deployment.scope_id) {
+            scope = await getScope(context.np, deployment.scope_id).catch(() => undefined);
+        }
+        const orgSlug = await context.org.organizationSlug();
+        const snappedNote = args.percent !== undefined && snapTraffic(args.percent) !== args.percent
+            ? `${translate("traffic.snapped", { requested: args.percent, snapped: snapTraffic(args.percent) })}\n\n`
+            : "";
+        const { md, structured } = renderRollout({
+            deployment,
+            scope,
+            dashboard: dashboardLink(orgSlug, scope?.nrn),
+        });
+        return reply(snappedNote + md, structured);
+    },
+});

package/dist/ui.js

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXTENSION_ID, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY, registerAppResource, } from "@modelcontextprotocol/ext-apps/server";
+/**
+ * MCP Apps (ext-apps) glue — hosts that support interactive widgets (claude.ai web/desktop,
+ * ChatGPT, VS Code) render a UI for a tool's results; text-only hosts keep the markdown.
+ *
+ * Widgets are React (src/widgets-react), compiled by `npm run build:widgets` into fully
+ * self-contained HTML files under widgets-dist/ — the iframe sandbox blocks all fetches,
+ * so React + the ext-apps SDK are bundled inline per widget.
+ */
+export { EXTENSION_ID, RESOURCE_MIME_TYPE };
+/** Every widget this server can serve, by file name -> human title. */
+export const WIDGETS = {
+    "np-panel": "Application panel",
+    "create-app": "Create application",
+    params: "Parameters",
+    logs: "Logs",
+    "find-apps": "Applications",
+    metrics: "Metrics",
+};
+/** Did this session's client negotiate the MCP Apps extension? (Knowable after initialize.) */
+export function uiNegotiated(server) {
+    const caps = server.server.getClientCapabilities();
+    return Boolean(caps?.extensions?.[EXTENSION_ID]);
+}
+/** Hosts disagree on the _meta key shape — emit both the nested and the flat form. */
+export function uiMeta(resourceUri) {
+    return { ui: { resourceUri }, [RESOURCE_URI_META_KEY]: resourceUri };
+}
+const distDir = join(dirname(fileURLToPath(import.meta.url)), "..", "widgets-dist");
+const widgetCache = new Map();
+let manifestCache;
+function manifest() {
+    if (manifestCache)
+        return manifestCache;
+    let loaded;
+    try {
+        loaded = JSON.parse(readFileSync(join(distDir, "manifest.json"), "utf8"));
+    }
+    catch {
+        loaded = {};
+    }
+    manifestCache = loaded;
+    return loaded;
+}
+/** Content-hashed resource URI for a widget (stable fallback when not built yet). */
+export function widgetUri(name) {
+    return manifest()[name] ?? `ui://widgets/${name}.html`;
+}
+export function loadWidget(name) {
+    const hit = widgetCache.get(name);
+    if (hit)
+        return hit;
+    let html;
+    try {
+        html = readFileSync(join(distDir, `${name}.html`), "utf8");
+    }
+    catch {
+        throw new Error(`widget "${name}" not built — run \`npm run build:widgets\``);
+    }
+    widgetCache.set(name, html);
+    return html;
+}
+function registerWidget(server, title, file) {
+    const uri = widgetUri(file);
+    registerAppResource(server, title, uri, { _meta: { ui: { prefersBorder: true } } }, async () => ({
+        contents: [{ uri, mimeType: RESOURCE_MIME_TYPE, text: loadWidget(file) }],
+    }));
+}
+/** Register widget resources (deduped). The set normally derives from the tool registry. */
+export function registerWidgets(server, names) {
+    for (const name of new Set(names))
+        registerWidget(server, WIDGETS[name], name);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@nullplatform/mcp",
+  "version": "0.1.0",
+  "description": "nullplatform from your code assistant — an MCP server that replaces the dashboard for the everyday developer journey",
+  "license": "MIT",
+  "author": "nullplatform",
+  "homepage": "https://github.com/nullplatform/ai-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nullplatform/ai-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nullplatform/ai-mcp/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "nullplatform-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "widgets-dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "npm run build:widgets && tsx src/index.ts",
+    "build": "rm -rf dist widgets-dist && tsc -p tsconfig.json && node scripts/build-widgets.mjs",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:widgets": "node scripts/build-widgets.mjs",
+    "pretest": "node scripts/build-widgets.mjs",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p src/widgets-react/tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20.14.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.0",
+    "happy-dom": "^20.10.3",
+    "preact": "^10.29.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/skills/deploying-safely/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: deploying-safely
+description: Use when deploying, shipping, releasing or rolling out a nullplatform application — the safe rollout methodology - pre-flight checks, canary traffic steps with metric gates, finalize/rollback criteria.
+---
+
+# Deploying safely on nullplatform
+
+Deployments are blue/green: the new version comes up next to the old one, traffic moves
+over in steps you control, and nothing is destroyed until you finalize. Rollback is cheap
+**until** finalize; after it, going back means deploying the previous release again.
+
+## Pre-flight (always, before any deploy)
+
+1. Run `application_get` for the app. Confirm:
+   - No rollout already active on the target scope (one at a time per scope — the platform
+     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.
+   - 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
+   deploy — mention which parameters will take effect.
+
+## The rollout
+
+1. `application_deployment_create` (with `version:"x.y.z"` for a specific release, or defaults for latest).
+   - Multi-asset builds: the tool auto-picks by scope type (docker-image for web pools,
+     lambda for serverless). If it asks, choose the asset matching the scope's runtime.
+   - If the result is `creating_approval` ✋: STOP — an approver must allow it
+     (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:
+   - 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):
+   - `http.error_rate` rising above its pre-deploy baseline → rollback, don't rationalize.
+   - `http.response_time` degraded > ~30% sustained → hold the step, check `application_log_list`.
+   - CPU/memory near limits at partial traffic → it will not survive 100%; rollback and
+     fix sizing (scope capabilities) first.
+5. At 100% healthy: `application_deployment_update action:"finalize"`. Tell the user finalize retires the old
+   version — past this point rollback = redeploy of the previous release.
+
+## When in doubt
+
+`application_deployment_update action:"rollback"` returns ALL traffic to the old version immediately and safely.
+Prefer a needless rollback over a defended bad deploy. After rolling back, capture evidence
+(`application_log_list`, `application_metric_list`) before retrying.
+
+## 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.

package/skills/incident-response/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: incident-response
+description: Use when a nullplatform application is failing, degraded, erroring, slow or down — the triage runbook - establish state, read the right signals, mitigate first (rollback), then diagnose.
+---
+
+# Incident response on nullplatform
+
+Mitigate first, diagnose second. The fastest mitigation is almost always returning traffic
+to the last known-good version.
+
+## 1. Establish state (one call)
+
+`application_get` for the app. Read it as a timeline:
+- Is a rollout active or recent? An incident that started with a deploy is that deploy
+  until proven otherwise.
+- Which release is live on the affected scope, and since when ("When" column)?
+- Any scope in `failed` / approval-blocked state?
+
+## 2. Mitigate
+
+- Active rollout suspected → `application_deployment_update action:"rollback"` immediately. It is safe, fast,
+  and reversible (you can redeploy). Do not wait for full diagnosis.
+- Already finalized → redeploy the previous version: `application_deployment_create version:"<previous semver>"`
+  (the Releases line in `application_get` lists them in order), then walk traffic with the
+  deploying-safely methodology — faster this time, but still metric-gated.
+- No deploy correlation → likely capacity or dependency: check metrics first (below).
+
+## 3. Read the signals
+
+- `application_metric_list` (start 1h, widen to 24h to find when it broke):
+  - error rate up + response time up → app-level failure (recent code/config/dependency).
+  - response time up, errors flat → saturation: CPU/memory near 100% means the scope is
+    undersized — scaling/capability change, not rollback, is the fix.
+  - 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`.
+- `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.
+
+## 4. Close the loop
+
+After mitigation, confirm with `application_metric_list` (error rate back to baseline) AND the scope's
+domain URL responding. Summarize for the user: what broke, when, the mitigation applied,
+and the evidence — and leave the bad release identified so it isn't redeployed by the
+"latest" defaults.
+
+## 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 restart/recreate scopes as a first move; that destroys the evidence and rarely
+  fixes the cause.

package/skills/platform-conventions/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: platform-conventions
+description: Use when interpreting nullplatform entities — applications, builds, releases, scopes, deployments, dimensions, parameters - what each is, how they chain, and the platform's semantics and gotchas.
+---
+
+# nullplatform conventions
+
+## The entity chain
+
+```
+application ← build (CI) ← asset(s) ← release (semver) → deployment → scope
+```
+
+- **Builds** come only from CI (push a commit); they cannot be created here.
+- A **release** is an immutable semver pointer to a build. Deploys ship releases, never
+  builds directly. Latest build ≠ latest release until someone cuts it.
+- A **scope** is a deploy target (real infrastructure: k8s pool, EC2, serverless…).
+  Its `domain` is the live URL. Creating one provisions infra — treat as a real action.
+- A **deployment** is one release landing on one scope, with blue/green traffic control.
+
+## Dimensions
+
+Scopes carry org-defined dimensions like `environment` and `country`
+(e.g. `environment=production · country=argentina`). Conventions:
+- "deploy to production" means the scope whose `environment=production` — match by
+  dimension, not by the scope's display name.
+- Dimension *definitions* are admin-gated; infer valid shapes from sibling scopes.
+- New scopes in dimension-using orgs must carry dimensions (tools borrow a sibling's
+  shape by default).
+
+## 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 —
+  that's also how you roll back after a finalize.
+
+## Parameters
+
+- Env vars or files, app-NRN scoped, optionally secret (values never readable again).
+- Changes take effect ONLY on the next deploy of each scope — saying "parameter updated"
+  without mentioning the pending redeploy is misleading.
+
+## Traffic & lifecycle semantics
+
+- Traffic percentages snap to: 1, 5, 10, 25, 50, 75, 90, 95, 99, 100.
+- 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.
+- 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".
+- 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.
+- Every entity has an NRN and a dashboard deep link (`…app.nullplatform.io/nrn/<nrn>`) —
+  offer it when the user needs surfaces this integration doesn't cover (approvals UI,
+  scope capability editing, team management).