Overview

RAGit is a local-first RAG CLI for git-based AI agent workflows. It captures project documents and context, then binds retrieval snapshots to commit SHA.

Product Purpose

RAGit is a local-first RAG CLI that turns AI agent project documents and context into commit-bound, reusable knowledge inside the repository.

Core Value

Preserve project context across AI agent work
Reproduce knowledge at a specific commit state
Turn structured docs into agent-ready inputs
Automate indexing without adding workflow friction

License

RAGit is licensed under Apache-2.0. The root LICENSE file is the single source of truth for license terms across this repository.

What You Get

Commit-bound retrieval snapshots
Hybrid search (vector + keyword)
Agent-friendly context packing
A split memory model for active work and durable knowledge
Secure ingestion with secret masking

Document types are not storage formats. They tell RAGit what role a document plays inside collaborative memory, so the next agent can tell whether a file is about product intent, system requirements, implementation contracts, decisions, or topology. The acronyms below are shorthand for the canonical document names, so first-time readers can map the role and the label together immediately.

Type	Use it when	Main output	Common boundary
`Architecture Decision (ADR)`	You need to record a decision and why you chose it	Decision, rationale, consequences	Not an execution checklist like `Plan`
`Product Requirement (PRD)`	You are defining the product problem, users, goals, and success criteria	Product intent and acceptance outcomes	Not a system contract like `Software Requirements (SRS)`
`Software Requirements (SRS)`	You are defining what the system must do end to end	Functional and non-functional requirements	Not implementation detail like `Implementation Specification (SPEC)`
`Implementation Specification (SPEC)`	You are pinning down module behavior, interfaces, state, and validation	Implementation contract	Not topology explanation like `Phase and Binding Documents (PBD)`
`Plan`	You are organizing milestones, tasks, and delivery sequence	Execution plan and work breakdown	Not a durable decision record like `ADR`
`Domain-Driven Design (DDD)`	You are modeling bounded contexts, aggregates, and domain structure	Domain model and conceptual boundaries	Not a simple term dictionary like `Glossary`
`Glossary`	You need one stable meaning for recurring terms	Shared vocabulary	Not a domain model or architecture map like `DDD`
`Phase and Binding Documents (PBD)`	You are explaining phase topology, bindings, interaction paths, and drift points	Topology and binding map	Not a feature-by-feature contract like `Implementation Specification (SPEC)`

Quick Distinctions

Product Requirement (PRD) vs Software Requirements (SRS): PRD answers why the product exists and what outcome matters. SRS answers what the system must provide.
Software Requirements (SRS) vs Implementation Specification (SPEC): SRS stays at the system contract level. SPEC moves down to implementation behavior, interfaces, and acceptance details.
Implementation Specification (SPEC) vs Phase and Binding Documents (PBD): SPEC explains what one implementation unit must do. PBD explains how phases and bindings are arranged across units.
Architecture Decision (ADR) vs Plan: ADR records a stable decision. Plan records the sequence of work to execute.
Domain-Driven Design (DDD) vs Glossary: DDD models structure and boundaries in the domain. Glossary stabilizes the meaning of recurring terms.

SAD/HLD/LLD Compatibility Layer

SAD, HLD, and LLD are supported as external architecture views, not as new canonical document types. They help teams map familiar architecture language onto RAGit's existing document system without changing ingest or retrieval semantics.

External view	Use it when	Primary RAGit mapping
`SAD`	You are explaining the whole system shape, major constraints, and architecture direction	Architecture overview plus related `ADR` documents, with `SRS` or `PBD` when needed
`HLD`	You are explaining module boundaries, flows, and higher-level topology	`SRS`, `DDD`, and `PBD`
`LLD`	You are locking down implementation-unit behavior, interfaces, and state	`SPEC`

If authors want to make that view explicit, they can add an optional frontmatter hint:

---
type: spec
architecture_view: lld
---

architecture_view is advisory only. RAGit still classifies documents by canonical type, so SPEC, SRS, DDD, PBD, and ADR remain the source of truth for document behavior.

Why RAGit Keeps `SPEC` and `PBD` Separate

SPEC is optimized for questions like "what should this module do?" and "what interface contract must be preserved?"
PBD is optimized for questions like "how do phases connect?" and "where can drift or failure happen between parts?"
Keeping them separate makes retrieval more precise for agents that need either feature-level contracts or topology-level reasoning.

Where To Start

If you are defining a new feature or workflow, start with PRD, then move to SRS, and finally SPEC.
If you already know the feature and need to explain one implementation unit, start with SPEC.
If the hard part is coordination between phases, components, or agents, add a PBD.
If you are locking in a choice between alternatives, write an ADR.
If the team keeps reusing the same term with different meanings, add a Glossary. If the confusion is about domain boundaries, add DDD.

Read Getting Started if you are applying RAGit to a new project. Read Quickstart if you want a short map of the docs and paths. If you are setting up the authoring system inside a repository, read Init Guide. If you want command-by-command guidance with examples and option details, start at Commands. If you want to understand why memory is split across control-plane state and searchable docs, read Memory Model Guide. If you are integrating RAGit into an agent workflow, read Agent CLI Contract for --format json, --view minimal, --input, and --dry-run rules.