@tenderprompt/cli 0.1.15 → 0.1.16

package/README.md

@@ -56,7 +56,7 @@ tender capabilities --json
 
 tender auth login --device --profile edit-preview --artifact artifact_123 --ttl 7d
 
-tender app init artifact_123 --dir ./widget --json
+tender app init artifact_123 --dir ./widget --preview --json
 
 cd ./widget
 npm run check
@@ -70,7 +70,7 @@ tender app publish artifact_123 --commit "$(git rev-parse HEAD)" --confirm publi
 For agents, keep the pattern simple:
 
 1. start with `tender capabilities --json`
-2. use `tender app init` to clone/bootstrap an existing app checkout
+2. use `tender app init --preview` to clone/bootstrap an existing app checkout
 3. inspect and edit files locally
 4. run `tender app doctor` and local project checks
 5. push source with Git
@@ -128,8 +128,9 @@ tender --version
 tender capabilities --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 bindings outbound --id shopify --host admin.shopify.com --dry-run --json
 tender app context status artifact_123 --dir ./widget --json
 tender app doctor --dir ./widget --json

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.2",
     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.",
@@ -136,8 +136,9 @@ Examples:
   tender auth status --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
@@ -208,7 +209,7 @@ function appHelp() {
 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 +224,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 +261,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 +279,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 +566,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 +587,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 +604,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 +623,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 +851,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]
 
@@ -878,6 +924,7 @@ function tenderCliCapabilities() {
                 "tender --help",
                 "tender auth --help",
                 "tender app --help",
+                "tender app agent heartbeat --help",
                 "tender app analytics --help",
                 "tender app db --help",
                 "tender app bindings outbound --help",
@@ -892,17 +939,28 @@ function tenderCliCapabilities() {
                     "tender auth login --device --profile edit-preview --artifact <artifact-id> --ttl 7d --json",
                 ],
             },
+            {
+                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 +968,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 +1058,25 @@ 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 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 +1360,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 +2126,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 +2143,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 +2186,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 +2230,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 +2340,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 +2359,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 +2401,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 +2417,8 @@ function parseArtifactsInitArgs(args) {
         flagToken,
         profileName,
         ttl,
+        scaffold,
+        preview,
         dryRun,
         force,
         json,
@@ -3798,6 +3970,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" };
@@ -3857,6 +4227,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));
         }
@@ -5246,6 +5628,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 +5861,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 +5895,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 +5910,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 +6000,7 @@ function shellQuote(value) {
 function createCredentialHelperCommand(input) {
     const parts = [
         "tender",
-        "artifacts",
+        "app",
         "git",
         "credential",
         shellQuote(input.artifactId),
@@ -5736,6 +6173,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "local_head_exists",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     if (input.sourceCheckout.checkedOut) {
@@ -5746,6 +6184,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 +6195,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "remote_unavailable",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     const paths = [...new Set(input.paths)].sort();
@@ -5767,6 +6207,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
             skippedReason: "no_files_to_seed",
             commitExitCode: null,
             pushExitCode: null,
+            commitSha: null,
         };
     }
     await runGitCommand({
@@ -5779,6 +6220,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 +6237,7 @@ async function maybeSeedInitialArtifactGitCommit(input) {
         skippedReason: null,
         commitExitCode: commitResult.exitCode,
         pushExitCode: pushResult.exitCode,
+        commitSha: commitShaResult.stdout.trim() || null,
     };
 }
 async function requestGitRemoteLease(input) {
@@ -5808,6 +6255,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 +6477,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 +6534,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 +6567,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 +6641,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 +6652,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 +6663,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 +6737,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 +6789,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 +6825,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 +7229,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,
@@ -7433,6 +8099,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());
             }
@@ -7573,6 +8242,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 +8311,15 @@ 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"))) {
             io.stdout(JSON.stringify(cliErrorPayload(error, args, command), null, 2));
             return error instanceof TenderCliUsageError ? 2 : 1;
         }
@@ -7659,6 +8336,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", "-"))));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tenderprompt/cli",
-	"version": "0.1.15",
+	"version": "0.1.16",
 	"type": "module",
 	"bin": {
 		"tender": "bin/tender.js"