fix(docs): mark generateText image batching as unavailable in the published CLI

Summary

The live command reference says that image generation with --n above 1 makes separate generateText calls. The package installed by the site's standard npm installation command still rejects that combination. Users following the reference cannot use the documented batching behavior with the published CLI.

The batching implementation has already merged. This report concerns the remaining mismatch between the live documentation and the published package.

Steps to reproduce

These are package and documentation inspection steps. No CLI execution or model request was performed.

1. Read the live installation page and its npm install -g ai-cli instruction.
2. Read the command reference's image section, which says that --n makes one generateText call per requested image, with --concurrency limiting those calls.
3. Fetch the npm registry's latest metadata and inspect its referenced tarball. The archive's SHA-512 matches dist.integrity; its package/dist/index.js contains a guard rejecting settings.n !== 1 when any model uses generateText.
4. Compare that guard with the published revision's image command and shared option parser. For example, the supported entry point ai image "draw a lighthouse" -m google/gemini-2.5-flash-image --api generateText --n 2 selects the text API and parses the count as the number 2. With no size, mask, batching-limit, or reference-image options, it reaches the count rejection before generation. This command was not executed.

Expected behavior

The live reference should identify the version needed for batching, or describe behavior available through its standard installation instructions. A reader should be able to tell whether the documented combination is available in the published package.

Actual behavior

The live reference describes batching without a release qualification. The published bundle and corresponding source reject it. The guard's source message is:

generateText does not support --size, --mask, --max-images-per-call or --n other than 1; use --provider-options for model-specific image settings

This is quoted source text, not captured CLI output. The published source registers --n, parses it with parsePositiveInt, accepts an explicit generateText API and full model ID without requiring successful discovery, and then rejects a count other than 1 before runMediaJobs invokes generation.

Runtime or environment

• Published baseline: npm ai-cli@0.8.0, registry latest, with gitHead bd9d87a8ead2ff247b669fc6d4bcac90e8d96353.
• Default-branch baseline: main at 20592fdd6deb68e09856f675a54e685b05b02226, whose package manifest prepares 0.8.1 and includes the batching implementation.
• Documentation: live, unversioned production command and installation pages, inspected over HTTP. The command page was fetched with Accept: text/markdown.
• Node.js and CLI runtime platform: unmeasured because the CLI was not executed.

Evidence

• Expected source: The live command reference, image section, describes per-image generateText calls and the calls JSON field; the installation page directs users to the unqualified npm install command.
• Failure source: The npm latest metadata, its integrity-checked tarball's package/dist/index.js, and the published revision's image command, lines 76–178. The shared media options, lines 50–149 register and parse the count. The model resolver, lines 293–330 preserves a full model ID independently of the catalog.
• Evidence provenance: static
• Local verification: static-proof
• Reproduction completeness: complete

Fresh published-bundle and pinned-source inspection establish the contradiction; live documentation and registry metadata were observed over HTTP. The supported explicit-API entry point, numeric count, model resolution, and pre-generation guard were traced. Runtime reproduction and end-to-end generation were not run. Completeness describes the documentation/package contradiction.

Restoration check

Repeat the inspection using the live installation instructions, current npm latest, and live command reference. The reference should accurately identify when the documented count is supported. If batching is described as available through standard installation, that published artifact must support the combination; otherwise the docs should explain its version requirement or current limitation. Preserve the existing single-image path.

References

• Merged batching implementation, PR #113: implements the documented behavior on the default branch.
• Merged release preparation, PR #116: prepares the next package version, but the npm latest metadata still points to the published baseline above. These merged changes do not by themselves establish npm publication.

Additional context

Separate --n 1 invocations avoid this count guard in the published source. This workaround is source-supported; successful model generation was not tested.

Co-contributor credit

No, do not credit me.

Checklist

• I have searched existing issues for duplicates.
• I have removed API keys, tokens, credentials, and private data from this report.

Triage assessment

• Impact level: P2
• Assessment status: supported
• Impact basis: Following the live image batching reference selects a combination the published package rejects before generation. The affected input is bounded to generateText image counts above 1.
• Workaround status: available
• Workaround basis: Separate single-image invocations avoid the count guard without changing model selection. Availability is established from source; end-to-end generation remains untested.