Add writing-style standards; backtick inline code in help prose - #166
Merged
Conversation
New docs/agents/writing-style.md: inline code (flags, commands, paths, env vars) is always backticked in help text and docstrings. The hosted docs generate their CLI reference from help --json, where a bare --flag renders as an em dash plus the flag name; backticks also make literals unambiguous for agents. tests/test_help_style.py enforces the flag rule across the help surface's prose fields (topic bodies exempt: they are pre-formatted terminal layouts). Wraps the ~50 existing bare mentions and regenerates the help.json snapshot. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds two prose standards: cite what a reader outside this repo can open, and leave out issue numbers, internal URLs, and anything that resolves only inside LandingAI. An issue number is dead weight to someone reading the shipped binary, so the prose states the behavior and the number stays in the commit history. Extends tests/test_help_style.py with an issue-reference guard over the same prose fields as the flag rule. The lookbehind spares URL fragments, which are legitimate prose (view.html#element). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
# Conflicts: # docs/reference/help.json # src/ade_cli/help.py
The branch predated v1.0.3 through v1.0.5, so the strings those releases added never met either rule. Backticks the 15 bare flags the guard names (history list's summary, note, and `--limit` help; parse's `--keep-copy`; view and crop's download flags; the job-item-ids convention; meta.json's store entry) and drops the two issue references from view and crop, whose sentences already state the behavior. Regenerates the help.json snapshot. Both style guards pass; full suite 742 passed, 8 skipped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
yuanwen-tian
approved these changes
Aug 11, 2026
|
The This PR backticks bare flags in sibling convention entries in the same array ( Suggested fix: backtick |
Collaborator
Author
|
Thanks @DanGH1 — addressed in #188, which goes a bit wider than the suggested one-line fix:
Your follow-up QA review on #188 also caught a 🤖 Generated with Claude Code |
lai-bianca
added a commit
that referenced
this pull request
Aug 11, 2026
… style test (#188) Follow-up to the post-merge review feedback on #166 (#166 (comment)): the `env overrides` convention entry was left unbackticked even though `docs/agents/writing-style.md` names environment variables as a backtick category, and the style test could not catch it because it only matched `--flag` shapes. ## Changes - Backtick `ADE_HOME`, `ADE_API_KEY`, and `ADE_ENDPOINT` in the `env overrides` convention entry (the reviewed miss). - Fix the sibling misses in help-surface prose the same manual pass skipped: `ADE_API_KEY` in the `auth status` result key, `ADE_HOME` in the store home line, and five prose `$ADE_ENV` mentions normalized to `` `ADE_ENV` `` (the style doc's notation). The topic-body mention stays bare per the pre-formatted exemption. - Extend `tests/test_help_style.py` with a `BARE_ENV_VAR` check so the env-var rule is enforced the same way the flag rule is. The test's original rationale for flag-only scope was that a long flag is unmistakable in prose; an `ADE_*` env var is equally unmistakable. The pattern also flags `$`-prefixed mentions. - Add the previously unscanned `store.home` and `store.note` fields to the prose scan, which surfaced one more bare `--json` in the store note (now backticked). - Update `docs/agents/writing-style.md` to state that both rules are enforced and that env vars are written as a backticked bare name (`ADE_ENV`, not `$ADE_ENV`). - Regenerate the `docs/reference/help.json` snapshot. Deliberately out of scope: bare env vars in error and status messages outside the help surface (for example the login hints in `auth.py` and `credentials.py`); those are not part of the `help --json` contract the hosted docs consume. Full suite passes (743 passed, 8 skipped); `uvx ruff check src tests` and `uvx ty check src` are clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
lai-bianca
added a commit
that referenced
this pull request
Aug 11, 2026
> **Do not merge until [landing-ai/docs#377](landing-ai/docs#377) is live.** Eight links in this README point at `docs.landing.ai/cli/...`, which 404 until that PR deploys. ## 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.ai` now has an eight-page CLI tab, and its reference page regenerates from this repo's `docs/reference/help.json` on 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.1` against 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** - What `ade` does, in one paragraph. - **Install, in full.** The installer scripts live in this repo, so this stays the canonical home: platform installers, where the app lands, `ADE_HOME`, `ADE_CLI_VERSION`, `ADE_CLI_INSTALL_DIR`, the never-`rm -rf ~/.ade` warning, `ade update`, `ADE_NO_UPDATE_CHECK`. - A three-command first run. - One table, one line per command, no prose. - `For agents`: `ade help --json` and the `SKILL.md` pointer. - The `agentic-doc` lineage, contributing, license. **Moved to the docs** (auth details, job items and the guarantee, parse and extract prose, view/crop/find prose, `--json` and piping, help topics). Each now has a link to the page that owns it. **Two defects fixed** - Two sections were both titled `## 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`. - The top documentation link pointed at the docs root rather than the CLI documentation. 2,767 words to 821. 335 lines to 133. ## Verification - All 18 commands in `docs/reference/help.json` appear in the command table, and no others. - Every link returns 200 except the eight `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_VERSION` example now matches the shipped version. - No duplicate headings. - `LICENSE`, `SKILL.md`, and `CONTRIBUTING.md` all exist at the paths linked. ## Notes for review - **This conflicts with #185**, which adds a 19-line `## Build a schema` section to the same file. Whichever merges second resolves it. In the new structure that section belongs after `First run`. - I deliberately did not document `ade schema build` here. It is not on `main`, and the skill it links in #185 lives in `landing-ai/claude-skills`, which is private, so a public README linking it would 404 for every reader. - This does not depend on #166. That PR adds `docs/agents/writing-style.md` but does not touch `README.md`. I wrote this against those standards anyway. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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
3 participants
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.
Adds
docs/agents/writing-style.md(prose standards plus one enforced rule: inline code in help prose is always backticked) andtests/test_help_style.py, which fails CI naming any bare--flagin the help surface's prose fields. Wraps the ~50 existing bare mentions in the source help strings and regenerates thehelp.jsonsnapshot.Why: the hosted docs now generate their CLI reference from
help --json, and their renderer displays a bare--flagin prose as an em dash plus the flag name. Backticks also give agents unambiguous literal boundaries, and they are already this CLI's help-text voice.Deliberately exempt: topic bodies and usage lines (pre-formatted terminal layouts and copy-pasteable commands, where backticks would corrupt the rendering).
Full suite passes (667 tests),
ruffandtyclean. Referenced from CLAUDE.md and CONTRIBUTING.md.🤖 Generated with Claude Code