@kodevibe/harness 0.11.0 → 0.11.1

package/README.ko.md

@@ -64,6 +64,56 @@ npx @kodevibe/harness init --ide antigravity
 
 ---
 
+## 기존 설치 업그레이드
+
+이미 kode:harness가 설치된 프로젝트에서 `init`을 다시 실행하면 project state와 agent memory는 보존하고 IDE 설정 파일만 최신 버전으로 갱신합니다. 기본 동작은 데이터 손실 없이 진행되며, 덮어쓴 IDE 설정은 자동 백업됩니다.
+
+| 범주 | 기본 동작 | 세부 내용 |
+|------|----------|----------|
+| **State files** | 보존 | `project-state.md`, `failure-patterns.md`, `dependency-map.md`, `features.md`, `project-brief.md` |
+| **Agent memory** | 보존 | solo 모드에서는 `docs/agent-memory/`, team 모드에서는 `.harness/agent-memory/` |
+| **IDE config** | 매 실행 갱신 | `.github/copilot-instructions.md`, `CLAUDE.md`, `.claude/`, `.cursor/`, `.codex/`, `.windsurf/`, `.agents/`, `AGENTS.md` |
+| **백업 위치** | 자동 생성 | 기존 IDE 설정 → `.harness/init-backups/<ISO-timestamp>/...` |
+
+```bash
+npx @kodevibe/harness init --ide <vscode|claude|cursor|codex|windsurf|antigravity> --batch
+```
+
+`--overwrite`는 state files까지 초기화하므로, 손상된 상태 파일을 재생성해야 할 때만 사용하세요.
+
+---
+
+## 안전 제거
+
+`init`은 `.harness/install-manifest.json`에 생성 파일, hash, IDE 대상, 모드, 백업 경로를 기록합니다. `uninstall`은 이 manifest를 사용해 kode:harness가 관리한 파일만 제거합니다.
+
+```bash
+# 먼저 미리보기. 파일은 변경되지 않습니다.
+npx @kodevibe/harness uninstall --ide claude --dry-run
+
+# 적용. state files와 agent memory는 기본 보존됩니다.
+npx @kodevibe/harness uninstall --ide claude --yes
+```
+
+안전 규칙:
+
+- `docs/project-state.md`, `docs/project-brief.md`, `docs/features.md`, `docs/dependency-map.md`, `docs/failure-patterns.md`, agent memory는 기본 보존됩니다.
+- 기존 `CLAUDE.md` 또는 `AGENTS.md`를 `init`이 덮어쓴 경우 `.harness/init-backups/<timestamp>/...`에서 복원합니다.
+- 설치 후 수정된 managed file은 `--force` 없이는 건드리지 않고 skip합니다.
+- `AGENTS.md`, `.agents/skills/*`처럼 여러 IDE가 공유하는 경로는 다른 active install이 소유 중이면 보존하거나 남은 owner의 내용으로 되돌립니다.
+- 삭제/복원 전 파일은 `.harness/uninstall-backups/<timestamp>/...`에 백업됩니다.
+
+```bash
+npx @kodevibe/harness uninstall --all --dry-run       # 감지된 전체 IDE 제거 계획 확인
+npx @kodevibe/harness uninstall --ide vscode --yes    # 특정 IDE 표면만 제거
+npx @kodevibe/harness uninstall --ide vscode --yes --purge-state
+npx @kodevibe/harness uninstall --all --yes --purge-state --purge-backups
+```
+
+`--purge-state`는 생성된 state files까지 의도적으로 삭제할 때만 사용하세요. `--purge-state --purge-backups`를 함께 쓰면 active install이 모두 제거된 뒤 `.harness/install-manifest.json`까지 삭제되어 kode:harness 흔적을 남기지 않습니다.
+
+---
+
 ## 문제: 컨텍스트 부패 (Context Rot)
 
 AI 코딩 에이전트는 매 세션 제로에서 시작합니다. 세션 3에서는 세션 1의 아키텍처 결정을 잊고, 세션 10에서는 이미 확정된 사항을 다시 논의하며 자신의 이전 작업과 모순됩니다.
@@ -101,9 +151,10 @@ kode:harness는 세 가지 메커니즘으로 해결합니다:
 | ✅ **Evidence-Gated Progress Board** | 테스트/스모크 증거가 있어야 Planned → Proof Pending → Proven으로 진행 |
 | 📒 **Proof Ledger** | review/wrap-up 출력에 명령어, 결과, 관찰 증거를 짧게 기록 |
 | 🔒 **Proof-First Enforcement** | pm/lead/reviewer/state-check가 모호한 계획, 증거 없는 완료, 실패한 테스트, 누락된 proof 기록을 막음 |
+| 🗂️ **Project Docs Bridge** | 원본과 visibility 경계를 보존하며 로컬 docs hub 인덱스 생성 |
 | 📝 **상태 영속성** | LLM 세션 간 프로젝트 지식을 유지하는 5개 마크다운 파일 |
 | 🔄 **5개 파이프라인** | 🟢 신규 → 🔵 계속 → 🔴 버그 수정 → 🟡 방향 전환 → 🟣 Crew 기반 |
-| 🛠️ **11개 스킬** | 단계별 절차: setup, debug, breakdown, review, pivot, state-check 등 |
+| 🛠️ **12개 스킬** | 단계별 절차: setup, debug, breakdown, docs-bridge, review, pivot, state-check 등 |
 | 🤖 **4개 에이전트** | 역할 기반 페르소나: pm, reviewer, lead, architect |
 | ⚠️ **실패 패턴** | 세션 간 같은 실수를 방지하는 프로젝트별 실패 기록 |
 | 📋 **Decision Log** | 결정의 이유를 기록해 LLM이 확정된 사항을 재논의하지 않도록 방지 |
@@ -116,6 +167,7 @@ kode:harness는 세 가지 메커니즘으로 해결합니다:
 ```bash
 npx @kodevibe/harness doctor    # 파일 설치 상태 확인
 npx @kodevibe/harness validate  # state 파일에 실제 내용 확인
+npx @kodevibe/harness uninstall --dry-run --ide vscode  # 안전 제거 미리보기
 ```
 
 ---
@@ -155,6 +207,7 @@ npx @kodevibe/harness validate  # state 파일에 실제 내용 확인
 | **debug** | 4단계 체계적 디버깅 (증거 → 범위축소 → 수정 → 검증) |
 | **check-impact** | 공유 모듈 수정 전 영향 범위 평가 |
 | **breakdown** | 기능을 의존성 순서대로 구현 태스크로 분해 |
+| **docs-bridge** | 원본 문서를 보존하면서 repository docs를 wiki/docs hub와 연결할 수 있는 로컬 인덱스 생성 |
 | **pr-review** | PR 코드 리뷰: 품질, 보안, 방향 정렬 확인 |
 | **release** | 배포 전 검증 체크리스트 (테스트, state 파일, 보안, 버전) |
 
@@ -177,6 +230,8 @@ npx @kodevibe/harness validate  # state 파일에 실제 내용 확인
 | **dependency-map.md** | 영향 분석을 위한 모듈 의존성 그래프 ("어떻게"에 대한 기록) |
 | **failure-patterns.md** | 반복 실수를 방지하는 프로젝트별 실패 패턴 ("주의사항") |
 
+`project-brief.md`에는 필요 시 **Project Docs Hub Index**를 함께 둘 수 있습니다. 로컬 문서를 wiki, Confluence, Obsidian vault, 사내 문서 허브에서 찾을 수 있게 연결할 때 사용합니다. tracked index에는 repository-relative source와 정제된 hub alias만 두고, PC별 resolver 정보는 ignored `.harness/docs-bridge.local.*` 파일에 둡니다.
+
 ---
 
 ## 작동 방식
@@ -298,6 +353,16 @@ Bootstrap이 `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/`에서 crew
 
 원본 crew 문서는 **절대 수정되지 않습니다**. 인덱스와 트래커만 생성됩니다.
 
+### Project Docs Bridge
+
+프로젝트 문서가 README, `docs/`, ADR, runbook, API spec, 기획 산출물로 흩어져 있다면 `docs-bridge`를 실행합니다:
+
+```bash
+> "이 프로젝트 문서를 wiki/docs hub와 연결해줘"
+```
+
+`project-brief.md`에 Project Docs Hub Index를 추가해 각 로컬 원본, 역할, 정제된 hub 대상, sync 방향, visibility, 상태, 검토일을 기록합니다. 원본은 repository에 남깁니다. 외부 hub에 요약이나 링크를 쓰는 작업은 사용자가 명시적으로 요청하고 visibility boundary를 확인한 뒤에만 진행합니다.
+
 ### 다른 프레임워크와의 비교
 
 | | BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | **kode:harness** |
@@ -315,7 +380,7 @@ Bootstrap이 `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/`에서 crew
 
 ## 로드맵
 
-kode:harness는 현재 **v0.11.0** — Common Mode의 proof-first 동작을 강제합니다. Proof Plan은 정확한 명령/체크여야 하고, Story 완료는 증거 없이는 막히며, reviewer는 proof 실패/누락 시 멈추고, state-check는 Proof Ledger 누락을 점검합니다.
+kode:harness는 현재 **v0.11.1** — manifest 기반 안전 제거를 추가해 설치 흔적을 미리보기, 보존, 복원, purge 흐름으로 관리합니다. Common Mode의 proof-first 동작도 계속 강제합니다.
 
 | 단계 | 버전 | 상태 | 초점 |
 |------|------|------|------|
