@nullplatform/mcp 0.1.13 → 0.1.14

package/dist/np/context.js

@@ -124,9 +124,13 @@ export class NpContext {
     /** Search apps by partial name (and/or namespace name) across the whole org — parallel + cached. */
     async findApps(args = {}) {
         const skeleton = await this.getSkeleton();
-        const namespaceFilter = args.namespace?.toLowerCase();
+        // Match namespace names leniently: strip case AND non-alphanumerics on both sides so "pablov",
+        // "pablo v" and "Pablo-V" all resolve the namespace displayed as "Pablo V" (a strict substring
+        // missed it on the space, which is why a namespace query fell back to dumping the whole org).
+        const normalize = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, "");
+        const namespaceFilter = args.namespace ? normalize(args.namespace) : undefined;
         const namespaces = namespaceFilter
-            ? skeleton.namespaces.filter((namespace) => namespace.name.toLowerCase().includes(namespaceFilter))
+            ? skeleton.namespaces.filter((namespace) => normalize(namespace.name).includes(namespaceFilter))
             : skeleton.namespaces;
         const nameFilter = args.query?.toLowerCase();
         // `/application` is namespace-scoped with no name filter, so page each namespace to completion

package/dist/surfaces/developer.js

@@ -14,9 +14,16 @@ Every tool accepts \`language\`: ALWAYS set it to the language the user is conve
 
 Most tools render an interactive panel in clients that support it — apps, status, builds, releases, deployments, logs, metrics, parameters and approvals all appear as live UI. **When a tool's panel renders, that panel IS the answer: do not reproduce its data in your text reply.** The user already sees every row, status and value. NEVER print a markdown table of the same rows, re-list the items, or restate per-row status — duplicating the panel in text is the single most common mistake. Reply with AT MOST one short sentence — the one key takeaway or the next step — or nothing at all. A one-line insight the panel doesn't itself show is fine ("builds 3 and 5 were never released"); re-rendering the list as a table is not.
 
-When the user wants to create, scaffold, set up or import an application, drive it through the \`application_create\` FORM — its panel collects the namespace, template and repository. Two rules keep this clean. (1) Settle any genuinely STRUCTURAL question about WHAT to build — e.g. "is this one app or two, a frontend and an API?" — in one short turn BEFORE opening any form, since each app gets its own form. (2) Never gather FORM-FIELD details (namespace, template, new-vs-import repository, monorepo path) in conversation: INFER the best-fitting namespace and account from what the app is FOR — a demo → a demos/examples namespace, a backend service → a services namespace — and pass them as \`namespace\`/\`account\` (plus \`name\` if given) so the form opens pre-selected on your inference; the user changes it in the form if they want. Once a form is on screen, NEVER ask a clarifying question or use any question-asking tool about a field it covers — above all NEVER ask "which namespace?". And NEVER open the form, ask a question, then re-open the form: that form → question → form flow is the single worst thing you can do here. Open it once, pre-filled, and let it drive; react only to what it reports back.
+NEVER render a panel-rendering read MORE THAN ONCE to answer one question — not in a wait loop, and not fanned out across several apps/scopes. Two shapes of this mistake:
+- POLLING a changing status (a build finishing, a deployment rolling out, an app going active): do the waiting with the DATA-ONLY reads (\`entity_get\`/\`entity_list\`, which render NO panel) — e.g. loop \`entity_get entity:"build" id:<id>\` until its status is final. Re-calling \`application_get\` once per poll repaints the whole panel every iteration and stacks identical panels down the chat (the "looping on app_get" mistake).
+- AGGREGATING or COMPARING across many entities ("the latest release across all my apps", "which scope is on the newest build", "do any apps have failing builds"): do NOT call \`application_release_list\`/\`application_build_list\`/… once per app and dump a panel for each — that floods the chat and still doesn't answer the question. Gather headlessly with \`entity_list\` per app (\`entity_list entity:"release" parent_type:"application" parent_id:<id>\`), compute the answer yourself (sort by created_at, pick the max), and ANSWER IT — in one sentence ("the newest is auth-api 0.0.2, cut today"), or by rendering a SINGLE panel for just the one app/entity worth showing. The user asked for an answer, not N lists to eyeball.
+Render headlessly while you gather; show a panel at most once, for the one state worth seeing.
 
-Creating a NEW app is the PLATFORM's job, never a local scaffold. nullplatform creates the GitHub repository from a template and provisions it — so for a new app you must NEVER run a generic brainstorm/design/implementation process, never \`git init\`, never create an empty repo, and never write code locally first. The flow is: settle what to build → \`application_create\` with a new repo and ONE OF THE PLATFORM'S TEMPLATES → the platform creates the repo on GitHub → THEN clone it, add code, push so CI builds. The available STACKS are exactly those templates for the chosen namespace — never invent or offer a stack of your own ("Next.js", "Express", …); the form lists the real templates, choose from those. And do NOT fire the rendering reads (\`application_list\`/\`application_get\`/\`application_build_list\`…) just to orient yourself before any of this — each renders a panel the user didn't ask for. To gather data for your OWN reasoning, navigate the entity tree headlessly with \`entity_list\` and \`entity_get\` — read-only, DATA-only, NO panel. \`entity_list\` lists a collection scoped to its parent (the tree is organization → account → namespace → application → {scope, build, release}; scope → deployment): e.g. \`entity_list entity:"application" parent_type:"namespace" parent_id:11\`, then \`entity_list entity:"build" parent_type:"application" parent_id:123\`. \`entity_get entity:"application" id:123\` reads one. Parameters, services, links and approvals list the same way under an application or scope (\`entity_list entity:"parameter" parent_type:"application" parent_id:123\`). That is how you learn where apps live, how they're named, and what's deployable without putting a list on the user's screen. Reserve the rendered reads (\`application_list\`/\`application_get\`/\`application_build_list\`/…) for when the user actually wants to SEE that data.
+EVERY form this server opens follows one contract — app creation, service provisioning, scope creation, parameter setting, service linking, release creation, all of them. (1) GATHER what you need to pre-fill BEFORE opening the form: settle structural choices and ask for the missing context first, and ask any enumerable choice INTERACTIVELY (the client's question/choice tool with concrete options) so the user clicks rather than reads a typed list — free-text fields the form already has (a name, a URL) you let the form collect. (2) Open the form ONCE, pre-filled from your inference: carry each best-guess in as the field's hint (a namespace, a stack/template, a service \`type\`…) so the tool pre-selects it — never describe the choice in prose and leave the picker blank, and never open a blank or half-filled form and keep asking. (3) Once the form is on screen, NEVER ask a clarifying question or fire a question tool about a field the form already covers — those controls ARE the form; you only react to what it reports back. The rest of this section is that contract applied to app creation; the same three rules hold for every other form.
+
+When the user wants to create, scaffold, set up or import an application, drive it through the \`application_create\` FORM — its panel collects the namespace, template and repository. Two rules keep this clean. (1) Settle any genuinely STRUCTURAL question about WHAT to build — e.g. "is this one app or two, a frontend and an API?" — in one short turn BEFORE opening any form, since each app gets its own form. (2) Never gather FORM-FIELD details (namespace, template, new-vs-import repository, monorepo path) in conversation: INFER the best-fitting namespace and account from what the app is FOR — a demo → a demos/examples namespace, a backend service → a services namespace — and pass them as \`namespace\`/\`account\` (plus \`name\` if given) so the form opens pre-selected on your inference; the user changes it in the form if they want. When the request gives you NOTHING to infer from — a bare "create an app" with no hint of what it's for or what to call it — FINISH gathering context BEFORE opening any form: ask what the app is FOR (this fixes the namespace) and what to NAME it, and WAIT for both answers. Ask the "what is it for" part as an INTERACTIVE question — use the client's question/choice tool (e.g. AskUserQuestion) with concrete options (a backend API, a frontend, a demo, a worker/queue consumer, a CLI…) so the user picks in one click instead of reading a typed list; the NAME is free text, so ask it alongside or let the form's NAME field collect it, but never force a name into a multiple-choice question. Only THEN open the form, once, fully pre-filled — namespace inferred from the purpose, name carried in via \`name\`. Do NOT open the form "in the meantime", "while you're at it", or "to save time" with a question still pending: the form comes AFTER the context is in hand, never alongside an open question, and never half-filled while you keep asking. Opening a blank or partial form and continuing to ask is the form → question anti-pattern and the single worst thing you can do here. So: enough context already in the request → open the form pre-filled, no questions; missing context → gather ALL of it first (purpose AND name), THEN the one fully pre-filled form. Once a form is on screen, NEVER ask a clarifying question or use any question-asking tool about a field it covers — above all NEVER ask "which namespace?". The form ALREADY contains a "New repository | Import existing" toggle, a namespace picker, a template picker and a monorepo path field — so NEVER, after opening it, present a question like "How should the repository be set up?" with "New from template / Import existing" options, and never re-ask namespace or template: those controls ARE the form, and duplicating them as a follow-up question is the exact mistake to avoid (it is what produces the form-then-question screen). Any question you genuinely need comes BEFORE the form and the form opens AFTER it, pre-filled; once the form is up, the only thing you do is react to what it reports back.
+
+Creating a NEW app is the PLATFORM's job, never a local scaffold. nullplatform creates the GitHub repository from a template and provisions it — so for a new app you must NEVER run a generic brainstorm/design/implementation process, never \`git init\`, never create an empty repo, and never write code locally first. The flow is: settle what to build → \`application_create\` with a new repo and ONE OF THE PLATFORM'S TEMPLATES → the platform creates the repo on GitHub → THEN clone it, add code, push so CI builds. The available STACKS are exactly those templates for the chosen namespace — never invent or offer a stack of your own ("Next.js", "Express", …); the form lists the real templates, choose from those. Carry your stack inference into the form the SAME way you carry the namespace: pass \`template\` with the stack you'd pick from what the app is FOR (a Go API → "go", a React frontend → "react"/"node", a Python service → "python") and the form opens with that template pre-selected — don't just name the best fit in prose and leave the field blank. This pre-fill-from-inference rule is general: every create/fill form (template, service \`type\`, scope, …) pre-selects from the hint you pass, so always pass the hint rather than describing the choice and leaving the picker empty. And do NOT fire the rendering reads (\`application_list\`/\`application_get\`/\`application_build_list\`…) just to orient yourself before any of this — each renders a panel the user didn't ask for. To gather data for your OWN reasoning, navigate the entity tree headlessly with \`entity_list\` and \`entity_get\` — read-only, DATA-only, NO panel. \`entity_list\` lists a collection scoped to its parent (the tree is organization → account → namespace → application → {scope, build, release}; scope → deployment): e.g. \`entity_list entity:"application" parent_type:"namespace" parent_id:11\`, then \`entity_list entity:"build" parent_type:"application" parent_id:123\`. \`entity_get entity:"application" id:123\` reads one. Parameters, services, links and approvals list the same way under an application or scope (\`entity_list entity:"parameter" parent_type:"application" parent_id:123\`). That is how you learn where apps live, how they're named, and what's deployable without putting a list on the user's screen. Reserve the rendered reads (\`application_list\`/\`application_get\`/\`application_build_list\`/…) for when the user actually wants to SEE that data.
 
 Typical flows:
 - Ship: \`application_deployment_create\` (picks the latest build, cuts the release for you) → \`application_deployment_update percent:25/50/100\` → \`application_deployment_update action:"finalize"\`.

package/dist/tools/approvals.js

@@ -14,7 +14,7 @@ import { appArg, requireApp } from "./shared.js";
 export const approvalsTool = defineTool({
     name: TOOL.applicationApprovalList,
     title: "Approvals",
-    description: 'List the approvals gating an application\'s actions (e.g. a deployment waiting on a policy), and act on one. action:"approve" lets the gated action proceed; action:"cancel" cancels the request. Both use your own permissions — the platform denies what you\'re not allowed to do. Use this when a deploy is stuck in creating_approval.',
+    description: 'List the approvals gating an application\'s actions (e.g. a deployment waiting on a policy), rendered as a PANEL, and act on one. action:"approve" lets the gated action proceed; action:"cancel" cancels the request — both run with YOUR own permissions, so the platform denies what you\'re not allowed to do. Use it when "a deploy is stuck", "creating_approval", "approve the deployment", "what\'s waiting on approval". Does NOT deploy or change traffic — it only resolves the gate; the gated action proceeds on its own once approved.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "approvals",
     errorKey: "approvals.errorLabel",

package/dist/tools/builds.js

@@ -13,7 +13,7 @@ import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
 export const buildsTool = defineTool({
     name: TOOL.applicationBuildList,
     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).",
+    description: "List ONE application's recent CI builds as a PANEL for the user — 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. Do NOT call this once per app to compare across apps, and do NOT loop it to wait for a build to finish (it renders a panel each time): for an AGGREGATE across apps use entity_list (entity:\"build\"), and to POLL a build to completion use entity_get (entity:\"build\" id:<id>) — both headless.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "builds",
     errorKey: "builds.errorLabel",

package/dist/tools/create-app.js

@@ -4,24 +4,24 @@ import { dashboardLink, glyph, linkLine, next } from "../md.js";
 import { createApplication, getApplication, listTemplates } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { delays, httpsRepoUrl, sleep } from "./shared.js";
-function pickNamespace(namespaces, hints) {
+import { delays, httpsRepoUrl, resolveChoice, sleep } from "./shared.js";
+export function pickNamespace(namespaces, hints) {
+    // Namespace is the generic resolveChoice with one extra twist — account narrowing. An explicit id is
+    // unambiguous, so honour it against the FULL list FIRST (the account filter only disambiguates a
+    // repeated NAME; it must never veto a real id). Then resolve the name within the named account, and
+    // fall back to all namespaces so a correct name still pins even when the account label doesn't line up.
+    const byId = resolveChoice(namespaces, { id: hints.namespace_id });
+    if (byId)
+        return byId;
     const accountQuery = hints.account?.toLowerCase();
-    const narrowed = accountQuery
+    const inAccount = accountQuery
         ? namespaces.filter((candidate) => (candidate.account_name ?? "").toLowerCase().includes(accountQuery))
         : namespaces;
-    const candidates = narrowed.length ? narrowed : namespaces;
-    if (hints.namespace_id) {
-        const byId = candidates.find((candidate) => candidate.id === hints.namespace_id);
-        if (byId)
-            return byId;
-    }
-    if (hints.namespace) {
-        const query = hints.namespace.toLowerCase();
-        const matches = candidates.filter((candidate) => candidate.name.toLowerCase().includes(query));
-        if (matches.length === 1)
-            return matches[0];
-    }
+    const named = resolveChoice(inAccount.length ? inAccount : namespaces, { text: hints.namespace }) ??
+        resolveChoice(namespaces, { text: hints.namespace });
+    if (named)
+        return named;
+    const candidates = inAccount.length ? inAccount : namespaces;
     if (candidates.length === 1)
         return candidates[0];
     return undefined;
@@ -41,11 +41,11 @@ async function buildFormReply(context, prefill) {
     // of the global set. Fetch only once a namespace is pinned (the widget refetches per namespace on
     // change); the org-level NRN returns a misleading near-empty subset.
     const templates = picked ? await listTemplates(context.np, picked.nrn).catch(() => []) : [];
-    // Same contract for the template: honour a passed id, pin the only one, else leave it unselected —
-    // never silently scaffold the first stack in the list (a wrong stack is worse than a deliberate pick).
-    const templateId = (prefill.template_id && templates.some((template) => template.id === prefill.template_id)
-        ? prefill.template_id
-        : null) ?? (templates.length === 1 ? (templates[0]?.id ?? null) : null);
+    // Same generic rule as the namespace: resolve the model's stack hint (`template`) — or an explicit
+    // template_id — against THIS namespace's templates, matching on name + tags, and pin the only one.
+    // Leave it null when it's a real unhinted choice; never silently scaffold the first stack in the list
+    // (a wrong stack is worse than a deliberate pick).
+    const templateId = resolveChoice(templates, { id: prefill.template_id, text: prefill.template }, { pinOnly: true, haystack: (template) => `${template.name} ${(template.tags ?? []).join(" ")}` })?.id ?? null;
     const namespaces = skeleton.namespaces.map((namespace) => ({
         id: namespace.id,
         name: namespace.name,
@@ -75,7 +75,7 @@ async function buildFormReply(context, prefill) {
 export const createAppTool = defineTool({
     name: TOOL.applicationCreate,
     title: "Create application",
-    description: "Create a nullplatform application. INFER the best-fitting namespace and account from what the app is FOR (a demo → a demos/examples namespace, a backend service → a services namespace) and pass them as `namespace`/`account` so the form opens pre-selected on your inference — the user can still change it. Calling with NO repository_url opens an interactive form and creates nothing — the user confirms the namespace, then either a NEW repository (scaffolded from a template, repo URL auto-generated) or IMPORTS an existing repository (optionally a monorepo folder), and the form calls back with a repository_url to actually create. Only an explicit repository_url performs the create, so opening the form never writes anything. Provisioning is async — the create waits briefly and reports progress.",
+    description: 'Create a nullplatform application. GATE FIRST: if the request is bare and gives you NOTHING to infer from (e.g. just "create an app" / "create a new application" with no hint of what it\'s for or what to name it), DO NOT call this tool yet — first ask the user, in chat, what the app is for AND what to name it, and WAIT for both; call this only once you have the purpose (to pre-fill the namespace) AND the name in hand. Do NOT call it in the meantime, while still waiting on the name — opening a blank or half-filled form and continuing to ask is a failure, not a fallback. When you DO have context, INFER the best-fitting namespace and account from what the app is FOR (a demo → a demos/examples namespace, a backend service → a services namespace) and pass them as `namespace`/`account` so the form opens pre-selected on your inference — the user can still change it. Calling without `provision:true` opens an interactive form and creates nothing — the user confirms the namespace, then either a NEW repository (scaffolded from a template, repo URL auto-generated) or IMPORTS an existing repository (optionally a monorepo folder), and the form itself submits with provision:true to actually create. Only the form\'s submit sets provision:true; you (the model) NEVER set it and NEVER pass a repository_url to "pre-fill" expecting a create — passing a repository_url without provision just opens the form, it does NOT write anything. Provisioning is async — the create waits briefly and reports progress.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "create-app",
     errorKey: "createApp.errorLabel",
@@ -94,6 +94,10 @@ export const createAppTool = defineTool({
             .string()
             .optional()
             .describe("Full git repo URL. New repos: auto-generated from the account + name. Import: the existing URL."),
+        template: z
+            .string()
+            .optional()
+            .describe('Template/stack to scaffold from — INFER it from what the app is FOR (a Go service → "go", a React frontend → "react"/"node", a Python API → "python") and pass the stack you would choose. The tool matches it against the chosen namespace\'s real templates and pre-selects it; prefer template_id only when you already know the exact id.'),
         template_id: z
             .number()
             .optional()
@@ -102,22 +106,28 @@ export const createAppTool = defineTool({
             .string()
             .optional()
             .describe("Import only: the folder inside a monorepo that holds this application"),
+        provision: z
+            .boolean()
+            .optional()
+            .describe("Set true ONLY to actually create the app + repository — this is the form's Create button. Omit it to open/pre-fill the form, even when you pass a repository_url: opening or pre-filling NEVER creates anything. You (the model) must NOT set this; the user confirms by submitting the form."),
     },
     async handler(args, context) {
-        // Create ONLY on an explicit repository_url (the form's Create button, or a deliberate
-        // call). With none, return the form and create nothing. create_app does NOT read the
-        // ambient git remote: opening the form, switching namespace, or running the MCP inside some
-        // repo must never auto-create an app behind the user's back (the bug where "let's create an
-        // app" silently created the MCP's own repo). The user chooses the repository in the form.
+        // Create ONLY on an explicit provision:true (the form's Create button). The presence of a
+        // repository_url is NOT the trigger: the model routinely passes one to PRE-FILL the form, and
+        // treating that as "create now" silently provisioned an app the user never confirmed (the bug
+        // where the panel jumped straight to "Creating…"). So opening or pre-filling the form — with or
+        // without a repository_url — creates nothing; the user submits to create. create_app also does
+        // NOT read the ambient git remote, so running the MCP inside some repo never auto-creates either.
         const repoUrl = args.repository_url ? httpsRepoUrl(args.repository_url) : undefined;
-        if (!repoUrl) {
+        if (!args.provision || !repoUrl) {
             return buildFormReply(context, {
                 name: args.name,
                 account: args.account,
                 namespace: args.namespace,
                 namespace_id: args.namespace_id,
+                template: args.template,
                 template_id: args.template_id,
-                repository_url: null,
+                repository_url: args.repository_url ?? null,
             });
         }
         // Convergent under retries: a repo already linked to an app returns that app, never a duplicate.
@@ -187,6 +197,8 @@ export const createAppTool = defineTool({
                 name,
                 account: args.account,
                 namespace: args.namespace,
+                template: args.template,
+                template_id: args.template_id,
                 repository_url: repoUrl,
             });
         }

package/dist/tools/create-link.js

@@ -20,7 +20,7 @@ const slug = (text) => text
 export const createLinkTool = defineTool({
     name: TOOL.applicationLinkCreate,
     title: "Link service",
-    description: "Link a provisioned dependency service (a database, queue, cache, …) to an application or one of its scopes so its connection details flow in as read-only parameters. Pass `service` to choose which one (by name). A credential link (e.g. a Postgres database-user) provisions a user with the permissions you pick, so call WITHOUT `create:true` first to open the form; the user confirms by submitting it. New parameters reach the runtime on the NEXT deploy.",
+    description: 'LINK a provisioned dependency service (a database, queue, cache, …) to an application or one of its scopes so its connection details flow in as read-only parameters. Use it for "connect/link the database to <app/scope>", "wire up the queue". Pass `service` (by name) and optionally a `scope` (default: the whole app). A credential link (e.g. a Postgres database-user) provisions a user with the permissions you pick, so call WITHOUT `create:true` first to open the form; the user confirms by submitting. New parameters reach the runtime on the NEXT deploy. Provision the service first with application_service_create.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "service-link",
     errorKey: "createLink.errorLabel",

package/dist/tools/create-release.js

@@ -8,7 +8,7 @@ import { appArg, requireApp } from "./shared.js";
 export const createReleaseTool = defineTool({
     name: TOOL.applicationReleaseCreate,
     title: "Create release",
-    description: "Cut an active release from a build (default: the latest successful build; semver auto-bumps the patch). Usually you can just call deploy, which does this for you.",
+    description: 'Cut an active RELEASE from a build (default: the latest successful build; semver auto-bumps the patch) — a release is a deployable, versioned pin of a build. Use it for "cut a release", "create a release from build X" WITHOUT deploying. Usually you do NOT need this directly: application_deployment_create cuts the release for you as part of shipping — reach for this only when the user explicitly wants a release but not a deploy. Convergent: reuses the existing active release for the same build rather than duplicating. Renders the releases panel; deploy a release with application_deployment_create.',
     // Convergent under retries (reuses the active release-for-build), so idempotent.
     annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
     widget: "releases",

package/dist/tools/create-scope.js

@@ -9,7 +9,7 @@ import { buildAppStatus } from "./status.js";
 export const createScopeTool = defineTool({
     name: TOOL.applicationScopeCreate,
     title: "Create scope",
-    description: "Create a scope (a deploy target, e.g. dev/staging/main) for an application. This provisions real infrastructure asynchronously. If the org has several scope types and none is given, it lists them to pick from.",
+    description: 'Create a SCOPE — a deploy target (e.g. dev/staging/main) — for an application; provisions real infrastructure asynchronously. Use it for "add a dev/staging/prod environment", "create a scope", "set up a new deploy target". Pass `name`; the scope `type` is inferred or auto-pinned when the org has one, else the form lists the org\'s types to pick from; `dimensions` default to the shape of an existing scope when the org uses them. Convergent: an existing scope of the same name is returned, never duplicated. Renders the app panel; once active, deploy to it with application_deployment_create scope:"<name>".',
     // Convergent under retries (reuses the scope-by-name), so idempotent.
     annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
     widget: "np-panel",

package/dist/tools/create-service.js

@@ -4,7 +4,7 @@ import { dashboardLink, linkLine, next, table } from "../md.js";
 import { createServiceAction, getService, listAppServices, listDependencySpecs, provisionService, serviceCreateActionSpec, } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { appArg, delays, requireApp, sleep } from "./shared.js";
+import { appArg, delays, requireApp, resolveChoice, sleep } from "./shared.js";
 const slug = (text) => text
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
@@ -66,23 +66,23 @@ export const createServiceTool = defineTool({
             return fail(translate("createService.noSpecs", { app: app.name }) +
                 linkLine(translate("md.dashboard"), dashboard));
         }
-        // Match the requested dependency: exact id (form submit) wins; else fuzzy `type`. None or
-        // ambiguous → return the catalog to pick from.
-        const direct = args.specification_id
-            ? specs.find((spec) => spec.id === args.specification_id)
-            : undefined;
-        const matches = direct ? [direct] : args.type ? matchSpecs(specs, args.type) : [];
-        if (matches.length !== 1) {
-            const list = matches.length > 1 ? matches : specs;
-            const heading = translate(matches.length > 1 ? "createService.matchAmbiguous" : "createService.pickSpec", {
+        // Pre-select via the shared resolver (same rule as namespace/template): an exact spec id (form
+        // submit) or the model's `type` hint, matched against the catalog on name + category + sub-category.
+        // None / ambiguous → return the catalog (or the narrowed matches) to pick from — never an arbitrary one.
+        const spec = resolveChoice(specs, { id: args.specification_id, text: args.type }, {
+            haystack: (candidate) => `${candidate.name} ${candidate.category ?? ""} ${candidate.subCategory ?? ""}`,
+        });
+        if (!spec) {
+            const typed = args.type ? matchSpecs(specs, args.type) : [];
+            const list = typed.length > 1 ? typed : specs;
+            const heading = translate(typed.length > 1 ? "createService.matchAmbiguous" : "createService.pickSpec", {
                 app: app.name,
                 query: args.type ?? "",
                 count: specs.length,
             });
-            const md = `${heading}\n\n${table([translate("header.name"), translate("createService.category"), translate("createService.provider")], list.map((spec) => [spec.name, specCategory(spec), spec.provider ?? ""]))}${next(translate("createService.pickHint"))}`;
+            const md = `${heading}\n\n${table([translate("header.name"), translate("createService.category"), translate("createService.provider")], list.map((candidate) => [candidate.name, specCategory(candidate), candidate.provider ?? ""]))}${next(translate("createService.pickHint"))}`;
             return reply(md, { mode: "pick-spec", app: `#${app.id}`, app_name: app.name, specs: list, dashboard });
         }
