@longtable/setup 0.1.9

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.1.4
+
+- treat global setup as researcher-profile onboarding, not project intake
+- remove project-specific defaults from setup examples and persisted summaries
+- align setup output with the new `longtable start` project interview flow
+
+## 0.1.3
+
+- make setup prompts read more like a short researcher interview and less like a raw config form
+
+## 0.1.2
+
+- add `quickstart` and `interview` setup flows
+- persist topic, blocker, preferred entry mode, weakest domain, and panel preference
+- enrich runtime artifacts so setup can connect directly to the first research question
+
+## 0.1.1
+
+- switch CLI packaging to `directories.bin` so npm preserves the published executable
+- keep the executable name as `longtable-setup`
+
+## 0.1.0
+
+- initial publish-ready setup package scaffold
+- quick setup flow and provider selection
+- persisted setup output generation
+- CLI entrypoint for setup initialization
+- example setup outputs for Codex and Claude

package/README.md

@@ -0,0 +1,46 @@
+# @longtable/setup
+
+Researcher onboarding and setup flows for LongTable.
+
+## Recommended Usage
+
+Researchers should use the unified CLI:
+
+```bash
+npm install -g @longtable/cli
+longtable init --flow interview
+```
+
+This package exists so the setup flow can also be consumed programmatically or tested in isolation during development.
+
+By default this writes:
+
+- setup output to `~/.longtable/setup.json`
+- Codex runtime config to `~/.longtable/runtime/codex/longtable.toml`
+- Claude runtime config to `~/.longtable/runtime/claude/longtable.json`
+
+The generated runtime config does not overwrite platform-native config files directly. It creates LongTable-managed runtime artifacts that can later be wired into provider-specific runtimes during migration.
+
+## Package Role
+
+The setup contract combines technical setup with researcher-profile calibration rather than treating installation as a purely technical step.
+
+Global setup should answer:
+
+- who the researcher is
+- how much challenge or slowdown they want
+- what makes writing still feel like theirs
+- how visible disagreement should be by default
+
+Project and session intake belongs to `longtable start`, not library-level setup helpers.
+
+## Included Outputs
+
+- quick setup question flow
+- provider selection resolution
+- persisted setup output generator
+- saved setup output helpers
+- runtime config installer helpers
+- numbered checkpoint helpers
+
+See `examples/` for sample Codex and Claude setup outputs.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,275 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { buildProviderChoices, buildQuickSetupFlow, createPersistedSetupOutput } from "./onboarding.js";
+import { installRuntimeConfigFromStoredSetup, loadSetupOutput, renderInstallSummary, renderSetupSummary, resolveDefaultSetupPath, saveSetupAndRuntimeConfig, saveSetupOutput, serializeSetupOutput } from "./persistence.js";
+function printUsage() {
+    console.log(`Usage:
+  longtable-setup 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]
+  longtable-setup install [--path <file>] [--runtime-path <file>] [--json]
+  longtable-setup show [--path <file>] [--json]
+
+Example:
+  longtable-setup init --flow interview --provider codex --field education --career-stage doctoral --experience intermediate --checkpoint balanced --entry-mode explore --panel-preference show_on_conflict --json
+
+If required flags are omitted, interactive setup starts automatically.
+Use --write to save setup.json and --install to also generate provider runtime config.`);
+}
+function parseArgs(argv) {
+    const parsed = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith("--")) {
+            parsed._command = token;
+            continue;
+        }
+        const key = token.slice(2);
+        const next = argv[index + 1];
+        if (!next || next.startsWith("--")) {
+            parsed[key] = true;
+            continue;
+        }
+        parsed[key] = next;
+        index += 1;
+    }
+    return parsed;
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Missing required argument: --${key}`);
+    }
+    return value;
+}
+function toSetupAnswers(args) {
+    return {
+        field: requireString(args, "field"),
+        careerStage: requireString(args, "career-stage"),
+        experienceLevel: requireString(args, "experience"),
+        preferredCheckpointIntensity: requireString(args, "checkpoint"),
+        humanAuthorshipSignal: typeof args["authorship-signal"] === "string" && args["authorship-signal"].trim().length > 0
+            ? args["authorship-signal"].trim()
+            : undefined,
+        preferredEntryMode: typeof args["entry-mode"] === "string" && args["entry-mode"].trim().length > 0
+            ? args["entry-mode"].trim()
+            : undefined,
+        weakestDomain: typeof args["weakest-domain"] === "string" && args["weakest-domain"].trim().length > 0
+            ? args["weakest-domain"].trim()
+            : undefined,
+        panelPreference: typeof args["panel-preference"] === "string" && args["panel-preference"].trim().length > 0
+            ? args["panel-preference"].trim()
+            : undefined
+    };
+}
+function hasCompleteFlagInput(args) {
+    const requiredKeys = [
+        "provider",
+        "field",
+        "career-stage",
+        "experience",
+        "checkpoint"
+    ];
+    return requiredKeys.every((key) => typeof args[key] === "string" && String(args[key]).trim().length > 0);
+}
+function resolveSetupFlow(args) {
+    return args.flow === "interview" ? "interview" : "quickstart";
+}
+function renderChoices(choices) {
+    return choices
+        .map((choice, index) => `${index + 1}. ${choice.label} — ${choice.description}`)
+        .join("\n");
+}
+async function readPipedLines() {
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(String(chunk));
+    }
+    return chunks
+        .join("")
+        .split(/\r?\n/);
+}
+async function promptChoice(rl, prompt, choices) {
+    while (true) {
+        const answer = await rl.question(`${prompt}\n${renderChoices(choices)}\nSelect one number: `);
+        const numeric = Number(answer.trim());
+        if (!Number.isInteger(numeric) || numeric < 1 || numeric > choices.length) {
+            console.log("Invalid selection. Enter one of the listed numbers.");
+            continue;
+        }
+        const choice = choices[numeric - 1];
+        if (choice.fallbackToText) {
+            const freeText = await rl.question("Type your custom value: ");
+            if (freeText.trim().length === 0) {
+                console.log("Custom value cannot be empty.");
+                continue;
+            }
+            return freeText.trim();
+        }
+        return choice.id;
+    }
+}
+function promptChoiceFromLines(prompt, choices, lines, state) {
+    while (true) {
+        console.log(`${prompt}\n${renderChoices(choices)}\nSelect one number: `);
+        const answer = lines[state.index] ?? "";
+        state.index += 1;
+        const numeric = Number(answer.trim());
+        if (!Number.isInteger(numeric) || numeric < 1 || numeric > choices.length) {
+            console.log("Invalid selection. Enter one of the listed numbers.");
+            continue;
+        }
+        const choice = choices[numeric - 1];
+        if (choice.fallbackToText) {
+            console.log("Type your custom value: ");
+            const freeText = (lines[state.index] ?? "").trim();
+            state.index += 1;
+            if (freeText.length === 0) {
+                console.log("Custom value cannot be empty.");
+                continue;
+            }
+            return freeText;
+        }
+        return choice.id;
+    }
+}
+function printInitResult(outputValue, options, installResult) {
+    if (options.writeOutput && installResult) {
+        console.error(`Saved setup output to ${installResult.setupTarget.path}`);
+        console.error(`Installed runtime config to ${installResult.runtimeTarget.path}`);
+    }
+    else if (options.writeOutput) {
+        const target = resolveDefaultSetupPath(options.customPath);
+        console.error(`Saved setup output to ${target.path}`);
+    }
+    if (options.jsonOutput) {
+        console.log(serializeSetupOutput(outputValue));
+        return;
+    }
+    const summary = [renderSetupSummary(outputValue)];
+    if (installResult) {
+        summary.push("");
+        summary.push(renderInstallSummary(installResult));
+    }
+    console.log(summary.join("\n"));
+}
+async function persistInitResult(outputValue, options) {
+    let installResult;
+    if (options.installRuntime) {
+        installResult = await saveSetupAndRuntimeConfig(outputValue, {
+            setupPath: options.customPath,
+            runtimePath: options.runtimePath
+        });
+    }
+    else if (options.writeOutput) {
+        await saveSetupOutput(outputValue, options.customPath);
+    }
+    printInitResult(outputValue, options, installResult);
+}
+async function runNonInteractiveInputSetup(options, flow) {
+    const lines = await readPipedLines();
+    const state = { index: 0 };
+    const provider = promptChoiceFromLines("Which provider do you want to configure?", buildProviderChoices(), lines, state);
+    const answers = {};
+    for (const question of buildQuickSetupFlow(flow)) {
+        if (!question.choices) {
+            throw new Error(`Question ${question.id} requires choices in non-interactive mode.`);
+        }
+        const value = promptChoiceFromLines(question.prompt, question.choices, lines, state);
+        answers[question.id] = value;
+    }
+    const outputValue = createPersistedSetupOutput(answers, provider, flow);
+    await persistInitResult(outputValue, options);
+}
+async function runInteractiveSetup(options, flow) {
+    if (!input.isTTY) {
+        await runNonInteractiveInputSetup(options, flow);
+        return;
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const provider = await promptChoice(rl, "Which provider do you want to configure?", buildProviderChoices());
+        const answers = {};
+        for (const question of buildQuickSetupFlow(flow)) {
+            if (question.kind !== "single_choice" || !question.choices) {
+                const response = await rl.question(`${question.prompt}\n> `);
+                if (response.trim().length === 0) {
+                    console.log("This field cannot be empty.");
+                    return await runInteractiveSetup(options, flow);
+                }
+                answers[question.id] = response.trim();
+                continue;
+            }
+            const value = await promptChoice(rl, question.prompt, question.choices);
+            answers[question.id] = value;
+        }
+        const outputValue = createPersistedSetupOutput(answers, provider, flow);
+        await persistInitResult(outputValue, options);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function printStoredSetup(customPath, jsonOutput) {
+    const setup = await loadSetupOutput(customPath);
+    console.log(jsonOutput ? serializeSetupOutput(setup) : renderSetupSummary(setup));
+}
+async function installStoredSetup(customPath, runtimePath, jsonOutput) {
+    const result = await installRuntimeConfigFromStoredSetup({
+        setupPath: customPath,
+        runtimePath
+    });
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(renderInstallSummary(result));
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args._command || args._command === "help" || args._command === "--help") {
+        printUsage();
+        process.exit(0);
+    }
+    if (args._command === "show") {
+        await printStoredSetup(typeof args.path === "string" ? args.path : undefined, args.json === true);
+        return;
+    }
+    if (args._command === "install") {
+        await installStoredSetup(typeof args.path === "string" ? args.path : undefined, typeof args["runtime-path"] === "string" ? args["runtime-path"] : undefined, args.json === true);
+        return;
+    }
+    if (args._command !== "init") {
+        printUsage();
+        throw new Error(`Unknown command: ${String(args._command)}`);
+    }
+    if (hasCompleteFlagInput(args)) {
+        const provider = requireString(args, "provider");
+        const outputValue = createPersistedSetupOutput(toSetupAnswers(args), provider, resolveSetupFlow(args));
+        const shouldWrite = args.write === true;
+        const shouldInstall = args.install === true;
+        const customPath = typeof args.path === "string" ? args.path : undefined;
+        const runtimePath = typeof args["runtime-path"] === "string"
+            ? args["runtime-path"]
+            : undefined;
+        await persistInitResult(outputValue, {
+            jsonOutput: args.json === true,
+            writeOutput: shouldWrite || shouldInstall,
+            customPath,
+            installRuntime: shouldInstall,
+            runtimePath
+        });
+        return;
+    }
+    await runInteractiveSetup({
+        jsonOutput: args.json === true,
+        writeOutput: args.write === true || args.install === true,
+        customPath: typeof args.path === "string" ? args.path : undefined,
+        installRuntime: args.install === true,
+        runtimePath: typeof args["runtime-path"] === "string"
+            ? args["runtime-path"]
+            : undefined
+    }, resolveSetupFlow(args));
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./numbered-checkpoint.js";
+export * from "./onboarding.js";
+export * from "./persistence.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./numbered-checkpoint.js";
+export * from "./onboarding.js";
+export * from "./persistence.js";
+export * from "./types.js";

package/dist/numbered-checkpoint.d.ts

@@ -0,0 +1,3 @@
+import type { NumberedCheckpointSpec, ParsedCheckpointSelection } from "./types.js";
+export declare function buildNumberedCheckpointPrompt(spec: NumberedCheckpointSpec): string;
+export declare function parseNumberedCheckpointResponse(spec: NumberedCheckpointSpec, input: string): ParsedCheckpointSelection | null;

package/dist/numbered-checkpoint.js

@@ -0,0 +1,42 @@
+export function buildNumberedCheckpointPrompt(spec) {
+    const lines = [`CHECKPOINT: ${spec.title}`, ""];
+    if (spec.instructions) {
+        lines.push(spec.instructions, "");
+    }
+    spec.options.forEach((option, index) => {
+        lines.push(`${index + 1}. ${option.label}`);
+    });
+    lines.push("");
+    if (spec.allowRationale) {
+        lines.push("Reply with one number only, or one number followed by a short rationale on the next line.");
+    }
+    else {
+        lines.push(`Reply with one number only: ${spec.options.map((_, index) => index + 1).join(", ")}.`);
+    }
+    return lines.join("\n");
+}
+export function parseNumberedCheckpointResponse(spec, input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const [firstLine, ...restLines] = trimmed.split(/\r?\n/);
+    if (!/^\d+$/.test(firstLine.trim())) {
+        return null;
+    }
+    const index = Number(firstLine.trim()) - 1;
+    const option = spec.options[index];
+    if (!option) {
+        return null;
+    }
+    const rationale = restLines.join("\n").trim();
+    if (!spec.allowRationale && rationale.length > 0) {
+        return null;
+    }
+    return {
+        index,
+        value: option.value,
+        label: option.label,
+        rationale: rationale.length > 0 ? rationale : undefined
+    };
+}

package/dist/onboarding.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderKind, SetupChoice, SetupFlow, ProviderSelection, ResearcherProfileSeed, SetupAnswers, SetupPersistedOutput, SetupQuestion } from "./types.js";
+export declare function buildQuickSetupFlow(flow?: SetupFlow): SetupQuestion[];
+export declare function buildProviderChoices(): SetupChoice[];
+export declare function buildFieldChoices(): SetupChoice[];
+export declare function buildCareerStageChoices(): SetupChoice[];
+export declare function buildProjectTypeChoices(): SetupChoice[];
+export declare function isFallbackChoice(choice: SetupChoice | undefined): boolean;
+export declare function normalizeProviderChoice(choice: string): ProviderKind;
+export declare function createResearcherProfileSeed(answers: SetupAnswers): ResearcherProfileSeed;
+export declare function resolveProviderSelection(provider: ProviderSelection["provider"]): ProviderSelection;
+export declare function createPersistedSetupOutput(answers: SetupAnswers, provider: ProviderSelection["provider"], flow?: SetupFlow): SetupPersistedOutput;

package/dist/onboarding.js

@@ -0,0 +1,212 @@
+import { createEmptyResearchState } from "@longtable/memory";
+export function buildQuickSetupFlow(flow = "quickstart") {
+    const baseQuestions = [
+        {
+            id: "field",
+            prompt: "Before we begin, which research field best matches your work right now?",
+            required: true,
+            kind: "single_choice",
+            choices: buildFieldChoices()
+        },
+        {
+            id: "careerStage",
+            prompt: "What kind of researcher role best fits you today?",
+            required: true,
+            kind: "single_choice",
+            choices: buildCareerStageChoices()
+        },
+        {
+            id: "experienceLevel",
+            prompt: "How comfortable are you making independent research design decisions right now?",
+            required: true,
+            kind: "single_choice",
+            choices: [
+                { id: "novice", label: "Novice", description: "Needs stronger checkpoint guidance." },
+                { id: "intermediate", label: "Intermediate", description: "Wants balanced guidance." },
+                { id: "advanced", label: "Advanced", description: "Prefers lighter intervention." }
+            ]
+        },
+        {
+            id: "preferredCheckpointIntensity",
+            prompt: "How strongly should LongTable challenge or slow you down by default?",
+            required: true,
+            kind: "single_choice",
+            choices: [
+                { id: "low", label: "Low", description: "Mostly lightweight logging and advisory prompts." },
+                { id: "balanced", label: "Balanced", description: "Recommended by default." },
+                { id: "high", label: "High", description: "Frequent structured commitment prompts." }
+            ]
+        },
+        {
+            id: "humanAuthorshipSignal",
+            prompt: "When a piece of writing still feels like yours, what usually makes that true?",
+            required: false,
+            kind: "single_choice",
+            choices: [
+                { id: "personal experience in the narrative", label: "Personal experience", description: "Humanity appears through lived experience and situated voice." },
+                { id: "visible judgment and reasoning path", label: "Judgment trail", description: "Humanity appears through explicit choices and reasoning history." },
+                { id: "contextual nuance that avoids generic fluency", label: "Contextual nuance", description: "Humanity appears through specificity and non-generic framing." },
+                { id: "a distinctive voice that still sounds like the researcher", label: "Distinctive voice", description: "Humanity appears through authorial tone and cadence." },
+                { id: "other", label: "None of the above", description: "Enter a custom authorship signal.", fallbackToText: true }
+            ]
+        }
+    ];
+    if (flow === "quickstart") {
+        return baseQuestions;
+    }
+    return [
+        ...baseQuestions,
+        {
+            id: "preferredEntryMode",
+            prompt: "When you first open LongTable, where do you want it to begin?",
+            required: false,
+            kind: "single_choice",
+            choices: [
+                { id: "explore", label: "Explore", description: "Open the problem, surface tensions, and ask better questions." },
+                { id: "review", label: "Review", description: "Critically inspect a claim, plan, or draft." },
+                { id: "critique", label: "Critique", description: "Stress-test weak assumptions and generate counterarguments." },
+                { id: "draft", label: "Draft", description: "Write while preserving narrative trace and authorship." },
+                { id: "commit", label: "Commit", description: "Slow down and make an explicit research decision." }
+            ]
+        },
+        {
+            id: "weakestDomain",
+            prompt: "Where do you most want LongTable to push back on you first?",
+            required: false,
+            kind: "single_choice",
+            choices: [
+                { id: "theory", label: "Theory", description: "Sharpen framing, constructs, and theoretical defensibility." },
+                { id: "methodology", label: "Methodology", description: "Question design fit, sampling, and study structure." },
+                { id: "measurement", label: "Measurement", description: "Challenge scales, validity, and operationalization." },
+                { id: "analysis", label: "Analysis", description: "Probe analytic logic, interpretation, and evidence claims." },
+                { id: "writing", label: "Writing", description: "Preserve voice while improving clarity and argument flow." }
+            ]
+        },
+        {
+            id: "panelPreference",
+            prompt: "How visible should disagreement between roles be by default?",
+            required: false,
+            kind: "single_choice",
+            choices: [
+                { id: "synthesis_only", label: "Synthesis only", description: "Show one LongTable answer unless I ask for more." },
+                { id: "show_on_conflict", label: "Show on conflict", description: "Surface panel disagreement when roles materially diverge." },
+                { id: "always_visible", label: "Always visible", description: "Keep panel opinions visible by default." }
+            ]
+        }
+    ];
+}
+export function buildProviderChoices() {
+    return [
+        {
+            id: "codex",
+            label: "Codex",
+            description: "Use numbered checkpoints and Codex runtime surfaces."
+        },
+        {
+            id: "claude",
+            label: "Claude",
+            description: "Use structured-question capable Claude runtime surfaces."
+        }
+    ];
+}
+export function buildFieldChoices() {
+    return [
+        { id: "education", label: "Education", description: "Learning, instruction, or educational technology." },
+        { id: "psychology", label: "Psychology", description: "Behavior, cognition, or social psychology." },
+        { id: "hrd", label: "HRD", description: "Human resource development and workplace learning." },
+        { id: "management", label: "Management", description: "Organizations, strategy, or business research." },
+        { id: "other", label: "None of the above", description: "Enter a custom field.", fallbackToText: true }
+    ];
+}
+export function buildCareerStageChoices() {
+    return [
+        { id: "doctoral", label: "Doctoral student", description: "Currently in doctoral training." },
+        { id: "postdoctoral", label: "Postdoctoral researcher", description: "Research-focused early career stage." },
+        { id: "faculty", label: "Faculty", description: "Professor or lecturer role." },
+        { id: "industry", label: "Industry researcher", description: "Research outside a university role." },
+        { id: "other", label: "None of the above", description: "Enter a custom career stage.", fallbackToText: true }
+    ];
+}
+export function buildProjectTypeChoices() {
+    return [
+        { id: "journal article", label: "Journal article", description: "A paper targeted at an academic journal." },
+        { id: "conference paper", label: "Conference paper", description: "A paper targeted at a conference venue." },
+        { id: "proposal", label: "Proposal", description: "A grant, dissertation, or research proposal." },
+        { id: "mixed-methods study", label: "Mixed-methods study", description: "A study design spanning multiple methods." },
+        { id: "other", label: "None of the above", description: "Enter a custom project type.", fallbackToText: true }
+    ];
+}
+export function isFallbackChoice(choice) {
+    return choice?.fallbackToText === true;
+}
+export function normalizeProviderChoice(choice) {
+    return choice === "claude" ? "claude" : "codex";
+}
+export function createResearcherProfileSeed(answers) {
+    return {
+        currentProjectType: answers.currentProjectType ?? "unspecified research task",
+        ...answers,
+        aiAutonomyPreference: answers.experienceLevel === "advanced"
+            ? "balanced"
+            : answers.experienceLevel === "intermediate"
+                ? "balanced"
+                : "low"
+    };
+}
+export function resolveProviderSelection(provider) {
+    if (provider === "claude") {
+        return {
+            provider,
+            checkpointProtocol: "native_structured",
+            supportsStructuredQuestions: true
+        };
+    }
+    return {
+        provider,
+        checkpointProtocol: "numbered",
+        supportsStructuredQuestions: false
+    };
+}
+export function createPersistedSetupOutput(answers, provider, flow = "quickstart") {
+    const profileSeed = createResearcherProfileSeed(answers);
+    const initialState = createEmptyResearchState();
+    initialState.explicitState = {
+        field: profileSeed.field,
+        careerStage: profileSeed.careerStage,
+        experienceLevel: profileSeed.experienceLevel,
+        ...(profileSeed.currentProjectType
+            ? { currentProjectType: profileSeed.currentProjectType }
+            : {}),
+        preferredCheckpointIntensity: profileSeed.preferredCheckpointIntensity,
+        ...(profileSeed.humanAuthorshipSignal
+            ? { humanAuthorshipSignal: profileSeed.humanAuthorshipSignal }
+            : {}),
+        ...(profileSeed.preferredEntryMode
+            ? { preferredEntryMode: profileSeed.preferredEntryMode }
+            : {}),
+        ...(profileSeed.weakestDomain
+            ? { weakestDomain: profileSeed.weakestDomain }
+            : {}),
+        ...(profileSeed.panelPreference
+            ? { panelPreference: profileSeed.panelPreference }
+            : {})
+    };
+    if (profileSeed.humanAuthorshipSignal) {
+        initialState.narrativeTraces.push({
+            id: "setup-human-authorship-signal",
+            timestamp: new Date().toISOString(),
+            source: "setup",
+            traceType: "voice",
+            summary: `Researcher identifies human authorship through ${profileSeed.humanAuthorshipSignal}.`,
+            visibility: "explicit",
+            importance: "high"
+        });
+    }
+    return {
+        setupFlow: flow,
+        profileSeed,
+        providerSelection: resolveProviderSelection(provider),
+        defaultInteractionMode: profileSeed.preferredEntryMode ?? "explore",
+        initialState
+    };
+}

package/dist/persistence.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderKind } from "@longtable/core";
+import type { RuntimeConfigTarget, SetupAnswers, SetupInstallResult, SetupPersistedOutput, SetupStorageTarget } from "./types.js";
+export declare function serializeSetupOutput(output: SetupPersistedOutput): string;
+export declare function parseSetupOutput(input: string): SetupPersistedOutput;
+export declare function createSetupOutputExample(provider: ProviderKind, overrides?: Partial<SetupAnswers>): SetupPersistedOutput;
+export declare function renderSetupSummary(output: SetupPersistedOutput): string;
+export declare function resolveDefaultSetupPath(customPath?: string): SetupStorageTarget;
+export declare function resolveDefaultRuntimeConfigPath(provider: ProviderKind, customPath?: string): RuntimeConfigTarget;
+export declare function saveSetupOutput(output: SetupPersistedOutput, customPath?: string): Promise<SetupStorageTarget>;
+export declare function loadSetupOutput(customPath?: string): Promise<SetupPersistedOutput>;
+export declare function renderRuntimeConfig(output: SetupPersistedOutput, setupPath: string): string;
+export declare function writeRuntimeConfig(output: SetupPersistedOutput, setupPath: string, customPath?: string): Promise<RuntimeConfigTarget>;
+export declare function saveSetupAndRuntimeConfig(output: SetupPersistedOutput, options?: {
+    setupPath?: string;
+    runtimePath?: string;
+}): Promise<SetupInstallResult>;
+export declare function installRuntimeConfigFromStoredSetup(options?: {
+    setupPath?: string;
+    runtimePath?: string;
+}): Promise<SetupInstallResult>;
+export declare function renderInstallSummary(result: SetupInstallResult): string;

package/dist/persistence.js

@@ -0,0 +1,178 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createPersistedSetupOutput } from "./onboarding.js";
+export function serializeSetupOutput(output) {
+    return JSON.stringify(output, null, 2);
+}
+export function parseSetupOutput(input) {
+    return JSON.parse(input);
+}
+export function createSetupOutputExample(provider, overrides = {}) {
+    return createPersistedSetupOutput({
+        field: overrides.field ?? "education",
+        careerStage: overrides.careerStage ?? "doctoral",
+        experienceLevel: overrides.experienceLevel ?? "intermediate",
+        preferredCheckpointIntensity: overrides.preferredCheckpointIntensity ?? "balanced"
+    }, provider);
+}
+export function renderSetupSummary(output) {
+    const lines = [
+        "LongTable setup summary",
+        `setup flow: ${output.setupFlow}`,
+        `provider: ${output.providerSelection.provider}`,
+        `checkpoint protocol: ${output.providerSelection.checkpointProtocol}`,
+        `default mode: ${output.defaultInteractionMode}`,
+        `field: ${output.profileSeed.field}`,
+        `career stage: ${output.profileSeed.careerStage}`,
+        `experience: ${output.profileSeed.experienceLevel}`,
+        `checkpoint intensity: ${output.profileSeed.preferredCheckpointIntensity}`
+    ];
+    if (output.profileSeed.weakestDomain) {
+        lines.push(`challenge first: ${output.profileSeed.weakestDomain}`);
+    }
+    if (output.profileSeed.panelPreference) {
+        lines.push(`panel preference: ${output.profileSeed.panelPreference}`);
+    }
+    return lines.join("\n");
+}
+export function resolveDefaultSetupPath(customPath) {
+    const targetPath = customPath
+        ? resolve(customPath)
+        : join(homedir(), ".longtable", "setup.json");
+    return {
+        path: targetPath,
+        directory: dirname(targetPath)
+    };
+}
+export function resolveDefaultRuntimeConfigPath(provider, customPath) {
+    const format = provider === "codex" ? "toml" : "json";
+    const fileName = provider === "codex" ? "longtable.toml" : "longtable.json";
+    const targetPath = customPath
+        ? resolve(customPath)
+        : join(homedir(), ".longtable", "runtime", provider, fileName);
+    return {
+        provider,
+        path: targetPath,
+        directory: dirname(targetPath),
+        format
+    };
+}
+export async function saveSetupOutput(output, customPath) {
+    const target = resolveDefaultSetupPath(customPath);
+    await mkdir(target.directory, { recursive: true });
+    await writeFile(target.path, serializeSetupOutput(output), "utf8");
+    return target;
+}
+export async function loadSetupOutput(customPath) {
+    const target = resolveDefaultSetupPath(customPath);
+    const content = await readFile(target.path, "utf8");
+    return parseSetupOutput(content);
+}
+function resolveRuntimeGuidance(output) {
+    if (output.providerSelection.provider === "codex") {
+        return {
+            askAtLeastTwoQuestionsInExplore: true,
+            preserveNarrativeTraceInDraft: true,
+            requireWhyMayBeWrongInReview: true,
+            questionBiasCompensation: "strong"
+        };
+    }
+    return {
+        askAtLeastTwoQuestionsInExplore: true,
+        preserveNarrativeTraceInDraft: true,
+        requireWhyMayBeWrongInReview: true,
+        structuredQuestionBias: "strong"
+    };
+}
+function renderCodexRuntimeConfig(output, setupPath) {
+    const runtimeGuidance = resolveRuntimeGuidance(output);
+    return [
+        "[longtable]",
+        `provider = "${output.providerSelection.provider}"`,
+        `setup_path = "${setupPath}"`,
+        `checkpoint_protocol = "${output.providerSelection.checkpointProtocol}"`,
+        `default_interaction_mode = "${output.defaultInteractionMode}"`,
+        `setup_flow = "${output.setupFlow}"`,
+        "",
+        "[longtable.profile]",
+        `field = "${output.profileSeed.field}"`,
+        `career_stage = "${output.profileSeed.careerStage}"`,
+        `experience_level = "${output.profileSeed.experienceLevel}"`,
+        ...(output.profileSeed.currentProjectType && output.profileSeed.currentProjectType !== "unspecified research task"
+            ? [`current_project_type = "${output.profileSeed.currentProjectType}"`]
+            : []),
+        ...(output.profileSeed.weakestDomain
+            ? [`weakest_domain = "${output.profileSeed.weakestDomain}"`]
+            : []),
+        ...(output.profileSeed.panelPreference
+            ? [`panel_preference = "${output.profileSeed.panelPreference}"`]
+            : []),
+        "",
+        "[longtable.runtime_guidance]",
+        `ask_at_least_two_questions_in_explore = ${runtimeGuidance.askAtLeastTwoQuestionsInExplore}`,
+        `preserve_narrative_trace_in_draft = ${runtimeGuidance.preserveNarrativeTraceInDraft}`,
+        `require_why_may_be_wrong_in_review = ${runtimeGuidance.requireWhyMayBeWrongInReview}`,
+        `question_bias_compensation = "${runtimeGuidance.questionBiasCompensation}"`
+    ].join("\n");
+}
+function renderClaudeRuntimeConfig(output, setupPath) {
+    const runtimeGuidance = resolveRuntimeGuidance(output);
+    return JSON.stringify({
+        setupPath,
+        provider: output.providerSelection.provider,
+        checkpointProtocol: output.providerSelection.checkpointProtocol,
+        defaultInteractionMode: output.defaultInteractionMode,
+        setupFlow: output.setupFlow,
+        profileSummary: {
+            field: output.profileSeed.field,
+            careerStage: output.profileSeed.careerStage,
+            experienceLevel: output.profileSeed.experienceLevel,
+            currentProjectType: output.profileSeed.currentProjectType && output.profileSeed.currentProjectType !== "unspecified research task"
+                ? output.profileSeed.currentProjectType
+                : undefined,
+            weakestDomain: output.profileSeed.weakestDomain,
+            panelPreference: output.profileSeed.panelPreference
+        },
+        runtimeGuidance
+    }, null, 2);
+}
+export function renderRuntimeConfig(output, setupPath) {
+    return output.providerSelection.provider === "codex"
+        ? renderCodexRuntimeConfig(output, setupPath)
+        : renderClaudeRuntimeConfig(output, setupPath);
+}
+export async function writeRuntimeConfig(output, setupPath, customPath) {
+    const target = resolveDefaultRuntimeConfigPath(output.providerSelection.provider, customPath);
+    await mkdir(target.directory, { recursive: true });
+    await writeFile(target.path, renderRuntimeConfig(output, setupPath), "utf8");
+    return target;
+}
+export async function saveSetupAndRuntimeConfig(output, options = {}) {
+    const setupTarget = await saveSetupOutput(output, options.setupPath);
+    const runtimeTarget = await writeRuntimeConfig(output, setupTarget.path, options.runtimePath);
+    return {
+        provider: output.providerSelection.provider,
+        setupTarget,
+        runtimeTarget
+    };
+}
+export async function installRuntimeConfigFromStoredSetup(options = {}) {
+    const setupTarget = resolveDefaultSetupPath(options.setupPath);
+    const output = await loadSetupOutput(options.setupPath);
+    const runtimeTarget = await writeRuntimeConfig(output, setupTarget.path, options.runtimePath);
+    return {
+        provider: output.providerSelection.provider,
+        setupTarget,
+        runtimeTarget
+    };
+}
+export function renderInstallSummary(result) {
+    return [
+        "LongTable runtime install summary",
+        `provider: ${result.provider}`,
+        `setup path: ${result.setupTarget.path}`,
+        `runtime config path: ${result.runtimeTarget.path}`,
+        `runtime config format: ${result.runtimeTarget.format}`
+    ].join("\n");
+}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+import type { CheckpointIntensity, ExperienceLevel, InteractionMode, ProviderKind, ResearcherConfidenceByDomain, ResearchState } from "@longtable/core";
+export interface SetupChoice {
+    id: string;
+    label: string;
+    description: string;
+    fallbackToText?: boolean;
+}
+export interface SetupQuestion {
+    id: string;
+    prompt: string;
+    required: boolean;
+    kind: "single_choice" | "text";
+    choices?: SetupChoice[];
+}
+export type SetupFlow = "quickstart" | "interview";
+export interface SetupAnswers {
+    field: string;
+    careerStage: string;
+    experienceLevel: ExperienceLevel;
+    currentProjectType?: string;
+    preferredCheckpointIntensity: CheckpointIntensity;
+    humanAuthorshipSignal?: string;
+    preferredEntryMode?: Exclude<InteractionMode, "submit">;
+    weakestDomain?: Extract<keyof ResearcherConfidenceByDomain, string>;
+    panelPreference?: "synthesis_only" | "show_on_conflict" | "always_visible";
+}
+export interface ResearcherProfileSeed extends SetupAnswers {
+    aiAutonomyPreference: "low" | "balanced" | "high";
+}
+export interface ProviderSelection {
+    provider: ProviderKind;
+    checkpointProtocol: "native_structured" | "numbered";
+    supportsStructuredQuestions: boolean;
+}
+export interface SetupPersistedOutput {
+    setupFlow: SetupFlow;
+    profileSeed: ResearcherProfileSeed;
+    providerSelection: ProviderSelection;
+    defaultInteractionMode: Exclude<InteractionMode, "submit">;
+    initialState: ResearchState;
+}
+export interface SetupStorageTarget {
+    path: string;
+    directory: string;
+}
+export interface RuntimeConfigTarget {
+    provider: ProviderKind;
+    path: string;
+    directory: string;
+    format: "toml" | "json";
+}
+export interface SetupInstallResult {
+    provider: ProviderKind;
+    setupTarget: SetupStorageTarget;
+    runtimeTarget: RuntimeConfigTarget;
+}
+export interface NumberedCheckpointOption {
+    value: string;
+    label: string;
+}
+export interface NumberedCheckpointSpec {
+    title: string;
+    instructions?: string;
+    options: NumberedCheckpointOption[];
+    allowRationale?: boolean;
+}
+export interface ParsedCheckpointSelection {
+    index: number;
+    value: string;
+    label: string;
+    rationale?: string;
+}
+export type { CheckpointIntensity, ExperienceLevel, ProviderKind, ResearchState } from "@longtable/core";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/examples/claude-setup-output.json

@@ -0,0 +1,27 @@
+{
+  "profileSeed": {
+    "field": "psychology",
+    "careerStage": "faculty",
+    "experienceLevel": "advanced",
+    "preferredCheckpointIntensity": "low",
+    "aiAutonomyPreference": "balanced"
+  },
+  "providerSelection": {
+    "provider": "claude",
+    "checkpointProtocol": "native_structured",
+    "supportsStructuredQuestions": true
+  },
+  "defaultInteractionMode": "explore",
+  "initialState": {
+    "explicitState": {
+      "field": "psychology",
+      "careerStage": "faculty",
+      "experienceLevel": "advanced",
+      "preferredCheckpointIntensity": "low"
+    },
+    "inferredHypotheses": [],
+    "openTensions": [],
+    "decisionLog": [],
+    "artifactRecords": []
+  }
+}

package/examples/codex-setup-output.json

@@ -0,0 +1,27 @@
+{
+  "profileSeed": {
+    "field": "education",
+    "careerStage": "doctoral",
+    "experienceLevel": "intermediate",
+    "preferredCheckpointIntensity": "balanced",
+    "aiAutonomyPreference": "balanced"
+  },
+  "providerSelection": {
+    "provider": "codex",
+    "checkpointProtocol": "numbered",
+    "supportsStructuredQuestions": false
+  },
+  "defaultInteractionMode": "explore",
+  "initialState": {
+    "explicitState": {
+      "field": "education",
+      "careerStage": "doctoral",
+      "experienceLevel": "intermediate",
+      "preferredCheckpointIntensity": "balanced"
+    },
+    "inferredHypotheses": [],
+    "openTensions": [],
+    "decisionLog": [],
+    "artifactRecords": []
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@longtable/setup",
+  "version": "0.1.9",
+  "private": false,
+  "description": "Researcher onboarding and setup flows for LongTable",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@longtable/core": "0.1.9",
+    "@longtable/memory": "0.1.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "longtable",
+    "research",
+    "setup",
+    "onboarding",
+    "codex",
+    "claude"
+  ],
+  "author": "Hosung You",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HosungYou/LongTable.git"
+  },
+  "homepage": "https://github.com/HosungYou/LongTable#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}