@longtable/cli 0.1.8 → 0.1.10

package/README.md

@@ -1,17 +1,17 @@
 # @longtable/cli
 
-Long Table의 researcher-facing CLI입니다.
+Researcher-facing CLI for LongTable.
 
-이 패키지의 핵심은 명령을 많이 외우게 하는 것이 아니라, 아래 두 단계를 명확하게 만드는 것입니다.
+LongTable is an npm-first, provider-neutral research harness. It keeps the core
+product contract in project files and shared packages, while Codex skills,
+Claude skills, and future MCP surfaces remain generated adapter artifacts.
 
-1. `longtable init`
-2. `longtable start`
+The basic contract is:
 
-중요한 점:
-
-- 이 두 명령은 **터미널에서 실행하는 셸 명령**입니다.
-- Codex 채팅창에 `longtable start`를 입력하는 것이 아닙니다.
-- `longtable start`로 프로젝트 작업공간을 만든 뒤, 그 디렉토리에서 `codex`를 여는 것이 기본 경로입니다.
+1. seed the researcher profile once
+2. create a workspace for each project
+3. continue the research conversation inside that workspace
+4. preserve decisions, tensions, and evidence as durable project state
 
 ## Install
 
@@ -19,117 +19,162 @@ Long Table의 researcher-facing CLI입니다.
 npm install -g @longtable/cli
 ```
 
-## 1. Global setup
+## Primary Flow
 
 ```bash
 longtable init --flow interview
+longtable start
+cd "<project-path>"
+codex
 ```
 
-여기서는 연구자 프로필과 기본 선호를 묻습니다.
+Return later:
 
-- 연구 분야
-- 연구자 역할
-- challenge 강도
-- 저자성/서사 관련 기본값
-- Long Table이 보통 어디서부터 시작해야 하는지
+```bash
+cd "<project-path>"
+longtable resume
+codex
+```
 
-## 2. Project start
+## What `longtable start` Creates
 
-```bash
-longtable start
+```text
+<project>/
+  AGENTS.md
+  CURRENT.md
+  .longtable/
+    project.json
+    current-session.json
+    state.json
+    sessions/
 ```
 
-여기서는 실제 작업공간을 만듭니다.
+## Artifact Contract
+
+- `AGENTS.md`: runtime guidance for Codex
+- `CURRENT.md`: human-facing current view regenerated from state
+- `.longtable/project.json`: stable project identity
+- `.longtable/current-session.json`: current session cursor
+- `.longtable/state.json`: layered memory state
+- `.longtable/sessions/`: historical snapshots
 
-- 프로젝트 이름
-- 프로젝트 디렉토리 위치
-- 현재 세션 목표
-- 현재 blocker
-- 필요한 관점
-- disagreement 가시성
+## Why This Shape
 
-그리고 Long Table은:
+The CLI tries to keep the root simple for novice researchers while preserving enough structure for power users and downstream tooling.
 
-- 프로젝트 디렉토리 생성
-- `.longtable/` 메모리 파일 생성
-- 프로젝트용 `AGENTS.md` 생성
-- `START-HERE.md` 생성
-- `NEXT-STEPS.md` 생성
-- `SESSION-SNAPSHOT.md` 생성
+The memory model distinguishes:
 
-을 수행합니다.
+- explicit state
+- working state
+- inferred hypotheses
+- open tensions
+- narrative traces
 
-## Recommended flow
+This is how LongTable avoids turning tacit knowledge into fake certainty.
+
+## Commands
 
 ```bash
-longtable init --flow interview
+longtable init
 longtable start
-cd "<project-path>"
-codex
+longtable resume --cwd "<project-path>"
+longtable roles
+longtable ask --cwd "<project-path>" --prompt "..."
+longtable panel --prompt "..."
+longtable codex install-skills
+longtable claude install-skills
 ```
 
-이게 현재 가장 신뢰할 수 있는 Long Table 사용 경로입니다.
-
-돌아와서 다시 이어갈 때는:
+Useful structured routes for scripts and debugging:
 
 ```bash
-cd "<project-path>"
-longtable resume
-codex
+longtable panel --prompt "review this methods section" --json
+longtable review --role methods_critic,measurement_auditor --panel --prompt "review this methods section" --json
+longtable ask --prompt "lt panel: show the disagreement before I commit" --json
 ```
 
