Init Guide

If you are applying RAGit to a new project, start with Getting Started first. The repository init command is now a discover-first bootstrap flow. It still anchors to the repository root, still prepares .ragit/**, AGENTS.md, guide assets, and the empty zvec store, but it does that only after it scans the repository and decides what knowledge already exists.

Flow

1. Check Git context and optionally run git init
2. Scan repository code/docs/build files
3. Select empty, existing, docs-heavy, or monorepo mode
4. Run documentation census, coverage scoring, and maturity scoring
5. Build a knowledge-slot map from existing repository sources
6. Plan missing foundational docs and reuse existing sources first
7. Write stage-1 drafts and bootstrap .ragit/**
8. Select the .gitignore policy for RAGit runtime data
9. Bootstrap the zvec store
10. Print the final report and next actions

Stage-1 generated docs

init can generate only these draft docs in stage 1:

• RAGIT.md
• docs/workspace-map.md
• docs/ragit/ingestion-policy.md
• docs/known-gaps.md
• docs/adr/README.md

Every generated doc is marked as inferred draft content so humans can distinguish generated scaffolding from validated repository truth.

What init prepares

• Git-aware repository normalization
• Existing-doc discovery and coverage evaluation
• Draft foundational docs for missing gaps only
• .ragit/config.toml
• .ragit/guide/templates/*
• .ragit/guide/guide-index.json
• .gitignore entries for the selected runtime-data policy
• .ragit/store/meta.json
• Empty zvec collections for documents and chunks

What init does not prepare

• No searchable corpus
• No chunk/document record creation in zvec
• No snapshot manifests
• No query-ready knowledge state

init can inspect repository docs, but searchable knowledge still begins with ingest.

Git Tracking Choices

init separates durable project knowledge from local runtime state. The safe policy is the default for --yes and --non-interactive; it keeps generated runtime state out of Git. In an interactive terminal run, answer the manifest and harness questions differently only when those files are part of your repository contract.

After init, git status should normally show project-facing files such as .ragit/config.toml, .ragit/guide/**, .ragit/docs/index.json, AGENTS.md, RAGIT.md, and generated docs/** drafts. It should not show .ragit/store/**, .ragit/cache/**, .ragit/log/**, .ragit/reports/**, .ragit/security/**, .ragit/memory/sessions/**, .ragit/memory/working/**, or .ragit/artifacts/session/**.

Representative scenarios

Empty repository

• pnpm ragit init --yes --git-init
• Mode selected: empty
• Expected result: foundational drafts plus control-plane/bootstrap assets

Existing codebase

• pnpm ragit init
• Mode selected: existing
• Expected result: existing docs are reused, missing drafts are added, no core docs are overwritten

Docs-heavy repository

• pnpm ragit init
• Mode selected: docs-heavy
• Expected result: high reuse ratio, low generated-doc count

Monorepo

• pnpm ragit init
• Mode selected: monorepo
• Expected result: apps/packages are reflected in the workspace map and knowledge map

Dry-run

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

Expected result:

• full scan/coverage/maturity report
• planned create/reuse/skip actions
• planned .gitignore policy and entries under bootstrap.gitignore
• no file system mutations

Non-interactive examples

pnpm ragit init --yes
pnpm ragit init --yes --git-init
pnpm ragit init --mode auto --strategy balanced --merge-existing --output json
pnpm ragit init --dry-run --output json

Generated structure

RAGIT.md
docs/
  adr/README.md
  known-gaps.md
  ragit/ingestion-policy.md
  workspace-map.md
.ragit/
  config.toml
  guide/
    guide-index.json
    templates/
  store/
    meta.json
    documents/
    chunks/