@longtable/cli 0.1.31 → 0.1.32

package/README.md

@@ -8,9 +8,9 @@ Claude skills, and future MCP surfaces remain generated adapter artifacts.
 
 The basic contract is:
 
-1. seed the researcher profile once
-2. create a workspace for each project
-3. continue the research conversation inside that workspace
+1. approve provider/runtime support once
+2. start each project inside the provider with `$longtable-interview`
+3. create or resume a workspace from that interview
 4. preserve decisions, tensions, and evidence as durable project state
 
 ## Install
@@ -26,15 +26,17 @@ config, hooks, or provider runtime files without explicit setup approval.
 
 ```bash
 longtable setup --provider codex
-longtable start
-cd "<project-path>"
+cd "<research-folder>"
 codex
 ```
 
+Then invoke `$longtable-interview` inside Codex.
+
 `longtable setup --provider codex` is the permission-first setup route. It asks
 where LongTable may install support, which runtime surfaces it may enable, how
-strongly it may interrupt research decisions, and whether to create a project
-workspace now. `longtable init` remains only as a deprecated compatibility alias.
+strongly it may interrupt research decisions, and whether to show the
+provider-native interview launch steps. `longtable init` remains only as a
+deprecated compatibility alias.
 
 Return later:
 
@@ -44,7 +46,7 @@ longtable resume
 codex
 ```
 
-## What `longtable start` Creates
+## What `$longtable-interview` Creates
 
 ```text
 <project>/
