Skip to content

docs: update the Atlas README and add recorded walkthroughs - #2383

Open
BernhardJackiewicz wants to merge 1 commit into
DeusData:feat/codeatlas-webfrom
BernhardJackiewicz:docs/readme-atlas-review
Open

BernhardJackiewicz wants to merge 1 commit into
DeusData:feat/codeatlas-webfrom
BernhardJackiewicz:docs/readme-atlas-review

Conversation

@BernhardJackiewicz

Copy link
Copy Markdown

The README still showed the old graph UI. This update documents Atlas as it exists on the branch in #2068, including Explore, Architecture, Galaxy and local code chat. It also covers project indexing, architecture decisions and index coverage, while keeping the existing README structure.

New screenshots and browser recordings show the source reader, a real chat response, graph navigation, and a walkthrough from the architecture map into source code. Each view has an explanation before its images.

The introduction explains how Atlas helps with unfamiliar codebases, rescue engineering and reviewing code produced by AI. I updated the tool and language information, test counts, build instructions and VirusTotal links for v0.11.0. The benchmark summaries link to their sources and distinguish the five query token comparison from the larger evaluation. The README also makes clear that this Atlas interface belongs to the development branch.

The native and frontend builds passed. Vitest passed 2,821 of 2,822 tests; the existing translation check still fails on three interface strings. Package tests passed 63 checks, with one Windows test skipped on macOS. The C tests were counted, but the full C suite was not rerun. I checked the rendered README on desktop and mobile.

The local chat section also documents a memory error encountered with a whole file as context. A smaller code selection worked and is shown in the screenshot.

Signed-off-by: Bernhard Jackiewicz <bj@techport.io>
@github-actions

Copy link
Copy Markdown

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

  • It will not be closed for inactivity. No stale bot touches pull requests here.
  • It may still sit a while before a human reads it. That is on us, not on you.
  • Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

  • Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
  • Get CI green, or say which failures you believe are pre-existing.
  • Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
  • Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

@DeusData

Copy link
Copy Markdown
Owner

Thank you so much, @BernhardJackiewicz. This is a genuinely careful piece of work. The capture log in docs/images/README.md records the exact commit, sparse-checkout scope, node and edge counts, viewport and encoding settings, and it notes honestly where the whole-file chat fails. That is exactly the provenance we want behind every screenshot. It's also great to see Atlas documented by the person who built it. You caught a lot of stale facts along the way too: the 17-tool table, persistence defaulting to off, and the v0.11.0 VirusTotal hashes (all eight match the release notes).

We've talked it through, and here's how we'd like to proceed:

  1. Media goes into Git LFS. The eight images add about 27.6 MB (the Galaxy WebP alone is 17.8 MB). Without LFS, every future clone carries that forever. Please add an LFS rule for docs/images/*.webp and docs/images/*.png in .gitattributes, and commit the images through LFS. Full quality is fine then.
  2. The README rewrite waits until Atlas is on main. The new text describes the feature branch accurately today, but it would advertise an unmerged draft on the project's front page. Wording like "not in v0.11.0 or main" also flips the moment CBM Atlas: the human interface to the code graph #1860/CBM Lens Beta: graph exploration and architecture workspace #2068 land. So we'll keep this PR open and take the README work together with the Atlas merge, rather than landing it on its own now.
  3. One fix we'd ask for in the meantime. It looks like the em dashes were replaced mechanically with ;. That broke three table cells (|; | in the zlib, Aider and Pi rows) and turned several parentheticals into sentences like …; which is consulted per session; …. Could you restore those lines to their original punctuation? It also shrinks the diff down to the parts that actually change content.

When the README work does go in, we'd suggest moving the per-suite "README review result" numbers into the PR description rather than the README. They're great evidence, but they go stale on the next commit.

None of this changes how much we appreciate the effort. The walkthroughs make Atlas click in a way prose never could. Thanks again!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants