init

무엇을 하는 명령인가

init은 discover-first bootstrap 명령입니다. 저장소 루트로 정규화한 뒤 Git 문맥을 확인하고, 저장소를 스캔하고, empty, existing, docs-heavy, monorepo 중 하나로 분류하며, 문서 coverage/maturity를 평가하고, 누락된 기초 문서를 계획한 뒤 control plane과 로컬 zvec store를 부팅합니다.

언제 쓰는가 / 언제 쓰지 않는가

언제 쓰는가

• 저장소에서 RAGit을 처음 설정할 때
• 기존 문서를 우선 재사용하고 부족한 초안만 생성하고 싶을 때
• 에이전트나 CI가 읽을 수 있는 initialization report가 필요할 때

언제 쓰지 않는가

• 신규 프로젝트 onboarding을 처음 따라갈 때는 Getting Started부터 읽으십시오.
• searchable knowledge만 필요할 때. init 이후 ingest를 실행하십시오.
• 현재 상태 점검만 필요할 때. status 또는 doctor를 사용하십시오.

기본 구문

pnpm ragit init [--cwd <path>] [--yes|--non-interactive] \
  [--mode auto|empty|existing|monorepo|docs-heavy] \
  [--strategy minimal|balanced|full] [--dry-run] \
  [--merge-existing] [--git-init] \
  [--output text|json|both]

인자와 옵션

• --cwd <path>: 다른 저장소 경로를 대상으로 실행합니다. Git worktree 내부 경로를 주면 저장소 루트 기준으로 정규화됩니다.
• --yes: 기본값을 수락하고 질문을 건너뜁니다.
• --non-interactive: --yes와 같은 의도로 비대화형 실행을 강제합니다.
• --mode auto|empty|existing|monorepo|docs-heavy: 저장소 모드 자동 판정을 덮어씁니다. 기본값은 auto입니다.
• --strategy minimal|balanced|full: 1단계 기초 문서 생성 강도를 제어합니다. 기본값은 balanced입니다.
• --dry-run: 파일을 쓰지 않고 전체 리포트만 계산합니다.
• --merge-existing: 기존 문서를 1차 소스로 우선 재사용합니다. 기본 동작입니다.
• --git-init: 비대화형 모드에서 git 저장소를 자동 생성합니다.
• --output text|json|both: 사람이 읽는 요약, JSON 요약, 둘 다 중 하나를 선택합니다.

입력/출력 계약

• 이 명령은 플래그 입력만 지원합니다. --input <path|-> payload 모드는 없습니다.
• JSON 출력에는 다음 키가 포함됩니다.
  • executionMode
  • repositoryMode
  • strategy
  • scan
  • coverage
  • maturity
  • knowledgeMap
  • actions
  • bootstrap
  • nextActions
• actions는 1단계 기초 문서에 대한 create/reuse/skip 계획을 보고합니다.
• bootstrap은 실제 AGENTS/guide/zvec/gitignore 상태 또는 --dry-run일 때 계획 상태를 보고합니다.
• bootstrap.gitignore에는 선택된 policy, 전체 planned entries, 이미 있던 entries, 실제 추가됐거나 추가될 entries가 포함됩니다.

Gitignore 정책

대화형 init은 commit-bound snapshot manifest와 reviewed harness artifact를 Git에 보관할지 묻습니다. 안전 기본값은 다음 로컬 실행 상태를 ignore합니다.

• .ragit/store/, .ragit/store.next/, .ragit/store.prev/
• .ragit/cache/
• .ragit/log/
• .ragit/reports/
• .ragit/security/
• .ragit/memory/sessions/, .ragit/memory/working/
• .ragit/artifacts/session/
• .ragit/manifest/
• .ragit/artifacts/harness/

--yes 또는 --non-interactive를 쓰면 질문 없이 이 안전 정책을 적용합니다. dogfooding 저장소처럼 snapshot history 또는 reviewed harness asset이 저장소 계약의 일부라면 대화형 선택에서 .ragit/manifest/ 또는 .ragit/artifacts/harness/를 Git에 남기도록 선택하십시오.

저장소 성격에 따라 정책을 고르십시오.

사람이 터미널에서 실행하면 다음 질문이 정책으로 매핑됩니다.

commit-bound snapshot manifest(.ragit/manifest/)를 Git에 보관하시겠습니까? [y/N]
reviewed harness artifact(.ragit/artifacts/harness/)를 Git에 보관하시겠습니까? [y/N]

.gitignore를 실제로 바꾸기 전에 정확한 entries를 보려면 --dry-run --output json을 사용하십시오. 관련 필드는 다음과 같습니다.

{
  "bootstrap": {
    "gitignore": {
      "policy": "safe",
      "plannedEntries": [".ragit/store/", ".ragit/manifest/"],
      "addedEntries": [".ragit/manifest/"],
      "existingEntries": [".ragit/store/"]
    }
  }
}

대표 사용 예시

사람용 터미널 예시:

pnpm ragit init --mode auto --strategy balanced --merge-existing

에이전트 호출 예시:

pnpm ragit init --yes --git-init --output json

미리보기 예시:

pnpm ragit init --dry-run --output json

실패/주의 사항

• 비대화형 모드에서 git 저장소가 아니고 --git-init도 없으면 실패합니다.
• TTY가 없는 환경에서는 대화형 모드를 사용할 수 없습니다.
• --dry-run은 저장소 분석은 수행하지만 파일과 zvec store는 만들지 않습니다.
• --dry-run은 .gitignore에 추가될 policy와 entries를 보고하지만 .gitignore 파일은 수정하지 않습니다.
• RAGit은 Node.js 22.14 이상이 필요합니다. zvec bootstrap은 darwin/arm64, linux/arm64를 지원하며, 그 외 대상에서는 native binding을 로드하기 전에 지원 매트릭스와 함께 실패합니다.
• init은 저장소 문서를 읽고 분류할 수 있지만, 저장소를 search-ready 상태로 만들지는 않습니다. 초기화 후 ingest를 실행하십시오.

관련 명령

• ingest
• status
• doctor
• hooks install