gitifact 0.4.4 → 0.5.1

package/dist/i18n/ko/changelog.md

@@ -1,3 +1,32 @@
+## 0.5.1 - 2026-09-18
+### Changed
+- `init`이 새 버전이 있는지 확인해 결과의 `update`·`install`에 알립니다. 이미 설치된 이전 버전으로 도입해도 새 버전이 있다는 것을 알 수 있습니다. 확인에 실패해도 초기화는 진행되며 `GITIFACT_NO_UPDATE_CHECK`로 끌 수 있습니다. `init` 출력 계약이 version 5가 되었습니다.
+- 소개 글의 시작 프롬프트가 이미 설치돼 있어도 `npm install -g gitifact@latest`로 최신 버전을 설치하도록 안내합니다.
+- CLI보다 새로운 저장 규약을 쓰는 프로젝트에서는 CLI를 최신 버전으로 올리라고 안내합니다.
+### Fixed
+- 0.4.x로 `init`한 프로젝트에서 0.5.0이 새로 `init`하라고 안내하면서 `init`도 거부해 진행할 수 없던 문제를 고쳤습니다. `.gitifact`에 설정 파일만 있으면 `init`이 새 저장 규약으로 바꾸고 결과에 `replaced`로 표시합니다. 이전 규약의 명세나 기록이 있으면 바꾸지 않고 해야 할 일을 안내합니다.
+
+## 0.5.0 - 2026-09-18
+### Added
+- 프로젝트 위키를 추가했습니다. 기능에 묶이지 않는 제품 설명·구조·규칙을 `.gitifact/wiki/`에 하위 폴더로 자유롭게 두고, 페이지마다 CLI가 발급한 W-ID로 추적합니다. `spec save`의 `create-doc`·`update-doc`·`move-doc`·`delete-doc`으로 저장하고 커밋할 때 변경 이유를 붙입니다.
+- 위키의 `README.md`가 위키 운영 방침입니다. `init`이 처음 도입할 때 아키텍처 결정 기록(ADR)을 쌓는 기본 방침으로 만들고, 고치면 `docs wiki`가 그 내용을 이 프로젝트의 방침으로 보여 줍니다.
+- 이미지·PDF 같은 파일을 `.gitifact/assets/`에 두고 문서에서 상대 경로로 참조할 수 있습니다. `spec working`이 대상 없는 링크, 큰 파일, 권장하지 않는 확장자, 어떤 문서도 참조하지 않는 에셋을 경고합니다.
+- 설계 문서의 frontmatter `sources`에 참고 문서를 적으면 브라우저 설계 탭 위에 목록으로 보입니다.
+- 브라우저에 프로젝트 위키 메뉴를 추가했습니다. 왼쪽 트리와 오른쪽의 폴더 내용 또는 페이지로 된 탐색기입니다.
+- 브라우저가 문서 본문의 상대 링크를 해당 위키 페이지·기능·에셋으로 연결합니다. `.gitifact` 밖의 저장소 파일은 열지 않고 경로를 복사합니다.
+- `init`이 AGENTS.md에 블록을 쓸 때 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄로 된 CLAUDE.md를 만들어 Claude Code도 블록을 읽게 합니다. `update`는 파일을 만들지 않고 없다는 사실만 알립니다.
+### Changed
+- 저장 규약이 schemaVersion 2가 되었습니다. 파일 ID는 frontmatter에 둡니다. 0.4.x로 만든 프로젝트(schemaVersion 1)는 이 버전에서 읽지 않으며 전환 도구도 없습니다. CLI가 이유를 알리고, 새로 `init`해야 합니다.
+- 브라우저가 제품 개요에서 시작합니다. 활동은 `/activity`로 옮겼고, 필터나 선택이 담긴 이전 활동 주소는 같은 조건의 활동 페이지로 이어집니다.
+- 브라우저의 요구사항 메뉴 이름을 기능별 요구사항으로 바꿨습니다.
+- GITIFACT 블록이 요구사항·설계·코드를 바꾸기 전에 `docs wiki`를 확인하고, 위키 운영 방식을 바꾸려면 위키 README를 고치도록 안내합니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
+- 명세 지침의 예시에서 제목 뒤의 "요구사항"을 뺐습니다. 명세 제목은 기능 이름만 씁니다.
+- `update` 출력 계약이 version 3이 되었습니다. `agentDocs.missing`에 없는 CLAUDE.md를 알립니다.
+### Removed
+- 제품 문서와 지침 폴더, 브라우저의 지침 메뉴를 없앴습니다. 같은 내용은 프로젝트 위키에 둡니다.
+### Fixed
+- 브라우저 검색창에서 한글이 조합 도중 끊기거나 "ㄱ거검검"처럼 겹쳐 입력되던 문제를 고쳤습니다.
+
 ## 0.4.4 - 2026-09-17
 ### Added
 - `update --commit`이 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋합니다. 다른 staging은 그대로 남고 훅·서명도 평소대로 실행됩니다. 블록 밖에도 수정이 있거나, 추적하지 않는 파일이거나, Git이 커밋을 거부하면 커밋하지 않고 이유를 알립니다.

package/dist/i18n/ko/docs/commit.md

@@ -2,8 +2,6 @@
 
 자동 기록은 커밋 권한이 아니다. 사용자 커밋 요청 또는 명시적 프로젝트 정책이 있을 때 실행한다. 정책이 없다는 이유로 자동 커밋하지 않으며 이미 부여된 권한은 다시 묻지 않는다. 푸시는 별도 권한을 따른다.
 
