own-rag-cli 0.0.2-snapshot → 0.0.4-snapshot

package/README.md

@@ -1,84 +1,75 @@
-# MCP binary checksum (SHA-256, payload without shebang): `74bb1de161e5ebeef6691397fc1403bc58c221b9302f67fd770b1097f8ff76d8`
-
 # own-rag
 
-Local RAG for codebases with:
-- ChromaDB (Docker)
-- MCP server (`mcp-rag-server`)
-- CPU embeddings (`jina`, `bge`, `hybrid`)
-- Cross-platform setup (`Linux` and `macOS`)
+Local RAG for codebases with ChromaDB + MCP, focused on practical setup and lower LLM token waste.
+
+Language: English (default) | Portuguese: `README.pt-br.md`
+
+## Why use own-rag
 
-## Why this repo
+Without local retrieval, an AI assistant often scans many files or asks you to paste large chunks of code, which increases token usage and slows iteration. With `own-rag`, your repository is indexed once and exposed via MCP tools, so the assistant can fetch only the most relevant files/chunks.
 
-`own-rag` lets you index local projects and query them from MCP-compatible tools (Claude/Cursor).
+Example:
+- Without RAG: asking "where is `MedicationController` used?" may trigger broad project reads.
+- With MCP + own-rag: retrieval points directly to likely files first, so the assistant reads less and answers faster.
 
-It includes:
-- installers: `rag-setup.run`, `rag-setup-macos.run`
-- MCP server source: `bin/mcp_server.py`
-- indexer source: `bin/indexer_full.py`
-- monitor and wrapper scripts
+Immediate MCP targets are Claude Code and Cursor, but the server can be used by any MCP-capable client.
 
-## Source vs Artifact
+## What gets installed
 
-This repo is fully auditable:
-- source of logic: `bin/*.py` and `bin/*.sh`
-- generated artifacts: `rag-setup.run`, `rag-setup-macos.run`
+- ChromaDB container (Docker)
+- Python virtual environment (`~/.rag_venv`)
+- MCP server binary (`~/.local/bin/mcp-rag-server`)
+- Setup runners (`rag-setup.run`, `rag-setup-macos.run`)
+- CLI wrapper command: `rag`
 
-To refresh embedded payloads from source files:
+## Install and run
+
+### Option A: npm (recommended)
 
 ```bash
-./bin/build_run.sh
-./bin/build_run_macos.sh
+npm install -g own-rag-cli
+rag run /path/to/your/project
 ```
 
-## Quick Start
+If you run `rag run` without a path, it asks whether to use the current directory.
+
+### Option B: direct `.run`
 
-### Linux
+Linux:
 
 ```bash
 chmod +x rag-setup.run
-./rag-setup.run /path/to/project
+./rag-setup.run /path/to/your/project
 ```
 
-### macOS
+macOS:
 
 ```bash
 chmod +x rag-setup-macos.run
-./rag-setup-macos.run /path/to/project
+./rag-setup-macos.run /path/to/your/project
 ```
 
-### NPM wrapper
+## Main commands
 
 ```bash
-rag run /path/to/project
-rag monitor
-rag remove
+rag run /path/to/project        # full setup + indexing
+rag monitor                     # interactive Chroma monitor
+rag monitor full                # full monitor dashboard
+rag remove                      # full local uninstall (double confirmation)
+rag remove --force              # uninstall without confirmation prompts
 ```
 
-## What setup does
-
-1. Creates `~/.rag_venv` and installs dependencies.
-2. Starts ChromaDB in Docker with persistent volume (`~/.rag_db`).
-3. Installs `mcp-rag-server` in `~/.local/bin`.
-4. Optionally updates MCP config files (`.claude.json`, Cursor config).
-5. Indexes the project.
+## Configuration files and paths
 
-## Permissions and Tuning Config
+### 1) Runtime config (CLI-level)
 
-- Autotune/indexer tuning is persisted by default in:
-  - `~/.cache/own-rag-cli/indexer_tuning.json`
-- This avoids permission issues when `~/.rag_db` is owned by `root`.
-- If you want to store tuning inside `~/.rag_db`, grant permissions and set:
+Path: `~/.own-rag-cli.json`
 
-```bash
-sudo chown -R "$USER":"$USER" ~/.rag_db
-export MCP_INDEXER_CONFIG_FILE="$HOME/.rag_db/indexer_tuning.json"
-```
+Purpose:
+- Stores Chroma endpoint and last known indexing batch values.
+- Used as the simplest user-facing config to move between machines or switch endpoint.
 
