# Eidos

**A deterministic grounding engine for markdown docs and code.**

The law: *nothing true without evidence.* Every Aun docs node traces to a markdown file; every Glyph
code node traces to an exact `file:line` span when the current executor can extract it. **No
embeddings, no vector DB, no LLM in the engine** — retrieval is deterministic lexical scoring with
*calibrated confidence*, so the same query returns the same answer and the engine knows when it
doesn't know.

Eidos is an **engine + a CLI + an MCP server**. The public direction is the Aun + Glyph + Vellum
trifecta: ground markdown docs with Aun, ground the supported code graph with Glyph, and let Vellum
maintain the project knowledge library through reviewed proposals.

---

## Install

```sh
# The CLI (provides the `eidos` binary)
cargo install eidos-cli      # → installs the `eidos` command

# The MCP server (provides the `eidos-mcp` binary)
cargo install eidos-mcp
```

> The CLI crate is **`eidos-cli`**; the binary it installs is **`eidos`**. (The crate name `eidos`
> was unavailable, so `cargo install eidos-cli` is the honest install line — it still gives you
> `eidos` on your PATH.)

Build from source instead:

```sh
git clone https://github.com/obeedgarza1/eidos-rs && cd eidos-rs
cargo install --path crates/eidos-cli      # the `eidos` CLI
cargo install --path crates/eidos-mcp      # the MCP server
```

---

## First 10 Minutes

Run the CLI against an existing project by pointing Eidos at the authored markdown roots and code
root you already have:

```sh
# from this repo
cargo run -q -p eidos-cli -- --help
cargo run -q -p eidos-cli -- compile --vault /path/to/vault --docs /path/to/docs
cargo run -q -p eidos-cli -- health --vault /path/to/vault --docs /path/to/docs

# build the generated persistent graph snapshot
cargo run -q -p eidos-cli -- graph build \
  --project /path/to/project \
  --vault /path/to/vault \
  --docs /path/to/docs \
  --root /path/to/code

cargo run -q -p eidos-cli -- graph status --project /path/to/project
cargo run -q -p eidos-cli -- graph query "retry policy" --project /path/to/project --limit 5
```

For MCP, build the snapshot first for faster repeatable reads, then start `eidos-mcp` with roots:

```sh
EIDOS_VAULT=/path/to/vault \
EIDOS_DOCS=/path/to/docs \
EIDOS_GLYPH_ROOT=/path/to/code \
cargo run -q -p eidos-mcp --
```

MCP read tools prefer a fresh `.eidos/graph` snapshot and fall back to live Aun/Glyph compile when
the snapshot is missing, stale, incomplete, invalid, or source-unknown. Generated
`.eidos/graph/` and `.eidos/graph.tmp-*` directories are artifacts, not source truth; rebuild them
instead of editing or committing them.

Use Vellum only when you want proposal planning:

```sh
eidos vellum audit --vault /path/to/vault --docs /path/to/docs
eidos vellum plan-repairs --vault /path/to/vault --docs /path/to/docs
eidos-mcp --allow-write
```

`--allow-write` exposes proposal tools, but MCP still has no accept/reject truth tools. Vellum
queues reviewed source proposals through `eidos-codex`; applying accepted proposals is an
out-of-band operation.

---

## Public Surface

Eidos's intended public trifecta is Aun + Glyph + Vellum:

- **Aun** — compiles markdown docs and skills into the docs/vault graph, including body/heading
  search surfaces, wikilinks, standard internal Markdown links, schema-profile-backed
  frontmatter/link/structure audit findings, stable finding IDs, conservative repairability
  metadata, and deterministic quality scores. Aun now tolerates an OKF-inspired authoring profile
  (`index.md`, `log.md`, simple frontmatter such as `description`, `resource`, `updated`, and
  path identity metadata), but this is not a full OKF conformance promise and does not rename Eidos
  formats.
- **Glyph** — compiles the currently supported source executor into a symbol graph with spans,
  lexical cross-links, deterministic diagnostics, and project-zone evidence. Today the syntactic
  tree-sitter executor supports Rust, TypeScript/TSX, and Python, including visible FastAPI route
  decorators and common React wrapper exports.
- **Vellum** — maintains the project knowledge library: docs, skills, wiki links, indexes, and
  repair proposals. Vellum uses the internal proposal queue currently implemented in the
  `eidos-codex` crate; the old `sigil_*` names remain as compatibility/internal gated tool names.

The default shipped path is still read-only and grounds queries against Aun docs, Glyph code, or
both:

- **Grounded retrieval with `file:line` receipts** — every `ground` hit carries a **confidence band**
  (`exact` / `strong` / `weak` / `fallback`) and a **`why`** explaining what matched. For code, the
  hit resolves to the symbol's exact span: `read` returns the body plus a `{path, lines}` receipt.
- **Glyph code graph** — a tree-sitter walk turns a source tree into a symbol graph (Function · Type ·
  Trait · Module) with `contains` / `implements` / lexical `references` edges where supported.
- **Glyph diagnostics** — `glyph compile` reports files walked/parsed/skipped, parser-error files
  where detectable, language/kind/relation counts, project-zone assignment counts, unsupported
  common extensions, no-parsed-file roots, duplicate IDs, spanless nodes, stable diagnostic IDs, and
  syntactic reference evidence. JSON output includes the same additive diagnostics profile.
- **Aun diagnostics** — `compile`, `health`, and Vellum audit flows report markdown scanned,
  node/edge counts, kind breakdowns, malformed-frontmatter warnings, frontmatter/link/structure
  findings, stable `finding_id` values, conservative `repairability` metadata, and node quality
  scores. The frontmatter checks are backed by an explicit Aun schema profile for known fields,
  scalar/list field shapes, valid statuses/kinds, and tolerated legacy kind normalizations.
  Internal Markdown links create graph edges; external `http`/`https` links are tolerated and do
  not become unresolved local-link findings.

The fixture/golden evals currently reject nonsense queries at 100%. Treat these as regression
guards over committed fixtures, not as a broad claim about every possible vault or codebase.

### The Aun and Glyph compile sources

| | **Aun docs** | **Glyph code** |
|---|---|---|
| Compiles | a markdown vault (`skills/` + docs), including Eidos-authored and OKF-like bundles | supported source files (`.rs`, `.ts`, `.tsx`, `.py`) via tree-sitter |
| Granularity | 1 node / file | N nodes / file — Function · Type · Trait · Module |
| Provenance | source file | exact `file:line` **span** |
| Fixture/golden evals | harsh/general: p@1 96%, hit@k 100%, garbage rejected 100% | code-vault: p@1 96%, hit@k 100%, garbage rejected 100%; real-codebase fixture: p@1 90%, hit@k 100%, garbage rejected 100% |

The read side (`ground` · `ground_subgraph` · `eval` · calibration) is shared verbatim; only the
compile (walk → extract → edges) differs.

---

## Persistent Graph Runtime (Phase 2E fast freshness checks)

Eidos now has the first persistent graph runtime foundation, described in
[`docs/v1/05-EIDOS-GRAPH-RUNTIME.md`](docs/v1/05-EIDOS-GRAPH-RUNTIME.md). Phase 2E has landed:
the `eidos-graph` crate composes Aun docs and Glyph code into generated `.eidos/graph/` snapshot
artifacts, publishes snapshots through a temporary sibling directory before swapping them into
place, records source fingerprints, and exposes `eidos graph build`, `eidos graph status`, and
`eidos graph health`. The CLI can also `query`, `inspect`, and `export` a fresh persisted snapshot.
The MCP read tools now prefer a fresh `.eidos/graph` snapshot when one is available and fall back to
the existing live Aun/Glyph compile path when the snapshot is missing, stale, incomplete, invalid,
or source-unknown.

The contract is:

- **Source truth remains authored files** — docs, code, manifests, claim ledgers, and accepted
  proposals are the truth.
- **The graph is generated** — `.eidos/graph/*` is a compiled snapshot artifact for status/health
  reporting and snapshot-backed CLI lookup. `graph status` checks artifact consistency and recorded
  source fingerprints. Unchanged files are checked by metadata first; content hashes remain the
  final safety check when size or modified time changes. Do not hand-edit generated graph files.
- **Vellum stays proposal-only** — Vellum may plan repairs and queue source-level proposals; it
  never mutates generated graph state and never accepts truth over MCP.

Current and planned graph-runtime integration:

- **Aun** compiles markdown docs, skills, frontmatter, wikilinks, flows, contracts, and checks into
  doc/knowledge nodes with source receipts. It also accepts standard internal Markdown links as
  `links_to` edges, treats `index.md` as directory overview and `log.md` as folder history, and
  preserves path identity metadata in persisted snapshots where roots are known.
- **Glyph** compiles supported source trees into code/file/directory nodes, spans, lexical
  references, and coverage findings.
- **Vellum** reads graph health and Aun quality findings, then queues reviewed source edits through
  the proposal system. The old `sigil_*` names remain compatibility/internal only.
- **Planned** — SQLite indexing and incremental rebuilds remain future work.

Current Phase 2E snapshot flow:

```sh
eidos graph build --project . --vault ./vault --docs ./docs --root ./src
eidos graph status --project .     # artifact consistency + source freshness
eidos graph health --project .
eidos graph query "retry policy" --project .
eidos graph inspect skill.retry-policy --project .
eidos graph export --project . --format json
```

`eidos init` and `eidos setup mcp --client ...` are still planned onboarding commands. For MCP,
continue to use `eidos-mcp` with `EIDOS_VAULT`, `EIDOS_DOCS`, and `EIDOS_GLYPH_ROOT`. Run
`eidos graph build` before starting MCP for faster, repeatable grounding from the persisted graph;
MCP will still fall back to live compile if the snapshot is not fresh.

First-run scenarios and mutation boundaries are sketched in
[`docs/v1/06-FIRST-RUN-ONBOARDING.md`](docs/v1/06-FIRST-RUN-ONBOARDING.md).

---

## Quickstart (CLI)

Create a tiny demo project first, so the commands below work in any fresh directory:

```sh
mkdir -p eidos-demo/vault/skills/retry-policy eidos-demo/docs eidos-demo/src

cat > eidos-demo/vault/skills/retry-policy/SKILL.md <<'EOF'
---
name: Retry Policy
summary: Requests retry transient errors with exponential backoff.
aliases: [retry policy, backoff]
---
Use bounded retries for transient failures.
EOF

cat > eidos-demo/docs/confidence.md <<'EOF'
---
title: Confidence Calibration
summary: Confidence is calibrated from exact, strong, weak, and fallback lexical matches.
---
Exact matches are preferred; weak matches are surfaced with lower confidence.
EOF

cat > eidos-demo/src/lib.rs <<'EOF'
/// Retry policy for transient request failures.
pub fn retry_policy() {
    let _backoff = "exponential";
}
EOF
```

```sh
# Aun: docs
eidos compile --vault eidos-demo/vault --docs eidos-demo/docs
eidos ground "how is confidence calibrated" --vault eidos-demo/vault --docs eidos-demo/docs
eidos health --vault eidos-demo/vault --docs eidos-demo/docs

# Glyph: code
eidos glyph compile --root eidos-demo/src
eidos glyph ground "where is the retry policy" --root eidos-demo/src
eidos glyph read fn.lib::retry_policy --root eidos-demo/src

# Aun + Glyph, joined
eidos glyph link --root eidos-demo/src --vault eidos-demo/vault --docs eidos-demo/docs --ground "retry policy"
#   → hits tagged [docs] / [code]; reports doc→code cross-links

# Vellum: human CLI mirror for proposal-only maintenance
eidos vellum audit --vault eidos-demo/vault --docs eidos-demo/docs
eidos vellum plan-repairs --vault eidos-demo/vault --docs eidos-demo/docs
eidos vellum review --vault eidos-demo/vault
```

To run the repository's measured baseline, run this from the cloned `eidos-rs` repo and point it at
your real vault/docs:

```sh
eidos eval --golden evals/real-vault.json --vault /path/to/vault --docs /path/to/docs
```

---

## How an agent uses it (MCP)

`eidos-mcp` exposes its tools over stdio. **Read-only by default**, the v0.1 public value is:
`ground` · `get_node` · `read_doc` · `health` · `render` · `load_project`.

The intended agent policy is simple:

1. Use Eidos for questions about the configured repo, docs, vault, or codebase.
2. Call `ground` first.
3. Call `read_doc` or `get_node` on the best candidate before answering.
4. Use `load_project` when the question is about a different code root.
5. Use `health` when results look empty, stale, or misconfigured.
6. Treat `strong` confidence as answer-ready; read more or state uncertainty for `ambiguous`,
   `weak`, or fallback results.

`seal_status` is still registered as an advanced/internal ledger-inspection tool because the binary
already carries it, but it is not part of the v0.1 headline promise. Arming the server with
`--allow-write` *adds* gated Vellum tools: `vellum_audit` · `vellum_inspect` ·
`vellum_plan_repairs` · `vellum_review` · `vellum_propose_doc` ·
`vellum_propose_frontmatter_fix` · `vellum_propose_link_fix` · `vellum_propose_skill` ·
`vellum_describe`.
These audit, inspect, plan, and route to the internal proposal queue currently implemented in
`eidos-codex`. `vellum_audit` and `vellum_plan_repairs` are read-only; proposal tools queue markdown
knowledge-library changes only and do not materialize files.
`vellum_plan_repairs` consumes Aun quality findings and returns deterministic repair suggestions
that preserve the source `finding_id`, plus stable `suggestion_id` values, confidence/safety levels,
`auto_proposable` flags, and `summary.auto_proposable_by_tool` batch metadata. A single
high-confidence unresolved wikilink target is queueable through `vellum_propose_link_fix`; safe
status and type/kind normalizations are queueable through `vellum_propose_frontmatter_fix` only when
Aun supplies a deterministic replacement.
`vellum_propose_frontmatter_fix` is deliberately narrow: it queues only frontmatter-only status
normalization, type/kind normalization, or explicitly requested unknown-field removal for a
vault-relative markdown file under `EIDOS_VAULT`.
`vellum_propose_link_fix` can repair a broken wikilink only when the source file is representable
relative to `EIDOS_VAULT`; docs outside the vault are rejected until the internal proposal queue
supports multi-root writes.

