668.1-help-system Implement progressive disclosure help system for prompt commands

[codekiln]

Summary

Implement a three-level progressive disclosure help system for langstar prompt commands to improve discoverability and AI-first UX.

Parent: #668 (ls-prompt-ux milestone)
Phase: 1 of 4 (Non-Breaking)
Design: docs/implementation/ls-prompt-ux-command-redesign.md (section: Phase 1)

Goals

Replace flat --help output with a hierarchical help system that guides exploration:

• Level 1: Command overview (langstar prompt help)
• Level 2: Command-specific help (langstar prompt list help)
• Level 3: Detailed help (langstar prompt list help details)

Implementation Tasks

• Add help subcommand infrastructure to CLI
• Implement Level 1: Overview help (langstar prompt help)
  • Show available commands (list, get, create, update)
  • Show basic examples
  • Show how to get more help
• Implement Level 2: Command-specific help (langstar prompt <cmd> help)
  • Usage syntax
  • Common flags
  • Basic examples
  • Link to detailed help
• Implement Level 3: Detailed help (langstar prompt <cmd> help details)
  • Behavior explanation
  • Pagination details
  • Search details
  • Output format details
  • Scoping details
• Keep existing --help flag working (backward compatibility)
• Document progressive disclosure pattern for other commands
• Add tests for all help levels

Example Output

Level 1 (langstar prompt help):

Manage LangSmith prompts

Commands:
  list      List or search prompts
  get       Read prompt content (text, metadata, model, schema)
  create    Create a new prompt
  update    Update existing prompt (text, metadata, model, schema)
  help      Show help for commands

Examples:
  langstar prompt list              # List all prompts (first page)
  langstar prompt get my-prompt     # Get prompt text
  langstar prompt create my-prompt  # Create new prompt

For detailed help on a command:
  langstar prompt list help
  langstar prompt get help details

Level 2 (langstar prompt list help):

List or search prompts in your workspace

Usage:
  langstar prompt list [search-term] [flags]

Flags:
  --all    Show all pages (default: first page only)

Examples:
  langstar prompt list                 # First page of prompts
  langstar prompt list rag             # Search for "rag"
  langstar prompt list --all           # All prompts (all pages)

For more details:
  langstar prompt list help details

Level 3 (langstar prompt list help details):

Detailed usage for 'langstar prompt list'

Behavior:
  - Without arguments: Lists first page of prompts in workspace
  - With search term: Server-side search, first page of results
  - With --all flag: Fetches all pages until exhaustion

Pagination:
  - Default page size: 20 prompts
  - --all: Continues fetching until no more results

Search:
  - Multi-word terms: Use quotes: "structured output"
  - Case-insensitive
  - Searches: name, description, tags

Output Format:
  - Table: Handle, Type, Downloads, Description
  - Type: "Regular" or "Structured" (has JSON schema)
  - Use --output json for programmatic access

Testing Requirements

• Test langstar prompt help shows overview
• Test langstar prompt list help shows command help
• Test langstar prompt list help details shows detailed help
• Test --help flag still works for backward compatibility
• Test help for all commands: list, get, pull, push, search

Success Criteria

• Three-level help system works for all prompt commands
• Help output follows progressive disclosure pattern
• Backward compatibility maintained with --help flag
• AI agents can navigate help system to find correct command
• Documentation pattern is documented for other commands

References

• Design document: docs/implementation/ls-prompt-ux-command-redesign.md
• Parent issue: ls-prompt-ux milestone - Improve UX consistency across prompt commands #668
• Related: 668.2-help-docs Fix --help documentation for all prompt commands #667 (may be superseded by this work)