@longtable/cli 0.1.2 → 0.1.4

package/README.md

@@ -1,107 +1,113 @@
 # @longtable/cli
 
-Researcher-facing Long Table CLI built on top of the legacy `@diverga/*` package surface.
+Long Table의 researcher-facing CLI입니다.
 
-현재 공개 설치 경로는 `@longtable/cli`입니다.
+이 패키지의 핵심은 명령을 많이 외우게 하는 것이 아니라, 아래 두 단계를 명확하게 만드는 것입니다.
 
-## Install
+1. `longtable init`
+2. `longtable start`
+
+중요한 점:
 
-공개 설치:
+- 이 두 명령은 **터미널에서 실행하는 셸 명령**입니다.
+- Codex 채팅창에 `longtable start`를 입력하는 것이 아닙니다.
+- `longtable start`로 프로젝트 작업공간을 만든 뒤, 그 디렉토리에서 `codex`를 여는 것이 기본 경로입니다.
+
+## Install
 
 ```bash
 npm install -g @longtable/cli
 ```
 
-로컬 preview:
+## 1. Global setup
 
 ```bash
-npm install
-npm run build
-node packages/longtable/dist/cli.js --help
+longtable init --flow interview
 ```
 
-## Recommended flow
+여기서는 연구자 프로필과 기본 선호를 묻습니다.
 
-Run setup once and install Codex prompt aliases:
+- 연구 분야
+- 연구자 역할
+- challenge 강도
+- 저자성/서사 관련 기본값
+- Long Table이 보통 어디서부터 시작해야 하는지
+
+## 2. Project start
 
 ```bash
-longtable init --flow interview --install-prompts
+longtable start
 ```
 
-`longtable init` now uses an arrow-key terminal menu instead of plain number-entry prompts and supports:
+여기서는 실제 작업공간을 만듭니다.
+
+- 프로젝트 이름
+- 프로젝트 디렉토리 위치
+- 현재 세션 목표
+- 현재 blocker
+- 필요한 관점
+- disagreement 가시성
 
-- `--flow quickstart`
-- `--flow interview`
+그리고 Long Table은:
 
-Then you can work in two ways.
+- 프로젝트 디렉토리 생성
+- `.longtable/` 메모리 파일 생성
+- 프로젝트용 `AGENTS.md` 생성
 
-From the terminal:
+을 수행합니다.
+
+## Recommended flow
 
 ```bash
-longtable ask --prompt "연구를 시작하고 싶어. 지금 어디서부터 좁혀야 할지 모르겠어."
-longtable review --prompt "Review this claim critically."
-longtable review --prompt "BJET 편집자 관점에서 봐줘." --role editor
-longtable review --prompt "방법론적으로 어디가 취약한지 말해줘." --panel --show-conflicts
+longtable init --flow interview
+longtable start
+cd "<project-path>"
+codex
 ```
 
-Inside Codex after prompt aliases are installed:
+이게 현재 가장 신뢰할 수 있는 Long Table 사용 경로입니다.
 
-- `/prompts:longtable`
-- `/prompts:longtable-init`
-- `/prompts:longtable-explore`
-- `/prompts:longtable-review`
-- `/prompts:longtable-critique`
-- `/prompts:longtable-draft`
-- `/prompts:longtable-commit`
-- `/prompts:longtable-status`
+## After the project starts
 
-## Core commands
+프로젝트 디렉토리 안에서는 보통 그냥 `codex`를 열고 자연어로 연구를 시작하면 됩니다.
 
-```bash
-longtable ask --prompt "Help me open this research problem carefully."
-longtable init
-longtable show --json
-longtable install --json
-longtable explore --prompt "Help me stay exploratory."
-longtable review --prompt "Review this claim critically."
-longtable commit --prompt "Help me make this decision carefully."
-```
-
-## Codex overlay
+CLI를 계속 쓰고 싶다면 아래 명령은 보조 경로입니다.
 
-Install Codex prompt aliases:
+## Advanced commands
 
 ```bash
-longtable codex install-prompts
+longtable roles
+longtable ask --cwd "<project-path>" --prompt "연구 질문을 어디서부터 좁혀야 할지 모르겠어."
+longtable review --cwd "<project-path>" --prompt "방법론적으로 어디가 취약한지 말해줘." --role methods_critic
 ```
 
-If you finish onboarding inside Codex with `/prompts:longtable-init`, you can persist the collected answers with:
+## Roles
 
 ```bash
-longtable codex persist-init --flow interview --provider codex --field education --career-stage doctoral --experience intermediate --project-type "journal article" --checkpoint balanced --topic "AI adoption in workplace settings" --blocker "기업 맥락으로 범위를 다시 잡아야 하는데 어디서부터 포함/제외 기준을 세울지 모르겠어." --entry-mode explore --weakest-domain methodology --panel-preference show_on_conflict --install-prompts
+longtable roles
 ```
 
-Or from a JSON block:
+예:
 
-```bash
-pbpaste | longtable codex persist-init --stdin --install-prompts
-```
+- `editor`
+- `reviewer`
+- `methods_critic`
+- `voice_keeper`
 
-Check whether setup and aliases are present:
+## Codex prompt-file integration
 
 ```bash
+longtable codex install-prompts
 longtable codex status
 ```
 
-Remove the aliases:
-
-```bash
-longtable codex remove-prompts
-```
+이 경로는 현재 실험적입니다.  
+사용자에게 약속하는 주 경로는 아닙니다.
 
-## Why this package exists
+기본 경로는 여전히:
 