@@ -329,7 +394,9 @@ kode:harness는 현재 **v0.11.0** — Common Mode의 proof-first 동작을 강
 | **Consistency & Budget** | v0.9.5 | ✅ 완료 | reviewer.md Iron Laws stale 수정, 디스패처 동기화, 경량성 예산 재교정(40K/1500/2500) 및 근거 기록 |
 | **Drift Guard & Positioning** | v0.9.7 | ✅ 완료 | `harness/`↔`.github/` drift 가드, reviewer working-proof 게이트, kode:vibe 위치 안내, IDE 선택 가이드, project-brief 예시 |
 | **Confidence Loop** | v0.10.0 | ✅ 완료 | Goal Card, Quiet Navigator, Evidence-Gated Progress Board, Proof Ledger, QA/content 회귀 테스트 |
-| **Proof-First Enforcement** | v0.11.0 | ✅ 현재 | Mandatory Proof Plan, lead proof blocker, reviewer proof blocker, state-check Proof Ledger coverage |
+| **Proof-First Enforcement** | v0.11.0 | ✅ 완료 | Mandatory Proof Plan, lead proof blocker, reviewer proof blocker, state-check Proof Ledger coverage |
+| **Uninstall Safety** | v0.11.1 | ✅ 현재 | Manifest 기반 uninstall, state 기본 보존, shared owner 복원, purge cleanup |
+| **Docs Bridge** | v0.11.1 | 🧪 Experimental | Project Docs Hub Index, docs-bridge 스킬, visibility 경계를 가진 로컬 docs hub 인덱스 |
 | **Safety & Branding** | v0.9.6 | ✅ 완료 | init overwrite 백업, 배포 파일 pm 네이밍 정리, LICENSE 브랜딩 정리 |
 | **Validation** | v1.0 | 🔜 다음 | 실사용 검증, 사용자 피드백 수집 |
 

package/README.md

@@ -64,6 +64,68 @@ npx @kodevibe/harness init --ide antigravity
 
 ---
 
+## Upgrade an existing install
+
+If you already have kode:harness installed, running `init` again refreshes IDE configuration files while preserving project state and agent memory. **No data loss by default** — only IDE config files are updated, and previous versions are automatically backed up.
+
+| Category | Behavior (default) | Details |
+|----------|-------------------|---------|
+| **State files** (preserved) | Not overwritten | `project-state.md`, `failure-patterns.md`, `dependency-map.md`, `features.md`, `project-brief.md` |
+| **Agent memory** (preserved) | Not overwritten | `agent-memory/{architect,lead,pm,reviewer}.md` (under `docs/` in solo mode or `.harness/` in team mode) |
+| **IDE config** (refreshed) | Overwritten each run | `.github/copilot-instructions.md`, `CLAUDE.md`, `.claude/`, `.cursor/`, `.codex/`, `.windsurf/`, `.agents/`, `AGENTS.md` |
+| **Backup location** | Automatic (v0.9.6+) | Previous IDE config files → `.harness/init-backups/<ISO-timestamp>/...` |
+
+### Safe re-init (recommended for version upgrades)
+
+```bash
+npx @kodevibe/harness init --ide <vscode|claude|cursor|codex|windsurf|antigravity> --batch
+```
+
+State files and agent memory remain intact.
+
+### Force overwrite (caution)
+
+```bash
+npx @kodevibe/harness init --ide vscode --batch --overwrite
+```
+
+⚠️ `--overwrite` will erase your current `project-state.md`, `failure-patterns.md`, and agent memory files. Recover the previous versions from `.harness/init-backups/<ISO-timestamp>/` if needed.
+
+---
+
+## Uninstall Safely
+
+Every `init` now writes `.harness/install-manifest.json`, which records the generated files, hashes, IDE target, mode, and backup paths. `uninstall` uses that manifest to remove only kode:harness-managed files.
+
+```bash
+# Preview first. No files are changed.
+npx @kodevibe/harness uninstall --ide claude --dry-run
+
+# Apply. State files and agent memory are preserved by default.
+npx @kodevibe/harness uninstall --ide claude --yes
+```
+
+Safety rules:
+
+- `docs/project-state.md`, `docs/project-brief.md`, `docs/features.md`, `docs/dependency-map.md`, `docs/failure-patterns.md`, and agent memory are kept by default.
+- Existing root files such as `CLAUDE.md` or `AGENTS.md` are restored from `.harness/init-backups/<timestamp>/...` when `init` overwrote them.
+- Files modified after install are skipped unless `--force` is used.
+- Shared cross-tool paths such as `AGENTS.md` and `.agents/skills/*` are kept while another active IDE install still owns them.
+- Deleted/restored files are copied to `.harness/uninstall-backups/<timestamp>/...` before changes are applied.
+
+Additional options:
+
+```bash
+npx @kodevibe/harness uninstall --all --dry-run       # preview all detected IDE installs
+npx @kodevibe/harness uninstall --ide vscode --yes    # remove one IDE surface
+npx @kodevibe/harness uninstall --ide vscode --yes --purge-state
+npx @kodevibe/harness uninstall --all --yes --purge-state --purge-backups
+```
+
+Use `--purge-state` only when you intentionally want to delete generated state files too. Backup directories are kept unless `--purge-backups` is explicitly provided. Combining `--purge-state --purge-backups` removes `.harness/install-manifest.json` too once no active installs remain, leaving no kode:harness state behind.
+
+---
+
 ## The Problem: Context Rot
 
 Your AI coding agent starts every session from zero. By session 3, it's forgotten the architecture decisions from session 1. By session 10, it's re-debating settled choices and contradicting its own earlier work.
