@functional-systems/lambdadb-cli 0.1.0-dev.1

package/README.md

@@ -0,0 +1,309 @@
+# LambdaDB CLI
+
+A first, project-scoped CLI for developers, coding agents and CI. It uses
+`@functional-systems/lambdadb@0.5.1` for authentication, HTTP, read retries,
+pagination, bulk transfers and large response downloads.
+
+## Install and run
+
+Requires Node.js 22.14 or newer and npm.
+
+### Install from npm
+
+After the first development version is published, install the `dev` channel:
+
+```sh
+npm install --global @functional-systems/lambdadb-cli@dev
+lambdadb --version
+lambdadb --help
+```
+
+The `dev` channel contains prerelease versions. For reproducible CI runs, pin an
+exact published version instead of the moving `dev` tag. See
+[RELEASING.md](RELEASING.md#current-status) for release preparation status and
+[VALIDATION.md](VALIDATION.md) for verification results and remaining limitations.
+
+### Build from source
+
+From a checkout of this repository:
+
+```sh
+npm ci
+npm run build
+node dist/cli.js --help
+```
+
+Run commands with `node dist/cli.js`, or install the built directory into a local
+prefix to use the `lambdadb` executable:
+
+```sh
+npm install --prefix "$HOME/.local" /absolute/path/to/lambdadb-cli
+export PATH="$HOME/.local/node_modules/.bin:$PATH"
+lambdadb --help
+```
+
+`npm start -- ...` also works for human use. For machine-readable stdout, invoke
+`node dist/cli.js ... --json` or the executable directly; npm may print banners.
+
+## Configuration and authentication
+
+Obtain the endpoint, existing project name and project API key from the LambdaDB
+Console. This CLI does not create projects or issue keys. Endpoint is the API
+origin, such as `https://api.lambdadb.ai`, without `/projects/...`. HTTPS is
+required, except HTTP on localhost/127.0.0.1/::1 for local testing.
+
+```sh
+lambdadb configure --endpoint https://api.lambdadb.ai --project YOUR_DEV_PROJECT
+```
+
+Set `LAMBDADB_API_KEY` through your shell's secure input or your CI secret manager.
+For example, in Bash, this avoids putting the value into shell history:
+
+```bash
+read -r -s -p 'LambdaDB project API key: ' LAMBDADB_API_KEY
+printf '\n'
+export LAMBDADB_API_KEY
+```
+
+No command accepts a raw key argument. Configuration stores only `endpoint`,
+`project` and `apiKeyEnv`. Keys are read from the selected environment variable at
+runtime and are never persisted by this CLI. Environment variables are still
+accessible to the current process and appropriately privileged local processes;
+the CLI is not a secret vault. Avoid shell tracing around secret injection.
+
+The default configuration is
+`${XDG_CONFIG_HOME:-$HOME/.config}/lambdadb/config.json`. Writes use an atomic
+rename and file mode `0600`; newly created directories use `0700` (POSIX).
+Configuration is user-local, not discovered from the working repository.
+`.env` files are not automatically loaded, and are ignored by this repository.
+Use a CI secret manager instead of adding credentials to tracked files.
+
+| Setting | Precedence, highest first |
+| --- | --- |
+| Endpoint | `--endpoint`, `LAMBDADB_ENDPOINT`, saved `endpoint` |
+| Project | `--project`, `LAMBDADB_PROJECT`, saved `project` |
+| Key variable name | `--api-key-env`, `LAMBDADB_API_KEY_ENV`, saved `apiKeyEnv`, `LAMBDADB_API_KEY` |
+| Key value | Value of the selected variable only; no fallback to another key |
+| Config path | `--config`, `LAMBDADB_CONFIG`, default user path |
+| Network budget | `--timeout-ms`, `LAMBDADB_TIMEOUT_MS`, `30000` milliseconds |
+
+There is no implicit endpoint, project, collection, branch or read ref. Explicit
+empty values fail validation instead of silently falling back. An explicitly
+selected missing config file fails except when `configure` creates it.
+`configure` applies the same precedence and saves the selected non-secret values;
+it does not contact the service. To reference a different secret variable:
+
+```sh
+lambdadb configure --api-key-env MY_PROJECT_KEY
+lambdadb doctor --json
+```
+
+`doctor` validates configuration and uses `listCollections({size: 1})` to check
+authentication and project collection-list access. Success does not prove write
+permissions, collection readiness, or search visibility. Failure provides a safe
+error category and a recovery hint. SDK debug logging is disabled even when
+`LAMBDADB_DEBUG` is set. Error bodies, raw SDK errors and presigned response URLs
+are not printed. The active key is redacted if echoed inside returned data.
+Other document data remains visible; redirect results to appropriate storage.
+
+## First-use flow
+
+Only run the following against a project explicitly designated for development.
+Configuration and the API key must already be supplied as above. Replace
+`cli-demo-docs` with a new, unique collection name. Each JSON example is included
+in this repository.
+
+```sh
+lambdadb doctor
+lambdadb collections list --size 20
+lambdadb collections create --collection cli-demo-docs --index-config examples/index-config.json
+lambdadb collections describe --collection cli-demo-docs
+lambdadb docs import --collection cli-demo-docs --branch main --file examples/documents.jsonl
+lambdadb query --collection cli-demo-docs --ref branch:main --file examples/query.json
+lambdadb docs fetch --collection cli-demo-docs --ref branch:main --ids doc-1 doc-2 doc-3
+```
+
+Collection creation returns `state: "created"`. Import returns accepted counts,
+not committed or searchable counts. Both explicitly report
+`searchable: "not_verified"`. The sample query uses `consistentRead: false`.
+The first query/fetch can therefore be empty or encounter a transient loading
+error. Repeat reads after an appropriate delay and inspect expected IDs and
+contents; do not recreate the collection or blindly replay the import as a wait
+mechanism. There is no CLI readiness endpoint or readiness polling claim.
+
+For eligible ordinary writes, `docs fetch --consistent-read` or a query file
+with `"consistentRead": true` can overlay pending writes when reading a direct
+branch. This does not establish committed indexing, excludes pending bulk
+imports, can return `429`, and is rejected for tag/alias refs.
+
+### Collections
+
+```sh
+lambdadb collections list --all --size 100 --json
+lambdadb collections list --page-token 'TOKEN_FROM_PREVIOUS_RESULT' --json
+lambdadb collections describe --collection cli-demo-docs --json
+```
+
+One page is the default; `nextPageToken` is an opaque continuation token.
+`--all` uses the SDK page iterator and buffers its result within the total network
+budget. No partial list is printed on failure. Collection statistics describe
+the committed head of `main`, not the selected read ref or whole-index readiness.
+The create input file is the index map itself, not a full create request body.
+
+### Import JSONL
+
+```sh
+lambdadb docs import --collection cli-demo-docs --branch main \
+  --file examples/documents.jsonl --batch-size 1000 --json
+
+lambdadb docs import --collection cli-demo-docs --branch main \
+  --file examples/documents.jsonl --mode bulk --timeout-ms 120000 --json
+```
+
+Input must be a UTF-8 regular file of at most 64 MiB and 100,000 documents.
+Each nonblank line must be a JSON object; blank lines do not count toward the
+document limit. Split files that exceed either limit before importing.
+If supplied, `id` must be a nonempty string. Omitted IDs are
+generated by the service and are not returned in the acceptance response; replay
+can create duplicates. Existing IDs are upserted and can replace existing data.
+
+The entire file is parsed and all batch sizes are checked before any network
+call. This keeps a malformed later line from causing a partial write, at the
+cost of buffering the input. Lines are scanned without allocating a separate
+array of every line, and document retention stops at the count limit. This bounds
+the overhead of many small documents, not the total process memory: large or
+complex documents can still use much more memory than the raw file size. Batches run
+sequentially and stop on the first failure. Counts count input records, not unique
+IDs. Repeated IDs are sent in input order; server resolution within a batch is
+not a CLI guarantee.
+
+Ordinary upsert defaults to 1,000 documents and a 4,000,000-byte serialized
+request cap including branch/envelope overhead. Bulk defaults to 1,000 documents
+and 16,000,000 bytes; `--batch-bytes` allows up to 64,000,000. These are conservative
+CLI limits, not advertised server maxima. The SDK also enforces the bulk limit
+returned by the server. `--mode bulk` calls the existing SDK `bulkUpsertDocs`
+helper with the selected branch, including signed upload headers and finalization.
+Bulk is unsupported for managed embedding vector fields; use ordinary upsert.
+
+Import result fields are stable under `schemaVersion: 1`:
+
+- `total`, `accepted`, `failed`, `unknown`, `notAttempted`: input record counts;
+  their outcome counts sum to `total`.
+- `batches`: attempted batch number, first/last physical JSONL lines, document
+  count, state and a sanitized error where applicable.
+- `state`: `accepted`, `failed`, `partial` or `unknown`.
+- `searchable`: always `not_verified` in this MVP.
+
+A definite HTTP rejection is `failed`. A disconnect, timeout, server error or
+invalid success response after dispatch is conservatively `unknown`. An unknown
+batch takes precedence over partial success in the exit code. The bulk SDK does
+not expose structured failure stages for local/upload exceptions, so those also
+use `unknown`; it can overstate uncertainty when upload failed before finalization.
+The CLI does not parse SDK error strings to guess the stage. A deadline reached
+between batches leaves unsent records `notAttempted`.
+
+There are no durable checkpoints, automatic resume, exactly-once guarantees,
+write retries or server mutation receipts. Inspect the selected branch and batch
+line ranges before constructing a deliberate retry. Do not treat accepted counts
+as a readiness check. A hard process kill may prevent any final report.
+
+### Query and fetch at explicit refs
+
+```sh
+lambdadb query --collection cli-demo-docs --ref tag:release-one --file examples/query.json --json
+lambdadb docs fetch --collection cli-demo-docs --ref alias:production --ids doc-1 --json
+lambdadb docs fetch --collection cli-demo-docs --ref branch:main --ids doc-1 --consistent-read --json
+```
+
+These examples require the named ref to exist. Query files use the SDK/API
+request body, including a `query` object and optional `size`, `sort`, `fields`,
+`partitionFilter`, `consistentRead` and `includeVectors`. The query DSL is forwarded
+to the API, not reimplemented in the CLI. Unknown top-level fields are rejected.
+`size` accepts 1–100, `null`, or omission; null is normalized to SDK omission.
+An optional file `ref` must match the mandatory `--ref`; conflicting selectors
+are rejected. Fetch accepts up to 100 IDs and reports `missingIds` without
+turning a successful missing-document response into an error.
+
+The SDK downloads large query/fetch responses from `docsUrl` automatically using
+its separate unauthenticated transfer client. Results are buffered, not streamed
+or truncated. The CLI omits the consumed signed URL. No ref is resolved to or
+claimed to pin a snapshot by the CLI. Branches and aliases can move between calls.
+
+## Output, deadlines and exit codes
+
+`--json` emits exactly one JSON object plus a newline on stdout for an executed
+command, including failures. It contains `schemaVersion`, `command`, `ok`, optional
+`target`, `data` and `error`. Target includes endpoint/project and, where relevant,
+collection and explicit ref/branch. Errors use stable categories and safe hints.
+API-specific response data may grow as the upstream API evolves. Help/version
+remain plain text even with `--json`. Default output adds a readable summary and
+pretty-printed data. Progress and diagnostics go only to stderr. No ANSI styling
+or interactive prompts are used.
+
+Credential redaction preserves fixed protocol field names and command, status,
+ref-kind and error-code tokens, even when a short credential coincides with one
+of them. It redacts variable string values and arbitrary document, index-config
+and tag-map keys. Returned data can therefore differ from the stored data when
+it contains the selected credential; public protocol tokens remain unchanged.
+If redacted map keys collide, unchanged keys keep their names and renamed keys
+receive unique `#N` suffixes, skipping existing names. Every entry is retained,
+with values still subject to credential redaction. Suffixes are local to each map.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | Success, including empty search/fetch results and write acceptance |
+| `2` | Invalid CLI input, file, request shape or configuration/missing credentials |
+| `3` | Authentication/API/request failure, or import with no accepted/unknown batches |
+| `4` | Incomplete import with some accepted records, no unknown outcomes |
+| `5` | At least one write outcome is unknown; inspect before retrying |
+
+The shared network deadline defaults to 30 seconds, covers retries, all pages,
+batches and signed transfers, and accepts 1–3,600,000 milliseconds. It starts
+after import/query input preflight. SIGINT/SIGTERM abort active network work;
+imports preserve acknowledged progress where the process can still report it.
+File parsing and formatting are outside the network budget. Read calls use the
+SDK backoff with a two-second retry budget; its sleep can add up to approximately
+500 ms after cancellation. Writes and bulk steps disable automatic retries.
+
+## Development and boundaries
+
+Development changes target the Git `develop` branch; reviewed release promotions
+for rc/stable target `main`. Once npm setup is complete and automatic publication
+is enabled, successful develop push CI publishes uniquely versioned packages on
+the `dev` channel. CI generates the number; developers do not increment it for
+every merge. Newer work may supersede pending builds. Stable releases remain
+explicit and use `latest`. See [CONTRIBUTING.md](CONTRIBUTING.md) for branch roles, PR checks
+and the release boundary. [RELEASING.md](RELEASING.md) covers version channels,
+npm bootstrap, Trusted Publishing and release checks. CI validates Node.js 22
+and 24 using local contracts and the same CLI contracts against an installed
+tarball.
+
+```sh
+npm run lint
+npm run check:version
+npm run typecheck
+npm test
+npm run test:package
+```
+
+Tests execute the real CLI and installed SDK against loopback HTTP servers. They
+cover the complete first-use flow, ref forwarding, signed transfers, pagination,
+partial and unknown writes, validation, output, credentials and exit codes.
+They do not contact a LambdaDB service. See [DESIGN.md](DESIGN.md) for contract
+evidence and [VALIDATION.md](VALIDATION.md) for measured verification scope.
+
+This MVP intentionally omits Branch/Tag/Alias management: default `main` supports
+first use, while reads can select existing refs. It also omits Console management,
+MCP, Git collection, chunking, embedding workflows, code-search logic, delete,
+plugins and publication. There are no changes to the SDK or reference repositories.
+
+Live verification requires an explicitly designated development project, endpoint
+and project key. Do not discover or borrow credentials from another repository.
+Use `npm run test:live` with the explicit opt-in settings in
+[RELEASING.md](RELEASING.md#explicit-live-smoke). It exercises ordinary/bulk import
+and committed query/fetch contents in a random temporary collection, then uses
+the SDK to clean up that collection. The normal test suite and CI never run it.
+
+## License
+
+Licensed under the [Apache License, Version 2.0](LICENSE).

package/RELEASING.md

@@ -0,0 +1,239 @@
+# Releasing LambdaDB CLI
+
+## Current status
+
+The first public development candidate is `0.1.0-dev.1`, targeting npm's `dev`
+channel. Release preparation sets `private: false`; metadata now permits
+publication, but no package has been published by this project workflow.
+The CLI is licensed under [Apache-2.0](LICENSE), with matching package metadata.
+The development-project smoke is recorded in [VALIDATION.md](VALIDATION.md).
+npm organization permission verification and an authorized first bootstrap from
+reviewed `develop` remain required. Main promotion is required for rc/stable
+releases, not for development publication. Automatic dev publication is disabled
+until the repository variable `NPM_DEV_PUBLISH_ENABLED` is set to `true` after
+bootstrap and Trusted Publishing setup.
+The public npm lookup for `@functional-systems/lambdadb-cli` returned E404 on
+2026-09-18; this is not proof that the name is available or that ownership exists.
+
+The workflow rejects private packages and missing license metadata. Explicit
+rc/stable releases also require matching tags, prerelease flags and dated
+changelog entries. Passing metadata validation does not establish live-service
+verification. Enabling automatic dev publication authorizes eligible develop
+pushes to publish after CI; rc/stable publication remains an explicit action.
+
+## Branch and version policy
+
+Follow [CONTRIBUTING.md](CONTRIBUTING.md): feature/fix PRs target `develop`,
+promotion PRs target `main`. Development versions publish from `develop` after
+CI, while rc/stable releases publish from reviewed `main` history. npm `latest`,
+not the main branch tip, identifies the stable npm version.
+
+| Source | Package version | Trigger | npm dist-tag |
+| --- | --- | --- | --- |
+| `develop` | `X.Y.Z-dev.N` | Push CI succeeds and automatic publication is enabled | `dev` |
+| `main` history | `X.Y.Z-rc.N` | GitHub prerelease `vX.Y.Z-rc.N` is published | `rc` |
+| `main` history | `X.Y.Z` | GitHub release `vX.Y.Z` is published | `latest` |
+
+Only these canonical version forms are supported. No leading zeroes or build
+suffixes. For reviewed version changes, update package.json and both root version
+entries in package-lock.json together; `npm version VERSION --no-git-tag-version`
+prepares this without a tag. For explicit releases, move release notes from
+Unreleased to a dated `## [VERSION] - YYYY-MM-DD` section.
+The executable reads package.json, so it has no independently maintained version.
+
+## Automatic development publication
+
+The `CI` workflow lives in `.github/workflows/publish.yaml`. Its Node 22 and 24
+jobs must both succeed for the exact push commit. Only a push to this repository's
+`develop` can enter automatic publication; PRs, main pushes and manual CI runs
+cannot. Only the publishing job receives `id-token: write`. No LambdaDB service
+keys are available to CI, so automatic dev builds do not imply a fresh live smoke.
+
+Keep a reviewed development base such as `0.1.0-dev.1` in Git. The publishing job
+uses the `X.Y.Z` prefix and sets `N` to `git rev-list --first-parent --count HEAD`
+from a full checkout. For example, count 12 produces `0.1.0-dev.12`. The counter
+includes commits that were never published; it is not necessarily consecutive
+in npm. A rerun of the same commit produces the same version. Force pushes and
+history rewrites must remain disabled. When starting the next release line,
+review a new base such as `0.2.0-dev.1`, including when synchronizing main back.
+
+Generated package/lock versions and `gitHead` are changed only in the runner;
+there are no version-bump commits, Git tags or GitHub Releases for automatic dev
+builds. The source changelog remains a reviewed summary rather than generating
+a dated entry for every build. npm `gitHead` and provenance identify the source.
+The workflow packs once, tests that exact tarball, and publishes it with
+`--tag dev --provenance`; `latest` is not changed.
+
+Dev publication jobs are serialized without interrupting an active registry
+write. A newer pending job can replace an older pending job. The current remote
+develop head is checked before preparation and immediately before publishing;
+stale jobs are skipped. The existing dev tag is also compared numerically to
+prevent an older version from moving it backward. This follows the latest
+eligible develop head rather than guaranteeing an artifact for every rapid merge.
+
+If a version already exists, a rerun checks its source commit and tarball integrity
+and skips publication only when they agree and the dev tag already points there.
+Conflicts fail; missing or older tag state requires maintainer investigation.
+Registry authentication, transport and invalid-response failures are not treated
+as missing versions. A publish request is never retried automatically. After a
+successful write, bounded registry reads verify the manifest and dev tag. If
+propagation is delayed, retry reads before rerunning the job. Newer dev versions
+and stale commits are skipped without changing tags.
+
+After setup, an eligible push is sufficient; no manual version increment is
+needed. Users update with `npm install -g @functional-systems/lambdadb-cli@dev`,
+or pin an exact published version for reproducible CI. Installed CLIs do not
+update themselves. Disable `NPM_DEV_PUBLISH_ENABLED` to stop future automatic
+publications; do not cancel an active registry write to simulate rollback.
+
+Treat command/flag changes, required target changes, JSON envelope changes and
+exit-code reinterpretations as compatibility changes. Describe migrations before
+shipping them. Additive optional fields can remain schemaVersion 1; incompatible
+JSON envelope changes require a new schemaVersion. During 0.x, put incompatible
+changes in a minor release; after 1.0, use a major release. Keep patch releases
+compatible. Human summaries are not a scripting interface.
+
+## Bootstrap and explicit rc/stable release preflight
+
+1. Prepare and review the release version, license file/metadata, changelog,
+   dependency changes and package inventory. Set `private: false` only in this
+   explicitly approved preparation. Preserve the exact repository URL.
+2. Run the following in a clean checkout of the candidate commit with Node
+   22.14+ (CI tests current Node 22 and 24). Do not load production credentials.
+
+   ```sh
+   npm ci
+   npm run lint
+   npm run check:version
+   npm run typecheck
+   npm test
+   npm run test:package
+   ```
+
+3. Run the live smoke below against an explicitly designated development project.
+   Record commit, SDK version, endpoint/project, command, outcome and cleanup
+   without keys or signed URLs. Missing credentials are a blocked release
+   prerequisite, not a skipped success. PR CI deliberately has no service keys.
+4. For rc/stable releases, promote to main by reviewed PR with required CI
+   checks. The first development bootstrap can use reviewed develop directly.
+   Re-run checks/live smoke if release contents changed. Record the verified
+   commit in release notes.
+5. Obtain explicit authorization for the immutable tag and publication. Tag the
+   verified main commit with `vVERSION`, push that tag, and publish a GitHub
+   Release with `prerelease: true` for rc and `false` for stable. Draft releases
+   do not publish npm. For the first development bootstrap, use the separate
+   procedure below; do not publish a dev GitHub Release.
+6. `.github/workflows/publish.yaml` validates main ancestry and metadata, runs
+   lint/types/local tests, packs once, installs and tests that exact tarball, then
+   publishes it with the selected dist-tag and provenance. The release workflow
+   does not rerun the credentialed live prerequisite; release owners must retain
+   that evidence before publishing the GitHub Release.
+7. Verify the workflow, npm version/dist-tag, provenance's repository/commit and
+   a clean consumer install of the exact version. Test the installed binary's
+   version/help and basic JSON behavior. Confirm a dev/rc release did not move
+   `latest`. Synchronize release-only main changes back to develop by PR.
+
+Useful read-only checks after publication:
+
+```sh
+npm view @functional-systems/lambdadb-cli@VERSION version dist.integrity dist.attestations --json
+npm view @functional-systems/lambdadb-cli dist-tags --json
+```
+
+Do not move published tags or republish a used version. If registry metadata is
+slow to propagate, retry reads; do not initiate another publication. For a bad
+release, stop promotion, document the impact and prepare a new patch version.
+Deprecation or dist-tag changes are explicit maintainer actions, not automatic
+rollback. Never silently downgrade consumers.
+
+## First publication and npm Trusted Publishing
+
+Trusted Publishers are package-specific. The SDK's configuration does not cover
+this CLI. npm requires an existing package before configuring its trust policy.
+See the official [npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
+
+For a new package, first complete the reviewed release preparation and preflight.
+An authorized npm organization owner performs the bootstrap from the verified
+develop commit, using interactive `npm login` and the account's MFA, then
+publishing the tested `0.1.0-dev.1` tarball with `--access public --tag dev`.
+Verify that the account has publication rights in npm's `functional-systems`
+organization; GitHub organization membership does not supply npm permissions.
+Use a real prerelease, not an empty placeholder. This
+one-time local publication does not provide GitHub Actions provenance. Do not
+also trigger the publish workflow for that same already-published version.
+
+After bootstrap, open the CLI package's npm **Settings → Trusted Publisher** and
+select GitHub Actions. Use these values for the workflow in this repository:
+
+| npm setting | Value |
+| --- | --- |
+| Package | `@functional-systems/lambdadb-cli` |
+| Organization or user | `lambdadb` |
+| Repository | `lambdadb-cli` |
+| Workflow filename | `publish.yaml` (filename only) |
+| Environment name | Leave empty; the job currently declares no environment |
+| Allowed actions | Enable direct `npm publish` |
+
+After those settings are saved, enable automatic publication in GitHub repository
+**Settings → Secrets and variables → Actions → Variables** by setting
+`NPM_DEV_PUBLISH_ENABLED=true`. This grants ongoing publication to eligible
+develop pushes. The next develop push (or rerun of its existing push workflow)
+validates and publishes an automatically numbered version. Keep the variable
+unset until bootstrap and trust configuration are complete. `workflow_dispatch`
+runs validation only. Push-triggered dev publication does not require main to
+contain the workflow; explicit GitHub Release handling does require the workflow
+on the default branch.
+
+The workflow uses a GitHub-hosted runner, Node 24, npm >=11.5.1 and
+`id-token: write`. No long-lived npm secret is required. If a GitHub Environment
+is later added, its exact name must also be configured on npm. Saving settings
+does not prove OIDC works; verify the next authorized publication. Current npm
+configurations can default to staged publishing only, which is insufficient for
+this direct-publish workflow. See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+
+## Explicit live smoke
+
+Provision a disposable development project/key outside this tool, with create,
+ordinary and bulk write, query/fetch and temporary-collection delete access.
+Supply the key through secure shell input or a secret manager, never in history.
+
+```sh
+export LAMBDADB_ENDPOINT=https://YOUR_DEV_API_ORIGIN
+export LAMBDADB_PROJECT=YOUR_DEV_PROJECT
+# Inject LAMBDADB_API_KEY securely; no .env file is loaded automatically.
+export LAMBDADB_RUN_LIVE_TESTS=1
+export LAMBDADB_LIVE_CONFIRM_PROJECT="$LAMBDADB_PROJECT"
+npm run test:live
+```
+
+The test fails before API calls when required settings are absent. It creates a
+random temporary collection, imports two 3 MiB documents plus a bulk document,
+and checks committed query/fetch contents with a maximum 300-second observation
+window per stage. Request timeouts and polling sleeps are capped to the remaining
+budget, and responses at or after the deadline cannot pass. Process termination
+and event-loop scheduling may delay reporting. It reports elapsed time and
+matched-document counts; a timeout is a failed smoke, not proof that accepted
+writes were rejected or lost.
+Collection cleanup uses the SDK because deletion is outside the public CLI MVP.
+Only the test's own collection is eligible for cleanup. An interrupted process
+or failed cleanup may leave that named collection; inspect it manually.
+
+This sample does not prove global index readiness, ranking quality, every ref's
+live behavior, or exactly-once writes. A large result alone does not prove the
+service selected docsUrl; mock tests explicitly exercise that transport path.
+Use existing known development tag/alias refs for additional live ref evidence.
+
+## Design references
+
+- LambdaDB TypeScript client `RELEASING.md` and `publish.yaml`: canonical channels,
+  separate live evidence, same tested artifact and OIDC. This CLI intentionally
+  publishes dev from develop, while rc/stable releases require main history.
+- LambdaDB migration `.goreleaser.yml`/release workflow and `install.sh`: verify
+  installed artifacts and explicit versions. Go binaries, GoReleaser and Docker
+  distribution are unnecessary for this npm CLI's first release.
+- [Command Line Interface Guidelines](https://clig.dev/): preserve machine output,
+  separate diagnostics, avoid interactive CI requirements, protect secrets and
+  test cancellation. The CLI contract suite exercises these boundaries.
+
+External documentation checked on 2026-09-18. Consult current npm documentation
+when configuring the package; registry requirements can change independently.