@nullplatform/mcp 0.1.13 → 0.1.15

package/dist/tools/create-scope.js

@@ -6,13 +6,41 @@ import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, dimsLabel, requireApp } from "./shared.js";
 import { buildAppStatus } from "./status.js";
+/**
+ * Resolve the scope `type` (+ provider) to provision with. An explicit `type` wins; otherwise, for
+ * an app with an NRN, auto-pick the org's single scope type. Mirrors requireApp's shape: returns
+ * { type, provider } (type left undefined when there are none — the handler fails on that), or an
+ * `out` reply — the which-type form (riding the overview) when the org offers several.
+ */
+async function resolveScopeType(context, app, scopeName, argType, argProvider) {
+    if (argType || !app.nrn)
+        return { type: argType, provider: argProvider };
+    const scopeTypes = await listScopeTypes(context.np, app.nrn);
+    const onlyType = scopeTypes.length === 1 ? scopeTypes[0] : undefined;
+    if (onlyType) {
+        return { type: onlyType.type ?? onlyType.name, provider: argProvider ?? onlyType.provider ?? undefined };
+    }
+    if (scopeTypes.length > 1) {
+        // The create-scope form picks a type from scope_types; the overview rides along so a fresh app
+        // (no scopes yet) renders that form instead of an empty panel.
+        const { structured } = await buildAppStatus(context, app);
+        return {
+            out: reply(`${translate("createScope.whichType", { name: scopeName })}\n\n${table([translate("header.type"), translate("header.name"), translate("header.provider")], scopeTypes.map((scopeType) => [
+                scopeType.type ?? "",
+                scopeType.name ?? "",
+                scopeType.provider ?? "",
+            ]))}${next(translate("createScope.typeHint", { name: scopeName }))}`, { ...structured, scope_types: scopeTypes }),
+        };
+    }
+    return { type: argType, provider: argProvider };
+}
 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",
+    widget: "status",
     errorKey: "createScope.errorLabel",
     inputSchema: {
         app: appArg,
@@ -42,26 +70,10 @@ export const createScopeTool = defineTool({
                 next(translate("createScope.provisioningHint", { name: existing.name })) +
                 linkLine(translate("md.dashboard"), dashboardLink(orgSlug, existing.nrn)), { ...status.structured, scope: existing, reused: true });
         }
-        let type = args.type;
-        let provider = args.provider;
-        if (!type && app.nrn) {
-            const scopeTypes = await listScopeTypes(context.np, app.nrn);
-            const onlyType = scopeTypes.length === 1 ? scopeTypes[0] : undefined;
-            if (onlyType) {
-                type = onlyType.type ?? onlyType.name;
-                provider = provider ?? onlyType.provider ?? undefined;
-            }
-            else if (scopeTypes.length > 1) {
-                // np-panel's create-scope form picks a type from scope_types; the overview rides along
-                // so a fresh app (no scopes yet) renders that form instead of an empty panel.
-                const { structured } = await buildAppStatus(context, app);
-                return reply(`${translate("createScope.whichType", { name: args.name })}\n\n${table([translate("header.type"), translate("header.name"), translate("header.provider")], scopeTypes.map((scopeType) => [
-                    scopeType.type ?? "",
-                    scopeType.name ?? "",
-                    scopeType.provider ?? "",
-                ]))}${next(translate("createScope.typeHint", { name: args.name }))}`, { ...structured, scope_types: scopeTypes });
-            }
-        }
+        const typeResult = await resolveScopeType(context, app, args.name, args.type, args.provider);
+        if ("out" in typeResult)
+            return typeResult.out;
+        const { type, provider } = typeResult;
         if (!type)
             return fail(translate("createScope.noTypes"));
         // Orgs with runtime dimensions usually require them — borrow the shape from a sibling scope.
@@ -78,7 +90,7 @@ export const createScopeTool = defineTool({
             provider,
             dimensions,
         });
-        // Hand off into np-panel: the overview now includes the provisioning scope, so the panel
+        // Hand off into the status panel: the overview now includes the provisioning scope, so the panel
         // shows it alongside a Deploy button — the literal next move (read-after-write).
         const [orgSlug, status] = await Promise.all([
             context.org.organizationSlug(),

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, "-")
@@ -19,6 +19,38 @@ function matchSpecs(specs, query) {
     });
 }
 const specCategory = (spec) => [spec.category, spec.subCategory].filter(Boolean).join(" › ");
