@handsupmin/gc-tree 0.1.1

package/docs/local-development.ja.md

@@ -0,0 +1,83 @@
+# ローカル実行方法
+
+[English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
+
+## Summary
+
+ローカル開発は標準的な Node.js 20+ ワークフローです。依存関係を入れ、CLI をビルドし、ローカルで実行し、提出前に既存テストで検証します。
+
+## パッケージ状況
+
+このリポジトリの npm パッケージ名は `@handsupmin/gc-tree` で、リポジトリ名は引き続き `gc-tree` のままです。
+リリース前には `npm publish --dry-run` を実行し、実際に publish した後はクリーンなディレクトリで `npx @handsupmin/gc-tree --help` または `npm install -g @handsupmin/gc-tree` を使って配布物を検証してください。
+
+## 前提条件
+
+- Node.js 20+
+- npm
+- provider 起動を手動で確認したい場合は、ローカルの `codex` または `claude` バイナリ
+
+## セットアップ
+
+```bash
+npm install
+npm run build
+```
+
+## ローカルで CLI を実行する
+
+### 方法 1: ビルド済みエントリを直接実行する
+
+```bash
+node dist/src/cli.js status
+```
+
+### 方法 2: CLI をシェルにリンクする
+
+```bash
+npm link
+gctree status
+```
+
+TypeScript ソースを変更した場合は、再度 CLI を試す前にビルドし直してください。
+
+## 検証
+
+変更を提出する前に次を実行してください。
+
+```bash
+npm run build
+npm test
+npm publish --dry-run
+```
+
+## リポジトリ範囲テスト
+
+現在のテストスイートでは次を検証しています。
+
+- provider モード（`claude-code`、`codex`、`both`）の保存
+- 優先言語の保存と launch prompt での強い言語固定
+- リポジトリに応じた gc-branch 選択
+- `resolve` 中の include/exclude インタラクション
+- branch repo map の更新
+- ガイド付きオンボーディング/更新フローの境界条件
+
+## 手動 provider E2E 検証
+
+自動テストでは provider launch を無効にしているため、Codex や Claude Code の実セッションは開かず、launch plan だけを確認します。
+実際の起動経路を手元で確認したい場合は、使い捨てディレクトリで次を実行してください。
+
+```bash
+gctree init --provider codex
+gctree init --provider claude-code
+```
+
+正常なら provider が実際に起動し、すぐに `$gc-onboard` または `/gc-onboard` が渡されます。
+
+## プロジェクト構成
+
+- `src/` — CLI、コンテキスト保存、provider 選択、リポジトリ範囲マッピング、ガイド付きオンボーディング/更新フロー、scaffolding ロジック
+- `tests/` — CLI と挙動のテスト
+- `skills/` — ツール非依存のワークフロースキル
+- `scaffolds/` — ホスト別 bootstrap テンプレート
+- `docs/` — concept、principles、usage、development ドキュメント

package/docs/local-development.ko.md

@@ -0,0 +1,83 @@
+# 로컬 실행방법
+
+[English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
+
+## Summary
+
+로컬 개발은 일반적인 Node.js 20+ 워크플로를 따릅니다. 의존성을 설치하고, CLI를 빌드한 뒤, 로컬에서 실행하고, 제출 전에 기존 테스트로 검증하면 됩니다.
+
+## 패키지 상태
+
+이 레포의 npm 패키지 이름은 `@handsupmin/gc-tree`이고, 레포 이름은 계속 `gc-tree`로 유지됩니다.
+릴리스 시도 전에는 `npm publish --dry-run`을 실행하고, 실제 publish 후에는 깨끗한 디렉터리에서 `npx @handsupmin/gc-tree --help` 또는 `npm install -g @handsupmin/gc-tree`로 배포본을 검증하세요.
+
+## 준비사항
+
+- Node.js 20+
+- npm
+- provider 런치를 수동으로 점검하려면 로컬 `codex` 또는 `claude` 바이너리
+
+## 설정
+
+```bash
+npm install
+npm run build
+```
+
+## 로컬에서 CLI 실행
+
+### 방법 1: 빌드된 엔트리를 직접 실행
+
+```bash
+node dist/src/cli.js status
+```
+
+### 방법 2: 셸에 CLI를 링크
+
+```bash
+npm link
+gctree status
+```
+
+TypeScript 소스를 수정했다면 다시 테스트하기 전에 재빌드하세요.
+
+## 검증
+
+변경을 제출하기 전에 다음을 실행하세요.
+
+```bash
+npm run build
+npm test
+npm publish --dry-run
+```
+
+## 레포 범위 관련 테스트
+
+현재 테스트 스위트는 다음을 검증합니다.
+
+- provider 모드(`claude-code`, `codex`, `both`) 저장
+- 선호 언어 저장과 launch prompt에서의 강한 언어 고정
+- 레포에 따른 gc-branch 선택
+- `resolve` 중 include/exclude 인터랙션
+- branch repo map 갱신
+- 가이드형 온보딩/업데이트 경계 조건
+
+## 수동 provider E2E 점검
+
+자동 테스트는 Codex/Claude Code 세션을 실제로 열지 않도록 provider launch를 비활성화한 상태에서 launch plan만 검증합니다.
+실제 런치 경로를 직접 확인하고 싶다면 임시 디렉터리에서 다음처럼 실행하면 됩니다.
+
+```bash
+gctree init --provider codex
+gctree init --provider claude-code
+```
+
+정상이라면 provider가 실제로 열리고, 바로 `$gc-onboard` 또는 `/gc-onboard` 명령이 주입되어야 합니다.
+
+## 프로젝트 구조
+
+- `src/` — CLI, 컨텍스트 저장소, provider 선택, 레포 범위 매핑, 가이드형 온보딩/업데이트 흐름, 스캐폴딩 로직
+- `tests/` — CLI 및 동작 테스트
+- `skills/` — 도구 독립형 워크플로 스킬
+- `scaffolds/` — 호스트별 bootstrap 템플릿
+- `docs/` — concept, principles, usage, development 문서

package/docs/local-development.md

@@ -0,0 +1,83 @@
+# Local Development
+
+[English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
+
+## Summary
+
+Local development follows a standard Node.js 20+ workflow: install dependencies, build the CLI, run it locally, and verify with the existing test suite before you send changes.
+
+## Package status
+
+`@handsupmin/gc-tree` is the published npm package name for this repository, while the repository name stays `gc-tree`.
+Run `npm publish --dry-run` before release attempts, and after a real publish verify the released package from a clean directory with `npx @handsupmin/gc-tree --help` or `npm install -g @handsupmin/gc-tree`.
+
+## Prerequisites
+
+- Node.js 20+
+- npm
+- local `codex` and/or `claude` binaries if you want to manually dogfood provider launches
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Run the CLI locally
+
+### Option 1: run the built entry directly
+
+```bash
+node dist/src/cli.js status
+```
+
+### Option 2: link the CLI into your shell
+
+```bash
+npm link
+gctree status
+```
+
+If you change TypeScript sources, rebuild before testing the CLI again.
+
+## Verification
+
+Run these before opening a pull request:
+
+```bash
+npm run build
+npm test
+npm publish --dry-run
+```
+
+## Repo-scope tests
+
+The test suite now covers:
+
+- provider mode persistence (`claude-code`, `codex`, `both`)
+- preferred language persistence and strong language enforcement in launch prompts
+- repo-aware gc-branch selection
+- interactive include/exclude decisions during `resolve`
+- branch repo map updates
+- guided onboarding/update flow boundaries
+
+## Manual provider E2E checks
+
+Automated tests disable provider launch so they can verify launch plans without opening Codex or Claude Code sessions.
+If you want to dogfood the real launch path, run one of these in a throwaway directory:
+
+```bash
+gctree init --provider codex
+gctree init --provider claude-code
+```
+
+You should see the provider open and immediately receive `$gc-onboard` or `/gc-onboard`.
+
+## Project layout
+
+- `src/` — CLI, context storage, provider selection, repo-scope mapping, guided onboarding/update flows, and scaffolding logic
+- `tests/` — CLI and behavior tests
+- `skills/` — tool-agnostic workflow skills
+- `scaffolds/` — host-specific bootstrap templates
+- `docs/` — concept, principles, usage, and development documentation

package/docs/local-development.zh.md

@@ -0,0 +1,83 @@
+# 本地运行方法
+
+[English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
+
+## Summary
+
+本地开发采用标准的 Node.js 20+ 工作流：安装依赖、构建 CLI、本地运行，并在提交前用现有测试套件进行验证。
+
+## 包状态
+
+这个仓库对应的 npm 包名是 `@handsupmin/gc-tree`，而仓库名仍然保持为 `gc-tree`。
+在任何发布尝试前先运行 `npm publish --dry-run`；真正发布之后，再在干净目录里用 `npx @handsupmin/gc-tree --help` 或 `npm install -g @handsupmin/gc-tree` 验证发布结果。
+
+## 前置条件
+
+- Node.js 20+
+- npm
+- 如果想手动验证 provider 启动流程，需要本地可用的 `codex` 或 `claude` 二进制
+
+## 设置
+
+```bash
+npm install
+npm run build
+```
+
+## 在本地运行 CLI
+
+### 方法 1：直接运行构建后的入口
+
+```bash
+node dist/src/cli.js status
+```
+
+### 方法 2：把 CLI 链接到你的 shell
+
+```bash
+npm link
+gctree status
+```
+
+如果你修改了 TypeScript 源码，请在再次测试 CLI 之前重新构建。
+
+## 验证
+
+提交改动前请运行：
+
+```bash
+npm run build
+npm test
+npm publish --dry-run
+```
+
+## 仓库范围相关测试
+
+目前测试套件会验证：
+
+- provider 模式（`claude-code`、`codex`、`both`）持久化
+- 首选语言持久化以及 launch prompt 中更强的语言约束
+- 根据仓库自动选择 gc-branch
+- `resolve` 过程中的 include/exclude 交互
+- branch repo map 更新
+- 引导式 onboarding/update 的边界条件
+
+## 手动 provider E2E 验证
+
+自动测试会关闭 provider launch，只验证 launch plan，而不会真的打开 Codex 或 Claude Code 会话。
+如果你想亲自验证真实启动路径，可以在临时目录里运行：
+
+```bash
+gctree init --provider codex
+gctree init --provider claude-code
+```
+
+正常情况下，provider 会真正启动，并立即收到 `$gc-onboard` 或 `/gc-onboard`。
+
+## 项目结构
+
+- `src/` — CLI、上下文存储、provider 选择、仓库范围映射、引导式 onboarding/update 流程、scaffolding 逻辑
+- `tests/` — CLI 与行为测试
+- `skills/` — 工具无关的工作流技能
+- `scaffolds/` — 宿主特定的 bootstrap 模板
+- `docs/` — concept、principles、usage 与 development 文档

package/docs/principles.es.md

@@ -0,0 +1,49 @@
+# Principios
+
+[English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
+
+## Summary
+
+`gctree` sigue un conjunto pequeño pero claro de principios de producto: separar el contexto por gc-branch, escribir documentos summary-first, mantener los índices livianos y hacer que cada gc-branch solo influya en los repositorios donde realmente corresponde.
+
+## 1. Separar el contexto por gc-branch
+
+Una sola máquina puede contener varios árboles de contexto global sin mezclarlos.
+Por eso `gctree` usa comandos al estilo git como `checkout` y `checkout -b`, pero en la interfaz deja claro que la rama activa se presenta como **gc-branch**.
+
+## 2. Gestionar explícitamente el alcance por repositorio
+
+Un gc-branch no debería afectar en silencio a todos los repositorios de la máquina.
+`gctree` usa `branch-repo-map.json` para registrar el estado de un repo respecto a un gc-branch:
+
+- include
+- exclude
+- aún sin mapear
+
+Si `resolve` se ejecuta en un repo sin mapear, el usuario puede decidir si quiere continuar solo esta vez, usar siempre ese gc-branch allí o ignorarlo allí.
+
+## 3. Mantener `index.md` liviano
+
+El `index.md` de nivel superior es un índice, no un volcado de conocimiento.
+Su trabajo es llevar a herramientas y personas rápidamente al documento fuente correcto.
+
+## 4. Priorizar documentos summary-first
+
+Cada documento markdown source-of-truth debería incluir una sección `## Summary` cerca del inicio.
+Así las herramientas pueden leer primero la versión corta y abrir el resto solo cuando haga falta.
+
+## 5. Hacer que el onboarding sea explícito y guiado
+
+El usuario no debería tener que escribir JSON a mano para crear un contexto global útil.
+`gctree init` y `gctree onboard` deberían guiar la conversación a través del provider elegido y guardar el resultado en el gc-branch activo.
+
+El onboarding solo aplica a gc-branches vacíos.
+Si un gc-branch ya tiene contexto, la ruta correcta es:
+
+- resetear ese gc-branch y volver a hacer onboarding
+- o ejecutar una actualización duradera guiada
+
+## 6. Mantener las actualizaciones duraderas bajo control
+
+El contexto duradero no debería cambiar por accidente ni por memoria oculta.
+El flujo de actualización debe ser explícito, guiado por el provider y siempre ligado al gc-branch activo.

package/docs/principles.ja.md

@@ -0,0 +1,49 @@
+# 原則
+
+[English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
+
+## Summary
+
+`gctree` は、少数の明確な製品原則に基づいています。コンテキストは gc-branch 単位で分け、文書は summary-first で書き、インデックスは小さく保ち、各 gc-branch が本当に関係するリポジトリでだけ使われるようにします。
+
+## 1. コンテキストを gc-branch 単位で分ける
+
+1 台のマシン上に複数のグローバルコンテキストツリーを混在させずに保持できます。
+そのため `gctree` は `checkout` や `checkout -b` のような git ライクなコマンドを使いながら、ユーザー向けには現在のブランチを **gc-branch** と明示します。
+
+## 2. リポジトリ範囲を明示的に管理する
+
+ある gc-branch がマシン上のすべてのリポジトリへ静かに影響してはいけません。
+`gctree` は `branch-repo-map.json` によって、そのリポジトリがその gc-branch に対してどの状態かを記録します。
+
+- include
+- exclude
+- まだ未設定
+
+`resolve` が未設定のリポジトリで呼ばれた場合、今回だけ使うか、今後も使うか、ここでは無視するかを選べます。
+
+## 3. `index.md` を小さく保つ
+
+トップレベルの `index.md` はダンプではなくインデックスです。
+役割は、ツールを適切な source document へ素早く導くことであり、知識をすべてインラインで複製することではありません。
+
+## 4. summary-first 文書を優先する
+
+すべての source-of-truth markdown 文書は、できるだけ冒頭近くに `## Summary` を置くべきです。
+これにより、ツールはまず短い要約を読み、要約だけで足りる場合は全文読み込みを避けられます。
+
+## 5. オンボーディングは明示的かつガイド付きにする
+
+有用なグローバルコンテキストを作るために、ユーザーが手で onboarding JSON を書く必要はありません。
+`gctree init` と `gctree onboard` は、ユーザーが選んだ provider を通じて対話し、その結果を現在の gc-branch に書き込みます。
+
+オンボーディングは空の gc-branch に対してのみ実行します。
+すでにコンテキストが入っている場合は、次のどちらかが正しい流れです。
+
+- gc-branch をリセットしてから再オンボーディングする
+- またはガイド付きの永続更新を行う
+
+## 6. 永続更新は意図的に行う
+
+長期コンテキストは、隠れたメモリや偶発的な操作で変わるべきではありません。
+更新フローは明示的で、provider 主導で、常に現在アクティブな gc-branch に結びついている必要があります。

package/docs/principles.ko.md

@@ -0,0 +1,49 @@
+# 원리
+
+[English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
+
+## Summary
+
+`gctree`는 몇 가지 단순한 제품 원칙을 따릅니다. 컨텍스트는 gc-branch 단위로 분리하고, 문서는 summary-first로 작성하며, 인덱스는 작게 유지하고, 각 gc-branch가 실제로 관련 있는 레포에서만 영향을 주도록 범위를 명시합니다.
+
+## 1. 컨텍스트는 gc-branch 단위로 분리한다
+
+한 머신 안에서도 여러 글로벌 컨텍스트 트리를 섞지 않고 운영할 수 있어야 합니다.
+그래서 `gctree`는 `checkout`, `checkout -b` 같은 git 스타일 명령을 쓰되, 사용자에게는 현재 브랜치를 **gc-branch**라고 명시합니다.
+
+## 2. 레포 범위를 명시적으로 관리한다
+
+어떤 gc-branch가 머신의 모든 레포에 조용히 영향을 주면 안 됩니다.
+`gctree`는 `branch-repo-map.json`을 통해 각 레포가 해당 gc-branch에 대해 어떤 상태인지 기록합니다.
+
+- include
+- exclude
+- 아직 미지정
+
+`resolve`가 미지정 레포에서 호출되면, 이번만 사용할지 / 항상 사용할지 / 여기서는 무시할지를 고를 수 있습니다.
+
+## 3. `index.md`는 작게 유지한다
+
+최상위 `index.md`는 지식 덤프가 아니라 인덱스입니다.
+역할은 도구를 올바른 source document로 빠르게 안내하는 것이지, 모든 내용을 인라인으로 복제하는 것이 아닙니다.
+
+## 4. summary-first 문서를 우선한다
+
+모든 source-of-truth markdown 문서는 상단 근처에 `## Summary` 섹션을 두는 것이 좋습니다.
+이렇게 하면 도구가 먼저 짧은 버전을 읽고, 요약만으로 충분할 때는 전체 문서를 읽지 않아도 됩니다.
+
+## 5. 온보딩은 명시적이고 가이드형이어야 한다
+
+유용한 글로벌 컨텍스트를 만들기 위해 사용자가 직접 onboarding JSON을 손으로 작성할 필요는 없어야 합니다.
+`gctree init`과 `gctree onboard`는 사용자가 고른 provider를 통해 질문을 주고받으며 활성 gc-branch에 결과를 기록해야 합니다.
+
+온보딩은 비어 있는 gc-branch에서만 실행합니다.
+이미 컨텍스트가 있다면 다음 중 하나가 올바른 경로입니다.
+
+- gc-branch를 리셋하고 다시 온보딩한다
+- 또는 가이드형 장기 업데이트를 실행한다
+
+## 6. 장기 업데이트는 의도적으로 수행한다
+
+장기 컨텍스트는 실수로 바뀌거나 숨겨진 메모리로 덮어써지면 안 됩니다.
+업데이트는 명시적이어야 하고, provider를 통해 진행되며, 항상 현재 활성 gc-branch에 연결되어야 합니다.

package/docs/principles.md

@@ -0,0 +1,50 @@
+# Principles
+
+[English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
+
+## Summary
+
+`gctree` follows a small set of product rules: keep context branch-aware, keep source docs summary-first, keep indexes slim, and make repo scope explicit so a gc-branch only influences the repositories where it belongs.
+
+## 1. Keep context branch-aware
+
+A single machine should be able to hold multiple global-context trees without mixing them.
+That is why `gctree` uses git-like language such as `checkout` and `checkout -b`, while referring to the active branch as a **gc-branch** in user-facing language.
+
+## 2. Keep repo scope explicit
+
+A gc-branch should not silently affect every repository on the machine.
+`gctree` uses `branch-repo-map.json` to record whether a repository is:
+
+- included for a gc-branch
+- excluded for a gc-branch
+- not mapped yet
+
+If `resolve` is called from an unmapped repository, the user can decide whether to continue once, always use that gc-branch there, or ignore it there.
+
+## 3. Keep `index.md` slim
+
+The top-level `index.md` is an index, not a dump.
+Its job is to help tools and humans find the right source document quickly.
+It should stay compact and link-oriented instead of duplicating full knowledge inline.
+
+## 4. Make source docs summary-first
+
+Every source-of-truth markdown document should include a `## Summary` section near the top.
+That gives downstream tools a fast path: read the short version first, then expand only when more detail is necessary.
+
+## 5. Make onboarding explicit and guided
+
+A user should not have to hand-author onboarding JSON just to create a useful context tree.
+`gctree init` and `gctree onboard` should guide the user through their preferred provider and write the resulting context into the active gc-branch.
+
+Onboarding is only for empty gc-branches.
+If a gc-branch already contains context, the correct path is either:
+
+- reset that gc-branch and onboard again
+- or run a guided durable update
+
+## 6. Keep durable updates intentional
+
+Durable context should not change by accident or through hidden memory.
+The update flow should be explicit, provider-driven, and tied to the currently active gc-branch.

package/docs/principles.zh.md

@@ -0,0 +1,49 @@
+# 原理
+
+[English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
+
+## Summary
+
+`gctree` 遵循一组简洁而明确的产品原则：上下文按 gc-branch 隔离、文档采用 summary-first 结构、索引保持精简，并且让每个 gc-branch 只在真正相关的仓库里生效。
+
+## 1. 按 gc-branch 隔离上下文
+
+一台机器可以同时保存多个全局上下文树，而且彼此不混淆。
+因此 `gctree` 虽然使用 `checkout`、`checkout -b` 这样的 git 风格命令，但在用户界面里会明确把当前分支称为 **gc-branch**。
+
+## 2. 显式管理仓库范围
+
+某个 gc-branch 不应该悄悄影响整台机器上的所有仓库。
+`gctree` 通过 `branch-repo-map.json` 记录一个仓库相对于某个 gc-branch 的状态：
+
+- include
+- exclude
+- 尚未映射
+
+当 `resolve` 在一个尚未映射的仓库里被调用时，用户可以选择是仅本次继续、以后总是使用，还是在这里忽略它。
+
+## 3. 保持 `index.md` 精简
+
+顶层 `index.md` 是索引，不是内容堆积区。
+它的职责是把工具快速引导到正确的源文档，而不是把所有知识都内联复制进去。
+
+## 4. 优先使用 summary-first 文档
+
+每个 source-of-truth markdown 文档都应该在靠前位置包含 `## Summary`。
+这样工具可以先读取简短版本，如果摘要已经足够，就不必再读取整篇文档。
+
+## 5. 让 onboarding 明确且有引导
+
+用户不应该为了创建可用的全局上下文而手写 onboarding JSON。
+`gctree init` 和 `gctree onboard` 应该通过用户选择的 provider 与用户对话，并把结果写入当前 gc-branch。
+
+onboarding 只适用于空的 gc-branch。
+如果该 gc-branch 已经有内容，正确做法是：
+
+- 重置该 gc-branch 后重新 onboarding
+- 或者执行一次引导式长期更新
+
+## 6. 让长期更新保持可控
+
+长期上下文不应该因为隐式记忆或误操作而被改写。
+更新流程应当是显式的、由 provider 驱动的，并且始终绑定到当前激活的 gc-branch。