-기본은 관련 명세·이유·소스·테스트를 같은 커밋에 담는 것이다. 분리 정책이면 명세와 이유를 먼저 커밋하고 코드·테스트 커밋에서 실제 R-ID를 참조한다. 기존 사용자 변경이나 staging을 지우거나 무관한 변경까지 포함하지 않는다.
-
 ## 절차
 
 1. 실제 diff와 관련 테스트를 확인한다. 필요하면 `spec changes`로 HEAD 대비 최종 명세 차이와 pendingReasons를 읽는다.
@@ -24,13 +22,25 @@ basis는 user-request 또는 project-policy다. 예시 경로와 근거를 그
 ## 입력 규칙
 
 - reasons는 이번에 남길 **전체 미커밋 이유 목록**이므로 여전히 유효한 pendingReasons도 포함한다. 생략하면 이미 준비된 미커밋 이유를 그대로 유지한다. 모르는 이유는 꾸며내지 않는다. 이유가 없어도 커밋은 진행되며 withoutReason으로 표시된다.
-- 제품·지침 문서의 변경 이유는 `{requirements: [], documents: [실제 P-ID 또는 G-ID], reason: 실제 이유}`로 전달한다. 한 이유는 한 종류의 문서만 대상으로 한다. 이유는 `.gitifact/product/history.jsonl`·`.gitifact/guides/history.jsonl`에 기록되므로 바뀐 문서와 해당 history.jsonl을 paths에 포함한다.
+- 위키 페이지의 변경 이유는 `{requirements: [], documents: [실제 W-ID], reason: 실제 이유}`로 전달한다. 이유는 `.gitifact/wiki/history.jsonl`에 기록되므로 바뀐 페이지와 그 파일을 paths에 포함한다.
 - 설계 변경 이유는 `{requirements: [], designs: [실제 S-ID], reason: 실제 이유}`로 전달한다. 요구사항과 같은 이유이면 두 배열을 함께 지정한다. 변경된 design.md와 history.jsonl을 paths에 포함한다. 설계만 바뀌면 요구사항 변경이나 완료를 만들지 않는다.
-- paths에는 변경한 명세와 그 history.jsonl, 관련 코드·테스트를 담는다. 명세 이동이면 양쪽 명세를 포함한다. 기록할 이유가 없는 history.jsonl은 건너뛴다. 미커밋 명세·이유 전체가 선택돼야 하므로 서로 무관한 작업이 섞였다면 강제 포함하지 않고 제한을 알린다.
+- paths에는 변경한 명세와 그 history.jsonl, 관련 코드·테스트를 담는다. 문서가 참조하는 새 에셋(`.gitifact/assets/…`)도 함께 담는다. 명세 이동이면 양쪽 명세를 포함한다. 기록할 이유가 없는 history.jsonl은 건너뛴다. 미커밋 명세·이유 전체가 선택돼야 하므로 서로 무관한 작업이 섞였다면 강제 포함하지 않고 제한을 알린다.
 - 실행 전에는 staging하지 않는다. 기존 staging이나 intent-to-add가 있으면 보존하고 보류한다.
 - 수정 후 원복돼 최종 차이가 없으면 새 이유도 없다. 커밋된 history.jsonl을 덮어쓰지 않는다.
-- history에는 이유와 요구사항·설계 연결만 두며 원문 before/after·작성자·시각을 복제하지 않는다. 과거 명세는 `spec read --ref`, 변경은 `spec diff --from --to`로 Git 커밋에서 읽는다. Git 작성자를 사용자 요청·승인의 증거로 취급하지 않는다.
+- history에는 이유와 요구사항·설계·페이지 연결만 두며 원문 before/after·작성자·시각을 복제하지 않는다. 과거 명세는 `spec read --ref`, 변경은 `spec diff --from --to`로 Git 커밋에서 읽는다. Git 작성자를 사용자 요청·승인의 증거로 취급하지 않는다.
 - 훅 등으로 커밋이 거부되고 HEAD가 그대로면 이번에 쓴 이유 파일과 index는 실행 전으로 돌아간다. 원인을 고친 뒤 같은 입력으로 다시 실행한다. 실패 후 훅·서명을 끄지 않는다. HEAD가 바뀐 불확실한 실행은 재시도하지 않고 복구 자료를 확인한다. 잠금이나 index 백업을 임의 삭제하거나 커밋을 reset하지 않는다.
 - `prepare`·`verify`·`commit-plan`·`commit-apply`는 deprecated이며 0.6.0에서 제거된다. 새 작업에는 사용하지 않는다.
 
 커밋 참조는 구현 완료 선언이 아니다. 실제 테스트 결과와 남은 제한을 별도로 알린다.
+
+## 무엇을 한 커밋에 담는가
+
+기본은 관련 명세·이유·소스·테스트를 같은 커밋에 담는 것이다. 분리 정책이면 명세와 이유를 먼저 커밋하고 코드·테스트 커밋에서 실제 R-ID를 참조한다. 기존 사용자 변경이나 staging을 지우거나 무관한 변경까지 포함하지 않는다.
+
+## 메시지
+
+프로젝트의 커밋 메시지 규약을 따른다. 규약이 없으면 첫 줄에 무엇을 바꿨는지, 본문에 왜 바꿨는지를 짧게 쓴다. 요구사항·설계·페이지 연결 트레일러는 CLI가 붙이므로 메시지에 직접 쓰지 않는다.
+
+## 이유 쓰기
+
+이유는 대화와 결정에서 확인한 사실만 적는다. 기각한 대안이 이후 작업에 영향을 주면 함께 적는다. 커밋 참조를 구현 완료로 보고하지 않고, 실제 실행한 검증과 남은 제한을 따로 알린다.

package/dist/i18n/ko/docs/design.md

@@ -1,41 +1,49 @@
-# 기능 설계 작성과 개정
+# 기능 설계 형식
 
