Start here: the root README for install and quick start.
This documentation is organized by the Diataxis framework: Tutorials (learning), How-to (task), Reference (lookup), Explanation (understanding).
- tutorials/quickstart.md: install, first index, bootstrap
- how-to/configure-lsp-servers.md: LSP server overrides and concurrency
- how-to/query-another-project.md: query another indexed project on this machine with
--db - how-to/switch-embedding-provider.md: local ONNX, Ollama, OpenAI-compatible
- how-to/set-up-s3-sync.md: remote push/pull via S3-compatible storage
- how-to/update-cartog.md: upgrade, rollback, deferred updates
- how-to/wire-editors.md:
cartog ide,cartog uninstalland manual MCP config - how-to/publish-vscode-extension.md: maintainer runbook: publish the VS Code extension to the Marketplace + Open VSX
- reference/cli.md: all 29 commands and global flags
- reference/config.md: all
.cartog.tomlkeys and environment variables - reference/mcp-tools.md: 16 MCP tools (+2 opt-in cross-project), progress, cancellation, logging
- reference/exit-codes.md:
cartog selfexit codes and state file - updates.md: full
cartog self updatesurface (canonical reference; procedures are in how-to/update-cartog.md)
- explanation/architecture.md: design decisions, secret redaction, SQLite tuning
- explanation/rag-pipeline.md: hybrid search, embedding models, provider architecture
- explanation/incremental-indexing.md: three-layer change detection, Merkle invariants
- explanation/concurrency.md: rayon / tokio / std::thread models
- explanation/project-registry.md: user-global project registry:
cartog projects,cartog_list_projects, and self-populated descriptions (shipped), and the proposed later phases - explanation/cross-project-queries.md: (proposal) federated search and cross-service edges
- usage.md: hub: search commands, plugin, agent skill, MCP server, agents
- product.md: vision, target users, positioning
- tech.md: technology stack, dependencies, benchmarks
- structure.md: workspace layout and per-crate links
- mcp-setup.md: per-editor MCP wiring (Cursor, VS Code, Codex, Copilot CLI, Gemini, Qwen Code, Claude Desktop, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes, Cline, Roo Code, Kilo Code)
- agent-snippet.md: drop-in rules that teach your agent when to prefer cartog over grep
- editor-integration.md: Neovim, VS Code, Emacs, Zed CLI recipes
- troubleshooting.md: common errors and fixes
- release-smoke.md: manual smoke checklist run before tagging
The animated GIF on the README and the landing page is generated from demo.tape using
VHS. The tape walks through:
cartog init → cartog index → cartog stats → cartog search → cartog rag setup
→ cartog rag index → cartog rag search.
To regenerate after changing CLI output:
brew install vhs # or: go install github.com/charmbracelet/vhs@latest
cargo build --release
PATH="$PWD/target/release:$PATH" vhs docs/demo.tape
cp docs/demo.gif site/public/demo.gif # keep site mirror in sync- demo.tape: VHS script (edit this to update the demo)
demo.gif, rendered output (commit alongside the tape; keepsite/public/demo.gifin sync)
- CONTRIBUTING.md: how to build, test, and contribute
- AGENTS.md: instructions for AI agents working on this repo
- CHANGELOG.md: release history