@@ -84,7 +86,6 @@ This is how LongTable avoids turning tacit knowledge into fake certainty.
 
 ```bash
 longtable setup
-longtable start
 longtable resume --cwd "<project-path>"
 longtable roles
 longtable ask --cwd "<project-path>" --prompt "..."
@@ -136,12 +137,14 @@ longtable claude install-skills
 
 Codex skills include `longtable`, `longtable-panel`, and generated role-specific
 skills such as `longtable-methods-critic`. If your Codex build exposes explicit
-skill shortcuts, `$longtable` is the manual entry. Do not depend on `/prompts`;
-current Codex builds may reject it.
+skill shortcuts, `$longtable-interview` is the research-start entry and
+`$longtable` is the general router. Do not depend on `/prompts`; current Codex
+builds may reject it.
 
 Claude Code skills include `longtable`, `longtable-panel`, and generated
-role-specific skills such as `longtable-methods-critic`. They are adapter files
-generated from the LongTable role registry.
+role-specific skills such as `longtable-methods-critic`. They also include
+`longtable-interview` for the First Research Shape workflow. They are adapter
+files generated from the LongTable role registry.
 
 ## Panel Orchestration
 

package/dist/cli.js

@@ -43,7 +43,7 @@ const ANSI = {
     green: "\u001B[32m"
 };
 const LONGTABLE_MCP_SERVER_NAME = "longtable-state";
-const LONGTABLE_MCP_PACKAGE_VERSION = "0.1.31";
+const LONGTABLE_MCP_PACKAGE_VERSION = "0.1.32";
 const LONGTABLE_MCP_MARKER_START = "# LongTable state MCP START";
 const LONGTABLE_MCP_MARKER_END = "# LongTable state MCP END";
 function style(text, prefix) {
@@ -68,6 +68,20 @@ function renderBrandBanner(title, subtitle) {
     }
     return lines.join("\n");
 }
+function renderInterviewLaunchSteps(provider) {
+    const command = provider === "codex" ? "codex" : "claude";
+    return renderSectionCard("LongTable Interview", [
+        "Setup is permission and runtime calibration, not the research interview.",
+        "The first research conversation now happens inside the provider so the model can listen, reflect, and ask one natural-language follow-up at a time.",
+        "",
+        "Next:",
+        "1. cd \"<research-folder>\"",
+        `2. run \`${command}\``,
+        "3. invoke `$longtable-interview`",
+        "",
+        "The interview will create or resume `.longtable/`, build a First Research Shape, and use option UI only for the final confirmation."
+    ]);
+}
 function renderProgressBar(current, total) {
     const width = 10;
     const filled = Math.max(1, Math.round((current / total) * width));
@@ -77,11 +91,11 @@ function usage() {
     return [
         "Usage:",
         "  Run `longtable ...` in your terminal, not inside the Codex chat box.",
-        "  After `longtable start`, move into the created project directory and open `codex` there.",
+        "  LongTable research starts inside Codex or Claude with `$longtable-interview` after setup.",
         "",
         "  longtable setup [--provider codex|claude] [--install-scope user|project|none] [--surfaces cli_only|skills|skills_mcp|skills_mcp_sentinel] [--intervention advisory|balanced|strong] [--checkpoint-ui off|interactive|strong] [--workspace create|later] [--project-dir <path>] [--json] [--dir <path>] [--skills-dir <path>] [--runtime-path <file>] [--setup-path <file>]",
         "  longtable init [deprecated alias for setup; full legacy flags still supported for automation]",
-        "  longtable start [--path <dir>] [--name <project>] [--goal <text>] [--blocker <text>] [--research-object research_question|theory_framework|measurement_instrument|study_design|analysis_plan|manuscript] [--gap-risk known_gap|suspected_tacit_assumptions|diagnose] [--protected-decision theory|measurement|method|evidence_citation|authorship_voice|submission_public_sharing] [--perspectives <role[,role]>] [--disagreement synthesis_only|show_on_conflict|always_visible] [--setup <path>] [--json]",
+        "  longtable start [deprecated fallback] [--path <dir>] [--name <project>] [--goal <text>] [--blocker <text>] [--research-object research_question|theory_framework|measurement_instrument|study_design|analysis_plan|manuscript] [--gap-risk known_gap|suspected_tacit_assumptions|diagnose] [--protected-decision theory|measurement|method|evidence_citation|authorship_voice|submission_public_sharing] [--perspectives <role[,role]>] [--disagreement synthesis_only|show_on_conflict|always_visible] [--setup <path>] [--json] [--no-interview]",
         "  longtable resume [--cwd <path>] [--json]",
         "  longtable doctor [--cwd <path>] [--fix] [--json] [--codex-dir <path>] [--codex-config <path>] [--claude-dir <path>] [--codex-prompts-dir <path>] [--codex-runtime-path <file>] [--claude-runtime-path <file>]",
         "  longtable status [--cwd <path>] [--fix] [--json] [--codex-dir <path>] [--codex-config <path>] [--claude-dir <path>] [--codex-prompts-dir <path>] [--codex-runtime-path <file>] [--claude-runtime-path <file>]",
@@ -114,9 +128,9 @@ function usage() {
         "",
         "Examples:",
         "  longtable setup --provider codex",
-        "  longtable start",
-        "  longtable start --path ~/Research/My-Project --name \"AI Adoption Meta-Analysis\" --goal \"Narrow the review question\"",
-        "  cd \"<project-path>\" && codex",
+        "  cd \"<research-folder>\" && codex",
+        "  $longtable-interview",
+        "  longtable start --no-interview --path ~/Research/My-Project --name \"AI Adoption Meta-Analysis\" --goal \"Narrow the review question\"",
         "  longtable doctor",
         "  longtable roles",
         "  longtable ask --prompt \"연구를 시작하고 싶어. 지금 어디서부터 좁혀야 할지 모르겠어.\"",
@@ -447,13 +461,13 @@ function buildPermissionSetupChoices() {
         workspace: [
             {
                 id: "create",
-                label: "Yes, create one now",
-                description: "Why: durable state needs .longtable/. What you get: decision log and CURRENT.md. Tradeoff: asks project-specific questions now."
+                label: "Show interview launch steps",
+                description: "Why: research should start inside the provider. What you get: setup finishes with Codex/Claude + $longtable-interview steps. Tradeoff: workspace creation waits for the in-provider interview."
             },
             {
                 id: "later",
                 label: "No, prepare runtime only",
-                description: "Why: keeps setup short. What you get: runtime support without project state. Tradeoff: no durable research memory until `longtable start`."
+                description: "Why: keeps setup short. What you get: runtime support without project state. Tradeoff: no durable research memory until `$longtable-interview` creates or resumes a workspace."
             }
         ]
     };
@@ -575,6 +589,8 @@ async function runSetup(args) {
         interventionPosture: effectiveIntervention,
         checkpointUiMode: checkpointUi,
         workspaceCreationPreference: workspacePreference,
+        officialStartSurface: "$longtable-interview",
+        setupPosture: "permission_first",
         teamMode: "panel"
     };
     if (surfaces === "skills_mcp_sentinel") {
@@ -617,7 +633,12 @@ async function runSetup(args) {
             runtime: result,
             installedSkills: installedSkills.map((skill) => skill.name),
             mcpInstall,
-            workspacePreference
+            workspacePreference,
+            nextStep: {
+                surface: "$longtable-interview",
+                command: provider === "codex" ? "codex" : "claude",
+                description: "Open the provider in the research folder and invoke `$longtable-interview`."
+            }
         }, null, 2));
         return;
     }
@@ -646,12 +667,11 @@ async function runSetup(args) {
         console.log("Background sentinel approval recorded.");
         console.log("Hook installation remains opt-in; LongTable will not install hooks without an explicit hook command.");
     }
+    console.log("");
+    console.log(renderInterviewLaunchSteps(provider));
     if (workspacePreference === "create") {
         console.log("");
-        console.log("Project workspace requested. LongTable will now run `longtable start` with an adaptive start interview.");
-        await runStart({
-            setup: result.setupTarget.path
-        });
+        console.log("Workspace launch requested. Open the provider in your research folder and run `$longtable-interview`; the interview will create `.longtable/` there.");
     }
 }
 function perspectiveChoices() {
@@ -849,6 +869,7 @@ function normalizePerspectiveList(value) {
         .filter(Boolean);
 }
 async function collectProjectInterview(setup, args) {
+    const skipResearchInterview = args["no-interview"] === true;
     const providedPerspectives = normalizePerspectiveList(typeof args.perspectives === "string" ? args.perspectives : undefined);
     const providedGoal = typeof args.goal === "string" && args.goal.trim() ? args.goal.trim() : undefined;
     const providedBlocker = typeof args.blocker === "string" && args.blocker.trim() ? args.blocker.trim() : undefined;
@@ -863,11 +884,11 @@ async function collectProjectInterview(setup, args) {
         : undefined;
     const needsInteractivePrompts = !(typeof args.name === "string" && args.name.trim()) ||
         !(typeof args.path === "string" && args.path.trim()) ||
-        !providedGoal ||
-        !providedBlocker ||
-        !providedResearchObject ||
-        !providedGapRisk ||
-        !providedProtectedDecision;
+        (!skipResearchInterview && (!providedGoal ||
+            !providedBlocker ||
+            !providedResearchObject ||
+            !providedGapRisk ||
+            !providedProtectedDecision));
     if (needsInteractivePrompts) {
         console.log("");
         console.log(renderBrandBanner("LongTable", "Project workspace interview"));
@@ -887,15 +908,17 @@ async function collectProjectInterview(setup, args) {
     const projectPath = (typeof args.path === "string" && args.path.trim()
         ? normalizeUserPath(args.path.trim())
         : resolveInteractiveProjectPath((await promptText(renderQuestionHeader(2, 2, "Workspace", `Which parent directory should contain this project?\nLongTable will create this folder:\n${suggestedPath}`), true)), projectName));
-    const adaptive = await collectAdaptiveStartInterview({
-        currentGoal: providedGoal,
-        currentBlocker: providedBlocker,
-        needsResearchSeed: !providedGoal ||
-            !providedBlocker ||
-            !providedResearchObject ||
-            !providedGapRisk ||
-            !providedProtectedDecision
-    });
+    const adaptive = skipResearchInterview
+        ? {}
+        : await collectAdaptiveStartInterview({
+            currentGoal: providedGoal,
+            currentBlocker: providedBlocker,
+            needsResearchSeed: !providedGoal ||
+                !providedBlocker ||
+                !providedResearchObject ||
+                !providedGapRisk ||
+                !providedProtectedDecision
+        });
     const currentGoal = providedGoal ?? adaptive.currentGoal;
     if (!currentGoal?.trim()) {
         throw new Error("LongTable start needs a current research goal or an opening interview answer.");
@@ -2773,6 +2796,26 @@ async function runRoles(args) {
     }
 }
 async function runStart(args) {
+    const hasMinimalFallbackArgs = typeof args.name === "string" &&
+        typeof args.path === "string" &&
+        typeof args.goal === "string";
+    const hasFallbackIntent = args["no-interview"] === true ||
+        hasMinimalFallbackArgs;
+    if (!hasFallbackIntent) {
+        console.log(renderSectionCard("LongTable Start Has Moved", [
+            "`longtable start` is now a fallback for automation and scripted workspace creation.",
+            "The primary research-start experience is provider-native so LongTable can run a real interview instead of a terminal questionnaire.",
+            "",
+            "Use:",
+            "1. longtable setup --provider codex",
+            "2. cd \"<research-folder>\"",
+            "3. codex",
+            "4. $longtable-interview",
+            "",
+            "For automation, pass `--no-interview --json` with `--name`, `--path`, and `--goal`."
+        ]));
+        return;
+    }
     const setupPath = typeof args.setup === "string" ? args.setup : undefined;
     const existingSetup = await loadOptionalSetup(setupPath);
     if (!existingSetup) {

package/dist/project-session.d.ts

@@ -19,6 +19,53 @@ export interface StartInterviewSession {
     inferredSignals: StartInterviewSignal[];
     summary: string;
 }
+export type InterviewTurnQuality = "thin" | "usable" | "rich";
+export type InterviewDepth = "gathering_context" | "forming_first_handle" | "ready_to_summarize";
+export interface FirstResearchShape {
+    handle: string;
+    currentGoal: string;
+    currentBlocker?: string;
+    researchObject?: string;
+    gapRisk?: string;
+    protectedDecision?: string;
+    openQuestions: string[];
+    nextAction: string;
+    confidence: "low" | "medium" | "high";
+    sourceHookId?: string;
+    confirmedAt?: string;
+}
+export interface LongTableInterviewTurn {
+    id: string;
+    index: number;
+    createdAt: string;
+    question: string;
+    answer: string;
+    reflection?: string;
+    quality: InterviewTurnQuality;
+    needsFollowUp: boolean;
+    followUpQuestion?: string;
+    rationale?: string[];
+}
+export interface LongTableHookRun {
+    id: string;
+    kind: "longtable_interview" | "quality_probe" | "checkpoint" | "panel_decision";
+    status: "pending" | "active" | "ready_to_confirm" | "confirmed" | "deferred" | "cancelled";
+    createdAt: string;
+    updatedAt: string;
+    targetOutcome?: "first_research_handle" | string;
+    depth?: InterviewDepth;
+    provider?: ProviderKind;
+    turns?: LongTableInterviewTurn[];
+    firstResearchShape?: FirstResearchShape;
+    qualityNotes?: string[];
+    rationale?: string[];
+    linkedQuestionRecordIds?: string[];
+    linkedDecisionRecordIds?: string[];
+}
+export type LongTableWorkspaceState = ResearchState & {
+    hooks?: LongTableHookRun[];
+    firstResearchShape?: FirstResearchShape;
+};
 export interface LongTableProjectRecord {
     schemaVersion: 1;
     product: "LongTable";
@@ -52,6 +99,7 @@ export interface LongTableSessionRecord {
     nextAction?: string;
     openQuestions?: string[];
     startInterview?: StartInterviewSession;
+    firstResearchShape?: FirstResearchShape;
     requestedPerspectives: string[];
     disagreementPreference: ProjectDisagreementPreference;
     activeModes?: string[];
@@ -127,9 +175,43 @@ export interface LongTableWorkspaceInspection {
         suggestion?: string;
     }>;
 }
-export declare function loadWorkspaceState(context: LongTableProjectContext): Promise<ResearchState>;
+export declare function loadWorkspaceState(context: LongTableProjectContext): Promise<LongTableWorkspaceState>;
 export declare function syncCurrentWorkspaceView(context: LongTableProjectContext): Promise<string>;
-export declare function appendInvocationRecordToWorkspace(context: LongTableProjectContext, invocation: InvocationRecord, questions?: QuestionRecord[]): Promise<ResearchState>;
+export declare function appendInvocationRecordToWorkspace(context: LongTableProjectContext, invocation: InvocationRecord, questions?: QuestionRecord[]): Promise<LongTableWorkspaceState>;
+export declare function beginLongTableInterview(options: {
+    context: LongTableProjectContext;
+    provider?: ProviderKind;
+    openingQuestion?: string;
+    seedAnswer?: string;
+}): Promise<{
+    hook: LongTableHookRun;
+    state: LongTableWorkspaceState;
+}>;
+export declare function appendLongTableInterviewTurn(options: {
+    context: LongTableProjectContext;
+    hookId?: string;
+    question: string;
+    answer: string;
+    reflection?: string;
+    quality?: InterviewTurnQuality;
+    needsFollowUp?: boolean;
+    followUpQuestion?: string;
+    rationale?: string[];
+}): Promise<{
+    hook: LongTableHookRun;
+    turn: NonNullable<LongTableHookRun["turns"]>[number];
+    state: LongTableWorkspaceState;
+}>;
+export declare function summarizeLongTableInterview(options: {
+    context: LongTableProjectContext;
+    hookId?: string;
+    shape: FirstResearchShape;
+}): Promise<{
+    hook: LongTableHookRun;
+    shape: FirstResearchShape;
+    state: LongTableWorkspaceState;
+    session: LongTableSessionRecord;
+}>;
 export declare function listBlockingWorkspaceQuestions(context: LongTableProjectContext): Promise<QuestionRecord[]>;
 export declare function assertWorkspaceNotBlocked(context: LongTableProjectContext): Promise<void>;
 export declare function createWorkspaceFollowUpQuestions(options: {

package/dist/project-session.js

@@ -54,6 +54,9 @@ function resolveUserLocale() {
     return normalizeLocale(Intl.DateTimeFormat().resolvedOptions().locale);
 }
 function buildFirstQuestion(session) {
+    if (session.firstResearchShape?.openQuestions?.[0]) {
+        return session.firstResearchShape.openQuestions[0];
+    }
     return session.currentBlocker
         ? `Where does "${session.currentBlocker}" show up most concretely in the scene, material, or evidence?`
         : `What scene, case, text, data, or draft would make "${session.currentGoal}" easiest to inspect first?`;
@@ -63,20 +66,23 @@ function buildOpenQuestions(session) {
     if (session.startInterview) {
         return [
             firstQuestion,
-            `What would a reader need to understand differently if "${session.currentGoal}" becomes a strong research project?`
+            `What still feels hardest to name or make concrete in "${session.currentGoal}"?`
         ];
     }
     return session.currentBlocker
         ? [
             firstQuestion,
-            `What would a reader need to understand differently if "${session.currentBlocker}" becomes a strong research problem?`
+            `What would give "${session.currentBlocker}" a usable first research handle without forcing a final research question yet?`
         ]
         : [
             firstQuestion,
-            `What would count as a good first outcome for "${session.currentGoal}" in this session?`
+            `What would give this project a usable first research handle without pretending the question is settled?`
         ];
 }
 function buildNextAction(session) {
+    if (session.firstResearchShape) {
+        return session.firstResearchShape.nextAction;
+    }
     if (session.startInterview) {
         return session.currentBlocker
             ? `Begin from the start-interview brief, then make "${session.currentBlocker}" concrete with one scene, source, case, or dataset.`
@@ -87,6 +93,9 @@ function buildNextAction(session) {
         : "Open with your current goal in one sentence, then ask LongTable for the first concrete research move.";
 }
 function buildResumeHint(session) {
+    if (session.firstResearchShape) {
+        return `I want to continue from the First Research Shape: ${session.firstResearchShape.handle}.`;
+    }
     if (session.startInterview) {
         return session.currentBlocker
             ? `I want to continue from the LongTable start interview. The first unresolved issue is ${session.currentBlocker}.`
@@ -118,6 +127,7 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
             ...(session.researchObject ? [`- 연구 객체: ${session.researchObject}`] : []),
             ...(session.gapRisk ? [`- 공백/암묵지 위험: ${session.gapRisk}`] : []),
             ...(session.protectedDecision ? [`- 보호할 결정: ${session.protectedDecision}`] : []),
+            ...(session.firstResearchShape ? [`- First Research Shape: ${session.firstResearchShape.handle}`] : []),
             ...(session.startInterview ? [`- start interview: ${session.startInterview.summary}`] : []),
             `- 다음 액션: ${nextAction}`,
             `- 관점: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
@@ -149,10 +159,19 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
             "",
             "## 다시 시작 문장",
             `- "${resumeHint}"`,
+            ...(session.firstResearchShape
+                ? [
+                    "",
+                    "## First Research Shape",
+                    `- Handle: ${session.firstResearchShape.handle}`,
+                    `- Confidence: ${session.firstResearchShape.confidence}`,
+                    ...session.firstResearchShape.openQuestions.map((question) => `- Open question: ${question}`)
+                ]
+                : []),
             "",
             "## 빠른 시작",
             "- 이 디렉토리에서 `codex`를 엽니다.",
-            `- 첫 메시지는 보통 \`${suggestedPrompt}\` 정도면 충분합니다.`,
+            `- 첫 메시지는 보통 \`${session.firstResearchShape ? suggestedPrompt : "$longtable-interview"}\` 정도면 충분합니다.`,
             "",
             "## 증거 규칙",
             "- 외부 사실이나 현재 정보는 source를 붙이거나 inference로 낮춥니다."
@@ -171,6 +190,7 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
         ...(session.researchObject ? [`- Research object: ${session.researchObject}`] : []),
         ...(session.gapRisk ? [`- Gap/tacit risk: ${session.gapRisk}`] : []),
         ...(session.protectedDecision ? [`- Protected decision: ${session.protectedDecision}`] : []),
+        ...(session.firstResearchShape ? [`- First Research Shape: ${session.firstResearchShape.handle}`] : []),
         ...(session.startInterview ? [`- Start interview: ${session.startInterview.summary}`] : []),
         `- Next action: ${nextAction}`,
         `- Perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
@@ -202,10 +222,19 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
         "",
         "## Restart Prompt",
         `- "${resumeHint}"`,
+        ...(session.firstResearchShape
+            ? [
+                "",
+                "## First Research Shape",
+                `- Handle: ${session.firstResearchShape.handle}`,
+                `- Confidence: ${session.firstResearchShape.confidence}`,
+                ...session.firstResearchShape.openQuestions.map((question) => `- Open question: ${question}`)
+            ]
+            : []),
         "",
         "## Quick Start",
         "- Open `codex` in this directory.",
-        `- A good first message is usually \`${suggestedPrompt}\`.`,
+        `- A good first message is usually \`${session.firstResearchShape ? suggestedPrompt : "$longtable-interview"}\`.`,
         "",
         "## Evidence Rule",
         "- External or current claims should carry a source link or be labeled as inference."
@@ -220,6 +249,8 @@ async function loadResearchState(stateFilePath) {
         ...parsed,
         explicitState: parsed.explicitState ?? {},
         workingState: parsed.workingState ?? {},
+        hooks: parsed.hooks ?? [],
+        ...(parsed.firstResearchShape ? { firstResearchShape: parsed.firstResearchShape } : {}),
         inferredHypotheses: parsed.inferredHypotheses ?? [],
         openTensions: parsed.openTensions ?? [],
         decisionLog: parsed.decisionLog ?? [],
@@ -339,13 +370,16 @@ function buildProjectAgentsMd(project, session) {
         "- Treat `AGENTS.md` as runtime guidance, not as the researcher-facing resume artifact.",
         "",
         "## Invocation Rules",
+        "- If the user message starts with `$longtable-interview`, run the LongTable interview flow before generic research advice.",
         "- If the user message starts with `lt `, `longtable `, `long table `, or `롱테이블 ` followed by a directive and `:`, treat it as an explicit LongTable invocation.",
-        "- Supported explicit directives are: explore, review, critique, draft, commit, panel, status, editor, reviewer, methods, theory, measurement, ethics, voice, venue.",
+        "- Supported explicit directives are: interview, explore, review, critique, draft, commit, panel, status, editor, reviewer, methods, theory, measurement, ethics, voice, venue.",
         "- For explicit LongTable invocations, do not begin by scanning the workspace. Use the current session files first and answer as LongTable immediately.",
         "- For general research requests in this workspace, prefer LongTable behavior before generic coding behavior.",
         "",
         "## Research Behavior",
         "- Begin exploratory work with clarifying or tension questions before recommending a direction.",
+        "- For `$longtable-interview`, ask one natural-language question at a time, reflect with `LongTable hears: ...`, and avoid early reader/reviewer or theory/method/measurement classification.",
+        "- Use structured options only at the final First Research Shape confirmation or at true checkpoint boundaries.",
         "- If you foreground role perspectives, disclose them with `LongTable consulted: ...`.",
         "- Keep one accountable synthesis, but do not hide meaningful disagreement.",
         ...(session.disagreementPreference === "always_visible"
@@ -362,6 +396,7 @@ function buildProjectAgentsMd(project, session) {
         ...(session.researchObject ? [`- Research object: ${session.researchObject}`] : []),
         ...(session.gapRisk ? [`- Gap/tacit risk: ${session.gapRisk}`] : []),
         ...(session.protectedDecision ? [`- Protected decision: ${session.protectedDecision}`] : []),
+        ...(session.firstResearchShape ? [`- First Research Shape: ${session.firstResearchShape.handle}`] : []),
         ...(session.startInterview ? [`- Start interview summary: ${session.startInterview.summary}`] : []),
         `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
         `- Disagreement visibility: ${session.disagreementPreference}`,
@@ -390,6 +425,10 @@ function buildStateSeed(project, session, setup) {
         ...(session.startInterview ? { startInterview: session.startInterview } : {}),
         ...(session.resumeHint ? { resumeHint: session.resumeHint } : {})
     };
+    if (session.firstResearchShape) {
+        state.firstResearchShape = session.firstResearchShape;
+        state.workingState.firstResearchShape = session.firstResearchShape;
+    }
     if (session.currentBlocker) {
         state.openTensions.push(session.currentBlocker);
     }
@@ -477,6 +516,200 @@ export async function appendInvocationRecordToWorkspace(context, invocation, que
 function createId(prefix) {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
+function normalizeInterviewQuality(answer, quality) {
+    if (quality) {
+        return quality;
+    }
+    const trimmed = answer.trim();
+    const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+    if (trimmed.length < 12 || wordCount < 3) {
+        return "thin";
+    }
+    if (trimmed.length > 80 || wordCount >= 12) {
+        return "rich";
+    }
+    return "usable";
+}
+function defaultFollowUpQuestion(answer) {
+    const trimmed = answer.trim();
+    if (trimmed.length < 12) {
+        return "Say one more sentence about where this problem appears or why it matters before LongTable tries to classify it.";
+    }
+    return "What concrete scene, case, material, text, dataset, or decision would make that problem easier to inspect first?";
+}
+function depthForInterview(turns = []) {
+    const usableTurns = turns.filter((turn) => turn.quality !== "thin").length;
+    if (usableTurns >= 3) {
+        return "ready_to_summarize";
+    }
+    if (usableTurns >= 1) {
+        return "forming_first_handle";
+    }
+    return "gathering_context";
+}
+function activeInterviewHook(state, hookId) {
+    const hooks = state.hooks ?? [];
+    if (hookId) {
+        return hooks.find((hook) => hook.id === hookId);
+    }
+    return [...hooks].reverse().find((hook) => hook.kind === "longtable_interview" &&
+        (hook.status === "pending" || hook.status === "active" || hook.status === "ready_to_confirm"));
+}
+function upsertHook(state, hook) {
+    const hooks = state.hooks ?? [];
+    const existingIndex = hooks.findIndex((candidate) => candidate.id === hook.id);
+    const nextHooks = existingIndex >= 0
+        ? hooks.map((candidate) => candidate.id === hook.id ? hook : candidate)
+        : [...hooks, hook];
+    return {
+        ...state,
+        hooks: nextHooks
+    };
+}
+export async function beginLongTableInterview(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const existing = activeInterviewHook(state);
+    if (existing) {
+        return { hook: existing, state };
+    }
+    const timestamp = nowIso();
+    const hook = {
+        id: createId("hook_interview"),
+        kind: "longtable_interview",
+        status: "active",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        targetOutcome: "first_research_handle",
+        depth: "gathering_context",
+        provider: options.provider,
+        turns: [],
+        qualityNotes: [],
+        rationale: [
+            "Official LongTable research start surface is provider-native `$longtable-interview`, not the CLI start questionnaire.",
+            "The hook keeps early research ambiguity open until a first research handle can be summarized."
+        ]
+    };
+    let updated = upsertHook(state, hook);
+    updated.workingState = {
+        ...updated.workingState,
+        activeInterviewHookId: hook.id,
+        interviewSurface: "$longtable-interview",
+        ...(options.openingQuestion ? { interviewOpeningQuestion: options.openingQuestion } : {}),
+        ...(options.seedAnswer ? { interviewSeedAnswer: options.seedAnswer } : {})
+    };
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { hook, state: updated };
+}
+export async function appendLongTableInterviewTurn(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const existing = activeInterviewHook(state, options.hookId);
+    if (!existing) {
+        throw new Error("No active LongTable interview hook was found. Run begin_interview first.");
+    }
+    const quality = normalizeInterviewQuality(options.answer, options.quality);
+    const needsFollowUp = options.needsFollowUp ?? quality === "thin";
+    const followUpQuestion = needsFollowUp
+        ? options.followUpQuestion ?? defaultFollowUpQuestion(options.answer)
+        : options.followUpQuestion;
+    const timestamp = nowIso();
+    const turns = existing.turns ?? [];
+    const turn = {
+        id: createId("interview_turn"),
+        index: turns.length + 1,
+        createdAt: timestamp,
+        question: options.question.trim(),
+        answer: options.answer.trim(),
+        ...(options.reflection?.trim() ? { reflection: options.reflection.trim() } : {}),
+        quality,
+        needsFollowUp,
+        ...(followUpQuestion?.trim() ? { followUpQuestion: followUpQuestion.trim() } : {}),
+        ...(options.rationale && options.rationale.length > 0 ? { rationale: options.rationale } : {})
+    };
+    const nextTurns = [...turns, turn];
+    const depth = depthForInterview(nextTurns);
+    const hook = {
+        ...existing,
+        status: depth === "ready_to_summarize" ? "ready_to_confirm" : "active",
+        updatedAt: timestamp,
+        depth,
+        turns: nextTurns,
+        qualityNotes: [
+            ...(existing.qualityNotes ?? []),
+            ...(needsFollowUp ? [`Turn ${turn.index} needs follow-up: ${followUpQuestion}`] : [])
+        ]
+    };
+    const updated = upsertHook(state, hook);
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { hook, turn, state: updated };
+}
+export async function summarizeLongTableInterview(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const existing = activeInterviewHook(state, options.hookId);
+    if (!existing) {
+        throw new Error("No active LongTable interview hook was found. Run begin_interview first.");
+    }
+    const timestamp = nowIso();
+    const shape = {
+        ...options.shape,
+        handle: options.shape.handle.trim(),
+        currentGoal: options.shape.currentGoal.trim(),
+        openQuestions: options.shape.openQuestions.map((question) => question.trim()).filter(Boolean),
+        nextAction: options.shape.nextAction.trim(),
+        sourceHookId: existing.id
+    };
+    const hook = {
+        ...existing,
+        status: "ready_to_confirm",
+        updatedAt: timestamp,
+        depth: "ready_to_summarize",
+        firstResearchShape: shape
+    };
+    const session = {
+        ...options.context.session,
+        lastUpdatedAt: timestamp,
+        currentGoal: shape.currentGoal,
+        ...(shape.currentBlocker ? { currentBlocker: shape.currentBlocker } : {}),
+        ...(shape.researchObject ? { researchObject: shape.researchObject } : {}),
+        ...(shape.gapRisk ? { gapRisk: shape.gapRisk } : {}),
+        ...(shape.protectedDecision ? { protectedDecision: shape.protectedDecision } : {}),
+        nextAction: shape.nextAction,
+        openQuestions: shape.openQuestions,
+        firstResearchShape: shape,
+        resumeHint: `I want to continue from the First Research Shape: ${shape.handle}.`
+    };
+    options.context.session = session;
+    let updated = upsertHook(state, hook);
+    updated.firstResearchShape = shape;
+    updated.workingState = {
+        ...updated.workingState,
+        currentGoal: shape.currentGoal,
+        ...(shape.currentBlocker ? { currentBlocker: shape.currentBlocker } : {}),
+        ...(shape.researchObject ? { researchObject: shape.researchObject } : {}),
+        ...(shape.gapRisk ? { gapRisk: shape.gapRisk } : {}),
+        ...(shape.protectedDecision ? { protectedDecision: shape.protectedDecision } : {}),
+        openQuestions: shape.openQuestions,
+        nextAction: shape.nextAction,
+        firstResearchShape: shape
+    };
+    if (shape.currentBlocker && !updated.openTensions.includes(shape.currentBlocker)) {
+        updated.openTensions.push(shape.currentBlocker);
+    }
+    updated.narrativeTraces.push({
+        id: createId("narrative_trace"),
+        timestamp,
+        source: "$longtable-interview",
+        traceType: "judgment",
+        summary: `First Research Shape: ${shape.handle}.`,
+        visibility: "explicit",
+        importance: shape.confidence
+    });
+    await writeFile(options.context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { hook, shape, state: updated, session };
+}
 function findQuestionForDecision(state, questionId) {
     const pending = (state.questionLog ?? []).filter((record) => record.status === "pending");
     if (questionId) {
@@ -1175,6 +1408,7 @@ export function renderProjectWorkspaceSummary(context) {
         `Goal: ${context.session.currentGoal}`,
         ...(context.session.currentBlocker ? [`Blocker: ${context.session.currentBlocker}`] : []),
         ...(context.session.researchObject ? [`Working object: ${context.session.researchObject}`] : []),
+        ...(context.session.firstResearchShape ? [`First Research Shape: ${context.session.firstResearchShape.handle}`] : []),
         ...(context.session.startInterview ? [`Start interview: ${context.session.startInterview.summary}`] : []),
         "└───────────────────────────────────────────────────────┘",
         "",

package/dist/prompt-aliases.js

@@ -29,18 +29,18 @@ function promptSpec() {
             argumentHint: "[project context or current uncertainty]",
             body: [
                 "You are LongTable setup guidance inside Codex.",
-                "Treat `longtable init` as deprecated. Prefer `longtable setup --provider codex` for runtime permissions, then `longtable start` for the project interview.",
+                "Treat `longtable init` as deprecated. Prefer `longtable setup --provider codex` for runtime permissions, then `$longtable-interview` inside Codex for the project interview.",
                 "Ask exactly one setup question at a time.",
                 "Use numbered choices and include a concise Why / What you get / Tradeoff for each option.",
                 "Do not move to the next question until the researcher answers the current one.",
-                "Runtime setup covers only: provider, install scope, runtime surfaces, intervention strength, and whether to create a workspace now.",
+                "Runtime setup covers only: provider, install scope, runtime surfaces, intervention strength, and whether to show interview launch steps.",
                 "Do not ask for field, career stage, experience level, authorship signal, weakest domain, or panel preference during runtime setup.",
-                "Project start covers: research object, gap/tacit risk, and protected decision area.",
+                "Project interview covers: the first research handle, early uncertainty, first inspectable material, and final structured confirmation.",
                 "After collecting runtime answers, summarize the proposed setup and output the exact `longtable setup --provider codex ...` command.",
-                "If the researcher is ready to create a project workspace, output the exact `longtable start ...` command separately.",
+                "If the researcher is ready to create a project workspace, tell them to open Codex in the research folder and invoke `$longtable-interview`.",
                 "If the researcher asks you to stay inside Codex, keep the conversation in numbered form and do not prematurely close.",
                 "Frame setup as permission and intervention calibration, not a researcher profile interview.",
-                "Do not pretend setup is the full project-start interview. The project-start interview happens in `longtable start`.",
+                "Do not pretend setup is the full project-start interview. The project-start interview happens in `$longtable-interview`.",
                 "Treat any slash-command arguments as context for why setup is being done now."
             ]
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/cli",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "private": false,
   "description": "Researcher-facing LongTable CLI",
   "type": "module",
@@ -29,12 +29,12 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@longtable/checkpoints": "0.1.31",
-    "@longtable/core": "0.1.31",
-    "@longtable/memory": "0.1.31",
-    "@longtable/provider-claude": "0.1.31",
-    "@longtable/provider-codex": "0.1.31",
-    "@longtable/setup": "0.1.31"
+    "@longtable/checkpoints": "0.1.32",
+    "@longtable/core": "0.1.32",
+    "@longtable/memory": "0.1.32",
+    "@longtable/provider-claude": "0.1.32",
+    "@longtable/provider-codex": "0.1.32",
+    "@longtable/setup": "0.1.32"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",