The same proposal-only Vellum flow is available to humans through `eidos vellum ...`:
`inspect`, `audit`, `plan-repairs`, `review`, `propose-doc`, `propose-frontmatter-fix`, and
`propose-link-fix`. These commands mirror the Vellum domain logic and still never accept/reject
truth; accepting queued proposals remains an out-of-band `eidos-codex` operation.

The compatibility/internal `sigil_*` names still work behind the same gate: `sigil_author_skill` ·
`sigil_scaffold` · `sigil_edit` · `sigil_review` · `sigil_describe`. They queue proposals only; they
do not accept truth. There is intentionally no Vellum alias for generic code edit or scaffold in
this pass; Etch remains the future scaffold/restructure generator.

Configure it with environment variables:

| Variable | Points at |
|---|---|
| `EIDOS_VAULT` | the docs vault root |
| `EIDOS_DOCS` | the Aun docs directory; `EIDOS_CODEX` remains as a compatibility fallback |
| `EIDOS_GLYPH_ROOT` | the Glyph code root; `EIDOS_ATLAS_ROOT` remains as a compatibility fallback |

Advanced/internal Seal commands auto-discover the nearest `.aether/` project root from the
configured docs/code paths.

For faster and more repeatable MCP reads, build a fresh snapshot before starting the server:

```sh
eidos graph build --project /path/to/project \
  --vault /path/to/vault \
  --docs /path/to/docs \
  --root /path/to/code
```

`ground`, `get_node`, `read_doc`, `health`, and `render` prefer that fresh `.eidos/graph` snapshot.
If the snapshot is missing, stale, incomplete, invalid, or source-unknown, the same tools fall back
to live compile and include additive `graph_source`, `graph_snapshot_status`, and `fallback_reason`
metadata where the response is JSON.

```jsonc
// e.g. an MCP client config
{
  "mcpServers": {
    "eidos": {
      "command": "eidos-mcp",
      "env": {
        "EIDOS_VAULT": "/path/to/vault",
        "EIDOS_DOCS": "/path/to/docs",
        "EIDOS_GLYPH_ROOT": "/path/to/code"
      }
    }
  }
}
```

The loop:

1. **`ground("…")`** → ranked hits with calibrated confidence + `why`.
2. **`read_doc(top.id)`** → the exact doc, or the code symbol's **body + `file:line` receipt**.
3. The agent acts on grounded, **cited** facts.

The point: the agent **grounds before judging**, and every answer carries a receipt.

### Codex MCP Smoke Tests

When testing Eidos with Codex, run both an explicit and an implicit prompt. The explicit prompt
tests tool capability; the implicit prompt tests whether the MCP instructions are discoverable
enough for the agent to choose Eidos without being told.

Explicit capability prompt:

```text
Use the Eidos MCP. First call health. Then use ground and read_doc/get_node before answering.

Question: Where is Glyph project-zone confidence implemented? Return the node id, file:line
receipt, and a short explanation.
```

Implicit discoverability prompt:

```text
Where is project-zone confidence implemented in this repo? Give file:line evidence.
```

Vellum safety prompt:

```text
Use Eidos to audit the docs. If there are safe repairs, plan them. Queue only proposal-backed
repairs. Do not accept truth or directly modify files.
```

A good agent run calls `ground` before answering repo-specific questions, reads the cited node or
span, uses `load_project` when the configured code root is wrong, and never treats Vellum proposal
tools as permission to accept truth.

---

## Why Eidos

- **Deterministic** — same query → same result; no index drift, no model-version surprises.
- **Receipts** — every hit has provenance: `cat`-able truth, `git`-diffable, no hallucinated relevance.
- **Calibrated confidence** — it knows when it doesn't know, and the fixture/golden evals pin
  garbage rejection as a regression guard.
- **No service to run** — no embedding model, no vector DB; `eidos graph build/status/health`
  produces generated snapshots, and MCP reads fresh snapshots with live compile fallback.

**vs. grep/ripgrep** — structured (symbols, kinds, edges), ranked, expands to related context, returns
receipts + confidence. **vs. LSP/rust-analyzer** — complementary; Eidos works on partial/WIP
multi-language source trees and unifies docs + code retrieval, but its call graph is lexical
(`references`), not type-resolved. **vs. ctags** — adds ranking, confidence, edges, doc-comment
surfaces, cross-linking, and a measurement harness.

---

## Honest scope & limitations (measured, not hidden)

- **Lexical only** — no semantic paraphrase: abbreviation/synonym gaps (`expression` ↛ `Expr`),
  substring confusion (`Serialize` / `Deserialize`).
- **Glyph scope** — the public path is syntactic Rust, TypeScript/TSX, and Python extraction. Do not
  treat v0.1 as general semantic multi-language codebase intelligence.
- **Glyph skipped-file visibility** — common unsupported files such as `.go`, `.vue`, `.svelte`,
  `.sql`, `.prisma`, `.java`, `.kt`, `.php`, and `.rb` are counted and reported, not parsed.
- **Fixture scope** — the headline Aun/Glyph numbers above are fixture/golden evals. They are useful
  regression guards, not a promise of semantic understanding on arbitrary projects.
- **No semantic code resolver** — Glyph references are deterministic import-aware lexical edges, not
  an LSP/type-checker/runtime call graph.
- **v0 residue** — ~2.85% duplicate ids on generic-heavy code (`From<A>` / `From<B>` overloads); the
  resolved (type-checked) call graph is parked behind measured need.

The discipline throughout: **measure, don't assert.** Every change is scored against a golden set
(`eidos eval`) before and after; improvements that don't move the number are rejected.

---

## Gated / Future / Advanced

These components either sit behind an explicit gate today or remain in the workspace/binary for
dogfood and future work:

- **Seal** — evidence-bound belief ledger inspection under `<project>/.aether/claims/`. Commands such
  as `eidos seal ...` and MCP `seal_status` are advanced/internal.
- **Vellum** — the current gated knowledge-library maintainer. It audits Aun quality findings and
  plans deterministic repair suggestions before queueing any reviewed markdown/library repair
  through the internal `eidos-codex` engine. Current proposal verbs cover docs, skills, targeted
  wikilink fixes, and narrow frontmatter fixes; duplicate-title, orphan, weak-doc, unknown-type, and
  unknown-field plans stay advisory unless a user explicitly invokes the narrow frontmatter tool.
- **Sigil** — legacy/internal proposal/write-gate terminology behind MCP `--allow-write`. The
  `sigil_*` tools remain for compatibility and never self-accept truth.
- **Nym** — structural snapshots and decay checks. `eidos nym ...` remains experimental/internal.
- **Scry** — future/internal structural analyzers over Glyph's graph.
- **Etch** — future scaffold/restructure generator. It is not implemented or exposed as Vellum.

## Architecture

| Crate | Role |
|---|---|
| `eidos-core` | the pure-logic engine — schema, compile (docs), retrieval, eval, events. No tokio/clap/rmcp. |
| `eidos-atlas` | Glyph — the code compile source: tree-sitter walk → symbol graph; `read_span`; `link` (docs↔code). |
| `eidos-codex` | Internal proposal queue/accept engine: `propose → review → accept`, never direct mutation from MCP. |
| `eidos-vellum` | Vellum — proposal-only knowledge-library maintenance logic over Aun diagnostics and the internal `eidos-codex` queue. |
| `eidos-graph` | Phase 2E persistent graph snapshot runtime — generated `.eidos/graph` files, atomic snapshot publishing, source fingerprints, fast freshness checks, build/status/health, persisted snapshot query/inspect/export, and graph-backed MCP reads with live compile fallback. SQLite indexing and incremental rebuilds remain planned. |
| `eidos-claims` | Seal — future/internal read/index overlay for the evidence-bound belief ledger. |
| `eidos-analyze` | Future/internal edge-dependent analyzers (coupling, dead code), gated by the grounding honesty rule. |
| `eidos-archive` | Nym/future codebase memory — structural snapshots and decay detection. |
| `eidos-cli` | `eidos` — the command-line surface. |
| `eidos-mcp` | the MCP server (rmcp/stdio) — thin transport adapter for read tools plus gated Vellum/Sigil proposal tools. |

Design spec: [`DESIGN.md`](DESIGN.md). Historical build notes live under
[`docs/archive/`](docs/archive/).
Release history: [`CHANGELOG.md`](CHANGELOG.md).

---

## License

Licensed under the [Apache License, Version 2.0](LICENSE).
