@xqyz/xq-cli 0.2.1 → 0.3.1

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,8 +1849,20 @@ function buildOutlineParams(snapshot, args) {
 async function triggerOutlineGeneration(client, snapshot, params) {
     await postJson(client, '/task/preSet', params);
 
-    const hasTaskStatus = snapshot.task_status !== undefined && snapshot.task_status !== null;
-    if (hasTaskStatus && Number(snapshot.task_status) !== 0) {
+    if (Number(params.planMode) === 1) {
+        await setPlanModePhase(client, params.cid, 1);
+    }
+
+    // task_status=6 means "file parsing" in the Xique backend. It is not a
+    // signal that this is a multi-bid/EPC task. Only route through the
+    // special-selection endpoint when the caller actually supplied a
+    // multi-bid or EPC selection; ordinary tasks must use the normal
+    // generation endpoint even while the task is transitioning from parse.
+    const hasSpecialSelection = Boolean(
+        String(params.multiBidId ?? snapshot.multiBidId ?? '').trim()
+        || String(params.epcEngineerType ?? snapshot.epcEngineerType ?? '').trim()
+    );
+    if (hasSpecialSelection) {
         await getJson(client, '/proxy/multiBiddingChoice', compactObject({
             uuid: snapshot.uuid,
             multiBidId: params.multiBidId ?? snapshot.multiBidId,
@@ -1277,6 +1875,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 +2168,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 +2230,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 +2352,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)),
@@ -1908,7 +2768,23 @@ function isContentRunningOrDone(detail) {
 async function pollUntil(checkFn, options) {
     const startedAt = Date.now();
     while (true) {
-        const result = await checkFn();
+        let result;
+        try {
+            result = await checkFn();
+        } catch (error) {
+            // A transient connection reset must not turn an already accepted
+            // asynchronous backend task into a false failure. Read requests
+            // are retried by getJson; this catch keeps polling the same cid
+            // when a response stream still closes during that retry window.
+            if (!isRetryableNetworkError(error)) {
+                throw error;
+            }
+            result = {
+                done: false,
+                data: null,
+                progressLabel: `transient network error; retrying (${String(error?.message || error)})`,
+            };
+        }
         if (result.done) {
             return result.data;
         }
@@ -1958,6 +2834,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 +3677,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 +3872,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,19 +3888,54 @@ 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 });
-    }, options);
+    }, {
+        retries: DEFAULT_RETRY_COUNT,
+        ...options,
+    });
     return unwrapApiResponse(response);
 }
 
@@ -3050,7 +3991,7 @@ function isRetryableNetworkError(error) {
     if (RETRYABLE_NETWORK_CODES.has(code)) {
         return true;
     }
-    return /socket disconnected|econnreset|tls connection|network error|timeout/i.test(message);
+    return /socket disconnected|econnreset|tls connection|network error|timeout|stream has been aborted|socket hang up|premature close|aborted/i.test(message);
 }
 
 function unwrapApiResponse(response) {
@@ -3466,7 +4407,9 @@ function normalizeBaseUrl(value) {
 function createDefaultState() {
     return {
         baseUrl: DEFAULT_BASE_URL,
+        apiKey: '',
         token: '',
+        authType: '',
         user: {},
         lastCid: '',
         tasks: {},
@@ -3484,7 +4427,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 +4470,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,