+/**
+ * Pick which catalog dependency to provision from the `specification_id` / `type` hints. Mirrors
+ * requireApp's shape: returns the matched spec, or an `out` reply — a `fail` when the app's catalog
+ * is empty, or the pick-spec panel when the hint is missing/ambiguous (resolved via the shared
+ * resolveChoice on name + category + sub-category, never an arbitrary first entry).
+ */
+async function resolveServiceSpec(context, app, hints, dashboard) {
+    const specs = await listDependencySpecs(context.np, app.nrn);
+    if (specs.length === 0) {
+        return {
+            out: fail(translate("createService.noSpecs", { app: app.name }) +
+                linkLine(translate("md.dashboard"), dashboard)),
+        };
+    }
+    const spec = resolveChoice(specs, { id: hints.specification_id, text: hints.type }, {
+        haystack: (candidate) => `${candidate.name} ${candidate.category ?? ""} ${candidate.subCategory ?? ""}`,
+    });
+    if (spec)
+        return { spec };
+    // None / ambiguous → return the catalog (or the narrowed matches) to pick from.
+    const typed = hints.type ? matchSpecs(specs, hints.type) : [];
+    const list = typed.length > 1 ? typed : specs;
+    const heading = translate(typed.length > 1 ? "createService.matchAmbiguous" : "createService.pickSpec", {
+        app: app.name,
+        query: hints.type ?? "",
+        count: specs.length,
+    });
+    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 {
+        out: reply(md, { mode: "pick-spec", app: `#${app.id}`, app_name: app.name, specs: list, dashboard }),
+    };
+}
 /**
  * Provision a dependency service (the service record + its create action). Linking it to an app or
  * scope is a SEPARATE operation (`application_link_create`) — two distinct platform entities with
@@ -27,7 +59,7 @@ const specCategory = (spec) => [spec.category, spec.subCategory].filter(Boolean)
 export const createServiceTool = defineTool({
     name: TOOL.applicationServiceCreate,
     title: "Provision service",
-    description: 'Provision a dependency service (SQL database, queue, cache, …) for an application. Pass `type` to choose the dependency (e.g. "postgres", "redis"). Provisioning creates real cloud resources (cost-bearing) and runs asynchronously, so call WITHOUT `provision:true` first to open the form; the user confirms by submitting it. Once it is active, LINK it to a scope with application_link_create so its connection details flow in as parameters.',
+    description: 'Provision a dependency service (SQL database, queue, cache, …) for an application. ALWAYS pass a SEMANTIC `type` from what the user asked for (e.g. "postgres", "redis", "queue", "cache") — you do NOT need the exact catalog spec name/id; the tool matches your word to the real catalog and pre-selects it, so the form opens with the dependency already chosen. Do NOT open the form with no `type` and then list the catalog or recommend one in text — pre-select it. Provisioning creates real cloud resources (cost-bearing) and runs asynchronously, so call WITHOUT `provision:true` first to open the form; the user confirms by submitting it. Once it is active, LINK it to a scope with application_link_create so its connection details flow in as parameters.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "service-create",
     errorKey: "createService.errorLabel",
@@ -60,29 +92,11 @@ export const createServiceTool = defineTool({
             return fail(translate("resolve.noNrn", { app: app.name }));
         const orgSlug = await context.org.organizationSlug();
         const dashboard = dashboardLink(orgSlug, app.nrn);
-        // The provisionable catalog (core API — carries the action specs the write path needs).
-        const specs = await listDependencySpecs(context.np, app.nrn);
-        if (specs.length === 0) {
-            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", {
-                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"))}`;
-            return reply(md, { mode: "pick-spec", app: `#${app.id}`, app_name: app.name, specs: list, dashboard });
-        }
-        const spec = matches[0];
+        // The provisionable catalog → pre-select the spec (or surface the picker / empty-catalog fail).
+        const resolvedSpec = await resolveServiceSpec(context, { id: app.id, name: app.name, nrn: app.nrn }, { specification_id: args.specification_id, type: args.type }, dashboard);
+        if ("out" in resolvedSpec)
+            return resolvedSpec.out;
+        const spec = resolvedSpec.spec;
         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

@@ -79,12 +79,54 @@ async function resolveRelease(context, applicationId, args) {
         return { release: releases[0], note: "" };
     return { out: fail(translate("deploy.nothing") + next(translate("deploy.nothingHint"))) };
 }
+/**
+ * Resolve which scope to deploy to. Mirrors requireApp's shape: returns the picked scope, or an
+ * `out` reply — pickScope's own ask/fail, except a brand-new app with NO scopes gets a "create a
+ * scope first" guide listing the available scope types (the literal next move).
+ */
+async function resolveDeployScope(context, app, scopeHint) {
+    const scopes = await listScopes(context.np, app.id);
+    const picked = pickScope(scopes, scopeHint);
+    if ("scope" in picked)
+        return { scope: picked.scope };
+    if (scopes.length === 0 && app.nrn) {
+        const scopeTypes = await listScopeTypes(context.np, app.nrn);
+        if (scopeTypes.length) {
+            const firstType = scopeTypes[0]?.type ?? scopeTypes[0]?.name ?? "";
+            const markdown = translate("deploy.noScopeTypes", {
+                types: scopeTypes.map((scopeType) => `**${scopeType.name}**`).join(", "),
+            }) + next(translate("deploy.createScopeHint", { type: firstType }));
+            return { out: fail(markdown, { scope_types: scopeTypes }) };
+        }
+    }
+    return { out: picked.out };
+}
+/**
+ * Resolve which asset to ship. An explicit `asset` wins; otherwise auto-pick by the scope's type.
+ * Mirrors requireApp's shape: returns the asset name (undefined when the build has none to name),
+ * or an `out` reply — the pick-asset panel when a multi-asset build can't be disambiguated.
+ */
+async function resolveDeployAsset(context, release, scope, assetHint) {
+    if (assetHint)
+        return { assetName: assetHint };
+    const buildId = release.build_id ?? (await getRelease(context.np, release.id).catch(() => release)).build_id;
+    if (!buildId)
+        return { assetName: undefined };
+    const assets = await listAssets(context.np, buildId);
+    const choice = pickAsset(assets, scope.type);
+    if ("ambiguous" in choice) {
+        return {
+            out: reply(`${translate("deploy.multiAsset", { build: buildId, scope: scope.name, type: scope.type ?? "?" })}\n\n${table([translate("header.asset"), translate("header.type"), translate("header.platform")], choice.ambiguous.map((asset) => [asset.name, asset.type, asset.platform ?? ""]))}${next(translate("deploy.assetHint", { name: choice.ambiguous[0]?.name ?? "" }))}`, { assets: choice.ambiguous }),
+        };
+    }
+    return { assetName: choice.name };
+}
 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",
+    widget: "status",
     errorKey: "deploy.errorLabel",
     // The platform reports a missing/incompatible asset choice as a cross-app mismatch.
     onError: (message) => /different applications/i.test(message) ? fail(translate("deploy.rejected", { message })) : undefined,
@@ -111,39 +153,19 @@ export const deployTool = defineTool({
         if ("out" in resolved)
             return resolved.out;
         const app = resolved.app;
-        const scopes = await listScopes(context.np, app.id);
-        const picked = pickScope(scopes, args.scope);
-        if ("out" in picked) {
-            if (scopes.length === 0 && app.nrn) {
-                const scopeTypes = await listScopeTypes(context.np, app.nrn);
-                if (scopeTypes.length) {
-                    const firstType = scopeTypes[0]?.type ?? scopeTypes[0]?.name ?? "";
-                    const markdown = translate("deploy.noScopeTypes", {
-                        types: scopeTypes.map((scopeType) => `**${scopeType.name}**`).join(", "),
-                    }) + next(translate("deploy.createScopeHint", { type: firstType }));
-                    return fail(markdown, { scope_types: scopeTypes });
-                }
-            }
-            return picked.out;
-        }
-        const scope = picked.scope;
+        const scopeResult = await resolveDeployScope(context, app, args.scope);
+        if ("out" in scopeResult)
+            return scopeResult.out;
+        const scope = scopeResult.scope;
         const shipping = await resolveRelease(context, app.id, args);
         if ("out" in shipping)
             return shipping.out;
         const { release, note } = shipping;
         // Multi-asset builds must name the asset to ship; the platform's error otherwise is misleading.
-        let assetName = args.asset;
-        if (!assetName) {
-            const buildId = release.build_id ?? (await getRelease(context.np, release.id).catch(() => release)).build_id;
-            if (buildId) {
-                const assets = await listAssets(context.np, buildId);
-                const choice = pickAsset(assets, scope.type);
-                if ("ambiguous" in choice) {
-                    return reply(`${translate("deploy.multiAsset", { build: buildId, scope: scope.name, type: scope.type ?? "?" })}\n\n${table([translate("header.asset"), translate("header.type"), translate("header.platform")], choice.ambiguous.map((asset) => [asset.name, asset.type, asset.platform ?? ""]))}${next(translate("deploy.assetHint", { name: choice.ambiguous[0]?.name ?? "" }))}`, { assets: choice.ambiguous });
-                }
-                assetName = choice.name;
-            }
-        }
+        const assetResult = await resolveDeployAsset(context, release, scope, args.asset);
+        if ("out" in assetResult)
+            return assetResult.out;
+        const assetName = assetResult.assetName;
         const orgSlug = await context.org.organizationSlug();
         // Convergent under retries: if this exact release is already rolling out on this scope
         // (a non-terminal deployment), return that rollout instead of starting a second one.

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getApplication, getScope, listApprovals, listEntity, listLinks, listParameters, listServices, } from "../np/journey.js";
+import { getApplication, getScope, listApprovals, listEntity, listLinks, listParameters, listServices, listTemplates, } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 /**
@@ -22,8 +22,9 @@ const REST_ENTITIES = [
     "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"];
+/** NRN-addressed collections — listed by the parent's NRN (resolved from parent_id, or given as nrn).
+ * `template` is scoped by a NAMESPACE's NRN (the scaffolding templates available to a new app there). */
+const NRN_ENTITIES = ["parameter", "service", "link", "approval", "template"];
 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"];
@@ -38,6 +39,11 @@ async function resolveNrn(context, args) {
         return (await getApplication(context.np, args.parent_id)).nrn;
     if (args.parent_type === "scope")
         return (await getScope(context.np, args.parent_id)).nrn;
+    if (args.parent_type === "namespace") {
+        // Templates hang off a namespace; resolve its NRN from the cached org skeleton (no extra fetch).
+        const skeleton = await context.org.getSkeleton();
+        return skeleton.namespaces.find((namespace) => namespace.id === args.parent_id)?.nrn;
+    }
     return undefined;
 }
 /** List an nrn-scoped resource via its existing typed function (a different addressing scheme to REST). */
@@ -51,6 +57,8 @@ async function listByNrn(context, entity, nrn) {
             return listLinks(context.np, nrn);
         case "approval":
             return listApprovals(context.bff, nrn);
+        case "template":
+            return listTemplates(context.np, nrn);
         default:
             return [];
     }
@@ -58,14 +66,14 @@ 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. `template` is scoped by a NAMESPACE: pass entity:"template" parent_type:"namespace" parent_id:<namespace_id> to list the scaffolding templates available for a new app there — do this to choose a template BEFORE opening the application_create form, so the form opens with it pre-selected (don\'t open the form blind to discover templates). 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."),
+            .describe("Collection to list. REST tree: account, namespace, application, scope, build, release, deployment. NRN-scoped: parameter, service, link, approval, template (template lists a namespace's scaffolding templates)."),
         parent_type: z
             .enum(PARENTS)
             .optional()
@@ -74,7 +82,7 @@ export const entityListTool = defineTool({
         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."),
+            .describe('For nrn-scoped entities (parameter/service/link/approval/template): the scoping NRN directly, if you have it; otherwise pass parent_type + parent_id (for template, parent_type:"namespace") and it\'s resolved for you.'),
         limit: z.number().optional().describe("Max rows (default 100) — REST collections only."),
     },
     async handler(args, context) {

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

@@ -1,14 +1,27 @@
 import { z } from "zod";
 import { plural, translate } from "../i18n.js";
+import { log } from "../log.js";
 import { dashboardLink, linkLine, next } from "../md.js";
 import { listScopes, readLogs } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, chooseScope, requireApp } from "./shared.js";
+const parseMs = (value) => {
+    if (!value)
+        return 0;
+    const ms = new Date(value).getTime();
+    return Number.isNaN(ms) ? 0 : ms;
+};
+/** A log entry's timestamp as epoch ms, from the platform's `date` field (ISO-8601). The single time
+ *  source for BOTH ordering and the staleness check. Absent → 0 (sorts as oldest, adds no recency).
+ *  We never parse a time out of the message TEXT: the platform already resolves each line's time into
+ *  `date`; an app that logs structured JSON keeps its own `"time"` inside the message, which is the
+ *  app's payload to show verbatim, not ours to reinterpret. */
+const logTimeMs = (entry) => parseMs(entry.date);
 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", "show <app> logs". Pass `app` (name OR "#id") and this resolves the application ITSELF — call it DIRECTLY; do NOT call application_list (to find the app) or application_get (to look it up) first, that just renders panels the user didn\'t ask for. "show <app> logs" is ONE call: this tool with app:"<app>". Logs are per-scope: omit `scope` to use the only one (or be asked which). With no window the SERVER auto-widens 1m → 5m → 30m and returns the first window that has logs, then falls back to the LATEST available lines (any age) so a quiet/stopped app still shows its last logs (e.g. the crash) — it prefers recent activity but is NEVER empty, so you NEVER need to re-call with a wider window (don\'t widen client-side — one call is enough). To pin a specific range pass `start_time`/`end_time` (ISO-8601) or a bigger `lines` (an explicit window skips the auto-widen). Page older lines with `page_token`. 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",
@@ -46,14 +59,84 @@ export const logsTool = defineTool({
             return picked.out;
         const scope = picked.scope;
         const maxLines = args.lines ?? 50;
-        const page = await readLogs(context.np, {
-            application_id: app.id,
-            scope_id: scope.id,
-            next_page_token: args.page_token,
-            start_time: args.start_time,
-            end_time: args.end_time,
-        });
-        const entries = (page.results ?? []).slice(-maxLines);
+        // No explicit window → progressively WIDEN the lookback (1m → 5m → 30m → 6h → 24h → 7d), stopping
+        // at the first window that actually has logs. So "show logs" starts with recent activity instead
+        // of an empty last-minute view on a quiet app. The wider steps past 30m are NOT cosmetic: an app
+        // that last logged, say, 45m ago has its newest lines just OUTSIDE the 30m "live" window. Without
+        // a 6h step the widen would skip straight to the unfiltered fallback — and an unfiltered read can
+        // return an OLDER partition than the most-recent lines (observed live: 06-19 lines surfaced while
+        // the app's real 06-22 lines sat in the 30m→unfiltered gap). An explicit `start_time` filters
+        // server-side, so the 6h step returns those 06-22 lines; staleness still flags them as not-live.
+        // The live tail re-runs this each poll. An explicit window / `page_token` skips the widening (the
+        // user/model asked for a specific range; widen further yourself to diagnose an older failure).
+        const explicit = Boolean(args.start_time || args.end_time || args.page_token);
+        const minute = 60_000;
+        const hour = 60 * minute;
+        const since = (ageMs) => ({ start_time: new Date(Date.now() - ageMs).toISOString() });
+        const windows = explicit
+            ? [{ start_time: args.start_time, end_time: args.end_time, next_page_token: args.page_token }]
+            : [
+                since(minute),
+                since(5 * minute),
+                since(30 * minute),
+                since(6 * hour),
+                since(24 * hour),
+                since(7 * 24 * hour),
+                // Last resort: latest-available, ANY age — an app silent for >7d still shows its last lines
+                // (e.g. an old crash), NEVER an empty panel. The explicit windows above are what surface the
+                // REAL most-recent lines; an unfiltered read can return an older partition, so it's only the
+                // truly-ancient safety net, never the primary path.
+                {},
+            ];
+        let page = await readLogs(context.np, { application_id: app.id, scope_id: scope.id, ...windows[0] });
+        let usedWindow = 0;
+        log.debug({ logsTool: { app: app.id, scope: scope.id, window: windows[0], count: page.results?.length ?? 0 } }, "logs: window 0");
+        for (let attempt = 1; attempt < windows.length && !(page.results ?? []).length; attempt++) {
+            page = await readLogs(context.np, { application_id: app.id, scope_id: scope.id, ...windows[attempt] });
+            usedWindow = attempt;
+            log.debug({
+                logsTool: {
+                    app: app.id,
+                    scope: scope.id,
+                    window: windows[attempt],
+                    count: page.results?.length ?? 0,
+                },
+            }, `logs: window ${attempt}`);
+        }
+        // Sort oldest → newest by timestamp, THEN take the newest `maxLines` (kept oldest-first for the
+        // "newest last" display). The platform returns lines newest-first, so a naive slice(-maxLines)
+        // took the OLDEST lines — which is why a multi-day log set surfaced days-old lines under "live".
+        const ordered = (page.results ?? []).slice().sort((left, right) => logTimeMs(left) - logTimeMs(right));
+        const entries = ordered.slice(-maxLines);
+        // Staleness: with no explicit window the auto-widen tries 1m → 5m → 30m before the latest-available
+        // fallback. So if the NEWEST line we got is older than that widest live window (30m), the app has had
+        // no recent activity and these are last-gasp lines (e.g. a crash days ago). Flag it so the panel/text
+        // says "no recent activity, last logs from <time>" instead of presenting old lines as a live tail.
+        // An explicit window/page_token means the user asked for that range — old lines there aren't "stale".
+        const newestMs = entries.reduce((max, entry) => Math.max(max, logTimeMs(entry)), 0);
+        const stale = !explicit && newestMs > 0 && Date.now() - newestMs > 30 * 60_000;
+        const newestTs = newestMs > 0 ? new Date(newestMs).toISOString() : null;
+        // The trace that pins down a logs-fetch complaint: which window won, how the staleness verdict was
+        // reached, and a sample of the RAW entries — the `date` field each line carries (the platform's
+        // timestamp) plus a short message head, so a missing/odd `date` is visible in the trace.
+        log.debug({
+            logsTool: {
+                app: app.id,
+                scope: scope.name,
+                explicit,
+                usedWindow,
+                rawCount: page.results?.length ?? 0,
+                entryCount: entries.length,
+                newestTs,
+                stale,
+                nowIso: new Date().toISOString(),
+                ageMin: newestMs > 0 ? Math.round((Date.now() - newestMs) / 60_000) : null,
+                sample: (page.results ?? []).slice(0, 6).map((entry) => ({
+                    date: entry.date ?? null,
+                    msgHead: entry.message.slice(0, 80),
+                })),
+            },
+        }, "logs: resolved entries + staleness");
         const scopeSuffix = ` · ${scope.name}`;
         // The full scope list rides along so the widget can offer a scope switcher.
         const scopeList = scopes.map((candidate) => ({ name: candidate.name, status: candidate.status }));
@@ -64,24 +147,38 @@ export const logsTool = defineTool({
         }
         const body = entries
             .map((entry) => {
-            const timestamp = entry.datetime ?? entry.timestamp;
-            const prefix = timestamp
-                ? `${new Date(timestamp).toISOString().slice(5, 19).replace("T", " ")}  `
-                : "";
-            return `${prefix}${(entry.message ?? "").trimEnd()}`;
+            // Timestamp column comes from the `date` field; guard a bad value (the API could return an
+            // unparseable date) so the prefix is just dropped rather than throwing.
+            const ms = parseMs(entry.date);
+            const prefix = ms ? `${new Date(ms).toISOString().slice(5, 19).replace("T", " ")}  ` : "";
+            return `${prefix}${entry.message.trimEnd()}`;
         })
             .join("\n");
-        const markdown = `${plural(entries.length, "logs.lastLines.one", "logs.lastLines.many", { app: app.name, scope: scopeSuffix })}\n\n\`\`\`\n${body}\n\`\`\``;
+        const heading = stale
+            ? plural(entries.length, "logs.staleLines.one", "logs.staleLines.many", {
+                app: app.name,
+                scope: scopeSuffix,
+                time: (newestTs ?? "").slice(0, 16).replace("T", " "),
+            })
+            : plural(entries.length, "logs.lastLines.one", "logs.lastLines.many", {
+                app: app.name,
+                scope: scopeSuffix,
+            });
+        const markdown = `${heading}\n\n\`\`\`\n${body}\n\`\`\``;
         return reply(markdown, {
             count: entries.length,
+            stale,
+            newest_ts: newestTs,
             next_page_token: page.next_page_token ?? null,
             app: `#${app.id}`,
             app_name: app.name,
             scope: scope.name,
             scopes: scopeList,
+            // Two columns: the timestamp from the `date` field (null → the widget shows no timestamp cell,
+            // just the message), and the message verbatim. No parsing time out of the text.
             lines: entries.map((entry) => ({
-                ts: entry.datetime ?? entry.timestamp ?? null,
-                message: entry.message ?? "",
+                ts: entry.date ?? null,
+                message: entry.message,
             })),
         });
     },

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