docs: add showcase example for CLI version/info/diagnostics basics #11108

Open
HAL9000 wants to merge 2 commits from fix-pr-4211 into master
Owner

Add a verified CLI showcase entry for the version, info, and diagnostics introspection commands, update CHANGELOG.md/CONTRIBUTORS.md, and fix an inaccurate fast-path claim in the documentation.

Changes (2 commits):

1. docs: add showcase example for CLI version/info/diagnostics basics

  • Registered a new showcase entry in docs/showcase/examples.json for the CLI version/info/diagnostics guide
  • Updated CHANGELOG.md with the #4211 changelog entry
  • Updated CONTRIBUTORS.md with HAL 9000's contribution to PR #4211

2. docs: fix inaccurate fast-path claim in CLI basics documentation

  • Corrected an incorrect statement that version, info, and diagnostics commands are on the fast-path
  • Only --help and --version use fast-path eager exit; the three introspection commands are lightweight but do not benefit from the optimization

Files changed:

  • CHANGELOG.md (+6 lines)
  • CONTRIBUTORS.md (+2 lines)
  • docs/showcase/examples.json (+23 lines, 1 removed)
  • docs/showcase/cli-tools/cleveragents-cli-basics.md (fixed fast-path claim)

**ISSUES CLOSED: #7592

Add a verified CLI showcase entry for the `version`, `info`, and `diagnostics` introspection commands, update CHANGELOG.md/CONTRIBUTORS.md, and fix an inaccurate fast-path claim in the documentation. ## Changes (2 commits): ### 1. docs: add showcase example for CLI version/info/diagnostics basics - Registered a new showcase entry in `docs/showcase/examples.json` for the CLI version/info/diagnostics guide - Updated CHANGELOG.md with the #4211 changelog entry - Updated CONTRIBUTORS.md with HAL 9000's contribution to PR #4211 ### 2. docs: fix inaccurate fast-path claim in CLI basics documentation - Corrected an incorrect statement that `version`, `info`, and `diagnostics` commands are on the fast-path - Only `--help` and `--version` use fast-path eager exit; the three introspection commands are lightweight but do not benefit from the optimization ## Files changed: - CHANGELOG.md (+6 lines) - CONTRIBUTORS.md (+2 lines) - docs/showcase/examples.json (+23 lines, 1 removed) - docs/showcase/cli-tools/cleveragents-cli-basics.md (fixed fast-path claim) **ISSUES CLOSED: #7592
Add a verified CLI showcase for the version, info, and diagnostics commands,
register in examples.json and update CHANGELOG/CONTRIBUTORS.

ISSUES CLOSED: #7592
docs: fix inaccurate fast-path claim in CLI basics documentation
Some checks failed
CI / lint (pull_request) Successful in 1m21s
CI / typecheck (pull_request) Successful in 1m33s
CI / security (pull_request) Successful in 1m33s
CI / benchmark-publish (pull_request) Has been skipped
CI / quality (pull_request) Successful in 1m35s
CI / push-validation (pull_request) Successful in 30s
CI / helm (pull_request) Successful in 35s
CI / build (pull_request) Successful in 46s
CI / benchmark-regression (pull_request) Failing after 1m11s
CI / integration_tests (pull_request) Successful in 4m46s
CI / e2e_tests (pull_request) Failing after 3m20s
CI / unit_tests (pull_request) Successful in 6m11s
CI / docker (pull_request) Successful in 1m30s
CI / coverage (pull_request) Successful in 14m8s
CI / status-check (pull_request) Failing after 5s
ec0dded425
The version, info, and diagnostics commands were incorrectly stated as being on the fast-path. Only --help and --version are eager exit options that skip subcommand module loading.

ISSUES CLOSED: #7592
HAL9001 left a comment

Review Summary

This PR adds a showcase example for the CLI version, info, and diagnostics commands and fixes an inaccurate fast-path claim in the documentation. The documentation content itself is accurate, well-written, and the fast-path correction is correct. However, there are five blocking issues that must be resolved before this PR can be merged.


CI Gate Status (required-for-merge checks)

Check Status
lint success
typecheck success
security success
unit_tests success
coverage success

The five required-for-merge CI checks all pass. However, two other CI jobs are failing (see blockers below).

Failing CI Jobs

Check Status
e2e_tests failing after 3m20s
benchmark-regression failing after 1m11s
status-check (gate) failing (aggregator)

BLOCKING Issues

1. CI failures: e2e_tests and benchmark-regression are failing.
Per CONTRIBUTING.md, all CI jobs must pass before a PR can be merged. status-check is the merge gate aggregator and currently reports failure. Investigate whether these failures are pre-existing or introduced by this branch. Either fix them or document clearly that they are pre-existing infrastructure failures unrelated to this PR and request maintainer override.

2. Two commits for one issue - violates the one-issue-one-commit atomicity rule.
CONTRIBUTING.md requires each issue to map to exactly one commit. This PR has two commits that both close #7592:

  • fee708e0: docs: add showcase example for CLI version/info/diagnostics basics
  • ec0dded4: docs: fix inaccurate fast-path claim in CLI basics documentation

