@corners/cli 0.0.3 → 0.0.5

package/dist/cli.js

@@ -4,8 +4,9 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { CornersApiClient as DefaultCornersApiClient, } from "./client.js";
 import { ConfigStore, LOCAL_ROOT_CONFIG_RELATIVE_PATH, } from "./config.js";
+import { buildExpectedManagedGuidanceBlock, buildGuidanceFileContent, buildGuidanceRevision, extractManagedGuidanceBlock, GUIDANCE_SYNC_COMMAND, GUIDANCE_TARGETS, normalizeGuidanceTargets, } from "./guidance.js";
 import { createPromptApi } from "./prompts.js";
-import { CLIError, getPackageVersion, normalizeApiUrl, openUrlInBrowser, printJson, printLine, readTextFromStdin, sleep, toGraphQLAttachmentKind, toGraphQLWorkstreamUpdateType, toIsoString, } from "./support.js";
+import { CLIError, getPackageVersion, normalizeApiUrl, openUrlInBrowser, printJson, printLine, readTextFromStdin, sleep, toGraphQLAttachmentKind, toGraphQLWorkstreamStatus, toGraphQLWorkstreamUpdateType, toIsoString, } from "./support.js";
 const WORKSTREAM_LOOKUP_QUERY = `
   query CliWorkstreamLookup($id: ID!) {
     workstream(id: $id) {
@@ -13,9 +14,11 @@ const WORKSTREAM_LOOKUP_QUERY = `
       accountId
       cornerId
       name
+      isOpen
       summary
       category
       status
+      statusDetails
       updatedAt
       topic {
         id
@@ -31,9 +34,11 @@ const WORKSTREAM_PULL_QUERY = `
       accountId
       cornerId
       name
+      isOpen
       summary
       category
       status
+      statusDetails
       createdAt
       updatedAt
       firstAttachmentActivityAt
@@ -283,6 +288,26 @@ const RECORD_WORKSTREAM_UPDATE_MUTATION = `
     }
   }
 `;
+const UPDATE_WORKSTREAM_MUTATION = `
+  mutation CliUpdateWorkstream($id: ID!, $input: UpdateWorkstreamInput!) {
+    updateWorkstream(id: $id, input: $input) {
+      id
+      accountId
+      cornerId
+      name
+      isOpen
+      summary
+      category
+      status
+      statusDetails
+      updatedAt
+      topic {
+        id
+        name
+      }
+    }
+  }
+`;
 const REVOKE_MCP_SESSION_MUTATION = `
   mutation CliRevokeMcpSession($id: ID!) {
     revokeMCPSession(id: $id)
@@ -318,9 +343,11 @@ const CREATE_WORKSTREAM_MUTATION = `
       id
       cornerId
       name
+      isOpen
       summary
       category
       status
+      statusDetails
       updatedAt
       topic {
         id
@@ -351,10 +378,11 @@ function printMainHelp(runtime) {
         "",
         "Commands:",
         "  auth login|logout|status",
+        "  guidance status|sync",
         "  init",
         "  corner use",
         "  whoami",
-        "  workstream (ws) list|use|current|create|pull|push|question|attach|reply-thread",
+        "  workstream (ws) list|use|current|create|pull|update|push|question|attach|reply-thread",
         "  help",
         "  version",
         "",
@@ -375,6 +403,15 @@ function printInitHelp(runtime) {
         "  corners init [--profile <name>] [--api-url <url>] [--json]",
     ].join("\n"));
 }
+function printGuidanceHelp(runtime) {
+    printLine(runtime.stdout, [
+        "corners guidance",
+        "",
+        "Usage:",
+        "  corners guidance status [--json]",
+        "  corners guidance sync [--json]",
+    ].join("\n"));
+}
 function printAuthHelp(runtime) {
     printLine(runtime.stdout, [
         "corners auth",
@@ -411,6 +448,7 @@ function printWorkstreamHelp(runtime) {
         "  corners workstream current [--json]",
         "  corners workstream create <name> [--summary <text>] [--corner <cornerNameOrId>] [--json]",
         "  corners workstream pull <workstreamId> [--json]",
+        "  corners workstream update <workstreamId> [--status <status>] [--status-details <text> | --clear-status-details] [--json]",
         "  corners workstream push <workstreamId> [--type <type>] [--message <text>] [--summary <text>] [--file <path>] [--title <title>] [--json]",
         "  corners workstream question list <workstreamId> [--json]",
         "  corners workstream question ask <workstreamId> [--question <text>] [--rationale <text>] [--suggested-answer <text>]... [--json]",
@@ -418,6 +456,9 @@ function printWorkstreamHelp(runtime) {
         "  corners workstream attach <workstreamId> --kind <kind> --entity-id <id> [--json]",
         "  corners workstream reply-thread <threadId> [--text <text>] [--json]",
         "",
+        "Lifecycle statuses:",
+        "  scoping | in_progress | blocked | done",
+        "",
         "Update types:",
         "  status | blocker | learning | outcome",
     ].join("\n"));
@@ -693,14 +734,104 @@ function resolveCornerForCwd(root, cwd) {
         corner: resolveCornerForRelativePath(root.config, relativePath),
     };
 }
-async function requireLocalRoot(runtime, common) {
+async function resolveGuidanceState(root) {
+    const expectedBlock = buildExpectedManagedGuidanceBlock();
+    const fileEntries = await Promise.all(GUIDANCE_TARGETS.map(async (target) => ({
+        target,
+        content: await readOptionalUtf8(join(root.rootDir, target.relativePath)),
+    })));
+    const discoveredManagedTargets = GUIDANCE_TARGETS.map((target) => target.key).filter((key) => {
+        const entry = fileEntries.find((candidate) => candidate.target.key === key);
+        return extractManagedGuidanceBlock(entry?.content ?? null) !== null;
+    });
+    const configuredManagedTargets = root.config.guidance?.managedTargets;
+    const managedTargets = configuredManagedTargets !== undefined
+        ? normalizeGuidanceTargets(configuredManagedTargets)
+        : discoveredManagedTargets;
+    const files = fileEntries.map(({ target, content }) => {
+        if (content === null) {
+            return {
+                target: target.key,
+                path: target.relativePath,
+                state: "missing",
+            };
+        }
+        if (!managedTargets.includes(target.key)) {
+            return {
+                target: target.key,
+                path: target.relativePath,
+                state: "unmanaged",
+            };
+        }
+        return {
+            target: target.key,
+            path: target.relativePath,
+            state: extractManagedGuidanceBlock(content) === expectedBlock
+                ? "current"
+                : "stale",
+        };
+    });
+    const staleFiles = files
+        .filter((file) => file.state === "stale")
+        .map((file) => file.path);
+    return {
+        stale: staleFiles.length > 0,
+        lastSyncedAt: root.config.guidance?.syncedAt ?? null,
+        managedTargets,
+        staleFiles,
+        files,
+    };
+}
+function buildGuidanceWarning(guidance) {
+    if (!guidance.stale) {
+        return null;
+    }
+    const syncedSuffix = guidance.lastSyncedAt
+        ? ` Last synced: ${guidance.lastSyncedAt}.`
+        : "";
+    return `Warning: managed Corners guidance is out of date in ${guidance.staleFiles.length} file(s).${syncedSuffix} Run \`${GUIDANCE_SYNC_COMMAND}\`.`;
+}
+function buildGuidanceJsonMetadata(guidance) {
+    return {
+        stale: guidance.stale,
+        lastSyncedAt: guidance.lastSyncedAt,
+        staleFiles: guidance.staleFiles,
+        syncCommand: GUIDANCE_SYNC_COMMAND,
+    };
+}
+function withGuidanceJsonMetadata(payload, guidance) {
+    if (!guidance) {
+        return payload;
+    }
+    return {
+        ...payload,
+        _corners: {
+            guidance: buildGuidanceJsonMetadata(guidance),
+        },
+    };
+}
+async function resolveRootContext(runtime, common, root, options) {
+    const guidance = await resolveGuidanceState(root);
+    if ((options?.emitWarning ?? true) && !common.json) {
+        const warning = buildGuidanceWarning(guidance);
+        if (warning) {
+            printLine(runtime.stderr, warning);
+        }
+    }
+    return {
+        root,
+        guidance,
+    };
+}
+async function requireLocalRoot(runtime, common, options) {
     const root = await runtime.config.findLocalRoot(runtime.cwd);
     if (!root) {
         throw new CLIError("No local Corners CLI root found. Run `corners init` from your project root first.", { json: common.json });
     }
-    return root;
+    return resolveRootContext(runtime, common, root, options);
 }