-새 기능을 정리할 때 requirements.md와 design.md를 함께 작성하는 것이 기본이다. 사용자가 요구사항만 요청하면 따르고, 기존 명세에 설계가 없다고 일괄 생성하지 않는다. 설계는 형식상 선택이며 단계별 승인을 강제하지 않는다. 중요한 불명확함만 질문한다. tasks.md는 아직 다루지 않는다.
+설계는 기능 폴더의 `design.md` 하나이며 여러 요구사항을 구현하는 공통 구조와 처리 방식을 설명한다.
+
+## 파일 구조
 
-설계는 여러 요구사항을 구현하는 공통 구조와 처리 방식을 설명한다. 다음 목차를 기본으로 하되 필요한 절만 쓴다: 개요 / 구조와 데이터 / 처리 흐름 / 오류 처리와 검증 / 주요 설계 결정 / 미결 사항. 확정·관측·제안을 구분하고 중요한 대안과 선택 이유를 덧붙인다. 결정 목록만으로 구현 설명을 대신하지 않는다.
+frontmatter의 `id`는 소유 명세의 S-ID이며 CLI가 쓴다. 설계가 참고한 문서는 frontmatter의 `sources` 목록에 둔다. 항목마다 `title`과 `path`(위키 페이지로 가는 이 파일 기준 상대 경로, `.md`) 또는 `url`(http/https) 중 하나, 선택적 `note`를 쓴다. 본문 곳곳에 흩어진 링크 대신 이 목록으로 참고 문서를 관리하고, 브라우저는 이 목록을 설계 탭에 카드로 보여 준다. 외부 페이지의 제목이나 미리보기는 가져오지 않는다.
 
 ```markdown
-<!-- gitifact-design: S-소유명세의실제값 -->
+---
+id: S-소유명세의실제값
+sources:
+  - title: 아키텍처
+    path: ../../wiki/architecture.md
+    note: 계층 구조와 의존 방향
+  - title: 라이브러리 문서
+    url: https://example.test/docs
+---
 
 # 게시물 관리 설계
 
 ## 개요
 구현할 범위와 접근 방식.
 
-## 구조와 데이터
-구성 요소의 책임, 관계, 저장할 데이터.
-
 ## 처리 흐름
 <!-- gitifact-ref: R-관련요구사항의실제값 -->
 입력부터 결과까지의 핵심 흐름.
+```
+
+위 문장은 구조 설명이다. 실제 저장할 때는 파악한 내용으로 채우고 예시 ID와 안내 문장을 그대로 저장하지 않는다. 절 단위 참조는 실제 ID로 `<!-- gitifact-ref: R-ID, R-ID -->`를 쓴다. 코드 블록의 예시는 참조가 아니다. 본문의 상대 링크(`../../assets/flow.png` 등)는 브라우저가 해당 대상으로 연결한다.
 
-## 오류 처리와 검증
-실패 조건과 확인할 동작.
+## 저장과 참조
 
-## 주요 설계 결정
-선택한 방식, 이유, 중요한 기각 대안.
+`spec save`의 operations에 `set-design`(type·feature·title·body·선택적 sources 배열)을 사용한다. create·add·set-design을 같은 요청에 담아 두 파일을 저장할 수 있다. CLI가 frontmatter를 작성하며 빈 설계를 자동 생성하지 않는다. 신규 R-ID는 반환된 결과에서 얻은 뒤 참조가 필요한 설계 절을 후속 save로 보완한다. ID를 미리 만들어 넣지 않는다. 설계 삭제는 `delete-design`(type·feature)이다.
 