The second commit is a correction to the first. Per project policy, history must be cleaned up before merging using interactive rebase to squash fixup commits. These two commits must be squashed into a single atomic commit.

3. Branch name does not follow naming conventions.
The branch is fix-pr-4211. Per CONTRIBUTING.md, documentation-only changes must use the feature/mN-<descriptive-name> prefix, where N is the milestone number. Issue #7592 is in milestone v3.6.0, so the branch should be named feature/m6-<descriptive-name> (e.g. feature/m6-showcase-cli-basics). The fix-pr- prefix is not a recognized convention and the milestone number is absent entirely. Note: if renaming is not possible after the PR is open, document the deviation in the PR body.

4. PR has no milestone assigned.
CONTRIBUTING.md requires the PR to be assigned to the same milestone as the linked issue. Issue #7592 is in milestone v3.6.0. Please assign milestone v3.6.0 to this PR.

5. PR has no Type/ label.
CONTRIBUTING.md requires exactly one Type/ label on every PR. This PR should have Type/Documentation applied.


Non-Blocking Suggestions

S1. PR body closing keyword format.
The PR body ends with **ISSUES CLOSED: #7592 (bolded, no Forgejo closing syntax). While the commit footers correctly use ISSUES CLOSED: #7592, the PR body should also use Forgejo closing keyword syntax (Closes #7592 or Fixes #7592) to trigger automatic issue close on merge.

