Every prior documentation deck ran against the same familiar codebase. This time:
a brand-new, real FastAPI backend EKOS had zero prior ledger state for — pdf-reader, a PDF reader with OCR and AI-assisted translation. Five real
pipeline commands later, every module and every symbol has a real, evidence-grounded AI overview,
the project's real README grounds a real Purpose statement, and nothing not in the source is ever
invented. This is the first release: the whole loop, working end to end, on a project it had
never touched before.
llama3:latest · RFC 0035 · RFC 0087 · RFC 0088 · devlog_98No prior .ekos/ state, no
hand-written fixture, no mock data — a real project cloned for other reasons, scoped to its
backend, plus the top-level README.md so the Purpose/Architecture
summary has something real to ground itself in. Every stage of the pipeline runs exactly the
same way it would on any workspace.
[observe] paths = ["backend/app", "README.md"] [llm] provider = "ollama" model = "llama3:latest" [llm-description] enabled = true scope = "all" # modules + symbols
$ ekos build
Files observed (new): 15
$ ekos commit --yes
LLM description requested for up to 60 real call(s)
(28 module(s), 31 symbol(s), 1 project-level summary)
AI descriptions: 28 module(s), 31 symbol(s) described
(0 cached, 0 skipped without a source span, 0 errors)
$ ekos docs generate --layout curated --output doc
Entity detail pages written: 59
Scope the run to source only and Purpose is honestly blank — "not yet computed, no real EKOS source for
a project's stated purpose today." Add the real README and RFC 0088's project-level
summary step reads it, once, and writes a real, grounded answer. No README, no answer —
never a fabricated placeholder either way.
**Purpose:** Local, browser-based reader for technical/scanned PDFs with AI-assisted translation and explanation. (LLM-assisted, RFC 0088 — see the object's own evidence) **Architecture style:** layered (LLM-assisted, RFC 0088)
Most of this real codebase's route-handler and service functions have no docstring — RFC 0087's real doc-comment extraction correctly says so, and still does; nothing here fabricates one. What's new is the section below it: a real, evidence-grounded reading of the function's own real source lines, cited by id, distinct in the page from anything claiming to be human-written documentation.
# delete_document (PythonSymbol) ## Definition _Not documented in source._ **Lines:** 76–87 ## AI-Assisted Overview A Python function that deletes a document from the database and removes associated files. It takes a file hash as input, checks if the document exists, and then performs the deletion by removing the file, deleting related cache entries, and committing the changes to the database. ## Evidence ai_overview grounded in delete_document's own real source lines (confidence: 1.00)
| Before | After |
|---|---|
python_analyzer.rs never captured a real source_span (Rust/Elixir only at RFC 0088's launch) | real line_number/item_span — byte offset (rustpython_parser::Ranged) converted to a real 1-indexed line |
every PythonSymbol honestly skipped — scope = "symbols"/"all" silently did nothing for Python, with no diagnostic saying why | 31/31 real symbols described, 0 skipped without a span, 0 errors |
This deck's own predecessor listed "Python/JS source_span — same pattern, not yet wired" as a deliberately deferred
item. It stayed deferred until a real user, reading a real generated page, asked directly why it
was empty — the same live-verification pattern this whole effort keeps converging on: a real
question about a real page finds what a passing test suite doesn't.
A generated Markdown page and an MCP tool response aren't
two different pipelines that happen to agree — they're two renderings of the exact same compiled
KirObject. ekos_state/ekos_neighborhood return the object's real properties
map verbatim — the same ai_overview, the same source_span, the same evidence id that renders into the page above. Fix the
gap for one, and every AI agent calling that tool live gets the fix too, with no separate change
needed on the MCP side.
| Real, shipped | Deliberately deferred |
|---|---|
| Cold run against a project EKOS had zero prior state for — no fixture, no mock | JS/TS source_span — same pattern, still not wired |
Module + symbol AI overviews for Rust, Elixir, and now Python — scope = "all" | A dedicated File entity page — symbol pages link to their file by name, not a page of its own |
| Real Purpose/Architecture-style, grounded in the project's own README, honestly blank without one | Per-symbol re-verification against changed code at every scope size |
Zero API cost — real local llama3:latest, cost-gated (ekos commit --yes) | Real Architecture confidence from an LLM judgment |
Full workspace gate (cargo build/test/clippy -D warnings/fmt) clean after every fix; 4 new tests for the Python span fix alone, 25 for the run overall.
$ ekos init && ekos build && ekos recover \
&& ekos resolve && ekos compile && ekos commit --yes
$ ekos docs generate --layout curated --output doc
# same ledger, live, over MCP:
$ ekos mcp serve --workspace .