@nullplatform/mcp 0.1.12 → 0.1.14

package/dist/i18n.js

@@ -354,6 +354,8 @@ const english = {
     "createApp.errorLabel": "Couldn't create the application",
     // — playbook_get tool —
     "playbook.errorLabel": "Couldn't load the playbook",
+    "entityList.errorLabel": "Couldn't list that",
+    "entityGet.errorLabel": "Couldn't read that",
     // — application_scope_create tool —
     "createScope.whichType": "Which scope type for **{name}**?",
     "createScope.typeHint": "name a scope type for **{name}** to create it.",
@@ -720,6 +722,8 @@ const spanish = {
     "createApp.errorLabel": "No pude crear la aplicación",
     // — playbook_get tool —
     "playbook.errorLabel": "No pude cargar el playbook",
+    "entityList.errorLabel": "No pude listar eso",
+    "entityGet.errorLabel": "No pude leer eso",
     "createScope.whichType": "¿Qué tipo de scope para **{name}**?",
     "createScope.typeHint": "nombrá un tipo de scope para **{name}** para crearlo.",
     "createScope.noTypes": 'No hay tipos de scope disponibles — pasá type explícito (p. ej. type:"web_pool").',
@@ -1101,6 +1105,8 @@ const portuguese = {
     "createApp.errorLabel": "Não foi possível criar a aplicação",
     // — playbook_get tool —
     "playbook.errorLabel": "Não foi possível carregar o playbook",
+    "entityList.errorLabel": "Não foi possível listar isso",
+    "entityGet.errorLabel": "Não foi possível ler isso",
     // — application_scope_create tool —
     "createScope.whichType": "Qual tipo de scope para **{name}**?",
     "createScope.typeHint": "informe um tipo de scope para **{name}** para criá-lo.",

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/np/journey.js

@@ -1,3 +1,18 @@
+/**
+ * Generic entity navigation. The platform's REST surface is uniform — every entity in the core tree
+ * lists as `GET /<entity>?<parent>_id=<id>` (returning `{results}`) and reads as `GET /<entity>/<id>`.
+ * One pair of accessors therefore resolves the whole hierarchy (organization → account → namespace →
+ * application → scope → deployment, plus build/release under application) without a per-entity function.
+ * (NRN-scoped resources — parameters/services/links/approvals — use a different addressing scheme and
+ * keep their own typed functions.) This is the typed seam the generic read tools call.
+ */
+export async function listEntity(np, entity, query) {
+    const page = await np.get(`/${entity}`, query);
+    return Array.isArray(page) ? page : (page.results ?? []);
+}
+export async function getEntity(np, entity, id) {
+    return np.get(`/${entity}/${id}`);
+}
 /** Traffic percentages the platform accepts (same marks the dashboard slider snaps to). */
 export const TRAFFIC_MARKS = [0, 1, 5, 10, 25, 50, 75, 90, 95, 99, 100];
 export const snapTraffic = (percent) => TRAFFIC_MARKS.reduce((closest, mark) => (Math.abs(mark - percent) < Math.abs(closest - percent) ? mark : closest), 0);

package/dist/surfaces/developer.js

@@ -14,7 +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.
+
+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/tool-names.js

@@ -30,5 +30,7 @@ export const TOOL = {
     applicationParameterDelete: "application_parameter_delete",
     applicationApprovalList: "application_approval_list",
     organizationGet: "organization_get",
+    entityList: "entity_list",
+    entityGet: "entity_get",
     playbookGet: "playbook_get",
 };

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

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { getEntity } from "../np/journey.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+/**
+ * Generic read-only, DATA-only GET — NO widget, so nothing renders. Reads ONE core entity by id
+ * (`GET /<entity>/<id>`), the drill-in companion to `entity_list`. The model uses it to inspect a
+ * specific node while navigating the tree, without putting a panel on the user's screen. The rendered
+ * reads (application_get/…) stay for when the user wants to SEE it. See CLAUDE.md (data-only read).
+ */
+const ENTITIES = [
+    "organization",
+    "account",
+    "namespace",
+    "application",
+    "scope",
+    "build",
+    "release",
+    "deployment",
+];
+export const entityGetTool = defineTool({
+    name: TOOL.entityGet,
+    title: "Read an entity (data)",
+    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",
+    inputSchema: {
+        entity: z.enum(ENTITIES).describe("Which entity type to read."),
+        id: z.number().describe("The entity's id."),
+    },
+    async handler(args, context) {
+        const result = await getEntity(context.np, args.entity, args.id);
+        return reply(`${args.entity} #${args.id}.`, { entity: args.entity, result });
+    },
+});

package/dist/tools/entity-list.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { getApplication, getScope, listApprovals, listEntity, listLinks, listParameters, listServices, } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+/**
+ * Generic read-only, DATA-only LIST — NO widget, so nothing renders. One tool navigates the whole
+ * entity tree: pick an `entity` and the `parent_type`/`parent_id` it lives under. Two addressing
+ * schemes hide behind one uniform interface — the REST tree lists as `GET /<entity>?<parent>_id=<id>`,
+ * and the NRN-scoped resources (parameter/service/link/approval) list by the parent's NRN (resolved
+ * from `parent_id`, or passed directly as `nrn`). Each dispatches to its existing typed function in
+ * journey.ts (tools never touch NpClient directly). The model uses it to traverse the org and gather
+ * context without a panel; pair it with `entity_get` to drill into one. This is the data-only read
+ * pattern (see CLAUDE.md).
+ */
+/** REST-addressed collections — listed by `<parent_type>_id`. */
+const REST_ENTITIES = [
+    "account",
+    "namespace",
+    "application",
+    "scope",
+    "build",
+    "release",
+    "deployment",
+];
+/** NRN-addressed collections — listed by the parent's NRN (resolved from parent_id, or given as nrn). */
+const NRN_ENTITIES = ["parameter", "service", "link", "approval"];
+const ENTITIES = [...REST_ENTITIES, ...NRN_ENTITIES];
+/** The parents a collection can hang under — its id (REST) or its NRN (nrn-scoped) scopes the list. */
+const PARENTS = ["organization", "account", "namespace", "application", "scope"];
+const NRN_ENTITY_SET = new Set(NRN_ENTITIES);
+/** Resolve the NRN that scopes an nrn-addressed collection: the model's `nrn`, or its parent's. */
+async function resolveNrn(context, args) {
+    if (args.nrn)
+        return args.nrn;
+    if (args.parent_id === undefined)
+        return undefined;
+    if (args.parent_type === "application")
+        return (await getApplication(context.np, args.parent_id)).nrn;
+    if (args.parent_type === "scope")
+        return (await getScope(context.np, args.parent_id)).nrn;
+    return undefined;
+}
+/** List an nrn-scoped resource via its existing typed function (a different addressing scheme to REST). */
+async function listByNrn(context, entity, nrn) {
+    switch (entity) {
+        case "parameter":
+            return (await listParameters(context.np, nrn)) ?? [];
+        case "service":
+            return listServices(context.bff, nrn);
+        case "link":
+            return listLinks(context.np, nrn);
+        case "approval":
+            return listApprovals(context.bff, nrn);
+        default:
+            return [];
+    }
+}
+export const entityListTool = defineTool({
+    name: TOOL.entityList,
+    title: "List entities (data)",
+    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",
+    inputSchema: {
+        entity: z
+            .enum(ENTITIES)
+            .describe("Collection to list. REST tree: account, namespace, application, scope, build, release, deployment. NRN-scoped: parameter, service, link, approval."),
+        parent_type: z
+            .enum(PARENTS)
+            .optional()
+            .describe("The parent the collection lives under. REST: its `<parent_type>_id` scopes the list (required except `account`). NRN-scoped: application|scope, used to resolve the NRN."),
+        parent_id: z.number().optional().describe("The parent entity's id."),
+        nrn: z
+            .string()
+            .optional()
+            .describe("For nrn-scoped entities (parameter/service/link/approval): the scoping NRN directly, if you have it; otherwise pass parent_type + parent_id and it's resolved for you."),
+        limit: z.number().optional().describe("Max rows (default 100) — REST collections only."),
+    },
+    async handler(args, context) {
+        if (NRN_ENTITY_SET.has(args.entity)) {
+            const nrn = await resolveNrn(context, args);
+            if (!nrn) {
+                return fail(`Listing ${args.entity} needs an NRN — pass nrn, or parent_type:"application"|"scope" + parent_id.`);
+            }
+            const nrnResults = await listByNrn(context, args.entity, nrn);
+            return reply(`${nrnResults.length} ${args.entity}(s).`, { entity: args.entity, results: nrnResults });
+        }
+        const query = { limit: args.limit ?? 100 };
+        if (args.parent_type && args.parent_id !== undefined) {
+            query[`${args.parent_type}_id`] = args.parent_id;
+        }
+        else if (args.entity === "account") {
+            query.organization_id = (await context.org.getSkeleton()).orgId;
+        }
+        const results = await listEntity(context.np, args.entity, query);
+        return reply(`${results.length} ${args.entity}(s).`, { entity: args.entity, results });
+    },
+});

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/index.js

@@ -10,6 +10,8 @@ import { deleteParamTool } from "./delete-param.js";
 import { deleteServiceTool } from "./delete-service.js";
 import { deployTool } from "./deploy.js";
 import { deploymentsTool } from "./deployments.js";
+import { entityGetTool } from "./entity-get.js";
+import { entityListTool } from "./entity-list.js";
 import { findAppsTool } from "./find-apps.js";
 import { logsTool } from "./logs.js";
 import { metricsTool } from "./metrics.js";
@@ -45,6 +47,8 @@ export const tools = [
     createAppTool,
     createScopeTool,
     approvalsTool,
+    entityListTool,
+    entityGetTool,
     servicesTool,
     createServiceTool,
     updateServiceTool,

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",