[Hackathon] Reconcile the CLI guide and add a reliable automation journey

[rohith500]

Problem Statement

The current HydraDB CLI page is not fully aligned with the published hydradb-cli interface and stops short of a reliable automation journey.

Verified examples of the drift include:

• examples pass tenant IDs and text as positional arguments even though the current commands use stored configuration/--tenant-id and --text
• environment-variable names differ from the CLI's actual HYDRA_DB_* names
• the page recommends hydradb config set output json, although output is not a supported persisted config key
• command tables and copy-paste examples do not match the released command signatures
• the automation section does not cover asynchronous ingestion verification, response-level partial failures, or safe JSON handling

This means several documented commands fail when copied, and a script can mistake an HTTP-success response containing failed items for a successful ingestion.

Affected page: https://docs.hydradb.com/plugins/cli

Proposed Solution

Reconcile the CLI page against the released CLI source and add a focused production-automation journey:

1. Correct installation, authentication, environment variables, command signatures, and examples.
2. Add a compact CLI command-routing table—Memory commands vs. Knowledge commands—without duplicating the broader conceptual guides.
3. Document an end-to-end upload → verify → recall flow that accounts for asynchronous indexing.
4. Explain global JSON output, response validation, current exit-code limitations, and CI-friendly failure checks.
5. Add safe rerun guidance using supported stable IDs and upsert controls.
6. Validate examples against the released CLI source/help output and the Mintlify build.

Related CLI work that exposed these documentation gaps:

• Fix/explicit upsert and exit codes hydradb-cli#12
• fix(client): exit non-zero when memory add reports failed items hydradb-cli#13
• fix(cli): escape user content in Rich output hydradb-cli#14

The documentation will describe released behavior. Pending CLI improvements will be context for the audit, not presented as already available.

Overlap Audit

A full review of all repository issues and pull requests found no earlier issue or PR implementing this CLI correctness and automation journey.

PR #180 also touches plugins/cli.mdx, but its CLI change is limited to a short legacy tenant/database terminology note. This proposal will preserve that clarification if #180 merges and does not duplicate its endpoint/metadata corrections.

Several hackathon submissions cover Memory vs. Knowledge conceptually. This proposal intentionally limits that topic to a small command-routing aid and focuses on executable CLI behavior.

Alternatives Considered

Add another general Memory-vs.-Knowledge page

Several active submissions already cover that journey. It would not correct the broken CLI examples or automation contract.

Copy the CLI repository README verbatim

The README is useful command reference material, but copying it would not connect asynchronous ingestion, response validation, reruns, and recall into one reliable journey.

Only correct individual typos

That would make isolated commands accurate while leaving the overall script lifecycle unclear and unsafe.

Additional Context

This is proposed as a focused HydraDB × Docs hackathon contribution.