@handsupmin/gc-tree 0.8.19 → 1.0.1

package/docs/principles.ko.md

@@ -22,16 +22,32 @@ gc-branch가 머신의 모든 저장소에 조용히 영향을 미쳐서는 안
 
 매핑되지 않은 저장소에서 `resolve`가 호출되면, 사용자가 해당 저장소에서 한 번만 계속할지, 항상 해당 gc-branch를 사용할지, 아니면 무시할지 결정할 수 있습니다.
 
-## 3. `index.md`를 슬림하게 유지한다
+## 3. `index.md`를 슬림하고 키워드 풍부하게 유지한다
 
 최상위 `index.md`는 인덱스이지, 덤프가 아닙니다.
 도구와 사람이 올바른 소스 문서를 빠르게 찾을 수 있도록 돕는 것이 역할입니다.
-**2000자** 이하로 유지되어야 하며, 전체 지식을 인라인으로 복제하는 대신 링크 중심으로 구성되어야 합니다.
 
-## 4. 소스 문서를 요약 우선으로 구성한다
+형식은 각 문서 경로 아래에 키워드를 그룹화하여 경로 항목이 반복되는 것을 없앱니다:
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+이렇게 하면 인덱스를 간결하게 유지하면서 검색 범위를 최대화합니다. 모든 문서에는 가능한 많은 관련 키워드를 포함해야 합니다 — 별칭, 명령어 이름, 필드 이름, 약어, 관련 용어 등 — 어떤 합리적인 쿼리도 유용한 결과를 찾을 수 있도록.
+
+## 4. 소스 문서를 실행 가능한 내용이 담긴 요약 우선으로 구성한다
 
 모든 정보 소스 마크다운 문서는 상단 근처에 `## Summary` 섹션을 포함해야 합니다.
-이는 다운스트림 도구에게 빠른 경로를 제공합니다: 먼저 짧은 버전을 읽고, 실제로 더 많은 상세 내용이 필요할 때만 확장합니다.
+이 섹션은 매 작업 전에 AI 컨텍스트에 주입되므로, 문서가 다루는 내용에 대한 설명이 아니라 **실제 패턴, 명령, 제약사항**을 포함해야 합니다.
+
+나쁜 요약: `"이 문서는 updateCollection 패턴을 설명합니다."`
+좋은 요약: `"updateCollection: { ...dto } spread 필수. return plainToInstance(Res, result satisfies Res). 새 필드 추가 = DTO → 서비스 → 컨트롤러 순서."`
+
+목차 항목처럼 읽히는 요약은 쓸모없습니다. AI는 이를 건너뛰고 바로 코드로 갑니다.
 
 ## 5. 온보딩을 명시적이고 안내된 방식으로 만든다
 

package/docs/principles.md

@@ -22,16 +22,32 @@ A gc-branch should not quietly affect every repository on the machine.
 
 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
+## 3. Keep `index.md` slim and keyword-rich
 
 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 under **2000 characters** and remain link-oriented instead of duplicating full knowledge inline.
 
-## 4. Make source docs summary-first
+The format groups keywords under each document path, eliminating repeated path entries:
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+This keeps the index compact while maximizing search surface. Every document should have as many relevant keywords as possible — aliases, command names, field names, acronyms, and related terms — so that any plausible query hits something useful.
+
+## 4. Make source docs summary-first with actionable content
 
 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 actually needed.
+That section is injected into the AI context before every task — so it must contain **actual patterns, commands, and constraints**, not a description of what the document covers.
+
+Bad summary: `"This document describes the updateCollection pattern."`
+Good summary: `"updateCollection: spread { ...dto } into body. Return plainToInstance(Res, result satisfies Res). New field order: DTO → service → controller."`
+
+A summary that reads like a table-of-contents entry is useless. The AI will skip it and go straight to code.
 
 ## 5. Make onboarding explicit and guided
 

package/docs/principles.zh.md

@@ -22,16 +22,32 @@ gc-branch 不应该悄无声息地影响机器上的每一个代码仓库。
 
 如果从未映射的代码仓库调用 `resolve`，用户可以决定是继续一次、始终在该仓库使用此 gc-branch，还是在该仓库忽略它。
 
-## 3. 保持 `index.md` 精简
+## 3. 保持 `index.md` 精简且关键词丰富
 
 顶层 `index.md` 是索引，而非内容转储。
 它的职责是帮助工具和人员快速找到正确的源文档。
-它应保持在 **2000 字符**以内，以链接为主，而不是将完整知识内联复制进来。
 
-## 4. 让源文档以摘要为先
+格式将关键词统一归在每个文档路径下，避免路径条目的重复：
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+这样既能保持索引紧凑，又能最大化搜索覆盖面。每个文档都应尽可能包含多个相关关键词——别名、命令名、字段名、缩写及关联术语——确保任何合理的查询都能找到有用的结果。
+
+## 4. 让源文档以包含可执行内容的摘要为先
 
 每个作为可信来源的 Markdown 文档都应在靠近顶部的位置包含一个 `## Summary` 部分。
-这为下游工具提供了一条快速路径：先读取简短版本，只有在真正需要更多细节时才展开阅读。
+该部分会在每次任务前注入 AI 上下文，因此必须包含**真实的模式、命令和约束**，而不是对文档内容的描述。
+
+不好的摘要：`"This document describes the updateCollection pattern."`
+好的摘要：`"updateCollection: spread { ...dto } into body. Return plainToInstance(Res, result satisfies Res). New field order: DTO → service → controller."`
+
+像目录条目一样的摘要毫无用处。AI 会直接跳过它去看代码。
 
 ## 5. 让 onboarding 明确且有引导
 

package/docs/usage.es.md

@@ -4,7 +4,7 @@
 
 ## Resumen
 
-Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tree, elegir un proveedor, hacer onboarding de la gc-branch `main` predeterminada, hacer resolve del contexto que necesitas, crear nuevas gc-branches cuando el trabajo merece su propio carril, mapear los repositorios a las gc-branches correctas y usar actualizaciones guiadas para cambios duraderos más adelante.
+Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tree, elegir un proveedor, hacer onboarding de la gc-branch `main` predeterminada, hacer resolve del contexto que necesitas, crear nuevas gc-branches cuando el trabajo merece su propio carril, mapear los repositorios a las gc-branches correctas, usar actualizaciones guiadas para cambios duraderos de contexto y ejecutar `gctree update` cuando quieras refrescar la CLI y las integraciones de providers instaladas.
 
 ## Flujo de trabajo estándar
 
@@ -19,7 +19,8 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 9. crear o cambiar de gc-branch con `gctree checkout`
 10. ejecutar `gctree onboard` solo para una gc-branch vacía
 11. usar el mapeo de alcance del repositorio para que una gc-branch solo aplique donde corresponde
-12. usar `gctree update-global-context` para cambios duraderos más adelante
+12. usar `gctree update-global-context` para cambios duraderos de contexto más adelante
+13. usar `gctree update` para actualizar gc-tree y reinstalar los providers instalados
 
 ## Comandos principales
 
@@ -41,6 +42,7 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 | `gctree update-global-context` | Iniciar una actualización duradera guiada para la gc-branch activa. |
 | `gctree update-gc` / `gctree ugc` | Alias para `gctree update-global-context`. |
 | `gctree scaffold --host <codex\|claude-code>` | Instalar un override local orientado al proveedor en un repositorio o workspace concreto. |
+| `gctree update` | Actualizar gctree a la última versión de npm y reinstalar todos los providers previamente instalados. |
 | `gctree uninstall --yes` | Eliminar `~/.gctree` y la activación global de gctree. |
 
 ## Qué devuelve resolve
@@ -51,40 +53,22 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "query": "auth token rotation policy",
-  "status": "matched",
-  "matches": [
-    {
-      "id": "auth",
-      "title": "Auth & Session Conventions",
-      "path": "docs/auth.md",
-      "score": 4,
-      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
-      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
-      "commands": {
-        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
-        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
-      }
-    }
-  ]
-}
+```
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
+[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"
 ```
 
 El flujo recomendado es:
 
 1. `resolve` → índice compacto
-2. `related` → documentos de apoyo alrededor de una coincidencia
-3. `show-doc` → markdown completo solo cuando hace falta
+2. `show-doc` → markdown completo solo cuando hace falta
 
 La degradación elegante también es explícita:
 
