@nullplatform/mcp 0.1.2 → 0.1.4

package/dist/ui.js

@@ -19,6 +19,9 @@ export const WIDGETS = {
     logs: "Logs",
     "find-apps": "Applications",
     metrics: "Metrics",
+    builds: "Builds",
+    releases: "Releases",
+    deployments: "Deployments",
 };
 /** Did this session's client negotiate the MCP Apps extension? (Knowable after initialize.) */
 export function uiNegotiated(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.

package/skills/understand-a-service/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: understand-a-service
+description: Use when getting oriented on an unfamiliar or inherited nullplatform application — what it is, where it runs, what it depends on, and how it is configured — before changing anything.
+---
+
+# Understanding a service on nullplatform
+
+Build the picture by fusing two views — the platform's and the repo's — read-only, before you
+touch anything. Establish current state AND how it got there before forming any plan.
+
+## 1. Resolve which app
+
+Inside a linked repo the app is inferred from the git remote. Confirm you mean **this repo's**
+app, not a similarly-named other one, and say which app (and scope) you're describing.
+
+## 2. The platform view
+
+- `application_get` — what's live where: the scopes (environments) and their dimensions, the
+  release each one serves, and recent activity. This is the spine of the picture.
+- `application_service_list` — the dependencies (databases, queues, caches…) and their status. A
+  dependency in a non-active state is part of "how it runs", not a footnote.
+- `application_parameter_list` — the config surface (names; secret values masked). What's
+  configured tells you what the service expects from its environment.
+
+## 3. The repo view (what the dashboard can't see)
+
+You're running in the developer's environment — read it. The `README`, `package.json` /
+`Dockerfile` (language, runtime, entrypoint, ports), the default branch, and recent `git log`
+(what's changing, and by whom). This is the half a web dashboard structurally lacks, and it's
+where this integration earns its keep.
+
+## 4. Correlate the two
+
+- Does the release on the main scope match the repo's `HEAD`? A gap means production is behind
+  (or ahead of) what's checked out — say so.
+- How many environments are there, and how do they differ (dimensions, releases)?
+- What does the service talk to, and is each dependency provisioned and active?
+
+## 5. Summarize, don't act
+
+Give the user a grounded picture: what the service is, where it runs, what it depends on, how
+it's configured, and what's live. For ownership, teams, and other surfaces this integration
+doesn't cover, deep-link to the dashboard.
+
+## Don'ts
+
+- Stay read-only until you have the picture: no deploy, config change, or scope edit while still
+  learning.
+- Don't assume the repo you're in is the app — confirm the git remote matches before you describe
+  anything as fact.

package/skills/working-from-a-ticket/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: working-from-a-ticket
+description: Use when starting from a tracker work item (Jira, GitHub Issues, Linear, …) — read or create the ticket, implement it in the repo, ship it through nullplatform, and report status back to the ticket.
+---
+
+# Working from a ticket on nullplatform
+
+nullplatform owns the delivery half — build → release → deploy. The ticket is the *intent* half,
+and it lives in the developer's own tracker, reached through whatever issue-tracker connection
+they've set up (Jira, GitHub Issues, Linear, …) — not through nullplatform. Your job is to carry
+one work item across the whole loop and close it. The thread that ties intent to delivery is the
+**commit**: keep the issue key on the branch and the commit so the change stays traceable end to
+end (see `tracing-a-change`).
+
+## 1. Get the work item
+
+- Have a ticket → read it from the connected tracker. Pull out the change, the acceptance
+  criteria, and the issue key (e.g. `PROJ-123`).
+- No ticket yet → draft one from repo + platform context (what the app is, what's live — see
+  `understand-a-service`) and create it in the tracker. Confirm the title and description with the
+  user before creating it — it's an external write.
+
+## 2. Implement it
+
+Work on a branch named for the issue key, and put the key in the commit / PR. Implement against the
+acceptance criteria with your normal approach — plan, code, tests — that's your own craft, not this
+playbook's job. The one thing that matters here: the issue key must ride the commit, because that
+is what lets the deploy be traced back to the ticket afterwards.
+
+## 3. Deliver it
+
+Push so CI builds (the build records the commit). Watch it land with `application_build_list`, then
+ship it with `deploying-safely`, or move it from a lower environment with
+`promoting-across-environments`.
+
+## 4. Close the loop
+
+Once it's live on the target scope and verified, report back to the ticket — the release it shipped
+in, the environment, and the commit — and move its state. Posting to the tracker is an external
+write: confirm with the user first, and don't mark a ticket done before it's actually deployed and
+healthy (merged ≠ deployed).
+
+## Don'ts
+
+- Don't lose the issue key — no key on the commit, no traceability back from a deploy.
+- Don't create or update a tracker item without the user's ok.
+- Don't close a ticket on merge; close it when the change is live and verified.