S2. CHANGELOG entry references old PR number.
The CHANGELOG entry refers to (#4211) (the previous PR number) rather than this PR (#11108). This should be updated to reference the correct PR number so the changelog correctly links to the merged PR.


Acceptance Criteria Check (Issue #7592)

Criterion Status
Documentation explains fast-path vs regular command behavior accurately PASS - Fixed in ec0dded4: only --help and --version are fast-path; version, info, diagnostics correctly described as lightweight but not fast-path
Showcase examples list updated without losing existing entries PASS - examples.json shows all 5 existing entries plus the new entry added correctly
CLI coverage robot tests continue to pass PASS - integration_tests passed

Content Quality Assessment

The documentation itself is high quality: the showcase walkthrough is clear, accurate, and beginner-friendly. All command examples include actual output and explanations. The scripting example is practical and correct. The format flag table is comprehensive and accurate. The diagnostics --check CI-friendly usage is well-documented. Once the blocking process issues are resolved, the documentation content itself is approvable.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker

## Review Summary This PR adds a showcase example for the CLI `version`, `info`, and `diagnostics` commands and fixes an inaccurate fast-path claim in the documentation. The documentation content itself is accurate, well-written, and the fast-path correction is correct. However, there are **five blocking issues** that must be resolved before this PR can be merged. --- ### CI Gate Status (required-for-merge checks) | Check | Status | |---|---| | `lint` | success | | `typecheck` | success | | `security` | success | | `unit_tests` | success | | `coverage` | success | The five required-for-merge CI checks all pass. However, two other CI jobs are failing (see blockers below). ### Failing CI Jobs | Check | Status | |---|---| | `e2e_tests` | failing after 3m20s | | `benchmark-regression` | failing after 1m11s | | `status-check` (gate) | failing (aggregator) | --- ### BLOCKING Issues **1. CI failures: `e2e_tests` and `benchmark-regression` are failing.** Per CONTRIBUTING.md, all CI jobs must pass before a PR can be merged. `status-check` is the merge gate aggregator and currently reports failure. Investigate whether these failures are pre-existing or introduced by this branch. Either fix them or document clearly that they are pre-existing infrastructure failures unrelated to this PR and request maintainer override. **2. Two commits for one issue - violates the one-issue-one-commit atomicity rule.** CONTRIBUTING.md requires each issue to map to exactly one commit. This PR has two commits that both close #7592: - fee708e0: docs: add showcase example for CLI version/info/diagnostics basics - ec0dded4: docs: fix inaccurate fast-path claim in CLI basics documentation The second commit is a correction to the first. Per project policy, history must be cleaned up before merging using interactive rebase to squash fixup commits. These two commits must be squashed into a single atomic commit. **3. Branch name does not follow naming conventions.** The branch is `fix-pr-4211`. Per CONTRIBUTING.md, documentation-only changes must use the `feature/mN-<descriptive-name>` prefix, where N is the milestone number. Issue #7592 is in milestone v3.6.0, so the branch should be named `feature/m6-<descriptive-name>` (e.g. feature/m6-showcase-cli-basics). The fix-pr- prefix is not a recognized convention and the milestone number is absent entirely. Note: if renaming is not possible after the PR is open, document the deviation in the PR body. **4. PR has no milestone assigned.** CONTRIBUTING.md requires the PR to be assigned to the same milestone as the linked issue. Issue #7592 is in milestone v3.6.0. Please assign milestone v3.6.0 to this PR. **5. PR has no Type/ label.** CONTRIBUTING.md requires exactly one Type/ label on every PR. This PR should have Type/Documentation applied. --- ### Non-Blocking Suggestions **S1. PR body closing keyword format.** The PR body ends with `**ISSUES CLOSED: #7592` (bolded, no Forgejo closing syntax). While the commit footers correctly use `ISSUES CLOSED: #7592`, the PR body should also use Forgejo closing keyword syntax (Closes #7592 or Fixes #7592) to trigger automatic issue close on merge. **S2. CHANGELOG entry references old PR number.** The CHANGELOG entry refers to (#4211) (the previous PR number) rather than this PR (#11108). This should be updated to reference the correct PR number so the changelog correctly links to the merged PR. --- ### Acceptance Criteria Check (Issue #7592) | Criterion | Status | |---|---| | Documentation explains fast-path vs regular command behavior accurately | PASS - Fixed in ec0dded4: only --help and --version are fast-path; version, info, diagnostics correctly described as lightweight but not fast-path | | Showcase examples list updated without losing existing entries | PASS - examples.json shows all 5 existing entries plus the new entry added correctly | | CLI coverage robot tests continue to pass | PASS - integration_tests passed | --- ### Content Quality Assessment The documentation itself is high quality: the showcase walkthrough is clear, accurate, and beginner-friendly. All command examples include actual output and explanations. The scripting example is practical and correct. The format flag table is comprehensive and accurate. The diagnostics --check CI-friendly usage is well-documented. Once the blocking process issues are resolved, the documentation content itself is approvable. --- Automated by CleverAgents Bot Supervisor: PR Review | Agent: pr-review-worker
Owner

Suggestion: CHANGELOG entry references the old PR number #4211 instead of the current PR #11108.

This line reads: - CLI showcase: version/info/diagnostics basics (#4211):

This PR is #11108. The reference to #4211 appears to be a carry-over from a previous attempt at this work. Please update to reference #11108 so the changelog correctly links to the merged PR.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker

Suggestion: CHANGELOG entry references the old PR number #4211 instead of the current PR #11108. This line reads: - CLI showcase: version/info/diagnostics basics (#4211): This PR is #11108. The reference to #4211 appears to be a carry-over from a previous attempt at this work. Please update to reference #11108 so the changelog correctly links to the merged PR. --- Automated by CleverAgents Bot Supervisor: PR Review | Agent: pr-review-worker
Owner

BLOCKING: Pre-existing conflict marker present in this file.

Line 20 contains a <<<<<<< HEAD merge conflict marker. While this marker originates from a prior merge on the base branch (it was present before this PR), this PR adds new content to CONTRIBUTORS.md on top of a file that already contains an unresolved conflict marker. Merging this PR would perpetuate the corrupted state.

The correct fix is:

  1. Rebase this branch on master
  2. Resolve the conflict marker in CONTRIBUTORS.md (removing the <<<<<<< HEAD marker and any ======= and >>>>>>> markers) during the rebase
  3. Add your new contribution line cleanly after the conflict is resolved

This must be resolved before merge.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker

BLOCKING: Pre-existing conflict marker present in this file. Line 20 contains a `<<<<<<< HEAD` merge conflict marker. While this marker originates from a prior merge on the base branch (it was present before this PR), this PR adds new content to CONTRIBUTORS.md on top of a file that already contains an unresolved conflict marker. Merging this PR would perpetuate the corrupted state. The correct fix is: 1. Rebase this branch on master 2. Resolve the conflict marker in CONTRIBUTORS.md (removing the <<<<<<< HEAD marker and any ======= and >>>>>>> markers) during the rebase 3. Add your new contribution line cleanly after the conflict is resolved This must be resolved before merge. --- Automated by CleverAgents Bot Supervisor: PR Review | Agent: pr-review-worker
Owner

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker

--- Automated by CleverAgents Bot Supervisor: PR Review | Agent: pr-review-worker
Some checks failed
CI / lint (pull_request) Successful in 1m21s
Required
Details
CI / typecheck (pull_request) Successful in 1m33s
Required
Details
CI / security (pull_request) Successful in 1m33s
Required
Details
CI / benchmark-publish (pull_request) Has been skipped
CI / quality (pull_request) Successful in 1m35s
Required
Details
CI / push-validation (pull_request) Successful in 30s
CI / helm (pull_request) Successful in 35s
CI / build (pull_request) Successful in 46s
Required
Details
CI / benchmark-regression (pull_request) Failing after 1m11s
CI / integration_tests (pull_request) Successful in 4m46s
Required
Details
CI / e2e_tests (pull_request) Failing after 3m20s
CI / unit_tests (pull_request) Successful in 6m11s
Required
Details
CI / docker (pull_request) Successful in 1m30s
Required
Details
CI / coverage (pull_request) Successful in 14m8s
Required
Details
CI / status-check (pull_request) Failing after 5s
This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin fix-pr-4211:fix-pr-4211
git switch fix-pr-4211
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core!11108
No description provided.