-## After the project starts
+## Inside Codex
 
-프로젝트 디렉토리 안에서는 보통 그냥 `codex`를 열고 자연어로 연구를 시작하면 됩니다.
+Natural language should be the default.
 
-Codex 안에서 더 명시적으로 부르고 싶다면, 아래처럼 짧은 문법도 사용할 수 있습니다.
+Explicit short forms are available when needed:
 
 ```text
-lt explore: 연구 질문을 어디서부터 좁혀야 할지 모르겠어.
-lt review: 이 주장 어디가 약한지 봐줘.
-lt panel: 이 방향에 대한 의견 충돌도 같이 보여줘.
-lt editor: BJET 편집자 관점에서 봐줘.
-lt methods: 방법론적으로 어디가 취약한지 말해줘.
+lt explore: Where should I narrow the question first?
+lt review: What is weak in this claim?
+lt panel: Show me the disagreement before I commit.
+lt methods: Where is the design vulnerable?
 ```
 
-CLI를 계속 쓰고 싶다면 아래 명령은 보조 경로입니다.
-
-## Advanced commands
+Provider-native surfaces are available when installed:
 
 ```bash
-longtable roles
-longtable resume --cwd "<project-path>"
-longtable ask --cwd "<project-path>" --prompt "연구 질문을 어디서부터 좁혀야 할지 모르겠어."
-longtable review --cwd "<project-path>" --prompt "방법론적으로 어디가 취약한지 말해줘." --role methods_critic
+longtable codex install-skills
+longtable claude install-skills
 ```
 
-## Roles
+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.
+
+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.
+
+## Panel Orchestration
+
+Panel orchestration is for moments where disagreement matters: methods risk,
+measurement validity, theory fit, literature positioning, and claims that need
+challenge before they become project memory.
+
+The CLI creates a provider-neutral `PanelPlan` and returns a planned
+`PanelResult`. When native subagents are unavailable, LongTable uses a stable
+sequential fallback prompt. That keeps the same research semantics available in
+Codex and Claude Code without making either provider's native question or agent
+tool the source of truth.
+
+Inside a LongTable project workspace, panel planning also appends an
+`InvocationRecord` to `.longtable/state.json`, creates a pending follow-up
+`QuestionRecord`, and refreshes `CURRENT.md`.
 
 ```bash
-longtable roles
+longtable decide --answer evidence --rationale "Need citation support before continuing."
 ```
 
-예:
+Default panel roles include:
 
-- `editor`
 - `reviewer`
 - `methods_critic`
-- `voice_keeper`
+- `measurement_auditor`
+- `theory_critic`
 
-## Codex prompt-file integration
+Use `--role` to constrain the panel when the research problem is already clear.
 
-```bash
-longtable codex install-prompts
-longtable codex status
-```
+## Evidence And Search Direction
+
+LongTable should not behave like a generic web scraper. Research search should
+start from scholarly routes when the user needs literature discovery, citation
+verification, publication metadata, or evidence-backed research decisions.
 
-이 경로는 현재 실험적입니다.  
-사용자에게 약속하는 주 경로는 아닙니다.
+Planned scholarly routes include arXiv, Crossref, OpenAlex, Semantic Scholar,
+PubMed/NCBI, ERIC, DOAJ, and Unpaywall. They have different setup requirements:
+some work without keys, some require a contact email, and some need API keys for
+reliable use.
 
-기본 경로는 여전히:
+Citation support should be checked explicitly. A reference can be useful as
+background while still failing to support the specific claim attached to it.
 
-- `longtable init`
-- `longtable start`
-- 프로젝트 디렉토리에서 `codex`
+See:
 
-입니다.
+- [Research Search](https://github.com/HosungYou/LongTable/blob/main/docs/RESEARCH-SEARCH.md)
+- [Evidence Policy](https://github.com/HosungYou/LongTable/blob/main/docs/EVIDENCE-POLICY.md)
+- [LongTable Command Surface](https://github.com/HosungYou/LongTable/blob/main/docs/LONGTABLE-COMMAND-SURFACE.md)
+
+## Validation
+
+```bash
+npm install
+npm run typecheck
+npm run build
+```