@@ -101,9 +163,10 @@ kode:harness solves this with three mechanisms:
 | ✅ **Evidence-Gated Progress Board** | Stories move from Planned → Proof Pending → Proven only when tests or smoke proof exist |
 | 📒 **Proof Ledger** | Review and wrap-up outputs record compact proof: command, result, and observation |
 | 🔒 **Proof-First Enforcement** | pm/lead/reviewer/state-check block vague plans, unproven completion, failing tests, and missing proof records |
+| 🗂️ **Project Docs Bridge** | Creates a local docs hub index while preserving originals and visibility boundaries |
 | 📝 **State Persistence** | 5 markdown files that persist project knowledge across LLM sessions |
 | 🔄 **5 Pipelines** | 🟢 New Dev → 🔵 Continue → 🔴 Bug Fix → 🟡 Direction Change → 🟣 Crew-Driven |
-| 🛠️ **11 Skills** | Step-by-step procedures: setup, debug, breakdown, review, pivot, state-check, and more |
+| 🛠️ **12 Skills** | Step-by-step procedures: setup, debug, breakdown, docs-bridge, review, pivot, state-check, and more |
 | 🤖 **4 Agents** | Role-based personas: pm, reviewer, lead, architect |
 | ⚠️ **Failure Patterns** | Project-specific failure log that prevents repeat mistakes across sessions |
 | 📋 **Decision Log** | Records why decisions were made so LLMs don't re-debate settled choices |
@@ -116,6 +179,7 @@ kode:harness solves this with three mechanisms:
 ```bash
 npx @kodevibe/harness doctor    # verify files are installed
 npx @kodevibe/harness validate  # verify state files have real content
+npx @kodevibe/harness uninstall --dry-run --ide vscode  # preview safe removal
 ```
 
 ## Supported IDEs
