docs: document CLI lifecycle and improve error messages - #11
Merged
mrsimpson merged 11 commits intoNov 26, 2025
Conversation
- Add comprehensive CLI documentation to README - Document docset lifecycle (DEFINE → CREATE → INITIALIZE → USE → REFRESH) - Add detailed documentation for all CLI commands (create, init, status, refresh) - Include practical examples and complete workflow - Enhance MCP server error messages with CLI usage instructions - Add setup instructions when config file not found - Include CLI commands in "docset not found" error - Add initialization check for git_repo sources with helpful CLI guidance This makes the CLI more discoverable and helps users understand the proper workflow for managing docsets.
- Simplify docset lifecycle from 5 to 4 phases - Remove redundant DEFINE/CREATE distinction - CREATE now covers both CLI and manual config editing - Clearer progression: CREATE → INITIALIZE → USE → REFRESH - Allow MCP server to start without configuration file - Server starts successfully even if no .knowledge/config.yaml exists - Tools advertise helpful setup instructions in their descriptions - Errors only occur when tools are actually invoked without config - Enhance tool descriptions for unconfigured state - search_docs shows complete setup guide when no docsets configured - list_docsets provides CLI and manual configuration examples - Both options (CLI and manual) clearly explained This improves the getting-started experience by allowing users to see the tools and their documentation before configuring docsets.
- Add clear explanation of when to use init vs refresh - init: First-time setup or complete reset (destructive) - refresh: Smart incremental updates (preserves state) - Highlight key difference in both command sections - Remove recency indicators from status documentation - No more green/yellow/red color coding - Show initialization date instead of "last refreshed" - Simpler, clearer status output This addresses common confusion about when to use each command and simplifies the status display to focus on initialization state.
- Remove color-coded recency indicators (green/yellow/red) - Show initialization date in YYYY-MM-DD format instead of "X ago" - Match simpler format documented in README - Cleaner, less judgmental status display Output now shows: - Docset name and ID - File count and source count - Initialization date - For non-initialized: helpful init command This removes the arbitrary recency thresholds and focuses on factual information about when docsets were initialized.
- Streamline README to focus on value proposition and quick start - New tagline: "Search any documentation as if you had written it yourself" - Clear "What Is This For?" section with use cases - Minimal quick start (4 simple steps) - Move philosophy/RAG comparison to "How and Why It Works" section - Create comprehensive USER_GUIDE.md with detailed usage - Complete CLI command documentation - Full docset lifecycle explanation - Configuration guide with all options - Complete workflow examples - MCP integration details - Troubleshooting section - Remove redundant content from README - No more 500+ line README mixing everything - Philosophy kept but moved to appropriate section - Essential CLI commands with link to user guide This makes the README scannable and approachable while preserving all detailed documentation in a dedicated guide.
- Change all CLI examples to use npx instead of global install - Installation: npm install (local) or npx (no install) - All commands: npx agentic-knowledge <command> - More aligned with modern MCP server practices - Add comprehensive Claude Desktop configuration - Show config file locations (macOS, Windows, Linux) - Option 1: npx (recommended, no installation needed) - Option 2: Project-specific with cwd - Option 3: Global installation (legacy) - Include -y flag to auto-confirm npx prompts - Update workflows to reflect automatic server startup - Server runs automatically via Claude Desktop - No need to manually start server - Clearer separation of CLI usage vs MCP server MCP servers are typically not installed globally - they run via npx in separate threads managed by the MCP client.
- Prefix unused test variables with underscore - Remove unused import (execSync) - Remove unused catch variable - Prefix unused ErrorType enum values with underscore - Update all references to use prefixed enum values All tests passing: 179/179 (100%) Linting clean (2 false positive warnings for constructor parameters)
The underscore prefixing was an ugly workaround for false positive linter warnings. Enum values ARE used throughout the codebase via ErrorType.CONFIG_NOT_FOUND, etc. Added comment explaining that linter warnings are false positives. All tests still passing (179/179).
Previously, search_docs would succeed even when a docset was created but not initialized, returning search instructions for an empty directory. Changes: - Check for .agentic-metadata.json file instead of just directory existence - Add test case for uninitialized docset search (should fail with helpful error) - Update web-sources tests to include metadata file in setup The fix ensures that docsets with git_repo sources must be initialized (via 'agentic-knowledge init') before they can be searched, providing clear error messages with CLI instructions when attempting to search an uninitialized docset. Fixes bug where docsets created via CLI but not initialized would still return successful search results.
mrsimpson
deleted the
claude/document-docset-cli-01EDcZbK6PdVCe9D19WtYGcw
branch
November 26, 2025 08:14
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
2 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.
Add comprehensive CLI documentation to README
Enhance MCP server error messages with CLI usage instructions
This makes the CLI more discoverable and helps users understand the proper
workflow for managing docsets.