@tenderprompt/cli 0.1.15 → 0.1.17

package/dist/index.js

@@ -11,7 +11,7 @@ const CLI_PACKAGE_NAME = "@tenderprompt/cli";
 const UNKNOWN_CLI_VERSION = "0.0.0";
 const RECOMMENDED_TENDER_PROMPT_SKILL = {
     name: "tender-prompt",
-    version: "0.1.1",
+    version: "0.1.4",
     source: "git@github.com:tenderprompt/skills.git",
     path: "skills/tender-prompt/SKILL.md",
     updateHint: "Refresh the tender-prompt skill from git@github.com:tenderprompt/skills.git when the local skill version is older.",
@@ -82,6 +82,10 @@ Commands:
   tender auth login --device
                              Authorize this machine with a browser-approved device flow
   tender auth status         Show whether a Tender API token is available
+  tender playbooks list      List remote Tender Prompt playbook metadata
+  tender playbooks get <id>  Fetch one remote playbook body on demand
+  tender playbooks file <id> --path <path>
+                             Fetch one playbook reference file on demand
   tender app list            List Tender App records visible to the current token
   tender app create --name <name>
                              Create a new Tender App in the current account
@@ -134,10 +138,14 @@ Examples:
   tender capabilities --json
   tender auth login --device --profile edit-preview --artifact artifact_123 --ttl 7d
   tender auth status --json
+  tender playbooks list --json
+  tender playbooks get recharge-bundle-builder --json
+  tender playbooks file recharge-bundle-builder --path references/recharge-payloads.md --json
   tender app list --json
   tender app create --name "Exit Intent Widget" --json
+  tender app create --name "Exit Intent Widget" --init --dir ./widget --preview --json
   tender app update artifact_123 --name "Sale Widget" --json
-  tender app init artifact_123 --dir ./widget --json
+  tender app init artifact_123 --dir ./widget --preview --json
   tender app validate artifact_123 --json
   tender app build artifact_123 --commit $(git rev-parse HEAD) --json
   tender app preview artifact_123 --commit $(git rev-parse HEAD) --stream --json
@@ -202,13 +210,56 @@ Examples:
   tender auth status
   tender auth status --profile publish --json`;
 }
+function playbooksHelp() {
+    return `Usage: tender playbooks <command> [options]
+
+Commands:
+  tender playbooks list
+                             List remote playbook metadata only
+  tender playbooks get <playbook-id>
+                             Fetch one playbook body and reference index
+  tender playbooks file <playbook-id> --path <path>
+                             Fetch one playbook reference file
+
+Examples:
+  tender playbooks list --json
+  tender playbooks get recharge-bundle-builder --json
+  tender playbooks file recharge-bundle-builder --path references/recharge-payloads.md --json`;
+}
+function playbooksListHelp() {
+    return `Usage: tender playbooks list [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+
+Lists compact metadata for all remote Tender Prompt playbooks. This command
+does not write playbooks to disk.
+
+Examples:
+  tender playbooks list --json`;
+}
+function playbooksGetHelp() {
+    return `Usage: tender playbooks get <playbook-id> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+
+Fetches one remote playbook body plus a reference-file index. This command
+prints session-only context and does not write to the checkout.
+
+Examples:
+  tender playbooks get recharge-bundle-builder --json`;
+}
+function playbooksFileHelp() {
+    return `Usage: tender playbooks file <playbook-id> --path <references/file.md> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+
+Fetches one playbook reference file. Paths are limited to references/*.md.
+This command does not write playbooks to disk.
+
+Examples:
+  tender playbooks file recharge-bundle-builder --path references/recharge-payloads.md --json`;
+}
 function appHelp() {
     return `Usage: tender app <command> [options]
 
 Commands:
   tender app list            List Tender App records visible to the current token
   tender app create --name <name>
-                             Create a new Tender App in the current account
+                             Create a new Tender App, optionally initialize source, and preview
   tender app update <app-id> --name <name>
                              Update app metadata
   tender app init <app-id>
@@ -223,6 +274,8 @@ Commands:
                              Show preview job status by latest, commit, or job id
   tender app preview watch <app-id>
                              Replay lifecycle events by latest, commit, or job id
+  tender app agent heartbeat <app-id>
+                             Send a concise agent status update to the workspace
   tender app publish <app-id>
                              Publish after dry-run or explicit confirmation
   tender app publish status <app-id>
@@ -258,7 +311,7 @@ Commands:
   tender app db query <app-id> --env <preview|published> --sql <sql>
                              Run one read-only app database query
   tender app context fetch <app-id>
-                             Fetch AGENTS.md, skills, and Tender App scaffold files
+                             Fetch AGENTS.md, skills, and Tender project context
   tender app context status <app-id>
                              Show managed context freshness for a checkout
   tender app context refresh <app-id>
@@ -276,13 +329,15 @@ Commands:
 Examples:
   tender app list --json
   tender app create --name "Exit Intent Widget" --json
+  tender app create --name "Exit Intent Widget" --init --dir ./widget --preview --json
   tender app update artifact_123 --name "Sale Widget" --json
-  tender app init artifact_123 --dir ./widget --json
+  tender app init artifact_123 --dir ./widget --preview --json
   tender app validate artifact_123 --json
   tender app build artifact_123 --commit $(git rev-parse HEAD) --json
   tender app preview artifact_123 --commit $(git rev-parse HEAD) --stream --json
   tender app preview status artifact_123 --commit $(git rev-parse HEAD) --json
   tender app preview watch artifact_123 --job job_123 --stream --json
+  tender app agent heartbeat artifact_123 --source codex --status working --phase editing --summary "Updating the result screen" --json
   tender app publish artifact_123 --dry-run --json
   tender app publish status artifact_123 --job job_123 --json
   tender app publish watch artifact_123 --job job_123 --stream --json
@@ -561,10 +616,18 @@ Examples:
   TENDER_API_TOKEN=tpat_... tender app list --base-url https://app.tenderprompt.com --json`;
 }
 function artifactsCreateHelp() {
-    return `Usage: tender app create --name <name> [--target-pack <id>] [--target-pack-version <version>] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+    return `Usage: tender app create --name <name> [--init] [--dir <path>] [--scaffold <server-backed|none>] [--preview] [--target-pack <id>] [--target-pack-version <version>] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
 Options:
   --name <name>                  App name.
+  --init                         Initialize a local checkout after creating the app.
+  --dir <path>                   Local checkout directory for --init. Defaults to current directory.
+  --scaffold <value>             API-derived scaffold for empty app source: server-backed or none. Defaults to server-backed.
+  --no-scaffold                  Alias for --scaffold none.
+  --preview                      After --init writes and pushes initial source, request a preview build.
+  --remote <name>                Git remote name for --init. Defaults to tender.
+  --ttl <value>                  Deprecated for Tender-hosted Git remotes; accepted for compatibility.
+  --force                        Overwrite conflicting managed files during --init.
   --target-pack <id>             Target pack id. Defaults to the API default.
   --target-pack-version <value>  Target pack version. Defaults to the API default.
   --base-url <url>               Tender base URL. Defaults to TENDER_BASE_URL, saved profile base URL, or https://app.tenderprompt.com.
@@ -574,6 +637,7 @@ Options:
 
 Examples:
   tender app create --name "Exit Intent Widget" --json
+  tender app create --name "Exit Intent Widget" --init --dir ./widget --preview --json
   tender app create --name "Exit Intent Widget" --profile account --json`;
 }
 function artifactsUpdateHelp() {
@@ -590,11 +654,14 @@ Examples:
   tender app update artifact_123 --name "Sale Widget" --json`;
 }
 function artifactsInitHelp() {
-    return `Usage: tender app init <app-id> [--dir <path>] [--remote <name>] [--base-url <url>] [--token <token>] [--profile <name>] [--ttl <7d|14d|30d>] [--dry-run] [--force] [--json]
+    return `Usage: tender app init <app-id> [--dir <path>] [--remote <name>] [--scaffold <server-backed|none>] [--preview] [--base-url <url>] [--token <token>] [--profile <name>] [--ttl <7d|14d|30d>] [--dry-run] [--force] [--json]
 
 Options:
   --dir <path>      Local checkout directory to create/update. Defaults to current directory.
   --remote <name>   Git remote name to add or update. Defaults to tender.
+  --scaffold <value> API-derived scaffold for empty app source: server-backed or none. Defaults to server-backed.
+  --no-scaffold     Alias for --scaffold none.
+  --preview         Request a preview build for the initialized source commit.
   --base-url <url>  Tender base URL. Defaults to TENDER_BASE_URL, saved profile base URL, or https://app.tenderprompt.com.
   --token <token>   Tender API token. Precedence: --token, explicit --profile, TENDER_API_TOKEN, saved default profile.
   --profile <name>  Local config profile name. Defaults to the saved default profile.
@@ -606,6 +673,7 @@ Options:
 Examples:
   tender app init artifact_123 --dir ./widget --dry-run --json
   tender app init artifact_123 --dir ./widget --json
+  tender app init artifact_123 --dir ./widget --preview --json
   tender app init artifact_123 --dir ./widget --force --json`;
 }
 function artifactsContextFetchHelp() {
@@ -833,6 +901,34 @@ Examples:
   tender app publish artifact_123 --dry-run --json
   tender app publish artifact_123 --commit $(git rev-parse HEAD) --confirm publish --stream --json`;
 }
+function agentHeartbeatHelp() {
+    return `Usage: tender app agent heartbeat <app-id> --source <codex|claude-code|tender-cli|git|other> --status <connected|working|waiting_for_user|needs_attention> --summary <text> [options]
+
+Options:
+  --source <value>            Agent identity. Use codex first, claude-code for Claude Code, or other with --source-label.
+  --source-label <text>       Optional display name when --source other is not specific enough.
+  --status <value>            connected, working, waiting_for_user, or needs_attention.
+  --phase <value>             planning, exploring, editing, pushing, validating, building_preview, preview_updating, watching_preview, or waiting.
+  --summary <text>            Short status line shown in the workspace.
+  --detail <text>             Optional detail shown in activity history.
+  --current-task <text>       Optional current task label.
+  --commit <sha>              Commit SHA related to this update.
+  --preview-job <job-id>      Preview lifecycle job related to this update.
+  --ttl-seconds <seconds>     Freshness window. The API clamps this to a bounded range.
+  --requested-action <value>  none, answer_question, review_preview, or approve_publish. Defaults to none.
+  --interruptible             Mark the agent as interruptible.
+  --input <file|->            Read additional heartbeat JSON fields from a file or stdin. Flags override JSON fields.
+  --base-url <url>            Tender base URL. Defaults to TENDER_BASE_URL, saved profile base URL, or https://app.tenderprompt.com.
+  --token <token>             Tender API token. Precedence: --token, explicit --profile, TENDER_API_TOKEN, saved default profile.
+  --profile <name>            Local config profile name. Defaults to the saved default profile.
+  --json                      Emit stable JSON for coding agents.
+
+Examples:
+  tender app agent heartbeat artifact_123 --source codex --status connected --summary "Loaded the Tender Prompt skill" --json
+  tender app agent heartbeat artifact_123 --source codex --status working --phase exploring --summary "Reading the app structure" --json
+  tender app agent heartbeat artifact_123 --source claude-code --status needs_attention --summary "Waiting for an API key decision" --requested-action answer_question --json
+  tender app agent heartbeat artifact_123 --input - --json < heartbeat.json`;
+}
 function publishStatusHelp() {
     return `Usage: tender app publish status <app-id> --job <job-id> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
@@ -870,6 +966,14 @@ function tenderCliCapabilities() {
             latestRunner: "npm exec --yes @tenderprompt/cli@latest --",
         },
         recommendedSkill: RECOMMENDED_TENDER_PROMPT_SKILL,
+        playbooks: {
+            mode: "remote_progressive_disclosure",
+            metadataCommand: "tender playbooks list --json",
+            entryCommand: "tender playbooks get <playbook-id> --json",
+            fileCommand: "tender playbooks file <playbook-id> --path <path> --json",
+            persistence: "session_only",
+            writesToCheckout: false,
+        },
         description: "Agent-safe Tender App source, lifecycle, analytics, and local scaffold controls.",
         discovery: {
             primary: "npm exec --yes @tenderprompt/cli@latest -- capabilities --json",
@@ -877,7 +981,9 @@ function tenderCliCapabilities() {
                 "tender --version",
                 "tender --help",
                 "tender auth --help",
+                "tender playbooks --help",
                 "tender app --help",
+                "tender app agent heartbeat --help",
                 "tender app analytics --help",
                 "tender app db --help",
                 "tender app bindings outbound --help",
@@ -892,17 +998,42 @@ function tenderCliCapabilities() {
                     "tender auth login --device --profile edit-preview --artifact <artifact-id> --ttl 7d --json",
                 ],
             },
+            {
+                name: "playbook_discovery",
+                when: "Before planning non-trivial Tender App or widget work.",
+                commands: [
+                    "tender playbooks list --json",
+                    "tender playbooks get <playbook-id> --json",
+                    "tender playbooks file <playbook-id> --path references/<file>.md --json",
+                ],
+                notes: [
+                    "List returns metadata only; use it to decide whether a playbook is relevant.",
+                    "Fetch full playbooks and reference files only on demand.",
+                    "Do not write fetched playbook contents into the checkout or install them as skills.",
+                ],
+            },
+            {
+                name: "create_new_app_with_preview",
+                when: "When the user wants a new Tender App that is immediately visible.",
+                commands: [
+                    "tender app create --name <name> --init --dir <dir> --preview --json",
+                ],
+                notes: [
+                    "create --init uses the API-derived scaffold when the new app has no source.",
+                    "--preview requests a preview build for the initial source commit after the push.",
+                ],
+            },
             {
                 name: "clone_or_bootstrap_existing_app",
                 when: "When the user wants to download or work on an existing app locally.",
                 commands: [
                     "tender app init <artifact-id> --dir <dir> --dry-run --json",
-                    "tender app init <artifact-id> --dir <dir> --json",
+                    "tender app init <artifact-id> --dir <dir> --preview --json",
                 ],
                 notes: [
                     "init is the normal clone/bootstrap command.",
                     "If the app already has artifact Git source, init fetches it and configures the tender remote.",
-                    "If no artifact Git source exists yet, init writes managed context/scaffold files and configures the tender remote.",
+                    "If no artifact Git source or workspace source exists yet, init fetches the API-derived scaffold, writes managed context files, and configures the tender remote.",
                     "Use context fetch only when you already have a checkout and only need AGENTS.md, skills, or Tender context refreshed.",
                 ],
             },
@@ -910,14 +1041,18 @@ function tenderCliCapabilities() {
                 name: "local_edit_preview_publish",
                 when: "When editing app source from a local checkout.",
                 commands: [
+                    "tender app agent heartbeat <artifact-id> --source codex --status connected --summary \"Loaded Tender Prompt context\" --json",
                     "tender app doctor --dir <dir> --json",
+                    "tender app agent heartbeat <artifact-id> --source codex --status working --phase editing --summary \"Editing app files\" --json",
                     "tender app git setup <artifact-id> --dir <dir> --dry-run --json",
                     "git push tender main",
+                    "tender app agent heartbeat <artifact-id> --source codex --status working --phase building_preview --summary \"Waiting for preview build\" --commit $(git rev-parse HEAD) --json",
                     "tender app preview <artifact-id> --commit $(git rev-parse HEAD) --stream --json",
                     "tender app publish <artifact-id> --dry-run --json",
                     "tender app publish <artifact-id> --commit $(git rev-parse HEAD) --confirm publish --stream --json",
                 ],
                 notes: [
+                    "Send heartbeat updates only at meaningful milestones or when waiting for user input; do not send rapid polling updates.",
                     "Publishing is production-facing and requires explicit user intent.",
                 ],
             },
@@ -996,12 +1131,43 @@ function tenderCliCapabilities() {
                 writes: false,
             },
             {
-                command: "tender app init <artifact-id> --dir <dir> --json",
-                purpose: "Clone/bootstrap an existing Tender App checkout and configure context plus the tender Git remote.",
+                command: "tender playbooks list --json",
+                purpose: "List remote Tender Prompt playbook metadata without fetching full bodies.",
+                requiresAuth: true,
+                writes: false,
+            },
+            {
+                command: "tender playbooks get <playbook-id> --json",
+                purpose: "Fetch one remote playbook body plus its reference index.",
+                requiresAuth: true,
+                writes: false,
+            },
+            {
+                command: "tender playbooks file <playbook-id> --path references/<file>.md --json",
+                purpose: "Fetch one playbook reference file on demand.",
+                requiresAuth: true,
+                writes: false,
+            },
+            {
+                command: "tender app create --name <name> --init --dir <dir> --preview --json",
+                purpose: "Create a new Tender App, initialize API-derived source in a local checkout, push it, and request a preview build.",
+                requiresAuth: true,
+                writes: true,
+                dryRun: false,
+            },
+            {
+                command: "tender app init <artifact-id> --dir <dir> --preview --json",
+                purpose: "Clone/bootstrap an existing Tender App checkout, configure context plus the tender Git remote, and optionally request a preview for the initialized commit.",
                 requiresAuth: true,
                 writes: true,
                 dryRun: true,
             },
+            {
+                command: "tender app agent heartbeat <artifact-id> --source codex --status working --summary <text> --json",
+                purpose: "Send a concise workspace feedback update from a coding agent.",
+                requiresAuth: true,
+                writes: true,
+            },
             {
                 command: "tender app context fetch <artifact-id> --dir <dir> --json",
                 purpose: "Fetch managed AGENTS.md, skills, and Tender context into an existing checkout.",
@@ -1285,6 +1451,12 @@ function parseTtl(value) {
     }
     return value;
 }
+function parseScaffoldTemplate(value) {
+    if (value !== "server-backed" && value !== "none") {
+        throw new TenderCliUsageError("--scaffold must be one of server-backed or none.");
+    }
+    return value;
+}
 function parseGitRemoteArgs(args) {
     if (args.includes("--help") || args.includes("-h")) {
         return { command: "help", topic: "app git remote" };
@@ -2045,6 +2217,13 @@ function parseArtifactsCreateArgs(args) {
     let name = "";
     let targetPackId = null;
     let targetPackVersion = null;
+    let init = false;
+    let dir = ".";
+    let remoteName = "tender";
+    let ttl = "7d";
+    let force = false;
+    let scaffold = "server-backed";
+    let preview = false;
     let baseUrl = null;
     let flagToken = null;
     let profileName = null;
@@ -2055,6 +2234,22 @@ function parseArtifactsCreateArgs(args) {
             json = true;
             continue;
         }
+        if (arg === "--init") {
+            init = true;
+            continue;
+        }
+        if (arg === "--preview") {
+            preview = true;
+            continue;
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--no-scaffold") {
+            scaffold = "none";
+            continue;
+        }
         if (arg === "--name") {
             const value = args[index + 1];
             if (!value || value.startsWith("-")) {
@@ -2082,6 +2277,30 @@ function parseArtifactsCreateArgs(args) {
             index += 1;
             continue;
         }
+        if (arg === "--dir") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new TenderCliUsageError("--dir requires a path.");
+            }
+            dir = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--remote") {
+            remoteName = parseRemoteName(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--ttl") {
+            ttl = parseTtl(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--scaffold") {
+            scaffold = parseScaffoldTemplate(args[index + 1]);
+            index += 1;
+            continue;
+        }
         if (arg === "--base-url") {
             baseUrl = parseBaseUrlFlag(args, index);
             index += 1;
@@ -2102,11 +2321,38 @@ function parseArtifactsCreateArgs(args) {
     if (!name.trim()) {
         throw new TenderCliUsageError("--name is required. Example: tender app create --name \"Exit Intent Widget\" --json");
     }
+    if (!init) {
+        if (preview) {
+            throw new TenderCliUsageError("--preview requires --init. Example: tender app create --name \"Exit Intent Widget\" --init --dir ./widget --preview --json");
+        }
+        if (force) {
+            throw new TenderCliUsageError("--force is only valid with --init.");
+        }
+        if (dir !== ".") {
+            throw new TenderCliUsageError("--dir is only valid with --init.");
+        }
+        if (remoteName !== "tender") {
+            throw new TenderCliUsageError("--remote is only valid with --init.");
+        }
+        if (ttl !== "7d") {
+            throw new TenderCliUsageError("--ttl is only valid with --init.");
+        }
+        if (scaffold !== "server-backed") {
+            throw new TenderCliUsageError("--scaffold is only valid with --init.");
+        }
+    }
     return {
         command: "app create",
         name: name.trim(),
         targetPackId,
         targetPackVersion,
+        init,
+        dir,
+        remoteName,
+        ttl,
+        force,
+        scaffold,
+        preview,
         baseUrl,
         flagToken,
         profileName,
@@ -2185,6 +2431,8 @@ function parseArtifactsInitArgs(args) {
     let flagToken = null;
     let profileName = null;
     let ttl = "7d";
+    let scaffold = "server-backed";
+    let preview = false;
     let dryRun = false;
     let force = false;
     let json = false;
@@ -2202,6 +2450,14 @@ function parseArtifactsInitArgs(args) {
             force = true;
             continue;
         }
+        if (arg === "--preview") {
+            preview = true;
+            continue;
+        }
+        if (arg === "--no-scaffold") {
+            scaffold = "none";
+            continue;
+        }
         if (arg === "--dir") {
             const value = args[index + 1];
             if (!value || value.startsWith("-")) {
@@ -2236,6 +2492,11 @@ function parseArtifactsInitArgs(args) {
             index += 1;
             continue;
         }
+        if (arg === "--scaffold") {
+            scaffold = parseScaffoldTemplate(args[index + 1]);
+            index += 1;
+            continue;
+        }
         throw new TenderCliUsageError(`Unknown app init option: ${arg}`);
     }
     return {
@@ -2247,6 +2508,8 @@ function parseArtifactsInitArgs(args) {
         flagToken,
         profileName,
         ttl,
+        scaffold,
+        preview,
         dryRun,
         force,
         json,
@@ -2570,6 +2833,114 @@ function parseAuthStatusArgs(args) {
         json,
     };
 }
+function parsePlaybooksCommonArgs(args, startIndex) {
+    let baseUrl = null;
+    let flagToken = null;
+    let profileName = null;
+    let json = false;
+    const extras = [];
+    for (let index = startIndex; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--base-url") {
+            baseUrl = parseBaseUrlFlag(args, index);
+            index += 1;
+            continue;
+        }
+        if (arg === "--token") {
+            flagToken = parseTokenFlag(args, index);
+            index += 1;
+            continue;
+        }
+        if (arg === "--profile") {
+            profileName = parseProfileName(args[index + 1], "--profile");
+            index += 1;
+            continue;
+        }
+        extras.push(arg);
+    }
+    return { baseUrl, flagToken, profileName, json, extras };
+}
+function parsePlaybooksListArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "playbooks list" };
+    }
+    const parsed = parsePlaybooksCommonArgs(args, 0);
+    if (parsed.extras.length > 0) {
+        throw new TenderCliUsageError(`Unknown playbooks list option: ${parsed.extras[0]}`);
+    }
+    return {
+        command: "playbooks list",
+        baseUrl: parsed.baseUrl,
+        flagToken: parsed.flagToken,
+        profileName: parsed.profileName,
+        json: parsed.json,
+    };
+}
+function parsePlaybooksGetArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "playbooks get" };
+    }
+    const playbookId = args[0];
+    if (!playbookId || playbookId.startsWith("-")) {
+        throw new TenderCliUsageError("playbook id is required. Example: tender playbooks get recharge-bundle-builder --json");
+    }
+    const parsed = parsePlaybooksCommonArgs(args, 1);
+    if (parsed.extras.length > 0) {
+        throw new TenderCliUsageError(`Unknown playbooks get option: ${parsed.extras[0]}`);
+    }
+    return {
+        command: "playbooks get",
+        playbookId,
+        baseUrl: parsed.baseUrl,
+        flagToken: parsed.flagToken,
+        profileName: parsed.profileName,
+        json: parsed.json,
+    };
+}
+function parsePlaybooksFileArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "playbooks file" };
+    }
+    const playbookId = args[0];
+    if (!playbookId || playbookId.startsWith("-")) {
+        throw new TenderCliUsageError("playbook id is required. Example: tender playbooks file recharge-bundle-builder --path references/recharge-payloads.md --json");
+    }
+    let filePath = null;
+    const rest = [];
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--path") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new TenderCliUsageError("--path requires a playbook reference path.");
+            }
+            filePath = value;
+            index += 1;
+            continue;
+        }
+        rest.push(arg);
+    }
+    const parsed = parsePlaybooksCommonArgs(rest, 0);
+    if (parsed.extras.length > 0) {
+        throw new TenderCliUsageError(`Unknown playbooks file option: ${parsed.extras[0]}`);
+    }
+    if (!filePath) {
+        throw new TenderCliUsageError("--path is required. Example: tender playbooks file recharge-bundle-builder --path references/recharge-payloads.md --json");
+    }
+    return {
+        command: "playbooks file",
+        playbookId,
+        filePath,
+        baseUrl: parsed.baseUrl,
+        flagToken: parsed.flagToken,
+        profileName: parsed.profileName,
+        json: parsed.json,
+    };
+}
 function parseGenerateEnvTypesArgs(args) {
     if (args.includes("--help") || args.includes("-h")) {
         return { command: "help", topic: "app generate-env-types" };
@@ -3798,6 +4169,204 @@ function parseDbQueryArgs(args) {
         ...parsed,
     };
 }
+const AGENT_HEARTBEAT_SOURCE_VALUES = new Set([
+    "codex",
+    "claude-code",
+    "tender-cli",
+    "git",
+    "other",
+]);
+const AGENT_HEARTBEAT_STATUS_VALUES = new Set([
+    "connected",
+    "working",
+    "waiting_for_user",
+    "needs_attention",
+]);
+const AGENT_HEARTBEAT_PHASE_VALUES = new Set([
+    "planning",
+    "exploring",
+    "editing",
+    "pushing",
+    "validating",
+    "building_preview",
+    "preview_updating",
+    "watching_preview",
+    "waiting",
+]);
+const AGENT_HEARTBEAT_REQUESTED_ACTION_VALUES = new Set([
+    "answer_question",
+    "review_preview",
+    "approve_publish",
+    "none",
+]);
+function parseAgentHeartbeatEnum(value, flag, allowed) {
+    const parsed = parseRequiredFlagValue(value, flag);
+    if (!allowed.has(parsed)) {
+        throw new TenderCliUsageError(`${flag} must be one of ${Array.from(allowed).join(", ")}.`);
+    }
+    return parsed;
+}
+function parseAgentHeartbeatInputPath(value) {
+    if (!value || (value !== "-" && value.startsWith("-"))) {
+        throw new TenderCliUsageError("--input requires a JSON file path or - for stdin.");
+    }
+    return value;
+}
+function parseAgentHeartbeatArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "app agent heartbeat" };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith("-")) {
+        throw new TenderCliUsageError("app id is required. Example: tender app agent heartbeat <app-id> --source codex --status working --summary \"Reading files\" --json");
+    }
+    let baseUrl = null;
+    let flagToken = null;
+    let profileName = null;
+    let inputPath = null;
+    let source = null;
+    let sourceLabel = null;
+    let status = null;
+    let phase = null;
+    let summary = null;
+    let detail = null;
+    let currentTask = null;
+    let commitSha = null;
+    let previewJobId = null;
+    let ttlSeconds = null;
+    let interruptible = false;
+    let requestedAction = null;
+    let json = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        const sourceAssignment = parseFlagAssignment(arg, "--source");
+        if (sourceAssignment !== null) {
+            source = parseAgentHeartbeatEnum(sourceAssignment, "--source", AGENT_HEARTBEAT_SOURCE_VALUES);
+            continue;
+        }
+        const statusAssignment = parseFlagAssignment(arg, "--status");
+        if (statusAssignment !== null) {
+            status = parseAgentHeartbeatEnum(statusAssignment, "--status", AGENT_HEARTBEAT_STATUS_VALUES);
+            continue;
+        }
+        const phaseAssignment = parseFlagAssignment(arg, "--phase");
+        if (phaseAssignment !== null) {
+            phase = parseAgentHeartbeatEnum(phaseAssignment, "--phase", AGENT_HEARTBEAT_PHASE_VALUES);
+            continue;
+        }
+        const requestedActionAssignment = parseFlagAssignment(arg, "--requested-action");
+        if (requestedActionAssignment !== null) {
+            requestedAction = parseAgentHeartbeatEnum(requestedActionAssignment, "--requested-action", AGENT_HEARTBEAT_REQUESTED_ACTION_VALUES);
+            continue;
+        }
+        const ttlAssignment = parseFlagAssignment(arg, "--ttl-seconds");
+        if (ttlAssignment !== null) {
+            ttlSeconds = parsePositiveIntegerFlag(ttlAssignment, "--ttl-seconds");
+            continue;
+        }
+        const inputAssignment = parseFlagAssignment(arg, "--input");
+        if (inputAssignment !== null) {
+            inputPath = parseAgentHeartbeatInputPath(inputAssignment);
+            continue;
+        }
+        const textAssignments = [
+            ["--source-label", (value) => { sourceLabel = value; }],
+            ["--summary", (value) => { summary = value; }],
+            ["--detail", (value) => { detail = value; }],
+            ["--current-task", (value) => { currentTask = value; }],
+            ["--commit", (value) => { commitSha = value; }],
+            ["--preview-job", (value) => { previewJobId = value; }],
+        ];
+        const matchedAssignment = textAssignments.find(([flag]) => arg.startsWith(`${flag}=`));
+        if (matchedAssignment) {
+            const [flag, assign] = matchedAssignment;
+            assign(parseRequiredFlagValue(parseFlagAssignment(arg, flag) ?? undefined, flag));
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--interruptible") {
+            interruptible = true;
+            continue;
+        }
+        if (arg === "--base-url") {
+            baseUrl = parseBaseUrlFlag(args, index);
+            index += 1;
+            continue;
+        }
+        if (arg === "--token") {
+            flagToken = parseTokenFlag(args, index);
+            index += 1;
+            continue;
+        }
+        if (arg === "--profile") {
+            profileName = parseProfileName(args[index + 1], "--profile");
+            index += 1;
+            continue;
+        }
+        if (arg === "--source") {
+            source = parseAgentHeartbeatEnum(args[index + 1], "--source", AGENT_HEARTBEAT_SOURCE_VALUES);
+            index += 1;
+            continue;
+        }
+        if (arg === "--status") {
+            status = parseAgentHeartbeatEnum(args[index + 1], "--status", AGENT_HEARTBEAT_STATUS_VALUES);
+            index += 1;
+            continue;
+        }
+        if (arg === "--phase") {
+            phase = parseAgentHeartbeatEnum(args[index + 1], "--phase", AGENT_HEARTBEAT_PHASE_VALUES);
+            index += 1;
+            continue;
+        }
+        if (arg === "--requested-action") {
+            requestedAction = parseAgentHeartbeatEnum(args[index + 1], "--requested-action", AGENT_HEARTBEAT_REQUESTED_ACTION_VALUES);
+            index += 1;
+            continue;
+        }
+        if (arg === "--ttl-seconds") {
+            ttlSeconds = parsePositiveIntegerFlag(args[index + 1], "--ttl-seconds");
+            index += 1;
+            continue;
+        }
+        if (arg === "--input") {
+            inputPath = parseAgentHeartbeatInputPath(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        const matchedFlag = textAssignments.find(([flag]) => arg === flag);
+        if (matchedFlag) {
+            const [flag, assign] = matchedFlag;
+            assign(parseRequiredFlagValue(args[index + 1], flag));
+            index += 1;
+            continue;
+        }
+        throw new TenderCliUsageError(`Unknown app agent heartbeat option: ${arg}`);
+    }
+    return {
+        command: "app agent heartbeat",
+        artifactId,
+        baseUrl,
+        flagToken,
+        profileName,
+        inputPath,
+        source,
+        sourceLabel,
+        status,
+        phase,
+        summary,
+        detail,
+        currentTask,
+        commitSha,
+        previewJobId,
+        ttlSeconds,
+        interruptible,
+        requestedAction,
+        json,
+    };
+}
 function parseTenderArgs(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         return { command: "help", topic: "root" };
@@ -3823,6 +4392,21 @@ function parseTenderArgs(args) {
         }
         throw new TenderCliUsageError(`Unknown auth command: ${args[1]}`);
     }
+    if (args[0] === "playbooks") {
+        if (args[1] === undefined || args[1] === "--help" || args[1] === "-h") {
+            return { command: "help", topic: "playbooks" };
+        }
+        if (args[1] === "list") {
+            return parsePlaybooksListArgs(args.slice(2));
+        }
+        if (args[1] === "get") {
+            return parsePlaybooksGetArgs(args.slice(2));
+        }
+        if (args[1] === "file") {
+            return parsePlaybooksFileArgs(args.slice(2));
+        }
+        throw new TenderCliUsageError(`Unknown playbooks command: ${args[1]}`);
+    }
     if (args[0] === "apps") {
         throw new TenderCliUsageError("Unknown command: apps. Use `tender app ...` for Tender App workflows.");
     }
@@ -3857,6 +4441,18 @@ function parseTenderArgs(args) {
         if (resourceArgs[1] === "context" && resourceArgs[2] === "refresh") {
             return parseContextRefreshArgs(resourceArgs.slice(3));
         }
+        if (resourceArgs[1] === "agent" &&
+            (resourceArgs[2] === undefined ||
+                resourceArgs[2] === "--help" ||
+                resourceArgs[2] === "-h")) {
+            return { command: "help", topic: "app agent heartbeat" };
+        }
+        if (resourceArgs[1] === "agent" && resourceArgs[2] === "heartbeat") {
+            return parseAgentHeartbeatArgs(resourceArgs.slice(3));
+        }
+        if (resourceArgs[1] === "agent") {
+            throw new TenderCliUsageError(`Unknown app agent command: ${resourceArgs[2]}`);
+        }
         if (resourceArgs[1] === "bindings" && resourceArgs[2] === "outbound") {
             return parseBindingsOutboundArgs(resourceArgs.slice(3));
         }
@@ -4426,6 +5022,40 @@ async function requestDbApi(input) {
     }
     return payload;
 }
+function encodePathSegments(filePath) {
+    return filePath.split("/").map(encodeURIComponent).join("/");
+}
+async function requestPlaybooksApi(input) {
+    const suffix = input.playbooksPath === "list"
+        ? ""
+        : input.playbooksPath === "get"
+            ? `/${encodeURIComponent(input.playbookId)}`
+            : `/${encodeURIComponent(input.playbookId)}/files/${encodePathSegments(input.filePath)}`;
+    const response = await input.fetcher(`${input.baseUrl}/api/v1/playbooks${suffix}`, {
+        method: "GET",
+        headers: {
+            authorization: `Bearer ${input.token}`,
+            accept: "application/json",
+        },
+    });
+    const payload = await parseJsonResponse(response);
+    if (!response.ok || !payload) {
+        const reasonCode = (typeof payload?.reasonCode === "string" && payload.reasonCode) ||
+            `http_${response.status}`;
+        const message = (typeof payload?.message === "string" && payload.message) ||
+            (typeof payload?.reasonCode === "string" && payload.reasonCode) ||
+            `Playbooks request failed with HTTP ${response.status}.`;
+        const authHint = response.status === 401
+            ? "\nAuthenticate first: tender auth login --device --profile edit-preview --save-profile agent --ttl 7d --json"
+            : "";
+        throw new Error([
+            message,
+            `Reason: ${reasonCode}.`,
+            "Example: tender playbooks list --profile agent --json.",
+        ].join("\n") + authHint);
+    }
+    return payload;
+}
 function dbCorrectedExample(artifactId, dbPath) {
     if (dbPath === "capabilities") {
         return `tender app db capabilities ${artifactId} --json`;
@@ -5246,6 +5876,31 @@ async function requestAgentContext(input) {
         files: payload.files,
     };
 }
+async function requestArtifactScaffold(input) {
+    const params = new URLSearchParams({ template: input.template });
+    const response = await input.fetcher(`${input.baseUrl}/api/v1/artifacts/${encodeURIComponent(input.artifactId)}/scaffold?${params.toString()}`, {
+        headers: {
+            authorization: `Bearer ${input.token}`,
+        },
+    });
+    const payload = await parseJsonResponse(response);
+    if (!response.ok ||
+        !payload?.ok ||
+        !payload.files ||
+        !payload.revision ||
+        payload.template !== input.template) {
+        throw new Error(payload?.message ??
+            payload?.reasonCode ??
+            `Artifact scaffold request failed with HTTP ${response.status}.`);
+    }
+    return {
+        ...payload,
+        artifactId: payload.artifactId ?? input.artifactId,
+        template: payload.template,
+        revision: payload.revision,
+        files: payload.files,
+    };
+}
 async function runContextFetch(command, io, runtime) {
     const credentials = await resolveApiCredentials({
         baseUrl: command.baseUrl,
@@ -5454,8 +6109,33 @@ async function runArtifactsCreate(command, io, runtime) {
             payload?.reasonCode ??
             `Artifact create request failed with HTTP ${response.status}.`);
     }
+    let initResult = null;
+    let initExitCode = null;
+    if (command.init) {
+        const initStdout = [];
+        initExitCode = await runArtifactsInit({
+            command: "app init",
+            artifactId: payload.artifact.artifactId,
+            dir: command.dir,
+            remoteName: command.remoteName,
+            baseUrl: credentials.baseUrl,
+            flagToken: command.flagToken,
+            profileName: credentials.profileName,
+            ttl: command.ttl,
+            scaffold: command.scaffold,
+            preview: command.preview,
+            dryRun: false,
+            force: command.force,
+            json: true,
+        }, {
+            stdout: (message) => initStdout.push(message),
+            stderr: io.stderr,
+        }, runtime);
+        const initPayload = initStdout.join("\n").trim();
+        initResult = initPayload ? JSON.parse(initPayload) : null;
+    }
     const result = {
-        ok: true,
+        ok: initExitCode === null ? true : initExitCode === 0,
         command: command.command,
         baseUrl: credentials.baseUrl,
         authSource: credentials.source,
@@ -5463,7 +6143,9 @@ async function runArtifactsCreate(command, io, runtime) {
         tenantId: payload.tenantId ?? null,
         appId: payload.artifact.artifactId,
         artifact: payload.artifact,
+        init: initResult,
         next: {
+            init: `tender app init ${payload.artifact.artifactId} --dir . --preview`,
             contextFetch: `tender app context fetch ${payload.artifact.artifactId} --dir .`,
             gitSetup: `tender app git setup ${payload.artifact.artifactId} --dir .`,
         },
@@ -5476,10 +6158,13 @@ async function runArtifactsCreate(command, io, runtime) {
             `app_id: ${payload.artifact.artifactId}`,
             `name: ${payload.artifact.name}`,
             `preview_url: ${payload.artifact.previewUrl ?? ""}`,
-            `next: ${result.next.contextFetch}`,
-        ].join("\n"));
+            initExitCode === null ? `next: ${result.next.init}` : null,
+            initExitCode !== null ? `init_exit_code: ${initExitCode}` : null,
+        ]
+            .filter((line) => Boolean(line))
+            .join("\n"));
     }
-    return 0;
+    return initExitCode ?? 0;
 }
 async function runArtifactsUpdate(command, io, runtime) {
     const credentials = await resolveApiCredentials({
@@ -5563,7 +6248,7 @@ function shellQuote(value) {
 function createCredentialHelperCommand(input) {
     const parts = [
         "tender",
-        "artifacts",
+        "app",
         "git",
         "credential",
         shellQuote(input.artifactId),
@@ -5736,6 +6421,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "local_head_exists",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     if (input.sourceCheckout.checkedOut) {
@@ -5746,6 +6432,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "source_checked_out",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     if (input.sourceCheckout.skippedReason !== "remote_default_branch_missing") {
@@ -5756,6 +6443,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "remote_unavailable",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     const paths = [...new Set(input.paths)].sort();
@@ -5767,6 +6455,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "no_files_to_seed",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     await runGitCommand({
@@ -5779,6 +6468,11 @@ async function maybeSeedInitialArtifactGitCommit(input) {
         cwd: input.root,
         args: ["commit", "-m", "Seed Tender App scaffold"],
     });
+    const commitShaResult = await runGitCommand({
+        runtime: input.runtime,
+        cwd: input.root,
+        args: ["rev-parse", "HEAD"],
+    });
     const pushResult = await runGitCommand({
         runtime: input.runtime,
         cwd: input.root,
@@ -5791,6 +6485,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
         skippedReason: null,
         commitExitCode: commitResult.exitCode,
         pushExitCode: pushResult.exitCode,
+        commitSha: commitShaResult.stdout.trim() || null,
     };
 }
 async function requestGitRemoteLease(input) {
@@ -5808,6 +6503,26 @@ async function requestGitRemoteLease(input) {
     }
     return payload.git;
 }
+async function requestPreviewRebuildJob(input) {
+    const response = await input.fetcher(`${input.credentials.baseUrl}/api/v1/artifacts/${encodeURIComponent(input.artifactId)}/preview/rebuild`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${input.credentials.token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({ commitSha: input.commitSha }),
+    });
+    const payload = await parseJsonResponse(response);
+    if (!response.ok || !payload?.ok) {
+        throw new Error(payload?.message ??
+            payload?.reasonCode ??
+            `Artifact preview request failed with HTTP ${response.status}.`);
+    }
+    return {
+        job: payload.job ?? null,
+        result: payload.result ?? null,
+    };
+}
 function parseCredentialInput(stdin) {
     const values = new Map();
     for (const line of stdin.split(/\r?\n/)) {
@@ -6010,13 +6725,28 @@ async function runArtifactsInit(command, io, runtime) {
         skippedReason: command.dryRun ? "dry_run" : null,
         commitExitCode: null,
         pushExitCode: null,
+        commitSha: null,
     };
     let sourceExport = {
         attempted: false,
+        source: null,
+        template: null,
+        revision: null,
         filesWritten: 0,
         skippedReason: command.dryRun ? "dry_run" : null,
         files: [],
     };
+    let preview = {
+        attempted: false,
+        commitSha: null,
+        skippedReason: command.preview
+            ? command.dryRun
+                ? "dry_run"
+                : null
+            : "not_requested",
+        job: null,
+        result: null,
+    };
     let seedPaths = [];
     let plannedFiles = await planContextFiles({
         root,
@@ -6052,12 +6782,31 @@ async function runArtifactsInit(command, io, runtime) {
             defaultBranch: git.defaultBranch,
         });
         if (sourceCheckout.skippedReason === "remote_default_branch_missing") {
-            const sourceFiles = await collectArtifactWorkspaceSourceFiles({
+            let sourceFiles = await collectArtifactWorkspaceSourceFiles({
                 artifactId: command.artifactId,
                 baseUrl: credentials.baseUrl,
                 token: credentials.token,
                 fetcher,
             });
+            let source = sourceFiles.length > 0 ? "workspace" : null;
+            let scaffoldRevision = null;
+            let scaffoldTemplate = null;
+            if (sourceFiles.length === 0 && command.scaffold !== "none") {
+                const scaffold = await requestArtifactScaffold({
+                    artifactId: command.artifactId,
+                    template: command.scaffold,
+                    baseUrl: credentials.baseUrl,
+                    token: credentials.token,
+                    fetcher,
+                });
+                sourceFiles = scaffold.files.map((file) => ({
+                    path: file.path,
+                    content: file.content,
+                }));
+                source = "api_scaffold";
+                scaffoldRevision = scaffold.revision;
+                scaffoldTemplate = scaffold.template;
+            }
             const plannedSourceFiles = await planSourceFiles({
                 root,
                 files: sourceFiles,
@@ -6066,8 +6815,15 @@ async function runArtifactsInit(command, io, runtime) {
             const sourceConflicts = plannedSourceFiles.filter((file) => file.action === "conflict");
             sourceExport = {
                 attempted: true,
+                source,
+                template: scaffoldTemplate,
+                revision: scaffoldRevision,
                 filesWritten: 0,
-                skippedReason: plannedSourceFiles.length === 0 ? "empty_workspace" : null,
+                skippedReason: plannedSourceFiles.length === 0
+                    ? command.scaffold === "none"
+                        ? "scaffold_disabled"
+                        : "empty_workspace"
+                    : null,
                 files: plannedSourceFiles.map((file) => ({
                     path: file.path,
                     action: file.action,
@@ -6133,6 +6889,9 @@ async function runArtifactsInit(command, io, runtime) {
         else if (sourceCheckout.checkedOut) {
             sourceExport = {
                 attempted: false,
+                source: null,
+                template: null,
+                revision: null,
                 filesWritten: 0,
                 skippedReason: "source_checked_out",
                 files: [],
@@ -6141,6 +6900,9 @@ async function runArtifactsInit(command, io, runtime) {
         else if (sourceCheckout.skippedReason === "local_head_exists") {
             sourceExport = {
                 attempted: false,
+                source: null,
+                template: null,
+                revision: null,
                 filesWritten: 0,
                 skippedReason: "local_head_exists",
                 files: [],
@@ -6149,6 +6911,9 @@ async function runArtifactsInit(command, io, runtime) {
         else if (sourceCheckout.skippedReason === "remote_unavailable") {
             sourceExport = {
                 attempted: false,
+                source: null,
+                template: null,
+                revision: null,
                 filesWritten: 0,
                 skippedReason: "remote_unavailable",
                 files: [],
@@ -6220,6 +6985,45 @@ async function runArtifactsInit(command, io, runtime) {
             sourceCheckout,
             paths: seedPaths,
         });
+        if (command.preview) {
+            let commitSha = seedCommit.commitSha;
+            if (!commitSha && (seedCommit.pushed || sourceCheckout.checkedOut)) {
+                const headResult = await runGitCommand({
+                    runtime,
+                    cwd: root,
+                    args: ["rev-parse", "HEAD"],
+                    allowFailure: true,
+                });
+                commitSha =
+                    headResult.exitCode === 0 ? headResult.stdout.trim() || null : null;
+            }
+            if (!commitSha) {
+                preview = {
+                    attempted: false,
+                    commitSha: null,
+                    skippedReason: seedCommit.pushed || sourceCheckout.checkedOut
+                        ? "commit_unavailable"
+                        : "seed_not_pushed",
+                    job: null,
+                    result: null,
+                };
+            }
+            else {
+                const previewJob = await requestPreviewRebuildJob({
+                    artifactId: command.artifactId,
+                    commitSha,
+                    credentials,
+                    fetcher,
+                });
+                preview = {
+                    attempted: true,
+                    commitSha,
+                    skippedReason: null,
+                    job: previewJob.job,
+                    result: previewJob.result,
+                };
+            }
+        }
     }
     const result = {
         ok: true,
@@ -6233,11 +7037,13 @@ async function runArtifactsInit(command, io, runtime) {
         defaultBranch: git.defaultBranch,
         dryRun: command.dryRun,
         force: command.force,
+        scaffold: command.scaffold,
         authSource: credentials.source,
         profile: credentials.profileName,
         sourceCheckout,
         sourceExport,
         seedCommit,
+        preview,
         summary: {
             create: plannedFiles.filter((file) => file.action === "create").length,
             overwrite: plannedFiles.filter((file) => file.action === "overwrite").length,
@@ -6267,8 +7073,13 @@ async function runArtifactsInit(command, io, runtime) {
             `context_revision: ${context.revision}`,
             `dir: ${root}`,
             `remote: ${command.remoteName}`,
+            preview.attempted && preview.job?.jobId
+                ? `preview_job: ${preview.job.jobId}`
+                : null,
             `next: ${result.next}`,
-        ].join("\n"));
+        ]
+            .filter((line) => Boolean(line))
+            .join("\n"));
     }
     return 0;
 }
@@ -6666,6 +7477,109 @@ async function runPublishWatch(command, io, runtime) {
     }
     return 0;
 }
+async function readAgentHeartbeatInputObject(input) {
+    if (!input.command.inputPath) {
+        return {};
+    }
+    const raw = input.command.inputPath === "-"
+        ? input.stdin
+        : await readFile(path.resolve(input.command.inputPath), "utf8");
+    if (!raw) {
+        throw new TenderCliUsageError("--input - requires heartbeat JSON on stdin.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TenderCliUsageError("--input must contain valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new TenderCliUsageError("--input must contain a JSON object.");
+    }
+    return parsed;
+}
+function assignAgentHeartbeatField(body, field, value) {
+    if (value !== null) {
+        body[field] = value;
+    }
+}
+async function buildAgentHeartbeatBody(command, runtime) {
+    const body = await readAgentHeartbeatInputObject({
+        command,
+        stdin: runtime.stdin,
+    });
+    assignAgentHeartbeatField(body, "source", command.source);
+    assignAgentHeartbeatField(body, "sourceLabel", command.sourceLabel);
+    assignAgentHeartbeatField(body, "status", command.status);
+    assignAgentHeartbeatField(body, "phase", command.phase);
+    assignAgentHeartbeatField(body, "summary", command.summary);
+    assignAgentHeartbeatField(body, "detail", command.detail);
+    assignAgentHeartbeatField(body, "currentTask", command.currentTask);
+    assignAgentHeartbeatField(body, "commitSha", command.commitSha);
+    assignAgentHeartbeatField(body, "previewJobId", command.previewJobId);
+    assignAgentHeartbeatField(body, "ttlSeconds", command.ttlSeconds);
+    assignAgentHeartbeatField(body, "requestedAction", command.requestedAction);
+    if (command.interruptible) {
+        body.interruptible = true;
+    }
+    if (typeof body.source !== "string" || body.source.trim().length === 0) {
+        throw new TenderCliUsageError("--source is required. Example: tender app agent heartbeat <app-id> --source codex --status working --summary \"Reading files\" --json");
+    }
+    if (typeof body.status !== "string" || body.status.trim().length === 0) {
+        throw new TenderCliUsageError("--status is required. Example: tender app agent heartbeat <app-id> --source codex --status working --summary \"Reading files\" --json");
+    }
+    if (typeof body.summary !== "string" || body.summary.trim().length === 0) {
+        throw new TenderCliUsageError("--summary is required. Example: tender app agent heartbeat <app-id> --source codex --status working --summary \"Reading files\" --json");
+    }
+    return body;
+}
+async function runAgentHeartbeat(command, io, runtime) {
+    const credentials = await resolveApiCredentials({
+        baseUrl: command.baseUrl,
+        flagToken: command.flagToken,
+        profileName: command.profileName,
+        env: runtime.env ?? process.env,
+    });
+    const body = await buildAgentHeartbeatBody(command, runtime);
+    const response = await (runtime.fetcher ?? fetch)(`${credentials.baseUrl}/api/v1/artifacts/${encodeURIComponent(command.artifactId)}/agent/heartbeat`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${credentials.token}`,
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const payload = await parseJsonResponse(response);
+    if (!response.ok || !payload?.ok) {
+        throw new Error((typeof payload?.message === "string" && payload.message) ||
+            (typeof payload?.reasonCode === "string" && payload.reasonCode) ||
+            `Agent heartbeat failed with HTTP ${response.status}.`);
+    }
+    const result = {
+        ok: true,
+        command: command.command,
+        baseUrl: credentials.baseUrl,
+        authSource: credentials.source,
+        profile: credentials.profileName,
+        tenantId: payload.tenantId ?? null,
+        artifactId: payload.artifactId ?? command.artifactId,
+        activity: payload.activity ?? null,
+    };
+    if (command.json) {
+        io.stdout(JSON.stringify(result, null, 2));
+    }
+    else {
+        io.stdout([
+            `app_id: ${result.artifactId}`,
+            `heartbeat: accepted`,
+            `status: ${String(body.status)}`,
+            `summary: ${String(body.summary)}`,
+        ].join("\n"));
+    }
+    return 0;
+}
 async function runGitRemote(command, io, runtime) {
     const credentials = await resolveApiCredentials({
         baseUrl: command.baseUrl,
@@ -6723,6 +7637,25 @@ async function resolveAnalyticsCredentials(command, runtime) {
         env: runtime.env ?? process.env,
     });
 }
+async function resolvePlaybooksCredentials(command, runtime) {
+    try {
+        return await resolveApiCredentials({
+            baseUrl: command.baseUrl,
+            flagToken: command.flagToken,
+            profileName: command.profileName,
+            env: runtime.env ?? process.env,
+        });
+    }
+    catch (error) {
+        if (error instanceof TenderCliUsageError) {
+            throw new TenderCliUsageError([
+                "Playbooks require Tender authentication.",
+                "Run `tender auth login --device --profile edit-preview --save-profile agent --ttl 7d --json`, set TENDER_API_TOKEN, or pass --token <token>.",
+            ].join("\n"));
+        }
+        throw error;
+    }
+}
 async function resolveDbCredentials(command, runtime) {
     return await resolveApiCredentials({
         baseUrl: command.baseUrl,
@@ -6760,6 +7693,58 @@ function printDbPayload(command, io, payload, fallbackLines) {
         io.stdout(fallbackLines.join("\n"));
     }
 }
+function printPlaybooksPayload(command, io, payload, fallback) {
+    if (command.json) {
+        io.stdout(JSON.stringify(payload, null, 2));
+    }
+    else {
+        io.stdout(fallback);
+    }
+}
+async function runPlaybooksList(command, io, runtime) {
+    const credentials = await resolvePlaybooksCredentials(command, runtime);
+    const payload = await requestPlaybooksApi({
+        playbooksPath: "list",
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+    });
+    const playbooks = Array.isArray(payload.playbooks) ? payload.playbooks : [];
+    printPlaybooksPayload(command, io, payload, playbooks
+        .map((playbook) => isCliJsonRecord(playbook)
+        ? `${String(playbook.id ?? "")}\t${String(playbook.description ?? "")}`
+        : "")
+        .filter(Boolean)
+        .join("\n") || "No Tender Prompt playbooks found.");
+    return 0;
+}
+async function runPlaybooksGet(command, io, runtime) {
+    const credentials = await resolvePlaybooksCredentials(command, runtime);
+    const payload = await requestPlaybooksApi({
+        playbooksPath: "get",
+        playbookId: command.playbookId,
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+    });
+    printPlaybooksPayload(command, io, payload, typeof payload.body === "string" ? payload.body : JSON.stringify(payload, null, 2));
+    return 0;
+}
+async function runPlaybooksFile(command, io, runtime) {
+    const credentials = await resolvePlaybooksCredentials(command, runtime);
+    const payload = await requestPlaybooksApi({
+        playbooksPath: "file",
+        playbookId: command.playbookId,
+        filePath: command.filePath,
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+    });
+    printPlaybooksPayload(command, io, payload, typeof payload.content === "string"
+        ? payload.content
+        : JSON.stringify(payload, null, 2));
+    return 0;
+}
 async function runDbCapabilities(command, io, runtime) {
     const credentials = await resolveDbCredentials(command, runtime);
     const payload = await requestDbApi({
@@ -7376,6 +8361,18 @@ export async function runTenderCli(args, io = {
             else if (command.topic === "auth status") {
                 io.stdout(authStatusHelp());
             }
+            else if (command.topic === "playbooks") {
+                io.stdout(playbooksHelp());
+            }
+            else if (command.topic === "playbooks list") {
+                io.stdout(playbooksListHelp());
+            }
+            else if (command.topic === "playbooks get") {
+                io.stdout(playbooksGetHelp());
+            }
+            else if (command.topic === "playbooks file") {
+                io.stdout(playbooksFileHelp());
+            }
             else if (command.topic === "auth") {
                 io.stdout(authHelp());
             }
@@ -7433,6 +8430,9 @@ export async function runTenderCli(args, io = {
             else if (command.topic === "app preview watch") {
                 io.stdout(previewWatchHelp());
             }
+            else if (command.topic === "app agent heartbeat") {
+                io.stdout(agentHeartbeatHelp());
+            }
             else if (command.topic === "app publish") {
                 io.stdout(publishHelp());
             }
@@ -7525,6 +8525,15 @@ export async function runTenderCli(args, io = {
         if (command.command === "auth status") {
             return await runAuthStatus(command, io, runtime);
         }
+        if (command.command === "playbooks list") {
+            return await runPlaybooksList(command, io, runtime);
+        }
+        if (command.command === "playbooks get") {
+            return await runPlaybooksGet(command, io, runtime);
+        }
+        if (command.command === "playbooks file") {
+            return await runPlaybooksFile(command, io, runtime);
+        }
         if (command.command === "app list") {
             return await runArtifactsList(command, io, runtime);
         }
@@ -7573,6 +8582,9 @@ export async function runTenderCli(args, io = {
         if (command.command === "app preview watch") {
             return await runPreviewWatch(command, io, runtime);
         }
+        if (command.command === "app agent heartbeat") {
+            return await runAgentHeartbeat(command, io, runtime);
+        }
         if (command.command === "app publish") {
             return await runPublish(command, io, runtime);
         }
@@ -7639,10 +8651,17 @@ export async function runTenderCli(args, io = {
         if (command.command === "app git remote") {
             return await runGitRemote(command, io, runtime);
         }
-        return await runDoctor(command, io);
+        if (command.command === "app doctor") {
+            return await runDoctor(command, io);
+        }
+        throw new TenderCliUsageError("Unhandled command.");
     }
     catch (error) {
-        if (args.includes("--json") && args[0] === "app" && args[1] === "db") {
+        if (args.includes("--json") &&
+            ((args[0] === "app" &&
+                (args[1] === "db" ||
+                    (args[1] === "agent" && args[2] === "heartbeat"))) ||
+                args[0] === "playbooks")) {
             io.stdout(JSON.stringify(cliErrorPayload(error, args, command), null, 2));
             return error instanceof TenderCliUsageError ? 2 : 1;
         }
@@ -7659,6 +8678,9 @@ export function shouldReadEntrypointStdin(args) {
     return (args[0] === "app" &&
         ((args[1] === "git" && args[2] === "credential") ||
             (args[1] === "analytics" && hasFlagValue(args, "--spec", "-")) ||
+            (args[1] === "agent" &&
+                args[2] === "heartbeat" &&
+                hasFlagValue(args, "--input", "-")) ||
             (args[1] === "db" &&
                 args[2] === "query" &&
                 hasFlagValue(args, "--file", "-"))));