docs(readme): state the real requirements, and show the dashboard section by section - #14
Merged
contactacefleetdev merged 5 commits intoAug 15, 2026
Conversation
…tion by section Two things in the old README stopped a new reader before they got anywhere. It never named a Python version, though the package requires >=3.12, so the quickstart's `pip install ace-sidecar` fails on any older interpreter with "Could not find a version that satisfies the requirement" — a message that blames the package rather than the interpreter. Requirements now lead with the version, with a check command, per-OS install lines, and that error explained by name in a troubleshooting table. And the quickstart's second command did not work at all: bare `ace up` with no key configured exits and prints the three ways to supply one. Subscription users — most readers — need `ace up --no-key`. The quickstart now starts there and says why, with the API-key path alongside it. Install guidance moves to uv/pipx first. The sidecar is a CLI, so an isolated install is what people want, and it sidesteps the system-Python and permission problems that plain pip invites. Screenshots retaken from a live local instance at 1440x900, one per capability rather than a single hero image, and stored as JPEG: the same six shots as PNG came to 2.6M against 632K, for screenshots nobody is pixel-peeping. Also corrected: telemetry lives in ~/.ace/telemetry.db, not accountant.db; the suite is 40 tests, not 33; and the exporter emits 15 metric families, not the 16 the dashboard badge claims. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Cut 269 lines to 143. The install and troubleshooting tables restated what `ace up --help` and the error messages already say, and the per-capability prose ran longer than the screenshots it introduced. Quickstart is `ace up`, with the subscription case and the pointer to --help as one line after it rather than a decision to make before the first command. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This page is what people screenshot to show what their agents cost, and it printed absolute paths in four places: the installed-skills disk locations, the session list's transcript paths, working directories and opening prompts, and the footer's transcript and telemetry lines. Each one publishes the reader's account name, and the session list carries the names of the private repositories they work in alongside it. The masking already existed, inlined at the one call site that had been noticed — the header — so the page was half-masked and read as if the problem were handled. It is now a helper every call site goes through. It also covers a second encoding. Claude Code derives a transcript filename by replacing the separators in a project path with dashes, so /Users/alex turns up as -Users-alex, which a plain replace of the home path does not see. Screenshots retaken against the masked render. The section 09 session list stays out of the README: masking fixes the account name, but the project column still names private repositories, so it is not a section to publish. Also dropped two citations of internal analysis docs that do not exist in this repository — one in the section 10 prose, one in the section 01 subtitle — which were being read by anyone opening the dashboard or the README. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One inline row rather than a bulleted block: at nine sections a vertical list would push the first real sentence below the fold on the page it is supposed to introduce. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A reader arriving through this repo has no way to tell the sidecar apart from the company: the only mention of ACE Fleet was a half-sentence that read like an attribution line, so the open-source tool looked like the whole of what we build. The new section names Fleet as the product, the sidecar as one vertical of it, and puts the two side by side on the axes people actually confuse — scope, workload, measuring versus acting, where it runs, and licence. The line under "What it does" now points here instead of repeating it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
contactacefleetdev
deleted the
docs/readme-screenshots-and-requirements
branch
August 15, 2026 20:36
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Two things in the old README stopped a new reader before they got anywhere.
It never named a Python version, though the package requires >=3.12, so the quickstart's
pip install ace-sidecarfails on any older interpreter with "Could not find a version that satisfies the requirement" — a message that blames the package rather than the interpreter. Requirements now lead with the version, with a check command, per-OS install lines, and that error explained by name in a troubleshooting table.And the quickstart's second command did not work at all: bare
ace upwith no key configured exits and prints the three ways to supply one. Subscription users — most readers — needace up --no-key. The quickstart now starts there and says why, with the API-key path alongside it.Install guidance moves to uv/pipx first. The sidecar is a CLI, so an isolated install is what people want, and it sidesteps the system-Python and permission problems that plain pip invites.
Screenshots retaken from a live local instance at 1440x900, one per capability rather than a single hero image, and stored as JPEG: the same six shots as PNG came to 2.6M against 632K, for screenshots nobody is pixel-peeping.
Also corrected: telemetry lives in ~/.ace/telemetry.db, not accountant.db; the suite is 40 tests, not 33; and the exporter emits 15 metric families, not the 16 the dashboard badge claims.
Type of Change
Verification
Describe the tests and checks performed to verify changes:
pytestpasses cleanly.python -m buildandtwine check dist/*pass.scripts/e2e_test.pypasses.Checklist
CHANGELOG.mdwith my changes.