@xqyz/xq-cli 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -10,6 +10,22 @@
 
 ## [Unreleased]
 
+### WorkBuddy
+
+- 修复计划模式默认值：未提供 `planMode` 时明确使用快速（`--plan-mode 0`），用户明确选择规划时保留 `--plan-mode 1`，不再发生模式被错误回退的问题。
+- 准备发布 WorkBuddy Plugin/Connector `0.9.4`：恢复配置页“计划模式=快速/规划”选择，并将用户选择原样传递给 xq-cli。
+- 统一 Skill、安装脚本、MCP Server 和 Connector 的版本指向，避免继续加载 `0.9.3` 的快速模式固定包。
+- 新增 [版本与迭代记录](./docs/VERSION-HISTORY.md)，记录 xq-cli、Plugin、Connector 的功能、依赖、测试和发布结果。
+
+## [0.3.0] - 2026-08-14
+
+### xq-cli
+
+- 新增 `xq-cli plan` 规划模式命令链，覆盖补充/修正信息、确认生成/重新生成大纲、AI 调整大纲候选、确认采用候选、生成最终目录、重新生成目录、目录查看/修改和正文续写。
+- 补充/修正与 AI 调整结果先保存在本地任务状态，只有在用户明确确认 `plan confirm-outline` 或 `plan directory-generate` / `plan directory-regenerate` 后才会触发对应后台写入或生成请求。
+- AI 大纲候选不再生成本地伪章节 ID；最终保存请求与前端一致，仅提交章节内容、主题、重要度和续写标记，交由后台分配节点 ID。
+- 增加规划模式模拟 API 回归测试，覆盖意见提交、AI 候选不提前落库、候选确认和最终目录生成的顺序。
+
 ## [0.2.1] - 2026-08-11
 
 ### 安全性

package/README.md

@@ -7,6 +7,7 @@ Project execution rules for agents live in [AGENTS.md](./AGENTS.md). That file d
 Project maintenance documents:
 
 - [Version changelog](./CHANGELOG.md)
+- [Version and iteration history](./docs/VERSION-HISTORY.md)
 - [Release process](./docs/RELEASING.md)
 
 ## Install from npm
@@ -53,7 +54,8 @@ npm install -g .\xqyz-xq-cli-0.2.0.tgz
 ```bash
 xq-cli login
 xq-cli login --name your-account --password your-password
-xq-cli login --base-url https://xqai.atest.qianlima.com/api --browser
+xq-cli login --api-key xq_sk_xxx
+xq-cli login --browser
 xq-cli wizard
 xq-cli wizard --file D:\bids\tender.docx
 xq-cli init --file D:\bids\tender.docx --wait
@@ -72,9 +74,9 @@ xq-cli export --cid <cid> --interactive --out D:\output
 xq-cli export --cid <cid> --out D:\output
 ```
 
-Fresh installs default to the production API address `https://ai.bidfile.qianlima.com/api`. Use `--base-url` only when you need to target another environment such as `https://xqai.atest.qianlima.com/api`.
+Fresh installs default to the production API address `https://ai.bidfile.qianlima.com/api`. Use `--base-url` only when you need to target another API endpoint.
 
-`login` now defaults to browser authorization. If you explicitly pass `--name` and `--password`, the CLI falls back to password login.
+`login` now defaults to browser authorization. If you explicitly pass `--name` and `--password`, the CLI falls back to password login. If you pass `--api-key`, it saves the API key locally and uses it for later requests.
 
 `directory view` reads the complete generated directory tree without triggering outline, directory, or content generation. Add `--json` for the raw API structure, or `--out <file-or-directory>` to save a UTF-8 JSON document.
 
@@ -128,6 +130,39 @@ xq-cli outline update --cid <cid> --file D:\output\outline.json --yes --allow-de
 
 The update command automatically calculates `updateFlag` by comparing the edited file with the latest server outline. Changes to chapter titles or themes may cause the backend to regenerate affected child directories asynchronously.
 
+## 完整规划模式流程
+
+规划模式不是一次命令跑到底，而是把前端的“智能解读 → 大纲 → 目录 → 正文”拆成可恢复的阶段。先用普通 `outline --plan-mode planning` 启动任务；拿到 `cid` 后，用 `plan` 子命令推进后续阶段：
+
+```bash
+# 1. 补充或修正招标文件理解（只写入本地待提交区，不会请求后台）
+xq-cli plan status --cid <cid> --json
+xq-cli plan feedback --cid <cid> --text "补充项目实施边界" --quote "原文片段"
+xq-cli plan correction --cid <cid> --file D:\output\corrections.json
+
+# 2. 用户确认后，提交意见并生成/重新生成大纲
+xq-cli plan confirm-outline --cid <cid> --yes --wait --json
+
+# 3. 查看大纲；需要 AI 调整时先生成候选，不会立即改后台
+xq-cli plan outline-view --cid <cid> --json
+xq-cli plan outline-ai-adjust --cid <cid> --prompt "拆分实施方案和质量保障" --out D:\output
+xq-cli plan outline-ai-apply --cid <cid> --file D:\output\outline-ai-<cid>.json --yes
+
+# 4. 用户确认候选大纲后，保存大纲并生成最终目录（不会生成正文）
+xq-cli plan directory-generate --cid <cid> --yes --wait
+
+# 5. 查看/编辑目录；如果需要重新生成目录，必须明确确认
+xq-cli plan directory-view --cid <cid> --json
+xq-cli plan directory-update --cid <cid> --file D:\output\directory.json --dry-run
+xq-cli plan directory-regenerate --cid <cid> --yes --wait
+
+# 6. 目录确认后才开始正文和导出
+xq-cli plan write --cid <cid> --wait
+xq-cli export --cid <cid> --out D:\output
+```
+
+要点：`plan status` 是恢复和重跑前的权威入口；`plan feedback` / `plan correction` 只写本地暂存，不会重复请求后台；`plan outline-ai-adjust` 会请求 AI 但只返回候选，`plan outline-ai-apply` 仍只写本地候选且不带伪造章节 ID。只有 `plan confirm-outline`、`plan directory-generate` / `plan directory-regenerate` 明确确认后才会产生后台写入或启动阶段；首次目录必须使用 `directory-generate`，已有目录覆盖才使用 `directory-regenerate`。
+
 ## Interactive menus
 
 Use the full wizard if you want a CLI flow close to the frontend configuration panel:
@@ -155,6 +190,55 @@ xq-cli outline --cid <cid> --interactive --wait
 xq-cli export --cid <cid> --interactive --out D:\output
 ```
 
+## Agent / Codex usage
+
+When another agent (Codex, OpenCLI, or an MCP wrapper) invokes `xq-cli`, it
+must treat bid generation as a stateful sequence rather than a single command:
+
+```text
+init (source file) -> outline (confirmed config + plan mode) -> review
+-> directory review (planning mode) -> write -> export
+```
+
+`--plan-mode` belongs on `outline`, not on `write` or `export`:
+
+- `0` / `quick`: enter outline generation quickly; use when the user requests
+  a quick first run or explicitly chooses 快速.
+- `1` / `planning`: enable the backend's fuller planning phase; it can take
+  longer, so use `--wait` and do not shorten the polling timeout. Use the
+  dedicated `plan` commands to collect corrections, review AI candidates,
+  generate/re-generate the directory, and stop at every confirmation gate.
+
+The backend may report `plan_mode_phase=0..3` (`analysis`, `outline`,
+`directory`, `content`) while polling. This is progress information, not a
+subcommand. If the CLI returns `reference_selection_required` or
+`supplement_required`, stop and ask the user for the required choice/input;
+never invent it. `outline view` is read-only and safe for verification.
+
+For planning mode, the agent must pause at three human confirmation gates:
+
+1. collect any `plan feedback` / `plan correction`, then call
+   `plan confirm-outline` only after the user confirms generation;
+2. show the outline. `plan outline-ai-adjust` returns an editable candidate,
+   and `plan outline-ai-apply` accepts it locally without writing the backend;
+3. after the user confirms the final outline, call `plan directory-generate`,
+   show the directory, and wait for final directory confirmation before
+   `plan write`.
+
+Use `plan directory-regenerate` only after an explicit request to replace the
+existing directory. It is not a retry/status command. Fast mode has only the
+outline confirmation gate and can then proceed to `write`.
+
+For non-TTY or JSON automation, do not silently choose generation settings.
+Ask for the missing configuration, print the final summary, wait for a clear
+confirmation (`确认`, `开始`, or `就按这个跑`), then run the commands. Validate
+enum values with `xq-cli choices outline --json` and
+`xq-cli choices export --json` before constructing arguments. See
+[`AGENTS.md`](./AGENTS.md) for the complete confirmation order and value map.
+For the complete meaning of every outline/export choice, defaults, image-style
+dependencies, EPC/multi-bid rules, margins, colors, and `--style-json`, see
+[`docs/AGENT-PARAMETER-GUIDE.md`](./docs/AGENT-PARAMETER-GUIDE.md).
+
 ## Config choices
 
 `xq-cli` now exposes the same major bid-book generation settings that the frontend outline/download flow uses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xqyz/xq-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "CLI for xique bid-book task workflows",
   "type": "module",
   "scripts": {

package/src/cli.mjs

@@ -205,6 +205,12 @@ const PLAN_MODE_OPTIONS = [
     { value: 0, label: 'quick', description: 'quick mode', aliases: ['0', 'quick'] },
     { value: 1, label: 'planning', description: 'planning mode', aliases: ['1', 'planning', 'plan'] },
 ];
+const PLAN_MODE_PHASE_LABELS = {
+    0: 'analysis',
+    1: 'outline',
+    2: 'directory',
+    3: 'content',
+};
 const LAYOUT_OPTIONS = [
     { value: 0, label: 'normal', description: 'regular layout', aliases: ['0', 'normal', 'default'] },
     { value: 1, label: 'table', description: 'full table layout', aliases: ['1', 'table'] },
@@ -338,6 +344,12 @@ async function main() {
         case 'parse-status':
             await handleParseStatus(parsed, state);
             return;
+        case 'period-status':
+            await handlePeriodStatus(parsed, state);
+            return;
+        case 'period-confirm':
+            await handlePeriodConfirm(parsed, state);
+            return;
         case 'outline':
             if (isOutlineAction(parsed, ['view', 'show'])) {
                 await handleOutlineView(parsed, state);
@@ -354,7 +366,9 @@ async function main() {
             await handleOutlineUpdate(parsed, state);
             return;
         case 'directory':
-            if (!parsed._[1] || isOutlineAction(parsed, ['view', 'show'])) {
+            if (isOutlineAction(parsed, ['update', 'edit'])) {
+                await handleDirectoryUpdate(parsed, state);
+            } else if (!parsed._[1] || isOutlineAction(parsed, ['view', 'show'])) {
                 await handleDirectoryView(parsed, state);
             } else {
                 throw new Error(`Unknown directory action: ${parsed._[1]}`);
@@ -363,6 +377,12 @@ async function main() {
         case 'directory-view':
             await handleDirectoryView(parsed, state);
             return;
+        case 'directory-prepare':
+            await handleDirectoryPrepare(parsed, state);
+            return;
+        case 'directory-update':
+            await handleDirectoryUpdate(parsed, state);
+            return;
         case 'write':
             await handleWrite(parsed, state);
             return;
@@ -381,6 +401,9 @@ async function main() {
         case 'wizard':
             await handleWizard(parsed, state);
             return;
+        case 'plan':
+            await handlePlan(parsed, state);
+            return;
         default:
             throw new Error(`Unsupported command: ${command}. Run "xq-cli help" to see available commands.`);
     }
@@ -391,24 +414,41 @@ function printHelp() {
 xq-cli: xique brand task CLI
 
 Commands
-  login         Save xique account token locally
+  login         Save xique API key or account token locally
   init          Upload files and initialize a task
   parse-status  Query or wait for parse completion
+  period-status Query engineering project period confirmation status
+  period-confirm Save confirmed engineering project period
   outline       Pre-set task params and trigger outline generation
   outline view  View the current outline without triggering generation
   outline update Update the current outline from an edited JSON file
   directory view View the complete generated directory tree without triggering generation
+  directory update Apply an edited directory tree JSON file
+  directory-prepare Prepare/wait for the generated directory without starting body generation
   write         Charge if needed, enter content phase, and trigger content generation
+  plan          Run an explicit planning-mode phase (feedback, outline, AI review, directory)
   status        Query task status
   choices       Print selectable outline/export config values
   gallery-status Check whether My Gallery contains selectable images
   wizard        Run init -> outline -> write -> export with interactive menus
   export        Download the generated docx
 
+Plan actions
+  feedback|supplement|correction  Stage user additions/corrections locally
+  confirm-outline                 Submit staged feedback and generate the outline
+  outline-view                    View the current outline
+  outline-ai-adjust               Ask AI for an outline candidate (no server write)
+  outline-ai-apply                Accept a candidate locally for the directory step
+  directory-generate              Save the confirmed outline and generate the final directory
+  directory-regenerate            Explicitly replace and regenerate an existing directory
+  directory-view|directory-update Review or edit the directory
+
 Examples
   xq-cli login
   xq-cli login --name your-account --password your-password
-  xq-cli login --base-url https://xqai.atest.qianlima.com/api --browser
+  xq-cli login --api-key xq_sk_xxx
+  xq-cli login --browser
+  $env:XQ_API_KEY="xq_sk_xxx"
   xq-cli init --file D:\\bids\\tender.docx --wait
   xq-cli parse-status --cid <cid> --uuid <uuid> --wait
   xq-cli choices
@@ -429,6 +469,14 @@ Examples
   xq-cli outline update --cid <cid> --file D:\\output\\outline.json --yes
   xq-cli directory view --cid <cid>
   xq-cli directory view --cid <cid> --out D:\\output\\directory.json
+  xq-cli directory update --cid <cid> --file D:\\output\\directory.json --yes
+  xq-cli plan status --cid <cid> --json
+  xq-cli plan feedback --cid <cid> --text "Add the missing service boundary"
+  xq-cli plan confirm-outline --cid <cid> --yes --wait
+  xq-cli plan outline-ai-adjust --cid <cid> --prompt "Split chapter 2 into implementation and quality control" --out D:\\output\\
+  xq-cli plan outline-ai-apply --cid <cid> --file D:\\output\\outline-ai-<cid>.json --yes
+  xq-cli plan directory-generate --cid <cid> --yes --wait
+  xq-cli plan directory-regenerate --cid <cid> --yes --wait
   xq-cli write --cid <cid> --type 1 --wait
   xq-cli status --cid <cid> --content
   xq-cli export --cid <cid> --interactive --out D:\\output\\
@@ -442,6 +490,7 @@ Common options
   --interval-sec <n> Poll interval in seconds, default 10
   --reference-type <0|1|2>  Outline reference choice: 0=merge, 1=format only, 2=score only
   --browser          Force browser authorization login; browser is the default when credentials are not provided
+  --api-key <key>    Save a user API key locally and verify it with /user/info
   --interactive      Open prompt menus for the current command
   --dry-run          Preview an outline update without saving it
   --yes              Confirm an outline update without an interactive prompt
@@ -504,6 +553,33 @@ async function handleLogin(args, state) {
         throw new Error('Missing base URL. Pass --base-url <url>.');
     }
     const sourceFrom = stringOption(args, 'sourceFrom', DEFAULT_SOURCE_FROM);
+    const apiKey = normalizeApiKey(stringOption(args, 'apiKey'));
+    if (apiKey) {
+        const result = await loginWithApiKey(baseUrl, apiKey);
+        saveLoginState(state, {
+            baseUrl,
+            name: result.data?.username || result.data?.userName || result.data?.user?.username || state.user?.name || '',
+            sourceFrom,
+            result,
+            apiKey,
+            authType: 'api-key',
+            user: result.data || {},
+        });
+        outputResult(args, {
+            command: 'login',
+            mode: 'api-key',
+            authType: 'api-key',
+            baseUrl,
+            username: state.user.username,
+            apiKeySaved: true,
+        }, [
+            `login success: ${state.user.username}`,
+            'mode: api-key',
+            `baseUrl: ${baseUrl}`,
+            `config: ${CONFIG_FILE}`,
+        ]);
+        return;
+    }
     const loginMode = resolveLoginMode(args);
     const result = loginMode === 'browser'
         ? await loginWithBrowser(baseUrl, sourceFrom, args)
@@ -519,6 +595,7 @@ async function handleLogin(args, state) {
     outputResult(args, {
         command: 'login',
         mode: loginMode,
+        authType: loginMode === 'browser' ? 'token' : 'token',
         baseUrl,
         username: state.user.username,
         tokenSaved: true,
@@ -534,11 +611,19 @@ function resolveLoginMode(args) {
     if (booleanOption(args, 'browser')) {
         return 'browser';
     }
+    if (stringOption(args, 'apiKey')) {
+        return 'api-key';
+    }
     const hasName = stringOption(args, 'name');
     const hasPassword = stringOption(args, 'password');
     return hasName || hasPassword ? 'password' : 'browser';
 }
 
+async function loginWithApiKey(baseUrl, apiKey) {
+    const client = createClient(baseUrl, apiKey);
+    return getJson(client, '/user/info');
+}
+
 async function loginWithPassword(baseUrl, sourceFrom, args) {
     const name = requiredOption(args, 'name');
     const password = requiredOption(args, 'password');
@@ -680,6 +765,72 @@ async function handleParseStatus(args, state) {
     ]);
 }
 
+async function handlePeriodStatus(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const response = await getJson(client, `/engineering/checkPeriod/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT });
+    const data = response?.data || {};
+    saveTaskSnapshot(state, cid, {
+        periodStatus: data.status,
+        contractPeriod: data.contractPeriod,
+        contractStartDate: data.contractStartDate,
+        contractEndDate: data.contractEndDate,
+    });
+    const payload = { command: 'period-status', cid, ...data };
+    outputResult(args, payload, [
+        `period status: cid=${cid}`,
+        `status: ${data.status ?? '-'}`,
+        data.status === 2
+            ? `confirmation required: period=${data.contractPeriod ?? '-'}, start=${data.contractStartDate ?? '-'}, end=${data.contractEndDate ?? '-'}`
+            : data.status === 1
+                ? 'period confirmation not required or already confirmed'
+                : 'period extraction is still running',
+    ]);
+    return payload;
+}
+
+async function handlePeriodConfirm(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const contractPeriod = numberOption(args, 'contractPeriod');
+    if (!Number.isInteger(contractPeriod) || contractPeriod <= 0) {
+        throw new Error('Option --contract-period expects a positive integer.');
+    }
+    const periodMode = numberOption(args, 'periodMode', 2);
+    if (![1, 2].includes(periodMode)) {
+        throw new Error('Option --period-mode expects 1 (known dates) or 2 (unknown dates).');
+    }
+    const contractStartDate = periodMode === 1
+        ? requiredOption(args, 'contractStartDate')
+        : 'Day1';
+    const contractEndDate = periodMode === 1
+        ? requiredOption(args, 'contractEndDate')
+        : `Day${contractPeriod}`;
+    const response = await postJson(client, '/engineering/resetPeriod', {
+        cid,
+        contractPeriod,
+        contractStartDate,
+        contractEndDate,
+        periodMode,
+    });
+    saveTaskSnapshot(state, cid, {
+        periodStatus: 2,
+        contractPeriod,
+        contractStartDate,
+        contractEndDate,
+        periodMode,
+    });
+    const payload = { command: 'period-confirm', cid, contractPeriod, contractStartDate, contractEndDate, periodMode, response };
+    outputResult(args, payload, [
+        `period confirmed: cid=${cid}`,
+        `contract period: ${contractPeriod}`,
+        `start: ${contractStartDate}`,
+        `end: ${contractEndDate}`,
+        `period mode: ${periodMode === 1 ? 'known dates' : 'unknown dates'}`,
+    ]);
+    return payload;
+}
+
 function handleChoices(args) {
     const scope = normalizeChoicesScope(args._[1] || 'all');
     const payload = buildChoicesPayload(scope);
@@ -763,6 +914,336 @@ async function handleWizard(args, state) {
     return resultPayload;
 }
 
+async function handlePlan(args, state) {
+    const action = String(args?._?.[1] || 'status').trim().toLowerCase();
+    switch (action) {
+        case 'status':
+        case 'show':
+            await handlePlanStatus(args, state);
+            return;
+        case 'feedback':
+        case 'supplement':
+        case 'correction':
+            await handlePlanFeedback(args, state);
+            return;
+        case 'confirm-outline':
+        case 'outline-confirm':
+        case 'generate-outline':
+        case 'regenerate-outline':
+            await handlePlanOutlineConfirmation(args, state);
+            return;
+        case 'outline-ai-adjust':
+        case 'ai-adjust':
+        case 'ai-outline':
+            await handlePlanAiOutlineAdjust(args, state);
+            return;
+        case 'outline-ai-apply':
+        case 'ai-apply':
+            await handlePlanAiOutlineApply(args, state);
+            return;
+        case 'outline-view':
+            await handleOutlineView({ ...args, _: ['outline', 'view'] }, state);
+            return;
+        case 'outline-update':
+            await handleOutlineUpdate({ ...args, _: ['outline', 'update'] }, state);
+            return;
+        case 'directory-generate':
+        case 'generate-directory':
+            await handlePlanDirectoryGenerate(args, state, false);
+            return;
+        case 'directory-regenerate':
+        case 'regenerate-directory':
+            await handlePlanDirectoryGenerate(args, state, true);
+            return;
+        case 'directory-view':
+            await handleDirectoryView({ ...args, _: ['directory', 'view'] }, state);
+            return;
+        case 'directory-update':
+            await handleDirectoryUpdate({ ...args, _: ['directory', 'update'] }, state);
+            return;
+        case 'write':
+        case 'generate-content':
+            await handleWrite({ ...args, _: ['write'] }, state);
+            return;
+        default:
+            throw new Error(`Unknown plan action: ${action}. Run "xq-cli help" to see planning-mode commands.`);
+    }
+}
+
+async function handlePlanStatus(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const [taskResponse, outlineResponse, contentResponse] = await Promise.all([
+        getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT }),
+        fetchOutlineDetail(client, cid),
+        fetchContentDetail(client, cid),
+    ]);
+    const taskDetail = taskResponse?.data || {};
+    const outlineDetail = outlineResponse?.data || {};
+    const contentDetail = contentResponse?.data || {};
+    const phase = normalizePlanModePhase(taskDetail.plan_mode_phase);
+    const payload = {
+        command: 'plan-status',
+        cid,
+        planMode: normalizePlanModeValue(taskDetail.planMode),
+        planModePhase: phase,
+        phaseLabel: phase === null ? null : PLAN_MODE_PHASE_LABELS[phase],
+        taskDetail,
+        outlineDetail,
+        contentDetail,
+        pendingFeedback: normalizePlanFeedback(state.tasks?.[cid]?.planFeedback).length,
+    };
+    saveTaskSnapshot(state, cid, pickTaskSnapshot({ ...taskDetail, ...contentDetail }));
+    outputResult(args, payload, [
+        `plan status: cid=${cid}`,
+        `planMode: ${describeEnumValue(PLAN_MODE_OPTIONS, normalizePlanModeValue(taskDetail.planMode) ?? taskDetail.planMode)}`,
+        `phase: ${formatPlanModePhase(phase)}`,
+        `outline: ${outlineDetail.outline_status ? 'ready' : 'not-ready'} (${countOutlineRoots({ outlineDetail })} root chapters)`,
+        `directory: task_status=${contentDetail.task_status ?? taskDetail.task_status ?? '-'}, directory_status=${contentDetail.directory_portion_status ?? taskDetail.directory_portion_status ?? '-'}`,
+        `pending feedback: ${payload.pendingFeedback}`,
+    ]);
+    return payload;
+}
+
+async function handlePlanFeedback(args, state) {
+    const cid = resolveCid(args, state);
+    const task = state.tasks?.[cid] || {};
+    if (booleanOption(args, 'clear')) {
+        saveTaskSnapshot(state, cid, { planFeedback: [] });
+        const payload = { command: 'plan-feedback', cid, cleared: true, feedback: [] };
+        outputResult(args, payload, [`plan feedback cleared: cid=${cid}`]);
+        return payload;
+    }
+
+    const feedback = readPlanFeedbackArgs(args);
+    if (feedback.length === 0) {
+        throw new Error('Plan feedback requires --text <message>, --correction <message>, or --file <feedback.json>.');
+    }
+    const merged = mergePlanFeedback(normalizePlanFeedback(task.planFeedback), feedback);
+    saveTaskSnapshot(state, cid, {
+        planFeedback: merged,
+        // New feedback means the accepted AI candidate is no longer based on
+        // the latest analysis and must not be reused accidentally.
+        planAiOutlineCandidate: undefined,
+    });
+    const payload = {
+        command: 'plan-feedback',
+        cid,
+        added: feedback,
+        pendingFeedback: merged,
+    };
+    outputResult(args, payload, [
+        `plan feedback saved locally: cid=${cid}`,
+        `pending feedback: ${merged.length}`,
+        'feedback is not sent to the backend yet; it will be included only after plan confirm-outline is explicitly confirmed.',
+    ]);
+    return payload;
+}
+
+async function handlePlanOutlineConfirmation(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const snapshot = await hydrateTaskSnapshot(client, state, cid);
+    const params = buildOutlineParams(snapshot, { ...args, planMode: 'planning' });
+    const regenerating = booleanOption(args, 'regenerate') || normalizePlanModePhase(snapshot.plan_mode_phase) >= 1;
+    const feedback = normalizePlanFeedback(state.tasks?.[cid]?.planFeedback);
+
+    await confirmPlanAction(args, regenerating ? 'regenerate outline' : 'confirm and generate outline', [
+        `config: ${buildOutlineConfigSummary(params)}`,
+        `pending feedback: ${feedback.length}`,
+    ]);
+
+    await postJson(client, '/task/preSet', params);
+    const phaseResponse = await setPlanModePhase(client, cid, 1);
+    const response = await postJson(client, '/task/generateDirectoryByCid', compactObject({
+        cid,
+        chatList: feedback.length > 0
+            ? feedback.map(item => ({ quote_paragraph: item.quote, user_comments: item.text }))
+            : undefined,
+        triggerType: 1,
+    }));
+    saveTaskSnapshot(state, cid, {
+        ...pickTaskSnapshot(params),
+        planModePhase: 1,
+        planFeedback: [],
+        planAiOutlineCandidate: undefined,
+        planOutlineConfirmedAt: new Date().toISOString(),
+        planOutlineRegeneratedAt: regenerating ? new Date().toISOString() : undefined,
+    });
+
+    const waitResult = booleanOption(args, 'wait')
+        ? await waitForOutlineReady(client, state, cid, snapshot.uuid, args)
+        : null;
+    const payload = {
+        command: 'plan-confirm-outline',
+        cid,
+        regenerating,
+        config: pickOutlineConfig(params),
+        feedback,
+        planModePhase: phaseResponse,
+        response,
+        waitResult,
+    };
+    outputResult(args, payload, [
+        `plan outline ${regenerating ? 'regeneration' : 'generation'} started: cid=${cid}`,
+        `phase: ${formatPlanModePhase(phaseResponse)}`,
+        `feedback submitted: ${feedback.length}`,
+        waitResult?.phase === 'ready'
+            ? `outline ready: ${countOutlineRoots(waitResult)} root chapters; review or use plan outline-ai-adjust before generating the final directory.`
+            : 'outline generation started; query plan status or rerun with --wait to review it when ready.',
+    ]);
+    return payload;
+}
+
+async function handlePlanAiOutlineAdjust(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const prompt = requiredOption(args, 'prompt').trim();
+    if (!prompt) {
+        throw new Error('Option --prompt cannot be empty.');
+    }
+    const task = state.tasks?.[cid] || {};
+    const response = await postJson(client, '/outline/chat', compactObject({
+        cid,
+        prompt,
+        conversationId: stringOption(args, 'conversationId', task.planAiConversationId),
+    }));
+    const result = response?.data?.result || response?.result || {};
+    const conversationId = result.conversationId || response?.data?.conversationId || response?.conversationId || '';
+    if (conversationId) {
+        saveTaskSnapshot(state, cid, { planAiConversationId: conversationId });
+    }
+    const rows = extractPlanAiOutlineRows(result.answer);
+    const candidate = rows.length > 0
+        ? buildPlanAiOutlineCandidate(cid, prompt, conversationId, rows)
+        : null;
+    const savedPath = candidate && stringOption(args, 'out')
+        ? writePlanAiOutlineFile(stringOption(args, 'out'), cid, candidate)
+        : null;
+    const payload = {
+        command: 'plan-outline-ai-adjust',
+        cid,
+        prompt,
+        conversationId: conversationId || null,
+        responseType: result.type ?? null,
+        message: rows.length === 0 ? normalizeText(result.answer) : null,
+        candidate,
+        savedPath,
+    };
+    outputResult(args, payload, [
+        `plan AI response: cid=${cid}, type=${result.type ?? '-'}`,
+        rows.length > 0
+            ? `AI outline candidate: ${rows.length} chapter(s), not saved to the backend.`
+            : `AI message: ${normalizeText(result.answer) || 'no outline candidate returned'}`,
+        savedPath
+            ? `candidate saved: ${savedPath}`
+            : (rows.length > 0 ? 'hint: pass --out <file-or-directory> to save the candidate before applying it.' : ''),
+    ].filter(Boolean));
+    return payload;
+}
+
+async function handlePlanAiOutlineApply(args, state) {
+    const cid = resolveCid(args, state);
+    const filePath = path.resolve(requiredOption(args, 'file'));
+    const document = readOutlineEditFile(filePath);
+    validateOutlineEditCid(document, cid, filePath);
+    const rows = buildPlanAiOutlineUpdateRows(extractOutlineRows(document));
+    if (booleanOption(args, 'dryRun')) {
+        const payload = { command: 'plan-outline-ai-apply', cid, file: filePath, dryRun: true, applied: false, candidate: { cid, outLine: rows } };
+        outputResult(args, payload, [
+            `AI outline apply preview: cid=${cid}`,
+            `chapters: ${rows.length}`,
+            'dry-run only: the candidate was not accepted locally or sent to the backend.',
+        ]);
+        return payload;
+    }
+    await confirmPlanAction(args, 'accept AI outline candidate', [
+        `candidate file: ${filePath}`,
+        `chapters: ${rows.length}`,
+        'the candidate remains local until the final-directory step is explicitly confirmed.',
+    ]);
+    saveTaskSnapshot(state, cid, {
+        planAiOutlineCandidate: {
+            format: 'xq-cli-plan-ai-outline@1',
+            cid,
+            acceptedAt: new Date().toISOString(),
+            sourceFile: filePath,
+            outLine: rows,
+        },
+    });
+    const payload = { command: 'plan-outline-ai-apply', cid, file: filePath, dryRun: false, applied: true, candidate: { cid, outLine: rows } };
+    outputResult(args, payload, [
+        `AI outline candidate accepted locally: cid=${cid}`,
+        'the backend outline is unchanged. Review it, then run xq-cli plan directory-generate --cid <cid> --yes to save the candidate and generate the directory.',
+    ]);
+    return payload;
+}
+
+async function handlePlanDirectoryGenerate(args, state, regenerating) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const snapshot = await hydrateTaskSnapshot(client, state, cid);
+    ensurePlanningTask(snapshot);
+    const currentPhase = normalizePlanModePhase(snapshot.plan_mode_phase);
+    if (regenerating && (currentPhase === null || currentPhase < 2)) {
+        throw new Error('The task has not reached the directory phase yet. Use plan directory-generate for the first final-directory generation.');
+    }
+    if (!regenerating && currentPhase !== null && currentPhase >= 2) {
+        throw new Error('This task has already entered the directory phase. Use plan directory-regenerate for an explicit replacement request.');
+    }
+    const outlineResponse = await fetchOutlineDetail(client, cid);
+    const outlineDetail = outlineResponse?.data || {};
+    const outlineSelection = resolvePlanDirectoryOutline(args, state, cid, outlineDetail);
+    const rows = outlineSelection.rows;
+    await confirmPlanAction(args, regenerating ? 'regenerate final directory' : 'generate final directory', [
+        `outline chapters: ${rows.length}`,
+        `outline source: ${outlineSelection.source}`,
+        regenerating
+            ? 'the existing directory can be replaced after the outline is saved.'
+            : 'the outline will be saved and the backend will start final-directory generation.',
+    ]);
+
+    if (!regenerating) {
+        await postJson(client, '/task/checkPageScope', {
+            cid,
+            updateStatus: 1,
+            outLine: rows,
+        });
+    }
+    const outlineUpdate = await postJson(client, '/c/updateOutLine', {
+        cid,
+        outLine: rows,
+        source: outlineSelection.source === 'AI candidate' ? 1 : 2,
+    });
+    const planModePhase = await setPlanModePhase(client, cid, 2);
+    saveTaskSnapshot(state, cid, {
+        planModePhase: 2,
+        outlineUpdatedAt: new Date().toISOString(),
+        directoryGenerationRequestedAt: new Date().toISOString(),
+        directoryRegenerationRequestedAt: regenerating ? new Date().toISOString() : undefined,
+        planAiOutlineCandidate: undefined,
+    });
+    const directoryWaitResult = booleanOption(args, 'wait')
+        ? await ensureDirectoryReadyForWrite(client, state, cid, args)
+        : null;
+    const payload = {
+        command: regenerating ? 'plan-directory-regenerate' : 'plan-directory-generate',
+        cid,
+        regenerating,
+        outlineUpdate,
+        planModePhase,
+        directoryWaitResult,
+    };
+    outputResult(args, payload, [
+        `final directory ${regenerating ? 'regeneration' : 'generation'} requested: cid=${cid}`,
+        `phase: ${formatPlanModePhase(planModePhase)}`,
+        directoryWaitResult?.phase === 'ready'
+            ? 'directory ready for review; body generation has not started.'
+            : 'the backend is generating the directory; query plan status or rerun with --wait.',
+    ]);
+    return payload;
+}
+
 async function handleOutline(args, state) {
     validateOutlineReferenceTypeOption(args);
     const client = createAuthorizedClient(args, state);
@@ -775,6 +1256,26 @@ async function handleOutline(args, state) {
     const effectiveArgs = booleanOption(args, 'interactive')
         ? await collectOutlineInteractiveArgs(args, outlineSnapshot)
         : args;
+    const periodResult = booleanOption(effectiveArgs, 'wait')
+        ? await ensurePeriodReady(client, state, cid, effectiveArgs)
+        : null;
+    if (periodResult?.phase === 'confirmation_required') {
+        const resultPayload = {
+            command: 'outline',
+            cid,
+            uuid: outlineSnapshot.uuid,
+            periodResult,
+            waitResult: { phase: 'period_confirmation_required', periodResult },
+        };
+        outputResult(args, resultPayload, [
+            `outline blocked: engineering period confirmation required, cid=${cid}`,
+            `contract period: ${periodResult.contractPeriod ?? '-'}`,
+            `start: ${periodResult.contractStartDate ?? '-'}`,
+            `end: ${periodResult.contractEndDate ?? '-'}`,
+            `hint: run xq-cli period-confirm --cid ${cid} --contract-period <days> --period-mode <1|2>, then rerun outline for the same cid.`,
+        ]);
+        return resultPayload;
+    }
     const params = buildOutlineParams(outlineSnapshot, effectiveArgs);
 
     const triggerMode = await triggerOutlineGeneration(client, outlineSnapshot, params);
@@ -825,6 +1326,7 @@ async function handleOutline(args, state) {
         base: params.base,
         config: pickOutlineConfig(params),
         triggerMode,
+        periodResult,
         waitResult,
     };
     outputResult(args, resultPayload, [
@@ -933,6 +1435,7 @@ async function handleOutlineUpdate(args, state) {
     const response = await postJson(client, '/c/updateOutLine', requestData);
     saveTaskSnapshot(state, cid, {
         outlineUpdatedAt: new Date().toISOString(),
+        planAiOutlineCandidate: undefined,
     });
     const resultPayload = {
         ...baseResult,
@@ -977,6 +1480,87 @@ async function handleDirectoryView(args, state) {
     return resultPayload;
 }
 
+async function handleDirectoryPrepare(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const directoryWaitResult = await ensureDirectoryReadyForWrite(client, state, cid, args);
+    const payload = { command: 'directory-prepare', cid, directoryWaitResult };
+    outputResult(args, payload, [
+        `directory prepare: cid=${cid}`,
+        `phase: ${directoryWaitResult.phase}`,
+        `directory status: ${directoryWaitResult.contentDetail?.directory_portion_status ?? '-'}`,
+        directoryWaitResult.phase === 'ready'
+            ? 'directory ready for user review; body generation has not started.'
+            : 'directory is not ready; continue querying the same task.',
+    ]);
+    return payload;
+}
+
+async function handleDirectoryUpdate(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const filePath = path.resolve(requiredOption(args, 'file'));
+    ensureFileExists(filePath);
+    let document;
+    try {
+        document = JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, ''));
+    } catch {
+        throw new Error(`Failed to parse directory JSON: ${filePath}`);
+    }
+    const documentCid = document && !Array.isArray(document) ? String(document.cid || '').trim() : '';
+    if (documentCid && documentCid !== cid) {
+        throw new Error(`Directory file cid (${documentCid}) does not match --cid (${cid}): ${filePath}`);
+    }
+    const directories = Array.isArray(document)
+        ? document
+        : (Array.isArray(document?.directoryNodes) ? document.directoryNodes : null);
+    if (!directories || directories.length === 0) {
+        throw new Error('Directory JSON must be an array or contain a non-empty directoryNodes array.');
+    }
+    const requestPreview = { cid, directories };
+    const resultPayload = {
+        command: 'directory-update',
+        cid,
+        file: filePath,
+        dryRun: booleanOption(args, 'dryRun'),
+        applied: false,
+        requestPreview,
+    };
+    if (booleanOption(args, 'dryRun')) {
+        outputResult(args, resultPayload, [
+            `directory update preview: cid=${cid}`,
+            `roots: ${directories.length}`,
+            'dry-run only: no server data was changed.',
+            'hint: rerun with --yes to apply this update.',
+        ]);
+        return resultPayload;
+    }
+    const confirmed = booleanOption(args, 'yes') || await confirmDirectoryUpdate(args, cid, directories);
+    if (!confirmed) {
+        outputResult(args, { ...resultPayload, reason: 'cancelled' }, [`directory update cancelled: cid=${cid}`]);
+        return { ...resultPayload, reason: 'cancelled' };
+    }
+    const response = await postJson(client, '/task/updateDirectory', requestPreview);
+    const payload = { ...resultPayload, applied: true, response };
+    saveTaskSnapshot(state, cid, { directoryUpdatedAt: new Date().toISOString() });
+    outputResult(args, payload, [
+        `directory update accepted: cid=${cid}`,
+        'note: directory changes may trigger asynchronous content regeneration.',
+        `next: xq-cli directory view --cid ${cid}`,
+    ]);
+    return payload;
+}
+
+async function confirmDirectoryUpdate(args, cid, directories) {
+    if (!supportsInteractivePrompt()) {
+        throw new Error('Directory update changes server data. Review it with --dry-run, then rerun with --yes.');
+    }
+    return runPromptSession(args, async context => {
+        context.promptStream.write(`\nDirectory roots=${directories.length}\n`);
+        return promptYesNo(context, `Apply this directory update to cid=${cid}`, false);
+    });
+}
+
 async function confirmOutlineUpdate(args, cid, diff) {
     if (!supportsInteractivePrompt()) {
         throw new Error('Outline update changes server data. Review it with --dry-run, then rerun with --yes.');
@@ -1125,6 +1709,8 @@ async function handleStatus(args, state) {
         `status: cid=${cid}`,
         `title: ${detail.data.title || detail.data.projectName || '-'}`,
         `task_status: ${detail.data.task_status ?? '-'}`,
+        `planMode: ${describeEnumValue(PLAN_MODE_OPTIONS, normalizePlanModeValue(detail.data.planMode) ?? detail.data.planMode)}`,
+        `plan_mode_phase: ${formatPlanModePhase(detail.data.plan_mode_phase)}`,
         `viewStep: ${contentDetail?.data?.viewStep ?? detail.data.viewStep ?? '-'}`,
         `percentage: ${contentDetail?.data?.percentage ?? detail.data.percentage ?? '-'}`,
     ]);
@@ -1263,6 +1849,10 @@ function buildOutlineParams(snapshot, args) {
 async function triggerOutlineGeneration(client, snapshot, params) {
     await postJson(client, '/task/preSet', params);
 
+    if (Number(params.planMode) === 1) {
+        await setPlanModePhase(client, params.cid, 1);
+    }
+
     const hasTaskStatus = snapshot.task_status !== undefined && snapshot.task_status !== null;
     if (hasTaskStatus && Number(snapshot.task_status) !== 0) {
         await getJson(client, '/proxy/multiBiddingChoice', compactObject({
@@ -1277,6 +1867,241 @@ async function triggerOutlineGeneration(client, snapshot, params) {
     return 'generateByRequirement';
 }
 
+async function setPlanModePhase(client, cid, planModePhase) {
+    const response = await postJson(client, '/task/setPlanModePhase', { cid, planModePhase });
+    const returned = normalizePlanModePhase(response?.data?.planModePhase);
+    return returned === null ? planModePhase : returned;
+}
+
+function ensurePlanningTask(snapshot) {
+    if (Number(normalizePlanModeValue(snapshot?.planMode)) !== 1) {
+        throw new Error('This command requires a planning-mode task. Start the outline with --plan-mode planning first.');
+    }
+}
+
+async function confirmPlanAction(args, action, details = []) {
+    if (booleanOption(args, 'yes')) {
+        return true;
+    }
+    if (!canPromptForInput()) {
+        throw new Error(`Plan action "${action}" changes the task or starts generation. Review the result, then rerun with --yes.`);
+    }
+    return runPromptSession(args, async context => {
+        context.promptStream.write(`\nPlan action: ${action}\n`);
+        details.filter(Boolean).forEach(detail => context.promptStream.write(`  ${detail}\n`));
+        return promptYesNo(context, `Continue with ${action}`, false);
+    });
+}
+
+function readPlanFeedbackArgs(args) {
+    const entries = [];
+    const quote = normalizePlanText(stringOption(args, 'quote'));
+    const inputValues = [
+        ...ensureArray(args.text),
+        ...ensureArray(args.correction),
+        ...ensureArray(args.feedback),
+    ];
+    inputValues.forEach(value => {
+        const text = normalizePlanText(value);
+        if (text) {
+            entries.push({ quote, text });
+        }
+    });
+
+    const fileValue = stringOption(args, 'file');
+    if (!fileValue) {
+        return entries;
+    }
+    const filePath = path.resolve(fileValue);
+    ensureFileExists(filePath);
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, ''));
+    } catch {
+        throw new Error(`Failed to parse plan feedback JSON: ${filePath}`);
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : (parsed?.feedback || parsed?.corrections || parsed?.chatList || []);
+    if (!Array.isArray(rows)) {
+        throw new Error('Plan feedback JSON must be an array or contain feedback, corrections, or chatList.');
+    }
+    rows.forEach((row, index) => {
+        if (typeof row === 'string') {
+            const text = normalizePlanText(row);
+            if (text) entries.push({ quote: '', text });
+            return;
+        }
+        if (!row || typeof row !== 'object' || Array.isArray(row)) {
+            throw new Error(`Plan feedback item ${index + 1} must be a string or JSON object.`);
+        }
+        const text = normalizePlanText(row.text ?? row.content ?? row.user_comments);
+        if (!text) {
+            throw new Error(`Plan feedback item ${index + 1} has no text/content/user_comments value.`);
+        }
+        entries.push({ quote: normalizePlanText(row.quote ?? row.quote_paragraph), text });
+    });
+    return entries;
+}
+
+function normalizePlanFeedback(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map(item => ({
+            quote: normalizePlanText(item?.quote ?? item?.quote_paragraph),
+            text: normalizePlanText(item?.text ?? item?.content ?? item?.user_comments),
+        }))
+        .filter(item => Boolean(item.text));
+}
+
+function mergePlanFeedback(current, additions) {
+    const seen = new Set();
+    return [...current, ...additions].filter(item => {
+        const normalized = {
+            quote: normalizePlanText(item?.quote),
+            text: normalizePlanText(item?.text),
+        };
+        if (!normalized.text) {
+            return false;
+        }
+        const key = `${normalized.quote}\n${normalized.text}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    }).map(item => ({
+        quote: normalizePlanText(item.quote),
+        text: normalizePlanText(item.text),
+    }));
+}
+
+function extractPlanAiOutlineRows(answer) {
+    const candidates = [
+        answer?.modifiedChapters,
+        answer?.outline,
+        answer?.outLine,
+        Array.isArray(answer) ? answer : null,
+    ];
+    const rows = candidates.find(Array.isArray);
+    return Array.isArray(rows) ? rows : [];
+}
+
+function buildPlanAiOutlineCandidate(cid, prompt, conversationId, rows) {
+    // The frontend's AI-apply path submits text/theme/important without IDs.
+    // Let the backend assign IDs when it saves the accepted final outline;
+    // synthetic local IDs would otherwise be mistaken for database node IDs.
+    const candidateRows = buildPlanAiOutlineUpdateRows(rows);
+    return {
+        format: 'xq-cli-plan-ai-outline@1',
+        cid,
+        generatedAt: new Date().toISOString(),
+        prompt,
+        conversationId: conversationId || undefined,
+        outLine: candidateRows,
+    };
+}
+
+function buildPlanAiOutlineUpdateRows(rows, options = {}) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new Error('AI outline candidate must contain at least one chapter.');
+    }
+    return rows.map((row, index) => {
+        if (!row || typeof row !== 'object' || Array.isArray(row)) {
+            throw new Error(`AI outline chapter ${index + 1} must be a JSON object.`);
+        }
+        const text = normalizePlanText(row.text ?? row.title);
+        if (!text) {
+            throw new Error(`AI outline chapter ${index + 1} has an empty text field.`);
+        }
+        const theme = Array.isArray(row.theme)
+            ? row.theme.map(normalizePlanText).filter(Boolean).join('\n')
+            : normalizePlanText(row.theme ?? row.content);
+        const important = normalizePlanImportant(row.important, index);
+        const sequelFlag = normalizePlanSequelFlag(row.sequelFlag, index);
+        const id = options.preserveIds ? normalizePlanText(row.id) : '';
+        return compactObject({
+            id: id || undefined,
+            text,
+            theme,
+            updateFlag: Number(row.updateFlag) === 1 ? 1 : 0,
+            important,
+            sequelFlag,
+        });
+    });
+}
+
+function buildPlanServerOutlineRows(rows) {
+    return buildPlanAiOutlineUpdateRows(rows);
+}
+
+function resolvePlanDirectoryOutline(args, state, cid, outlineDetail) {
+    const explicitFile = stringOption(args, 'outlineFile');
+    if (explicitFile) {
+        const filePath = path.resolve(explicitFile);
+        const document = readOutlineEditFile(filePath);
+        validateOutlineEditCid(document, cid, filePath);
+        return {
+            source: 'outline file',
+            rows: buildPlanAiOutlineUpdateRows(extractOutlineRows(document)),
+        };
+    }
+
+    const candidate = state.tasks?.[cid]?.planAiOutlineCandidate;
+    if (candidate?.outLine) {
+        return {
+            source: 'AI candidate',
+            rows: buildPlanAiOutlineUpdateRows(candidate.outLine),
+        };
+    }
+
+    if (!isOutlineReadyForCli(outlineDetail)) {
+        throw new Error('The outline is not ready. Confirm and wait for the outline before generating the final directory.');
+    }
+    return {
+        source: 'server outline',
+        rows: buildPlanServerOutlineRows(getOutlineRows(outlineDetail)),
+    };
+}
+
+function normalizePlanImportant(value, index) {
+    if (value === undefined || value === null || value === '') {
+        return 2;
+    }
+    const parsed = Number(value);
+    if (parsed !== 1 && parsed !== 2) {
+        throw new Error(`Outline important for chapter ${index + 1} must be 1 or 2.`);
+    }
+    return parsed;
+}
+
+function normalizePlanSequelFlag(value, index) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (parsed !== 0 && parsed !== 1) {
+        throw new Error(`Outline sequelFlag for chapter ${index + 1} must be 0 or 1.`);
+    }
+    return parsed;
+}
+
+function normalizePlanText(value) {
+    return value === undefined || value === null ? '' : String(value).trim();
+}
+
+function writePlanAiOutlineFile(outputOption, cid, document) {
+    const resolvedOutput = path.resolve(outputOption);
+    const outputIsDirectory = !path.extname(resolvedOutput);
+    const fileName = `outline-ai-${normalizeDownloadFileName(cid) || 'task'}.json`;
+    const finalPath = outputIsDirectory ? path.join(resolvedOutput, fileName) : resolvedOutput;
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    fs.writeFileSync(finalPath, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+    return finalPath;
+}
+
 function buildFileMetadata(files, args) {
     const typeValues = ensureArray(args.type);
     const purposeValues = ensureArray(args.purpose);
@@ -1335,6 +2160,32 @@ async function pollParseUntilReady(client, state, cid, uuid, args) {
     });
 }
 
+async function ensurePeriodReady(client, state, cid, args) {
+    return pollUntil(async () => {
+        const response = await getJson(client, `/engineering/checkPeriod/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT });
+        const data = response?.data || {};
+        saveTaskSnapshot(state, cid, {
+            periodStatus: data.status,
+            contractPeriod: data.contractPeriod,
+            contractStartDate: data.contractStartDate,
+            contractEndDate: data.contractEndDate,
+        });
+        const status = Number(data.status);
+        if (status === 1) {
+            return { done: true, data: { phase: 'ready', ...data }, progressLabel: 'period_status=1' };
+        }
+        if (status === 2) {
+            return { done: true, data: { phase: 'confirmation_required', ...data }, progressLabel: 'period_status=2' };
+        }
+        return { done: false, data: null, progressLabel: `period_status=${data.status ?? '-'}` };
+    }, {
+        intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_TASK_INTERVAL_MS / 1000)),
+        timeoutMs: secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000)),
+        quiet: booleanOption(args, 'json'),
+        waitingText: 'waiting engineering period extraction',
+    });
+}
+
 function isParseReadyForNextStep(success) {
     const parsed = Number(success);
     return parsed === 1 || parsed === 4;
@@ -1371,6 +2222,7 @@ async function waitForOutlineReady(client, state, cid, uuid, args) {
 
         const outlineData = outlineDetail?.data || {};
         const hasOutline = isOutlineReadyForCli(outlineData);
+        const planModePhase = normalizePlanModePhase(taskDetail.data?.plan_mode_phase);
         const referenceData = referenceStatus?.data || {};
         const referencePhase = normalizeReferenceStatus(referenceData.status);
         if (referencePhase !== null) {
@@ -1492,14 +2344,14 @@ async function waitForOutlineReady(client, state, cid, uuid, args) {
             return {
                 done: false,
                 data: null,
-                progressLabel: `success=${parseSuccess}, task_status=${taskDetail.data?.task_status ?? '-'}, directory_status=${taskDetail.data?.directory_portion_status ?? '-'}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
+                progressLabel: `success=${parseSuccess}, task_status=${taskDetail.data?.task_status ?? '-'}, plan_mode_phase=${formatPlanModePhase(planModePhase)}, directory_status=${taskDetail.data?.directory_portion_status ?? '-'}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
             };
         }
 
         return {
             done: false,
             data: null,
-            progressLabel: `task_status=${taskDetail.data?.task_status ?? '-'}, directory_status=${taskDetail.data?.directory_portion_status ?? '-'}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
+            progressLabel: `task_status=${taskDetail.data?.task_status ?? '-'}, plan_mode_phase=${formatPlanModePhase(planModePhase)}, directory_status=${taskDetail.data?.directory_portion_status ?? '-'}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
         };
     }, {
         intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_TASK_INTERVAL_MS / 1000)),
@@ -1958,6 +2810,30 @@ function normalizeReferenceStatus(value) {
     return Number.isNaN(parsed) ? null : parsed;
 }
 
+function normalizePlanModeValue(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? String(value).trim() : parsed;
+}
+
+function normalizePlanModePhase(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 && parsed <= 3 ? parsed : null;
+}
+
+function formatPlanModePhase(value) {
+    const normalized = normalizePlanModePhase(value);
+    if (normalized === null) {
+        return '-';
+    }
+    return `${normalized}:${PLAN_MODE_PHASE_LABELS[normalized] || normalized}`;
+}
+
 function parseOutlineReferenceType(value) {
     if (value === undefined || value === null || value === '') {
         return null;
@@ -2777,13 +3653,17 @@ function collectIssueHints(issues, args) {
 }
 
 function saveLoginState(state, options) {
-    const username = options.result.data?.user?.username || options.name || '';
+    const resultData = options.result?.data || {};
+    const userInfo = options.user || resultData?.user || resultData || {};
+    const username = userInfo.username || userInfo.userName || resultData?.userName || options.name || '';
     state.baseUrl = options.baseUrl;
-    state.token = options.result.data.token;
+    state.authType = options.authType || (options.apiKey ? 'api-key' : 'token');
+    state.apiKey = state.authType === 'api-key' ? String(options.apiKey || '') : '';
+    state.token = state.authType === 'token' ? String(resultData.token || options.token || '') : '';
     state.user = {
         name: options.name || username,
         username,
-        userId: options.result.data?.user?.userId || '',
+        userId: userInfo.userId || userInfo.id || resultData?.userId || '',
         sourceFrom: options.sourceFrom,
         loggedInAt: new Date().toISOString(),
     };
@@ -2968,13 +3848,15 @@ function createAuthorizedClient(args, state) {
     if (!baseUrl) {
         throw new Error('Missing base URL. Run login first or pass --base-url.');
     }
-    if (!state.token) {
-        throw new Error('Missing local token. Run login first.');
+    const credential = resolveAuthCredential(args, state);
+    if (!credential.value) {
+        throw new Error('Missing local API key or token. Run login first.');
     }
-    return createClient(baseUrl, state.token);
+    return createClient(baseUrl, credential.value);
 }
 
 function createClient(baseUrl, token = '') {
+    const authorization = normalizeAuthorizationCredential(token);
     return axios.create({
         baseURL: baseUrl,
         timeout: 1_200_000,
@@ -2982,15 +3864,47 @@ function createClient(baseUrl, token = '') {
         maxContentLength: Infinity,
         httpAgent: HTTP_AGENT,
         httpsAgent: HTTPS_AGENT,
-        headers: token
+        headers: authorization
             ? {
-                  Authorization: token,
+                  Authorization: authorization,
               }
             : {},
         validateStatus: () => true,
     });
 }
 
+function resolveAuthCredential(args, state) {
+    const envApiKey = normalizeApiKey(process.env.XQ_API_KEY);
+    if (envApiKey) {
+        return { value: envApiKey, type: 'api-key-env' };
+    }
+    const stateApiKey = normalizeApiKey(state?.apiKey);
+    if (stateApiKey) {
+        return { value: stateApiKey, type: 'api-key-config' };
+    }
+    const stateToken = normalizeApiKey(state?.token);
+    if (stateToken) {
+        return { value: stateToken, type: 'token' };
+    }
+    return { value: '', type: 'missing' };
+}
+
+function normalizeAuthorizationCredential(value) {
+    const normalized = String(value || '').trim();
+    if (!normalized) {
+        return '';
+    }
+    if (normalized.toLowerCase().startsWith('bearer ')) {
+        return normalized;
+    }
+    return `Bearer ${normalized}`;
+}
+
+function normalizeApiKey(value) {
+    const normalized = String(value || '').trim();
+    return normalized || '';
+}
+
 async function getJson(client, url, params = {}, options = {}) {
     const response = await requestWithRetry(async () => {
         return client.get(url, { params });
@@ -3466,7 +4380,9 @@ function normalizeBaseUrl(value) {
 function createDefaultState() {
     return {
         baseUrl: DEFAULT_BASE_URL,
+        apiKey: '',
         token: '',
+        authType: '',
         user: {},
         lastCid: '',
         tasks: {},
@@ -3484,7 +4400,9 @@ function readState() {
             ...defaultState,
             ...parsed,
             baseUrl: normalizeBaseUrl(parsed?.baseUrl || defaultState.baseUrl),
+            apiKey: normalizeApiKey(parsed?.apiKey),
             token: parsed?.token || '',
+            authType: parsed?.authType || (parsed?.apiKey ? 'api-key' : parsed?.token ? 'token' : ''),
             user: parsed?.user && typeof parsed.user === 'object' ? parsed.user : {},
             lastCid: parsed?.lastCid || '',
             tasks: parsed?.tasks && typeof parsed.tasks === 'object' ? parsed.tasks : {},
@@ -3525,6 +4443,7 @@ function pickTaskSnapshot(source) {
         base: source.base,
         pageScopeCode: source.pageScopeCode,
         task_status: source.task_status,
+        plan_mode_phase: source.plan_mode_phase,
         viewStep: source.viewStep,
         percentage: source.percentage,
         content_portion_status: source.content_portion_status,