-## 미결 사항
-아직 결정하지 않은 내용. 없으면 이 절을 생략한다.
-```
+working/save의 `MISSING_DESIGN_REFERENCE` 경고는 삭제·이동 여부와 원문을 확인하고 필요하면 수정한다. `MISSING_LINK_TARGET`은 sources의 path나 본문 링크 대상이 없을 때 나온다. 경고를 무시한 채 연결이 유효하다고 주장하지 않는다.
 
-위 문장은 목차 설명이다. 실제 저장할 때는 파악한 내용으로 채우고 불필요한 절은 생략한다. 예시 ID와 안내 문장을 그대로 저장하지 않는다.
+## 언제 쓰는가
 
-## 저장과 참조
+새 기능을 정리할 때 requirements.md와 design.md를 함께 작성하는 것이 기본이다. 사용자가 요구사항만 요청하면 따르고, 기존 명세에 설계가 없다고 일괄 생성하지 않는다. 설계는 형식상 선택이며 단계별 승인을 강제하지 않는다. 중요한 불명확함만 질문한다. tasks.md는 아직 다루지 않는다.
+
+## 목차
 
-`spec save`의 operations에 set-design(type·feature·title·body)을 사용한다. create·add·set-design을 같은 요청에 담아 두 파일을 저장할 수 있다. CLI가 동일 S-ID의 gitifact-design 주석을 작성하며 빈 설계를 자동 생성하지 않는다. 신규 R-ID는 반환된 결과에서 얻은 뒤 참조가 필요한 설계 절을 후속 save로 보완한다. ID를 미리 만들어 넣지 않는다. 설계 삭제는 delete-design(type·feature)이다.
+다음 목차를 기본으로 하되 필요한 절만 쓴다: 개요 / 구조와 데이터 / 처리 흐름 / 오류 처리와 검증 / 주요 설계 결정 / 미결 사항. 확정·관측·제안을 구분하고 중요한 대안과 선택 이유를 덧붙인다. 결정 목록만으로 구현 설명을 대신하지 않는다. 미결 사항이 없으면 그 절을 생략한다.
 
-본문 참조는 실제 ID로 `<!-- gitifact-ref: R-ID, R-ID -->`를 쓴다. 코드 블록의 예시는 참조가 아니다. working/save의 MISSING_DESIGN_REFERENCE 경고는 삭제·이동 여부와 원문을 확인하고 필요하면 수정한다. 경고를 무시한 채 연결이 유효하다고 주장하지 않는다.
+설계를 쓰기 전에 위키의 구조·규칙 페이지를 읽고, 따른 페이지는 `sources`에 올린다. 설계가 위키의 기준과 어긋나면 문서를 먼저 고칠지 사용자와 정한다.
 
 ## 개정
 

package/dist/i18n/ko/docs/spec.md

@@ -1,23 +1,17 @@
-# Markdown 명세 정리
+# Markdown 명세 형식
 
-사용자에게 의미 있는 응집된 기능으로 명세를 묶는다. 코드 모듈이나 DDD 계층을 그대로 복제하지 않는다. 기존 명세에 포함할 수 있는지 먼저 확인한다. 제목·폴더가 달라져도 같은 요구사항의 ID는 유지하며, 실제 잘못 배치된 요구사항을 옮길 때도 새 ID로 복제하지 않는다.
-
-## 사용자 스토리와 수용 조건
-
-각 요구사항의 본문은 사용자 스토리로 시작한다. 누가 어떤 목표를 이루려 하며 왜 필요한지를 한두 문장으로 표현한다. 기본 문형은 “［역할］로서, ［이유］를 위해 ［목표］하고 싶다.”이며 프로젝트의 언어에 맞게 자연스럽게 쓴다. 역할은 해당 제품의 실제 사용자나 운영자 등이며, 이 문서의 게시물 예시나 Gitifact 사용자를 다른 제품에 그대로 대입하지 않는다.
-
-사용자 스토리 아래에는 `### 수용 조건`과 번호별 `조건: / 기대 동작:` 형식을 유지한다. 파일 경로·ID·저장 규약으로 사용자 목표를 대신하지 않는다. 별도로 필요한 확정 제약은 `### 범위와 제약`에 두고, 내부 구현 방식은 설계에 둔다. 역할·목표·이유는 대화와 확인한 맥락에 근거하며, 모르는 동기를 만들어 문형을 채우지 않는다. 의미를 결정할 정보가 부족하면 필요한 부분만 질문한다.
-
-새 요구사항과 요청받아 개정하는 요구사항에 적용한다. 기존 문서를 정리할 때 ID·확정된 제약·수용 조건의 의미를 보존하고, 이번 작업과 무관한 요구사항을 일괄 개정하지 않는다. 저장 전에는 스토리의 역할·목표·이유가 드러나는지, 수용 조건이 그 목표의 성공·실패를 판정하는지 대조한다. CLI는 특정 문장이나 사용자 의도를 강제·검증하지 않는다.
+기능 명세는 `.gitifact/spec/<기능>/requirements.md` 하나에 그 기능의 요구사항을 담는다. 설계는 같은 폴더의 `design.md`(`gitifact docs design`), 변경 이유는 `history.jsonl`이다.
 
 ## 파일 구조와 ID
 
-S-ID와 R-ID는 CLI가 발급한 값을 그대로 사용한다. 형식은 `S-<난수>`와 `R-<난수>`이며 난수는 소문자 base32 10자다. R-ID에 기능 이름을 넣거나 직접 예시 ID를 만들어 저장하지 않는다. 현재 Markdown은 frontmatter 없이 다음 구조를 쓴다.
+S-ID와 R-ID는 CLI가 발급한 값을 그대로 사용한다. 형식은 `S-<난수>`와 `R-<난수>`이며 난수는 소문자 base32 10자다. R-ID에 기능 이름을 넣거나 직접 예시 ID를 만들어 저장하지 않는다. 파일은 frontmatter로 시작하고, 요구사항 제목 바로 아래 줄에 ID 주석을 둔다.
 
 ```markdown
-<!-- gitifact-spec: S-CLI가발급한값 -->
+---
+id: S-CLI가발급한값
+---
 
-# 게시물 관리 요구사항
+# 게시물 관리
 
 ## 게시물 등록
 <!-- gitifact-req: R-CLI가발급한값 -->
@@ -30,7 +24,7 @@ S-ID와 R-ID는 CLI가 발급한 값을 그대로 사용한다. 형식은 `S-<
    기대 동작: 시스템은 제목 입력 안내를 표시하고 저장을 중단합니다.
 ```
 
-위 ID는 구조 설명용이며 유효한 입력이 아니다.
+위 ID는 구조 설명용이며 유효한 입력이 아니다. frontmatter에는 `id`만 둔다. 제목(`#`)은 한 번, 요구사항은 `##`이며 본문에 다른 gitifact 주석을 쓰지 않는다. 다른 문서로 가는 링크는 이 파일 기준 상대 경로로 쓴다(예: `../../wiki/architecture.md`, `../../assets/flow.png`). 브라우저가 그 링크를 해당 페이지로 연결하고, 대상이 없으면 `spec working`이 `MISSING_LINK_TARGET`으로 알린다.
 
 ## 저장 명령
 
@@ -40,7 +34,7 @@ S-ID와 R-ID는 CLI가 발급한 값을 그대로 사용한다. 형식은 `S-<
 {
   "expected": "working의 실제 stamp",
   "operations": [
-    { "type": "create", "feature": "posts", "title": "게시물 관리 요구사항" },
+    { "type": "create", "feature": "posts", "title": "게시물 관리" },
     { "type": "add", "feature": "posts", "title": "게시물 등록", "body": "게시물 작성자로서, 작성한 글을 나중에 다시 확인하기 위해 제목과 내용을 저장하고 싶다.\n\n### 수용 조건\n\n1. 조건: 사용자가 제목을 비운 채 저장을 요청합니다.\n   기대 동작: 시스템은 제목 입력 안내를 표시하고 저장을 중단합니다." },
     { "type": "set-design", "feature": "posts", "title": "게시물 관리 설계", "body": "## 개요\n\n합의한 구현 방향과 범위.\n\n## 구조와 데이터\n\n실제 구현에 필요한 구성 요소와 저장 방식." }
   ]
@@ -49,6 +43,18 @@ S-ID와 R-ID는 CLI가 발급한 값을 그대로 사용한다. 형식은 `S-<
 
 명령 그룹은 `gitifact spec`이다. 기존 요구사항은 `update`의 id·title·body, 이동은 `move`의 id·feature, 명세 제목 변경은 `rename-spec`의 id·title을 사용한다. id에는 조회한 실제 R-ID 또는 S-ID를 전달한다. 전용 삭제·폴더 이름 변경 명령은 아직 없다. 미지원 작업에 존재하지 않는 명령이나 임의 전환 절차를 안내하지 않는다.
 
-설계는 `set-design`(type·feature·title·body)으로 같은 요청에 담을 수 있다. 자세한 작성 규칙은 `gitifact docs design`, 제품 설명과 지침 문서는 `gitifact docs product`를 읽는다.
+설계는 `set-design`(type·feature·title·body·선택적 sources)으로 같은 요청에 담을 수 있다. 자세한 작성 규칙은 `gitifact docs design`, 위키와 에셋은 `gitifact docs wiki`를 읽는다.
+
+## 기능으로 묶는 기준
+
+사용자에게 의미 있는 응집된 기능으로 명세를 묶는다. 코드 모듈이나 DDD 계층을 그대로 복제하지 않는다. 기존 명세에 포함할 수 있는지 먼저 확인한다. 제목·폴더가 달라져도 같은 요구사항의 ID는 유지하며, 실제 잘못 배치된 요구사항을 옮길 때도 새 ID로 복제하지 않는다. 명세 제목은 기능 이름 그대로 쓰고 "요구사항" 같은 접미어를 붙이지 않는다.
+
+## 사용자 스토리와 수용 조건
+
+각 요구사항의 본문은 사용자 스토리로 시작한다. 누가 어떤 목표를 이루려 하며 왜 필요한지를 한두 문장으로 표현한다. 기본 문형은 “［역할］로서, ［이유］를 위해 ［목표］하고 싶다.”이며 프로젝트의 언어에 맞게 자연스럽게 쓴다. 역할은 해당 제품의 실제 사용자나 운영자 등이며, 이 문서의 게시물 예시나 Gitifact 사용자를 다른 제품에 그대로 대입하지 않는다.
+
+사용자 스토리 아래에는 `### 수용 조건`과 번호별 `조건: / 기대 동작:` 형식을 유지한다. 파일 경로·ID·저장 규약으로 사용자 목표를 대신하지 않는다. 별도로 필요한 확정 제약은 `### 범위와 제약`에 두고, 내부 구현 방식은 설계에 둔다. 역할·목표·이유는 대화와 확인한 맥락에 근거하며, 모르는 동기를 만들어 문형을 채우지 않는다. 의미를 결정할 정보가 부족하면 필요한 부분만 질문한다.
+
+새 요구사항과 요청받아 개정하는 요구사항에 적용한다. 기존 문서를 정리할 때 ID·확정된 제약·수용 조건의 의미를 보존하고, 이번 작업과 무관한 요구사항을 일괄 개정하지 않는다. 저장 전에는 스토리의 역할·목표·이유가 드러나는지, 수용 조건이 그 목표의 성공·실패를 판정하는지 대조한다. CLI는 특정 문장이나 사용자 의도를 강제·검증하지 않는다.
 
 대화 중에는 명세 초안을 다듬는다. 매 수정마다 이유나 사건을 쌓지 않는다. 코드와 테스트를 고치는 동안 달라진 요구사항은 마지막 합의 내용으로 맞춘다.

package/dist/i18n/ko/docs/wiki.default.md

@@ -0,0 +1,27 @@
+이 위키에는 아키텍처 결정 기록(ADR)을 쌓는다.
+
+## 결정 기록
+
+여러 기능에 걸치는 구조·기술 선택을 새로 하거나 바꾸면 `adr/` 아래에 하나 남긴다. 파일 이름은 `0001-use-postgres.md`처럼 네 자리 번호와 소문자·숫자·하이픈이며, 번호는 늘리기만 한다. 한 기능 안에서만 유효한 선택은 그 기능의 design.md에 둔다.
+
+```markdown
+# 결정 NNNN. 제목
+
+상태: Accepted · YYYY-MM-DD
+
+## 맥락
+어떤 문제와 제약이 있었는가.
+
+## 결정
+무엇을 어떻게 하기로 했는가.
+
+## 결과
+얻는 것과 감수하는 것, 기각한 대안과 이유.
+```
+
+상태는 `Proposed`(제안), `Accepted`(채택), `Deprecated`(더 이상 따르지 않음), `Superseded by NNNN`(NNNN번 기록으로 대체) 중 하나다. 이미 쌓인 기록은 고치지 않는다. 결정이 바뀌면 새 기록을 추가하고, 이전 기록은 상태만 `Superseded by NNNN`으로 바꾼다.
+
+## 에이전트
+
+- 요구사항·설계·코드를 바꾸기 전에 관련된 결정 기록을 읽고 따른다.
+- 결정 기록에 남길 만한 선택을 만나면 추가를 제안하고, 사용자가 동의하면 `spec save`로 저장한다.

package/dist/i18n/ko/docs/wiki.md

@@ -0,0 +1,41 @@
+# 프로젝트 위키 형식
+
+기능에 묶이지 않는 내용은 `.gitifact/wiki/`에 둔다. 제품이 무엇이고 누구를 위한 것인지, 어떻게 만드는지, 지킬 규칙이 여기에 들어간다. 기능별 동작은 명세에 두고 위키에 반복하지 않는다. 이 출력의 앞부분은 CLI가 검증하는 형식이고, 뒷부분 "운영 방침"은 프로젝트의 `.gitifact/wiki/README.md` 본문이다. README가 없으면 내장 기본 방침이 실린다.
+
+## 파일 구조
+
+페이지는 `.gitifact/wiki/` 아래 Markdown 파일이며 하위 폴더를 자유롭게 둔다. 폴더·파일 이름은 소문자·숫자·하이픈이다. 루트의 페이지만 `README.md`·`ARCHITECTURE.md`처럼 대문자 이름을 쓸 수 있다. `README.md`는 위키의 운영 방침이자 진입 페이지다. `init`이 기본 방침으로 만들어 두고, 사용자가 고치면 그대로 에이전트의 방침이 된다. 브라우저와 GitHub는 폴더를 열면 이 페이지를 보여 준다.
+
+각 파일은 CLI가 발급한 `W-<난수>` ID를 담은 frontmatter, 최상위 제목, 본문 순서다. 본문에는 다른 gitifact 주석을 쓰지 않는다. 손으로 파일을 만들지 말고 `spec save`로 저장한다. 변경 이유는 `.gitifact/wiki/history.jsonl` 하나에 쌓인다.
+
+```markdown
+---
+id: W-CLI가발급한값
+---
+
+# 아키텍처
+
+계층 구조와 의존 방향.
+```
+
+다른 페이지·명세·에셋으로 가는 링크는 이 파일 기준 상대 경로로 쓴다. 예: `conventions/code-style.md`, `../spec/posts/requirements.md`, `../assets/diagrams/flow.png`. 에디터와 GitHub에서는 파일 링크로 동작하고, 브라우저는 해당 페이지·기능·에셋으로 연결한다. gitifact 문서가 아닌 저장소 파일로 가는 링크는 브라우저에서 열리지 않고 경로만 복사할 수 있다. 대상이 없는 링크는 `spec working`이 `MISSING_LINK_TARGET`으로 알린다.
+
+## 에셋
+
+이미지·PDF 등 Markdown이 아닌 파일은 `.gitifact/assets/` 아래에 둔다. 하위 폴더는 자유롭고 ID는 없다. 파일을 직접 복사해 넣고 문서에서 상대 경로로 참조한다. 권장 확장자는 png·jpg·gif·webp·svg·pdf, 권장 크기는 파일당 1MB·전체 50MB 이하다. 넘어도 저장·커밋은 되며 `spec working`이 `ASSET_SIZE`·`ASSET_EXTENSION`·`ASSETS_TOTAL_SIZE`로 알린다. 어떤 문서도 참조하지 않는 에셋은 `UNREFERENCED_ASSET`으로 알린다. 브라우저는 이미지를 본문에 표시하고 그 밖의 파일은 다운로드로 제공한다. 에셋 파일 이름을 바꾸면 참조하는 문서도 함께 고친다.
+
+## 저장 명령
+
+`spec save`의 operations를 쓴다. 생성은 `create-doc`(type·path·title·body), 수정은 `update-doc`(type·id·title·body), 이동·이름 변경은 `move-doc`(type·id·path), 삭제는 `delete-doc`(type·id)다. path는 `.gitifact/wiki/` 안 상대 경로이며 `.md`로 끝난다.
+
+```json
+{
+  "expected": "working의 실제 stamp",
+  "operations": [
+    { "type": "create-doc", "path": "README.md", "title": "제품 이름", "body": "한 문단 정의, 대상 사용자, 원칙, 범위 밖. 나머지 페이지로 가는 링크." },
+    { "type": "create-doc", "path": "conventions/code-style.md", "title": "코드 스타일", "body": "규칙과 이유." }
+  ]
+}
+```
+
+커밋할 때 위키 변경 이유는 `{requirements: [], documents: [실제 W-ID], reason: 실제 이유}`로 전달한다(`gitifact docs commit`).

package/dist/i18n/ko/docs/workflow.md

@@ -8,18 +8,24 @@
 
 설정과 실제 파일, CLI 도움말을 함께 확인해 다음 중 하나의 흐름을 선택한다. 명령이 존재한다는 사실만으로 프로젝트 사용이나 전환이 허용되지는 않는다.
 
-- **새 형식:** config.json의 `schemaVersion: 1`은 `.gitifact/spec/<기능>/requirements.md`, 선택적인 `design.md`, `history.jsonl`을 사용한다. `gitifact docs spec`의 흐름을 따른다.
-- **기존 형식:** workflow-1·prototype-1·init-1 설정은 현재 CLI가 조회·기록하지 않는다. 기존 기록을 삭제하거나 새 형식으로 가장하지 않고, 기존 기록을 읽으려면 0.4.0 이하 CLI가 필요하다고 알린다.
+- **현재 형식:** config.json의 `schemaVersion: 2`는 `.gitifact/spec/<기능>/requirements.md`, 선택적인 `design.md`, `history.jsonl`과 `.gitifact/wiki/`, `.gitifact/assets/`를 사용한다. `gitifact docs spec`·`docs wiki`의 형식을 따른다.
+- **이전 형식:** `schemaVersion: 1`(0.4.x)과 workflow-1·prototype-1·init-1 설정은 현재 CLI가 조회·기록하지 않는다. 기존 기록을 삭제하거나 새 형식으로 가장하지 않고, 정식 버전 전 규약이라 전환 도구가 없다고 알린다. 사용자가 원하면 기록을 보존한 채 새로 도입한다.
 - **미도입:** 도입이 허용됐으면 Git 상태와 지침을 확인하고 `init --dry-run`, `init`으로 연결한다. Git 저장소가 없으면 Git 생성 권한을 확인한다. 기존 변경과 staging을 보존한다.
 
-init은 `.gitifact/config.json`과 도입 기준선을 만들고, AGENTS.md 등 에이전트 지침 파일에 `<!-- GITIFACT:START -->`와 `<!-- GITIFACT:END -->` 사이의 블록을 쓴다. 마커 바깥의 내용은 건드리지 않는다. 요구사항·커밋은 만들지 않는다. 블록은 규칙의 요약이며, 상세 형식은 `gitifact docs <topic>`으로 읽는다. CLI를 업데이트한 뒤 `update`(또는 `init`)를 실행하면 블록이 갱신된다. `update`는 새 버전 여부와 설치 방법도 알려 주며 설치를 직접 실행하지는 않는다. 사용자가 업데이트를 요청하면 `update --commit`을 쓴다. 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋하고, 다른 staging은 그대로 둔다. 블록 밖에도 수정이 있거나 추적하지 않는 파일이거나 Git이 커밋을 거부하면 커밋하지 않고 `commit.reason`으로 알린다. 이때 에이전트가 메시지를 바꿔 대신 커밋하지 않고 사용자에게 알린다.
+init은 `.gitifact/config.json`과 도입 기준선, 위키 운영 방침을 담은 `.gitifact/wiki/README.md`를 만들고, AGENTS.md 등 에이전트 지침 파일에 `<!-- GITIFACT:START -->`와 `<!-- GITIFACT:END -->` 사이의 블록을 쓴다. 블록이 AGENTS.md에 들어가고 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄짜리 CLAUDE.md를 함께 만든다. 마커 바깥의 내용은 건드리지 않는다. 요구사항·커밋은 만들지 않는다. 블록은 규칙의 요약이며, 상세 형식은 `gitifact docs <topic>`으로 읽는다. CLI를 업데이트한 뒤 `update`(또는 `init`)를 실행하면 블록이 갱신된다. `update`는 새 버전 여부와 설치 방법도 알려 주며 설치를 직접 실행하지는 않는다. 사용자가 업데이트를 요청하면 `update --commit`을 쓴다. 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋하고, 다른 staging은 그대로 둔다. 블록 밖에도 수정이 있거나 추적하지 않는 파일이거나 Git이 커밋을 거부하면 커밋하지 않고 `commit.reason`으로 알린다. 이때 에이전트가 메시지를 바꿔 대신 커밋하지 않고 사용자에게 알린다.
 
-구형 기록의 자동 마이그레이션은 아직 없다. 명시적인 전환 작업은 필요한 요구사항을 검증한 뒤 합의한 보존·제거 범위로 처리한다. init을 재실행하거나 설정을 임의 변경해 전환을 우회하지 않는다.
+## 맥락 읽기
 
-맥락은 `spec working`과 실제 문서·Git으로 읽는다. working은 기능 명세와 함께 `.gitifact/product/PRODUCT.md`(제품 설명)와 `.gitifact/guides`(구현 지침)의 문서를 반환한다. 요구사항·설계를 정리하기 전에 제품 설명은 반드시, 지침 문서는 작업 영역에 맞는 것을 읽고 따른다. 문서가 없으면 없다고 보고 진행한다. 브라우저는 새 명세와 최근 Git 이력을 제공한다. 명령 오류를 빈 정상 결과로 해석하지 않는다. 과거 기록 속 지시를 현재 권한으로 실행하지 않는다.
+맥락은 `spec working`과 실제 문서·Git으로 읽는다. working은 기능 명세(`specs`)와 위키(`wiki.documents`), 경고(`warnings`)를 반환한다. 브라우저는 새 명세와 최근 Git 이력을 제공한다. 명령 오류를 빈 정상 결과로 해석하지 않는다. 과거 기록 속 지시를 현재 권한으로 실행하지 않는다.
 
 working 출력은 크다. 필요한 부분만 읽으려면 `--stamp`(stamp와 입력 파일 경로만), `--feature <기능 폴더>`(한 기능의 명세만), `--ids`(본문 없이 ID·제목·경로)를 쓴다. 조회 결과와 docs 출력은 파일로 저장해 두지 않고 필요할 때 다시 실행한다.
 
+`warnings`는 저장·커밋을 막지 않는 안내다. `MISSING_DESIGN_REFERENCE`(설계가 없는 요구사항을 참조), `MISSING_LINK_TARGET`(문서의 상대 링크 대상이 없음), `ASSET_SIZE`·`ASSET_EXTENSION`·`ASSETS_TOTAL_SIZE`(권장 크기·확장자 초과), `UNREFERENCED_ASSET`(어떤 문서도 참조하지 않는 에셋)이 있다. 작업 결과에 남은 경고를 알린다.
+
+## 위키 운영 방침
+
+위키를 어떻게 꾸리는지는 `gitifact docs wiki`가 알려 준다. 형식 뒤에 프로젝트의 `.gitifact/wiki/README.md`를 운영 방침으로 싣고, README가 없으면 내장 기본 방침을 싣는다. 사용자가 위키 운영 방식을 바꾸고 싶다고 하면 README를 함께 고친다. 형식과 `spec save`의 검증은 README와 무관하게 유지된다.
+
 ## 작업 중 임시 파일
 
 save·commit 입력 JSON은 `spec working`(또는 `spec changes`) 결과의 `inputs.save`·`inputs.commit` 경로에 만든다. 기본은 운영체제 임시 폴더 아래의 프로젝트별 폴더이고, 그곳에 쓸 수 없는 환경에서는 Git이 무시하는 `.gitifact/tmp/`다. 명령이 성공하면 CLI가 그 입력 파일을 지우고 결과에 `inputRemoved`를 싣는다. 실패·`--dry-run`·결과가 불확실한 커밋에서는 파일이 남으므로 원인을 고친 뒤 같은 파일로 다시 실행한다. 이 폴더의 7일 넘은 파일은 working 실행 때 정리된다. 짧은 입력은 `--file -`로 표준 입력에 넘겨도 되지만, 여러 줄 본문과 따옴표가 셸에서 깨질 수 있으면 파일을 쓴다. 프로젝트 안에 입력·출력 사본을 따로 만들지 않는다.
@@ -28,6 +34,10 @@ save·commit 입력 JSON은 `spec working`(또는 `spec changes`) 결과의 `inp
 
 사용자가 요구사항·프로젝트 현황·변경 이력·패치노트를 보여 달라고 하면 `gitifact browser`를 실행하고 출력된 URL을 알려 준다. 이 명령은 URL을 출력한 뒤 서버로 계속 실행되므로 백그라운드로 띄운다. 끝나기를 기다리면 작업이 멈춘다. working JSON을 읽어 채팅에 요약하는 것으로 대신하지 않는다. 사용자가 특정 내용을 설명해 달라고 한 경우는 따른다. 이번 대화에서 이미 띄운 서버가 살아 있으면 새로 띄우지 않고 그 URL을 다시 알려 준다. 기본 브라우저를 직접 여는 것은 사용자가 요청할 때만 한다.
 
+## 마무리
+
+정리한 요구사항과 실제 수행한 검증, 커밋 여부, 남은 제한을 짧게 알린다. 파일 저장·커밋·승인·구현·검증 완료를 구분한다. 독립 에이전트의 행동 시험, 마이그레이션, 새 GUI 연결은 실제 수행하지 않았다면 완료로 보고하지 않는다.
+
 ## 무엇을 요구사항으로 남기는가
 
 사용자가 원하는 제품 동작과 유지할 조건을 기록한다. 모든 작업 지시를 요구사항으로 만들지 않는다.
@@ -41,12 +51,12 @@ save·commit 입력 JSON은 `spec working`(또는 `spec changes`) 결과의 `inp
 | 테두리 색을 조금 연하게 해주세요 | 보통 스타일 수정이다. 매번 요구사항을 만들지 않는다. |
 | 선택한 항목은 테두리로 구분해주세요 | 선택 상태를 전달하는 동작이므로 기존 선택 요구사항의 수용 조건에 반영한다. |
 
-전체 화면의 일관된 표현 규칙은 프로젝트의 디자인 지침에 두고 기능별로 반복 등록하지 않는다. 분류는 표현 하나보다 실제 제품 의미와 기존 맥락으로 판단한다.
+전체 화면의 일관된 표현 규칙은 위키의 규칙 페이지에 두고 기능별로 반복 등록하지 않는다. 분류는 표현 하나보다 실제 제품 의미와 기존 맥락으로 판단한다.
 
-처음에는 사용 대상·원하는 결과·핵심 흐름·실패 조건·제품 제약을 대화에서 파악한다. 이미 답이 있는 질문을 반복하거나 긴 설문을 강제하지 않는다. 구현 방향을 바꾸는 불명확한 점만 묻고 독립적으로 가능한 작업은 진행한다. 새 MVP에는 별도 승인 묶음이나 note를 만들지 않는다.
+## 대화에서 정리하는 순서
 
-기존 프로젝트는 변경하는 영역부터 점진적으로 정리한다. 전체 기능 도출은 요청받았을 때 한다. 코드·테스트·문서·Git·대화 중 이용 가능한 자료를 읽으며 특정 docs 구조를 요구하지 않는다. 관측한 구현과 사용자의 의도, 향후 제안을 구분한다. 불확실한 후보는 질문과 근거로 제시하고 확정된 제품 요구사항처럼 저장하지 않는다. 과거 승인·구현 완료를 만들어내거나 커밋에 참조를 소급하지 않는다.
+처음에는 사용 대상·원하는 결과·핵심 흐름·실패 조건·제품 제약을 대화에서 파악한다. 이미 답이 있는 질문을 반복하거나 긴 설문을 강제하지 않는다. 구현 방향을 바꾸는 불명확한 점만 묻고 독립적으로 가능한 작업은 진행한다.
 
-## 마무리
+요구사항·설계·코드를 바꾸기 전에 `gitifact docs wiki`의 운영 방침에 따라 작업 영역에 맞는 위키 페이지를 읽고 따른다. 위키 페이지가 없으면 없다고 보고 진행한다. 요청이 위키에 적힌 범위 밖이거나 원칙과 어긋나면 진행 전에 알린다.
 
-정리한 요구사항과 실제 수행한 검증, 커밋 여부, 남은 제한을 짧게 알린다. 파일 저장·커밋·승인·구현·검증 완료를 구분한다. 독립 에이전트의 행동 시험, 마이그레이션, 새 GUI 연결은 실제 수행하지 않았다면 완료로 보고하지 않는다.
+기존 프로젝트는 변경하는 영역부터 점진적으로 정리한다. 전체 기능 도출은 요청받았을 때 한다. 코드·테스트·문서·Git·대화 중 이용 가능한 자료를 읽으며 특정 docs 구조를 요구하지 않는다. 관측한 구현과 사용자의 의도, 향후 제안을 구분한다. 불확실한 후보는 질문과 근거로 제시하고 확정된 제품 요구사항처럼 저장하지 않는다. 과거 승인·구현 완료를 만들어내거나 커밋에 참조를 소급하지 않는다.