archeology-doc

Open-source CLI · Rust · local-first

Dig into any project.
Document it with evidence.

archeology-doc (adoc) inspects new or legacy projects and, with the AI agent you already use, generates a browsable knowledge base, documentation, findings and context for agents. Every claim cites its source as path:line.

$ curl -fsSL https://your-site/download/install.sh | sh
Install See how it works
🧭

System map

Modules, features, glossary and decisions in plain Markdown, browsable in Obsidian, VitePress or GitHub.

🔎

Contradictions and risks

Findings by severity: outdated documentation, duplicated rules, conflicting configuration, dead code.

🧪

Testing gaps

Features ↔ tests, covered and missing scenarios, disabled or empty tests.

🤖

Context for agents

AGENTS.md, persistent memory and skills: every AI session starts knowing what exists and where.

📐

Specs with OpenSpec

Requirement compliance checked against the code, and inferred baseline specs for projects that have none.

✅

Verifiable

adoc check validates evidence, links and outdated notes; ideal for CI.

How it works

Rust computes the deterministic parts; your agent does the interpretation; adoc orchestrates and validates.

  1. 1

    adoc scan

    AI-free inventory: languages, modules, tests, CI, git history and OpenSpec. Honors .gitignore and excludes secrets.

  2. 2

    adoc plan

    Splits the work into bounded tasks based on project size: a few tasks for a small one, more for a large one.

  3. 3

    adoc inspect

    Your agent runs each task. It is only marked done if it produced what was asked, with valid evidence.

  4. 4

    adoc preview

    A site with a dashboard: status, findings, questions for the team and FAQ. Or a single HTML report.

  5. 5

    adoc sync

    When the code changes, it marks the affected notes as outdated and reopens only those tasks.

Install

One command for your system: it downloads the binary for your platform, verifies its SHA-256 and puts it on your PATH. No Rust needed. Node 18+ only for the VitePress site and the extension.

Terminal

$ curl -fsSL https://your-site/download/install.sh | sh

or download the binary

Apple Silicon (M1–M4) Intel

When downloaded from the browser, macOS quarantines it: xattr -d com.apple.quarantine adoc archeology-doc, then move both to ~/.local/bin. Not needed with the terminal command.

Terminal

$ curl -fsSL https://your-site/download/install.sh | sh

or download the binary

x86_64 ARM64

Binaries for glibc 2.28 or later (Debian 10, Ubuntu 18.10, RHEL 8 and newer).

PowerShell

> irm https://your-site/download/install.ps1 | iex

or download the binary

Windows x64 (.zip)

The installer puts it in %LOCALAPPDATA%\Programs\archeology-doc\bin and adds it to your PATH, without administrator rights. On Windows ARM64 it runs under x64 emulation.

# Requires Rust (rustup.rs). Installs `adoc` into ~/.cargo/bin
git clone https://github.com/jsoncr/archeology-doc.git
cd archeology-doc
WEBSITE/installers/install.sh

# or directly with cargo
cargo install --path crates/archeology-cli --locked

Extras

# With shared VitePress and the VS Code extension
curl -fsSL https://your-site/download/install.sh | sh -s -- --with-vitepress --with-vscode

# Checks requirements: git, Node, VitePress, OpenSpec and agents
adoc doctor

Two equivalent binaries are installed: adoc (short) and archeology-doc. To uninstall: adoc uninstall (with --purge it also deletes ~/.archeology-doc; your project files are never touched).

All downloads

FilePlatformSizeSHA-256
List available once the site is published (WEBSITE/dist.sh).

Verify a download with shasum -a 256 <file> (macOS/Linux) or Get-FileHash <file> (PowerShell) and compare it with SHA256SUMS.

Getting started

In your project folder:

cd my-project

adoc init                 # config + structure
adoc agent use claude     # or devin, codex, gemini…
adoc scan                 # deterministic inventory
adoc plan                 # tasks sized to the project
adoc inspect              # the agent documents
adoc preview              # see the result

Day to day

adoc reviewProgress, findings, features without tests
adoc inspect --resumeRetries failed or interrupted tasks
adoc task answer T-014 "…"Answers an agent that asked a question
adoc task run T-014 -iInteractive session with the agent
adoc ask "…?"Ask about the project → FAQ
adoc syncDetects changes and marks outdated notes
adoc checkValidations for CI
adoc reportSingle HTML report to share
adoc projects listAll your projects and their progress

Work with your agent

Agent-agnostic: switch agent or model whenever you like. No CLI? Export the tasks and do them by hand.

Claude CodeDevinCodexGemini CLIQwen Code OpenCodeCursorGitHub CopilotAmpgooseAider 
adoc agent list                       # available; * = active
adoc agent use devin --model opus     # project agent and model
adoc inspect --agent codex            # just for this run

VS Code extension

Everything generated, in view while you code. Also works in Cursor, Windsurf and Devin Desktop.

  • Tasks by status with a ▶ button to run them
  • Findings that jump to the evidence line
  • Knowledge graph, like in Obsidian
  • Questions from the agent and the team, plus FAQ
  • Editor marks on the cited code
  • Progress and active agent in the status bar
cd archeology-doc/extension
npm ci
npm run package
code --install-extension archeology-doc-0.1.0.vsix

What stays in your project

Only results, in Markdown. Working state lives outside the repository.

my-project/
├── archeology-doc.toml     # config + ID
├── AGENTS.md               # context for agents
├── knowledge/              # Obsidian vault
│   ├── 00-overview.md
│   ├── modules/  features/  findings/
│   ├── tests/  glossary/  faq/
│   └── memory/
├── docs/                   # VitePress site
└── llms.txt

Principles

  • Evidence first: every claim cites path:line
  • Non-destructive: never modifies your code; respects your edits
  • Local-first: nothing leaves your machine except what your agent sends
  • Incremental: small, resumable tasks, module by module
  • Standards: Markdown, OpenSpec, AGENTS.md, Obsidian and VitePress