@nullplatform/mcp 0.1.6 → 0.1.7

package/dist/tools/params.js

@@ -1,17 +1,34 @@
 import { plural, translate } from "../i18n.js";
 import { dashboardLink, linkLine, next, table } from "../md.js";
-import { listParameters } from "../np/journey.js";
+import { listParameters, listScopes } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
+import { appArg, dimsLabel, offsetArg, pageOf, pickScope, requireApp, scopeArg } from "./shared.js";
+/** Where a value applies, in words: the base (Application), a dimension set, or a named scope. */
+function contextLabel(value, scopeNameById) {
+    if (value.scope_id) {
+        return translate("params.ctxScope", { scope: scopeNameById.get(value.scope_id) ?? `#${value.scope_id}` });
+    }
+    if (value.dimensions)
+        return dimsLabel(value.dimensions);
+    return translate("params.ctxApplication");
+}
+/** The full value set of a parameter, summarized as "context: value" pairs for the text table. */
+function valueSummary(parameter, scopeNameById) {
+    if (!parameter.values.length)
+        return translate("params.unset");
+    return parameter.values
+        .map((value) => `${contextLabel(value, scopeNameById)}: ${value.value ?? translate("params.unset")}`)
+        .join(" · ");
+}
 export const paramsTool = defineTool({
     name: TOOL.applicationParameterList,
     title: "Parameters",
-    description: "List an application's configuration parameters (env vars / files; secret values are masked). Use application_parameter_create to add or change them.",
+    description: "List an application's configuration parameters and every value they hold across scopes and dimensions (env vars / files; secret values are masked). Pass `scope` to resolve the single effective value per parameter for that scope. Use application_parameter_create to add or change them.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "params.errorLabel",
-    inputSchema: { app: appArg, offset: offsetArg },
+    inputSchema: { app: appArg, scope: scopeArg, offset: offsetArg },
     async handler(args, context) {
         const resolved = await requireApp(context, args);
         if ("out" in resolved)
@@ -19,12 +36,32 @@ export const paramsTool = defineTool({
         const app = resolved.app;
         if (!app.nrn)
             return fail(translate("resolve.noNrn", { app: app.name }));
-        const [parameters, orgSlug] = await Promise.all([
-            listParameters(context.np, app.nrn, { offset: args.offset }),
+        const [scopes, orgSlug] = await Promise.all([
+            listScopes(context.np, app.id),
             context.org.organizationSlug(),
         ]);
+        const scopeNameById = new Map(scopes.map((scope) => [scope.id, scope.name]));
         const dashboard = dashboardLink(orgSlug, app.nrn);
-        const appRef = { app: `#${app.id}`, app_name: app.name };
+        // scopes ride along so the widget can build its scope picker AND derive the by-dimension targets
+        const appRef = {
+            app: `#${app.id}`,
+            app_name: app.name,
+            scopes: scopes.map((scope) => ({ id: scope.id, name: scope.name, dimensions: scope.dimensions ?? {} })),
+        };
+        // With a scope, read at the scope NRN so the platform collapses each parameter to its single
+        // effective value (scope value › most-specific dimension match › app default).
+        let resolvedScope;
+        let readNrn = app.nrn;
+        if (args.scope) {
+            const picked = pickScope(scopes, args.scope);
+            if ("out" in picked)
+                return picked.out;
+            if (!picked.scope.nrn)
+                return fail(translate("resolve.noNrn", { app: picked.scope.name }));
+            resolvedScope = { id: picked.scope.id, name: picked.scope.name };
+            readNrn = picked.scope.nrn;
+        }
+        const parameters = await listParameters(context.np, readNrn, { offset: args.offset });
         if (parameters === undefined) {
             return reply(translate("params.unavailable") + linkLine(translate("params.viewInDashboard"), dashboard), { available: false, ...appRef });
         }
@@ -35,6 +72,35 @@ export const paramsTool = defineTool({
                 ...appRef,
             });
         }
+        const payload = {
+            available: true,
+            params: parameters,
+            page: pageOf(parameters.length, 100, args.offset ?? 0),
+            ...(resolvedScope ? { resolved_scope: resolvedScope } : {}),
+            ...appRef,
+        };
+        if (resolvedScope) {
+            const markdown = [
+                translate("params.effectiveFor", { app: app.name, scope: resolvedScope.name }),
+                "",
+                table([
+                    translate("header.name"),
+                    translate("header.variable"),
+                    translate("header.value"),
+                    translate("header.source"),
+                ], parameters.map((parameter) => {
+                    const effective = parameter.values[0];
+                    return [
+                        parameter.name,
+                        parameter.variable ?? parameter.destination_path ?? "",
+                        effective?.value ?? translate("params.unset"),
+                        effective ? contextLabel(effective, scopeNameById) : "—",
+                    ];
+                })),
+                next(translate("params.applyHint")),
+            ].join("\n");
+            return reply(markdown, payload);
+        }
         const markdown = [
             plural(parameters.length, "params.count.one", "params.count.many", { app: app.name }),
             "",
@@ -43,21 +109,16 @@ export const paramsTool = defineTool({
                 translate("header.variable"),
                 translate("header.type"),
                 translate("header.secret"),
-                translate("header.value"),
+                translate("header.values"),
             ], parameters.map((parameter) => [
                 parameter.name,
-                parameter.variable ?? "",
-                parameter.type ?? "ENVIRONMENT",
+                parameter.variable ?? parameter.destination_path ?? "",
+                parameter.type ?? "environment",
                 parameter.secret ? "🔒" : "",
-                parameter.values[0]?.value ?? translate("params.unset"),
+                valueSummary(parameter, scopeNameById),
             ])),
             next(translate("params.applyHint")),
         ].join("\n");
-        return reply(markdown, {
-            available: true,
-            params: parameters,
-            page: pageOf(parameters.length, 100, args.offset ?? 0),
-            ...appRef,
-        });
+        return reply(markdown, payload);
     },
 });

package/dist/tools/playbook.js

@@ -16,7 +16,8 @@ export const playbookGetTool = defineTool({
     title: "Operating playbooks",
     description: "Read a nullplatform operating playbook — the methodology to follow BEFORE the matching non-trivial work (e.g. deploying-safely before a deploy, incident-response when something is broken, configuring-safely before changing parameters or secrets). The server instructions carry the full catalog; call this with no name to list them too.",
     annotations: { readOnlyHint: true },
-    widget: "playbook",
+    // No widget: a playbook is model-facing methodology prose, not an interactive entity — it
+    // renders as text (the markdown below) for the model to read and act on. See CLAUDE.md.
     errorKey: "playbook.errorLabel",
     inputSchema: {
         name: z.string().optional().describe('Playbook name, e.g. "deploying-safely". Omit to list them.'),

package/dist/tools/releases.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, glyph, next, table } from "../md.js";
 import { listReleases } from "../np/journey.js";
 import { defineTool, reply } from "../tool.js";
@@ -34,7 +34,7 @@ export const releasesTool = defineTool({
             return reply(translate("releaseList.none", { app: app.name }) + next(translate("releaseList.noneHint")), { app: `#${app.id}`, app_name: app.name, releases: [] });
         }
         const markdown = [
-            translate("releaseList.title", { app: app.name, count: releases.length }),
+            plural(releases.length, "releaseList.title.one", "releaseList.title.many", { app: app.name }),
             "",
             table([
                 translate("header.version"),

package/dist/tools/services.js

@@ -1,4 +1,4 @@
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { dashboardLink, glyph, linkLine, next, table } from "../md.js";
 import { listServiceSpecifications, listServices } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
@@ -37,7 +37,7 @@ export const servicesTool = defineTool({
             sections.push(translate("services.none", { app: app.name }));
         }
         else {
-            sections.push(translate("services.attached", { app: app.name, count: services.length }));
+            sections.push(plural(services.length, "services.attached.one", "services.attached.many", { app: app.name }));
             sections.push("");
             sections.push(table([translate("header.name"), translate("services.specification"), translate("header.status")], services.map((service) => [
                 service.name,

package/dist/tools/set-params.js

@@ -1,14 +1,14 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { next } from "../md.js";
-import { listParameters, setParameters } from "../np/journey.js";
+import { listParameters, listScopes, setParameters } from "../np/journey.js";
 import { defineTool, errorMessage, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { appArg, requireApp } from "./shared.js";
+import { appArg, pickScope, requireApp } from "./shared.js";
 export const setParamsTool = defineTool({
     name: TOOL.applicationParameterCreate,
     title: "Set parameters",
-    description: "Create or update application configuration parameters (environment variables or files; mark secrets). Values apply on the NEXT deploy.",
+    description: "Create or update application configuration parameters (environment variables or files; mark secrets). Target a value at the application (default — every scope), by dimension (applies to any matching scope), or pinned to one scope. Values apply on the NEXT deploy.",
     annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "setParams.errorLabel",
@@ -18,8 +18,19 @@ export const setParamsTool = defineTool({
             .array(z.object({
             name: z.string().describe("Variable name, e.g. DATABASE_URL"),
             value: z.string(),
-            secret: z.boolean().optional().describe("Mask the value (default false)"),
+            secret: z
+                .boolean()
+                .optional()
+                .describe("Mask the value — only honored when first creating the parameter (secrecy is immutable after)"),
             type: z.enum(["ENVIRONMENT", "FILE"]).optional().describe("Default ENVIRONMENT"),
+            scope: z
+                .string()
+                .optional()
+                .describe('Pin this value to ONE scope (name, "#id", or "key=value") — the last-resort target. Do not combine with dimensions.'),
+            dimensions: z
+                .record(z.string())
+                .optional()
+                .describe('Target by dimension, e.g. {"environment":"production"} — the value then applies to any scope whose dimensions match. Do not combine with scope.'),
         }))
             .min(1),
     },
@@ -30,23 +41,57 @@ export const setParamsTool = defineTool({
         const app = resolved.app;
         if (!app.nrn)
             return fail(translate("resolve.noNrn", { app: app.name }));
+        // A scope NRN already locates the value; dimensions only apply at the application NRN. The
+        // platform rejects scope-NRN + dimensions (SCOPE_NRN_DIMENSIONS_AMBIGUITY) — catch it early.
+        const conflict = args.params.find((param) => param.scope && param.dimensions && Object.keys(param.dimensions).length);
+        if (conflict)
+            return fail(translate("setParams.scopeDimConflict", { name: conflict.name }));
+        // One scope fetch — used both to resolve scope refs to NRNs and to feed the widget's picker.
+        const scopes = await listScopes(context.np, app.id).catch(() => []);
+        const inputs = [];
+        for (const param of args.params) {
+            let nrn;
+            if (param.scope) {
+                const picked = pickScope(scopes, param.scope);
+                if ("out" in picked)
+                    return picked.out;
+                if (!picked.scope.nrn)
+                    return fail(translate("resolve.noNrn", { app: picked.scope.name }));
+                nrn = picked.scope.nrn;
+            }
+            inputs.push({
+                name: param.name,
+                value: param.value,
+                secret: param.secret,
+                type: param.type,
+                nrn,
+                dimensions: param.dimensions,
+            });
+        }
         try {
-            const result = await setParameters(context.np, app.nrn, args.params);
-            const names = args.params.map((parameter) => `\`${parameter.name}\``).join(", ");
+            const result = await setParameters(context.np, app.nrn, inputs);
+            const names = args.params.map((param) => `\`${param.name}\``).join(", ");
             const total = result.created + result.updated;
             // Honest about upsert: say how many were new vs changed so a retry reads as "0 new".
             const summary = result.updated === 0
-                ? translate("setParams.created", { count: result.created, app: app.name, names })
+                ? plural(result.created, "setParams.created.one", "setParams.created.many", {
+                    app: app.name,
+                    names,
+                })
                 : result.created === 0
-                    ? translate("setParams.updated", { count: result.updated, app: app.name, names })
+                    ? plural(result.updated, "setParams.updated.one", "setParams.updated.many", {
+                        app: app.name,
+                        names,
+                    })
                     : translate("setParams.mixed", {
                         created: result.created,
                         updated: result.updated,
+                        total,
                         app: app.name,
                         names,
                     });
-            // Mirror the params widget's shape so the SAME panel renders the resulting set with its
-            // add/save affordance (read-after-write); the markdown stays the plain confirmation.
+            // Mirror the params widget's shape so the SAME panel renders the resulting set (with its
+            // scope picker + add affordance) after the write; the markdown stays the plain confirmation.
             const parameters = await listParameters(context.np, app.nrn).catch(() => undefined);
             return reply(summary + next(translate("setParams.applyHint")), {
                 created: result.created,
@@ -54,6 +99,11 @@ export const setParamsTool = defineTool({
                 total,
                 app: `#${app.id}`,
                 app_name: app.name,
+                scopes: scopes.map((scope) => ({
+                    id: scope.id,
+                    name: scope.name,
+                    dimensions: scope.dimensions ?? {},
+                })),
                 ...(parameters === undefined ? { available: false } : { available: true, params: parameters }),
             });
         }

package/dist/tools/shared.js

@@ -15,6 +15,10 @@ export const offsetArg = z
     .number()
     .optional()
     .describe("Skip this many items to page through a long list (use page.next_offset from a prior call).");
+export const scopeArg = z
+    .string()
+    .optional()
+    .describe('Scope name, "#id", or a dimension match like "environment=production". Omit to list every value across all scopes and dimensions.');
 /**
  * Pagination token for a list reply. No list endpoint returns a total, so the boundary is the
  * standard offset heuristic: a full page means there is likely more. The widget/model pages by

package/dist/tools/update-link.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, next, table } from "../md.js";
+import { createLinkAction, getLinkAction, linkActionSpecs, listLinks } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { runActionFlow } from "./action-flow.js";
+import { appArg, requireApp } from "./shared.js";
+/**
+ * Run a custom action on a link — the platform-team-defined operations a link specification exposes
+ * under "Run action". Not every link spec has custom actions (many only have create/delete). Creating
+ * a link is `application_link_create`, removing it is `application_link_delete`. Form-first, same as
+ * the service variant.
+ */
+export const updateLinkTool = defineTool({
+    name: TOOL.applicationLinkUpdate,
+    title: "Run link action",
+    description: "Run a custom action on a link (a service↔application connection) — the platform-team-defined operations its link specification exposes. Pass `link` to choose which one (by name) and `action` to choose which action; call WITHOUT `run:true` first to open the form. Not every link has custom actions.",
+    annotations: { destructiveHint: false, openWorldHint: true },
+    widget: "service-action",
+    errorKey: "runAction.errorLabel",
+    inputSchema: {
+        app: appArg,
+        link: z.string().optional().describe("Which link to operate, by name (or the link id)"),
+        action: z.string().optional().describe("Which custom action to run, by name (or its slug)"),
+        parameters: z
+            .record(z.unknown())
+            .optional()
+            .describe("Values for the action parameters (per the action spec's schema shown in the form)"),
+        run: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually run the action (the form's submit sets it). Omit to return the form."),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (!app.nrn)
+            return fail(translate("resolve.noNrn", { app: app.name }));
+        const orgSlug = await context.org.organizationSlug();
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        // The app's links — pick which one to operate.
+        const links = (await listLinks(context.np, app.nrn)).filter((link) => link.status !== "failed");
+        if (links.length === 0) {
+            return fail(translate("runAction.noLinks", { app: app.name }) + next(translate("runAction.noLinksHint")));
+        }
+        const wanted = args.link?.toLowerCase();
+        const matched = wanted
+            ? links.filter((link) => link.name.toLowerCase().includes(wanted) || link.id === args.link)
+            : [];
+        if (matched.length !== 1) {
+            const list = matched.length > 1 ? matched : links;
+            const md = `${translate(matched.length > 1 ? "runAction.linkAmbiguous" : "runAction.pickLink", {
+                app: app.name,
+            })}\n\n${table([translate("header.name"), translate("header.status")], list.map((link) => [link.name, link.status]))}${next(translate("runAction.pickLinkHint"))}`;
+            return reply(md, {
+                mode: "pick-target",
+                entity: "link",
+                tool: TOOL.applicationLinkUpdate,
+                app: `#${app.id}`,
+                app_name: app.name,
+                targets: list,
+                dashboard,
+            });
+        }
+        const link = matched[0];
+        const specs = link.specification_id
+            ? (await linkActionSpecs(context.np, link.specification_id)).filter((spec) => spec.type === "custom")
+            : [];
+        const config = {
+            tool: TOOL.applicationLinkUpdate,
+            entity: "link",
+            appRef: `#${app.id}`,
+            appName: app.name,
+            entityId: link.id,
+            entityName: link.name,
+            entityStatus: link.status,
+            specs,
+            dashboard,
+            run: (input) => createLinkAction(context.np, link.id, input),
+            poll: (actionId) => getLinkAction(context.np, link.id, actionId),
+        };
+        return runActionFlow(config, args);
+    },
+});

package/dist/tools/update-service.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, next, table } from "../md.js";
+import { createServiceAction, getServiceAction, listAppServices, serviceActionSpecs } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { runActionFlow } from "./action-flow.js";
+import { appArg, requireApp } from "./shared.js";
+/**
+ * Run a custom action on a provisioned service — the platform-team-defined ad-hoc operations the
+ * dashboard surfaces under "Run action" (e.g. a Postgres "Run DML Query" / "Run DDL Query"). These
+ * are the action specs of `type: custom`; provisioning (`create`) is `application_service_create`,
+ * and deprovisioning (`delete`) is `application_service_delete`. Form-first: nothing runs until the
+ * user submits, because a custom action is an explicit, non-idempotent operation.
+ */
+export const updateServiceTool = defineTool({
+    name: TOOL.applicationServiceUpdate,
+    title: "Run service action",
+    description: "Run a custom action on a provisioned service — the platform-team-defined operations a service exposes (e.g. a Postgres database's DML/DDL query runners). Pass `service` to choose which one (by name) and `action` to choose which action; call WITHOUT `run:true` first to open the form, the user confirms by submitting it. A custom action is an explicit operation (not idempotent), so it never runs without that submit.",
+    annotations: { destructiveHint: false, openWorldHint: true },
+    widget: "service-action",
+    errorKey: "runAction.errorLabel",
+    inputSchema: {
+        app: appArg,
+        service: z
+            .string()
+            .optional()
+            .describe("Which provisioned service to operate, by name (or the service id)"),
+        action: z.string().optional().describe("Which custom action to run, by name (or its slug)"),
+        parameters: z
+            .record(z.unknown())
+            .optional()
+            .describe("Values for the action parameters (per the action spec's schema shown in the form)"),
+        run: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually run the action (the form's submit sets it). Omit to return the form."),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (!app.nrn)
+            return fail(translate("resolve.noNrn", { app: app.name }));
+        const orgSlug = await context.org.organizationSlug();
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        // The app's provisioned services — pick which one to operate.
+        const services = (await listAppServices(context.np, app.nrn)).filter((service) => service.status !== "failed");
+        if (services.length === 0) {
+            return fail(translate("runAction.noServices", { app: app.name }) + next(translate("runAction.noServicesHint")));
+        }
+        const wanted = args.service?.toLowerCase();
+        const matched = wanted
+            ? services.filter((service) => service.name.toLowerCase().includes(wanted) || service.id === args.service)
+            : [];
+        if (matched.length !== 1) {
+            const list = matched.length > 1 ? matched : services;
+            const md = `${translate(matched.length > 1 ? "runAction.serviceAmbiguous" : "runAction.pickService", {
+                app: app.name,
+            })}\n\n${table([translate("header.name"), translate("header.status")], list.map((service) => [service.name, service.status]))}${next(translate("runAction.pickServiceHint"))}`;
+            return reply(md, {
+                mode: "pick-target",
+                entity: "service",
+                tool: TOOL.applicationServiceUpdate,
+                app: `#${app.id}`,
+                app_name: app.name,
+                targets: list,
+                dashboard,
+            });
+        }
+        const service = matched[0];
+        // Only `custom` action specs are user-runnable (create/update/delete drive the lifecycle).
+        const specs = service.specification_id
+            ? (await serviceActionSpecs(context.np, service.specification_id)).filter((spec) => spec.type === "custom")
+            : [];
+        const config = {
+            tool: TOOL.applicationServiceUpdate,
+            entity: "service",
+            appRef: `#${app.id}`,
+            appName: app.name,
+            entityId: service.id,
+            entityName: service.name,
+            entityStatus: service.status,
+            specs,
+            dashboard,
+            run: (input) => createServiceAction(context.np, service.id, input),
+            poll: (actionId) => getServiceAction(context.np, service.id, actionId),
+        };
+        return runActionFlow(config, args);
+    },
+});

package/dist/ui.js

@@ -25,7 +25,10 @@ export const WIDGETS = {
     approvals: "Approvals",
     overview: "Organization overview",
     services: "Services & dependencies",
-    playbook: "Operating playbooks",
+    "service-create": "Provision service",
+    "service-link": "Link service",
+    "service-action": "Run action",
+    "service-delete": "Delete service",
 };
 /** Did this session's client negotiate the MCP Apps extension? (Knowable after initialize.) */
 export function uiNegotiated(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "nullplatform from your code assistant — an MCP server that replaces the dashboard for the everyday developer journey",
   "license": "MIT",
   "author": "nullplatform",
@@ -50,6 +50,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
+    "@jsonforms/core": "^3.5.1",
+    "@jsonforms/react": "^3.5.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^20.14.0",
     "@types/react": "^19.2.17",

package/skills/starting-a-new-app/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: starting-a-new-app
+description: Use when standing up something NEW on nullplatform — a new application (or a small set, e.g. a frontend and its API), choosing where it lives, wiring its data dependencies, and getting it to a first running deploy before any features are built. The greenfield counterpart to working-from-a-ticket.
+---
+
+# Starting a new app on nullplatform
+
+nullplatform owns the *platform* half — where the app lives, how it ships, what it depends on.
+The code is your own craft. This playbook carries a new thing from a request to its first running
+deploy with its dependencies wired, then hands the feature-building back to you. Do it in order:
+each step de-risks the next. Standing up the skeleton and *then* coding beats coding against a
+platform you haven't proven yet.
+
+## 1. Place it before you create it
+
+`application_create` opens a pre-filled form — but *where* it goes is a real decision, not a
+default. Read the request for the home it implies (a demo for a banking client in Argentina is not
+the same namespace as a throwaway): list the namespaces the form offers and pick the account +
+namespace that fits, and confirm that choice for anything that isn't obviously disposable. New repo
+vs. importing an existing one is the other fork the form covers; it derives the repo URL for new ones.
+
+A request often implies **more than one app** (a frontend *and* its API). Create them one at a time
+in the same namespace, named so the pair reads as a set — there is no batch-create, and that's fine:
+two focused creates are clearer than one opaque one.
+
+## 2. Get it running before you build on it
+
+Deploy the boilerplate to a real scope *first*, so the next step is "add features to a running app,"
+not "debug the platform and my code at once." Create the target environment with
+`managing-environments`, then ship the skeleton with `deploying-safely` (first-ever-deploy semantics
+live there). Real environments are usually **policy-gated** — a production scope or deploy may land
+in `creating_approval`; that's normal, surface it and don't fight it, keep moving on what isn't gated.
+
+## 3. Wire the data it needs
+
+A new product usually needs a dependency — a SQL database, a queue, a cache. `application_service_list`
+shows what's already attached and the catalog available; `application_service_create` provisions one
+and autolinks it. Provisioning creates **real cloud resources (cost-bearing)** and runs
+asynchronously, so it is **form-first**: call it to open the form, let the user fill the parameters
+and submit (the submit is the cost confirmation) — never pass `provision:true` unprompted. Target the
+link at the scope that needs the data. Don't call it "ready" until the service is active and linked.
+
+Once a service is linked, its connection details arrive **automatically as read-only parameters**
+(`DATABASE_URL`, host, credentials — secrets masked). Your code reads those env vars; you never
+hard-code them or re-create them by hand. New parameters only reach a running scope on the **next
+deploy**.
+
+## 4. Hand off to the build
+
+The platform's job is done when the app exists, runs, and its dependencies are wired and surfaced as
+parameters. Writing the REST API, the UI, the schema or its codegen — that is your craft, not this
+playbook's job (same boundary as `working-from-a-ticket`). Build against the injected env vars, keep
+the work on a branch with the issue key (`tracing-a-change`), push so CI produces a build, and ship
+it with `deploying-safely`.
+
+## 5. Configure and redeploy
+
+App-level config the code expects — a page-size cap, feature flags — is a parameter, not a code
+constant: set it with `application_parameter_create` (`configuring-safely` for targeting at app vs.
+scope vs. dimension). Remember values apply on the **next** deploy, so redeploy to pick them up.
+
+## Don'ts
+
+- Don't drop a new app in the default namespace without checking it fits the request.
+- Don't write feature code before the boilerplate has a running deploy — prove the platform first.
+- Don't re-create or hard-code connection details a service link already injects — read them as
+  parameters (they're `read_only`).
+- Don't treat provisioning as instant — it's async and costs money; confirm before, and don't mark
+  data "ready" until the service is active, linked, and a redeploy has surfaced its params.
+- Don't block the whole product on one approval — production gates are routine; surface them and
+  keep moving on everything that isn't gated.