init

What It Does

init is a discover-first bootstrap command. It normalizes to the repository root, checks Git context, scans the repository, classifies it as empty, existing, docs-heavy, or monorepo, evaluates documentation coverage/maturity, plans missing foundational docs, and then bootstraps the control plane and local zvec store.

When To Use / When Not To Use

When to use it

• You are setting up RAGit in a repository for the first time.
• You want existing docs to be reused before new draft docs are generated.
• You want a machine-readable initialization report for agents or CI.

When not to use it

• If you are onboarding a new project, start with Getting Started first.
• You only want searchable knowledge. Use ingest after init.
• You only want current health/status checks. Use status or doctor.

Syntax

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]

Arguments And Options

• --cwd <path>: Run initialization against another repository path. If the path is inside a Git worktree, init anchors to the repository root.
• --yes: Accept defaults and skip prompts.
• --non-interactive: Same intent as --yes, useful in scripted flows.
• --mode auto|empty|existing|monorepo|docs-heavy: Override repository mode detection. Default is auto.
• --strategy minimal|balanced|full: Control how aggressively stage-1 foundational docs are generated. Default is balanced.
• --dry-run: Compute the full report without writing files or bootstrapping storage.
• --merge-existing: Reuse existing docs as primary sources before creating draft files. This is the default behavior.
• --git-init: Create a git repository automatically in non-interactive mode.
• --output text|json|both: Choose the human summary, JSON summary, or both.

Input And Output Contract

• Input is flag-based only. There is no --input <path|-> payload mode.
• JSON output includes:
  • executionMode
  • repositoryMode
  • strategy
  • scan
  • coverage
  • maturity
  • knowledgeMap
  • actions
  • bootstrap
  • nextActions
• actions reports planned create/reuse/skip outcomes for stage-1 foundational docs.
• bootstrap reports the AGENTS/guide/zvec/gitignore state or planned state during --dry-run.
• bootstrap.gitignore includes the selected policy, all planned entries, entries already present, and entries that were or would be added.

Gitignore Policy

Interactive init asks whether to keep commit-bound snapshot manifests and reviewed harness artifacts in Git. The safe default ignores local runtime state:

• .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/

Use --yes or --non-interactive to accept that safe policy without prompts. In interactive dogfooding workflows, choose to keep .ragit/manifest/ or .ragit/artifacts/harness/ tracked when snapshot history or reviewed harness assets are part of the repository contract.

Choose the policy by repository type:

During a human terminal run, the prompts map to those policies:

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

Use --dry-run --output json to preview the exact entries before mutating .gitignore. The relevant fields are:

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

Examples

Human terminal flow:

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

Agent-oriented flow:

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

Preview-only flow:

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

Failures And Cautions

• In non-interactive mode, init fails if the directory is not a git repository and --git-init is missing.
• In TTY-less environments, interactive mode is not available.
• --dry-run performs repository analysis but does not write files or create the zvec store.
• --dry-run reports the .gitignore policy and entries that would be added, but does not edit .gitignore.
• zvec bootstrap currently supports darwin/arm64, linux/arm64, and linux/x64.
• init can inspect repository docs, but it still does not make the repository search-ready. Run ingest after setup.

Related Commands

• ingest
• status
• doctor
• hooks install