Rewrite the README as a landing page - #186
Merged
Merged
Conversation
The README was a 2,767-word manual with a section per verb, written when it was the only documentation the CLI had. docs.landing.ai now has an eight-page CLI tab whose reference regenerates from this repo's help.json on every release, so the hand-maintained copy here could only drift from it. It already had: the version-pin example still said 0.2.1 against a shipped 1.0.5. Keeps what this repo owns and a GitHub visitor needs: what ade does, install in full (the installer scripts live here), a three-command first run, one line per command, the agent contract, and the agentic-doc lineage. Everything conceptual links to the docs instead. Also fixes two defects. Two sections were both titled History, one for the command and one for the repo lineage, so their anchors collided; the second is now Project history. And the top link pointed at the docs root rather than the CLI documentation. 2,767 words to 821, 335 lines to 133. All 18 commands in help.json appear in the table, and no others. Every link resolves except the eight docs.landing.ai/cli/ paths, which go live with landing-ai/docs#377 and gate merging this.
Intro 65 words to 49. "The ade command drives LandingAI's ADE v2 APIs" asserted nothing the next clause did not say concretely, and "visually complex" was doing the work the parenthetical already did. Now it names the two verbs and what each returns. Install prose 250 words to 131. Cut three details no reader acts on: the _internal/ directory of bundled libraries, that the installer verifies the symlink runs, and that it never overwrites a real file at that name. Also cut "The installers detect your platform, verify the checksum, and put ade on your machine", which restates what three platform commands and the word install already convey. Names ADE_CLI_VERSION without a value. Pinning an example version is what went stale before, saying 0.2.1 against a shipped 1.0.5, so the flag alone removes that failure mode rather than resetting its clock. README total 2,767 words to 718.
Where files land, which environment variables move them, how to update, and how to uninstall are not what a first-time reader or an agent needs. They were sitting between the install commands and the first run, which is the worst place for them. Install is now what ships plus the three commands, 26 words of prose. A new "Managing your install" section before Project history holds the rest, reordered so updating comes before uninstalling, since one happens repeatedly and the other once. The reading order is now install, run it, what else it does, agents, then maintenance. Nothing was cut: all four environment variables, the rm -rf warning, the uv/pipx note, and the CONTRIBUTING pointer are all still present.
Contributor
There was a problem hiding this comment.
Pull request overview
Rewrites the README as a concise landing page while directing detailed usage to hosted CLI documentation.
Changes:
- Condenses command documentation into a summary table.
- Preserves installation, first-run, agent, and project-history guidance.
- Corrects documentation links and duplicate history headings.
Suppressed comments (2)
README.md:105
- This is presented as platform-neutral install behavior, but it is only true for macOS/Linux. The Windows installer puts
ade.exeunder%USERPROFILE%\.ade\binand adds that directory directly to the user PATH; it does not create~/.local/binor a symlink. Documenting both behaviors prevents Windows users from looking for a nonexistent link.
The app lands in `~/.ade/bin`, and the installer symlinks `ade` into
`~/.local/bin`, which is on the PATH in most setups. Set `ADE_HOME` to move the
README.md:116
- The uninstall instructions omit Windows even though this README installs Windows binaries. Following these paths on Windows leaves
%USERPROFILE%\.ade\bininstalled; the data-preservation warning should also name the Windows ADE home path.
To uninstall, remove `~/.ade/bin` and the `~/.local/bin/ade` symlink. Never run
`rm -rf ~/.ade`: the rest of that directory holds results that already consumed
credits.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The README ships two Windows installers but named no Windows path. The For agents section also explained the PATH problem as "non-interactive shells source no rc file", which describes POSIX only, so both its reasoning and its path were wrong on Windows. A Windows agent following it could not run the CLI at all. It now uses the installer's own framing (install.ps1:106): a process already running keeps the environment it started with, which is true on every platform, and names both absolute paths. Drops the export PATH alternative, which has no Windows equivalent and which the installer itself does not lead with. Managing your install gains a paths table covering the app, the store, and how each platform reaches PATH. Uninstall stops naming a POSIX path and rm -rf, borrowing install.ps1's own "never delete all of .ade". Restores a fact I removed while tightening Install two commits ago: the README on main carried "(%USERPROFILE%\.ade\bin on Windows)" and I cut it, which is what left the file with no Windows path anywhere. Every path verified against scripts/install.ps1 and scripts/install.sh.
yuanwen-tian
approved these changes
Aug 11, 2026
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
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.
Why
The README was a 2,767-word manual with a section per verb, written when it was the only documentation the CLI had.
docs.landing.ainow has an eight-page CLI tab, and its reference page regenerates from this repo'sdocs/reference/help.jsonon every release.That left two copies of the same material, one of which regenerates and one of which does not. The hand-maintained copy had already drifted: the version-pin example said
ADE_CLI_VERSION=0.2.1against a shipped 1.0.5.What this does
Trims the README to what this repo owns and a GitHub visitor needs, and links the docs for depth.
Kept
adedoes, in one paragraph.ADE_HOME,ADE_CLI_VERSION,ADE_CLI_INSTALL_DIR, the never-rm -rf ~/.adewarning,ade update,ADE_NO_UPDATE_CHECK.For agents:ade help --jsonand theSKILL.mdpointer.agentic-doclineage, contributing, license.Moved to the docs (auth details, job items and the guarantee, parse and extract prose, view/crop/find prose,
--jsonand piping, help topics). Each now has a link to the page that owns it.Two defects fixed
## History, one for the command and one for the repo lineage, so their anchors collided and the rendered nav showed "History" twice. The second is now## Project history.2,767 words to 821. 335 lines to 133.
Verification
docs/reference/help.jsonappear in the command table, and no others.docs.landing.ai/cli/paths noted above. I confirmed each of those eight matches a real page filename in the docs PR, so they resolve on deploy.ADE_CLI_VERSIONexample now matches the shipped version.LICENSE,SKILL.md, andCONTRIBUTING.mdall exist at the paths linked.Notes for review
## Build a schemasection to the same file. Whichever merges second resolves it. In the new structure that section belongs afterFirst run.ade schema buildhere. It is not onmain, and the skill it links in feat: post-parse handoff to the build-schema agent skill (ADR-0010) #185 lives inlanding-ai/claude-skills, which is private, so a public README linking it would 404 for every reader.docs/agents/writing-style.mdbut does not touchREADME.md. I wrote this against those standards anyway.🤖 Generated with Claude Code