@oqtopus-team/pi-qdash 0.1.9 → 0.1.10-beta.12

package/README.md

@@ -19,6 +19,7 @@ It uses [`@oqtopus-team/qdash-client`](https://www.npmjs.com/package/@oqtopus-te
 - **Read-only investigation**: dedicated tools to inspect chips, qubits, couplings, calibration task results, task knowledge (`qdash_get_task_knowledge`), executions, issues, and Forum posts. Secrets are redacted from tool output.
 - **Dashboards and insights**: compact dashboards, triage overviews, target-level incident reports, degradation reports, and wiring insights.
 - **Agent calibration workflow**: create agent sessions, submit and track agent actions, and commit/apply calibration candidates. Write operations are approval-gated.
+- **Calibration pipelines**: compose a declarative pipeline spec from QDash's step catalog (`qdash_get_pipeline_catalog`), validate it (`qdash_plan_pipeline`), and run it as one execution (`qdash_run_pipeline`, approval-gated).
 - **Figures**: fetch calibration PNG/JSON figures and render them in the interactive TUI.
 - **Generic timeseries comparison**: inspect and align arbitrary QDash parameters/targets with explicitly mapped local CSV sensor columns, reuse schema-validated investigation presets, and report correlations plus optional shared-period/phase evidence without hard-coded metrics or schemas.
 - **Forum integration**: read Forum posts, publish task-result evidence, and upload locally generated analysis images to replies.
@@ -47,6 +48,14 @@ Requires Node.js 20 or later and pi v0.74.0 or later. The extension tracks
 `@oqtopus-team/qdash-client` 1.9.x and uses its authenticated high-level and
 generated API clients.
 
+Every push to `main` also publishes a prerelease under the `beta` dist-tag
+(the next patch version with a `-beta.<build>` suffix, for example
+`0.1.10-beta.42`). Use it to try tools that are merged but not yet released:
+
+```bash
+pi install npm:@oqtopus-team/pi-qdash@beta
+```
+
 ## Quick Start
 
 In interactive pi, set up the session context first:

package/extensions/lib/results.ts

@@ -28,3 +28,26 @@ export function toTextToolResult(text: string, data: unknown, details: Record<st
     details: { ...details, data: safeData },
   };
 }
+
+/**
+ * Result of a tool that fetched a figure: the text summary plus, for an image,
+ * the image itself as model-visible content. Without the image block a
+ * vision model only reads that a figure exists; with it, it can judge the
+ * curve. Non-image figures (JSON) keep a text-only result.
+ */
+export function toFigureToolResult(
+  text: string,
+  figure: { base64?: string; mediaType: string },
+  data: unknown,
+  details: Record<string, unknown> = {},
+) {
+  const result = toTextToolResult(text, data, details);
+  if (!figure.base64 || !figure.mediaType.startsWith("image/")) return result;
+  return {
+    ...result,
+    content: [
+      ...result.content,
+      { type: "image" as const, data: figure.base64, mimeType: figure.mediaType },
+    ],
+  };
+}

package/extensions/lib/write-gate.ts

@@ -11,6 +11,7 @@ const WRITE_TOOL_NAMES = new Set([
   "qdash_update_forum_post",
   "qdash_create_forum_evidence_reply",
   "qdash_create_forum_image_reply",
+  "qdash_run_pipeline",
 ]);
 
 export function installQDashWriteGate(pi: ExtensionAPI): void {

package/extensions/qdash.ts

@@ -21,10 +21,11 @@ import { forumDetailComponent, forumDetailLines, forumListLines, forumPostTitle,
 import { investigationContextSummary, validateInvestigationContext, type TimeseriesInvestigationContext } from "./lib/investigation-context.js";
 import { qdashObjectLinks, qdashWebBaseUrl, qdashWebUrl, safeConfig, withQDashLinks } from "./lib/links.js";
 import { arrayFromPayload, compactItems, firstNumber, firstString, formatItem, payloadTotal, statusIcon } from "./lib/payload.js";
-import { toTextToolResult, toToolResult } from "./lib/results.js";
+import { toFigureToolResult, toTextToolResult, toToolResult } from "./lib/results.js";
 import { ansi, boxLinesToWidth, boxed, formatNumber, textComponent } from "./lib/render.js";
 import { plotSeriesLines, timeseriesPlotComponent, timeseriesPoints } from "./lib/timeseries-plot.js";
 import { installQDashWriteGate } from "./lib/write-gate.js";
+import { registerCalibrationPipelineTools } from "./tools/calibration-pipeline.js";
 import { registerTaskKnowledgeTool } from "./tools/task-knowledge.js";
 import { registerTimeseriesComparisonTool } from "./tools/timeseries.js";
 import { analyzeWiringMarkdown, wiringInsightLines, type WiringInsights } from "./lib/wiring-analysis.js";
@@ -1532,6 +1533,10 @@ async function executeQuery(params: QDashQueryParams) {
 export default function qdashExtension(pi: ExtensionAPI) {
   installQDashWriteGate(pi);
   registerTaskKnowledgeTool(pi, { makeClient });
+  registerCalibrationPipelineTools(pi, {
+    makeClient,
+    resolveChipId: (client, chipId) => defaultChipId(client as QDashClient, chipId),
+  });
 
   pi.registerTool({
     name: "qdash_config_info",
@@ -2538,7 +2543,7 @@ export default function qdashExtension(pi: ExtensionAPI) {
       const details: FigureDetails = { tool: "qdash_recent_calibration_figure", taskId, path: file.path ?? "", mediaType, sizeBytes: bytes.byteLength, figurePaths: file.figurePaths ?? [], jsonFigurePaths: file.jsonFigurePaths ?? [] };
       if (mediaType.startsWith("image/")) details.base64 = bytes.toString("base64");
       else details.text = bytes.toString("utf8");
-      return toTextToolResult(figureResultText(details), { task, selectedPath: details.path }, details);
+      return toFigureToolResult(figureResultText(details), details, { task, selectedPath: details.path }, details);
     },
     renderResult(result, _options, theme) {
       return figureComponent(result.details as unknown as FigureDetails, theme);
@@ -2558,7 +2563,7 @@ export default function qdashExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; path: string }) {
       const client = await makeClient(params);
       const details = await fetchFigureDetails(client, params.path);
-      return toTextToolResult(figureResultText(details), { path: params.path }, details);
+      return toFigureToolResult(figureResultText(details), details, { path: params.path }, details);
     },
     renderResult(result, _options, theme) {
       return figureComponent(result.details as unknown as FigureDetails, theme);
@@ -2595,7 +2600,7 @@ export default function qdashExtension(pi: ExtensionAPI) {
         };
         if (mediaType.startsWith("image/")) details.base64 = bytes.toString("base64");
         else details.text = bytes.toString("utf8");
-        return toTextToolResult(figureResultText(details), { taskId: params.taskId, figurePaths: details.figurePaths, jsonFigurePaths: details.jsonFigurePaths, selectedPath: details.path }, details);
+        return toFigureToolResult(figureResultText(details), details, { taskId: params.taskId, figurePaths: details.figurePaths, jsonFigurePaths: details.jsonFigurePaths, selectedPath: details.path }, details);
       } catch (error) {
         return toTextToolResult(boxed("QDash Task Figures", [
           `task ${params.taskId}`,

package/extensions/tools/calibration-pipeline.ts

@@ -0,0 +1,303 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { QDashClient } from "@oqtopus-team/qdash-client";
+import { Type } from "typebox";
+
+import { toTextToolResult } from "../lib/results.js";
+
+/**
+ * Declarative calibration pipelines.
+ *
+ * The agent writes a CalibrationPipelineSpec (targets, ordered steps, run
+ * parameters); QDash validates it against the chip, backend, and task catalog,
+ * then runs it as one execution. The spec cannot reference code, only the
+ * Step classes and task names QDash exposes, so QDash owns the validation and
+ * these tools only relay it. The spec schema is deliberately not restated
+ * here: `qdash_get_pipeline_catalog` returns QDash's own JSON schema.
+ */
+
+type ConnectionParams = { profile?: string; configPath?: string; useEnv?: boolean };
+
+export type PipelineProblem = { path: string; message: string };
+
+export type ResolvedPipelineStep = {
+  index: number;
+  type: string;
+  name: string;
+  kind: string;
+  tasks: string[];
+};
+
+export type PipelineValidation = {
+  valid: boolean;
+  problems?: PipelineProblem[];
+  backend_name: string;
+  spec?: Record<string, unknown> | null;
+  targets?: { qids?: string[]; mux_ids?: number[]; exclude_qids?: string[] } | null;
+  steps?: ResolvedPipelineStep[];
+  task_run_count?: number;
+};
+
+export type PipelineExecution = {
+  execution_id: string;
+  flow_run_id: string;
+  flow_run_url: string;
+  qdash_ui_url: string;
+  message: string;
+  steps?: ResolvedPipelineStep[];
+  targets?: PipelineValidation["targets"];
+};
+
+export type PipelineCatalog = {
+  backend_name: string;
+  step_types: Array<{
+    type: string;
+    kind: string;
+    description: string;
+    requires: string[];
+    provides: string[];
+    task_scope?: string | null;
+    default_tasks: string[];
+  }>;
+  one_qubit_modes: string[];
+  tasks: Record<string, string[]>;
+  spec_schema: Record<string, unknown>;
+  example?: Record<string, unknown>;
+};
+
+type PipelineRequest = { chip_id: string; spec: Record<string, unknown>; backend_name?: string };
+
+/** The slice of QDashClient these tools use; tests pass a stub. */
+export type PipelineClient = {
+  api: {
+    getCalibrationPipelineCatalog(params?: { backend_name?: string }): Promise<unknown>;
+    validateCalibrationPipeline(request: PipelineRequest): Promise<unknown>;
+    executeCalibrationPipeline(request: PipelineRequest): Promise<unknown>;
+  };
+};
+
+export type CalibrationPipelineDependencies = {
+  makeClient(params: ConnectionParams): Promise<PipelineClient>;
+  /** The chip to run on: the explicit id, else the session/default chip. */
+  resolveChipId(client: PipelineClient, chipId?: string): Promise<string>;
+};
+
+const TASK_PREVIEW = 8;
+
+function describeTargets(targets: PipelineValidation["targets"]): string {
+  if (!targets) return "targets unknown";
+  if (targets.qids?.length) return `qubits ${targets.qids.join(", ")}`;
+  if (targets.mux_ids?.length) {
+    const base = `MUX ${targets.mux_ids.join(", ")}`;
+    return targets.exclude_qids?.length ? `${base} (excluding ${targets.exclude_qids.join(", ")})` : base;
+  }
+  return "targets unknown";
+}
+
+function taskList(tasks: string[]): string {
+  if (tasks.length === 0) return "no tasks (transform)";
+  const shown = tasks.slice(0, TASK_PREVIEW).join(", ");
+  const rest = tasks.length - TASK_PREVIEW;
+  return rest > 0 ? `${tasks.length} tasks: ${shown}, +${rest} more` : `${tasks.length} task${tasks.length === 1 ? "" : "s"}: ${shown}`;
+}
+
+export function stepLines(steps: ResolvedPipelineStep[] | undefined): string[] {
+  if (!steps?.length) return ["- (no steps resolved)"];
+  return steps.map((step) => {
+    const label = step.name === step.type ? step.type : `${step.name} (${step.type})`;
+    return `${step.index}. ${label} — ${taskList(step.tasks)}`;
+  });
+}
+
+export function problemLines(problems: PipelineProblem[] | undefined): string[] {
+  if (!problems?.length) return [];
+  return problems.map((problem) => `- ${problem.path}: ${problem.message}`);
+}
+
+/** Text shown for a validated (or rejected) plan. */
+export function formatPipelinePlan(result: PipelineValidation, chipId: string): string {
+  const name = typeof result.spec?.name === "string" ? result.spec.name : undefined;
+  const header = `Pipeline${name ? ` '${name}'` : ""} on chip ${chipId} (backend ${result.backend_name})`;
+  const problems = problemLines(result.problems);
+  const lines = [header, `Targets: ${describeTargets(result.targets)}`, ""];
+  if (result.valid) {
+    lines.push(`Valid. ${result.task_run_count ?? 0} task runs per target.`);
+  } else {
+    lines.push(`Not valid: ${problems.length} problem${problems.length === 1 ? "" : "s"}. Fix the spec and validate again.`, ...problems);
+  }
+  if (result.steps?.length) lines.push("", "Steps:", ...stepLines(result.steps));
+  return lines.join("\n");
+}
+
+export function formatPipelineExecution(result: PipelineExecution, chipId: string): string {
+  const stepCount = result.steps?.length ?? 0;
+  const taskRuns = (result.steps ?? []).reduce((count, step) => count + step.tasks.length, 0);
+  return [
+    `Started: ${result.message}`,
+    `execution_id ${result.execution_id}`,
+    `chip ${chipId}, ${describeTargets(result.targets)}, ${stepCount} step${stepCount === 1 ? "" : "s"}, ${taskRuns} task runs per target`,
+    `qdash ${result.qdash_ui_url}`,
+    `prefect ${result.flow_run_url}`,
+    "",
+    "Use qdash_wait_execution with this execution_id to follow it to completion.",
+  ].join("\n");
+}
+
+export function formatPipelineCatalog(catalog: PipelineCatalog): string {
+  const lines = [`Calibration pipeline catalog (backend ${catalog.backend_name})`, "", "Step types:"];
+  for (const step of catalog.step_types) {
+    const needs = step.requires.length ? ` needs ${step.requires.join(" or ")};` : "";
+    const scope = step.task_scope ? ` ${step.task_scope} tasks` : "";
+    const defaults = step.default_tasks.length ? `; default ${step.default_tasks.length} tasks` : "";
+    lines.push(`- ${step.type} [${step.kind}${scope}]: ${step.description}${needs}${defaults}`);
+  }
+  lines.push("", `One-qubit modes: ${catalog.one_qubit_modes.join(", ")}`, "", "Tasks by type:");
+  for (const [taskType, names] of Object.entries(catalog.tasks)) {
+    lines.push(`- ${taskType} (${names.length}): ${names.join(", ")}`);
+  }
+  lines.push(
+    "",
+    "Targets are either {qids: [...]} or {mux_ids: [...], exclude_qids?: [...]}.",
+    "The full spec JSON schema is in details.data.spec_schema; validate with qdash_plan_pipeline.",
+  );
+  return lines.join("\n");
+}
+
+/** Problems carried by a 422 from /calibration-pipelines/execute, if that is what `error` is. */
+export function problemsFromError(error: unknown): PipelineProblem[] | null {
+  if (!error || typeof error !== "object") return null;
+  const payload = (error as { payload?: unknown }).payload;
+  const detail = payload && typeof payload === "object" ? (payload as { detail?: unknown }).detail : undefined;
+  const problems = detail && typeof detail === "object" ? (detail as { problems?: unknown }).problems : undefined;
+  if (!Array.isArray(problems)) return null;
+  return problems
+    .filter((item): item is PipelineProblem => Boolean(item) && typeof item === "object" && typeof (item as PipelineProblem).path === "string")
+    .map((item) => ({ path: item.path, message: String(item.message ?? "") }));
+}
+
+function statusOf(error: unknown): number | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const value = error as { statusCode?: unknown; status?: unknown };
+  return typeof value.statusCode === "number" ? value.statusCode : typeof value.status === "number" ? value.status : undefined;
+}
+
+const connectionParams = {
+  profile: Type.Optional(Type.String({ description: "QDash profile name. Defaults to env when QDASH_BASE_URL is set, otherwise 'default'." })),
+  configPath: Type.Optional(Type.String({ description: "Optional path to qdash config.ini." })),
+  useEnv: Type.Optional(Type.Boolean({ description: "Force QDASH_* environment variables instead of a profile." })),
+};
+
+// Loose on purpose: QDash validates the spec and reports problems with paths,
+// and a union-heavy schema here would be ignored by vLLM guided decoding anyway.
+const specParam = Type.Object({}, {
+  additionalProperties: true,
+  description: "CalibrationPipelineSpec: {name?, targets: {qids} | {mux_ids, exclude_qids?}, steps: [{type, ...}], task_run_parameters?, default_run_parameters?, tags?}. Get step types and tasks from qdash_get_pipeline_catalog.",
+});
+
+export function registerCalibrationPipelineTools(pi: Pick<ExtensionAPI, "registerTool">, deps: CalibrationPipelineDependencies): void {
+  pi.registerTool({
+    name: "qdash_get_pipeline_catalog",
+    label: "QDash Pipeline Catalog",
+    description: "List the step types, task names, and spec schema for composing a calibration pipeline. Read-only. Call this before writing a pipeline spec.",
+    promptSnippet: "Look up the step types and tasks available for a QDash calibration pipeline",
+    promptGuidelines: [
+      "Use qdash_get_pipeline_catalog before composing a pipeline spec; use only the step types and task names it lists.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      backendName: Type.Optional(Type.String({ description: "Backend to list tasks for. Defaults to the configured backend." })),
+    }),
+    async execute(_toolCallId, params: ConnectionParams & { backendName?: string }) {
+      const client = await deps.makeClient(params);
+      const catalog = (await client.api.getCalibrationPipelineCatalog(
+        params.backendName ? { backend_name: params.backendName } : undefined,
+      )) as PipelineCatalog;
+      return toTextToolResult(formatPipelineCatalog(catalog), catalog, { tool: "qdash_get_pipeline_catalog", backendName: catalog.backend_name });
+    },
+  });
+
+  pi.registerTool({
+    name: "qdash_plan_pipeline",
+    label: "QDash Plan Pipeline",
+    description: "Check a calibration pipeline spec against QDash without running it: returns problems with paths into the spec and the exact tasks each step will run. Read-only. Call this before qdash_run_pipeline.",
+    promptSnippet: "Validate a QDash calibration pipeline spec and preview the tasks it will run",
+    promptGuidelines: [
+      "Use qdash_plan_pipeline after composing a spec and after every edit; a spec with problems is not an error, fix it and plan again.",
+      "Show the user the resolved steps and task counts before running.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      chipId: Type.Optional(Type.String({ description: "Chip to run on. Defaults to the session or default chip." })),
+      spec: specParam,
+      backendName: Type.Optional(Type.String({ description: "Defaults to the configured backend." })),
+    }),
+    async execute(_toolCallId, params: ConnectionParams & { chipId?: string; spec: Record<string, unknown>; backendName?: string }) {
+      const client = await deps.makeClient(params);
+      const chipId = await deps.resolveChipId(client, params.chipId);
+      const result = (await client.api.validateCalibrationPipeline({
+        chip_id: chipId,
+        spec: params.spec,
+        ...(params.backendName ? { backend_name: params.backendName } : {}),
+      })) as PipelineValidation;
+      return toTextToolResult(formatPipelinePlan(result, chipId), result, {
+        tool: "qdash_plan_pipeline",
+        chipId,
+        valid: result.valid,
+        problemCount: result.problems?.length ?? 0,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "qdash_run_pipeline",
+    label: "QDash Run Pipeline",
+    description: "Run a calibration pipeline spec as one QDash execution. Confirmation-gated write operation. Validate with qdash_plan_pipeline first; the spec runs exactly as validated.",
+    promptSnippet: "Run a validated QDash calibration pipeline spec",
+    promptGuidelines: [
+      "Use qdash_run_pipeline only for a spec that qdash_plan_pipeline reported valid.",
+      "After it starts, follow the execution with qdash_wait_execution and summarize failed targets.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      chipId: Type.String({ description: "Chip to run on." }),
+      spec: specParam,
+      backendName: Type.Optional(Type.String({ description: "Defaults to the configured backend." })),
+      confirmWrite: Type.Optional(Type.Boolean({ description: "Required for non-interactive execution. Set true only after explicit user confirmation." })),
+    }),
+    async execute(_toolCallId, params: ConnectionParams & { chipId: string; spec: Record<string, unknown>; backendName?: string; confirmWrite?: boolean }, _signal, _onUpdate, ctx) {
+      if (!params.confirmWrite) {
+        if (!ctx.hasUI || !(await ctx.ui.confirm("Run QDash calibration pipeline?", `This starts a calibration execution on chip ${params.chipId}.`))) {
+          throw new Error("qdash_run_pipeline requires explicit confirmation");
+        }
+      }
+      const client = await deps.makeClient(params);
+      try {
+        const result = (await client.api.executeCalibrationPipeline({
+          chip_id: params.chipId,
+          spec: params.spec,
+          ...(params.backendName ? { backend_name: params.backendName } : {}),
+        })) as PipelineExecution;
+        return toTextToolResult(formatPipelineExecution(result, params.chipId), result, {
+          tool: "qdash_run_pipeline",
+          chipId: params.chipId,
+          executionId: result.execution_id,
+          started: true,
+        });
+      } catch (error) {
+        const problems = problemsFromError(error);
+        if (problems) {
+          const text = [
+            `QDash rejected the pipeline spec (${problems.length} problem${problems.length === 1 ? "" : "s"}). Nothing was started.`,
+            ...problemLines(problems),
+            "",
+            "Fix the spec, confirm it with qdash_plan_pipeline, then run again.",
+          ].join("\n");
+          return toTextToolResult(text, { problems }, { tool: "qdash_run_pipeline", chipId: params.chipId, started: false, problemCount: problems.length });
+        }
+        if (statusOf(error) === 503) {
+          throw new Error("QDash cannot run pipelines right now: the worker has not registered the calibration-pipeline deployment. Ask an operator to restart the worker, then try again.");
+        }
+        throw error;
+      }
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.9",
+  "version": "0.1.10-beta.12",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@oqtopus-team/qdash-client": "^1.9.11"
+    "@oqtopus-team/qdash-client": "1.9.21-beta.168"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/skills/qdash/SKILL.md

@@ -24,6 +24,7 @@ Prefer the dedicated tool that matches the question. Use `qdash_query` only as a
    - `qdash_get_task_knowledge` — interpret a task's purpose, expected result, failure modes, and check questions
    - `qdash_list_issues` — inspect tracked issues
    - `qdash_list_flows`, `qdash_get_flow` — list or inspect calibration flows
+   - `qdash_get_pipeline_catalog`, `qdash_plan_pipeline` — compose and check a calibration pipeline spec before running it
    - `qdash_list_executions`, `qdash_get_execution`, `qdash_wait_execution`, `qdash_compare_executions` — inspect, await, or compare executions
    - `qdash_list_ai_reviews`, `qdash_get_provenance_stats` — inspect AI reviews or provenance status
    - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies` — inspect Forum context
@@ -40,12 +41,33 @@ Prefer the dedicated tool that matches the question. Use `qdash_query` only as a
    - `qdash_apply_agent_candidate_commit` — apply a reviewed candidate commit
    - `qdash_create_forum_post`, `qdash_update_forum_post` — create or update Forum content
    - `qdash_create_forum_evidence_reply`, `qdash_create_forum_image_reply` — publish previously reviewed evidence replies
+   - `qdash_run_pipeline` — run a validated pipeline spec as one execution
 4. Agent workflow state tools:
    - `qdash_get_agent_session`, `qdash_get_agent_action`, `qdash_list_agent_actions`, `qdash_wait_agent_action` — inspect agent workflow state
    - `qdash_list_agent_action_candidates`, `qdash_get_agent_candidate_commit`, `qdash_wait_agent_candidate_apply` — inspect candidates and apply status
 5. `qdash_query` — fallback for read-only operations without a dedicated tool.
 6. `qdash_raw_get` — last-resort read-only GET for an uncovered endpoint.
 
+## Composing a calibration pipeline
+
+A calibration pipeline spec is a JSON description of one calibration run: targets, an ordered list of steps, and run parameters. QDash validates it against the chip, backend, and task catalog and runs it as one execution. The spec can only name the step types and tasks QDash exposes; it cannot contain code.
+
+Workflow:
+
+1. `qdash_get_pipeline_catalog` — read the step types (with what each needs from an earlier step and its default task list), the one-qubit modes, and the task names by type. Use only names from this catalog.
+2. Turn the request into steps. Start from the catalog defaults and the flow templates (`qdash_query` with `flow_templates`, then `flow_template` for one template's task list): `OneQubitCheck` and `OneQubitFineTune` carry the standard one-qubit sequences, `TwoQubitCalibration` the two-qubit chain. Use `CustomOneQubit` / `CustomTwoQubit` only where the user wants a different task list, and keep the task order the templates use.
+3. `qdash_plan_pipeline` — validate. A result with problems is not an error: each problem carries a path into the spec (`steps[2].tasks[0]`, `targets.qids[1]`); fix it and plan again until it is valid.
+4. Show the user the resolved steps and task counts from the plan, then `qdash_run_pipeline` with the same `chipId` and `spec`. The execution is confirmation-gated.
+5. `qdash_wait_execution` with the returned `execution_id`, then summarize which targets passed and which failed, and read `qdash_get_task_knowledge` for any task whose result needs interpretation.
+
+Rules:
+
+- Targets are either `qids` or `mux_ids` (with optional `exclude_qids`), never both. Prefer MUX targets for more than a few qubits; hardware scheduling works per MUX.
+- `FilterByStatus` and `FilterByMetric` are only valid after a one-qubit step. Put a filter before any two-qubit step.
+- Put values into `task_run_parameters` only when the user asked for them; otherwise leave QDash's defaults.
+- A pipeline takes the project execution lock. Check `qdash_list_executions` for a running execution before starting one.
+- Prefer short pipelines (one or two steps) when the next step depends on the result: run, inspect results and figures, then compose the next spec. Calibrated parameters persist in QDash between executions, so a later spec continues from the earlier one. Retries and branches are your decision between executions, not something the spec expresses.
+
 ## Session context
 
 When running in pi CLI, use `qdash_config_info` if the profile or non-secret connection settings are unclear.