init

Inspect a repository, reuse existing knowledge sources, and bootstrap RAGit foundations

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 state or planned state during --dry-run.

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

init

On this page