feat(RHIDP-14129): add intent-based CLI commands and backstage-cli pass-through

AGENTS.md

@@ -13,21 +13,31 @@
 
 ## Key Conventions
 
-<!-- Add 2-3 conventions an agent couldn't discover by reading the code —
-     e.g. co-location rules, naming patterns, file organisation decisions. -->
+- CLI command groups are co-located under `src/commands/intent-based-actions/`;
+  register new groups in that directory's `index.ts`.
+- Keep human/JSON rendering in `format.ts`, Backstage action invocation in
+  `client.ts`, and command-level error presentation in `intent-errors.ts`.
+- Add or update the co-located `*.test.ts` file when changing command behavior.
 
 ## Architecture
 
-<!-- Add non-obvious architectural decisions or places where things live
-     unexpectedly — e.g. why a module lives where it does, key abstractions,
-     anything that would surprise a reader unfamiliar with the project. -->
+- Intent-based commands invoke the bundled `@backstage/cli` through
+  `backstage-cli actions execute`; they do not call Backstage HTTP APIs
+  directly.
+- `backstage-passthrough.ts` owns the lower-level `auth`, `actions`, and
+  `sources` commands, while the other files wrap action execution with
+  purpose-specific flags and output formatting.
+- `docs list`, `docs get`, and `docs coverage` use the RHDH-only
+  `techdocs-mcp-extras` actions. `docs search` uses the standard
+  `search:query` action.
 
 ## Pattern References
 
-<!-- Point agents to 3-5 real examples for the most common change types.
-     Example:
-     - New CLI command: follow the pattern in `src/commands/config/show.ts`
-     - New lib utility: see `src/lib/parallel.ts` as reference -->
+- New command group: `src/commands/intent-based-actions/catalog.ts`
+- Shared list/search command behavior: `src/commands/intent-based-actions/helpers.ts`
+- Human/JSON output formatting: `src/commands/intent-based-actions/format.ts`
+- Structured CLI errors: `src/commands/intent-based-actions/intent-errors.ts`
+- Repeatable `key=value` and JSON input parsing: `src/commands/intent-based-actions/kv.ts`
 
 ## PR Conventions
 

README.md

@@ -82,6 +82,70 @@ or when executing from the project root you can also use:
 npx @red-hat-developer-hub/cli
 ```
 
+## Commands
+
+The CLI provides two categories of commands:
+
+### Plugin Development Commands
+
+- `plugin export`: Export a Backstage plugin as a dynamic plugin
+- `plugin package`: Package dynamic plugins for distribution
+- `plugin check-versions`: Verify plugin compatibility with RHDH versions
+
+### Intent-Based RHDH Interaction Commands
+
+High-level commands for interacting with RHDH instances:
+
+- `auth`: Log in to, select, inspect, and manage authenticated RHDH instances
+- `actions`: List and execute actions, and manage action-discovery sources
+- `catalog`: List, get, validate, register, and unregister catalog entities
+- `api`: List API entities and retrieve their OpenAPI/AsyncAPI/GraphQL specifications
+- `search`: Search catalog, TechDocs, and template content
+- `docs`: Search TechDocs and, on RHDH instances with optional plugins, list entities, retrieve pages, and view coverage
+- `template`: List, execute, and dry-run software templates
+
+**Quick Examples:**
+
+```bash
+# Authenticate with your RHDH instance
+rhdh-cli auth login --backend-url https://rhdh.example.com
+
+# List production components
+rhdh-cli catalog list --kind Component --filter spec.lifecycle=production
+
+# Search documentation
+rhdh-cli search "deployment guide" --types '["techdocs"]'
+
+# Get API specification
+rhdh-cli api get-spec --name my-api
+
+# Execute a template
+rhdh-cli template execute \
+  --template-ref template:default/nodejs-service \
+  --value name=my-app \
+  --value owner=team-platform
+```
+
+All commands support `--help` for detailed usage and `--output json` for machine-readable output.
+
+**📚 For complete documentation, setup guides, and examples, see:**
+
+- **[Intent-Based CLI Documentation](docs/Intent-Based-CLI.md)** - Complete guide for RHDH interaction commands
+
+### Optional TechDocs Features
+
+**TechDocs content retrieval** (`docs list`, `docs get`, `docs coverage`, `docs build`):
+
+- Requires **TechDocs MCP extras plugin** (`techdocs-mcp-extras`)
+- See the [CLI documentation](docs/Intent-Based-CLI.md#rhdh-instance-configuration) for setup instructions
+
+**TechDocs search** (`docs search`):
+
+- Requires **TechDocs search backend module** (`search-backend-module-techdocs`)
+- Standard Backstage plugin for indexing TechDocs content
+
+All other commands work without these optional plugins.
+
 ### Bumping Backstage Dependencies
 
 To update the `@backstage/*` dependencies to a new Backstage release: