@atollhq/cli 0.1.3 → 0.1.4

package/dist/index.js

@@ -81,9 +81,9 @@ var init_config = __esm({
 });
 
 // src/index.ts
-var import_commander8 = require("commander");
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_commander11 = require("commander");
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
 
 // src/commands/auth.ts
 var import_commander = require("commander");
@@ -97,6 +97,9 @@ function isJsonMode() {
   if (process.env.OUTPUT_FORMAT === "json") return true;
   return !process.stdout.isTTY;
 }
+function enableJsonMode() {
+  process.env.OUTPUT_FORMAT = "json";
+}
 function output(data, humanReadable) {
   if (isJsonMode()) {
     process.stdout.write(JSON.stringify(data) + "\n");
@@ -104,13 +107,34 @@ function output(data, humanReadable) {
     console.log(humanReadable);
   }
 }
+function outputJson(data) {
+  process.stdout.write(JSON.stringify(data) + "\n");
+}
 function outputError(message) {
   if (isJsonMode()) {
-    process.stdout.write(JSON.stringify({ error: message }) + "\n");
+    process.stderr.write(JSON.stringify({ error: message }) + "\n");
   } else {
     console.error(`Error: ${message}`);
   }
 }
+var DEFAULT_LIST_LIMIT = 25;
+var MAX_LIST_LIMIT = 100;
+function normalizeLimit(limit, defaultLimit = DEFAULT_LIST_LIMIT) {
+  if (limit === void 0 || Number.isNaN(limit)) return defaultLimit;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT) {
+    outputError(`--limit must be an integer from 1 to ${MAX_LIST_LIMIT} (got: "${limit}")`);
+    process.exit(2);
+  }
+  return limit;
+}
+function normalizeOffset(offset) {
+  if (offset === void 0 || Number.isNaN(offset)) return 0;
+  if (!Number.isInteger(offset) || offset < 0) {
+    outputError(`--offset must be a non-negative integer (got: "${offset}")`);
+    process.exit(2);
+  }
+  return offset;
+}
 
 // src/lib/client.ts
 var DEFAULT_BASE_URL = "https://atollhq.com";
@@ -140,7 +164,10 @@ var AtollClient = class {
       const body = await res.text();
       throw new Error(`API ${res.status}: ${body}`);
     }
-    return res.json();
+    if (res.status === 204) return void 0;
+    const text = await res.text();
+    if (!text) return void 0;
+    return JSON.parse(text);
   }
   async get(path) {
     return this.request(path, { method: "GET" });
@@ -464,15 +491,26 @@ Examples:
   $ atoll issue create --title "Fix login" --priority 1 --status todo
   $ atoll issue update ATOLL-42 --status done
   $ atoll issue assign ATOLL-42 --to <user-id>`);
-issueCommand.command("list").description("List issues").option("--status <status>", `Filter by status (${VALID_STATUSES.join(", ")})`).option("--assignee <user>", "Filter by assignee ID").option("--priority <n>", "Filter by priority (0=urgent, 1=high, 2=medium, 3=low)", parseInt).option("--limit <n>", "Max results (1-100)", parseInt).action(async (opts) => {
+issueCommand.command("list").description("List issues").option("--status <status>", `Filter by status (${VALID_STATUSES.join(", ")})`).option("--assignee <user>", "Filter by assignee ID").option("--priority <n>", "Filter by priority (0=urgent, 1=high, 2=medium, 3=low)", parseInt).option("--limit <n>", "Max results (1-100)", parseInt).option("--offset <n>", "Results offset for pagination", parseInt).action(async (opts) => {
   try {
+    if (opts.status && !VALID_STATUSES.includes(opts.status)) {
+      outputError(`Invalid status "${opts.status}". Must be one of: ${VALID_STATUSES.join(", ")}`);
+      process.exit(2);
+    }
+    if (opts.priority !== void 0 && ![0, 1, 2, 3].includes(opts.priority)) {
+      outputError("Priority must be 0 (urgent), 1 (high), 2 (medium), or 3 (low).");
+      process.exit(2);
+    }
     const client = new AtollClient();
     const org = await resolveOrg(client);
+    const limit = normalizeLimit(opts.limit);
+    const offset = normalizeOffset(opts.offset);
     const params = new URLSearchParams();
     if (opts.status) params.set("status", opts.status);
     if (opts.assignee) params.set("assigneeId", opts.assignee);
     if (opts.priority !== void 0) params.set("priority", String(opts.priority));
-    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    params.set("limit", String(limit));
+    if (offset > 0) params.set("offset", String(offset));
     const qs = params.toString();
     const [data, projects] = await Promise.all([
       client.get(`/api/orgs/${org.id}/issues${qs ? `?${qs}` : ""}`),
@@ -481,10 +519,17 @@ issueCommand.command("list").description("List issues").option("--status <status
     const enriched = data.issues.map(
       (issue) => attachIssueUrl(issue, client.baseUrl, org.slug, projects)
     );
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      for (const issue of enriched) {
-        process.stdout.write(JSON.stringify(issue) + "\n");
-      }
+    if (isJsonMode()) {
+      outputJson({
+        resource: "issues",
+        items: enriched,
+        total: data.total,
+        limit: data.limit,
+        offset: data.offset,
+        nextOffset: data.offset + data.limit < data.total ? data.offset + data.limit : null,
+        truncated: data.offset + data.limit < data.total,
+        hint: data.offset + data.limit < data.total ? "Use --offset with nextOffset to continue." : null
+      });
       return;
     }
     if (enriched.length === 0) {
@@ -502,11 +547,14 @@ issueCommand.command("list").description("List issues").option("--status <status
       console.log(`${padEnd(id, 10)} ${statusColor(issue.status, padEnd(issue.status, 14))} ${icon} ${padEnd(pri, 8)} ${title}`);
     }
     console.log(dim(`${enriched.length} of ${data.total} issues`));
+    if (data.offset + data.limit < data.total) {
+      console.log(dim(`Next: atoll issue list --offset ${data.offset + data.limit} --limit ${data.limit}`));
+    }
   } catch (err) {
     handleApiError(err);
   }
 });
-issueCommand.command("view <identifier>").description("View issue details (UUID or PREFIX-NUMBER e.g. ATOLL-42)").action(async (identifier) => {
+async function viewIssue(identifier) {
   try {
     const client = new AtollClient();
     const org = await resolveOrg(client);
@@ -516,8 +564,8 @@ issueCommand.command("view <identifier>").description("View issue details (UUID
       fetchProjectMap(client, org.id)
     ]);
     const enriched = attachIssueUrl(issue, client.baseUrl, org.slug, projects);
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      process.stdout.write(JSON.stringify(enriched) + "\n");
+    if (isJsonMode()) {
+      outputJson(enriched);
       return;
     }
     const id = formatIdentifier(enriched, projects);
@@ -544,7 +592,9 @@ Subtasks: ${enriched.sub_tasks.length}`);
   } catch (err) {
     handleApiError(err);
   }
-});
+}
+issueCommand.command("view <identifier>").description("View issue details (UUID or PREFIX-NUMBER e.g. ATOLL-42)").action(viewIssue);
+issueCommand.command("get <identifier>").description("Get issue details (UUID or PREFIX-NUMBER e.g. ATOLL-42)").action(viewIssue);
 issueCommand.command("create").description("Create a new issue").requiredOption("--title <title>", "Issue title").option("--description <text>", "Issue description").option("--status <status>", `Status (${VALID_STATUSES.join(", ")})`).option("--priority <n>", "Priority (0=urgent, 1=high, 2=medium, 3=low)", parseInt).action(async (opts) => {
   try {
     if (opts.status && !VALID_STATUSES.includes(opts.status)) {
@@ -605,11 +655,22 @@ issueCommand.command("update <identifier>").description("Update an issue").optio
     handleApiError(err);
   }
 });
-issueCommand.command("delete <identifier>").description("Delete an issue (admin/owner only)").action(async (identifier) => {
+issueCommand.command("delete <identifier>").description("Delete an issue (admin/owner only)").option("--force", "Permanently delete the issue").option("--dry-run", "Show what would be deleted without changing anything").action(async (identifier, opts) => {
   try {
+    if (!opts.dryRun && !opts.force) {
+      outputError("Permanent issue deletion requires --force. Prefer `atoll issue archive <identifier>` for reversible removal.");
+      process.exit(2);
+    }
     const client = new AtollClient();
     const orgId = await resolveOrgId(client);
     const issueId = await resolveIssueId(client, orgId, identifier);
+    if (opts.dryRun) {
+      output(
+        { dryRun: true, wouldDelete: { type: "issue", id: issueId, identifier } },
+        `Would permanently delete issue ${identifier} (${issueId})`
+      );
+      return;
+    }
     await client.delete(`/api/orgs/${orgId}/issues/${issueId}`);
     output(
       { success: true, id: issueId },
@@ -619,6 +680,48 @@ issueCommand.command("delete <identifier>").description("Delete an issue (admin/
     handleApiError(err);
   }
 });
+issueCommand.command("archive <identifier>").description("Archive an issue (reversible soft delete)").option("--dry-run", "Show what would be archived without changing anything").action(async (identifier, opts) => {
+  try {
+    const client = new AtollClient();
+    const orgId = await resolveOrgId(client);
+    const issueId = await resolveIssueId(client, orgId, identifier);
+    if (opts.dryRun) {
+      output(
+        { dryRun: true, wouldArchive: { type: "issue", id: issueId, identifier } },
+        `Would archive issue ${identifier} (${issueId})`
+      );
+      return;
+    }
+    await client.post(`/api/orgs/${orgId}/issues/${issueId}/archive`);
+    output(
+      { success: true, id: issueId, archived: true },
+      success(`Archived issue ${identifier}`)
+    );
+  } catch (err) {
+    handleApiError(err);
+  }
+});
+issueCommand.command("unarchive <identifier>").description("Unarchive an issue").option("--dry-run", "Show what would be unarchived without changing anything").action(async (identifier, opts) => {
+  try {
+    const client = new AtollClient();
+    const orgId = await resolveOrgId(client);
+    const issueId = await resolveIssueId(client, orgId, identifier);
+    if (opts.dryRun) {
+      output(
+        { dryRun: true, wouldUnarchive: { type: "issue", id: issueId, identifier } },
+        `Would unarchive issue ${identifier} (${issueId})`
+      );
+      return;
+    }
+    await client.delete(`/api/orgs/${orgId}/issues/${issueId}/archive`);
+    output(
+      { success: true, id: issueId, archived: false },
+      success(`Unarchived issue ${identifier}`)
+    );
+  } catch (err) {
+    handleApiError(err);
+  }
+});
 issueCommand.command("assign <identifier>").description("Assign an issue to a user or agent").requiredOption("--to <user>", 'User/agent ID or "self" for yourself').action(async (identifier, opts) => {
   try {
     const client = new AtollClient();
@@ -693,32 +796,44 @@ function formatTimestamp(ts) {
   return d.toLocaleString();
 }
 var commentCommand = new import_commander3.Command("comment").description("Manage issue comments");
-commentCommand.command("list <identifier>").description("List comments on an issue (UUID or PREFIX-NUMBER e.g. ATOLL-42)").action(async (identifier) => {
+commentCommand.command("list <identifier>").description("List comments on an issue (UUID or PREFIX-NUMBER e.g. ATOLL-42)").option("--limit <n>", "Max results (1-100)", parseInt).action(async (identifier, opts) => {
   try {
+    const limit = normalizeLimit(opts.limit);
     const client = new AtollClient();
     const orgId = await resolveOrgId(client);
     const issueId = await resolveIssueId(client, orgId, identifier);
     const data = await client.get(
       `/api/orgs/${orgId}/issues/${issueId}/comments`
     );
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      for (const comment of data.comments) {
-        process.stdout.write(JSON.stringify(comment) + "\n");
-      }
+    const allComments = data.comments ?? [];
+    const comments = allComments.slice(0, limit);
+    const truncated = allComments.length > comments.length;
+    if (isJsonMode()) {
+      outputJson({
+        resource: "comments",
+        items: comments,
+        total: allComments.length,
+        limit,
+        offset: 0,
+        nextOffset: null,
+        truncated,
+        hint: truncated ? "Increase --limit up to 100 to show more comments." : null
+      });
       return;
     }
-    if (data.comments.length === 0) {
+    if (comments.length === 0) {
       console.log("No comments found.");
       return;
     }
-    for (const comment of data.comments) {
+    for (const comment of comments) {
       const author = formatAuthor(comment);
       const time = formatTimestamp(comment.created_at);
       console.log(`${BOLD2}${CYAN}${author}${RESET2} ${DIM2}${time}${RESET2}`);
       console.log(comment.body);
       console.log();
     }
-    console.log(`${DIM2}${data.comments.length} comment(s)${RESET2}`);
+    console.log(`${DIM2}${comments.length} of ${allComments.length} comment(s)${RESET2}`);
+    if (truncated) console.log(`${DIM2}${allComments.length - comments.length} more comment(s) hidden; increase --limit to show more.${RESET2}`);
   } catch (err) {
     handleApiError(err);
   }
@@ -757,11 +872,22 @@ commentCommand.command("update <comment-id>").description("Update a comment").re
     handleApiError(err);
   }
 });
-commentCommand.command("delete <comment-id>").description("Delete a comment").requiredOption("--issue <identifier>", "Issue identifier (e.g. UUID or PREFIX-NUMBER)").action(async (commentId, opts) => {
+commentCommand.command("delete <comment-id>").description("Delete a comment").requiredOption("--issue <identifier>", "Issue identifier (e.g. UUID or PREFIX-NUMBER)").option("--force", "Delete the comment").option("--dry-run", "Show what would be deleted without changing anything").action(async (commentId, opts) => {
   try {
+    if (!opts.dryRun && !opts.force) {
+      outputError("Comment deletion requires --force.");
+      process.exit(2);
+    }
     const client = new AtollClient();
     const orgId = await resolveOrgId(client);
     const issueId = await resolveIssueId(client, orgId, opts.issue);
+    if (opts.dryRun) {
+      output(
+        { dryRun: true, wouldDelete: { type: "comment", id: commentId, issueId } },
+        `Would delete comment ${commentId} on ${opts.issue}`
+      );
+      return;
+    }
     await client.delete(`/api/orgs/${orgId}/issues/${issueId}/comments/${commentId}`);
     output(
       { success: true, id: commentId },
@@ -787,16 +913,26 @@ Examples:
   $ atoll project list
   $ atoll project create --name "My Project" --icon \u{1F680}
   $ atoll project view <project-id>`);
-projectCommand.command("list").description("List all projects with progress").action(async () => {
+projectCommand.command("list").description("List all projects with progress").option("--limit <n>", "Max results (1-100)", parseInt).action(async (opts) => {
   const client = new AtollClient();
   try {
+    const limit = normalizeLimit(opts.limit);
     const org = await resolveOrg(client);
     const data = await client.get(`/api/orgs/${org.id}/projects`);
-    const projects = (data.projects ?? []).map((p) => attachProjectUrl(p, client.baseUrl, org.slug));
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      for (const p of projects) {
-        process.stdout.write(JSON.stringify(p) + "\n");
-      }
+    const allProjects = (data.projects ?? []).map((p) => attachProjectUrl(p, client.baseUrl, org.slug));
+    const projects = allProjects.slice(0, limit);
+    const truncated = allProjects.length > projects.length;
+    if (isJsonMode()) {
+      outputJson({
+        resource: "projects",
+        items: projects,
+        total: allProjects.length,
+        limit,
+        offset: 0,
+        nextOffset: null,
+        truncated,
+        hint: truncated ? "Narrow the request in the API or increase --limit up to 100." : null
+      });
       return;
     }
     if (projects.length === 0) {
@@ -813,6 +949,7 @@ projectCommand.command("list").description("List all projects with progress").ac
       if (p.status === "archived") console.log(`  ${dim("[archived]")}`);
       console.log("");
     }
+    if (truncated) console.log(dim(`${allProjects.length - projects.length} more project(s) hidden; increase --limit to show more.`));
   } catch (err) {
     handleApiError(err);
   }
@@ -837,7 +974,7 @@ ${project.url}` : ""}`)
     handleApiError(err);
   }
 });
-projectCommand.command("view <projectId>").description("View project details and issues").action(async (projectId) => {
+async function viewProject(projectId) {
   const client = new AtollClient();
   try {
     const org = await resolveOrg(client);
@@ -845,8 +982,8 @@ projectCommand.command("view <projectId>").description("View project details and
       `/api/orgs/${org.id}/projects/${projectId}`
     );
     const p = attachProjectUrl(data.project, client.baseUrl, org.slug);
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      process.stdout.write(JSON.stringify(p) + "\n");
+    if (isJsonMode()) {
+      outputJson(p);
       return;
     }
     const progress = p.progress ?? 0;
@@ -869,7 +1006,9 @@ projectCommand.command("view <projectId>").description("View project details and
   } catch (err) {
     handleApiError(err);
   }
-});
+}
+projectCommand.command("view <projectId>").description("View project details and issues").action(viewProject);
+projectCommand.command("get <projectId>").description("Get project details and issues").action(viewProject);
 
 // src/commands/milestone.ts
 var import_commander5 = require("commander");
@@ -882,18 +1021,28 @@ var milestoneCommand = new import_commander5.Command("milestone").description("M
 Examples:
   $ atoll milestone list --project <project-id>
   $ atoll milestone create --project <project-id> --name "v1.0" --date 2026-06-01`);
-milestoneCommand.command("list").description("List milestones for a project").requiredOption("--project <id>", "Project ID").action(async (opts) => {
+milestoneCommand.command("list").description("List milestones for a project").requiredOption("--project <id>", "Project ID").option("--limit <n>", "Max results (1-100)", parseInt).action(async (opts) => {
   const client = new AtollClient();
   try {
+    const limit = normalizeLimit(opts.limit);
     const orgId = await resolveOrgId(client);
     const data = await client.get(
       `/api/orgs/${orgId}/projects/${opts.project}/milestones`
     );
-    const milestones = data.milestones ?? [];
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      for (const m of milestones) {
-        process.stdout.write(JSON.stringify(m) + "\n");
-      }
+    const allMilestones = data.milestones ?? [];
+    const milestones = allMilestones.slice(0, limit);
+    const truncated = allMilestones.length > milestones.length;
+    if (isJsonMode()) {
+      outputJson({
+        resource: "milestones",
+        items: milestones,
+        total: allMilestones.length,
+        limit,
+        offset: 0,
+        nextOffset: null,
+        truncated,
+        hint: truncated ? "Narrow the request by project or increase --limit up to 100." : null
+      });
       return;
     }
     if (milestones.length === 0) {
@@ -911,6 +1060,7 @@ milestoneCommand.command("list").description("List milestones for a project").re
       if (m.status === "closed") console.log(`  ${dim("[closed]")}`);
       console.log("");
     }
+    if (truncated) console.log(dim(`${allMilestones.length - milestones.length} more milestone(s) hidden; increase --limit to show more.`));
   } catch (err) {
     handleApiError(err);
   }
@@ -1059,32 +1209,44 @@ Examples:
   $ atoll webhook list
   $ atoll webhook create --url https://example.com/hook --events issue.created,issue.updated
   $ atoll webhook delete <id>`);
-webhookCommand.command("list").description("List webhooks for the current org").action(async () => {
+webhookCommand.command("list").description("List webhooks for the current org").option("--limit <n>", "Max results (1-100)", parseInt).action(async (opts) => {
   try {
+    const limit = normalizeLimit(opts.limit);
     const client = new AtollClient();
     const orgId = await resolveOrgId2(client);
     const data = await client.get(`/api/webhooks?orgId=${orgId}`);
-    if (!process.stdout.isTTY || process.env.OUTPUT_FORMAT === "json") {
-      for (const wh of data.webhooks) {
-        process.stdout.write(JSON.stringify(wh) + "\n");
-      }
+    const allWebhooks = data.webhooks ?? [];
+    const webhooks = allWebhooks.slice(0, limit);
+    const truncated = allWebhooks.length > webhooks.length;
+    if (isJsonMode()) {
+      outputJson({
+        resource: "webhooks",
+        items: webhooks,
+        total: allWebhooks.length,
+        limit,
+        offset: 0,
+        nextOffset: null,
+        truncated,
+        hint: truncated ? "Increase --limit up to 100 to show more webhooks." : null
+      });
       return;
     }
-    if (data.webhooks.length === 0) {
+    if (webhooks.length === 0) {
       console.log("No webhooks configured.");
       return;
     }
     const header = bold(`${padEnd2("ID", 38)} ${padEnd2("URL", 40)} ${padEnd2("EVENTS", 20)} ACTIVE`);
     console.log(header);
     console.log("\u2500".repeat(100));
-    for (const wh of data.webhooks) {
+    for (const wh of webhooks) {
       const evts = wh.events.length === 0 ? "all" : wh.events.join(",");
       const active = wh.enabled ? green("yes") : gray("no");
       const url = wh.url.length > 38 ? wh.url.slice(0, 35) + "\u2026" : wh.url;
       const evtStr = evts.length > 18 ? evts.slice(0, 15) + "\u2026" : evts;
       console.log(`${padEnd2(wh.id.slice(0, 36), 38)} ${padEnd2(url, 40)} ${padEnd2(evtStr, 20)} ${active}`);
     }
-    console.log(dim(`${data.webhooks.length} webhook(s)`));
+    console.log(dim(`${webhooks.length} of ${allWebhooks.length} webhook(s)`));
+    if (truncated) console.log(dim(`${allWebhooks.length - webhooks.length} more webhook(s) hidden; increase --limit to show more.`));
   } catch (err) {
     handleApiError2(err);
   }
@@ -1115,9 +1277,20 @@ webhookCommand.command("create").description("Create a new webhook").requiredOpt
     handleApiError2(err);
   }
 });
-webhookCommand.command("delete <id>").description("Delete a webhook").action(async (id) => {
+webhookCommand.command("delete <id>").description("Delete a webhook").option("--force", "Delete the webhook").option("--dry-run", "Show what would be deleted without changing anything").action(async (id, opts) => {
   try {
+    if (!opts.dryRun && !opts.force) {
+      outputError("Webhook deletion requires --force.");
+      process.exit(2);
+    }
     const client = new AtollClient();
+    if (opts.dryRun) {
+      output(
+        { dryRun: true, wouldDelete: { type: "webhook", id } },
+        `Would delete webhook ${id}`
+      );
+      return;
+    }
     await client.delete(`/api/webhooks/${id}`);
     output(
       { success: true, id },
@@ -1128,24 +1301,405 @@ webhookCommand.command("delete <id>").description("Delete a webhook").action(asy
   }
 });
 
+// src/commands/heartbeat.ts
+var import_commander8 = require("commander");
+var VALID_SEVERITIES = ["critical", "warning", "info"];
+var heartbeatCommand = new import_commander8.Command("heartbeat").description("Get the current agent heartbeat briefing").option("--signals-only", "Only show heartbeat signals").option("--severity <severity>", `Filter signals by severity (${VALID_SEVERITIES.join(", ")})`).action(async (opts) => {
+  try {
+    if (opts.severity && !VALID_SEVERITIES.includes(opts.severity)) {
+      outputError(`Invalid severity "${opts.severity}". Must be one of: ${VALID_SEVERITIES.join(", ")}`);
+      process.exit(2);
+    }
+    const client = new AtollClient();
+    const org = await resolveOrg(client);
+    const context = await client.get(`/api/orgs/${org.id}/heartbeat`);
+    const signals = filterSignals(context.signals ?? [], opts.severity);
+    if (isJsonMode()) {
+      if (opts.signalsOnly) {
+        outputJson({ signals });
+        return;
+      }
+      outputJson({ ...context, signals });
+      return;
+    }
+    renderHeartbeat(context, signals, opts.signalsOnly ?? false);
+  } catch (err) {
+    handleApiError(err);
+  }
+});
+function filterSignals(signals, severity) {
+  if (!severity) return signals;
+  return signals.filter((signal) => signal.severity === severity);
+}
+function renderHeartbeat(context, signals, signalsOnly) {
+  const agentName = context.agent?.display_name || context.agent?.id || "agent";
+  console.log(bold(`Heartbeat for ${agentName}`));
+  if (context.timestamp) console.log(dim(context.timestamp));
+  console.log("");
+  renderSignals(signals);
+  if (signalsOnly) return;
+  const assigned = context.assigned_issues ?? [];
+  if (assigned.length > 0) {
+    console.log("");
+    console.log(bold("Assigned"));
+    for (const issue of assigned.slice(0, 10)) {
+      const id = issue.number == null ? issue.id.slice(0, 8) : `ATOLL-${issue.number}`;
+      console.log(`  ${pad(id, 10)} ${pad(issue.status, 13)} P${issue.priority}  ${issue.title}`);
+    }
+    if (assigned.length > 10) console.log(dim(`  ${assigned.length - 10} more assigned issue(s) hidden`));
+  }
+  const goals = context.goals ?? [];
+  if (goals.length > 0) {
+    console.log("");
+    console.log(bold("Goals"));
+    for (const goal of goals.slice(0, 5)) {
+      const title = goal.goal?.title ?? "(untitled goal)";
+      const days = goal.days_remaining == null ? "no deadline" : `${goal.days_remaining} days left`;
+      const kpis = goal.kpis ?? [];
+      const initiatives = goal.initiatives ?? [];
+      const offPace = kpis.filter((kpi) => kpi.is_off_pace).length;
+      const stale = kpis.filter((kpi) => kpi.is_stale).length;
+      const stalledOrBlocked = initiatives.filter(
+        (initiative) => (initiative.stalled_issues ?? 0) > 0 || (initiative.blocked_issues ?? 0) > 0
+      ).length;
+      console.log(`  ${title}  ${dim(days)}`);
+      console.log(dim(`    KPIs: ${offPace} off pace, ${stale} stale`));
+      console.log(dim(`    Initiatives: ${stalledOrBlocked} stalled/blocked`));
+    }
+    if (goals.length > 5) console.log(dim(`  ${goals.length - 5} more goal(s) hidden`));
+  }
+}
+function renderSignals(signals) {
+  if (signals.length === 0) {
+    console.log(gray("No heartbeat signals."));
+    return;
+  }
+  const groups = [
+    ["critical", "Critical"],
+    ["warning", "Warnings"],
+    ["info", "Info"]
+  ];
+  for (const [severity, label] of groups) {
+    const group = signals.filter((signal) => signal.severity === severity);
+    if (group.length === 0) continue;
+    console.log(formatSeverityHeading(severity, label));
+    for (const signal of group) {
+      console.log(`  ${pad(signal.type, 18)} ${signal.message}`);
+    }
+    if (severity !== "info") console.log("");
+  }
+}
+function formatSeverityHeading(severity, label) {
+  if (severity === "critical") return red(bold(label));
+  if (severity === "warning") return yellow(bold(label));
+  return cyan(bold(label));
+}
+function pad(value, length) {
+  return value.length >= length ? value.slice(0, length) : value + " ".repeat(length - value.length);
+}
+
+// src/commands/agent-context.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_commander9 = require("commander");
+init_config();
+var ISSUE_STATUSES = ["backlog", "todo", "in_progress", "done", "cancelled"];
+var PRIORITIES = [0, 1, 2, 3];
+var SEVERITIES = ["critical", "warning", "info"];
+var SIGNAL_TYPES = [
+  "kpi_off_pace",
+  "kpi_stale",
+  "issue_stale",
+  "issue_blocked",
+  "milestone_overdue",
+  "initiative_stalled",
+  "webhook_failing"
+];
+var agentContextCommand = new import_commander9.Command("agent-context").description("Output machine-readable CLI context for agents").action(() => {
+  const config = readConfig();
+  const resolved = resolveConfig();
+  const profiles = Object.entries(config.profiles ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([name, profile]) => ({
+    name,
+    active: name === config.activeProfile,
+    apiKeySet: Boolean(profile.apiKey),
+    orgSlug: profile.orgSlug ?? null,
+    defaultTeam: profile.defaultTeam ?? null,
+    baseUrl: profile.baseUrl ?? null
+  }));
+  outputJson({
+    schema_version: "1",
+    cli: {
+      name: "atoll",
+      json_flag: "--json",
+      output: {
+        stdout: "data",
+        stderr: "diagnostics_and_errors",
+        list_shape: "{ resource, items, total, limit, offset, nextOffset, truncated, hint }"
+      }
+    },
+    selected_context: {
+      activeProfile: config.activeProfile ?? null,
+      selectedProfile: resolved.profile ?? null,
+      orgSlug: resolved.orgSlug ?? null,
+      defaultTeam: resolved.defaultTeam ?? null,
+      baseUrl: resolved.baseUrl ?? null,
+      apiKeySet: Boolean(resolved.apiKey)
+    },
+    available_profiles: profiles,
+    commands: buildCommandContext(),
+    skill_manifests: findSkillManifests()
+  });
+});
+var skillPathCommand = new import_commander9.Command("skill-path").description("Output local Atoll skill manifest paths when available").action(() => {
+  outputJson({ skill_manifests: findSkillManifests() });
+});
+function buildCommandContext() {
+  return {
+    heartbeat: {
+      description: "Primary agent orientation command. Reads current goals, KPI pace, initiative health, assigned work, and prioritized signals.",
+      subcommands: {},
+      flags: {
+        "--signals-only": { type: "boolean", default: false },
+        "--severity": { type: "enum", values: SEVERITIES },
+        "--json": { type: "boolean", default: false }
+      },
+      signal_types: SIGNAL_TYPES
+    },
+    issue: {
+      subcommands: {
+        list: {
+          flags: {
+            "--status": { type: "enum", values: ISSUE_STATUSES },
+            "--assignee": { type: "string" },
+            "--priority": { type: "enum", values: PRIORITIES },
+            "--limit": { type: "integer", min: 1, max: 100, default: 25 },
+            "--offset": { type: "integer", min: 0, default: 0 },
+            "--json": { type: "boolean", default: false }
+          }
+        },
+        get: { alias_for: "view", args: ["identifier"], flags: { "--json": { type: "boolean", default: false } } },
+        view: { args: ["identifier"], flags: { "--json": { type: "boolean", default: false } } },
+        create: {
+          flags: {
+            "--title": { type: "string", required: true },
+            "--description": { type: "string" },
+            "--status": { type: "enum", values: ISSUE_STATUSES },
+            "--priority": { type: "enum", values: PRIORITIES },
+            "--json": { type: "boolean", default: false }
+          }
+        },
+        update: {
+          args: ["identifier"],
+          flags: {
+            "--title": { type: "string" },
+            "--status": { type: "enum", values: ISSUE_STATUSES },
+            "--priority": { type: "enum", values: PRIORITIES },
+            "--json": { type: "boolean", default: false }
+          }
+        },
+        archive: { args: ["identifier"], flags: { "--dry-run": { type: "boolean" }, "--json": { type: "boolean" } } },
+        unarchive: { args: ["identifier"], flags: { "--dry-run": { type: "boolean" }, "--json": { type: "boolean" } } },
+        delete: {
+          args: ["identifier"],
+          flags: {
+            "--force": { type: "boolean", required: true },
+            "--dry-run": { type: "boolean" },
+            "--json": { type: "boolean", default: false }
+          }
+        },
+        assign: { args: ["identifier"], flags: { "--to": { type: "string", required: true }, "--json": { type: "boolean" } } },
+        unassign: { args: ["identifier"], flags: { "--json": { type: "boolean" } } }
+      }
+    },
+    project: {
+      subcommands: {
+        list: { flags: { "--limit": { type: "integer", min: 1, max: 100, default: 25 }, "--json": { type: "boolean" } } },
+        get: { alias_for: "view", args: ["projectId"], flags: { "--json": { type: "boolean" } } },
+        view: { args: ["projectId"], flags: { "--json": { type: "boolean" } } },
+        create: {
+          flags: {
+            "--name": { type: "string", required: true },
+            "--description": { type: "string" },
+            "--color": { type: "string", default: "#6366f1" },
+            "--icon": { type: "string", default: "folder" },
+            "--json": { type: "boolean" }
+          }
+        }
+      }
+    },
+    comment: {
+      subcommands: {
+        list: { args: ["identifier"], flags: { "--limit": { type: "integer", min: 1, max: 100, default: 25 }, "--json": { type: "boolean" } } },
+        add: { args: ["identifier"], flags: { "--body": { type: "string", required: true }, "--json": { type: "boolean" } } },
+        update: {
+          args: ["comment-id"],
+          flags: { "--issue": { type: "string", required: true }, "--body": { type: "string", required: true }, "--json": { type: "boolean" } }
+        },
+        delete: {
+          args: ["comment-id"],
+          flags: {
+            "--issue": { type: "string", required: true },
+            "--force": { type: "boolean", required: true },
+            "--dry-run": { type: "boolean" },
+            "--json": { type: "boolean" }
+          }
+        }
+      }
+    },
+    feedback: {
+      description: "Record CLI or platform friction locally and optionally submit it upstream.",
+      subcommands: {
+        add: {
+          alias: "feedback <text>",
+          flags: {
+            "--type": { type: "enum", values: ["bug", "feature"], default: "bug" },
+            "--url": { type: "string" },
+            "--send": { type: "boolean", default: false },
+            "--json": { type: "boolean" }
+          }
+        },
+        list: { flags: { "--limit": { type: "integer", min: 1, max: 100, default: 25 }, "--json": { type: "boolean" } } }
+      }
+    }
+  };
+}
+function findSkillManifests() {
+  const repoRoot = (0, import_node_path2.resolve)(__dirname, "..", "..", "..");
+  const candidates = [
+    ["codex", (0, import_node_path2.join)(repoRoot, "packages", "skill-codex", "skill", "SKILL.md")],
+    ["claude", (0, import_node_path2.join)(repoRoot, "packages", "skill-claude", "skill", "SKILL.md")],
+    ["gemini", (0, import_node_path2.join)(repoRoot, "packages", "skill-gemini", "skill", "SKILL.md")],
+    ["clawhub", (0, import_node_path2.join)(repoRoot, "clawhub", "atoll-api", "SKILL.md")]
+  ];
+  return candidates.map(([name, path]) => ({ name, path, exists: (0, import_node_fs2.existsSync)(path) }));
+}
+
+// src/commands/feedback.ts
+var import_node_fs3 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path3 = require("path");
+var import_commander10 = require("commander");
+init_config();
+var CONFIG_DIR2 = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".atoll");
+var FEEDBACK_PATH = (0, import_node_path3.join)(CONFIG_DIR2, "feedback.jsonl");
+var VALID_TYPES = ["bug", "feature"];
+var DEFAULT_BASE_URL2 = "https://atollhq.com";
+var feedbackCommand = new import_commander10.Command("feedback").description("Record CLI or platform feedback").argument("[text...]", "Feedback text").option("--type <type>", `Feedback type (${VALID_TYPES.join(", ")})`, "bug").option("--url <url>", "Related page or endpoint URL").option("--send", "Also submit to the configured Atoll feedback endpoint").action(async (text, opts) => {
+  if (text.length === 0) {
+    outputError('Feedback text is required. Usage: atoll feedback "what went wrong"');
+    process.exit(2);
+  }
+  await recordFeedback(text.join(" "), opts);
+});
+feedbackCommand.command("add <text...>").description("Record feedback").option("--type <type>", `Feedback type (${VALID_TYPES.join(", ")})`, "bug").option("--url <url>", "Related page or endpoint URL").option("--send", "Also submit to the configured Atoll feedback endpoint").action(async (text, opts) => {
+  await recordFeedback(text.join(" "), opts);
+});
+feedbackCommand.command("list").description("List locally recorded feedback").option("--limit <n>", "Max results (1-100)", parseInt).action((opts) => {
+  const limit = normalizeLimit(opts.limit);
+  const entries = readFeedbackEntries().slice(-limit).reverse();
+  if (isJsonMode()) {
+    outputJson({
+      resource: "feedback",
+      items: entries,
+      total: readFeedbackEntries().length,
+      limit,
+      offset: 0,
+      nextOffset: null,
+      truncated: readFeedbackEntries().length > entries.length,
+      hint: null
+    });
+    return;
+  }
+  if (entries.length === 0) {
+    console.log("No local feedback recorded.");
+    return;
+  }
+  for (const entry of entries) {
+    const sent = entry.sent_upstream ? `sent:${entry.upstream_status}` : "local";
+    console.log(`${entry.created_at}  ${entry.type}  ${sent}`);
+    console.log(`  ${entry.description}`);
+    if (entry.url) console.log(dim(`  ${entry.url}`));
+  }
+});
+async function recordFeedback(description, opts) {
+  if (!VALID_TYPES.includes(opts.type)) {
+    outputError(`Invalid feedback type "${opts.type}". Must be one of: ${VALID_TYPES.join(", ")}`);
+    process.exit(2);
+  }
+  const entry = {
+    id: makeId(),
+    type: opts.type,
+    description,
+    url: opts.url ?? null,
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    sent_upstream: false,
+    upstream_status: null,
+    upstream_error: null
+  };
+  const endpoint = process.env.ATOLL_FEEDBACK_ENDPOINT || (opts.send ? `${resolveConfig().baseUrl || DEFAULT_BASE_URL2}/api/feedback` : null);
+  if (endpoint) {
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          type: entry.type,
+          description: entry.description,
+          url: entry.url ?? void 0,
+          userName: getReporterName()
+        })
+      });
+      entry.sent_upstream = response.ok;
+      entry.upstream_status = response.status;
+      if (!response.ok) entry.upstream_error = await response.text();
+    } catch (err) {
+      entry.upstream_error = err.message ?? String(err);
+    }
+  }
+  appendFeedbackEntry(entry);
+  output(
+    { feedback: entry },
+    entry.sent_upstream ? success(`Feedback recorded locally and sent upstream (${entry.upstream_status})`) : success("Feedback recorded locally")
+  );
+}
+function readFeedbackEntries() {
+  if (!(0, import_node_fs3.existsSync)(FEEDBACK_PATH)) return [];
+  return (0, import_node_fs3.readFileSync)(FEEDBACK_PATH, "utf-8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+function appendFeedbackEntry(entry) {
+  if (!(0, import_node_fs3.existsSync)(CONFIG_DIR2)) (0, import_node_fs3.mkdirSync)(CONFIG_DIR2, { recursive: true });
+  (0, import_node_fs3.appendFileSync)(FEEDBACK_PATH, JSON.stringify(entry) + "\n", "utf-8");
+}
+function getReporterName() {
+  const config = readConfig();
+  return process.env.ATOLL_PROFILE || config.activeProfile || void 0;
+}
+function makeId() {
+  return `fb_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
 // src/index.ts
 function readCliVersion() {
   try {
-    const packageJson = JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(__dirname, "..", "package.json"), "utf-8"));
+    const packageJson = JSON.parse((0, import_node_fs4.readFileSync)((0, import_node_path4.join)(__dirname, "..", "package.json"), "utf-8"));
     return packageJson.version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
-var program = new import_commander8.Command("atoll").description("Atoll CLI \u2014 project management from the terminal").version(readCliVersion()).addHelpText("after", `
+var program = new import_commander11.Command("atoll").description("Atoll CLI \u2014 project management from the terminal").version(readCliVersion()).addHelpText("after", `
 Examples:
   $ atoll issue list
   $ atoll issue create --title "Fix login bug" --priority 1
   $ atoll issue view ATOLL-42
+  $ atoll heartbeat
   $ atoll project list
   $ atoll milestone list --project <id>
-  $ atoll config show`).option("--profile <name>", "Use a saved auth profile (env: ATOLL_PROFILE)").option("--org <slug>", "Override default org slug (env: ATOLL_ORG)").option("--team <id>", "Override default team slug/ID (env: ATOLL_TEAM)").hook("preAction", (thisCommand) => {
-  const opts = thisCommand.opts();
+  $ atoll config show`).option("--profile <name>", "Use a saved auth profile (env: ATOLL_PROFILE)").option("--org <slug>", "Override default org slug (env: ATOLL_ORG)").option("--team <id>", "Override default team slug/ID (env: ATOLL_TEAM)").option("--json", "Emit machine-readable JSON").hook("preAction", (_thisCommand, actionCommand) => {
+  const opts = actionCommand.optsWithGlobals();
+  if (opts.json) {
+    enableJsonMode();
+  }
   if (opts.profile) {
     process.env.ATOLL_PROFILE = opts.profile;
   }
@@ -1165,7 +1719,11 @@ program.addCommand(projectCommand);
 program.addCommand(milestoneCommand);
 program.addCommand(configCommand);
 program.addCommand(webhookCommand);
-var completionCommand = new import_commander8.Command("completion").description("Output shell completion scripts").addHelpText("after", `
+program.addCommand(heartbeatCommand);
+program.addCommand(agentContextCommand);
+program.addCommand(skillPathCommand);
+program.addCommand(feedbackCommand);
+var completionCommand = new import_commander11.Command("completion").description("Output shell completion scripts").addHelpText("after", `
 Examples:
   $ atoll completion bash >> ~/.bashrc
   $ atoll completion zsh  >> ~/.zshrc`);
@@ -1176,6 +1734,7 @@ completionCommand.command("zsh").description("Output zsh completion script").act
   process.stdout.write(zshCompletion());
 });
 program.addCommand(completionCommand);
+addJsonOptionToSubcommands(program);
 program.parse();
 function bashCompletion() {
   return `# Atoll CLI bash completion
@@ -1185,13 +1744,14 @@ _atoll_completions() {
   local cur prev words cword
   _init_completion || return
 
-  local commands="auth issue comment project milestone config webhook completion"
-  local issue_cmds="list view create update delete assign unassign"
-  local project_cmds="list create view"
+  local commands="auth issue comment project milestone config webhook heartbeat agent-context skill-path feedback completion"
+  local issue_cmds="list view get create update archive unarchive delete assign unassign"
+  local project_cmds="list create view get"
   local milestone_cmds="list create"
   local config_cmds="show set-org set-team set-base-url"
   local auth_cmds="login logout status profiles use"
   local webhook_cmds="list create delete"
+  local feedback_cmds="add list"
   local completion_cmds="bash zsh"
 
   if [ "\${COMP_CWORD}" -eq 1 ]; then
@@ -1230,6 +1790,11 @@ _atoll_completions() {
         COMPREPLY=( $(compgen -W "\${webhook_cmds}" -- "\${cur}") )
       fi
       ;;
+    feedback)
+      if [ "\${COMP_CWORD}" -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "\${feedback_cmds}" -- "\${cur}") )
+      fi
+      ;;
     completion)
       if [ "\${COMP_CWORD}" -eq 2 ]; then
         COMPREPLY=( $(compgen -W "\${completion_cmds}" -- "\${cur}") )
@@ -1263,6 +1828,10 @@ _atoll() {
         'milestone[Manage milestones]' \\
         'config[Manage CLI configuration]' \\
         'webhook[Manage outbound webhooks]' \\
+        'heartbeat[Get agent heartbeat briefing]' \\
+        'agent-context[Output machine-readable CLI context]' \\
+        'skill-path[Output local Atoll skill manifest paths]' \\
+        'feedback[Record CLI or platform feedback]' \\
         'completion[Output shell completion scripts]'
       ;;
     args)
@@ -1271,7 +1840,10 @@ _atoll() {
           _values 'subcommand' \\
             'list[List issues]' \\
             'view[View issue details]' \\
+            'get[Get issue details]' \\
             'create[Create a new issue]' \\
+            'archive[Archive an issue]' \\
+            'unarchive[Unarchive an issue]' \\
             'update[Update an issue]' \\
             'delete[Delete an issue]' \\
             'assign[Assign an issue]' \\
@@ -1281,7 +1853,8 @@ _atoll() {
           _values 'subcommand' \\
             'list[List projects]' \\
             'create[Create a project]' \\
-            'view[View project details]'
+            'view[View project details]' \\
+            'get[Get project details]'
           ;;
         milestone)
           _values 'subcommand' \\
@@ -1309,6 +1882,11 @@ _atoll() {
             'create[Create a webhook]' \\
             'delete[Delete a webhook]'
           ;;
+        feedback)
+          _values 'subcommand' \\
+            'add[Record feedback]' \\
+            'list[List local feedback]'
+          ;;
         completion)
           _values 'shell' 'bash' 'zsh'
           ;;
@@ -1320,4 +1898,12 @@ _atoll() {
 _atoll "$@"
 `;
 }
+function addJsonOptionToSubcommands(command) {
+  for (const subcommand of command.commands) {
+    if (!subcommand.options.some((option) => option.long === "--json")) {
+      subcommand.option("--json", "Emit machine-readable JSON");
+    }
+    addJsonOptionToSubcommands(subcommand);
+  }
+}
 //# sourceMappingURL=index.js.map