@nullplatform/mcp 0.1.6 → 0.1.8

package/dist/np/client.js

@@ -61,6 +61,9 @@ export class NpClient {
     patch(path, body, query) {
         return this.request("PATCH", path, query, body);
     }
+    del(path, query, body) {
+        return this.request("DELETE", path, query, body);
+    }
 }
 function safeJson(text) {
     try {

package/dist/np/journey.js

@@ -16,6 +16,17 @@ export function bumpSemver(semver) {
     const parts = /^(v?)(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
     return parts ? `${parts[1]}${parts[2]}.${parts[3]}.${Number(parts[4]) + 1}` : "0.0.1";
 }
+function mapBuild(build) {
+    return {
+        id: build.id,
+        status: build.status,
+        branch: build.branch,
+        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
+        commit_url: build.commit?.permalink,
+        description: build.description ?? undefined,
+        created_at: build.created_at,
+    };
+}
 export async function listBuilds(np, applicationId, options = {}) {
     const query = {
         application_id: applicationId,
@@ -29,13 +40,13 @@ export async function listBuilds(np, applicationId, options = {}) {
     if (options.offset)
         query.offset = options.offset;
     const page = await np.get("/build", query).catch(() => ({ results: [] }));
-    return (page.results ?? []).map((build) => ({
-        id: build.id,
-        status: build.status,
-        branch: build.branch,
-        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
-        created_at: build.created_at,
-    }));
+    return (page.results ?? []).map(mapBuild);
+}
+/** A single build by id (GET /build/{id}) — titles a build's asset view with its real status,
+ *  commit and description even when reached directly (not drilled in from the list). */
+export async function getBuild(np, buildId) {
+    const raw = await np.get(`/build/${buildId}`).catch(() => null);
+    return raw ? mapBuild(raw) : null;
 }
 function mapRelease(raw) {
     return {
@@ -232,11 +243,43 @@ export async function deploymentAction(np, deploymentId, action) {
         status: action === "finalize" ? "finalizing" : "cancelling",
     });
 }
+/** The scope id encoded in a value's NRN (…:scope=<id>), or null for an application-level value. */
+function scopeIdFromNrn(nrn) {
+    const match = nrn?.match(/:scope=(\d+)/);
+    return match ? Number(match[1]) : null;
+}
+function mapParameter(raw) {
+    const secret = !!raw.secret;
+    return {
+        id: raw.id,
+        name: raw.name,
+        variable: raw.variable,
+        destination_path: raw.destination_path,
+        type: raw.type,
+        secret,
+        read_only: raw.read_only,
+        values: (raw.values ?? []).map((entry) => {
+            const dimensions = entry.dimensions && Object.keys(entry.dimensions).length ? entry.dimensions : null;
+            const scopeId = scopeIdFromNrn(entry.nrn);
+            return {
+                id: entry.id,
+                // a value row only exists where a value is set, so secrets become a fixed marker (never plaintext)
+                value: secret ? "•••" : entry.value,
+                nrn: entry.nrn,
+                scope_id: scopeId,
+                dimensions,
+                base: !scopeId && !dimensions,
+            };
+        }),
+    };
+}
 /**
- * Upsert parameters. Agents retry, and re-running "set DATABASE_URL" must not accrete a
- * duplicate definition — so reuse the existing definition (matched by variable/name at this
- * NRN) and just add a value; only POST a new definition when none exists. Reports how many
- * were created vs updated.
+ * Upsert parameters, optionally targeting a scope (pin `nrn`) or a dimension set (`dimensions`).
+ * Agents retry, and re-running "set DATABASE_URL" must not accrete a duplicate definition — so
+ * reuse the existing definition (matched by variable/name at this NRN) and just add a value; only
+ * POST a new definition when none exists. The value write is convergent on (nrn, dimensions,
+ * value) server-side, so a retried set is a no-op new version, never a duplicate. Reports how
+ * many definitions were created vs reused.
  */
 export async function setParameters(np, nrn, params) {
     const existing = (await listParameters(np, nrn)) ?? [];
@@ -261,28 +304,24 @@ export async function setParameters(np, nrn, params) {
             definitionId = definition.id;
             created++;
         }
-        await np.post(`/parameter/${definitionId}/values`, { values: [{ nrn, value: param.value }] });
+        const valueBody = { nrn: param.nrn ?? nrn, value: param.value };
+        if (param.dimensions && Object.keys(param.dimensions).length) {
+            valueBody.dimensions = param.dimensions;
+        }
+        await np.post(`/parameter/${definitionId}/values`, { values: [valueBody] });
     }
     return { created, updated };
 }
-/** Read parameters — NRN-scoped on the public API; returns undefined when unavailable. */
+/** Read parameters with their full value set — NRN-scoped on the public API. Pass an application
+ *  NRN to get EVERY value (all dimensions + scopes); pass a scope NRN and the platform collapses
+ *  each parameter to the single effective value for that scope. undefined when unavailable. */
 export async function listParameters(np, nrn, options = {}) {
     try {
         const query = { nrn, limit: options.limit ?? 100 };
         if (options.offset)
             query.offset = options.offset;
         const page = await np.get("/parameter", query);
-        return (page.results ?? []).map((parameter) => ({
-            id: parameter.id,
-            name: parameter.name,
-            variable: parameter.variable,
-            type: parameter.type,
-            secret: !!parameter.secret,
-            values: (parameter.values ?? []).map((entry) => ({
-                value: parameter.secret ? "•••" : entry.value,
-                nrn: entry.nrn,
-            })),
-        }));
+        return (page.results ?? []).map(mapParameter);
     }
     catch {
         return undefined;
@@ -436,3 +475,176 @@ export async function listServiceSpecifications(bff, nrn) {
         .catch(() => ({ results: [] }));
     return (page.results ?? []).map((spec) => ({ id: spec.id, name: spec.name ?? spec.id }));
 }
+// ---- service provisioning & linking (WRITES — core API, like scopes/deployments) ----
+//
+// Grounded against the public service-api OpenAPI (request/response SHAPE) and the platform team's
+// np-developer-actions skill (BEHAVIOUR — the working implementation of exactly this flow).
+//
+// Provisioning is TWO sequential POSTs: `POST /service` creates the record in `pending`, then
+// `POST /service/{id}/action` enqueues the "create" action an external agent processes to `active`
+// (without #2 the service is `pending` forever). Linking is one OR two POSTs depending on the LINK
+// spec's `use_default_actions` — the SQL landmine, encoded in `linkService` so `status` is derived,
+// never an input. Reads `.catch` to empty; writes throw so the tool surfaces the platform error.
+const TERMINAL_SERVICE = new Set(["active", "failed", "cancelled"]);
+export const isServiceTerminal = (status) => TERMINAL_SERVICE.has(status ?? "");
+/**
+ * Provisionable dependency specs at an entity NRN, read from the CORE API (not the BFF projection
+ * that `listServiceSpecifications` uses) so the write flow can reach the action specs and
+ * `use_default_actions` the dashboard list omits.
+ */
+export async function listDependencySpecs(np, nrn) {
+    const page = await np
+        .get("/service_specification", { nrn, type: "dependency", limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        category: spec.selectors?.category,
+        subCategory: spec.selectors?.sub_category,
+        provider: spec.selectors?.provider,
+    }));
+}
+const mapActionSpec = (spec) => ({
+    id: spec.id,
+    type: spec.type ?? "",
+    name: spec.name,
+    slug: spec.slug,
+    schema: spec.parameters?.schema,
+});
+/** Every action spec of a service spec (`create`/`update`/`delete`/`custom`), mapped. The caller
+ *  filters by `type` — `custom` for run-an-action, `delete` for deprovision, `create` for provision. */
+export async function serviceActionSpecs(np, serviceSpecId) {
+    const page = await np
+        .get(`/service_specification/${serviceSpecId}/action_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapActionSpec);
+}
+/** The "create" action spec drives provisioning; its `parameters.schema` is the input form. */
+export async function serviceCreateActionSpec(np, serviceSpecId) {
+    return (await serviceActionSpecs(np, serviceSpecId)).find((spec) => spec.type === "create");
+}
+/**
+ * `POST /service` — creates the record in `pending`. Never sends `status` (the backend sets it).
+ * Provisioning does NOT start until `createServiceAction` enqueues the create action.
+ */
+export async function provisionService(np, input) {
+    return np.post("/service", {
+        name: input.name,
+        specification_id: input.specification_id,
+        entity_nrn: input.entity_nrn,
+        linkable_to: input.linkable_to ?? [input.entity_nrn],
+        dimensions: input.dimensions ?? {},
+        selectors: { imported: false },
+    });
+}
+/** `POST /service/{id}/action` — enqueue an action (the create action provisions). */
+export async function createServiceAction(np, serviceId, action) {
+    return np.post(`/service/${serviceId}/action`, {
+        name: action.name,
+        specification_id: action.specification_id,
+        parameters: action.parameters ?? {},
+    });
+}
+export async function getService(np, serviceId) {
+    return np.get(`/service/${serviceId}`);
+}
+/** The link spec(s) that apply to a service spec — the OpenAPI maps them directly. Each carries
+ *  `use_default_actions`, which decides the linking flow (see `linkService`). */
+export async function linkSpecsForService(np, serviceSpecId) {
+    const page = await np
+        .get(`/service_specification/${serviceSpecId}/link_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        use_default_actions: spec.use_default_actions ?? false,
+    }));
+}
+/** Every action spec of a link spec — the caller filters by `type` (`custom`/`delete`/`create`). */
+export async function linkActionSpecs(np, linkSpecId) {
+    const page = await np
+        .get(`/link_specification/${linkSpecId}/action_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapActionSpec);
+}
+/** The create action spec of a LINK spec (only present when `use_default_actions` is true). */
+export async function linkCreateActionSpec(np, linkSpecId) {
+    return (await linkActionSpecs(np, linkSpecId)).find((spec) => spec.type === "create");
+}
+/** `POST /link`. `status` is the SQL landmine: it is DERIVED from the link spec's
+ *  `use_default_actions`, never passed in. Caller passes the resolved spec; this never takes a free
+ *  `status`. */
+export async function createLink(np, input) {
+    const body = {
+        name: input.name,
+        service_id: input.service_id,
+        entity_nrn: input.entity_nrn,
+        specification_id: input.specification_id,
+        dimensions: input.dimensions ?? {},
+    };
+    // use_default_actions=false → no agent exists, so `active` must be set or the link is stuck
+    // `pending` forever. use_default_actions=true → OMIT status; a follow-up create-action provisions
+    // credentials. Sending `active` there yields an active-but-credential-less, unrecoverable link.
+    if (input.activateImmediately)
+        body.status = "active";
+    return np.post("/link", body);
+}
+export async function createLinkAction(np, linkId, action) {
+    return np.post(`/link/${linkId}/action`, {
+        name: action.name,
+        specification_id: action.specification_id,
+        parameters: action.parameters ?? {},
+    });
+}
+export async function getLink(np, linkId) {
+    return np.get(`/link/${linkId}`);
+}
+/** Existing dependency services on an app (core API) — for convergence: a retried provision must
+ *  reuse a same-name service rather than spin up a second (cost-bearing) one. */
+export async function listAppServices(np, nrn) {
+    const page = await np
+        .get("/service", { nrn, type: "dependency", limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((service) => ({
+        id: service.id,
+        name: service.name ?? service.id,
+        status: service.status ?? "",
+        specification_id: service.specification_id,
+    }));
+}
+/** Existing links on an app (core API) — for convergence: a retried link must reuse an existing one
+ *  for the same service+target rather than create a duplicate; also feeds the link picker (name) and
+ *  the link-action / link-delete flows (specification_id → the link spec's action specs). */
+export async function listLinks(np, nrn) {
+    const page = await np.get("/link", { nrn }).catch(() => ({ results: [] }));
+    return (page.results ?? []).map((link) => ({
+        id: link.id,
+        name: link.name ?? link.id,
+        status: link.status ?? "",
+        service_id: link.service_id,
+        entity_nrn: link.entity_nrn,
+        specification_id: link.specification_id,
+    }));
+}
+/** Poll one action of a service — `pending` → `in_progress` → `success`|`failed`. */
+export async function getServiceAction(np, serviceId, actionId) {
+    return np.get(`/service/${serviceId}/action/${actionId}`);
+}
+/** Poll one action of a link. */
+export async function getLinkAction(np, linkId, actionId) {
+    return np.get(`/link/${linkId}/action/${actionId}`);
+}
+/** `DELETE /service/{id}`. A `failed` service (no provisioned resources) deletes directly; an active
+ *  one needs `force` OR a prior delete-action that deprovisions — the tool decides which path. */
+export async function deleteService(np, serviceId, force = false) {
+    await np.del(`/service/${serviceId}`, force ? { force: true } : undefined);
+}
+/** `DELETE /link/{id}`. `force` skips the deprovisioning delete-action (orphans credentials), so the
+ *  tool only forces when there's no delete-action to run; otherwise it runs the action first. */
+export async function deleteLink(np, linkId, force = false) {
+    await np.del(`/link/${linkId}`, force ? { force: true } : undefined);
+}
+/** `DELETE /parameter/{id}` — removes a whole parameter definition (and all its values). */
+export async function deleteParameter(np, parameterId) {
+    await np.del(`/parameter/${parameterId}`);
+}

package/dist/tool-names.js

@@ -21,6 +21,13 @@ export const TOOL = {
     applicationReleaseCreate: "application_release_create",
     applicationScopeCreate: "application_scope_create",
     applicationServiceList: "application_service_list",
+    applicationServiceCreate: "application_service_create",
+    applicationServiceUpdate: "application_service_update",
+    applicationServiceDelete: "application_service_delete",
+    applicationLinkCreate: "application_link_create",
+    applicationLinkUpdate: "application_link_update",
+    applicationLinkDelete: "application_link_delete",
+    applicationParameterDelete: "application_parameter_delete",
     applicationApprovalList: "application_approval_list",
     organizationGet: "organization_get",
     playbookGet: "playbook_get",

package/dist/tools/action-flow.js

@@ -0,0 +1,94 @@
+import { translate } from "../i18n.js";
+import { linkLine, next, table } from "../md.js";
+import { fail, reply } from "../tool.js";
+import { delays, sleep } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+const actionLabel = (spec) => spec.name ?? spec.slug ?? spec.id;
+/**
+ * The run-a-custom-action flow shared by `application_service_update` and `application_link_update`:
+ * pick which action → fill its parameters (form-first; nothing runs without `run:true`) → POST the
+ * action → poll it once → report. A custom action is an explicit operation (it is NOT idempotent —
+ * running a DML twice runs it twice), so the safety here is the form gate, not convergence.
+ */
+export async function runActionFlow(config, args) {
+    const { entity, entityName, specs, dashboard } = config;
+    if (specs.length === 0) {
+        return fail(translate("runAction.noActions", { name: entityName }) + linkLine(translate("md.dashboard"), dashboard));
+    }
+    // Match the requested action by name/slug; none or ambiguous → list the runnable actions.
+    const wanted = args.action?.toLowerCase();
+    const matched = wanted
+        ? specs.filter((spec) => actionLabel(spec).toLowerCase().includes(wanted) ||
+            (spec.slug ?? "").toLowerCase() === wanted ||
+            spec.id === args.action)
+        : [];
+    if (matched.length !== 1) {
+        const list = matched.length > 1 ? matched : specs;
+        const heading = translate(matched.length > 1 ? "runAction.matchAmbiguous" : "runAction.pickAction", {
+            name: entityName,
+        });
+        const md = `${heading}\n\n${table([translate("header.name"), translate("runAction.paramsHeader")], list.map((spec) => [
+            actionLabel(spec),
+            (spec.schema?.required ?? []).join(", ") || "—",
+        ]))}${next(translate("runAction.pickHint"))}`;
+        return reply(md, {
+            mode: "pick-action",
+            entity,
+            tool: config.tool,
+            app: config.appRef,
+            app_name: config.appName,
+            target: { id: config.entityId, name: entityName, status: config.entityStatus },
+            actions: list.map((spec) => ({ id: spec.id, name: actionLabel(spec), slug: spec.slug })),
+            dashboard,
+        });
+    }
+    const spec = matched[0];
+    // Form-first: no explicit run OR a required parameter still missing → return the form.
+    const requiredKeys = spec.schema?.required ?? [];
+    const missing = requiredKeys.filter((key) => args.parameters?.[key] === undefined);
+    if (!args.run || missing.length > 0) {
+        return reply(translate("runAction.form", { action: actionLabel(spec), name: entityName }) +
+            next(translate("runAction.formHint")), {
+            mode: "form",
+            entity,
+            tool: config.tool,
+            app: config.appRef,
+            app_name: config.appName,
+            target: { id: config.entityId, name: entityName, status: config.entityStatus },
+            action: { id: spec.id, name: actionLabel(spec), slug: spec.slug },
+            parameters_schema: spec.schema ?? null,
+            dashboard,
+        });
+    }
+    // ---- RUN THE ACTION ----
+    const fired = await config.run({
+        name: spec.slug ?? slug(actionLabel(spec)),
+        specification_id: spec.id,
+        parameters: args.parameters ?? {},
+    });
+    await sleep(delays.appPoll);
+    const action = await config
+        .poll(fired.id)
+        .catch(() => ({ id: fired.id, status: fired.status ?? "pending" }));
+    const md = `${translate("runAction.running", { action: actionLabel(spec), name: entityName, status: action.status })}` +
+        next(translate("runAction.ranHint")) +
+        linkLine(translate("md.dashboard"), dashboard);
+    return reply(md, {
+        mode: "progress",
+        entity,
+        tool: config.tool,
+        app: config.appRef,
+        app_name: config.appName,
+        target: { id: config.entityId, name: entityName, status: config.entityStatus },
+        action: {
+            id: action.id,
+            name: actionLabel(spec),
+            status: action.status,
+            results: action.results ?? null,
+        },
+        dashboard,
+    });
+}

package/dist/tools/approvals.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, dashboardLink, glyph, linkLine, next, table } from "../md.js";
 import { cancelApproval, executeApproval, isSafeApprovalId, listApprovals } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
@@ -52,7 +52,7 @@ export const approvalsTool = defineTool({
             return reply(translate("approvals.none", { app: app.name }), { app: `#${app.id}`, approvals: [] });
         }
         const markdown = [
-            translate("approvals.title", { app: app.name, count: approvals.length }),
+            plural(approvals.length, "approvals.title.one", "approvals.title.many", { app: app.name }),
             "",
             table([
                 translate("header.id"),

package/dist/tools/builds.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, glyph, next, shortCommit, table } from "../md.js";
-import { listAssets, listBuilds, listReleases } from "../np/journey.js";
+import { getBuild, listAssets, listBuilds, listReleases } from "../np/journey.js";
 import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
@@ -33,10 +33,17 @@ export const buildsTool = defineTool({
             return resolved.out;
         const app = resolved.app;
         if (args.build) {
-            const assets = await listAssets(context.np, args.build);
+            // Fetch the build alongside its assets so the asset view shows the real status/commit and
+            // a no-assets message that fits the build's state (running vs failed vs simply none).
+            const [build, assets] = await Promise.all([
+                getBuild(context.np, args.build),
+                listAssets(context.np, args.build),
+            ]);
+            const buildData = build ?? { id: args.build, status: "" };
             if (assets.length === 0) {
-                return reply(translate("builds.noAssets", { build: args.build }), {
+                return reply(noAssetsText(build?.status, args.build), {
                     build_id: args.build,
+                    build: buildData,
                     assets: [],
                 });
             }
@@ -46,7 +53,7 @@ export const buildsTool = defineTool({
                 table([translate("header.asset"), translate("header.type"), translate("header.platform")], assets.map((asset) => [asset.name, asset.type, asset.platform ?? ""])),
                 next(translate("builds.deployHint", { build: args.build })),
             ].join("\n");
-            return reply(markdown, { build_id: args.build, assets });
+            return reply(markdown, { build_id: args.build, build: buildData, assets });
         }
         const [builds, releases] = await Promise.all([
             listBuilds(context.np, app.id, { limit: args.limit ?? 10, commit: args.commit, offset: args.offset }),
@@ -61,7 +68,7 @@ export const buildsTool = defineTool({
         const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
         const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));
         const markdown = [
-            translate("builds.title", { app: app.name, count: builds.length }),
+            plural(builds.length, "builds.title.one", "builds.title.many", { app: app.name }),
             "",
             table([
                 translate("header.id"),
@@ -92,6 +99,16 @@ export const buildsTool = defineTool({
         });
     },
 });
+/** No-assets message keyed to the build's state — "may still be running" only fits a build that
+ *  actually still is; a failed or finished one needs the truth. */
+function noAssetsText(status, build) {
+    if (status === "pending" || status === "in_progress") {
+        return translate("builds.noAssetsRunning", { build });
+    }
+    if (status === "failed")
+        return translate("builds.noAssetsFailed", { build });
+    return translate("builds.noAssets", { build });
+}
 function buildsHint(builds, releasedBuildIds) {
     const newestSuccessful = builds.find((build) => build.status === "successful");
     if (newestSuccessful && !releasedBuildIds.has(newestSuccessful.id)) {

package/dist/tools/create-app.js

@@ -48,6 +48,10 @@ export const createAppTool = defineTool({
     errorKey: "createApp.errorLabel",
     inputSchema: {
         name: z.string().optional().describe("App name (default: the repo name)"),
+        account: z
+            .string()
+            .optional()
+            .describe("Account name to place the app under — narrows the namespace choice to that account (a namespace name can repeat across accounts). Pick the best-fitting account from context when it isn't given."),
         namespace: z.string().optional().describe("Namespace name (prefer namespace_id when known)"),
         namespace_id: z.number().optional().describe("Namespace id to create the app in"),
         repository_url: z
@@ -104,26 +108,39 @@ export const createAppTool = defineTool({
                 ?.replace(/\.git$/, "");
         if (!name)
             return fail(translate("createApp.noName", { url: repoUrl }));
-        // Resolve the target namespace. If it can't be pinned down and there's a real choice, fall
-        // back to the form (rendered as a picker in the widget) rather than a dead-end ask.
+        // Resolve where the app lives — an (account, namespace) pair. Narrow to the named account first
+        // (a namespace name can repeat across accounts), then match/auto-pick the namespace inside it.
+        // If it still can't be pinned down and there's a real choice, fall back to the form (a picker)
+        // rather than a dead-end ask.
         const skeleton = await context.org.getSkeleton();
+        const accountQuery = args.account?.toLowerCase();
+        const candidates = accountQuery
+            ? skeleton.namespaces.filter((candidate) => (candidate.account_name ?? "").toLowerCase().includes(accountQuery))
+            : skeleton.namespaces;
+        if (accountQuery && candidates.length === 0) {
+            const accounts = [
+                ...new Set(skeleton.namespaces.map((candidate) => candidate.account_name).filter(Boolean)),
+            ];
+            return fail(translate("createApp.noAccountMatch", { account: args.account ?? "", names: accounts.join(", ") }));
+        }
         let namespace = args.namespace_id
-            ? skeleton.namespaces.find((candidate) => candidate.id === args.namespace_id)
+            ? candidates.find((candidate) => candidate.id === args.namespace_id)
             : undefined;
         if (!namespace && args.namespace) {
             const query = args.namespace.toLowerCase();
-            const matches = skeleton.namespaces.filter((candidate) => candidate.name.toLowerCase().includes(query));
+            const matches = candidates.filter((candidate) => candidate.name.toLowerCase().includes(query));
             if (matches.length === 1)
                 namespace = matches[0];
             else if (matches.length === 0) {
                 return fail(translate("createApp.noNamespaceMatch", {
                     namespace: args.namespace,
-                    names: skeleton.namespaces.map((candidate) => candidate.name).join(", "),
+                    names: candidates.map((candidate) => candidate.name).join(", "),
                 }));
             }
         }
-        if (!namespace && skeleton.namespaces.length === 1)
-            namespace = skeleton.namespaces[0];
+        // One namespace in scope (the whole org, or the chosen account) → auto-pick it.
+        if (!namespace && candidates.length === 1)
+            namespace = candidates[0];
         if (!namespace) {
             if (skeleton.namespaces.length === 0)
                 return fail(translate("createApp.noNamespaces"));
@@ -174,10 +191,21 @@ export const createAppTool = defineTool({
             .slice(-3)
             .map((entry) => `- ${entry.message ?? JSON.stringify(entry)}`)
             .join("\n");
-        const structured = { application: { id: app.id, name, status: app.status, nrn: app.nrn } };
+        // A new repo scaffolded from a template is a fresh REMOTE repo the developer has never cloned —
+        // the next move is to pull it into a folder and build there. An import is already local, so its
+        // next move is just to push. The two paths get different guidance.
+        const scaffolded = args.template_id !== undefined;
+        const structured = {
+            application: { id: app.id, name, status: app.status, nrn: app.nrn },
+            scaffolded,
+            repository_url: repoUrl,
+        };
+        const createdHint = scaffolded
+            ? translate("createApp.createdHintNew", { repo: repoUrl })
+            : translate("createApp.createdHint");
         if (app.status === "active") {
             return reply(`${glyph("active")} ${translate("createApp.created", { name, id: app.id, namespace: namespace.name, repo: repoUrl })}${recentMessages ? `\n${recentMessages}` : ""}` +
-                next(translate("createApp.createdHint")) +
+                next(createdHint) +
                 dashboard, structured);
         }
         return reply(`${translate("createApp.pending", { name, id: app.id, status: app.status })}${recentMessages ? `\n${recentMessages}` : ""}` +