localdeck 1.4.0 → 1.6.1

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   HOME_DIR,
   VERSION,
   __require,
+  applyProfiles,
   chooseUpstream,
   connectHost,
   dashboardDir,
@@ -31,7 +32,7 @@ import {
   unreachableListenerMessage,
   waitForReadiness,
   wrapper_default
-} from "./index-316fp4p2.js";
+} from "./index-2zg5ahh5.js";
 
 // src/index.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -155,7 +156,8 @@ async function startService(opts, overrides = {}) {
         upstreamPort,
         upstreamSource: opts.upstreamPort === undefined ? "assigned" : "manual",
         cwd,
-        command: opts.displayCommand ?? opts.command.join(" ")
+        command: opts.displayCommand ?? opts.command.join(" "),
+        ...opts.project ? { profiles: opts.profiles ?? [] } : {}
       });
     });
     ws.on("message", (raw) => {
@@ -849,7 +851,7 @@ ${c.bold("Usage")}
   localdeck run <name> [--port 4000] [--upstream 5173] [--] <command...>
   localdeck <name>                  run a command from the project's .localdeck file
   localdeck up [tag|name...]        run every .localdeck command (or just the tagged/named ones) in one terminal
-  localdeck up --profile <name>   run a saved profile and its prerequisites
+  localdeck profile [on|off <name...>|clear]  list or switch this project's profiles
   localdeck init [--dry-run] [--force]  preview/create/replace the project configuration
   localdeck init --name web --command 'your command'
   localdeck commands              list configured services (alias: cmds)
@@ -915,13 +917,16 @@ async function main(argv, overrides = {}) {
     case "--update":
       if (rest.length)
         throw new Error("Usage: localdeck --update");
-      return (await import("./update-w6vc3sdy.js")).updateLocalDeck();
+      return (await import("./update-n1fnecgj.js")).updateLocalDeck();
     case "up":
       return cmdUp(rest, dependencies);
+    case "profile":
+    case "profiles":
+      return cmdProfile(rest, dependencies);
     case "init":
       return cmdInit(rest, dependencies);
     case "mcp":
-      return (await import("./mcp-h8gf5pgj.js")).runMcp(rest);
+      return (await import("./mcp-r1ygwec0.js")).runMcp(rest);
     case "doctor":
       return cmdDoctor(rest);
     case "forward":
@@ -961,10 +966,12 @@ async function main(argv, overrides = {}) {
       const found = project && findProjectCommand(project, cmd);
       if (found) {
         const remembered = await rememberProject(project, dependencies);
+        const launch = await resolveLaunch(project, remembered, dependencies);
         const selected = startupLayers(project.commands, [found.name]).flat();
-        return dependencies.runForeground(selected.map((command, index) => toRunOptions(command, project, remembered, {
+        return dependencies.runForeground(selected.map((command, index) => toRunOptions(launch.effective(command), project, remembered, {
           prefix: selected.length > 1,
-          color: PALETTE[index % PALETTE.length]
+          color: PALETTE[index % PALETTE.length],
+          ...launch.options
         })));
       }
       const hint = project ? ` Commands in ${path3.basename(project.file)}: ${project.commands.map((p) => p.name).join(", ") || "(none)"}` : "";
@@ -1006,6 +1013,32 @@ async function rememberProject(project, dependencies) {
     return;
   }
 }
+async function resolveLaunch(project, remembered, dependencies) {
+  let active = [];
+  if (project.profiles?.length && remembered) {
+    try {
+      const daemon = await dependencies.ensureDaemon();
+      active = (await dependencies.createApi(daemon.apiPort).profiles(remembered.id)).active;
+    } catch (error) {
+      dependencies.warn(`LocalDeck: could not read active profiles, running without them: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  let resolved;
+  try {
+    resolved = applyProfiles(project, active);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  if (resolved.active.length)
+    dependencies.log(c.dim(`Profiles: ${resolved.active.join(" + ")}`));
+  for (const clash of resolved.clashes)
+    dependencies.warn(`LocalDeck: ${clash.profiles.join(" and ")} both set ${clash.service} ${clash.field}; ${clash.winner} wins because it is listed later.`);
+  const byName = new Map(resolved.commands.map((command) => [command.name, command]));
+  return {
+    effective: (command) => byName.get(command.name) ?? command,
+    options: remembered ? { profiles: resolved.active } : {}
+  };
+}
 async function printProjectCommands(failIfNone, dependencies) {
   const project = tryLoadProject(dependencies);
   if (!project) {
@@ -1017,6 +1050,9 @@ async function printProjectCommands(failIfNone, dependencies) {
   console.log(`${c.bold("Project commands")} ${c.dim(`(${path3.relative(process.cwd(), project.file) || path3.basename(project.file)})`)}`);
   const rows = project.commands.map((p) => [c.cyan(p.name), p.port ? String(p.port) : c.dim("auto"), p.after.join(",") || "", p.tags.join(",") || "", c.dim(p.run)]);
   console.log(table(rows, ["NAME", "PORT", "AFTER", "TAGS", "RUN"]));
+  if (project.profiles?.length)
+    console.log(`
+${c.bold("Profiles")} ${project.profiles.map((profile) => profile.name).join(", ")} ${c.dim("· localdeck profile")}`);
   console.log(c.dim(`
 run one: localdeck <name>   ·   run all: localdeck up   ·   by tag: localdeck up <tag>`));
 }
@@ -1033,12 +1069,16 @@ async function cmdUp(args, dependencies) {
       fail("--profile needs a profile name");
     args = args.filter((_, i) => i !== profileIndex && i !== profileIndex + 1);
   }
-  const profiles = project.profiles;
-  if (profile && (!profiles || !Object.prototype.hasOwnProperty.call(profiles, profile)))
-    fail(`unknown profile "${profile}". Available profiles: ${Object.keys(profiles ?? {}).join(", ") || "(none)"}`);
+  const legacy = project.legacyProfiles;
+  if (profile && project.profiles?.some((candidate) => candidate.name === profile))
+    fail(`"${profile}" is a profile you turn on, not a group to start: localdeck profile on ${profile}`);
+  if (profile && (!legacy || !Object.prototype.hasOwnProperty.call(legacy, profile)))
+    fail(`unknown profile "${profile}". Group services with tags and run: localdeck up <tag>`);
+  if (profile)
+    dependencies.warn(`LocalDeck: --profile is deprecated. "${profile}" is now a tag; run: localdeck up ${profile}`);
   let selected = project.commands;
   if (profile) {
-    const names = new Set(profiles[profile]);
+    const names = new Set(legacy[profile]);
     selected = project.commands.filter((command) => names.has(command.name));
     if (!selected.length)
       fail(`profile "${profile}" selects no configured services`);
@@ -1058,7 +1098,50 @@ async function cmdUp(args, dependencies) {
     fail("nothing to run");
   selected = startupLayers(project.commands, selected.map((command) => command.name)).flat();
   const remembered = await rememberProject(project, dependencies);
-  await dependencies.runForeground(selected.map((p, i) => toRunOptions(p, project, remembered, { prefix: selected.length > 1, color: PALETTE[i % PALETTE.length] })));
+  const launch = await resolveLaunch(project, remembered, dependencies);
+  await dependencies.runForeground(selected.map((p, i) => toRunOptions(launch.effective(p), project, remembered, { prefix: selected.length > 1, color: PALETTE[i % PALETTE.length], ...launch.options })));
+}
+async function cmdProfile(args, dependencies) {
+  const project = tryLoadProject(dependencies);
+  if (!project)
+    fail("no .localdeck file found here or in a parent folder. Create one with: localdeck init");
+  const [action = "list", ...names] = args;
+  if (!["list", "ls", "on", "off", "clear"].includes(action))
+    fail(`unknown profile action "${action}". Usage: localdeck profile [on|off <name...>|clear]`);
+  if ((action === "on" || action === "off") && !names.length)
+    fail(`localdeck profile ${action} needs at least one profile name`);
+  if (!project.profiles?.length) {
+    if (action === "list" || action === "ls") {
+      dependencies.log(`No profiles in ${path3.basename(project.file)}. Add a "profiles" object to run services differently, for example against staging.`);
+      return;
+    }
+    fail(`${path3.basename(project.file)} defines no profiles`);
+  }
+  const remembered = await rememberProject(project, dependencies);
+  if (!remembered)
+    fail("the LocalDeck daemon is needed to switch profiles");
+  const daemon = await dependencies.ensureDaemon();
+  const api = dependencies.createApi(daemon.apiPort);
+  let current = await api.profiles(remembered.id);
+  if (action === "on" || action === "off" || action === "clear") {
+    const wanted = names.map((name) => name.toLowerCase());
+    const unknown = wanted.filter((name) => !current.profiles.some((candidate) => candidate.name === name));
+    if (unknown.length)
+      fail(`unknown profile ${unknown.map((name) => `"${name}"`).join(", ")}. Available profiles: ${current.profiles.map((candidate) => candidate.name).join(", ")}`);
+    const next = action === "clear" ? [] : action === "on" ? [...new Set([...current.active, ...wanted])] : current.active.filter((name) => !wanted.includes(name));
+    current = await api.setActiveProfiles(remembered.id, next);
+    dependencies.log(current.active.length ? `Profiles on: ${c.cyan(current.active.join(" + "))}` : "No profiles on · running base services");
+    dependencies.log(c.dim("Running services keep their settings until restarted."));
+  } else {
+    const rows = current.profiles.map((candidate) => [candidate.active ? c.green("on") : c.dim("off"), c.cyan(candidate.name), candidate.services.join(","), candidate.description ?? ""]);
+    dependencies.log(table(rows, ["", "PROFILE", "CHANGES", "DESCRIPTION"]));
+    dependencies.log(c.dim(`
+turn on: localdeck profile on <name>   ·   off: localdeck profile off <name>   ·   all off: localdeck profile clear`));
+  }
+  for (const clash of current.clashes)
+    dependencies.warn(`LocalDeck: ${clash.profiles.join(" and ")} both set ${clash.service} ${clash.field}; ${clash.winner} wins because it is listed later.`);
+  if (current.error)
+    dependencies.warn(`LocalDeck: ${current.error}`);
 }
 async function cmdInit(args, dependencies) {
   const root = findPackageRoot() ?? process.cwd();
@@ -1185,10 +1268,12 @@ async function cmdRun(args, dependencies) {
     const found = project && name ? findProjectCommand(project, name) : undefined;
     if (found) {
       const remembered = await rememberProject(project, dependencies);
+      const launch = await resolveLaunch(project, remembered, dependencies);
       const selected = startupLayers(project.commands, [found.name]).flat();
-      return dependencies.runForeground(selected.map((command2, index) => toRunOptions(command2, project, remembered, {
+      return dependencies.runForeground(selected.map((command2, index) => toRunOptions(launch.effective(command2), project, remembered, {
         prefix: selected.length > 1,
         color: PALETTE[index % PALETTE.length],
+        ...launch.options,
         ...command2.name === found.name ? { stablePort: opts.port ?? found.port, upstreamPort: opts.upstream ?? found.upstream } : {}
       })));
     }

package/dist/{mcp-h8gf5pgj.js → mcp-r1ygwec0.js}

@@ -9,7 +9,7 @@ import {
   listProjectSecrets,
   redactDiagnostic,
   resolveProjectSecrets
-} from "./index-316fp4p2.js";
+} from "./index-2zg5ahh5.js";
 
 // ../../node_modules/.bun/ajv@8.20.0/node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS((exports) => {
@@ -33935,20 +33935,20 @@ function sanitize(value, secrets) {
   }
   return value;
 }
-function largestString(value) {
+function largestString(value, preserveItems = false) {
   if (!value || typeof value !== "object")
     return;
   let largest;
   for (const [key2, item] of Object.entries(value)) {
-    const candidate = typeof item === "string" && key2 !== "password" ? { text: item, replace: (text) => {
+    const candidate = typeof item === "string" && key2 !== "password" && !/cursor$/i.test(key2) && !(preserveItems && /^(id|service|serviceKey)$/i.test(key2)) ? { text: item, replace: (text) => {
       Reflect.set(value, key2, text);
-    } } : largestString(item);
+    } } : largestString(item, preserveItems);
     if (candidate && (!largest || candidate.text.length > largest.text.length))
       largest = candidate;
   }
   return largest;
 }
-function result(data, secrets, isError = false, password) {
+function result(data, secrets, isError = false, password, preserveItems = false) {
   const clean = sanitize(data, secrets);
   if (password)
     clean.password = password;
@@ -33961,7 +33961,7 @@ function result(data, secrets, isError = false, password) {
   if (fits())
     return encode3();
   clean.truncated = true;
-  if (Array.isArray(clean.items) && clean.items.length > 1) {
+  if (!preserveItems && Array.isArray(clean.items) && clean.items.length > 1) {
     const items = clean.items;
     const select = (count) => clean.retainedWindow ? items.slice(-count) : items.slice(0, count);
     let low = 1;
@@ -33977,7 +33977,7 @@ function result(data, secrets, isError = false, password) {
     clean.items = select(low);
   }
   while (!fits()) {
-    const largest = largestString(clean);
+    const largest = largestString(clean, preserveItems);
     if (!largest || largest.text.length < 100) {
       return {
         content: [{ type: "text", text: JSON.stringify({ truncated: true, error: "Result exceeds output limit; narrow the query." }) }],
@@ -34000,7 +34000,7 @@ function createMcpServer(options) {
         const connection = await options.connect();
         secrets.push(...connection.secrets ?? [], ...Object.entries(process.env).flatMap(([k, v]) => /password|secret|token|api[_-]?key|credential/i.test(k) && v ? [v] : []));
         const response = await handler(args, connection.api, secrets);
-        return result(response.data, secrets, response.data.ok === false, response.password);
+        return result(response.data, secrets, response.data.ok === false, response.password, name === "get_timeline");
       } catch (error61) {
         return result({ error: error61 instanceof Error ? error61.message : "LocalDeck request failed" }, secrets, true);
       }
@@ -34043,6 +34043,14 @@ function createMcpServer(options) {
       throw new Error("Unknown service key; use list_services");
     return { projectId, name, details, runtime };
   }
+  function profileState(details, name, runtime) {
+    const current = details?.fingerprints?.[name];
+    const running = runtime && runtime.status !== "stopped";
+    return {
+      ...running ? { profiles: runtime.profiles ?? [] } : {},
+      ...running && runtime.configFingerprint && current ? { restartNeeded: runtime.configFingerprint !== current } : {}
+    };
+  }
   tool("list_projects", "List remembered projects, their exact IDs and configuration availability.", { limit }, false, async (args, api2) => {
     const all = (await api2.projects()).filter((p) => !options.projectId || p.id === options.projectId);
     return { data: { items: all.slice(0, args.limit), truncated: all.length > args.limit } };
@@ -34063,14 +34071,34 @@ function createMcpServer(options) {
       const details = await project(api2, summary.id, secrets);
       for (const c of details.commands) {
         const serviceKey = `${summary.id}:${c.name}`;
-        items.set(serviceKey, { key: serviceKey, projectId: summary.id, projectName: summary.name, name: c.name, status: "stopped", managedBy: "daemon", configured: true, ...items.get(serviceKey) });
+        const existing = items.get(serviceKey);
+        items.set(serviceKey, { key: serviceKey, projectId: summary.id, projectName: summary.name, name: c.name, status: "stopped", managedBy: "daemon", configured: true, ...existing, ...profileState(details, c.name, existing && "upstreamPort" in existing ? existing : undefined) });
       }
     }
     return { data: { items: [...items.values()].slice(0, args.limit), truncated: items.size > args.limit, unavailable } };
   });
   tool("get_service", "Inspect a registered or configured service. Ports and counters appear after its first start.", serviceInput, false, async (args, api2, secrets) => {
     const target = await service(api2, args.serviceKey, secrets);
-    return { data: { service: target.runtime ?? { key: args.serviceKey, projectId: target.projectId, name: target.name, status: "stopped", configured: true, managedBy: "daemon" }, notice } };
+    const command = target.details?.commands.find((c) => c.name === target.name);
+    const origin = target.details?.provenance?.[target.name];
+    return { data: {
+      service: { ...target.runtime ?? { key: args.serviceKey, projectId: target.projectId, name: target.name, status: "stopped", configured: true, managedBy: "daemon" }, ...profileState(target.details, target.name, target.runtime) },
+      ...command ? { configuration: {
+        run: command.run,
+        cwd: command.cwd ?? ".",
+        activeProfiles: target.details?.activeProfiles ?? [],
+        ...origin ? { sources: { run: origin.run, cwd: origin.cwd, envNames: origin.env, secretNames: origin.secrets } } : {}
+      } } : {},
+      notice
+    } };
+  });
+  tool("list_profiles", "List a project's profiles: overlays that change how services run (command, env, secrets, cwd) on this computer. Shows which are on and any clashes. Does not start anything.", { projectId: id }, false, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.profiles(args.projectId) } };
+  });
+  tool("set_profiles", "Replace the list of profiles turned on for a project on this computer. Never starts, stops or restarts services; running services keep their settings until restarted (list_services shows restartNeeded).", { projectId: id, profiles: exports_external.array(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,40}$/i)).max(64) }, true, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.setActiveProfiles(args.projectId, args.profiles.map((name) => name.toLowerCase())) } };
   });
   tool("get_logs", "Read recent logs. Filters apply to the last 200 retained records. No live follow.", { ...serviceInput, limit, stream: exports_external.enum(["stdout", "stderr", "system"]).optional() }, false, async (args, api2, secrets) => {
     await service(api2, args.serviceKey, secrets);
@@ -34086,6 +34114,64 @@ function createMcpServer(options) {
     await service(api2, args.serviceKey, secrets);
     return { data: { serviceKey: args.serviceKey, requestId: args.requestId, response: await api2.response(args.serviceKey, args.requestId), notice } };
   });
+  const selectedServices = exports_external.array(key).min(1).max(100).optional();
+  function serviceScope(projectId, services) {
+    scope(projectId);
+    if (services?.some((serviceKey) => serviceKey.split(":")[0] !== projectId))
+      throw new Error("Selected services must belong to the requested project");
+  }
+  tool("get_timeline", "Read retained project activity, with optional exact service keys, incidents filter, text query and opaque pagination cursor. Coverage describes missing evidence; absence is not proof of recovery.", { projectId: id, services: selectedServices, filter: exports_external.enum(["all", "incidents"]).optional(), query: exports_external.string().max(200).optional(), cursor: exports_external.string().max(4096).optional(), limit }, false, async (args, api2, secrets) => {
+    serviceScope(args.projectId, args.services);
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.timeline(args.projectId, args), notice } };
+  });
+  tool("mark_baseline", "Explicitly mark current retained evidence before a debugging change. Does not start services or send requests.", { projectId: id, services: selectedServices, label: exports_external.string().max(100).optional() }, true, async (args, api2, secrets) => {
+    serviceScope(args.projectId, args.services);
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.markBaseline(args.projectId, { services: args.services, label: args.label }), notice } };
+  });
+  tool("list_baselines", "Read saved project baseline markers.", { projectId: id }, false, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.baselines(args.projectId), notice } };
+  });
+  tool("compare_baseline", "Compare retained evidence before and after a marker. Not observed again does not mean fixed; inspect coverage and insufficientEvidence.", { projectId: id, baselineId: id }, false, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.compareBaseline(args.projectId, args.baselineId), notice } };
+  });
+  tool("list_environments", "Read Git worktree environments for a project without registering or starting them.", { projectId: id }, false, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    const discovery = await api2.environments(args.projectId);
+    if (options.projectId) {
+      const environments = Array.isArray(discovery.environments) ? discovery.environments.filter((environment) => environment && typeof environment === "object" && ("projectId" in environment) && environment.projectId === options.projectId) : [];
+      return { data: { environments, notice } };
+    }
+    return { data: { ...discovery, notice } };
+  });
+  tool("register_environment", "Explicitly remember a discovered worktree environment without starting apps. Unavailable on project-restricted MCP servers because it expands project scope.", { projectId: id, environmentId: id }, true, async (args, api2, secrets) => {
+    scope(args.projectId);
+    if (options.projectId)
+      throw new Error("Environment registration expands project scope and is unavailable on a project-restricted MCP server");
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.registerEnvironment(args.projectId, args.environmentId), notice } };
+  });
+  tool("export_request", "Export a redacted reproduction of a recorded request without executing it. Inspect completeness and omitted credentials before use.", { ...serviceInput, requestId: id }, false, async (args, api2, secrets) => {
+    await service(api2, args.serviceKey, secrets);
+    return { data: { ...await api2.exportRequest(args.serviceKey, args.requestId), notice } };
+  });
+  tool("save_check", "Explicitly save a recorded GET/HEAD as a status check without running it. Credentials and arbitrary destinations cannot be supplied.", { projectId: id, ...serviceInput, requestId: id, name: exports_external.string().min(1).max(200), expectedStatus: exports_external.number().int().min(100).max(599) }, true, async (args, api2, secrets) => {
+    serviceScope(args.projectId, [args.serviceKey]);
+    await project(api2, args.projectId, secrets);
+    await service(api2, args.serviceKey, secrets);
+    return { data: { ...await api2.saveCheck(args.projectId, { serviceKey: args.serviceKey, requestId: args.requestId, name: args.name, expectedStatus: args.expectedStatus }), notice } };
+  });
+  tool("list_checks", "Read saved project status checks and their retained results without running requests.", { projectId: id }, false, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.checks(args.projectId), notice } };
+  });
+  tool("run_check", "Explicitly run one saved GET/HEAD check against its current local service. Even GET can have side effects. No automatic retries.", { projectId: id, checkId: id }, true, async (args, api2, secrets) => {
+    await project(api2, args.projectId, secrets);
+    return { data: { ...await api2.runCheck(args.projectId, args.checkId), notice } };
+  });
   for (const action of ["start", "restart"])
     tool(`${action}_service`, `${action === "start" ? "Start a configured service and its prerequisites in the background" : "Restart a daemon-owned configured service; terminal-owned services must be restarted in their terminal"}. May execute project commands.`, serviceInput, true, async (args, api2, secrets) => {
       const target = await service(api2, args.serviceKey, secrets, true);

package/dist/{update-w6vc3sdy.js → update-n1fnecgj.js}

@@ -3,7 +3,7 @@ import {
   STATE_FILE,
   assertUserRuntime,
   findDaemon
-} from "./index-316fp4p2.js";
+} from "./index-2zg5ahh5.js";
 
 // src/update.ts
 import { spawn } from "node:child_process";

package/docs/commands.md

@@ -29,11 +29,24 @@ Initialization uses the nearest `package.json` directory, or the current folder
 | `localdeck web` | Runs the configured `web` service and its transitive prerequisites in the terminal. |
 | `localdeck up` | Runs all configured services, starting each after its own prerequisites become ready. |
 | `localdeck up frontend api` | Runs services matching any supplied name or tag, plus their prerequisites. |
-| `localdeck up --profile app` | Runs the names in the saved `app` profile and their prerequisites. Additional name/tag selectors must stay within the profile. |
+| `localdeck up --profile app` | Deprecated. Runs a pre-1.6 list-style profile, now converted to the tag `app`; use `localdeck up app`. |
 | `localdeck run web` | Runs the configured `web` service; an alternative to `localdeck web`. |
 | `localdeck run api -- node server.js` | Runs a one-off command without requiring a configuration. |
 | `localdeck run api --port 4000 --upstream 8787 -- node server.js` | Reserves stable port 4000 and explicitly proxies to upstream port 8787. Omit these flags for automatic allocation and detection. |
 
+Terminal runs use the profiles turned on for the project and print them first, for example `Profiles: staging`.
+
+## Profiles
+
+| Command | What it does |
+| --- | --- |
+| `localdeck profile` | Lists the project's profiles, which services each changes, and which are on. Alias: `profiles`. |
+| `localdeck profile on staging debug` | Turns on one or more profiles for this project on this computer. |
+| `localdeck profile off debug` | Turns profiles off. |
+| `localdeck profile clear` | Turns every profile off, so services run as defined in the base configuration. |
+
+Profile commands never start, stop or restart services. Running services keep their settings until restarted. See [profiles](configuration.md#profiles).
+
 `run` accepts `-p` for `--port`, `-u` for `--upstream`, and `--port=4000`/`--upstream=8787`. Ports must be integers from 1 to 65535. Put LocalDeck options before the application command; `--` separates the two. `localdeck run web --port 4000` overrides the configured web service's stable port for that terminal run.
 
 `{port}` inside a configured command expands to the assigned **upstream** port in both terminal and dashboard launches. `$PORT` also contains that port. The stable port is held by LocalDeck, so avoid assigning it the same port your tool insists on using.
@@ -87,7 +100,7 @@ Normal startup handles clean URLs automatically where supported. Manual `forward
 | `NO_COLOR` | Disables CLI colors. |
 | `CI` | Suppresses interactive clean-URL preparation when set. |
 
-Child services receive `PORT` (upstream), `LOCALDECK_PORT` (stable/published port), and `LOCALDECK_SERVICE` (service name). HTTP services also receive `LOCALDECK_URL`, using a stable numeric localhost URL. These names and other `LOCALDECK_*` names are reserved in configuration `env`; see [environment wiring](configuration.md#profiles-and-environment-wiring).
+Child services receive `PORT` (upstream), `LOCALDECK_PORT` (stable/published port), and `LOCALDECK_SERVICE` (service name). HTTP services also receive `LOCALDECK_URL`, using a stable numeric localhost URL. These names and other `LOCALDECK_*` names are reserved in configuration `env`; see [environment wiring](configuration.md#environment-wiring).
 
 ## MCP client connection
 

package/docs/configuration.md

@@ -47,22 +47,58 @@ For Docker Compose databases, set `upstream` to the host-published database port
 
 Native database presets are `ready: "postgres"` (requires `pg_isready`) and `ready: "redis"` (requires `redis-cli`). The matching `serviceType` selects this check by default. Compose checks use tools inside the named container: `{ "type": "compose", "service": "redis", "engine": "redis" }`. Compose service names and engines are validated; the host still needs Docker. **Listening** means TCP connections are accepted; **ready** means the configured readiness contract passed. Custom HTTP/command checks also run for services with no dependents.
 
-### Profiles and environment wiring
+### Environment wiring
 
-Use the object format when defining startup profiles:
+Use `env` with `{service:NAME:url}` or `{service:NAME:port}` to hand one service the address of another it starts after:
 
 ```json
 {
   "services": [
     { "name": "api", "run": "npm run api", "ready": "/health" },
-    { "name": "web", "run": "npm run web", "after": "api", "env": { "PUBLIC_API_URL": "{service:api:url}" } },
-    { "name": "docs", "run": "npm run docs" }
+    { "name": "web", "run": "npm run web", "after": "api", "env": { "PUBLIC_API_URL": "{service:api:url}" } }
+  ]
+}
+```
+
+Variable names such as `PUBLIC_API_URL` must match what your framework actually reads; LocalDeck does not rewrite application code or `.env` files.
+
+### Profiles
+
+A profile changes how services run without renaming them. `web` stays `web`, with the same port, link and startup order, while a `staging` profile swaps its command and environment. With no profile on, services run exactly as defined above; that is your local setup.
+
+```json
+{
+  "services": [
+    { "name": "api", "run": "npm run api", "env": { "LOG_LEVEL": "info" } },
+    { "name": "web", "run": "npm run dev", "after": "api", "env": { "API_URL": "{service:api:url}" } }
   ],
-  "profiles": { "app": ["web"], "everything": ["web", "docs"] }
+  "profiles": {
+    "staging": {
+      "description": "Frontend talks to the staging API",
+      "services": {
+        "web": {
+          "run": "npm run dev:staging",
+          "env": { "API_URL": "https://api.staging.example.com" },
+          "secrets": ["STAGING_TOKEN"]
+        }
+      }
+    },
+    "debug": {
+      "description": "Attach the Node inspector to the API",
+      "services": { "api": { "env": { "NODE_OPTIONS": "--inspect", "LOG_LEVEL": "debug" } } }
+    }
+  }
 }
 ```
 
-`localdeck up --profile app` starts web and its API prerequisite. Profiles are also selectable in the dashboard. Variable names such as `PUBLIC_API_URL` must match what your framework actually reads; LocalDeck does not rewrite application code or `.env` files.
+- A profile may change a service's `run`, `cwd`, `env` and `secrets`. Name, ports, `after`, readiness and service type always come from the base service, so links and startup order never change.
+- `env` merges key by key: `debug` above keeps `api`'s other variables and replaces `LOG_LEVEL`. `secrets` are added to the base list. The same reserved-name rules apply as for base services.
+- Several profiles can be on at once. They apply in the order they are listed in the file. When two of them set the same command, directory or variable, the one listed later wins, and the dashboard and CLI say so.
+- Which profiles are on is stored **on this computer only**, in `~/.localdeck/projects.json` (or `$LOCALDECK_HOME`). It is never written to `.localdeck`, so turning on `staging` does not change the file for your teammates.
+- Turn profiles on with `localdeck profile on staging`, the Profiles menu at the top of the project page, or the MCP `set_profiles` tool. Switching never starts, stops or restarts anything. A running service keeps its settings and is marked **Restart to apply** until you restart it.
+- Profile names use lowercase letters, numbers, `-` and `_`. An unknown service, or a field a profile cannot change, is rejected when the file loads.
+
+**Older list-style profiles.** Before 1.6, `"profiles": { "app": ["web"] }` named a group of services to start. That form still loads: each listed service is tagged `app`, so run the group with `localdeck up app`. `localdeck up --profile app` keeps working for now with a notice. A file cannot mix service lists and profile objects under `profiles`.
 
 Keys are forgiving (`command`/`value`/`cmd` work too), and `{ "web": "npm run dev" }` shorthand is accepted. LocalDeck looks for `.localdeck`, `.localdeck.json` or `localdeck.json`, walking up from the current folder, so it works from anywhere inside a monorepo.