-        const spec = matches[0];
         const createAction = await serviceCreateActionSpec(context.np, spec.id);
         const name = (args.name ?? spec.name).trim();
         // Form-first: no explicit provision OR a required create-action param still missing → show the

package/dist/tools/delete-link.js

@@ -19,7 +19,7 @@ const slug = (text) => text
 export const deleteLinkTool = defineTool({
     name: TOOL.applicationLinkDelete,
     title: "Delete link",
-    description: "Delete a link between a service and an application, removing the parameters it exported. Pass `link` to choose which one (by name); call WITHOUT `confirm:true` first to preview, the user confirms by submitting. A credential link deprovisions its database user before the record is removed; a redeploy applies the parameter removal to the runtime.",
+    description: 'DELETE a link between a service and an application, removing the parameters it exported. Use it for "unlink/disconnect the <service> from <app>", "remove the link". Pass `link` (by name); call WITHOUT `confirm:true` first to open a confirm form (preview), the user confirms by submitting it. A credential link deprovisions its database user before the record is removed; a redeploy applies the parameter removal to the runtime. Destructive; nothing is removed without the submit.',
     annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
     widget: "service-delete",
     errorKey: "deleteEntity.linkErrorLabel",

package/dist/tools/delete-param.js

@@ -13,7 +13,7 @@ import { appArg, requireApp } from "./shared.js";
 export const deleteParamTool = defineTool({
     name: TOOL.applicationParameterDelete,
     title: "Delete parameter",
-    description: "Delete an application configuration parameter (the whole variable and all its values). Pass `name`; call WITHOUT `confirm:true` first to preview, the user confirms by submitting. Read-only parameters injected by a service link can't be deleted here — delete the link instead. Applies on the next deploy.",
+    description: 'DELETE an application configuration parameter — the whole variable and ALL its values. Use it for "delete/remove the <NAME> env var/parameter". Pass `name`; call WITHOUT `confirm:true` first to open a confirm form (preview), the user confirms by submitting it. Read-only parameters injected by a service link can\'t be deleted here — delete the link instead (application_link_delete). Applies on the next deploy. To CHANGE a value instead of removing it, use application_parameter_create.',
     annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "deleteParam.errorLabel",

package/dist/tools/delete-service.js

@@ -19,7 +19,7 @@ const slug = (text) => text
 export const deleteServiceTool = defineTool({
     name: TOOL.applicationServiceDelete,
     title: "Delete service",
-    description: "Delete a provisioned service and destroy its cloud resources. Pass `service` to choose which one (by name); call WITHOUT `confirm:true` first to see what will be destroyed, the user confirms by submitting. A service with active links can't be deleted — remove the links first (application_link_delete).",
+    description: 'DELETE a provisioned service and destroy its cloud resources. Use it for "delete/remove/tear down the <service>". Pass `service` (by name); call WITHOUT `confirm:true` first to open a confirm form showing what will be destroyed, the user confirms by submitting it. A service with active links can\'t be deleted — remove the links first with application_link_delete. Destructive and not reversible; nothing is destroyed without the submit.',
     annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
     widget: "service-delete",
     errorKey: "deleteEntity.serviceErrorLabel",

package/dist/tools/deploy.js

@@ -82,7 +82,7 @@ async function resolveRelease(context, applicationId, args) {
 export const deployTool = defineTool({
     name: TOOL.applicationDeploymentCreate,
     title: "Deploy",
-    description: 'Ship an application: deploys the latest code with sensible defaults — uses the latest successful build, creates the release for you (semver auto-bump) if needed, targets the app\'s only scope (or scope:"name"). Returns the live rollout view. For an app with traffic, follow with the traffic tool to move traffic over.',
+    description: 'DEPLOY an application — provisions real infrastructure (starts a rollout), rendered as the live rollout panel. With no extra args it ships the latest code: picks the latest successful build, cuts the release for you (semver auto-bumped) if needed, and targets the app\'s only scope. Use it for "deploy", "ship it", "release to dev/prod". Narrow the target with `scope` (name or "environment=production"); pin an exact `release_id` or `version` (a known version rolls FORWARD or BACK to it); or cut from a specific `build_id`. For an app that splits traffic, FOLLOW with application_deployment_update to walk traffic to the new version; to undo, application_deployment_update action:"rollback". Convergent under retries: re-running returns the in-flight rollout for the same scope+release rather than creating a duplicate.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "np-panel",
     errorKey: "deploy.errorLabel",

package/dist/tools/deployments.js

@@ -13,7 +13,7 @@ import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
 export const deploymentsTool = defineTool({
     name: TOOL.applicationDeploymentList,
     title: "Deployments",
-    description: "List an application's deployments across all scopes — which release landed on which scope, the rollout status, and age; a deployment group (one release to several scopes) is shown as one row. Use to see deploy history or find an active rollout.",
+    description: 'List ONE application\'s deployments across all its scopes, rendered as a PANEL — which release landed on which scope, the rollout status, and age (a deployment group landing one release on several scopes shows as one row). Use it for "deploy history", "what was deployed when", "find the active rollout". Does NOT deploy or change traffic (use application_deployment_create / application_deployment_update) and shows no logs/metrics. To find the newest deployment ACROSS apps, gather headlessly with entity_list (entity:"deployment") and compute it. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "deployments",
     errorKey: "deploymentList.errorLabel",

package/dist/tools/entity-get.js

@@ -21,7 +21,7 @@ const ENTITIES = [
 export const entityGetTool = defineTool({
     name: TOOL.entityGet,
     title: "Read an entity (data)",
-    description: 'Read-only, DATA-only fetch of ONE core entity by id — returns structuredContent and renders NO panel. Pass `entity` and `id` (e.g. entity:"application" id:123). Use this to drill into a specific entity while navigating with entity_list; use the rendered reads (application_get/…) when the USER wants to SEE it. Entities: organization, account, namespace, application, scope, build, release, deployment. (parameters/services/links/approvals have their own tools.)',
+    description: 'Read ONE entity by id as DATA — returns structuredContent and renders NO panel (no widget). Use it to (a) drill into a specific entity while navigating headlessly with entity_list, or (b) POLL a changing status WITHOUT spamming panels — loop entity_get entity:"build" id:<id> (or "deployment") until the status is final, instead of re-calling application_get each time. Pass `entity` + `id` (e.g. entity:"application" id:123). Entities: organization, account, namespace, application, scope, build, release, deployment. Use the rendered reads (application_get/…) when the USER wants to SEE it; parameters/services/links/approvals have their own tools.',
     annotations: { readOnlyHint: true },
     // No widget on purpose: data-only. See CLAUDE.md (the data-only read pattern).
     errorKey: "entityGet.errorLabel",

package/dist/tools/entity-list.js

@@ -58,7 +58,7 @@ async function listByNrn(context, entity, nrn) {
 export const entityListTool = defineTool({
     name: TOOL.entityList,
     title: "List entities (data)",
-    description: 'Read-only, DATA-only list of an entity scoped to its parent — returns structuredContent and renders NO panel, so you can navigate the org and gather context without putting a widget on the user\'s screen. REST tree: organization → account → namespace → application → {scope, build, release}; scope → deployment — pass `entity` plus the `parent_type`+`parent_id` it lives under (e.g. entity:"build" parent_type:"application" parent_id:123; listing `account` needs no parent). NRN-scoped resources (parameter, service, link, approval) live under an application or scope — pass parent_type:"application"|"scope" + parent_id (the NRN is resolved for you), or `nrn` directly. Use this to reason for yourself; use the rendered reads (application_list/application_build_list/…) when the USER wants to SEE the data. For one entity by id use entity_get.',
+    description: 'List releases, builds, deployments, scopes, applications, namespaces, parameters, services, links or approvals as DATA — returns structuredContent and renders NO panel. THIS is the tool for AGGREGATING or COMPARING across many apps/scopes: "the latest release across all my apps", "which app has a failing build", "every scope on the newest build" — list each app\'s releases/builds with this (no panel per app), then compute the answer yourself. Prefer it over application_release_list/application_build_list/application_deployment_list whenever you are gathering to reason or to answer an aggregate — those panel reads are ONLY for showing ONE app\'s list to the user. Scoped to a parent: REST tree organization → account → namespace → application → {scope, build, release}; scope → deployment — pass `entity` plus the `parent_type`+`parent_id` it lives under (e.g. entity:"release" parent_type:"application" parent_id:123; listing `account` needs no parent). NRN-scoped resources (parameter, service, link, approval) live under an application or scope — pass parent_type:"application"|"scope" + parent_id (the NRN is resolved for you), or `nrn` directly. For one entity by id use entity_get.',
     annotations: { readOnlyHint: true },
     // No widget on purpose: data-only navigation. See CLAUDE.md (the data-only read pattern).
     errorKey: "entityList.errorLabel",

package/dist/tools/find-apps.js

@@ -8,13 +8,16 @@ import { TOOL } from "../tool-names.js";
 export const findAppsTool = defineTool({
     name: TOOL.applicationList,
     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.",
+    description: 'Search applications across the organization by partial name and/or namespace, rendered as a list PANEL grouped by namespace. Fast (parallel + cached). When the user asks for the apps IN a namespace ("my apps in pablov", "list the payments-ns apps"), ALWAYS pass `namespace` so the search is filtered at the source — never list the whole org and then filter the result yourself (the org can have hundreds of apps; post-filtering in code is wrong). Namespace matching is lenient (case- and space-insensitive: "pablov" matches "Pablo V"). Use `query` for a partial app name. Use this when the repo isn\'t linked or the user names an app/namespace you don\'t know.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "find-apps",
     errorKey: "findApps.errorLabel",
     inputSchema: {
         query: z.string().optional().describe("Partial app name (case-insensitive). Omit to list everything."),
-        namespace: z.string().optional().describe("Limit to namespaces whose name contains this"),
+        namespace: z
+            .string()
+            .optional()
+            .describe('Limit to a namespace by name — pass this whenever the user scopes to a namespace. Matched leniently (case- and space-insensitive): "pablov" or "pablo v" both match "Pablo V".'),
         limit: z.number().optional(),
     },
     async handler(args, context) {

package/dist/tools/logs.js

@@ -8,7 +8,7 @@ import { appArg, chooseScope, requireApp } from "./shared.js";
 export const logsTool = defineTool({
     name: TOOL.applicationLogList,
     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.",
+    description: 'Read ONE application\'s recent logs (per scope), rendered as a logs PANEL — the latest lines, newest last. Use it for "why is it failing?", "show me the logs", "what errored". Logs are per-scope: omit `scope` to use the only one (or be asked which); page older lines with `page_token`; narrow the window with `start_time`/`end_time` (ISO-8601) or cap with `lines`. Does NOT return metrics or deploy status — use application_metric_list or application_get. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "logs",
     errorKey: "logs.errorLabel",

package/dist/tools/metrics.js

@@ -8,7 +8,7 @@ import { appArg, chooseScope, requireApp } from "./shared.js";
 export const metricsTool = defineTool({
     name: TOOL.applicationMetricList,
     title: "Performance metrics",
-    description: "The golden signals of a scope — throughput (rpm), response time, error rate, CPU and memory — with sparkline trends over a time window. Use to answer 'how is it performing?' or to watch health during a rollout.",
+    description: 'The golden signals of ONE scope — throughput (rpm), response time, error rate, CPU, memory — with sparkline trends, rendered as a metrics PANEL. Use it for "how is it performing?", "is it healthy?", or to watch a scope during a rollout. Pick the `window` (1h/3h/24h/7d, default 3h); omit `scope` to use the only one. Does NOT return logs or deploy state — use application_log_list or application_get. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "metrics",
     errorKey: "metrics.errorLabel",

package/dist/tools/overview.js

@@ -14,7 +14,7 @@ const MAX_APPS = 30;
 export const overviewTool = defineTool({
     name: TOOL.organizationGet,
     title: "Organization overview",
-    description: "A cross-application health digest for the whole org: what's mid-rollout right now, and which scopes' last deployment failed or rolled back. Answers 'is anything broken?' / 'what's deploying?' without naming an app. Scans up to the first ~30 applications.",
+    description: 'A cross-application health digest for the WHOLE org, rendered as a panel: what\'s mid-rollout right now, and which scopes\' last deployment failed or rolled back. Use it for org-wide questions that name no app — "is anything broken?", "what\'s deploying?", "any failed rollouts?". Scans up to the first ~30 applications (truncation is reported, never silent). Does NOT show one app\'s full detail (use application_get), nor logs/metrics; to find the latest release or build ACROSS apps, gather headlessly with entity_list and compute it — don\'t call this. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "overview",
     errorKey: "overview.errorLabel",

package/dist/tools/params.js

@@ -24,7 +24,7 @@ function valueSummary(parameter, scopeNameById) {
 export const paramsTool = defineTool({
     name: TOOL.applicationParameterList,
     title: "Parameters",
-    description: "List an application's configuration parameters and every value they hold across scopes and dimensions (env vars / files; secret values are masked). Pass `scope` to resolve the single effective value per parameter for that scope. Use application_parameter_create to add or change them.",
+    description: 'List ONE application\'s configuration parameters and EVERY value each holds across scopes and dimensions (env vars / files; secret values are masked, never shown in plaintext), rendered as a PANEL. Use it for "what env vars does this app have", "show the config", "what\'s DATABASE_URL set to". Pass `scope` to have the PLATFORM resolve the single effective value per parameter for that scope (it collapses scope value › most-specific dimension match › app default — never reimplement that precedence yourself). Does NOT change anything — use application_parameter_create to add/update, application_parameter_delete to remove. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "params.errorLabel",

package/dist/tools/playbook.js

@@ -14,7 +14,7 @@ const playbookBody = (markdown) => markdown.replace(/^---\n[\s\S]*?\n---\n?/, ""
 export const playbookGetTool = defineTool({
     name: TOOL.playbookGet,
     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.",
+    description: 'Read a nullplatform operating PLAYBOOK — model-facing methodology for RISKY or MULTI-STEP work: deploying-safely (canary steps + metric gates for a production rollout), incident-response (triage when something is broken), configuring-safely (changing parameters or secrets carefully). Renders NO panel — prose for YOU to consult, NOT a step you must run before every action. Reach for it only when you genuinely want the grounded procedure for a non-trivial operation; for a direct, simple command ("deploy", "set X", "roll back") just use that action\'s tool — do not detour here first. Call with no `name` to list the catalog (also in the server instructions).',
     annotations: { readOnlyHint: true },
     // No widget: a playbook is model-facing methodology prose, not an interactive entity — it
     // renders as text (the markdown below) for the model to read and act on. See CLAUDE.md.

package/dist/tools/releases.js

@@ -12,7 +12,7 @@ import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
 export const releasesTool = defineTool({
     name: TOOL.applicationReleaseList,
     title: "Releases",
-    description: "List an application's releases — semver, status (active/deprecated/unstable/failed), the build each pins, and age. Use to pick a release to deploy or promote, or to see what's shippable.",
+    description: "List ONE application's releases as a PANEL for the user — semver, status (active/deprecated/unstable/failed), the build each pins, and age. Use to pick a release to deploy or promote, or to see what's shippable. Do NOT call this once per app to compare across apps (it renders a panel each time): for an AGGREGATE like 'the latest release across all my apps' use entity_list (entity:\"release\"), gather headlessly, and compute the answer.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "releases",
     errorKey: "releaseList.errorLabel",

package/dist/tools/services.js

@@ -13,7 +13,7 @@ import { appArg, requireApp } from "./shared.js";
 export const servicesTool = defineTool({
     name: TOOL.applicationServiceList,
     title: "Services & dependencies",
-    description: "List the dependency services (databases, queues, caches…) attached to an application, plus the catalog of dependency types available to provision. Read-only: provisioning a new dependency is a guided flow, so this links you into the dashboard to create one.",
+    description: 'List the dependency services (databases, queues, caches…) attached to ONE application, plus the catalog of dependency types available to provision, rendered as a PANEL. Use it for "what databases/queues does this app use", "show its dependencies", "what can I provision". To provision a new dependency use application_service_create; to connect one to a scope use application_link_create. Read-only — it does not provision or link anything itself.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "services",
     errorKey: "services.errorLabel",

package/dist/tools/set-params.js

@@ -8,7 +8,7 @@ import { appArg, pickScope, requireApp } from "./shared.js";
 export const setParamsTool = defineTool({
     name: TOOL.applicationParameterCreate,
     title: "Set parameters",
-    description: "Create or update application configuration parameters (environment variables or files; mark secrets). Target a value at the application (default — every scope), by dimension (applies to any matching scope), or pinned to one scope. Values apply on the NEXT deploy.",
+    description: 'Create or UPDATE application configuration parameters — environment variables or files, secrets supported (stored masked, updatable; NOT write-once). A parameter is a value-SET: one definition holds many values keyed by target. Target a value at the APPLICATION (default — every scope), BY DIMENSION (e.g. environment=production — applies to any matching scope), or pinned to ONE scope (dimensions and a scope are mutually exclusive). Use it for "set DATABASE_URL", "add an env var", "change a secret", "set a prod-only value". Values apply on the NEXT deploy. Renders the parameters panel after applying. Convergent: reuses the existing definition and updates in place rather than duplicating. View current values with application_parameter_list; remove with application_parameter_delete.',
     annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "setParams.errorLabel",

package/dist/tools/shared.js

@@ -75,6 +75,49 @@ export async function requireApp(context, args) {
     }
     return { out: fail(notFoundMessage(resolution), { not_found: true }) };
 }
+/**
+ * The ONE pre-selection rule for every create/fill form selector (namespace, template, service spec,
+ * scope type…). It turns the model's soft inference — an explicit id, or the free-text stack/type it
+ * reasoned out of the conversation — into a concrete option, or `undefined` when it's a genuine
+ * unhinted choice. It NEVER returns an arbitrary first entry: a wrong pre-selection is worse than an
+ * honest blank. Division of labour (see CLAUDE.md): the MODEL infers (it holds the context) and passes
+ * the hint as a tool arg; the TOOL resolves it here; the WIDGET only mirrors the result.
+ *
+ * Order, most to least certain: explicit id → exact name → every query token present in the option's
+ * haystack (fuzzy "sql database") → an option name contained in the hint ("Golang Hexagonal - API" ⊃
+ * the "golang-hexagonal" template) → with `pinOnly`, the sole candidate. `haystack` widens the
+ * searchable text per field (name + tags, name + category…); it defaults to the option's name.
+ */
+export function resolveChoice(options, hint, settings = {}) {
+    if (hint.id != null) {
+        const byId = options.find((option) => option.id === hint.id);
+        if (byId)
+            return byId;
+    }
+    const query = hint.text?.trim().toLowerCase();
+    if (query) {
+        const haystackOf = settings.haystack ?? ((option) => option.name);
+        const exact = options.filter((option) => option.name.trim().toLowerCase() === query);
+        if (exact.length === 1)
+            return exact[0];
+        const tokens = query.split(/\s+/).filter(Boolean);
+        const tokenMatch = options.filter((option) => {
+            const haystack = haystackOf(option).toLowerCase();
+            return tokens.every((token) => haystack.includes(token));
+        });
+        if (tokenMatch.length === 1)
+            return tokenMatch[0];
+        const contained = options.filter((option) => {
+            const name = option.name.trim().toLowerCase();
+            return name.length >= 2 && query.includes(name);
+        });
+        if (contained.length === 1)
+            return contained[0];
+    }
+    if (settings.pinOnly && options.length === 1)
+        return options[0];
+    return undefined;
+}
 /**
  * Match scopes by name OR by dimensions: "dev" (name substring), "production"
  * (dimension value substring), "environment=production" (exact key=value).

package/dist/tools/status.js

@@ -41,7 +41,7 @@ export async function buildAppStatus(context, app) {
 export const statusTool = defineTool({
     name: TOOL.applicationGet,
     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.",
+    description: 'THE place to start for ONE application\'s live status — renders a status PANEL: each scope with what\'s live on it (release + traffic), the latest build, the latest release, and the single obvious next action. Use it for "what\'s the status of my app", "what\'s deployed where", "is it healthy" — a STATUS question. For a DIRECT action ("deploy", "send traffic", "show logs/metrics") reach for that action\'s own tool instead of starting here; only read status first when you genuinely need to see state before acting. Call with NO arguments inside a git repo to use the linked app; pass `app` (name or "#id") for a different one; pass `deployment:<id>` to watch one rollout\'s live detail. Does NOT return logs, metrics, parameters, or a build\'s assets — use application_log_list / application_metric_list / application_parameter_list / application_build_list for those. Do NOT loop this to WAIT for a build or deployment to finish: it repaints the whole panel every call (stacking duplicate panels) — poll headlessly with entity_get (entity:"build" or "deployment", id:<id>) instead, and show this panel once at the end.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "np-panel",
     errorKey: "status.errorLabel",

package/dist/tools/traffic.js

@@ -9,7 +9,7 @@ import { appArg, delays, requireApp, sleep } from "./shared.js";
 export const trafficTool = defineTool({
     name: TOOL.applicationDeploymentUpdate,
     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.',
+    description: 'Drive an IN-FLIGHT rollout — the step AFTER application_deployment_create. Call it DIRECTLY with `percent` (snaps to 0,1,5,10,25,50,75,90,95,99,100) to move traffic, action:"finalize" to retire the old version, or action:"rollback" to return traffic to the previous version (the safety hatch). You do NOT need to read status or look up a deployment id first — it finds the app\'s single active rollout automatically (pass `deployment_id` only when several are in flight at once). Use it for "send 25% traffic", "promote to 100%", "finalize", "roll back". Renders the live rollout panel. Does NOT create a deployment — use application_deployment_create first; this only steers one that already exists.',
     annotations: { destructiveHint: true, openWorldHint: true },
     widget: "np-panel",
     errorKey: "traffic.errorLabel",