-async function requirePinnedRootProfile(runtime, common, root) {
+async function requirePinnedRootProfile(runtime, common, rootContext) {
+    const { root, guidance } = rootContext;
     if (common.profile && common.profile !== root.config.profile) {
         throw new CLIError(`This initialized root is pinned to profile ${root.config.profile}.`, { json: common.json });
     }
@@ -724,6 +855,7 @@ async function requirePinnedRootProfile(runtime, common, root) {
     };
     return {
         root,
+        guidance,
         profileName: selected.name,
         profile,
         client: runtime.createClient({
@@ -735,11 +867,13 @@ async function requirePinnedRootProfile(runtime, common, root) {
 async function requireCommandProfile(runtime, common) {
     const root = await runtime.config.findLocalRoot(runtime.cwd);
     if (root) {
-        return requirePinnedRootProfile(runtime, common, root);
+        const rootContext = await resolveRootContext(runtime, common, root);
+        return requirePinnedRootProfile(runtime, common, rootContext);
     }
     const selected = await requireStoredProfile(runtime, common);
     return {
         root: null,
+        guidance: null,
         ...selected,
     };
 }
@@ -805,55 +939,6 @@ function upsertCornerOverride(config, relativePath, corner) {
         cornerOverrides: overrides,
     };
 }
-const GUIDANCE_SECTION_START = "<!-- corners-cli:start -->";
-const GUIDANCE_SECTION_END = "<!-- corners-cli:end -->";
-function buildGuidanceSection() {
-    return [
-        "## Corners CLI",
-        "",
-        "Corners CLI usage is local to each user. These shared instructions describe how AI should use the CLI, not which corners or workstreams a user has selected locally.",
-        "",
-        "- Only assume Corners CLI is initialized when `.corners/config.json` exists locally in the current repo root or an ancestor folder.",
-        "- The current folder selects the default corner through local path rules managed by `corners corner use`.",
-        "- Create new workstreams with `corners workstream create`.",
-        "- Connect existing workstreams to the local environment with `corners workstream use <workstreamId>`.",
-        "- Pass explicit workstream IDs to `corners workstream pull`, `push`, `question`, and `attach` commands.",
-        "- `corners workstream list` shows the workstreams connected for the current local environment.",
-        "",
-        "If `.corners/config.json` is absent, do not assume the repo is initialized for the current user.",
-    ].join("\n");
-}
-function upsertManagedSection(existing, section) {
-    const block = `${GUIDANCE_SECTION_START}\n${section}\n${GUIDANCE_SECTION_END}`;
-    const startIndex = existing.indexOf(GUIDANCE_SECTION_START);
-    const endIndex = existing.indexOf(GUIDANCE_SECTION_END);
-    if (startIndex >= 0 && endIndex > startIndex) {
-        return ensureTrailingNewline(`${existing.slice(0, startIndex).trimEnd()}\n\n${block}\n${existing
-            .slice(endIndex + GUIDANCE_SECTION_END.length)
-            .trimStart()}`.trim());
-    }
-    const trimmed = existing.trim();
-    if (!trimmed) {
-        return ensureTrailingNewline(block);
-    }
-    return ensureTrailingNewline(`${trimmed}\n\n${block}`);
-}
-function buildGuidanceFileContent(target, existing) {
-    const section = buildGuidanceSection();
-    if (target === "cursor") {
-        const base = existing?.trim()
-            ? existing
-            : [
-                "---",
-                "description: Corners CLI guidance",
-                "alwaysApply: true",
-                "---",
-                "",
-            ].join("\n");
-        return upsertManagedSection(base, section);
-    }
-    return upsertManagedSection(existing ?? "", section);
-}
 async function buildPlannedEdit(path, nextContent) {
     const existing = await readOptionalUtf8(path);
     if (existing === nextContent) {
@@ -865,6 +950,16 @@ async function buildPlannedEdit(path, nextContent) {
         content: nextContent,
     };
 }
+function withUpdatedGuidanceConfig(config, managedTargets, syncedAt) {
+    return {
+        ...config,
+        guidance: {
+            managedTargets: normalizeGuidanceTargets(managedTargets),
+            syncedAt,
+            revision: buildGuidanceRevision(),
+        },
+    };
+}
 function ensureGitignoreEntry(existing) {
     const content = existing ?? "";
     const lines = content
@@ -889,7 +984,16 @@ async function writePlannedEdits(edits) {
     }
 }
 function formatWorkstreamLine(workstream) {
-    return `${workstream.id}  ${workstream.name}  ${workstream.status.toLowerCase()}${workstream.summary ? `  ${workstream.summary}` : ""}`;
+    return [
+        workstream.id,
+        workstream.name,
+        workstream.isOpen ? "open" : "archived",
+        workstream.status.toLowerCase(),
+        workstream.statusDetails ?? null,
+        workstream.summary ? workstream.summary : null,
+    ]
+        .filter((part) => Boolean(part))
+        .join("  ");
 }
 async function handleAuth(args, runtime, inherited) {
     const subcommand = args[0];
@@ -1191,30 +1295,8 @@ async function handleInit(args, runtime, inherited) {
     const rootDir = existingRoot?.rootDir ?? currentRootPath;
     const existingConfig = existingRoot?.config ?? null;
     return withPrompts(runtime, async (prompts) => {
-        const guidanceTargets = [
-            {
-                key: "agents",
-                label: "Manage AGENTS.md guidance",
-                relativePath: "AGENTS.md",
-            },
-            {
-                key: "claude",
-                label: "Manage CLAUDE.md guidance",
-                relativePath: "CLAUDE.md",
-            },
-            {
-                key: "cursor",
-                label: "Manage Cursor rule guidance",
-                relativePath: ".cursor/rules/corners-cli.mdc",
-            },
-            {
-                key: "copilot",
-                label: "Manage Copilot instructions",
-                relativePath: ".github/copilot-instructions.md",
-            },
-        ];
         const selectedTargets = [];
-        for (const target of guidanceTargets) {
+        for (const target of GUIDANCE_TARGETS) {
             const include = await prompts.confirm(target.label, {
                 defaultValue: true,
             });
@@ -1230,7 +1312,8 @@ async function handleInit(args, runtime, inherited) {
         });
         const defaultCorner = joinedCorners.find((corner) => corner.id === selectedCornerId) ??
             joinedCorners[0];
-        const nextLocalConfig = {
+        const syncedAt = toIsoString();
+        const nextLocalConfig = withUpdatedGuidanceConfig({
             version: 1,
             profile: profileName,
             workspace: profile.workspace,
@@ -1241,7 +1324,7 @@ async function handleInit(args, runtime, inherited) {
             },
             cornerOverrides: existingConfig?.cornerOverrides ?? [],
             connectedWorkstreams: existingConfig?.connectedWorkstreams ?? [],
-        };
+        }, selectedTargets.map((target) => target.key), syncedAt);
         const plannedEdits = [];
         const gitignorePath = join(rootDir, ".gitignore");
         const gitignoreContent = ensureGitignoreEntry(await readOptionalUtf8(gitignorePath));
@@ -1302,11 +1385,132 @@ async function handleInit(args, runtime, inherited) {
             printJson(runtime.stdout, payload);
         }
         else {
-            printLine(runtime.stdout, `Initialized Corners CLI at ${rootDir} with default corner ${defaultCorner.name}.`);
+            printLine(runtime.stdout, `Initialized Corners CLI at ${rootDir} with default corner ${defaultCorner.name}. Run \`${GUIDANCE_SYNC_COMMAND}\` later to refresh managed guidance.`);
         }
         return 0;
     });
 }
+async function handleGuidance(args, runtime, inherited) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === "help" || subcommand === "--help") {
+        printGuidanceHelp(runtime);
+        return 0;
+    }
+    switch (subcommand) {
+        case "status": {
+            const parsed = parseArgs({
+                args: args.slice(1),
+                allowPositionals: false,
+                options: {
+                    json: { type: "boolean" },
+                    help: { type: "boolean", short: "h" },
+                },
+            });
+            const common = mergeCommonOptions(inherited, {
+                json: parsed.values.json,
+            });
+            if (parsed.values.help) {
+                printGuidanceHelp(runtime);
+                return 0;
+            }
+            const rootContext = await requireLocalRoot(runtime, common, {
+                emitWarning: false,
+            });
+            const payload = {
+                ok: true,
+                root: rootContext.root.rootDir,
+                guidance: rootContext.guidance,
+            };
+            if (common.json) {
+                printJson(runtime.stdout, payload);
+            }
+            else {
+                printLine(runtime.stdout, [
+                    `Root: ${payload.root}`,
+                    `Stale: ${payload.guidance.stale ? "yes" : "no"}`,
+                    `Last synced: ${payload.guidance.lastSyncedAt ?? "-"}`,
+                    `Managed targets: ${payload.guidance.managedTargets.join(", ") || "-"}`,
+                    ...payload.guidance.files.map((file) => `${file.path}: ${file.state}`),
+                ].join("\n"));
+            }
+            return 0;
+        }
+        case "sync": {
+            const parsed = parseArgs({
+                args: args.slice(1),
+                allowPositionals: false,
+                options: {
+                    json: { type: "boolean" },
+                    help: { type: "boolean", short: "h" },
+                },
+            });
+            const common = mergeCommonOptions(inherited, {
+                json: parsed.values.json,
+            });
+            if (parsed.values.help) {
+                printGuidanceHelp(runtime);
+                return 0;
+            }
+            const rootContext = await requireLocalRoot(runtime, common, {
+                emitWarning: false,
+            });
+            const managedTargets = rootContext.root.config.guidance?.managedTargets !== undefined
+                ? normalizeGuidanceTargets(rootContext.root.config.guidance.managedTargets)
+                : rootContext.guidance.managedTargets;
+            const edits = [];
+            const actions = new Map();
+            for (const target of GUIDANCE_TARGETS) {
+                if (!managedTargets.includes(target.key)) {
+                    actions.set(target.key, "skipped");
+                    continue;
+                }
+                const targetPath = join(rootContext.root.rootDir, target.relativePath);
+                const nextContent = buildGuidanceFileContent(target.key, await readOptionalUtf8(targetPath));
+                const edit = await buildPlannedEdit(targetPath, nextContent);
+                if (edit) {
+                    edits.push(edit);
+                    actions.set(target.key, edit.action);
+                }
+                else {
+                    actions.set(target.key, "unchanged");
+                }
+            }
+            if (edits.length > 0) {
+                await writePlannedEdits(edits);
+            }
+            const syncedAt = toIsoString();
+            const nextConfig = withUpdatedGuidanceConfig(rootContext.root.config, managedTargets, syncedAt);
+            await runtime.config.writeLocalConfig(rootContext.root.rootDir, nextConfig);
+            const nextRoot = {
+                ...rootContext.root,
+                config: nextConfig,
+            };
+            const nextGuidance = await resolveGuidanceState(nextRoot);
+            const guidance = {
+                ...nextGuidance,
+                files: nextGuidance.files.map((file) => ({
+                    ...file,
+                    action: actions.get(file.target) ?? "skipped",
+                })),
+            };
+            const payload = {
+                ok: true,
+                root: nextRoot.rootDir,
+                guidance,
+            };
+            if (common.json) {
+                printJson(runtime.stdout, payload);
+            }
+            else {
+                const updatedCount = guidance.files.filter((file) => file.action === "create" || file.action === "update").length;
+                printLine(runtime.stdout, `Synchronized Corners guidance at ${payload.root}. Updated ${updatedCount} file(s).`);
+            }
+            return 0;
+        }
+        default:
+            throw new CLIError(`Unknown guidance command: ${subcommand}`);
+    }
+}
 async function handleCorner(args, runtime, inherited) {
     const subcommand = args[0];
     if (!subcommand || subcommand === "help" || subcommand === "--help") {
@@ -1339,8 +1543,8 @@ async function handleCorner(args, runtime, inherited) {
             if (!cornerNameOrId) {
                 throw new CLIError("Usage: corners corner use <cornerNameOrId> [--path <path>]", { json: common.json });
             }
-            const root = await requireLocalRoot(runtime, common);
-            const { client } = await requirePinnedRootProfile(runtime, common, root);
+            const rootContext = await requireLocalRoot(runtime, common);
+            const { root, guidance, client } = await requirePinnedRootProfile(runtime, common, rootContext);
             const corner = await resolveMemberCorner(client, common, cornerNameOrId);
             const cwdPath = await realpath(runtime.cwd);
             const targetAbsolutePath = resolvePathWithinRoot(root.rootDir, cwdPath, parsed.values.path);
@@ -1351,12 +1555,12 @@ async function handleCorner(args, runtime, inherited) {
             });
             await runtime.config.writeLocalConfig(root.rootDir, nextConfig);
             if (common.json) {
-                printJson(runtime.stdout, {
+                printJson(runtime.stdout, withGuidanceJsonMetadata({
                     ok: true,
                     root: root.rootDir,
                     path: relativePath,
                     corner,
-                });
+                }, guidance));
             }
             else {
                 printLine(runtime.stdout, `Set default corner for ${relativePath} to ${corner.name}.`);
@@ -1394,8 +1598,8 @@ async function handleWorkstream(args, runtime, inherited) {
                 printWorkstreamHelp(runtime);
                 return 0;
             }
-            const root = await requireLocalRoot(runtime, common);
-            const { client } = await requirePinnedRootProfile(runtime, common, root);
+            const rootContext = await requireLocalRoot(runtime, common);
+            const { root, guidance, client } = await requirePinnedRootProfile(runtime, common, rootContext);
             const hydrated = await Promise.all(root.config.connectedWorkstreams.map(async (entry) => {
                 try {
                     return {
@@ -1417,11 +1621,11 @@ async function handleWorkstream(args, runtime, inherited) {
                 .filter((entry) => entry.workstream === null)
                 .map((entry) => entry.entry.id);
             if (common.json) {
-                printJson(runtime.stdout, {
+                printJson(runtime.stdout, withGuidanceJsonMetadata({
                     root: root.rootDir,
                     workstreams,
                     missingWorkstreamIds,
-                });
+                }, guidance));
             }
             else {
                 if (missingWorkstreamIds.length > 0) {
@@ -1461,19 +1665,19 @@ async function handleWorkstream(args, runtime, inherited) {
                     json: common.json,
                 });
             }
-            const root = await requireLocalRoot(runtime, common);
-            const { client } = await requirePinnedRootProfile(runtime, common, root);
+            const rootContext = await requireLocalRoot(runtime, common);
+            const { root, guidance, client } = await requirePinnedRootProfile(runtime, common, rootContext);
             const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
             const nextConfig = connectWorkstream(root.config, workstream.id);
             if (nextConfig !== root.config) {
                 await runtime.config.writeLocalConfig(root.rootDir, nextConfig);
             }
             if (common.json) {
-                printJson(runtime.stdout, {
+                printJson(runtime.stdout, withGuidanceJsonMetadata({
                     ok: true,
                     root: root.rootDir,
                     workstream,
-                });
+                }, guidance));
             }
             else {
                 printLine(runtime.stdout, `Connected ${workstream.id} (${workstream.name}) to ${root.rootDir}.`);
@@ -1496,7 +1700,7 @@ async function handleWorkstream(args, runtime, inherited) {
                 printWorkstreamHelp(runtime);
                 return 0;
             }
-            const root = await requireLocalRoot(runtime, common);
+            const { root, guidance } = await requireLocalRoot(runtime, common);
             const cwdPath = await realpath(runtime.cwd);
             const resolvedCorner = resolveCornerForCwd(root, cwdPath);
             const payload = {
@@ -1508,7 +1712,7 @@ async function handleWorkstream(args, runtime, inherited) {
                 connectedWorkstreamIds: root.config.connectedWorkstreams.map((entry) => entry.id),
             };
             if (common.json) {
-                printJson(runtime.stdout, payload);
+                printJson(runtime.stdout, withGuidanceJsonMetadata(payload, guidance));
             }
             else {
                 printLine(runtime.stdout, [
@@ -1548,8 +1752,8 @@ async function handleWorkstream(args, runtime, inherited) {
             if (!name) {
                 throw new CLIError("Usage: corners workstream create <name> [--summary <text>] [--corner <cornerNameOrId>]", { json: common.json });
             }
-            const root = await requireLocalRoot(runtime, common);
-            const { client } = await requirePinnedRootProfile(runtime, common, root);
+            const rootContext = await requireLocalRoot(runtime, common);
+            const { root, guidance, client } = await requirePinnedRootProfile(runtime, common, rootContext);
             const cwdPath = await realpath(runtime.cwd);
             const corner = parsed.values.corner
                 ? await resolveMemberCorner(client, common, parsed.values.corner)
@@ -1566,12 +1770,12 @@ async function handleWorkstream(args, runtime, inherited) {
                 await runtime.config.writeLocalConfig(root.rootDir, nextConfig);
             }
             if (common.json) {
-                printJson(runtime.stdout, {
+                printJson(runtime.stdout, withGuidanceJsonMetadata({
                     ok: true,
                     root: root.rootDir,
                     corner,
                     workstream: result.createWorkstream,
-                });
+                }, guidance));
             }
             else {
                 printLine(runtime.stdout, `Created ${result.createWorkstream.id} (${result.createWorkstream.name}) in ${corner.name}.`);
@@ -1604,7 +1808,7 @@ async function handleWorkstream(args, runtime, inherited) {
                     json: common.json,
                 });
             }
-            const { client } = await requireCommandProfile(runtime, common);
+            const { guidance, client } = await requireCommandProfile(runtime, common);
             const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
             const data = await client.graphql(WORKSTREAM_PULL_QUERY, {
                 id: workstream.id,
@@ -1612,13 +1816,16 @@ async function handleWorkstream(args, runtime, inherited) {
                 feedFirst: 20,
             });
             if (common.json) {
-                printJson(runtime.stdout, data.workstream);
+                printJson(runtime.stdout, withGuidanceJsonMetadata(data.workstream, guidance));
             }
             else {
                 const snapshot = data.workstream;
                 printLine(runtime.stdout, [
                     `${snapshot.name} (${snapshot.id})`,
                     snapshot.summary ? `Summary: ${snapshot.summary}` : "Summary: -",
+                    `State: ${snapshot.isOpen === false ? "archived" : "open"}`,
+                    `Lifecycle status: ${(snapshot.status ?? "SCOPING").toLowerCase()}`,
+                    `Status details: ${snapshot.statusDetails ?? "-"}`,
                     `Open questions: ${snapshot.openQuestions?.length ?? 0}`,
                     `Answered questions: ${snapshot.answeredQuestions?.length ?? 0}`,
                     `Attachments: ${snapshot.attachments?.totalCount ?? 0}`,
@@ -1627,6 +1834,75 @@ async function handleWorkstream(args, runtime, inherited) {
             }
             return 0;
         }
+        case "update": {
+            const parsed = parseArgs({
+                args: args.slice(1),
+                allowPositionals: true,
+                options: {
+                    json: { type: "boolean" },
+                    help: { type: "boolean", short: "h" },
+                    profile: { type: "string" },
+                    "api-url": { type: "string" },
+                    status: { type: "string" },
+                    "status-details": { type: "string" },
+                    "clear-status-details": { type: "boolean" },
+                },
+            });
+            const common = mergeCommonOptions(inherited, {
+                json: parsed.values.json,
+                profile: parsed.values.profile,
+                apiUrl: parsed.values["api-url"],
+            });
+            if (parsed.values.help) {
+                printWorkstreamHelp(runtime);
+                return 0;
+            }
+            const workstreamId = parsed.positionals[0];
+            if (!workstreamId) {
+                throw new CLIError("Usage: corners workstream update <workstreamId> [--status <status>] [--status-details <text> | --clear-status-details]", { json: common.json });
+            }
+            const rawStatusDetails = parsed.values["status-details"];
+            const clearStatusDetails = parsed.values["clear-status-details"] === true;
+            if (rawStatusDetails !== undefined && clearStatusDetails) {
+                throw new CLIError("Choose either --status-details or --clear-status-details, not both.", { json: common.json });
+            }
+            if (parsed.values.status === undefined &&
+                rawStatusDetails === undefined &&
+                !clearStatusDetails) {
+                throw new CLIError("Provide --status, --status-details, or --clear-status-details.", { json: common.json });
+            }
+            const { guidance, client } = await requireCommandProfile(runtime, common);
+            const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
+            const result = await client.graphql(UPDATE_WORKSTREAM_MUTATION, {
+                id: workstream.id,
+                input: {
+                    status: parsed.values.status === undefined
+                        ? undefined
+                        : toGraphQLWorkstreamStatus(parsed.values.status),
+                    statusDetails: clearStatusDetails
+                        ? null
+                        : rawStatusDetails === undefined
+                            ? undefined
+                            : rawStatusDetails,
+                },
+            });
+            const payload = {
+                ok: true,
+                workstream: result.updateWorkstream,
+            };
+            if (common.json) {
+                printJson(runtime.stdout, withGuidanceJsonMetadata(payload, guidance));
+            }
+            else {
+                printLine(runtime.stdout, [
+                    `Updated ${result.updateWorkstream.id}.`,
+                    `State: ${result.updateWorkstream.isOpen ? "open" : "archived"}`,
+                    `Lifecycle status: ${result.updateWorkstream.status.toLowerCase()}`,
+                    `Status details: ${result.updateWorkstream.statusDetails ?? "-"}`,
+                ].join("\n"));
+            }
+            return 0;
+        }
         case "push": {
             const parsed = parseArgs({
                 args: args.slice(1),
@@ -1665,7 +1941,7 @@ async function handleWorkstream(args, runtime, inherited) {
             if (!message) {
                 throw new CLIError("Workstream updates need a message. Use --message or pipe text on stdin.", { json: common.json });
             }
-            const { client } = await requireCommandProfile(runtime, common);
+            const { guidance, client } = await requireCommandProfile(runtime, common);
             const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
             let createdDocument = null;
             if (parsed.values.file) {
@@ -1696,7 +1972,7 @@ async function handleWorkstream(args, runtime, inherited) {
                 document: createdDocument,
             };
             if (common.json) {
-                printJson(runtime.stdout, payload);
+                printJson(runtime.stdout, withGuidanceJsonMetadata(payload, guidance));
             }
             else {
                 printLine(runtime.stdout, `Recorded ${String(parsed.values.type ?? "status")} update on ${workstream.id}.`);
@@ -1734,7 +2010,7 @@ async function handleWorkstream(args, runtime, inherited) {
                     if (!workstreamId) {
                         throw new CLIError("Usage: corners workstream question list <workstreamId>", { json: common.json });
                     }
-                    const { client } = await requireCommandProfile(runtime, common);
+                    const { guidance, client } = await requireCommandProfile(runtime, common);
                     const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
                     const data = await client.graphql(WORKSTREAM_QUESTION_LIST_QUERY, {
                         id: workstream.id,
@@ -1743,7 +2019,7 @@ async function handleWorkstream(args, runtime, inherited) {
                         throw new CLIError("Workstream not found", { json: common.json });
                     }
                     if (common.json) {
-                        printJson(runtime.stdout, data.workstream);
+                        printJson(runtime.stdout, withGuidanceJsonMetadata(data.workstream, guidance));
                     }
                     else {
                         printLine(runtime.stdout, [
@@ -1789,7 +2065,7 @@ async function handleWorkstream(args, runtime, inherited) {
                     if (!question) {
                         throw new CLIError("Question text is required. Use --question or pipe text on stdin.", { json: common.json });
                     }
-                    const { client } = await requireCommandProfile(runtime, common);
+                    const { guidance, client } = await requireCommandProfile(runtime, common);
                     const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
                     const result = await client.graphql(CREATE_WORKSTREAM_QUESTION_MUTATION, {
                         input: {
@@ -1800,7 +2076,7 @@ async function handleWorkstream(args, runtime, inherited) {
                         },
                     });
                     if (common.json) {
-                        printJson(runtime.stdout, result.createWorkstreamQuestion);
+                        printJson(runtime.stdout, withGuidanceJsonMetadata(result.createWorkstreamQuestion, guidance));
                     }
                     else {
                         printLine(runtime.stdout, `Created question on ${workstream.id}.`);
@@ -1841,13 +2117,13 @@ async function handleWorkstream(args, runtime, inherited) {
                             json: common.json,
                         });
                     }
-                    const { client } = await requireCommandProfile(runtime, common);
+                    const { guidance, client } = await requireCommandProfile(runtime, common);
                     const result = await client.graphql(ANSWER_WORKSTREAM_QUESTION_MUTATION, {
                         questionId,
                         answerText: answer,
                     });
                     if (common.json) {
-                        printJson(runtime.stdout, result.answerWorkstreamQuestion);
+                        printJson(runtime.stdout, withGuidanceJsonMetadata(result.answerWorkstreamQuestion, guidance));
                     }
                     else {
                         printLine(runtime.stdout, `Answered ${questionId}.`);
@@ -1886,7 +2162,7 @@ async function handleWorkstream(args, runtime, inherited) {
             if (!workstreamId || !kind || !entityId) {
                 throw new CLIError("Usage: corners workstream attach <workstreamId> --kind <kind> --entity-id <id>", { json: common.json });
             }
-            const { client } = await requireCommandProfile(runtime, common);
+            const { guidance, client } = await requireCommandProfile(runtime, common);
             const workstream = await resolveExplicitWorkstream(client, common, workstreamId);
             const result = await client.graphql(ADD_WORKSTREAM_ATTACHMENT_MUTATION, {
                 workstreamId: workstream.id,
@@ -1894,7 +2170,7 @@ async function handleWorkstream(args, runtime, inherited) {
                 entityId,
             });
             if (common.json) {
-                printJson(runtime.stdout, result.addWorkstreamAttachment);
+                printJson(runtime.stdout, withGuidanceJsonMetadata(result.addWorkstreamAttachment, guidance));
             }
             else {
                 printLine(runtime.stdout, `Attached ${kind}:${entityId} to ${workstream.id}.`);
@@ -1930,7 +2206,7 @@ async function handleWorkstream(args, runtime, inherited) {
             if (!threadId || !text) {
                 throw new CLIError("Usage: corners workstream reply-thread <threadId> [--text <text>]", { json: common.json });
             }
-            const { client } = await requireCommandProfile(runtime, common);
+            const { guidance, client } = await requireCommandProfile(runtime, common);
             const result = await client.graphql(REPLY_ARTIFACT_THREAD_MUTATION, {
                 id: threadId,
                 input: {
@@ -1938,7 +2214,7 @@ async function handleWorkstream(args, runtime, inherited) {
                 },
             });
             if (common.json) {
-                printJson(runtime.stdout, result.replyArtifactThread);
+                printJson(runtime.stdout, withGuidanceJsonMetadata(result.replyArtifactThread, guidance));
             }
             else {
                 printLine(runtime.stdout, `Replied to ${threadId}.`);
@@ -1970,6 +2246,9 @@ export async function runCli(argv, runtime = createRuntime()) {
             if (parsed.rest[1] === "auth") {
                 printAuthHelp(runtime);
             }
+            else if (parsed.rest[1] === "guidance") {
+                printGuidanceHelp(runtime);
+            }
             else if (parsed.rest[1] === "init") {
                 printInitHelp(runtime);
             }
@@ -1991,6 +2270,8 @@ export async function runCli(argv, runtime = createRuntime()) {
             return 0;
         case "init":
             return handleInit(parsed.rest.slice(1), runtime, parsed.common);
+        case "guidance":
+            return handleGuidance(parsed.rest.slice(1), runtime, parsed.common);
         case "auth":
             return handleAuth(parsed.rest.slice(1), runtime, parsed.common);
         case "corner":