-## Chroma Endpoint Config
-
-- Runtime config file: `~/.own-rag-cli.json`
-- Default generated content:
+Example:
 
 ```json
 {
@@ -94,79 +85,203 @@ export MCP_INDEXER_CONFIG_FILE="$HOME/.rag_db/indexer_tuning.json"
 }
 ```
 
-- You can point to remote ChromaDB by changing `scheme`, `host`, and `port`.
-- `indexing.embedding_batch_size` / `indexing.batch_count` are updated after indexing/autotune.
-- `rag-setup.run` / `rag-setup-macos.run` persist chosen values into this file.
-- If `host` is not local (`localhost`, `127.0.0.1`, `::1`), setup skips local Docker startup.
+Field meaning:
+- `chroma.scheme`: `http` or `https`.
+- `chroma.host`: Chroma host (`localhost`, IP, or DNS).
+- `chroma.port`: Chroma TCP port.
+- `indexing.embedding_batch_size`: batch size used by embedding encode.
+- `indexing.batch_count`: mirrored batch value for explicit readability.
+
+If you edit this file manually:
+1. Save the file.
+2. Restart tools that consume MCP (Claude/Cursor).
+3. If you changed model/chunk/batch strategy, run reindex (`rag run <project>` or `--only-index`) so stored vectors match new settings.
+
+### 2) Indexer tuning config
+
+Path: `~/.cache/own-rag-cli/indexer_tuning.json`
+
+Purpose:
+- Persists model/profile/tuning decisions (`chunk_size`, `chunk_overlap`, `embedding_batch_size`, etc.).
+- Loaded by both indexer and MCP server to keep behavior consistent across re-runs.
+
+### 3) Database and runtime directories
+
+- Chroma data: `~/.rag_db`
+- Python venv: `~/.rag_venv`
+- Installed binaries/scripts: `~/.local/bin/`
+
+### 4) MCP client config files (optional auto-update)
+
+- Claude Code: `~/.claude.json`
+- Cursor: `~/.cursor/mcp.json`
+- Cursor (alt paths): `~/.config/Cursor/User/mcp.json` or `~/Library/Application Support/Cursor/User/mcp.json`
 
-## ChromaDB Port Behavior (Local)
+## Choosing the embedding model (practical guidance)
 
-- Default host port is `8000`.
-- During ChromaDB install/reinstall, setup asks for the port.
-- The installer checks if the chosen port is already in use using native tools:
-  - Linux: `ss` (fallback: `lsof` / `netstat`)
-  - macOS: `lsof` (fallback: `netstat`)
-- If the port is busy, it asks for another one.
-- In non-interactive runs, it auto-selects the next free port.
-- Selected port is propagated to:
-  - Docker Compose mapping
-  - health checks
-  - `~/.own-rag-cli.json`
-  - indexer runtime (`MCP_CHROMA_PORT`)
+These are practical CPU-memory guidelines. Real usage depends on project size and concurrent processes.
 
-## Performance Profiles
+| Choice | Use case | Approx RAM target |
+|---|---|---|
+| `bge` (`BAAI/bge-m3`) | mixed docs + code, safer memory | 8-16 GiB |
+| `jina` (`jinaai/jina-embeddings-v3`, default) | code-focused quality | 32-64 GiB (48+ GiB preferred) |
+| `hybrid` (`jina v2 + bge`) | two collections, broader retrieval strategy | 24-48 GiB |
 
-Available in indexer/setup:
-- `autotune` (recommended): uses local machine metrics and short benchmark.
-- `max-performance`: higher throughput and higher memory usage risk.
+Notes:
+- Jina on CPU is heavy; with low free RAM/swap, slowdowns or OOM (`exit 137`) can happen.
+- If your machine is memory-limited, start with `bge`.
 
-`max-performance` warning shown by setup:
+## Performance profile
 
