Repository navigation
docs: map user goals to CLI commands and outcomes - #48
Merged
Merged
Conversation
The README listed the CLI in prose and one package-table row, so a reader could not see search, embed, analyze, the lake and corpus groups or the analytics views. A "What you can do" table now covers all 16 registered commands plus three headline queries taken from `atif-sql examples`, each linking to its docs/reference/cli.md anchor, with the Bedrock commands marked as costing money. Corrections the CLI backs: the atif-analytics row named trajectory, cluster, terms and community pipelines that `analyze` does not run (it runs classify, conflicts, friction and perceived), and the Install note called search dry-run by default when only analyze is (embed needs --limit or --all, search embeds one query per call). cli.md gains the missing `lake` section and the --all-corpora and --no-lake flags on query and search. Quick start prose the matrix now carries is trimmed. test_readme_matrix.py walks the cyclopts command tree and fails when a command has no row, when a row names a command the app lacks, when a link misses its cli.md heading, and when the matrix parses zero rows. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Readers choose commands to recover prior work, compare agent histories, review recurring corrections, and keep their session history current. Describe those goals and their outcomes before the implementation details. Clarify paid execution defaults, conversion output, search prerequisites, lower-bound cost estimates, and paid scheduled embedding and analysis. Lower the existing prose baseline to its observed warning count.
laithalsaadoon
changed the title
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.
The README maps reader goals to commands and useful outcomes, so readers can find prior work by topic, compare Claude Code and Codex histories, inspect recurring corrections, and keep their history current.
The matrix covers all registered CLI commands and links each to its reference. It distinguishes previews from paid Bedrock execution, explains search prerequisites and lower-bound cost estimates, and makes scheduled embedding and analysis costs explicit. The CLI reference adds the lake commands and cross-corpus flags. A drift test checks command coverage and reference anchors.
Validation, checked 2026-10-09:
mise run check: passed, 2,490 tests passed, 1 skipped, 1 expected failure.mise run docs:gate: passed, 73 site tests and 1,962 internal links with 0 broken.The prose warning baseline falls by one warning to match the measured count.