-Long Table is the product name.
-`Diverga` remains an internal compatibility layer for some lower-level packages and runtime paths.
+- `longtable init`
+- `longtable start`
+- 프로젝트 디렉토리에서 `codex`
 
-This package exists so researchers can install and run `longtable` directly while that compatibility layer remains underneath.
+입니다.

package/dist/cli.js

@@ -3,10 +3,13 @@ import { existsSync, readFileSync } from "node:fs";
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output, cwd, exit } from "node:process";
+import { resolve } from "node:path";
 import { buildProviderChoices, buildQuickSetupFlow, createPersistedSetupOutput, installRuntimeConfigFromStoredSetup, loadSetupOutput, renderInstallSummary, renderSetupSummary, resolveDefaultRuntimeConfigPath, resolveDefaultSetupPath, saveSetupAndRuntimeConfig, serializeSetupOutput } from "@diverga/setup";
 import { buildCodexThinWrappedPrompt, runCodexThinWrapper } from "@diverga/provider-codex";
 import { installCodexPromptAliases, listInstalledCodexPromptAliases, removeCodexPromptAliases, resolveCodexPromptsDir } from "./prompt-aliases.js";
 import { buildPersonaGuidance } from "./persona-router.js";
+import { PERSONA_DEFINITIONS } from "./personas.js";
+import { createOrUpdateProjectWorkspace, loadProjectContextFromDirectory, renderProjectWorkspaceSummary } from "./project-session.js";
 const VALID_MODES = new Set([
     "explore",
     "review",
@@ -27,7 +30,12 @@ const VALID_STAGES = new Set([
 function usage() {
     return [
         "Usage:",
-        "  longtable init [--flow quickstart|interview] [--provider codex|claude] [--field <field>] [--career-stage <stage>] [--experience novice|intermediate|advanced] [--project-type <type>] [--checkpoint low|balanced|high] [--authorship-signal <text>] [--topic <text>] [--blocker <text>] [--entry-mode explore|review|critique|draft|commit] [--weakest-domain theory|methodology|measurement|analysis|writing] [--panel-preference synthesis_only|show_on_conflict|always_visible] [--json] [--no-install] [--install-prompts]",
+        "  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 init [--flow quickstart|interview] [--provider codex|claude] [--field <field>] [--career-stage <stage>] [--experience novice|intermediate|advanced] [--checkpoint low|balanced|high] [--authorship-signal <text>] [--entry-mode explore|review|critique|draft|commit] [--weakest-domain theory|methodology|measurement|analysis|writing] [--panel-preference synthesis_only|show_on_conflict|always_visible] [--json] [--no-install] [--install-prompts]",
+        "  longtable start [--path <dir>] [--name <project>] [--goal <text>] [--blocker <text>] [--perspectives <role[,role]>] [--disagreement synthesis_only|show_on_conflict|always_visible] [--setup <path>] [--json]",
+        "  longtable roles [--json]",
         "  longtable show [--json] [--path <file>]",
         "  longtable install [--json] [--path <file>] [--runtime-path <file>]",
         "  longtable ask [--prompt <text>] [--print] [--json] [--setup <path>] [--cwd <path>]",
@@ -39,9 +47,11 @@ function usage() {
         "",
         "Examples:",
         "  longtable init --flow interview --install-prompts",
+        "  longtable start",
+        "  longtable start --path ~/Research/My-Project --name \"AI Adoption Meta-Analysis\" --goal \"Narrow the review question\"",
+        "  cd \"<project-path>\" && codex",
+        "  longtable roles",
         "  longtable ask --prompt \"연구를 시작하고 싶어. 지금 어디서부터 좁혀야 할지 모르겠어.\"",
-        "  longtable review --prompt \"Review this claim critically.\" --panel --show-conflicts",
-        "  longtable review --role editor --prompt \"BJET 편집자 관점에서 봐줘.\"",
         "  printf '{\"provider\":\"codex\",...}' | longtable codex persist-init --stdin --install-prompts",
         "  longtable codex install-prompts"
     ].join("\n");
@@ -51,7 +61,7 @@ function parseArgs(argv) {
     const values = {};
     let subcommand = maybeSubcommand;
     const modeCommand = command && VALID_MODES.has(command);
-    const directCommand = command && ["init", "show", "install", "codex", "ask"].includes(command);
+    const directCommand = command && ["init", "start", "roles", "show", "install", "codex", "ask"].includes(command);
     let startIndex = 1;
     if (modeCommand) {
         subcommand = undefined;
@@ -110,7 +120,7 @@ function buildSetupFlowChoices() {
 function renderSetupHeader(flow) {
     const title = flow === "interview" ? "Long Table Setup Interview" : "Long Table Quickstart";
     const subtitle = flow === "interview"
-        ? "We will ask about your research persona, current topic, blocker, and preferred kind of challenge."
+        ? "We will ask about your research persona, challenge preferences, and authorship defaults."
         : "We will capture the minimum profile needed to start using Long Table.";
     return [
         "┌──────────────────────────────────────────────┐",
@@ -126,9 +136,6 @@ function questionSection(questionId) {
     if (questionId === "field" || questionId === "careerStage" || questionId === "experienceLevel") {
         return "Researcher profile";
     }
-    if (questionId === "currentProjectType" || questionId === "currentResearchTopic" || questionId === "currentBlocker") {
-        return "Current work";
-    }
     if (questionId === "preferredCheckpointIntensity" || questionId === "preferredEntryMode") {
         return "Interaction style";
     }
@@ -137,6 +144,9 @@ function questionSection(questionId) {
     }
     return "Authorship and voice";
 }
+function formatModeLabel(mode) {
+    return `${mode[0].toUpperCase()}${mode.slice(1)}`;
+}
 function moveCursorUp(lines) {
     return lines > 0 ? `\u001B[${lines}A` : "";
 }
@@ -252,8 +262,84 @@ async function promptChoiceWithArrows(rl, prompt, choices) {
 async function promptChoice(rl, prompt, choices) {
     return promptChoiceWithArrows(rl, prompt, choices);
 }
+async function promptMultiChoice(rl, prompt, choices) {
+    const stream = input;
+    if (!stream.isTTY || !output.isTTY) {
+        const answer = await rl.question(`${prompt}\nType comma-separated ids or leave blank for auto.\n> `);
+        return answer
+            .split(",")
+            .map((part) => part.trim())
+            .filter(Boolean);
+    }
+    const previousRawMode = stream.isRaw;
+    let selectedIndex = 0;
+    const selected = new Set();
+    const renderedLineCount = choices.length + 2;
+    return await new Promise((resolvePromise, reject) => {
+        function draw(first = false) {
+            if (!first) {
+                output.write(moveCursorUp(renderedLineCount));
+            }
+            const lines = [prompt, "Use ↑/↓, Space to toggle, and Enter to confirm."];
+            for (let index = 0; index < choices.length; index += 1) {
+                const choice = choices[index];
+                const pointer = index === selectedIndex ? ">" : " ";
+                const marker = selected.has(choice.id) ? "[x]" : "[ ]";
+                lines.push(`${pointer} ${marker} ${choice.label} - ${choice.description}`);
+            }
+            for (const line of lines) {
+                output.write(clearLine());
+                output.write(`${line}\n`);
+            }
+        }
+        function cleanup() {
+            stream.off("keypress", onKeypress);
+            if (stream.isTTY) {
+                stream.setRawMode(previousRawMode ?? false);
+            }
+            output.write("\u001B[?25h");
+        }
+        function onKeypress(_, key) {
+            if (key.ctrl && key.name === "c") {
+                cleanup();
+                reject(new Error("Setup cancelled."));
+                return;
+            }
+            if (key.name === "up") {
+                selectedIndex = selectedIndex === 0 ? choices.length - 1 : selectedIndex - 1;
+                draw();
+                return;
+            }
+            if (key.name === "down") {
+                selectedIndex = selectedIndex === choices.length - 1 ? 0 : selectedIndex + 1;
+                draw();
+                return;
+            }
+            if (key.name === "space") {
+                const id = choices[selectedIndex].id;
+                if (selected.has(id)) {
+                    selected.delete(id);
+                }
+                else {
+                    selected.add(id);
+                }
+                draw();
+                return;
+            }
+            if (key.name === "return") {
+                cleanup();
+                resolvePromise([...selected]);
+            }
+        }
+        emitKeypressEvents(stream);
+        stream.setRawMode(true);
+        output.write("\u001B[?25l");
+        draw(true);
+        stream.on("keypress", onKeypress);
+    });
+}
 function hasCompleteFlagInput(args) {
-    const required = ["provider", "field", "career-stage", "experience", "project-type", "checkpoint"];
+    const required = ["provider", "field", "career-stage", "experience", "checkpoint"];
     return required.every((key) => typeof args[key] === "string" && String(args[key]).trim().length > 0);
 }
 function resolveSetupFlow(args) {
@@ -264,13 +350,13 @@ function toSetupAnswers(args) {
         field: String(args.field),
         careerStage: String(args["career-stage"]),
         experienceLevel: String(args.experience),
-        currentProjectType: String(args["project-type"]),
+        currentProjectType: typeof args["project-type"] === "string" && args["project-type"].trim().length > 0
+            ? String(args["project-type"])
+            : "unspecified research task",
         preferredCheckpointIntensity: String(args.checkpoint),
         humanAuthorshipSignal: typeof args["authorship-signal"] === "string" && args["authorship-signal"].trim().length > 0
             ? args["authorship-signal"].trim()
             : undefined,
-        currentResearchTopic: typeof args.topic === "string" && args.topic.trim().length > 0 ? args.topic.trim() : undefined,
-        currentBlocker: typeof args.blocker === "string" && args.blocker.trim().length > 0 ? args.blocker.trim() : undefined,
         preferredEntryMode: typeof args["entry-mode"] === "string" && VALID_MODES.has(String(args["entry-mode"]))
             ? String(args["entry-mode"])
             : undefined,
@@ -282,15 +368,18 @@ function toSetupAnswers(args) {
             : undefined
     };
 }
-async function collectInteractiveAnswers() {
+async function collectInteractiveAnswers(initialFlow) {
     const rl = createInterface({ input, output });
     try {
-        const flow = (await promptChoice(rl, "How would you like to set up Long Table?", buildSetupFlowChoices()));
+        const flow = initialFlow ??
+            (await promptChoice(rl, "How would you like to set up Long Table?", buildSetupFlowChoices()));
         console.log("");
         console.log(renderSetupHeader(flow));
         console.log("");
         const provider = await promptChoice(rl, "Which provider do you want to configure?", buildProviderChoices());
-        const answers = {};
+        const answers = {
+            currentProjectType: "unspecified research task"
+        };
         const questions = buildQuickSetupFlow(flow);
         for (let index = 0; index < questions.length; index += 1) {
             const question = questions[index];
@@ -311,18 +400,12 @@ async function collectInteractiveAnswers() {
                 answers.careerStage = value;
             if (question.id === "experienceLevel")
                 answers.experienceLevel = value;
-            if (question.id === "currentProjectType")
-                answers.currentProjectType = value;
             if (question.id === "preferredCheckpointIntensity") {
                 answers.preferredCheckpointIntensity = value;
             }
             if (question.id === "humanAuthorshipSignal" && value !== "other") {
                 answers.humanAuthorshipSignal = value;
             }
-            if (question.id === "currentResearchTopic")
-                answers.currentResearchTopic = value;
-            if (question.id === "currentBlocker")
-                answers.currentBlocker = value;
             if (question.id === "preferredEntryMode")
                 answers.preferredEntryMode = value;
             if (question.id === "weakestDomain")
@@ -340,6 +423,84 @@ async function collectInteractiveAnswers() {
         rl.close();
     }
 }
+function perspectiveChoices() {
+    return PERSONA_DEFINITIONS.map((persona) => ({
+        id: persona.key,
+        label: persona.label,
+        description: persona.shortDescription
+    }));
+}
+function normalizePerspectiveList(value) {
+    if (!value?.trim()) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+async function collectProjectInterview(setup, args) {
+    const needsInteractivePrompts = !(typeof args.name === "string" && args.name.trim()) ||
+        !(typeof args.path === "string" && args.path.trim()) ||
+        !(typeof args.goal === "string" && args.goal.trim()) ||
+        typeof args.blocker !== "string" ||
+        normalizePerspectiveList(typeof args.perspectives === "string" ? args.perspectives : undefined).length === 0 ||
+        !(typeof args.disagreement === "string" && args.disagreement.trim());
+    const rl = createInterface({ input, output });
+    try {
+        if (needsInteractivePrompts) {
+            console.log("");
+            console.log("┌──────────────────────────────────────────────┐");
+            console.log("│ Long Table Project Start                    │");
+            console.log("└──────────────────────────────────────────────┘");
+            console.log("We will create a project workspace and a session memory seed for today's work.");
+            console.log("");
+        }
+        const projectName = (typeof args.name === "string" && args.name.trim()) ||
+            (await promptText(rl, renderQuestionHeader(1, 6, "Project interview", "What should this project be called?"), true));
+        const suggestedPath = typeof args.path === "string" && args.path.trim()
+            ? args.path.trim()
+            : resolve(projectName.replace(/\s+/g, "-"));
+        const projectPath = (typeof args.path === "string" && args.path.trim()) ||
+            (await promptText(rl, renderQuestionHeader(2, 6, "Project interview", `Where should this project live on your machine?\nSuggested path: ${suggestedPath}`), true));
+        const currentGoal = (typeof args.goal === "string" && args.goal.trim()) ||
+            (await promptText(rl, renderQuestionHeader(3, 6, "Current session", "What are you trying to accomplish in this session?"), true));
+        const currentBlocker = (typeof args.blocker === "string" && args.blocker.trim()) ||
+            (await promptText(rl, renderQuestionHeader(4, 6, "Current session", "What is the main blocker or uncertainty right now?"), false));
+        const requestedPerspectives = normalizePerspectiveList(typeof args.perspectives === "string" ? args.perspectives : undefined).length > 0
+            ? normalizePerspectiveList(typeof args.perspectives === "string" ? args.perspectives : undefined)
+            : await promptMultiChoice(rl, renderQuestionHeader(5, 6, "Perspectives", "Which perspectives do you already know you want at the table? Leave everything unchecked for auto."), perspectiveChoices());
+        const disagreementPreference = (typeof args.disagreement === "string" && args.disagreement.trim()) ||
+            (await promptChoice(rl, renderQuestionHeader(6, 6, "Disagreement", "How visible should disagreement between perspectives be in this project by default?"), [
+                {
+                    id: "synthesis_only",
+                    label: "Synthesis only",
+                    description: "Show one Long Table answer unless I ask for more."
+                },
+                {
+                    id: "show_on_conflict",
+                    label: "Show on conflict",
+                    description: "Surface disagreement when the perspectives materially diverge."
+                },
+                {
+                    id: "always_visible",
+                    label: "Always visible",
+                    description: "Keep panel opinions visible by default."
+                }
+            ]));
+        return {
+            projectName: projectName.trim(),
+            projectPath: projectPath.trim(),
+            currentGoal: currentGoal.trim(),
+            ...(currentBlocker?.trim() ? { currentBlocker: currentBlocker.trim() } : {}),
+            requestedPerspectives,
+            disagreementPreference: disagreementPreference
+        };
+    }
+    finally {
+        rl.close();
+    }
+}
 function normalizePersistAnswers(raw) {
     return {
         flow: raw.flow === "interview" ? "interview" : "quickstart",
@@ -348,17 +509,11 @@ function normalizePersistAnswers(raw) {
             field: raw.field,
             careerStage: raw.careerStage,
             experienceLevel: raw.experienceLevel,
-            currentProjectType: raw.currentProjectType,
+            currentProjectType: "unspecified research task",
             preferredCheckpointIntensity: raw.preferredCheckpointIntensity,
             ...(raw.humanAuthorshipSignal?.trim()
                 ? { humanAuthorshipSignal: raw.humanAuthorshipSignal.trim() }
                 : {}),
-            ...(raw.currentResearchTopic?.trim()
-                ? { currentResearchTopic: raw.currentResearchTopic.trim() }
-                : {}),
-            ...(raw.currentBlocker?.trim()
-                ? { currentBlocker: raw.currentBlocker.trim() }
-                : {}),
             ...(raw.preferredEntryMode
                 ? { preferredEntryMode: raw.preferredEntryMode }
                 : {}),
@@ -408,7 +563,7 @@ async function runInit(args) {
             provider: String(args.provider) === "claude" ? "claude" : "codex",
             answers: toSetupAnswers(args)
         }
-        : await collectInteractiveAnswers();
+        : await collectInteractiveAnswers(typeof args.flow === "string" ? resolveSetupFlow(args) : undefined);
     const outputValue = createPersistedSetupOutput(answers, provider, flow);
     const result = await saveSetupAndRuntimeConfig(outputValue, {
         setupPath: customPath,
@@ -429,24 +584,19 @@ async function runInit(args) {
     }
     if (installedPrompts.length > 0) {
         console.log("");
-        console.log("Installed Codex prompt aliases:");
+        console.log("Installed Codex prompt files:");
         for (const prompt of installedPrompts) {
             console.log(`- /prompts:${prompt.name}`);
         }
+        console.log("  Note: whether Codex exposes these as slash commands depends on your Codex build.");
     }
     if (provider === "codex") {
         console.log("");
         console.log("Next step:");
-        console.log("- Open Codex and start with `/prompts:longtable`.");
-        if (answers.currentBlocker) {
-            console.log(`- Suggested first message: ${answers.currentBlocker}`);
-        }
-        else if (answers.currentResearchTopic) {
-            console.log(`- Suggested first message: Help me open the problem around ${answers.currentResearchTopic}.`);
-        }
-        else {
-            console.log("- Suggested first message: I want to start my research and need help opening the problem.");
-        }
+        console.log("- Start here: `longtable start`.");
+        console.log("- If you want a direct natural-language entry: `longtable ask --prompt \"...\"`.");
+        console.log("- Codex prompt files are available as an experimental integration, not the primary path.");
+        console.log("- Suggested next action: create a project workspace and let Long Table interview the current session.");
     }
 }
 async function runShow(args) {
@@ -492,24 +642,19 @@ async function runCodexPersistInit(args) {
     console.log(renderInstallSummary(result));
     if (installedPrompts.length > 0) {
         console.log("");
-        console.log("Installed Codex prompt aliases:");
+        console.log("Installed Codex prompt files:");
         for (const prompt of installedPrompts) {
             console.log(`- /prompts:${prompt.name}`);
         }
+        console.log("  Note: whether Codex exposes these as slash commands depends on your Codex build.");
     }
     if (provider === "codex") {
         console.log("");
         console.log("Next step:");
-        console.log("- Start Codex and use `/prompts:longtable` for the most natural entry.");
-        if (answers.currentBlocker) {
-            console.log(`- Suggested first message: ${answers.currentBlocker}`);
-        }
-        else if (answers.currentResearchTopic) {
-            console.log(`- Suggested first message: Help me think through ${answers.currentResearchTopic}.`);
-        }
-        else {
-            console.log("- Suggested first message: I want to start my research and I am not sure where to open the problem.");
-        }
+        console.log("- Start here: `longtable start`.");
+        console.log("- If you want a direct natural-language entry: `longtable ask --prompt \"...\"`.");
+        console.log("- Codex prompt files are available as an experimental integration, not the primary path.");
+        console.log("- Suggested next action: create a project workspace and let Long Table interview the current session.");
     }
 }
 async function resolvePrompt(prompt) {
@@ -578,7 +723,25 @@ async function loadOptionalSetup(path) {
         return null;
     }
 }
+async function buildProjectAwarePrompt(prompt, workingDirectory) {
+    const context = await loadProjectContextFromDirectory(workingDirectory);
+    if (!context) {
+        return { prompt, projectContextFound: false };
+    }
+    const lines = [
+        "Long Table project context",
+        `project: ${context.project.projectName}`,
+        `current session goal: ${context.session.currentGoal}`,
+        ...(context.session.currentBlocker ? [`current blocker: ${context.session.currentBlocker}`] : []),
+        `requested perspectives: ${context.session.requestedPerspectives.length > 0 ? context.session.requestedPerspectives.join(", ") : "auto"}`,
+        `disagreement preference: ${context.session.disagreementPreference}`,
+        "",
+        prompt
+    ];
+    return { prompt: lines.join("\n"), projectContextFound: true };
+}
 async function runModeCommand(mode, args) {
+    const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();
     const prompt = await resolvePrompt(typeof args.prompt === "string" ? args.prompt : undefined);
     if (!prompt) {
         throw new Error("A prompt is required.");
@@ -588,13 +751,14 @@ async function runModeCommand(mode, args) {
         throw new Error(`Invalid stage: ${stage}`);
     }
     const setup = await loadOptionalSetup(typeof args.setup === "string" ? args.setup : undefined);
+    const projectAware = await buildProjectAwarePrompt(prompt, workingDirectory);
     const panelPreference = setup?.profileSeed.panelPreference;
     const panelRequested = args.panel === true ||
         panelPreference === "always_visible" ||
         (panelPreference === "show_on_conflict" && args["show-conflicts"] === true);
     const { guidedPrompt } = buildPersonaGuidance({
         mode,
-        prompt,
+        prompt: projectAware.prompt,
         roleFlag: typeof args.role === "string" ? args.role : undefined,
         panel: panelRequested,
         showConflicts: args["show-conflicts"] === true,
@@ -606,7 +770,7 @@ async function runModeCommand(mode, args) {
             mode,
             researchStage: stage,
             setupPath: typeof args.setup === "string" ? args.setup : undefined,
-            workingDirectory: typeof args.cwd === "string" ? args.cwd : cwd()
+            workingDirectory
         });
         console.log(wrapped.wrappedPrompt);
         return;
@@ -616,7 +780,7 @@ async function runModeCommand(mode, args) {
         mode,
         researchStage: stage,
         setupPath: typeof args.setup === "string" ? args.setup : undefined,
-        workingDirectory: typeof args.cwd === "string" ? args.cwd : cwd(),
+        workingDirectory,
         json: args.json === true
     });
     exit(exitCode);
@@ -642,11 +806,67 @@ async function runAsk(args) {
     }
     await runModeCommand(mode, delegatedArgs);
 }
+async function runRoles(args) {
+    const payload = PERSONA_DEFINITIONS.map((persona) => ({
+        key: persona.key,
+        label: persona.label,
+        description: persona.shortDescription,
+        triggerMode: persona.triggerMode,
+        exampleTriggers: persona.synonyms.slice(0, 4)
+    }));
+    if (args.json === true) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log("Long Table roles");
+    console.log("These are perspectives Long Table can consult when relevant.");
+    console.log("");
+    for (const persona of payload) {
+        console.log(`- ${persona.label} (${persona.key})`);
+        console.log(`  ${persona.description}`);
+        console.log(`  Trigger: ${persona.triggerMode === "auto-callable" ? "auto-callable when your language strongly implies it" : "explicit request only"}`);
+        console.log(`  Examples: ${persona.exampleTriggers.join(", ")}`);
+    }
+}
+async function runStart(args) {
+    const setupPath = typeof args.setup === "string" ? args.setup : undefined;
+    const existingSetup = await loadOptionalSetup(setupPath);
+    if (!existingSetup) {
+        throw new Error("Long Table global setup is missing. Run `longtable init --flow interview` first.");
+    }
+    const interview = await collectProjectInterview(existingSetup, args);
+    const context = await createOrUpdateProjectWorkspace({
+        projectName: interview.projectName,
+        projectPath: interview.projectPath,
+        currentGoal: interview.currentGoal,
+        currentBlocker: interview.currentBlocker,
+        requestedPerspectives: interview.requestedPerspectives,
+        disagreementPreference: interview.disagreementPreference,
+        setup: existingSetup
+    });
+    if (args.json === true) {
+        console.log(JSON.stringify({
+            project: context.project,
+            session: context.session,
+            projectFilePath: context.projectFilePath,
+            sessionFilePath: context.sessionFilePath
+        }, null, 2));
+        return;
+    }
+    console.log(renderProjectWorkspaceSummary(context));
+    console.log("");
+    console.log("Next step:");
+    console.log(`- cd "${context.project.projectPath}"`);
+    console.log("- start Codex in that directory if you want a plain Codex session that inherits Long Table project instructions");
+    console.log(`- or run: longtable ask --cwd "${context.project.projectPath}" --prompt "${context.session.currentGoal.replaceAll("\"", "\\\"")}"`);
+    console.log("- the workspace now includes `.longtable/` memory files and a project-scoped `AGENTS.md`");
+}
 async function runCodexSubcommand(subcommand, args) {
     const customDir = typeof args.dir === "string" ? args.dir : undefined;
     if (subcommand === "install-prompts") {
         const installed = await installCodexPromptAliases(customDir);
         console.log(`Installed ${installed.length} Long Table prompt aliases in ${resolveCodexPromptsDir(customDir)}`);
+        console.log("Note: prompt-file discovery depends on the Codex build. Treat this as an experimental integration.");
         for (const prompt of installed) {
             console.log(`- /prompts:${prompt.name}`);
         }
@@ -681,6 +901,7 @@ async function runCodexSubcommand(subcommand, args) {
         console.log(`- setup: ${status.setupExists ? "present" : "missing"} (${setupPath})`);
         console.log(`- codex runtime artifact: ${status.runtimeExists ? "present" : "missing"} (${runtimePath})`);
         console.log(`- prompt aliases dir: ${status.promptsDir}`);
+        console.log("- prompt-file integration: experimental (your Codex build may not expose these as slash commands)");
         if (aliases.length === 0) {
             console.log("- prompt aliases: none");
         }
@@ -705,6 +926,14 @@ async function main() {
         await runInit(values);
         return;
     }
+    if (command === "start") {
+        await runStart(values);
+        return;
+    }
+    if (command === "roles") {
+        await runRoles(values);
+        return;
+    }
     if (command === "show") {
         await runShow(values);
         return;

package/dist/project-session.d.ts

@@ -0,0 +1,47 @@
+import type { SetupPersistedOutput } from "@diverga/setup";
+export type ProjectDisagreementPreference = "synthesis_only" | "show_on_conflict" | "always_visible";
+export interface LongTableProjectRecord {
+    schemaVersion: 1;
+    product: "Long Table";
+    projectName: string;
+    projectPath: string;
+    createdAt: string;
+    globalSetupSummary: {
+        field: string;
+        careerStage: string;
+        experienceLevel: string;
+        checkpointIntensity: string;
+        humanAuthorshipSignal?: string;
+        weakestDomain?: string;
+        defaultPanelPreference?: ProjectDisagreementPreference;
+    };
+}
+export interface LongTableSessionRecord {
+    schemaVersion: 1;
+    id: string;
+    createdAt: string;
+    projectName: string;
+    projectPath: string;
+    currentGoal: string;
+    currentBlocker?: string;
+    requestedPerspectives: string[];
+    disagreementPreference: ProjectDisagreementPreference;
+}
+export interface LongTableProjectContext {
+    project: LongTableProjectRecord;
+    session: LongTableSessionRecord;
+    projectFilePath: string;
+    sessionFilePath: string;
+    metaDir: string;
+}
+export declare function createOrUpdateProjectWorkspace(options: {
+    projectName: string;
+    projectPath: string;
+    currentGoal: string;
+    currentBlocker?: string;
+    requestedPerspectives: string[];
+    disagreementPreference: ProjectDisagreementPreference;
+    setup: SetupPersistedOutput;
+}): Promise<LongTableProjectContext>;
+export declare function loadProjectContextFromDirectory(startPath: string): Promise<LongTableProjectContext | null>;
+export declare function renderProjectWorkspaceSummary(context: LongTableProjectContext): string;

package/dist/project-session.js

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createEmptyResearchState } from "@diverga/memory";
+function nowIso() {
+    return new Date().toISOString();
+}
+function slugify(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9가-힣]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+function resolveMetaDir(projectPath) {
+    return join(projectPath, ".longtable");
+}
+function buildWorkspaceGuide(project, session) {
+    const lines = [
+        "# Long Table Workspace",
+        "",
+        "This directory is a Long Table research workspace.",
+        "",
+        "## Current project",
+        `- Project: ${project.projectName}`,
+        `- Goal right now: ${session.currentGoal}`,
+        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
+        `- Disagreement visibility: ${session.disagreementPreference}`,
+        `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
+        "",
+        "## How Codex should behave here",
+        "- Treat this as a researcher-facing Long Table session, not a generic coding task.",
+        "- Ask clarifying or tension questions before closing too early.",
+        "- If you foreground specific roles, disclose them with `Long Table consulted: ...`.",
+        "- Keep one accountable synthesis, but keep disagreement visible by default when it matters.",
+        "- Do not expose internal tool logs or process commentary in researcher-facing answers.",
+        "",
+        "## Session files",
+        "- `.longtable/project.json` contains project-level metadata.",
+        "- `.longtable/current-session.json` contains the current session goal and blocker."
+    ];
+    return lines.join("\n");
+}
+function buildProjectAgentsMd(project, session) {
+    return [
+        "# AGENTS.md",
+        "",
+        "This directory is a Long Table research workspace.",
+        "",
+        "## Purpose",
+        `- Project name: ${project.projectName}`,
+        `- Current goal: ${session.currentGoal}`,
+        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
+        `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
+        `- Disagreement visibility: ${session.disagreementPreference}`,
+        "",
+        "## Research-facing behavior",
+        "- Treat researcher interaction as the primary task.",
+        "- Begin exploratory work with clarifying or tension questions before recommending a direction.",
+        "- If you foreground role perspectives, disclose them with `Long Table consulted: ...`.",
+        "- Keep one accountable synthesis, but do not hide meaningful disagreement.",
+        "- Do not expose internal tool logs, file-search traces, or process commentary in the researcher-facing answer.",
+        "",
+        "## Session memory",
+        "- Read `.longtable/current-session.json` before giving substantial guidance.",
+        "- Use `.longtable/project.json` as the project-level context.",
+        "- Prefer the current goal and blocker over generic assumptions.",
+        "",
+        "## Scope",
+        "- These instructions apply to this directory and its children."
+    ].join("\n");
+}
+function buildStateSeed(project, session, setup) {
+    const state = createEmptyResearchState();
+    state.explicitState = {
+        field: setup.profileSeed.field,
+        careerStage: setup.profileSeed.careerStage,
+        experienceLevel: setup.profileSeed.experienceLevel,
+        projectName: project.projectName,
+        currentGoal: session.currentGoal,
+        disagreementPreference: session.disagreementPreference,
+        requestedPerspectives: session.requestedPerspectives
+    };
+    if (session.currentBlocker) {
+        state.explicitState.currentBlocker = session.currentBlocker;
+        state.openTensions.push(session.currentBlocker);
+    }
+    if (setup.profileSeed.humanAuthorshipSignal) {
+        state.explicitState.humanAuthorshipSignal = setup.profileSeed.humanAuthorshipSignal;
+    }
+    state.narrativeTraces.push({
+        id: "project-session-goal",
+        timestamp: nowIso(),
+        source: "longtable-start",
+        traceType: "judgment",
+        summary: `Current session goal: ${session.currentGoal}.`,
+        visibility: "explicit",
+        importance: "high"
+    });
+    if (session.currentBlocker) {
+        state.narrativeTraces.push({
+            id: "project-session-blocker",
+            timestamp: nowIso(),
+            source: "longtable-start",
+            traceType: "tension",
+            summary: `Current session blocker: ${session.currentBlocker}.`,
+            visibility: "explicit",
+            importance: "high"
+        });
+    }
+    return JSON.stringify(state, null, 2);
+}
+export async function createOrUpdateProjectWorkspace(options) {
+    const projectPath = resolve(options.projectPath);
+    const metaDir = resolveMetaDir(projectPath);
+    const sessionsDir = join(metaDir, "sessions");
+    const projectFilePath = join(metaDir, "project.json");
+    const sessionFilePath = join(metaDir, "current-session.json");
+    const sessionId = slugify(`${options.projectName}-${Date.now()}`);
+    await mkdir(projectPath, { recursive: true });
+    await mkdir(metaDir, { recursive: true });
+    await mkdir(sessionsDir, { recursive: true });
+    const project = existsSync(projectFilePath)
+        ? JSON.parse(await readFile(projectFilePath, "utf8"))
+        : {
+            schemaVersion: 1,
+            product: "Long Table",
+            projectName: options.projectName,
+            projectPath,
+            createdAt: nowIso(),
+            globalSetupSummary: {
+                field: options.setup.profileSeed.field,
+                careerStage: options.setup.profileSeed.careerStage,
+                experienceLevel: options.setup.profileSeed.experienceLevel,
+                checkpointIntensity: options.setup.profileSeed.preferredCheckpointIntensity,
+                ...(options.setup.profileSeed.humanAuthorshipSignal
+                    ? { humanAuthorshipSignal: options.setup.profileSeed.humanAuthorshipSignal }
+                    : {}),
+                ...(options.setup.profileSeed.weakestDomain
+                    ? { weakestDomain: options.setup.profileSeed.weakestDomain }
+                    : {}),
+                ...(options.setup.profileSeed.panelPreference
+                    ? { defaultPanelPreference: options.setup.profileSeed.panelPreference }
+                    : {})
+            }
+        };
+    const session = {
+        schemaVersion: 1,
+        id: sessionId,
+        createdAt: nowIso(),
+        projectName: project.projectName,
+        projectPath,
+        currentGoal: options.currentGoal,
+        ...(options.currentBlocker ? { currentBlocker: options.currentBlocker } : {}),
+        requestedPerspectives: options.requestedPerspectives,
+        disagreementPreference: options.disagreementPreference
+    };
+    await writeFile(projectFilePath, JSON.stringify(project, null, 2), "utf8");
+    await writeFile(sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(join(sessionsDir, `${sessionId}.json`), JSON.stringify(session, null, 2), "utf8");
+    await writeFile(join(metaDir, "state.json"), buildStateSeed(project, session, options.setup), "utf8");
+    await writeFile(join(projectPath, "LONGTABLE.md"), buildWorkspaceGuide(project, session), "utf8");
+    await writeFile(join(projectPath, "AGENTS.md"), buildProjectAgentsMd(project, session), "utf8");
+    return {
+        project,
+        session,
+        projectFilePath,
+        sessionFilePath,
+        metaDir
+    };
+}
+export async function loadProjectContextFromDirectory(startPath) {
+    let current = resolve(startPath);
+    while (true) {
+        const metaDir = resolveMetaDir(current);
+        const projectFilePath = join(metaDir, "project.json");
+        const sessionFilePath = join(metaDir, "current-session.json");
+        if (existsSync(projectFilePath) && existsSync(sessionFilePath)) {
+            return {
+                project: JSON.parse(await readFile(projectFilePath, "utf8")),
+                session: JSON.parse(await readFile(sessionFilePath, "utf8")),
+                projectFilePath,
+                sessionFilePath,
+                metaDir
+            };
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function renderProjectWorkspaceSummary(context) {
+    return [
+        "Long Table project workspace",
+        `project: ${context.project.projectName}`,
+        `path: ${context.project.projectPath}`,
+        `goal: ${context.session.currentGoal}`,
+        ...(context.session.currentBlocker ? [`blocker: ${context.session.currentBlocker}`] : []),
+        `perspectives: ${context.session.requestedPerspectives.length > 0 ? context.session.requestedPerspectives.join(", ") : "auto"}`,
+        `disagreement: ${context.session.disagreementPreference}`,
+        `project file: ${context.projectFilePath}`,
+        `session file: ${context.sessionFilePath}`
+    ].join("\n");
+}

package/dist/prompt-aliases.js

@@ -33,12 +33,13 @@ function promptSpec() {
                 "Ask exactly one setup question at a time.",
                 "Use numbered choices when possible and include a 'None of the above' option when needed.",
                 "Do not move to the next question until the researcher answers the current one.",
-                "Quickstart covers: provider, field, career stage, experience level, current project type, checkpoint intensity, and human authorship signal.",
-                "Interview also covers: current research topic, current blocker, preferred entry mode, weakest domain, and panel visibility preference.",
-                "After collecting all answers, summarize the proposed setup and then output both: 1) the exact `longtable codex persist-init ... --install-prompts` command and 2) a strict JSON object with keys provider, flow, field, careerStage, experienceLevel, currentProjectType, preferredCheckpointIntensity, and optional humanAuthorshipSignal, currentResearchTopic, currentBlocker, preferredEntryMode, weakestDomain, panelPreference.",
+                "Quickstart covers: provider, field, career stage, experience level, checkpoint intensity, and human authorship signal.",
+                "Interview also covers: preferred entry mode, weakest domain, and panel visibility preference.",
+                "After collecting all answers, summarize the proposed setup and then output both: 1) the exact `longtable codex persist-init ... --install-prompts` command and 2) a strict JSON object with keys provider, flow, field, careerStage, experienceLevel, preferredCheckpointIntensity, and optional humanAuthorshipSignal, preferredEntryMode, weakestDomain, panelPreference.",
                 "If the user prefers paste-based setup, tell them they can pipe the JSON into `longtable codex persist-init --stdin --install-prompts`.",
                 "If the researcher asks you to stay inside Codex, keep the conversation in numbered form and do not prematurely close.",
                 "Frame the setup like a short researcher interview, not a bare config form.",
+                "Do not pretend that this is the full project-start interview. The real project-start interview happens in `longtable start`.",
                 "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.2",
+  "version": "0.1.4",
   "private": false,
   "description": "Researcher-facing Long Table CLI on top of the legacy Diverga package surface",
   "type": "module",
@@ -25,8 +25,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@diverga/memory": "0.1.0",
     "@diverga/provider-codex": "0.1.1",
-    "@diverga/setup": "0.1.2"
+    "@diverga/setup": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",