@@ -147,6 +211,7 @@ All IDEs also get state files (`project-state.md`, `project-brief.md`, `features
 - **debug** — 4-phase systematic debugging (evidence → scope → fix → verify)
 - **check-impact** — Assess change blast radius before modifying shared modules
 - **breakdown** — Decompose features into dependency-ordered implementation tasks
+- **docs-bridge** — Create a local index that can connect repository docs to a wiki/docs hub while preserving originals and visibility boundaries
 - **pr-review** — Review incoming Pull Requests for quality, security, and direction alignment
 - **release** — Pre-release validation checklist (tests, state files, security, versioning)
 
@@ -163,6 +228,8 @@ All IDEs also get state files (`project-state.md`, `project-brief.md`, `features
 - **dependency-map.md** — Module dependency graph for impact analysis (the "how")
 - **failure-patterns.md** — Project-specific failure patterns that prevent repeat mistakes (the "watch out")
 
+`project-brief.md` can also carry a **Project Docs Hub Index** when you want local docs discoverable from a wiki, Confluence space, Obsidian vault, or other documentation hub. The tracked index stores repo-relative sources and sanitized hub aliases only; machine-specific resolver details belong in ignored `.harness/docs-bridge.local.*` files.
+
 ## How It Works
 
 ### 1. Bootstrap (once)
@@ -274,6 +341,16 @@ Bootstrap auto-detects crew artifacts in `docs/crew/`, `docs/PM/`, `docs/Analyst
 
 Original crew documents are **never modified**. Only the index and tracker are created.
 
+### Project Docs Bridge
+
+When a project already has useful docs spread across README files, `docs/`, ADRs, runbooks, API specs, or planning artifacts, run `docs-bridge`:
+
+```bash
+> "connect this project's docs to our wiki/docs hub"
+```
+
+It adds a Project Docs Hub Index to `project-brief.md` with each local source, role, sanitized hub target, sync direction, visibility, status, and review date. The repository keeps the originals. External hub summaries or links are written only when the user explicitly asks and visibility boundaries are confirmed.
+
 ### How It Compares
 
 | | BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | kode:harness |
@@ -289,7 +366,7 @@ Original crew documents are **never modified**. Only the index and tracker are c
 
 ## Roadmap
 
-kode:harness is at **v0.11.0** — makes Common Mode proof-first behavior enforceable: Proof Plans need exact commands/checklists, Story completion is blocked without evidence, reviewer must stop on missing/failing proof, and state-check audits Proof Ledger coverage.
+kode:harness is at **v0.11.1** — adds manifest-based safe uninstall so generated IDE files can be previewed, preserved, restored, or purged intentionally. Common Mode proof-first behavior remains enforceable.
 
 | Phase | Version | Status | Focus |
 |---|---|---|---|
@@ -303,7 +380,9 @@ kode:harness is at **v0.11.0** — makes Common Mode proof-first behavior enforc
 | **Consistency & Budget** | v0.9.5 | ✅ Done | Iron Laws stale-copy fix (reviewer.md), dispatcher sync (core-rules.md ↔ copilot-instructions.md), lightness budgets recalibrated (40K/1500/2500) with rationale |
 | **Drift Guard & Positioning** | v0.9.7 | ✅ Done | `harness/`↔`.github/` drift detector, reviewer working-proof gate, kode:vibe positioning, IDE selection guide, project-brief example |
 | **Confidence Loop** | v0.10.0 | ✅ Done | Goal Card, Quiet Navigator, Evidence-Gated Progress Board, Proof Ledger, QA/content regression tests |
-| **Proof-First Enforcement** | v0.11.0 | ✅ Current | Mandatory Proof Plan, lead proof blockers, reviewer proof blockers, state-check Proof Ledger coverage |
+| **Proof-First Enforcement** | v0.11.0 | ✅ Complete | Mandatory Proof Plan, lead proof blockers, reviewer proof blockers, state-check Proof Ledger coverage |
+| **Uninstall Safety** | v0.11.1 | ✅ Current | Manifest-based uninstall, default state preservation, shared owner restore, purge cleanup |
+| **Docs Bridge** | v0.11.1 | 🧪 Experimental | Project Docs Hub Index, docs-bridge skill, local docs hub index with visibility boundaries |
 | **Safety & Branding** | v0.9.6 | ✅ Done | init overwrite backups, shipped pm naming cleanup, LICENSE branding cleanup |
 | **Validation** | v1.0 | 🔜 Next | Real-world project adoption, user feedback collection |
 

package/harness/core-rules.md

@@ -77,6 +77,7 @@ When the user provides a feature request or development goal in their prompt:
    - Bug report or error → Start 🔴 Pipeline from `debug`
    - Structural/design change → Run `architect` first, then `pm`
    - Direction change → Start 🟡 Pipeline from `pivot`
+   - Docs/wiki request → Run `docs-bridge`
 <!-- CREW_MODE_START -->
    - Crew artifacts detected (`docs/crew/` exists, `docs/PM/`+`docs/Analyst/`+`docs/ARB/` exist, or user provided design docs) → Start 🟣 Pipeline from `setup`
 <!-- CREW_MODE_END -->
@@ -128,6 +129,7 @@ When a skill or agent reports STATUS: DONE, use the same block and point to the
 - docs/dependency-map.md — module dependency graph
 - docs/features.md — feature registry
 - docs/project-brief.md — project vision, goals, and non-goals
+   - Optional: `## Project Docs Hub Index` maps docs to hubs
 
 ## Iron Laws
 

package/harness/project-brief.md

@@ -52,6 +52,24 @@ _Example (kode:harness)_: Developers and small teams (1–10) using AI coding as
    - Manual proof: create item → refresh → item persists
 -->
 
+## Project Docs Hub Index
+
+<!-- Optional — maintained by the `docs-bridge` skill when the project needs to
+   connect local documentation to a wiki/docs hub without copying whole documents.
+   Keep originals in place; index repo-relative paths, roles, sync intent,
+   sanitized hub aliases, and visibility boundaries here. Machine-specific
+   resolver details belong in ignored `.harness/docs-bridge.local.*` files.
+
+   | Local Source | Role | Hub Target | Sync Direction | Visibility | Status | Last Reviewed |
+   |--------------|------|------------|----------------|------------|--------|---------------|
+   | README.md | source | local-only | local-source -> hub-summary | public | active | YYYY-MM-DD |
+
+   Role: source, planning-artifact, decision-record, reference, runbook, state, generated
+   Sync Direction: local-source -> hub-summary, hub-reference -> local-index, bidirectional-index-only, local-only
+   Visibility: public, team, company-confidential, personal-private, do-not-share
+   Status: active, proposed, stale, archived
+-->
+
 <!-- CREW_MODE_START -->
 ## Crew Artifact Index
 

package/harness/skills/docs-bridge.md

@@ -0,0 +1,161 @@
+# Docs Bridge
+
+## Purpose
+
+Connect project-local documentation to a wiki, knowledge base, or docs hub through a small, safe index in `docs/project-brief.md`.
+This keeps the repository as the source of truth for project-internal docs while letting a central hub discover, summarize, and link them safely.
+
+## Invoked By
+
+- **User** — "connect this project to my wiki", "문서를 위키처럼 정리해줘", "sync docs to Confluence", "Obsidian docs hub"
+- **setup** — after state files are filled, when the user asked for documentation organization or a central docs hub
+- **wrap-up** — when documentation changed and `docs/project-brief.md` already has a Project Docs Hub Index
+- **state-check** — validates the index shape and local path coverage
+
+## When to Apply
+
+- A project has several documentation surfaces: README, `docs/`, ADRs, runbooks, API specs, planning artifacts, generated reports
+- The user wants a central wiki/docs hub to know which project docs exist without copying every document into the hub
+- The user wants LLMs to manage internal docs, source cards, meeting notes, or project cards across sessions
+- Before promoting a local document into an external wiki, Confluence space, Obsidian vault, or team knowledge base
+
+## Boundaries
+
+- Preserve original documents unless the user explicitly asks to edit them.
+- Do not copy entire READMEs, specs, transcripts, or external pages into the hub. Summarize and link.
+- Treat the hub as a reference layer: path/URL, role, key constraints, status, and visibility are enough.
+- Respect visibility. Private or confidential rows need explicit user confirmation before any external target is written.
+- Do not commit company-private URLs or personal vault paths into OSS templates. Those belong in the user's local project state.
+- Keep tracked index rows sanitized: use `local-only`, `pending`, or a logical hub alias/note title, not machine-specific absolute paths.
+- Store local resolver details such as Obsidian vault paths, personal Wiki names, page IDs, or sync scripts only in ignored local files such as `.harness/docs-bridge.local.json`.
+- Keep uncertain relationships as `proposed`, `needs verification`, or `review required`.
+
+## Procedure
+
+### Phase 1: Discover Documentation Surfaces
+
+Read only enough to classify documents. Prefer headers, tables of contents, and first sections before reading full files.
+
+Common candidates:
+- Root docs: `README*`, `CHANGELOG*`, `CONTRIBUTING*`, `SECURITY*`, `LICENSE`
+- Project docs: `docs/`, `adr/`, `architecture/`, `design/`, `runbooks/`, `playbooks/`, `operations/`
+- API and contract docs: `openapi*`, `swagger*`, `schema*`, `proto/`, `graphql/`
+- AI/planning docs: planning artifact directories, role-based analysis folders, meeting notes, research notes
+- Existing state: `docs/project-brief.md`, `docs/features.md`, `docs/dependency-map.md`, `docs/project-state.md`
+
+Skip generated dependency/build directories: `node_modules/`, `dist/`, `build/`, `.next/`, coverage output, binary archives.
+
+### Phase 2: Classify Each Candidate
+
+Use this vocabulary in the index:
+
+| Role | Meaning |
+|------|---------|
+| `source` | Original project documentation maintained in this repo |
+| `planning-artifact` | PRD, design, architecture, ARB, roadmap, or external planning output |
+| `decision-record` | ADR, Decision Log, meeting decision, or governance note |
+| `reference` | External guide, source card, example, standard, or adoption candidate |
+| `runbook` | Operational procedure, deployment guide, incident response, support playbook |
+| `state` | kode:harness state file used by LLM agents |
+| `generated` | Derived output that should not be treated as an original source |
+
+### Phase 3: Confirm The Docs Hub Contract
+
+Ask at most three questions if the prompt does not already answer them:
+
+1. Hub target: logical hub alias/note title, wiki space/page label, repository path, `pending`, or `local-only`? Do not ask for or write absolute local vault paths into tracked state.
+2. Visibility boundary: `public`, `team`, `company-confidential`, `personal-private`, or `do-not-share`?
+3. Sync intent: summarize local docs into the hub, index hub references locally, or only maintain a bidirectional map?
+
+If the user skips the hub target, create a local map only and set Hub Target to `local-only`. If the user provides a local filesystem path, write only a sanitized alias or `local-only` in the tracked index and put the concrete path in `.harness/docs-bridge.local.json`.
+
+### Phase 4: Update Project Docs Hub Index
+
+Ensure `docs/project-brief.md` contains this section. Add it if missing:
+
+```markdown
+## Project Docs Hub Index
+
+| Local Source | Role | Hub Target | Sync Direction | Visibility | Status | Last Reviewed |
+|--------------|------|------------|----------------|------------|--------|---------------|
+| README.md | source | local-only | local-source -> hub-summary | public | active | YYYY-MM-DD |
+```
+
+Column rules:
+- **Local Source**: exact repository path, or external URL only when no local file exists.
+- **Role**: use the Phase 2 vocabulary.
+- **Hub Target**: `local-only`, `pending`, a sanitized external page label/URL, an Obsidian note title, a Confluence page label, or a logical hub alias. Never store `/Users/...`, `~/...`, `file://...`, drive-letter paths, personal vault paths, or tokens in this tracked table.
+- **Sync Direction**: one of `local-source -> hub-summary`, `hub-reference -> local-index`, `bidirectional-index-only`, `local-only`.
+- **Visibility**: one of `public`, `team`, `company-confidential`, `personal-private`, `do-not-share`.
+- **Status**: `active`, `proposed`, `stale`, or `archived`.
+- **Last Reviewed**: ISO date, or `pending` for proposed rows.
+
+### Phase 5: Promote Safely (Optional)
+
+Only when the user asks to update the hub:
+
+1. Create or update a short hub summary that links back to the Local Source.
+2. Preserve originals. If a local source needs improvement, ask before editing it.
+3. Record relationships with evidence, for example:
+   - `project -> documents -> Local Source`
+   - `Local Source -> summarized_by -> Hub Target`
+   - `reference -> supports -> project decision`
+4. Put uncertain claims under `needs verification` or `proposed relationship`.
+5. Never expose private/confidential rows into a less-restricted hub target without explicit user confirmation.
+6. For local-only hubs, use `.harness/docs-bridge.local.json` for machine-specific resolver details. Do not write those details into tracked state, README, or OSS templates.
+
+### Phase 6: Verify
+
+1. Run `state-check` after updating `docs/project-brief.md`.
+2. Confirm local paths in the index exist, unless the row is intentionally external.
+3. Report any private/confidential row that has an external Hub Target and ask for confirmation before hub writes.
+4. If documentation files changed, include the proof in the response: paths updated, index rows added/changed, and any hub target touched.
+
+## Output Format
+
+```markdown
+## Docs Bridge Result
+
+### Index Updates
+- Added/updated rows: N
+- Local-only rows: N
+- External hub rows: N
+
+### Visibility Warnings
+- [none] or [row requiring confirmation]
+
+### Verification
+- state-check: PASS | WARN | FAIL
+- Missing local paths: [none or list]
+
+---
+🧭 Next Step
+→ Goal: Keep project docs discoverable without rewriting originals
+→ Evidence: `state-check` plus changed index rows
+→ Next: `wrap-up` or [Hub update]
+→ Prompt: "문서 허브 인덱스를 기준으로 다음 문서를 요약/연결해줘"
+→ Why: The docs map is now explicit enough for future LLM sessions
+→ Pipeline: utility skill (docs bridge)
+---
+```
+
+## Rules
+
+- Use repository-relative paths for Local Source.
+- Prefer summaries and links over copied bodies.
+- Do not modify raw/source docs during discovery.
+- Do not invent hub targets. Use `local-only` or `pending` when unknown.
+- Keep visibility explicit on every row.
+- Keep personal/local Wiki resolver details in ignored `.harness/docs-bridge.local.*` files only.
+- Do not write absolute local paths, personal vault names, private page IDs, tokens, or company-private URLs into tracked templates or public docs.
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Copy every project doc into the central wiki | Index local sources and promote concise summaries only |
+| Treat generated reports as authoritative source | Mark as `generated` and link to the original input when known |
+| Publish private docs to a team/public hub silently | Stop and ask for explicit confirmation |
+| Rewrite READMEs while building the index | Preserve originals; ask before editing source docs |
+| Leave Hub Target blank | Use `local-only` or `pending` with a follow-up |
+| Put `/Users/...`, `~/...`, `file://...`, or personal vault paths in `project-brief.md` | Store only a logical alias in the index and keep resolver details in `.harness/docs-bridge.local.json` |

package/harness/skills/setup.md

@@ -13,6 +13,12 @@ One command does everything — no manual editing required.
 - When state files are outdated and need a refresh
 - When any agent reports "state files are empty"
 
+## Re-running on an existing install (Upgrade flow)
+
+On existing installs, default `init` preserves state (`project-state`, `features`, `dependency-map`, `failure-patterns`, `project-brief`, `agent-memory`) and refreshes IDE config (`.github/`, `.claude/`, `.cursor/`, `.codex/`, `.windsurf/`, `.agents/`, `CLAUDE.md`, `AGENTS.md`). Overwritten IDE files are backed up to `.harness/init-backups/<ISO-timestamp>/...`.
+
+Use `--overwrite` only to reset corrupted state after backup; then rerun setup to repopulate files.
+
 ## Procedure
 
 ### Phase 1: Project Discovery (read-only)
@@ -62,6 +68,10 @@ One command does everything — no manual editing required.
 
 **Do NOT modify any code files in this phase.**
 
+### Phase 1.4: Project Docs Hub Detection (optional)
+
+If user asked for wiki/docs-hub work, record candidate paths from Phase 1 without reading or rewriting full docs. After Phase 3, invoke `docs-bridge` to fill `## Project Docs Hub Index`. Otherwise skip.
+
 <!-- CREW_MODE_START -->
 ### Phase 1.5: Crew Artifact Detection + Indexing
 

package/harness/skills/state-check.md

@@ -115,6 +115,22 @@ If no Validation Tracker → skip.
    - Done Story with failing proof → FAIL: `[FAIL] Story {S-N-M} proof shows failure but status is done`
    - In-progress Story without proof → PASS; proof pending is normal
 
+### Check 8: Project Docs Hub Index (optional)
+
+If `docs/project-brief.md` contains `## Project Docs Hub Index` with non-comment table rows:
+
+1. For each row, verify `Local Source`, `Sync Direction`, `Visibility`, `Status`, and `Last Reviewed` are not blank or `TBD`.
+2. If `Local Source` is a repository path, verify the file or directory exists. Skip existence checks for URLs and explicitly external rows.
+3. Verify `Sync Direction` is one of: `local-source -> hub-summary`, `hub-reference -> local-index`, `bidirectional-index-only`, `local-only`.
+4. Verify `Visibility` is one of: `public`, `team`, `company-confidential`, `personal-private`, `do-not-share`.
+5. If `Hub Target` contains an absolute/local machine path (`/Users/`, `~/`, `file://`, drive-letter paths, or backslash user paths), WARN: `[WARN] docs hub row contains local machine path — move resolver details to .harness/docs-bridge.local.*`.
+6. If Visibility is `company-confidential`, `personal-private`, or `do-not-share` and Hub Target is not `local-only` or `pending`, WARN: `[WARN] restricted docs row has external Hub Target — confirm disclosure boundary before hub writes`.
+
+Outcomes:
+- Complete rows with existing local paths → PASS
+- Missing local path, blank required column, invalid vocabulary, local machine path leakage, or restricted row with external target → WARN
+- No `Project Docs Hub Index` section or no real rows → skip; this project may not use docs-bridge
+
 ## Output Format
 
 ```
@@ -139,6 +155,9 @@ If no Validation Tracker → skip.
 ### Check 7: Proof Ledger Coverage
 - {N} done Stories checked / {M} missing proof / {K} failing proof
 
+### Check 8: Project Docs Hub Index
+- {N} rows checked / {M} missing paths / {K} visibility warnings / skipped if unused
+
 <!-- CREW_MODE_START -->
 ### Check 6: Validation Tracker (🟣)
 - {N} FR references checked / {M} drifted

package/harness/skills/wrap-up.md

@@ -138,6 +138,15 @@ For each issue/error that occurred in this session:
 
 > **Self-check**: `docs/dependency-map.md`에 이 세션에서 새로 추가한 모듈이 모두 등록되었는지 확인. 누락 시 즉시 추가. state-check가 PASS 또는 WARN을 반환해야 다음 단계로 진행합니다.
 
+### Step 5.55: Refresh Project Docs Hub Index (if applicable)
+
+Run only if user used/requested `docs-bridge`, or Project Docs Hub Index has real rows.
+
+1. For changed docs (`README*`, `docs/`, ADR/design/runbook/API specs), refresh indexed review/status.
+2. For new docs, add `proposed` rows or recommend `docs-bridge`.
+3. Never write external hubs, invent targets, change visibility, or convert `local-only` / `pending` without explicit request.
+4. Keep filesystem paths, vault names, page IDs, and resolver details out of tracked state; use `.harness/docs-bridge.local.*`.
+
 ### Step 5.6: Resolve STATE-AUDIT Flags (if applicable)
 
 If the `reviewer` agent was run in this session and produced `[STATE-AUDIT]` flags:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodevibe/harness",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "kode:harness — harness engineering for keeping every developer's AI aligned on one project direction.",
   "keywords": [
     "llm",