-- gc-branch vacía → `status: "empty_branch"`
-- repo excluido → `status: "excluded"`
-- sin resultados → `status: "no_match"`
-- ID de documento inexistente → `status: "doc_not_found"`
+- gc-branch vacía → mensaje en texto plano indicando que la gc-branch está vacía
+- repo excluido → mensaje en texto plano indicando que el repo está excluido
+- sin resultados → mensaje en texto plano indicando que no hay coincidencias
 
 ## Ejemplo de flujo de alcance del repositorio
 
@@ -128,7 +112,7 @@ Luego:
 ## Ejemplo de flujo con múltiples branches
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -151,13 +135,21 @@ Si un repositorio recién relevante también debería pasar a formar parte del c
 1. mapear ese repositorio a la gc-branch
 2. luego ejecutar `update-global-context` para agregar conocimiento duradero sobre qué hace ese repositorio y por qué es importante
 
+## Ejemplo de flujo de actualización de la herramienta
+
+```bash
+gctree update
+```
+
+Esto actualiza `@handsupmin/gc-tree` a la última versión de npm y reinstala todos los providers ya instalados mediante `gctree init` o `gctree scaffold`. Es el comando de mantenimiento para cuando se publiquen nuevos hooks, comandos, skills o snippets de integración.
+
 ## Patrones de integración
 
 ### Codex CLI / Claude Code CLI
 
 `gctree init` instala la superficie global de hooks orientada al proveedor. `gctree scaffold` instala un override local en un directorio de destino cuando un repositorio concreto necesita sus propios snippets markdown o una superficie de comandos local.
 
-El hook UserPromptSubmit solo inyecta contexto previo compacto: estado found/no-match más títulos e IDs de documentos coincidentes. No incluye resúmenes ni excerpts largos por defecto; abre documentos completos con `gctree resolve --id <id>` cuando sea necesario.
+El hook UserPromptSubmit inyecta los resúmenes de los documentos coincidentes directamente en el contexto antes de cada prompt — de modo que la IA ve patrones y comandos reales, no solo títulos. Cuando un resumen es corto o genérico, el hook recurre a un fragmento del cuerpo del documento. Los documentos completos siempre están disponibles bajo demanda con `gctree resolve --id <id>`.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.ja.md

@@ -4,7 +4,7 @@
 
 ## 概要
 
-標準的な `gctree` の流れはこうです。gc-tree を初期化し、プロバイダーを選び、デフォルトの `main` gc-branch をオンボードし、必要なコンテキストを resolve で引き、作業に応じて新しい gc-branch を作り、リポジトリを適切な gc-branch に結び付け、後からの永続的な変更はガイド付き更新で反映していきます。
+標準的な `gctree` の流れはこうです。gc-tree を初期化し、プロバイダーを選び、デフォルトの `main` gc-branch をオンボードし、必要なコンテキストを resolve で引き、作業に応じて新しい gc-branch を作り、リポジトリを適切な gc-branch に結び付け、後からの永続的なコンテキスト変更はガイド付き更新で反映し、CLI とインストール済みプロバイダー統合を更新したいときは `gctree update` を実行します。
 
 ## 標準ワークフロー
 
@@ -19,7 +19,8 @@
 9. `gctree checkout` で gc-branch を作成または切り替える
 10. `gctree onboard` は空の gc-branch に対してだけ使う
 11. repo scope を設定して gc-branch が本来のリポジトリにだけ作用するようにする
-12. 後からの永続的な変更には `gctree update-global-context` を使う
+12. 後からの永続的なコンテキスト変更には `gctree update-global-context` を使う
+13. gc-tree 自体とインストール済みプロバイダーを更新するには `gctree update` を使う
 
 ## 主要コマンド
 
@@ -41,6 +42,7 @@
 | `gctree update-global-context` | アクティブな gc-branch に対するガイド付き永続的更新を開始します。 |
 | `gctree update-gc` / `gctree ugc` | `gctree update-global-context` の別名です。 |
 | `gctree scaffold --host <codex\|claude-code>` | 1つのリポジトリやワークスペースにローカルなプロバイダー override をインストールします。 |
+| `gctree update` | gctree を最新 npm バージョンに更新し、以前インストールしたすべてのプロバイダーを再スキャフォールドします。 |
 | `gctree uninstall --yes` | `~/.gctree` とグローバルな gctree 有効化を削除します。 |
 
 ## resolve が返す内容
@@ -51,40 +53,22 @@
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "query": "auth token rotation policy",
-  "status": "matched",
-  "matches": [
-    {
-      "id": "auth",
-      "title": "Auth & Session Conventions",
-      "path": "docs/auth.md",
-      "score": 4,
-      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
-      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
-      "commands": {
-        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
-        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
-      }
-    }
-  ]
-}
+```
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
+[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"
 ```
 
 推奨フローは次のとおりです。
 
 1. `resolve` → compact index
-2. `related` → その match の周辺にある supporting docs
-3. `show-doc` → 必要なときだけフル markdown
+2. `show-doc` → 必要なときだけフル markdown
 
 Graceful degradation も明示的です。
 
-- 空の gc-branch → `status: "empty_branch"`
-- 除外された repo → `status: "excluded"`
-- ヒットなし → `status: "no_match"`
-- 文書 ID が見つからない → `status: "doc_not_found"`
+- 空の gc-branch → gc-branch が空であることを示すプレーンテキストメッセージ
+- 除外された repo → そのリポジトリが除外されていることを示すプレーンテキストメッセージ
+- ヒットなし → 一致がなかったことを示すプレーンテキストメッセージ
 
 ## repo scope の設定例
 
@@ -128,7 +112,7 @@ gctree init
 ## 複数ブランチを使う例
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -151,13 +135,21 @@ gctree ugc
 1. まずそのリポジトリを gc-branch にマップする
 2. その後 `update-global-context` を実行して、そのリポジトリが何を担い、なぜ重要なのかという永続的な知識を追加する
 
+## ツール更新の例
+
+```bash
+gctree update
+```
+
+`@handsupmin/gc-tree` を最新の npm バージョンに更新し、`gctree init` または `gctree scaffold` でインストール済みのすべてのプロバイダーを再スキャフォールドします。新しいフック、コマンド、スキル、統合スニペットが配布されたときに使うメンテナンスコマンドです。
+
 ## 統合パターン
 
 ### Codex CLI / Claude Code CLI
 
 `gctree init` はグローバルなプロバイダーフック面をインストールします。`gctree scaffold` は特定のリポジトリに独自の markdown スニペットやローカルなコマンド面が必要なときに、ターゲットディレクトリへローカル override をインストールします。
 
-UserPromptSubmit フックが注入するのは compact な pre-task context だけです。found/no-match 状態と、マッチしたドキュメントのタイトル/ID を示します。要約や長い excerpt はデフォルトではインラインしません。必要な場合は `gctree resolve --id <id>` で全文を開きます。
+UserPromptSubmit フックは、各プロンプト前にマッチしたドキュメントの要約をコンテキストに直接注入します — AI がタイトルだけでなく実際のパターンとコマンドを見られるようにするためです。要約が短すぎるか一般的すぎる場合、フックはドキュメント本文の excerpt にフォールバックします。全文はいつでも `gctree resolve --id <id>` でオンデマンドに取得できます。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.ko.md

@@ -4,7 +4,7 @@
 
 ## 요약
 
-표준 `gctree` 워크플로우는 다음과 같습니다: gc-tree 초기화, 프로바이더 선택, 기본 `main` gc-branch 온보딩, 필요한 컨텍스트 resolve, 작업별로 새 gc-branch 생성, 저장소를 올바른 gc-branch에 매핑, 이후 지속 변경 시 안내된 업데이트 사용.
+표준 `gctree` 워크플로우는 다음과 같습니다: gc-tree 초기화, 프로바이더 선택, 기본 `main` gc-branch 온보딩, 필요한 컨텍스트 resolve, 작업별로 새 gc-branch 생성, 저장소를 올바른 gc-branch에 매핑, 이후 지속 컨텍스트 변경 시 안내된 업데이트 사용, CLI와 설치된 프로바이더 통합을 새로고침할 때 `gctree update` 실행.
 
 ## 표준 워크플로우
 
@@ -19,7 +19,8 @@
 9. `gctree checkout`으로 gc-branch 생성 또는 전환
 10. 빈 gc-branch에만 `gctree onboard` 실행
 11. 저장소 범위 매핑으로 gc-branch가 해당하는 곳에만 적용되도록 설정
-12. 이후 지속 변경에는 `gctree update-global-context` 사용
+12. 이후 지속 컨텍스트 변경에는 `gctree update-global-context` 사용
+13. gc-tree 자체와 설치된 프로바이더를 새로고침하려면 `gctree update` 사용
 
 ## 핵심 명령어
 
@@ -41,6 +42,7 @@
 | `gctree update-global-context` | 활성 gc-branch의 안내된 지속 업데이트 실행. |
 | `gctree update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭. |
 | `gctree scaffold --host <codex\|claude-code>` | 특정 저장소나 워크스페이스에 로컬 프로바이더 override 설치. |
+| `gctree update` | gctree를 최신 npm 버전으로 업데이트하고 이전에 설치된 모든 프로바이더를 재스캐폴드. |
 | `gctree uninstall --yes` | `~/.gctree`와 전역 gctree 활성화를 제거. |
 
 ## resolve가 반환하는 것
@@ -51,40 +53,22 @@
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "query": "auth token rotation policy",
-  "status": "matched",
-  "matches": [
-    {
-      "id": "auth",
-      "title": "Auth & Session Conventions",
-      "path": "docs/auth.md",
-      "score": 4,
-      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
-      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
-      "commands": {
-        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
-        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
-      }
-    }
-  ]
-}
+```
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
+[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"
 ```
 
 권장 흐름은 다음과 같습니다:
 
 1. `resolve` → compact index
-2. `related` → 특정 match 주변 supporting docs
-3. `show-doc` → 필요할 때만 전체 markdown
+2. `show-doc` → 필요할 때만 전체 markdown
 
 Graceful degradation도 명시적입니다:
 
-- 빈 gc-branch → `status: "empty_branch"`
-- 제외된 repo → `status: "excluded"`
-- 결과 없음 → `status: "no_match"`
-- 문서 ID 없음 → `status: "doc_not_found"`
+- 빈 gc-branch → gc-branch가 비어 있다는 일반 텍스트 메시지
+- 제외된 repo → 해당 repo가 제외되어 있다는 일반 텍스트 메시지
+- 결과 없음 → 매칭 결과가 없다는 일반 텍스트 메시지
 
 ## 저장소 범위 설정 예시 흐름
 
@@ -128,7 +112,7 @@ gctree init
 ## 다중 브랜치 예시 흐름
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -151,13 +135,21 @@ gctree ugc
 1. 해당 저장소를 gc-branch에 매핑
 2. `update-global-context`를 실행하여 해당 저장소가 무엇을 하고 왜 중요한지에 대한 지속 지식 추가
 
+## 도구 업데이트 예시 흐름
+
+```bash
+gctree update
+```
+
+`@handsupmin/gc-tree`를 최신 npm 버전으로 업데이트하고, `gctree init` 또는 `gctree scaffold`로 이미 설치한 모든 프로바이더를 다시 스캐폴드합니다. 새 훅, 명령, 스킬, 통합 스니펫이 배포됐을 때 실행하는 유지보수 명령입니다.
+
 ## 통합 패턴
 
 ### Codex CLI / Claude Code CLI
 
 `gctree init`은 전역 프로바이더 훅 표면을 설치합니다. `gctree scaffold`는 특정 저장소에 자체 markdown 스니펫이나 로컬 명령 표면이 필요할 때 대상 디렉토리에 로컬 override를 설치합니다.
 
-UserPromptSubmit 훅은 compact pre-task context만 주입합니다: 찾음/no-match 상태와 매칭된 문서 제목/ID입니다. 기본적으로 요약이나 긴 excerpt를 인라인하지 않으며, 필요할 때 `gctree resolve --id <id>`로 전체 문서를 엽니다.
+UserPromptSubmit 훅은 매 프롬프트 전에 매칭된 문서 요약을 컨텍스트에 직접 주입합니다 — AI가 제목만이 아니라 실제 패턴과 명령을 볼 수 있도록. 요약이 짧거나 일반적인 경우, 훅은 문서 본문에서 excerpt로 대체합니다. 전체 문서는 언제든 `gctree resolve --id <id>`로 필요할 때 확인할 수 있습니다.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.md

@@ -4,7 +4,7 @@
 
 ## Summary
 
-A standard `gctree` workflow looks like this: initialize gc-tree, choose a provider, onboard the default `main` gc-branch, resolve the context you need, create new gc-branches when work deserves its own lane, map repositories to the right gc-branches, and use guided updates for durable changes later.
+A standard `gctree` workflow looks like this: initialize gc-tree, choose a provider, onboard the default `main` gc-branch, resolve the context you need, create new gc-branches when work deserves its own lane, map repositories to the right gc-branches, use guided updates for durable context changes, and run `gctree update` when you want the CLI plus installed provider integrations refreshed.
 
 ## Standard workflow
 
@@ -19,7 +19,8 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 9. create or switch gc-branches with `gctree checkout`
 10. run `gctree onboard` only for an empty gc-branch
 11. use repo scope mapping so a gc-branch only applies where it belongs
-12. use `gctree update-global-context` for durable changes later
+12. use `gctree update-global-context` for durable context changes later
+13. use `gctree update` to update gc-tree itself and re-scaffold installed providers
 
 ## Core commands
 
@@ -41,6 +42,7 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 | `gctree update-global-context` | Launch a guided durable update for the active gc-branch. |
 | `gctree update-gc` / `gctree ugc` | Aliases for `gctree update-global-context`. |
 | `gctree scaffold --host <codex\|claude-code>` | Install a local provider-facing override in one repository or workspace. |
+| `gctree update` | Update gctree to the latest npm version and re-scaffold all previously installed providers. |
 | `gctree uninstall --yes` | Remove `~/.gctree` and the global gctree activation for the configured providers. |
 
 ## What resolve returns
@@ -51,40 +53,22 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "query": "auth token rotation policy",
-  "status": "matched",
-  "matches": [
-    {
-      "id": "auth",
-      "title": "Auth & Session Conventions",
-      "path": "docs/auth.md",
-      "score": 4,
-      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
-      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
-      "commands": {
-        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
-        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
-      }
-    }
-  ]
-}
+```
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
+[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"
 ```
 
 The intended flow is:
 
-1. `resolve` → compact index
-2. `related` → supporting docs around one match
-3. `show-doc` → full markdown only when needed
+1. `resolve` → compact text output with summary injected
+2. `show-doc` → full markdown only when needed
 
-Graceful degradation is explicit:
+Graceful degradation is explicit — each case returns a plain text message:
 
-- empty gc-branch → `status: "empty_branch"`
-- excluded repo → `status: "excluded"`
-- no hits → `status: "no_match"`
-- missing doc id → `status: "doc_not_found"`
+- empty gc-branch → `[gc-tree] No context found — gc-branch is empty.`
+- excluded repo → `[gc-tree] Repo "..." is excluded from gc-branch "...".`
+- no hits → `[gc-tree] No matching documents found.`
 
 ## Example repo-scope flow
 
@@ -128,7 +112,7 @@ Then:
 ## Example multi-branch flow
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -151,13 +135,21 @@ If a newly relevant repo should also become part of the durable context, the nat
 1. map that repo to the gc-branch
 2. then run `update-global-context` to add durable knowledge about what that repo does and why it matters
 
+## Example tool update flow
+
+```bash
+gctree update
+```
+
+This updates `@handsupmin/gc-tree` to the latest npm version and re-scaffolds every provider already installed through `gctree init` or `gctree scaffold`. It is the maintenance command to run when new provider hooks, commands, skills, or integration snippets ship.
+
 ## Integration patterns
 
 ### Codex CLI / Claude Code CLI
 
 `gctree init` installs the provider-facing hook surface globally. `gctree scaffold` installs a local override into one target directory when a specific repository needs its own markdown snippets or local command surface.
 
-The UserPromptSubmit hook injects compact pre-task context only: found/no-match state plus matched document titles and IDs. It does not inline summaries or long excerpts by default; open full documents with `gctree resolve --id <id>` when needed.
+The UserPromptSubmit hook injects matched document summaries directly into context before each prompt — so the AI sees actual patterns and commands, not just titles. When a summary is short or generic, the hook falls back to an excerpt from the document body. Full documents are always available on demand with `gctree resolve --id <id>`.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo