@handsupmin/gc-tree 0.1.1

package/dist/src/store.js

@@ -0,0 +1,149 @@
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { branchDir, branchDocsDir, branchIndexPath, branchMetaPath, branchesRoot, DEFAULT_BRANCH, headPath, INDEX_WARNING_CHARS, } from './paths.js';
+import { renderIndexMarkdown } from './markdown.js';
+export async function ensureHome(home) {
+    await mkdir(branchesRoot(home), { recursive: true });
+}
+export async function readHead(home) {
+    try {
+        return (await readFile(headPath(home), 'utf8')).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeHead(home, branch) {
+    await ensureHome(home);
+    await writeFile(headPath(home), `${branch}\n`, 'utf8');
+}
+export async function initHome(home, branch = DEFAULT_BRANCH) {
+    const already = existsSync(headPath(home));
+    await ensureHome(home);
+    await ensureBranch(home, branch, { copyFrom: null, summary: `Default gc-branch for ${branch}.` });
+    await writeHead(home, branch);
+    return { home, gc_branch: branch, created: !already };
+}
+export async function ensureBranch(home, branch, options) {
+    const dir = branchDir(home, branch);
+    if (existsSync(dir))
+        return;
+    await ensureHome(home);
+    if (options.copyFrom) {
+        await cp(branchDir(home, options.copyFrom), dir, { recursive: true });
+        const meta = await readBranchMeta(home, branch);
+        meta.branch = branch;
+        meta.updated_at = new Date().toISOString();
+        await writeFile(branchMetaPath(home, branch), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+        return;
+    }
+    await mkdir(branchDocsDir(home, branch), { recursive: true });
+    const now = new Date().toISOString();
+    const meta = {
+        version: 1,
+        branch,
+        created_at: now,
+        updated_at: now,
+        summary: options.summary,
+    };
+    await writeFile(branchMetaPath(home, branch), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+    await writeFile(branchIndexPath(home, branch), renderIndexMarkdown({ branch, branchSummary: meta.summary, docs: [] }), 'utf8');
+}
+export async function readBranchMeta(home, branch) {
+    const raw = await readFile(branchMetaPath(home, branch), 'utf8');
+    return JSON.parse(raw);
+}
+export async function updateBranchMeta(home, branch, input) {
+    const current = await readBranchMeta(home, branch);
+    const next = {
+        ...current,
+        ...input,
+        updated_at: new Date().toISOString(),
+    };
+    await writeFile(branchMetaPath(home, branch), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return next;
+}
+export async function listBranches(home) {
+    await ensureHome(home);
+    const entries = await readdir(branchesRoot(home), { withFileTypes: true }).catch(() => []);
+    const gcBranches = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    return {
+        gc_branches: gcBranches,
+        current_gc_branch: await readHead(home),
+    };
+}
+export async function checkoutBranch(home, branch, create = false) {
+    const exists = existsSync(branchDir(home, branch));
+    if (!exists && !create) {
+        throw new Error(`gc-branch does not exist: ${branch}`);
+    }
+    if (!exists) {
+        await ensureBranch(home, branch, {
+            copyFrom: null,
+            summary: `Created gc-branch ${branch}.`,
+        });
+    }
+    await writeHead(home, branch);
+    return {
+        gc_branch: branch,
+        created: !exists,
+    };
+}
+export async function writeIndexFromDocs(home, branch) {
+    const docsDir = branchDocsDir(home, branch);
+    await mkdir(docsDir, { recursive: true });
+    const files = (await readdir(docsDir)).filter((file) => file.endsWith('.md')).sort();
+    const docs = await Promise.all(files.map(async (file) => {
+        const raw = await readFile(join(docsDir, file), 'utf8');
+        const title = raw.match(/^#\s+(.+)$/m)?.[1]?.trim() || file.replace(/\.md$/i, '').replace(/-/g, ' ');
+        return { title, path: `docs/${file}` };
+    }));
+    const meta = await readBranchMeta(home, branch);
+    const index = renderIndexMarkdown({ branch, branchSummary: meta.summary, docs });
+    await writeFile(branchIndexPath(home, branch), index, 'utf8');
+    return { index_path: branchIndexPath(home, branch), doc_count: docs.length };
+}
+export async function isBranchContextEmpty(home, branch) {
+    const docs = (await readdir(branchDocsDir(home, branch)).catch(() => [])).filter((file) => file.endsWith('.md'));
+    return docs.length === 0;
+}
+export async function resetBranchContext(home, branch) {
+    await ensureBranchExists(home, branch);
+    await rm(branchDocsDir(home, branch), { recursive: true, force: true });
+    await mkdir(branchDocsDir(home, branch), { recursive: true });
+    await updateBranchMeta(home, branch, { summary: `Reset gc-branch ${branch}. Awaiting onboarding.` });
+    const index = await writeIndexFromDocs(home, branch);
+    return {
+        gc_branch: branch,
+        reset: true,
+        index_path: index.index_path,
+    };
+}
+export async function statusForBranch(home, branch) {
+    const indexRaw = await readFile(branchIndexPath(home, branch), 'utf8');
+    const docs = (await readdir(branchDocsDir(home, branch)).catch(() => [])).filter((file) => file.endsWith('.md'));
+    const warnings = [];
+    if (indexRaw.length > INDEX_WARNING_CHARS) {
+        warnings.push(`index.md is ${indexRaw.length} chars; keep it closer to an index than a knowledge dump.`);
+    }
+    for (const doc of docs) {
+        const raw = await readFile(join(branchDocsDir(home, branch), doc), 'utf8');
+        if (!/^## Summary$/m.test(raw)) {
+            warnings.push(`source doc is missing a Summary section: docs/${doc}`);
+        }
+    }
+    return {
+        home,
+        gc_branch: branch,
+        index_path: branchIndexPath(home, branch),
+        index_chars: indexRaw.length,
+        doc_count: docs.length,
+        warnings,
+    };
+}
+export async function ensureBranchExists(home, branch) {
+    if (!existsSync(branchDir(home, branch))) {
+        throw new Error(`gc-branch does not exist: ${branch}`);
+    }
+}

package/dist/src/types.js

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

package/dist/src/update.js

@@ -0,0 +1,26 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { renderDocMarkdown, slugify } from './markdown.js';
+import { branchDocsDir, DEFAULT_BRANCH } from './paths.js';
+import { ensureBranchExists, updateBranchMeta, writeIndexFromDocs } from './store.js';
+export async function updateBranchContext({ home, input, branch, }) {
+    const targetBranch = branch || input.branch || DEFAULT_BRANCH;
+    await ensureBranchExists(home, targetBranch);
+    await mkdir(branchDocsDir(home, targetBranch), { recursive: true });
+    const written = [];
+    for (const doc of input.docs) {
+        const fileName = `${slugify(doc.slug || doc.title)}.md`;
+        const fullPath = join(branchDocsDir(home, targetBranch), fileName);
+        await writeFile(fullPath, renderDocMarkdown(doc), 'utf8');
+        written.push(fullPath);
+    }
+    if (input.branchSummary?.trim()) {
+        await updateBranchMeta(home, targetBranch, { summary: input.branchSummary.trim() });
+    }
+    const index = await writeIndexFromDocs(home, targetBranch);
+    return {
+        gc_branch: targetBranch,
+        updated_docs: written,
+        index_path: index.index_path,
+    };
+}

package/docs/concept.es.md

@@ -0,0 +1,81 @@
+# Concepto
+
+[English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
+
+## Summary
+
+`gctree` es una capa de contexto global pequeña y clara para herramientas de programación con IA. Mantiene el contexto duradero en documentos markdown fuera de un único repositorio, permite cambiarlo y consultarlo por gc-branch, y además puede limitar cada gc-branch a los repositorios donde realmente aplica.
+
+## Qué es `gctree`
+
+`gctree` es una CLI ligera para gestionar contexto global reutilizable.
+Está pensada para personas y equipos que necesitan conservar el mismo contexto duradero entre varios repositorios, sesiones y herramientas.
+
+En lugar de dejar ese conocimiento repartido entre archivos de prompts o depender de memoria oculta, `gctree` le da un lugar claro, estable y basado en archivos.
+
+## Qué problema resuelve
+
+Muchos entornos de programación con IA empiezan con una de estas opciones:
+
+- un solo `AGENTS.md`
+- un solo `CLAUDE.md`
+- un archivo de prompts dentro del repositorio
+- un conjunto de notas copiadas manualmente en los prompts
+
+Eso funciona al principio, pero con el tiempo aparecen necesidades como estas:
+
+- separar el contexto por producto o cliente
+- mantener contexto fuera de un único repositorio
+- reutilizar la misma documentación duradera desde varias herramientas
+- encontrar el contexto correcto de forma rápida y consistente
+- actualizar el contexto duradero de una forma más segura
+- trabajar en paralelo en muchos repositorios y sesiones a la vez
+
+`gctree` se ocupa precisamente de esa capa.
+
+## Límite de alcance
+
+`gctree` intencionalmente no es:
+
+- un orquestador de entrega request-to-commit
+- un sistema de memoria oculta
+- un runtime de colaboración en navegador
+- un producto generalista de base de conocimiento
+
+Se centra en ramas reutilizables de contexto global y en flujos de actualización explícitos.
+
+## Estructura de archivos
+
+Un directorio home típico se ve así:
+
+```text
+~/.gctree/
+  HEAD
+  settings.json
+  branch-repo-map.json
+  branches/
+    main/
+      branch.json
+      index.md
+      docs/
+```
+
+- `HEAD` indica el gc-branch activo de fallback.
+- `settings.json` guarda el modo de provider, el provider real usado para iniciar el onboarding y el idioma preferido del flujo.
+- `branch-repo-map.json` guarda las reglas include/exclude por gc-branch.
+- `branch.json` guarda metadatos ligeros del gc-branch.
+- `index.md` es el punto de entrada compacto para las herramientas.
+- `docs/` guarda los documentos markdown source-of-truth.
+
+## Comportamiento con alcance por repositorio
+
+Un gc-branch no tiene por qué aplicarse a todos los repositorios.
+Si la rama `A` solo es relevante para `B`, `C` y `D`, eso puede registrarse en `branch-repo-map.json`.
+
+Entonces, si ejecutas `gctree resolve` desde `F`, puedes elegir entre:
+
+- continuar solo esta vez
+- usar siempre esa rama en ese repo
+- ignorarla en ese repo
+
+Eso vuelve a `gctree` mucho más seguro para usuarios intensivos que mantienen muchas sesiones paralelas abiertas sobre repositorios no relacionados.

package/docs/concept.ja.md

@@ -0,0 +1,81 @@
+# コンセプト
+
+[English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
+
+## Summary
+
+`gctree` は AI コーディングツール向けの、小さく明確なグローバルコンテキストレイヤーです。長期コンテキストを単一リポジトリの外にある markdown 文書として管理し、gc-branch 単位で切り替え・参照・維持でき、さらに実際に関係するリポジトリだけに適用範囲を絞れます。
+
+## `gctree` とは
+
+`gctree` は再利用可能なグローバルコンテキストを管理するための軽量 CLI です。
+複数のリポジトリ、セッション、ツールをまたいでも同じ長期コンテキストを使い続けたい個人やチームのために設計されています。
+
+長期知識を隠れたメモリに任せたり、複数のプロンプトファイルへ散らしたりする代わりに、`gctree` はその知識に明確で安定したファイルベースの置き場所を与えます。
+
+## 解決する課題
+
+多くの AI コーディング環境は、次のいずれかから始まります。
+
+- 1 つの `AGENTS.md`
+- 1 つの `CLAUDE.md`
+- リポジトリ内のローカルなプロンプトファイル
+- プロンプトに都度貼り付けるメモ
+
+最初はそれで十分でも、やがて次のような要件が出てきます。
+
+- プロダクトやクライアントごとにコンテキストを分けたい
+- 1 つのリポジトリの外にコンテキストを保ちたい
+- 複数ツールが同じ長期文書を再利用できるようにしたい
+- 必要なコンテキストを一貫した方法で素早く見つけたい
+- 長期コンテキストをより安全に更新したい
+- 同じユーザーが複数のリポジトリ・複数のセッションで並行作業する
+
+`gctree` は、まさにその層を扱います。
+
+## スコープ境界
+
+`gctree` が意図的に担当しないものは次の通りです。
+
+- request-to-commit 型のデリバリーオーケストレータ
+- 隠れたメモリシステム
+- ブラウザ協業ランタイム
+- 汎用ナレッジベース製品
+
+`gctree` は、再利用可能なグローバルコンテキストブランチと、明示的な更新フローに集中します。
+
+## ファイル構成
+
+典型的なホームディレクトリ構成は次の通りです。
+
+```text
+~/.gctree/
+  HEAD
+  settings.json
+  branch-repo-map.json
+  branches/
+    main/
+      branch.json
+      index.md
+      docs/
+```
+
+- `HEAD` は fallback のアクティブ gc-branch を指します。
+- `settings.json` は provider モード、実際のオンボーディング起動 provider、優先ワークフロー言語を保持します。
+- `branch-repo-map.json` は gc-branch ごとの include/exclude リポジトリ規則を保存します。
+- `branch.json` は軽量な gc-branch メタデータを保存します。
+- `index.md` はツール向けの小さな入口です。
+- `docs/` には source-of-truth の markdown 文書を保存します。
+
+## リポジトリ範囲の振る舞い
+
+ある gc-branch がすべてのリポジトリに適用される必要はありません。
+たとえば branch `A` が `B`、`C`、`D` にだけ関係するなら、その事実を `branch-repo-map.json` に記録できます。
+
+その状態で `F` リポジトリから `gctree resolve` を実行すると、次を選べます。
+
+- 今回だけ使う
+- 今後もこのリポジトリで使う
+- このリポジトリでは無視する
+
+これにより、多数のセッションを開いて複数の無関係なリポジトリで並行作業する heavy ユーザーにも、より安全に使えるようになります。

package/docs/concept.ko.md

@@ -0,0 +1,81 @@
+# 컨셉
+
+[English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
+
+## Summary
+
+`gctree`는 AI 코딩 도구를 위한 작고 명확한 글로벌 컨텍스트 레이어입니다. 장기적으로 유지할 컨텍스트를 단일 저장소 바깥의 markdown 문서로 관리하고, gc-branch 단위로 전환·조회·유지할 수 있으며, 실제로 관련 있는 레포에만 적용되도록 범위를 제한할 수도 있습니다.
+
+## `gctree`란
+
+`gctree`는 재사용 가능한 글로벌 컨텍스트를 관리하기 위한 경량 CLI입니다.
+여러 저장소, 세션, 도구를 오가더라도 같은 장기 컨텍스트를 일관되게 이어가야 하는 팀과 개인을 위해 만들어졌습니다.
+
+장기 지식을 숨겨진 메모리에 맡기거나 여러 프롬프트 파일에 흩어 두는 대신, `gctree`는 그 지식이 머무를 안정적인 파일 기반 홈을 제공합니다.
+
+## 해결하는 문제
+
+많은 AI 코딩 환경은 보통 다음 중 하나로 시작합니다.
+
+- 하나의 `AGENTS.md`
+- 하나의 `CLAUDE.md`
+- 저장소 내부의 프롬프트 파일
+- 프롬프트에 복붙하는 임시 메모
+
+처음에는 이 정도로도 충분하지만, 시간이 지나면 이런 요구가 생깁니다.
+
+- 제품이나 고객사별로 컨텍스트를 분리하고 싶다
+- 특정 저장소 바깥에서도 유지되는 컨텍스트가 필요하다
+- 여러 도구가 함께 재사용할 수 있는 장기 문서가 필요하다
+- 필요한 컨텍스트를 빠르게 찾는 일관된 방식이 필요하다
+- 장기 컨텍스트를 더 안전하게 업데이트하고 싶다
+- 한 사용자가 동시에 여러 레포/세션에서 병렬 작업을 한다
+
+`gctree`는 바로 그 레이어를 다룹니다.
+
+## 범위 경계
+
+`gctree`는 의도적으로 다음 역할을 맡지 않습니다.
+
+- request-to-commit 딜리버리 오케스트레이터
+- 숨겨진 메모리 시스템
+- 브라우저 기반 협업 런타임
+- 범용 지식베이스 제품
+
+`gctree`는 재사용 가능한 글로벌 컨텍스트 브랜치와 명시적인 업데이트 흐름에 집중합니다.
+
+## 파일 구조
+
+일반적인 홈 디렉터리 구조는 다음과 같습니다.
+
+```text
+~/.gctree/
+  HEAD
+  settings.json
+  branch-repo-map.json
+  branches/
+    main/
+      branch.json
+      index.md
+      docs/
+```
+
+- `HEAD`는 fallback 활성 gc-branch를 가리킵니다.
+- `settings.json`은 provider 모드, 실제 온보딩에 사용할 provider, 선호 워크플로 언어를 저장합니다.
+- `branch-repo-map.json`은 gc-branch별 include/exclude 레포 규칙을 저장합니다.
+- `branch.json`은 가벼운 gc-branch 메타데이터를 저장합니다.
+- `index.md`는 도구가 읽는 작은 진입점입니다.
+- `docs/`는 source-of-truth markdown 문서를 보관합니다.
+
+## 레포 범위 인식 동작
+
+어떤 gc-branch가 모든 레포에 적용될 필요는 없습니다.
+예를 들어 branch `A`가 `B`, `C`, `D` 레포에만 관련 있다면, 그 사실을 `branch-repo-map.json`에 기록할 수 있습니다.
+
+그 상태에서 `F` 레포에서 `gctree resolve`가 호출되면 다음 중 하나를 고를 수 있습니다.
+
+- 이번만 사용
+- 이 레포에서 항상 사용
+- 이 레포에서는 무시
+
+이 구조 덕분에, 동시에 여러 세션을 열고 서로 다른 레포를 다루는 heavy 사용자에게도 더 안전해집니다.

package/docs/concept.md

@@ -0,0 +1,81 @@
+# Concept
+
+[English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
+
+## Summary
+
+`gctree` is a lightweight global-context layer for AI coding tools. It keeps durable context in explicit markdown documents outside any single repository, lets users switch between gc-branches, and can restrict each gc-branch to the repositories where it actually applies.
+
+## What `gctree` is
+
+`gctree` is a CLI for managing reusable global context.
+It is designed for teams and individuals who want long-lived context to survive across repositories, sessions, and tools without turning that context into hidden memory.
+
+Instead of scattering important knowledge across prompt files, repo-local notes, and ad hoc instructions, `gctree` gives that knowledge a stable, file-backed home.
+
+## What problem it solves
+
+Many AI coding setups start small:
+
+- one `AGENTS.md`
+- one `CLAUDE.md`
+- one repo-local prompt file
+- a handful of notes copied into prompts as needed
+
+That works for a while. Then the same setup starts to break under real-world needs:
+
+- different products need different context
+- client work must stay isolated
+- reusable guidance should live outside any single repository
+- multiple tools should be able to read the same source of truth
+- long-lived context should evolve through a safe, reviewable flow
+- one user may run many sessions across many repositories at the same time
+
+`gctree` exists to solve that layer cleanly.
+
+## Scope boundary
+
+`gctree` is intentionally not:
+
+- a request-to-commit delivery orchestrator
+- a hidden memory system
+- a browser collaboration runtime
+- a general-purpose knowledge base product
+
+It focuses on one job: managing reusable global-context branches and explicit updates.
+
+## File model
+
+A typical home directory looks like this:
+
+```text
+~/.gctree/
+  HEAD
+  settings.json
+  branch-repo-map.json
+  branches/
+    main/
+      branch.json
+      index.md
+      docs/
+```
+
+- `HEAD` tracks the fallback active gc-branch.
+- `settings.json` stores the provider mode, the onboarding provider chosen for runtime launch, and the preferred workflow language.
+- `branch-repo-map.json` stores which repositories are included or excluded for each gc-branch.
+- `branch.json` stores lightweight gc-branch metadata.
+- `index.md` is the compact entry point for tools.
+- `docs/` holds source-of-truth markdown documents.
+
+## Repo-aware behavior
+
+A gc-branch does not have to apply everywhere.
+If branch `A` is only relevant to repositories `B`, `C`, and `D`, `gctree` can record that in `branch-repo-map.json`.
+
+When `gctree resolve` runs in another repository such as `F`, it can:
+
+- continue once
+- always use that gc-branch in `F`
+- ignore that gc-branch in `F`
+
+This makes gc-tree much safer for heavy users who keep many parallel sessions open across unrelated repositories.

package/docs/concept.zh.md

@@ -0,0 +1,81 @@
+# 概念
+
+[English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
+
+## Summary
+
+`gctree` 是一个小而明确的全局上下文层，面向 AI 编码工具。它把长期上下文放在单一仓库之外的 markdown 文档中，可以按 gc-branch 切换、检索和维护，也可以限制某个 gc-branch 只在真正相关的仓库中生效。
+
+## `gctree` 是什么
+
+`gctree` 是一个用于管理可复用全局上下文的轻量 CLI。
+它面向那些需要在多个仓库、多个会话和多种工具之间持续复用长期上下文的个人与团队。
+
+与其把长期知识交给隐藏记忆，或者散落在多个提示文件中，`gctree` 更像是为这些知识提供了一个清晰、稳定、基于文件的归档位置。
+
+## 它解决什么问题
+
+很多 AI 编码工作流最初都从下面这些方式开始：
+
+- 一个 `AGENTS.md`
+- 一个 `CLAUDE.md`
+- 仓库里的本地提示文件
+- 一组临时复制到提示词里的笔记
+
+一开始这样可以工作，但随着项目变复杂，往往会出现这些需求：
+
+- 希望按产品或客户隔离上下文
+- 希望把上下文放在单个仓库之外长期维护
+- 希望多种工具复用同一套长期文档
+- 希望用一致的方式快速找到正确的上下文
+- 希望以更安全的方式持续更新长期上下文
+- 同一个用户会同时在多个仓库和多个会话中并行工作
+
+`gctree` 解决的正是这一层问题。
+
+## 范围边界
+
+`gctree` 有意不做以下事情：
+
+- request-to-commit 交付编排器
+- 隐式记忆系统
+- 浏览器协作运行时
+- 通用知识库产品
+
+它专注于可复用的全局上下文分支，以及显式的更新流程。
+
+## 文件结构
+
+一个典型的 home 目录大致如下：
+
+```text
+~/.gctree/
+  HEAD
+  settings.json
+  branch-repo-map.json
+  branches/
+    main/
+      branch.json
+      index.md
+      docs/
+```
+
+- `HEAD` 记录 fallback 的激活 gc-branch。
+- `settings.json` 保存 provider 模式、实际用于启动 onboarding 的 provider，以及首选工作流语言。
+- `branch-repo-map.json` 保存每个 gc-branch 的 include/exclude 仓库规则。
+- `branch.json` 保存轻量级 gc-branch 元数据。
+- `index.md` 是工具读取时的紧凑入口。
+- `docs/` 存放 source-of-truth markdown 文档。
+
+## 仓库范围行为
+
+某个 gc-branch 不一定需要作用于所有仓库。
+如果 branch `A` 只适用于 `B`、`C`、`D`，就可以把这个关系写进 `branch-repo-map.json`。
+
+这样一来，当 `F` 仓库里运行 `gctree resolve` 时，可以选择：
+
+- 这次先继续
+- 以后这个仓库总是使用这个 gc-branch
+- 在这个仓库里忽略这个 gc-branch
+
+这让 `gctree` 更适合同时开很多会话、在多个不相关仓库里并行工作的 heavy 用户。

package/docs/local-development.es.md

@@ -0,0 +1,83 @@
+# Desarrollo local
+
+[English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
+
+## Summary
+
+El desarrollo local sigue un flujo estándar de Node.js 20+: instala dependencias, construye la CLI, ejecútala localmente y verifica con la suite de tests existente antes de enviar cambios.
+
+## Estado del paquete
+
+`@handsupmin/gc-tree` es el nombre del paquete npm publicado para este repositorio, mientras que el nombre del repositorio sigue siendo `gc-tree`.
+Antes de cualquier release ejecuta `npm publish --dry-run` y, después de publicar de verdad, verifica el paquete desde un directorio limpio con `npx @handsupmin/gc-tree --help` o `npm install -g @handsupmin/gc-tree`.
+
+## Requisitos previos
+
+- Node.js 20+
+- npm
+- binarios locales de `codex` o `claude` si quieres validar manualmente el arranque del provider
+
+## Configuración
+
+```bash
+npm install
+npm run build
+```
+
+## Ejecutar la CLI localmente
+
+### Opción 1: ejecutar directamente la entrada construida
+
+```bash
+node dist/src/cli.js status
+```
+
+### Opción 2: enlazar la CLI a tu shell
+
+```bash
+npm link
+gctree status
+```
+
+Si cambias el código TypeScript, vuelve a construir antes de probar de nuevo la CLI.
+
+## Verificación
+
+Antes de enviar cambios, ejecuta:
+
+```bash
+npm run build
+npm test
+npm publish --dry-run
+```
+
+## Tests de alcance por repositorio
+
+La suite actual verifica:
+
+- persistencia del modo de provider (`claude-code`, `codex`, `both`)
+- persistencia del idioma preferido y refuerzo fuerte del idioma en el launch prompt
+- selección de gc-branch según el repositorio
+- interacciones include/exclude durante `resolve`
+- actualización del branch repo map
+- límites del flujo guiado de onboarding/update
+
+## Verificación manual E2E del provider
+
+Los tests automáticos desactivan el provider launch para validar el launch plan sin abrir sesiones reales de Codex o Claude Code.
+Si quieres comprobar el camino real de arranque, usa un directorio temporal y ejecuta:
+
+```bash
+gctree init --provider codex
+gctree init --provider claude-code
+```
+
+Si todo está bien, el provider se abrirá de verdad y recibirá inmediatamente `$gc-onboard` o `/gc-onboard`.
+
+## Estructura del proyecto
+
+- `src/` — CLI, almacenamiento de contexto, selección de provider, mapeo de alcance por repositorio, flujos guiados de onboarding/update y lógica de scaffolding
+- `tests/` — tests de CLI y comportamiento
+- `skills/` — skills de flujo de trabajo agnósticos a la herramienta
+- `scaffolds/` — plantillas bootstrap específicas del host
+- `docs/` — documentación de concept, principles, usage y development