-```text
-Este modo pode elevar consideravelmente o consumo de memória e causar encerramento por OOM (exit 137).
+During setup/indexing:
+
+- `autotune` (recommended):
+  - Runs a short local benchmark (`model.encode`) with `psutil` metrics.
+  - Targets cost-benefit (not too aggressive, not too conservative).
+  - Automatically adjusts `MCP_EMBEDDING_BATCH_SIZE`, `MCP_CHUNK_SIZE`, `MCP_CHUNK_OVERLAP`.
+
+- `max-performance`:
+  - Uses more aggressive throughput-oriented parameters.
+  - Shows explicit memory-risk warning.
+
+## Chroma endpoint behavior
+
+- Default local endpoint is `http://localhost:8000`.
+- Setup checks if selected port is already in use.
+- If `~/.own-rag-cli.json` points to a remote host, local Docker startup is skipped.
+
+## Backup/snapshot before reinstall or machine migration
+
+Before running `rag remove`, formatting your machine, or moving to another machine, snapshot these files:
+
+```bash
+mkdir -p "$HOME/own-rag-backup"
+cp "$HOME/.own-rag-cli.json" "$HOME/own-rag-backup/" 2>/dev/null || true
+cp "$HOME/.cache/own-rag-cli/indexer_tuning.json" "$HOME/own-rag-backup/" 2>/dev/null || true
+
+tar -czf "$HOME/own-rag-backup/chromadb-ragdb-$(date +%Y%m%d-%H%M%S).tgz" -C "$HOME" .rag_db
 ```
 
-## Key Environment Variables
+Restore on a new machine:
+1. Install `own-rag-cli`.
+2. Restore `~/.own-rag-cli.json` and optional tuning file.
+3. Extract `.rag_db` backup into `$HOME`.
+4. Start with `rag run /path/to/project --skip-index` and validate search.
+5. If model/chunk settings changed, reindex.
 
-- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
-- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
-- `MCP_PERF_PROFILE=autotune|max-performance`
-- `OWN_RAG_CLI_CONFIG_FILE=~/.own-rag-cli.json`
-- `MCP_CHROMA_SCHEME=http|https`
-- `MCP_CHROMA_HOST=localhost|<host>`
-- `MCP_CHROMA_PORT=8000`
-- `MCP_CHUNK_SIZE`
-- `MCP_CHUNK_OVERLAP`
-- `MCP_EMBEDDING_BATCH_SIZE`
+## Common flows
 
-## Useful Commands
+### Reindex only (`--only-index`)
 
 ```bash
-# only index (infra already installed)
 ./rag-setup.run /path/to/project --only-index
+```
 
-# skip indexing
+Use when environment is already installed and you only changed project code/docs.
+
+### Skip index step (`--skip-index`)
+
+```bash
 ./rag-setup.run /path/to/project --skip-index
+```
 
-# force reinstall
-./rag-setup.run /path/to/project --reinstall
+Use when you want to refresh infra/config first (venv, Docker, MCP wiring), and index later.
 
-# force model change flow
+### Change model (`--change-model`)
+
+```bash
 ./rag-setup.run --change-model /path/to/project
 ```
 
-## Development
+Use when switching embedding strategy (`jina`, `bge`, `hybrid`). This may reset collections and requires full reindex so embeddings remain consistent.
+
+## Environment overrides
+
+Where to override:
+- Temporary for one shell/session: `export VAR=value` before `rag run`.
+- Persistent for MCP runtime: set env in your MCP client config (`~/.claude.json`, Cursor `mcp.json`).
+- Chroma endpoint can also be persisted in `~/.own-rag-cli.json`.
+
+What each variable does:
+
+- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
+  - Selects embedding strategy.
+  - After changing: reindex required.
+
+- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
+  - Jina CPU quantization mode.
+  - After changing: reindex recommended.
+
+- `MCP_PERF_PROFILE=autotune|max-performance`
+  - Chooses tuning strategy for chunk and batch decisions.
+  - After changing: rerun index setup to apply new tuning.
+
+- `MCP_EMBEDDING_BATCH_SIZE=<int>`
+  - Forces fixed embedding batch size (overrides autotune batch).
+  - After changing: restart MCP; reindex recommended for consistent throughput assumptions.
+
+- `MCP_CHUNK_SIZE=<int>`
+  - Sets chunk length for indexing.
+  - After changing: full reindex required.
+
+- `MCP_CHUNK_OVERLAP=<int>`
+  - Sets overlap between chunks.
+  - After changing: full reindex required.
+
+- `OWN_RAG_CLI_CONFIG_FILE=<path>`
+  - Moves runtime config location from default `~/.own-rag-cli.json`.
+  - After changing: restart setup/MCP tools.
+
+- `MCP_INDEXER_CONFIG_FILE=<path>`
+  - Moves tuning config location from default `~/.cache/own-rag-cli/indexer_tuning.json`.
+  - After changing: restart setup/MCP tools.
+
+- `MCP_CHROMA_SCHEME=http|https`
+- `MCP_CHROMA_HOST=<host>`
+- `MCP_CHROMA_PORT=<port>`
+  - Overrides Chroma endpoint.
+  - After changing: restart MCP clients; reindex only if switching to a fresh/empty database.
+
+## Checksum verification (`.run`)
+
+Manual verification (Linux/macOS):
+
+```bash
+sha256sum rag-setup.run
+sha256sum rag-setup-macos.run
+```
+
+On macOS without `sha256sum`:
+
+```bash
+shasum -a 256 rag-setup.run
+shasum -a 256 rag-setup-macos.run
+```
+
+## Source transparency
+
+Project logic is in source files (`bin/*.py`, `bin/*.sh`).
+Generated artifacts:
+
+- `rag-setup.run`
+- `rag-setup-macos.run`
+
+Rebuild artifacts after source changes:
+
+```bash
+./bin/build_run.sh
+./bin/build_run_macos.sh
+```
 
-- Edit source files in `bin/`.
-- Rebuild payloads with `./bin/build_run.sh` and `./bin/build_run_macos.sh`.
-- Validate before commit:
+## Validation before release
 
 ```bash
 bash -n rag-setup.run
 bash -n rag-setup-macos.run
-python3 -m py_compile bin/indexer_full.py
+python3 -m py_compile bin/indexer_full.py bin/mcp_server.py
+npm pack --dry-run
 ```
 
 ## License
 
-MIT (or your preferred OSS license file in this repo).
+MIT

package/README.pt-br.md

@@ -0,0 +1,287 @@
+# own-rag
+
+RAG local para codebases com ChromaDB + MCP, focado em setup prático e menor desperdício de tokens no uso de IA.
+
+Idioma: Português (PT-BR) | English: `README.md`
+
+## Por que usar o own-rag
+
+Sem recuperação local, a IA costuma ler muitos arquivos ou pedir grandes trechos de código, aumentando custo de tokens e tempo de resposta. Com `own-rag`, o repositório é indexado uma vez e exposto por ferramentas MCP, então a IA consulta primeiro os trechos mais relevantes.
+
+Exemplo:
+- Sem RAG: ao perguntar "onde `MedicationController` é usado?", a IA pode varrer boa parte do projeto.
+- Com MCP + own-rag: a recuperação aponta rapidamente para os arquivos com maior probabilidade, reduzindo leitura desnecessária.
+
+Os alvos imediatos por padrão são Claude Code e Cursor, mas o servidor pode ser usado por qualquer cliente compatível com MCP.
+
+## O que é instalado
+
+- Container ChromaDB (Docker)
+- Ambiente virtual Python (`~/.rag_venv`)
+- Binário MCP (`~/.local/bin/mcp-rag-server`)
+- Instaladores (`rag-setup.run`, `rag-setup-macos.run`)
+- Comando wrapper: `rag`
+
+## Instalação e execução
+
+### Opção A: npm (recomendado)
+
+```bash
+npm install -g own-rag-cli
+rag run /caminho/do/projeto
+```
+
+Se executar `rag run` sem caminho, o CLI pergunta se deve usar o diretório atual.
+
+### Opção B: `.run` direto
+
+Linux:
+
+```bash
+chmod +x rag-setup.run
+./rag-setup.run /caminho/do/projeto
+```
+
+macOS:
+
+```bash
+chmod +x rag-setup-macos.run
+./rag-setup-macos.run /caminho/do/projeto
+```
+
+## Comandos principais
+
+```bash
+rag run /caminho/do/projeto    # setup completo + indexação
+rag monitor                    # monitor interativo do Chroma
+rag monitor full               # painel completo do monitor
+rag remove                     # desinstalação completa local (dupla confirmação)
+rag remove --force             # desinstala sem prompts de confirmação
+```
+
+## Arquivos e caminhos de configuração
+
+### 1) Configuração de runtime (nível CLI)
+
+Caminho: `~/.own-rag-cli.json`
+
+Finalidade:
+- Guarda endpoint do Chroma e os últimos valores de batch de indexação.
+- É o arquivo mais simples para portar configuração entre máquinas.
+
+Exemplo:
+
+```json
+{
+  "chroma": {
+    "scheme": "http",
+    "host": "localhost",
+    "port": 8000
+  },
+  "indexing": {
+    "embedding_batch_size": 4,
+    "batch_count": 4
+  }
+}
+```
+
+Significado de cada variável:
+- `chroma.scheme`: protocolo (`http` ou `https`).
+- `chroma.host`: host do Chroma (`localhost`, IP ou DNS).
+- `chroma.port`: porta TCP do Chroma.
+- `indexing.embedding_batch_size`: tamanho do batch usado no encode de embeddings.
+- `indexing.batch_count`: espelho explícito do valor de batch para leitura humana.
+
+Se você editar esse arquivo manualmente:
+1. Salve o arquivo.
+2. Reinicie as ferramentas que usam MCP (Claude/Cursor).
+3. Se mudou estratégia de modelo/chunk/batch, rode reindexação (`rag run <projeto>` ou `--only-index`) para manter consistência dos vetores.
+
+### 2) Configuração de tuning do indexador
+
+Caminho: `~/.cache/own-rag-cli/indexer_tuning.json`
+
+Finalidade:
+- Persiste decisões de modelo/perfil/tuning (`chunk_size`, `chunk_overlap`, `embedding_batch_size`, etc.).
+- É lido por indexador e MCP server para manter consistência entre execuções.
+
+### 3) Diretórios de dados e runtime
+
+- Dados do Chroma: `~/.rag_db`
+- Venv Python: `~/.rag_venv`
+- Binários/scripts instalados: `~/.local/bin/`
+
+### 4) Arquivos de configuração MCP (auto-update opcional)
+
+- Claude Code: `~/.claude.json`
+- Cursor: `~/.cursor/mcp.json`
+- Cursor (caminhos alternativos): `~/.config/Cursor/User/mcp.json` ou `~/Library/Application Support/Cursor/User/mcp.json`
+
+## Escolha do modelo de embeddings (guia prático)
+
+Valores abaixo são referência prática para CPU. O consumo real depende do tamanho do projeto e de processos concorrentes.
+
+| Opção | Quando usar | RAM desejada (aprox.) |
+|---|---|---|
+| `bge` (`BAAI/bge-m3`) | docs + código, menor risco de memória | 8-16 GiB |
+| `jina` (`jinaai/jina-embeddings-v3`, padrão) | foco em qualidade para código | 32-64 GiB (ideal 48+ GiB) |
+| `hybrid` (`jina v2 + bge`) | duas coleções, recuperação mais ampla | 24-48 GiB |
+
+Notas:
+- Jina em CPU é pesado; com pouca RAM/swap livre pode ocorrer lentidão ou OOM (`exit 137`).
+- Se a máquina for limitada, comece com `bge`.
+
+## Perfil de performance
+
+Durante setup/indexação:
+
+- `autotune` (recomendado):
+  - Executa micro-benchmark local (`model.encode`) com métricas `psutil`.
+  - Busca custo-benefício (nem agressivo, nem conservador).
+  - Ajusta automaticamente `MCP_EMBEDDING_BATCH_SIZE`, `MCP_CHUNK_SIZE`, `MCP_CHUNK_OVERLAP`.
+
+- `max-performance`:
+  - Usa parâmetros mais agressivos para throughput.
+  - Exibe aviso explícito de risco de memória.
+
+## Comportamento do endpoint Chroma
+
+- Endpoint local padrão: `http://localhost:8000`.
+- O setup verifica se a porta escolhida já está em uso.
+- Se `~/.own-rag-cli.json` apontar para host remoto, o setup não sobe Docker local.
+
+## Backup/snapshot antes de remover, formatar ou migrar máquina
+
+Antes de executar `rag remove`, formatar o computador, ou migrar para outra máquina, faça snapshot:
+
+```bash
+mkdir -p "$HOME/own-rag-backup"
+cp "$HOME/.own-rag-cli.json" "$HOME/own-rag-backup/" 2>/dev/null || true
+cp "$HOME/.cache/own-rag-cli/indexer_tuning.json" "$HOME/own-rag-backup/" 2>/dev/null || true
+
+tar -czf "$HOME/own-rag-backup/chromadb-ragdb-$(date +%Y%m%d-%H%M%S).tgz" -C "$HOME" .rag_db
+```
+
+Restauração em nova máquina:
+1. Instale `own-rag-cli`.
+2. Restaure `~/.own-rag-cli.json` e, opcionalmente, o tuning.
+3. Extraia o backup de `.rag_db` em `$HOME`.
+4. Execute `rag run /caminho/do/projeto --skip-index` e valide a busca.
+5. Se mudou modelo/chunks, reindexe.
+
+## Fluxos comuns
+
+### Reindexar somente (`--only-index`)
+
+```bash
+./rag-setup.run /caminho/do/projeto --only-index
+```
+
+Use quando o ambiente já está instalado e você só alterou código/documentação do projeto.
+
+### Pular indexação (`--skip-index`)
+
+```bash
+./rag-setup.run /caminho/do/projeto --skip-index
+```
+
+Use para atualizar infraestrutura/configuração primeiro (venv, Docker, MCP), deixando a indexação para depois.
+
+### Trocar modelo (`--change-model`)
+
+```bash
+./rag-setup.run --change-model /caminho/do/projeto
+```
+
+Use ao mudar estratégia de embeddings (`jina`, `bge`, `hybrid`). Esse fluxo pode resetar coleções e exige reindexação completa para consistência.
+
+## Environment overrides
+
+Onde sobrescrever:
+- Temporário por sessão: `export VAR=valor` antes do `rag run`.
+- Persistente no runtime MCP: definir `env` no arquivo de configuração do MCP (`~/.claude.json`, `mcp.json` do Cursor).
+- Endpoint Chroma também pode ser persistido em `~/.own-rag-cli.json`.
+
+Para que serve cada variável:
+
+- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
+  - Seleciona estratégia de embedding.
+  - Ao alterar: reindexação obrigatória.
+
+- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
+  - Define quantização do Jina em CPU.
+  - Ao alterar: reindexação recomendada.
+
+- `MCP_PERF_PROFILE=autotune|max-performance`
+  - Define estratégia de tuning para chunks e batch.
+  - Ao alterar: rode setup/indexador novamente para aplicar novo tuning.
+
+- `MCP_EMBEDDING_BATCH_SIZE=<int>`
+  - Força batch fixo (sobrescreve batch autotunado).
+  - Ao alterar: reinicie MCP; reindexação recomendada para consistência operacional.
+
+- `MCP_CHUNK_SIZE=<int>`
+  - Define tamanho dos chunks na indexação.
+  - Ao alterar: reindexação completa obrigatória.
+
+- `MCP_CHUNK_OVERLAP=<int>`
+  - Define sobreposição entre chunks.
+  - Ao alterar: reindexação completa obrigatória.
+
+- `OWN_RAG_CLI_CONFIG_FILE=<path>`
+  - Muda localização do arquivo runtime (padrão `~/.own-rag-cli.json`).
+  - Ao alterar: reinicie setup/ferramentas MCP.
+
+- `MCP_INDEXER_CONFIG_FILE=<path>`
+  - Muda localização do arquivo de tuning (padrão `~/.cache/own-rag-cli/indexer_tuning.json`).
+  - Ao alterar: reinicie setup/ferramentas MCP.
+
+- `MCP_CHROMA_SCHEME=http|https`
+- `MCP_CHROMA_HOST=<host>`
+- `MCP_CHROMA_PORT=<port>`
+  - Sobrescrevem endpoint do Chroma.
+  - Ao alterar: reinicie clientes MCP; reindexe somente se trocar para base vazia/nova.
+
+## Verificação de checksum (`.run`)
+
+Verificação manual (Linux/macOS):
+
+```bash
+sha256sum rag-setup.run
+sha256sum rag-setup-macos.run
+```
+
+No macOS sem `sha256sum`:
+
+```bash
+shasum -a 256 rag-setup.run
+shasum -a 256 rag-setup-macos.run
+```
+
+## Transparência de código
+
+Lógica principal em arquivos-fonte (`bin/*.py`, `bin/*.sh`).
+Artefatos gerados:
+
+- `rag-setup.run`
+- `rag-setup-macos.run`
+
+Para regenerar artefatos após mudanças no fonte:
+
+```bash
+./bin/build_run.sh
+./bin/build_run_macos.sh
+```
+
+## Validação antes de publicar
+
+```bash
+bash -n rag-setup.run
+bash -n rag-setup-macos.run
+python3 -m py_compile bin/indexer_full.py bin/mcp_server.py
+npm pack --dry-run
+```
+
+## Licença
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "own-rag-cli",
-  "version": "0.0.2-snapshot",
+  "version": "0.0.4-snapshot",
   "description": "Local RAG setup with ChromaDB + MCP server (Jina/BGE hybrid support).",
   "license": "MIT",
   "private": false,