flashdata-cli 1.1.0__py3-none-win_amd64.whl

flashdata_cli/share/docs/release-notes-1.0.0.md

@@ -0,0 +1,47 @@
+# FlashData CLI v1.0.0
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs) · [English README](https://github.com/flashdatadev/flashdata-cli/blob/main/README.md) · [简体中文](https://github.com/flashdatadev/flashdata-cli/blob/main/README.zh-CN.md)
+
+Initial standalone FlashData CLI, built on the pinned and checksum-verified **FlashData Go SDK v1.0.0**. Ready-to-run binaries are available from the [official v1.0.0 release](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.0.0).
+
+## Included
+
+- Secure named profiles with Windows DPAPI, macOS Keychain/Linux Secret Service integration, or an explicitly selected protected file store. Keys are entered through hidden terminal input or stdin, never command arguments.
+- Recoverable machine onboarding, browser claiming and fresh-process credential verification before installation acknowledgement.
+- Google search, YouTube data and media delivery; general query, background and mixed-source batch commands.
+- Complete bulk create/upload/start/control/export workflows, streaming output, durable run IDs and recovery without automatic paid replay.
+- Account/source discovery, diagnostics, legacy state migration, English and Chinese READMEs, runnable inputs and offline tests.
+
+## Packages
+
+| Platform | Archive |
+| --- | --- |
+| Linux amd64 | `flashdata_1.0.0_linux_amd64.tar.gz` |
+| Linux arm64 | `flashdata_1.0.0_linux_arm64.tar.gz` |
+| macOS Intel | `flashdata_1.0.0_darwin_amd64.tar.gz` |
+| macOS Apple Silicon | `flashdata_1.0.0_darwin_arm64.tar.gz` |
+| Windows amd64 | `flashdata_1.0.0_windows_amd64.zip` |
+
+Archives contain the executable, English/Chinese READMEs, docs, example inputs and dependency license notices. The executable requires no separate Go, Node.js, Python or Docker installation. `build-report.json` records the exact CLI source commit, SDK version/checksum, toolchain, runtime source fingerprints and package hashes. The executable's `--version` reports 1.0.0 and that same source commit. The verified executables are unchanged from the tagged build; `documentationCommit` records the finalized package documentation separately, and executable hashes are included in the report.
+
+Download the matching public archive and SHA256SUMS; no GitHub sign-in is required. Follow the [English installation guide](https://github.com/flashdatadev/flashdata-cli/blob/main/docs/installation.md) or [简体中文安装指南](https://github.com/flashdatadev/flashdata-cli/blob/main/docs/installation.zh-CN.md). Put the extracted executable in a user-controlled PATH directory (`flashdata.exe` on Windows), then run `flashdata --version` and `flashdata --help` offline. The READMEs also explain building directly from the v1.0.0 source tag with Go 1.25+.
+
+## Checksums and verification
+
+`SHA256SUMS` covers all five archives, `build-report.json`, the separately attached English/Chinese READMEs and these release notes. From a directory containing all those files:
+
+```bash
+sha256sum -c SHA256SUMS
+```
+
+PowerShell: use `Get-FileHash -Algorithm SHA256 <file>` and compare its hash with the corresponding `SHA256SUMS` entry. Packages are not signed or notarized; SHA-256 checksums verify bytes and are not publisher signatures.
+
+## Validation and operational limits
+
+CI runs full tests/vet on Linux, Windows and Intel macOS with Go 1.25/1.27, Linux race checks, Apple Silicon cross-builds on both Go versions and all five archive builds. Native Apple Silicon execution and live macOS Keychain/Linux Secret Service integration remain separate acceptance checks; no native ARM runtime result is claimed.
+
+Onboarding is gated by server configuration. Imported-key recurring use requires the reviewed backend identity endpoint; unsupported identity responses fail closed. Publishing this CLI does not deploy backend changes, submit production paid work or verify customer storage. Lost or malformed submission responses remain uncertain: preserve the run ID and use read-only reconciliation/recovery before intentional new work. Cancellation stops local waiting while accepted remote work can continue.
+
+## 简体中文摘要
+
+独立 `flashdata` 命令行工具，锁定 Go SDK v1.0.0，覆盖安全凭据配置、可恢复接入、Google/YouTube 查询、后台批量任务、完整 Bulk 流程与持久化执行记录。提供 Linux amd64/arm64、macOS Intel/Apple Silicon、Windows amd64 安装包、构建记录和 SHA-256 校验和。GitHub Release 正式安装包现已提供公开下载；源码标签保持不变。原生 macOS 自动测试使用 Intel，Apple Silicon 已交叉编译，原生 ARM 运行及真实 Keychain/Secret Service 仍需单独验收。本次不部署后端或执行真实付费任务。

flashdata_cli/share/docs/release-notes-1.0.1.md

@@ -0,0 +1,43 @@
+# FlashData CLI v1.0.1
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs) · [English README](https://github.com/flashdatadev/flashdata-cli#readme) · [简体中文](https://github.com/flashdatadev/flashdata-cli/blob/main/README.zh-CN.md)
+
+## What's new
+
+- Public `flashdata discover plans` and `flashdata discover status` commands are now included in the standalone binaries. They read public API endpoints without an API key or account credentials.
+- English and Chinese workflow selectors and examples cover research, AI context, news, YouTube search, metadata, existing automatic transcripts, uploaded captions and complete MP3/MP4 bulk downloads to customer storage.
+- Clear API coverage and SDK comparisons explain accepted task recovery, partial item failures, export expiry and how to avoid duplicate submissions.
+- Homebrew, signed APT and signed RPM installation and upgrade instructions point to v1.0.1. Existing profiles, credentials and run journals are preserved during package upgrades.
+
+## Install or upgrade
+
+No Go compiler, Python, Node.js or source build is required. See the [English installation guide](https://github.com/flashdatadev/flashdata-cli/blob/v1.0.1/docs/installation.md) or [简体中文安装指南](https://github.com/flashdatadev/flashdata-cli/blob/v1.0.1/docs/installation.zh-CN.md) for first-time repository setup.
+
+| Method | Install | Upgrade an existing installation |
+| --- | --- | --- |
+| Homebrew (Linux/macOS) | `brew install flashdatadev/tap/flashdata` | `brew update && brew upgrade flashdatadev/tap/flashdata` |
+| APT (Ubuntu/Debian) | `sudo apt-get install flashdata` | `sudo apt-get update && sudo apt-get install --only-upgrade flashdata` |
+| RPM (Fedora/RHEL) | `sudo dnf --refresh install flashdata` | `sudo dnf --refresh upgrade flashdata` |
+| Manual archive | Download, verify and extract the matching archive | Replace only the executable; retain the CLI state directory |
+
+APT/RPM commands require the official signed repository to be configured first. Their package version is `1.0.1-1`. Check `flashdata --version` after upgrading; it reports `1.0.1` and the exact tagged source commit. An older copy earlier in PATH can hide a package-manager installation.
+
+## Downloads and verification
+
+| Platform | Archive |
+| --- | --- |
+| Linux amd64 | `flashdata_1.0.1_linux_amd64.tar.gz` |
+| Linux arm64 | `flashdata_1.0.1_linux_arm64.tar.gz` |
+| macOS Intel | `flashdata_1.0.1_darwin_amd64.tar.gz` |
+| macOS Apple Silicon | `flashdata_1.0.1_darwin_arm64.tar.gz` |
+| Windows x64 | `flashdata_1.0.1_windows_amd64.zip` |
+
+Download from the [official release](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.0.1) and verify the selected archive against `SHA256SUMS` before extraction. Archives include the executable, both READMEs, docs, example inputs and dependency licenses from the same source tag. `build-report.json` records the CLI commit, Go toolchain, pinned Go SDK v1.0.0 checksum and archive hashes. Previous v1.0.0 assets and tags remain unchanged.
+
+Source tests and native archive acceptance cover all five platforms using mock APIs, including onboarding, credentials, query/bulk execution and recovery. Homebrew checks install and upgrades on Linux/macOS Intel and ARM64; signed repository checks cover Ubuntu 22.04/24.04, Debian 12/13, Fedora 43/44 and Red Hat UBI 8/9/10 userspace on both CPUs. Full RHEL hosts, FIPS mode, live OS credential services and production API/cloud delivery are separate environment-specific checks. Standalone archives use checksums; macOS binaries are not notarized. APT metadata and RPM packages/metadata use the existing signing certificates.
+
+No PyPI, TestPyPI or npm publication is part of this release. The separately prepared Python wheel candidate remains pinned to v1.0.0 and does not contain the new discovery commands.
+
+## 简体中文
+
+v1.0.1 将无需 API 密钥的 `discover plans`、`discover status` 纳入五个平台的独立安装包，无需源码构建。中英文文档补充工作流选择、手动上传字幕、MP3/MP4 完整批量下载及恢复示例。Homebrew、签名 APT 和 RPM 源提供升级；升级保留用户配置、凭据和执行历史。首次安装请先按安装指南配置软件源，升级后用 `flashdata --version` 确认版本为 1.0.1。独立归档附带准确源码提交、构建记录和 SHA-256 校验和；旧 v1.0.0 文件保持不变。本次不发布 PyPI、TestPyPI 或 npm，独立 Python wheel 候选包仍固定为 v1.0.0。

flashdata_cli/share/docs/release-notes-1.1.0.md

@@ -0,0 +1,44 @@
+# FlashData CLI v1.1.0
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+Choose JSON, plain text or Markdown with independent `--accept` and
+`--respond-with` flags. JSON remains the default.
+
+- Search, YouTube and generic query commands support all four content formats.
+- Async/batch receipts and job status support `--accept text/plain`.
+- Use `jobs result` or async/batch `--wait` for Markdown completed results.
+- Plain text goes directly to stdout; add `--json` for the CLI envelope or
+  `--output FILE` to save the selected body.
+- Saved runs remember format choices. Reformat completed background results
+  without submitting another query. A failed save preserves the previous cache.
+- Redact credentials escaped by Markdown, including older cached responses and
+  file exports, while retaining source links.
+- Pin Go SDK v1.1.0 and preserve accepted IDs, uncertain receipts, access checks
+  and durable recovery.
+
+## Install or upgrade
+
+Download the archive for your platform from the
+[official release](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.1.0).
+Standalone binaries need no Go, Python or Node.js. Keep your existing profiles
+and state directory when replacing the executable.
+
+The [installation guide](installation.md) covers Homebrew, signed APT/RPM,
+manual archives and Windows. Go 1.25+ users can install the source tag:
+
+```bash
+go install github.com/flashdatadev/flashdata-cli/cmd/flashdata@v1.1.0
+```
+
+The release includes Linux amd64/arm64, macOS Intel/Apple Silicon and Windows x64
+archives, matching English/Chinese documentation, a build report and `SHA256SUMS`.
+`flashdata --version` identifies the exact tagged source commit. Existing release
+assets remain unchanged. Bulk exports and media keep their existing formats.
+
+## 简体中文
+
+1.1.0 新增独立的 `--accept` 和 `--respond-with` 参数，默认仍为 JSON。
+实时内容和已完成结果支持 Markdown；后台提交、批量提交及任务状态支持纯文本。
+执行历史保留格式设置，切换已完成后台结果的格式不会重复提交；保存失败时保留旧缓存。
+修复 Markdown 转义后的凭据脱敏，涵盖旧缓存读取和导出。五个平台均提供独立可执行文件。

flashdata_cli/share/docs/release-readiness.md

@@ -0,0 +1,28 @@
+# Initial joint release-readiness review (historical)
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+This records the local review before initial GitHub source publication, not the current distribution state. See [v1.0.1 release notes](release-notes-1.0.1.md) and [current release process](releases.md) for standalone packages, signed repositories and native archive acceptance. Current workflow results are available in [GitHub Actions](https://github.com/flashdatadev/flashdata-cli/actions).
+
+Reviewed together on 2026-10-22 as local 1.0.0 candidates. This check does not publish, tag, push, deploy, register real accounts or submit live paid work. Exact executed counts and platform evidence are in [validation](validation.md).
+
+## Integration fixes
+
+The SDK retains valid recovery IDs even when another response field has the wrong JSON type. The CLI preserves them as `candidateRemoteIds` in both errors and durable uncertain records, with `acceptanceConfirmed:false`. Candidate IDs are evidence for manual `jobs get` or `bulk get` reconciliation; they cannot turn a partial batch into a successful complete submission. Reusing the run ID never replays the submission.
+
+Partial bulk transfers remain partial when exported from saved history. Available receipt files are retained, the command exits nonzero and the error goes to stderr. Per-item failures also return a structured error with export metadata instead of emitting a success envelope. Safe `runs recover` reads can finish an interrupted export. A safe state read during recovery discards spent signed-upload capabilities after an observed start, including when the original start response was lost.
+
+Compiled-process acceptance covers a server-side installation ACK whose response is lost: the candidate and proof survive, a new process verifies them, and the same installation converges without another registration. It also covers a lost bulk start response followed by a new process recovering the original task without another create, upload or start. SDK confirmation responses must have consistent generation metadata.
+
+## Packages and documentation
+
+Each repository has an explicit `release-files.json` allowlist. Package selection rejects traversal, duplicate paths and symlink components, and ignores stray local files. ZIP metadata is deterministic; Unix archive metadata is normalized. Dependency license/notice copies are shipped and linked from the READMEs. CLI build reports retain both runtime source fingerprints and the Go toolchain. The SDK package verifier cross-builds the packaged consumer for all five targets through an isolated local module proxy.
+
+English is the default README with a top-level 简体中文 link. Chinese commands and executable SDK Go programs stay synchronized with English. Documentation distinguishes ID-only SDK examples from the CLI's private upload-capability journal, explains uncertain submissions, and keeps official FlashData links. Source and command reference generation are checked for drift.
+
+## Before a public release
+
+- Deploy the reviewed identity backend patch and verify the production onboarding feature configuration. Complete authorized live claim/handoff, callback and customer-storage checks.
+- Run native Linux/macOS credential-store acceptance and the Linux race check. Windows native protection and subprocess workflows are covered locally; cross-compilation does not establish other native OS behavior.
+- The initial source candidate pinned an SDK pseudo-version. Released CLI versions pin the public SDK v1.0.0 tag and go.sum checksums, with no local replacement or sibling checkout.
+- Review the final source, archives and SHA-256 checksums; sign/notarize platform executables as appropriate to the distribution plan. No signing, remote CI execution or publication is claimed by this check.

flashdata_cli/share/docs/releases.md

@@ -0,0 +1,42 @@
+# Releases, installation and source builds
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+The current release is [v1.1.0](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.1.0).
+It includes JSON, plain-text and Markdown response options, safe cached-result
+reformatting, and credential redaction for Markdown and cached exports. See the
+[release notes](release-notes-1.1.0.md) and [response formats](response-formats.md).
+
+## Install
+
+Standalone archives support Linux amd64/arm64, macOS Intel/Apple Silicon and
+Windows x64, without a separate runtime. The [installation guide](installation.md)
+and [简体中文](installation.zh-CN.md) cover direct downloads, Homebrew, signed APT
+and signed RPM installation and upgrades. Preserve profiles and execution history
+when updating. Existing release files and signed package versions remain immutable.
+
+The CLI pins Go SDK **v1.1.0**, with its recorded Go checksums and no local module
+replacement. Go 1.25+ users can also install
+`github.com/flashdatadev/flashdata-cli/cmd/flashdata@v1.1.0` with `go install`.
+
+## Build and verify
+
+From a clean checkout of the intended tag, run
+`python scripts/build_release.py --go /path/to/go --commit FULL_SOURCE_COMMIT`.
+The script builds five CGo-disabled executables and archives with reviewed docs,
+examples, licenses and a build report. It creates no tag and uploads no files.
+
+The formal release contains the archives, both READMEs, `RELEASE_NOTES.md`,
+`build-report.json` and `SHA256SUMS`. Executable `--version` output and the build
+report record the exact tagged source commit. The report also records the pinned
+SDK, source fingerprints and toolchain. Verify the canonical tag and every asset
+checksum before publishing; keep existing tags and released bytes unchanged.
+
+[GitHub Actions](https://github.com/flashdatadev/flashdata-cli/actions) runs Linux,
+Windows and Intel macOS source checks on Go 1.25/1.27, Linux race checks, source
+and command generation checks, archive-policy tests and all five native archive
+acceptance jobs. Release checks use mock APIs and submit no paid queries.
+
+The separate unpublished Python installer candidate remains pinned to historical
+v1.0.0 binaries. It is not the Python SDK and does not provide v1.1.0 CLI flags.
+Use the standalone distribution for this release. See [wheel preparation](python-packaging.md).

flashdata_cli/share/docs/response-formats.md

@@ -0,0 +1,87 @@
+# JSON, plain text and Markdown
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+Response-format flags are included in v1.1.0 standalone binaries. See the
+[installation guide](installation.md). With Go 1.25+, you can also use
+`go install github.com/flashdatadev/flashdata-cli/cmd/flashdata@v1.1.0`.
+
+`--accept` chooses the API response type. `--respond-with markdown` selects
+Markdown content. They are independent HTTP headers, outside query JSON and params.
+
+| Flags | API response |
+| --- | --- |
+| Neither flag | Original JSON fields |
+| `--accept text/plain` | Original fields as indented text |
+| `--respond-with markdown` | JSON with Markdown in `content`, replacing `results` |
+| `--accept text/plain --respond-with markdown` | Metadata followed by Markdown |
+
+Markdown preserves source links, transcript timestamps and response metadata. The
+API formats retrieved content without generating a summary.
+
+## Search and transcripts
+
+```bash
+flashdata search "vector databases" --accept text/plain
+flashdata search "vector databases" --respond-with markdown
+flashdata youtube transcript dQw4w9WgXcQ --accept text/plain --respond-with markdown
+```
+
+Each realtime command submits a query. For all other sources, use `query --input`
+with the same flags. `--output FILE` saves the selected response body to a new file.
+
+Plain text goes directly to stdout. Add `--json` to keep the CLI's versioned JSON
+envelope, with the text in `data`. For submission receipts, the text is in
+`data.submission`, alongside saved remote IDs and recovery instructions. JSON API
+responses keep the existing CLI envelope. `--output` writes the response body;
+stdout then reports the output path. Credentials and signed URLs are redacted.
+
+## Background jobs and batches
+
+```bash
+flashdata search "vector databases" --mode async --accept text/plain --run-id research
+flashdata batch submit --input examples/batch.json --accept text/plain --run-id research-batch
+flashdata jobs get JOB_ID --accept text/plain
+flashdata jobs wait JOB_ID --accept text/plain
+flashdata jobs result JOB_ID --accept text/plain --respond-with markdown
+```
+
+Submissions return receipts; status reads return status. They support `--accept`.
+Choose Markdown when reading completed results. `--wait` on an async query or
+batch also accepts `--respond-with markdown` for completed results; the submission
+request receives no Markdown header. Batch waiting returns one result per job,
+with job labels separating plain-text results.
+
+The CLI saves accepted job IDs before waiting or writing output. A malformed
+receipt leaves an uncertain run with any candidate IDs available for inspection.
+Neither rerunning that ID nor recovery submits replacement work. Access checks
+and polling use JSON regardless of the selected final response format.
+
+YouTube Download supports text receipts and Markdown result manifests. Media bytes
+keep their original format. Bulk exports remain JSONL; account, discovery and
+onboarding commands keep their existing formats.
+
+## Saved runs and recovery
+
+```bash
+flashdata runs recover research --accept text/plain --respond-with markdown
+flashdata runs show research --result
+```
+
+The run journal remembers the saved response's format. Reusing a run ID without
+format flags returns that saved format after access verification. A different
+explicit format for a completed background job performs safe result reads, without
+another query or query-credit charge. The same applies to `jobs result`.
+If saving a different format fails, the previous saved response remains available.
+Retry recovery after correcting the local storage problem.
+
+A saved realtime response cannot be fetched again in another format. An explicit
+format change returns `run_response_format_conflict` without repeating the query.
+Use `runs show RUN_ID --result` to read the existing response. To clear a saved
+Markdown choice for a background result, pass `--respond-with ""`.
+
+The CLI accepts `application/json` and `text/plain` for `--accept`, and `markdown`
+or an empty `--respond-with`. Invalid choices fail before API calls. Errors go to
+stderr with a nonzero exit status; `--json` keeps structured CLI errors.
+See the [API response-format guide](https://flashdata.dev/docs/guides/response-formats)
+for HTTP requests and response bodies.

flashdata_cli/share/docs/review.md

@@ -0,0 +1,41 @@
+# Local CLI review
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+This records the local review before initial GitHub source publication. Current workflow results are available in [GitHub Actions](https://github.com/flashdatadev/flashdata-cli/actions). Source publication does not create version tags, GitHub Releases or backend deployments.
+
+Reviewed against the supplied CLI spec, the checked-out backend implementation and the sibling Go SDK. No live credentials or production mutations were used. The final joint review also updates the sibling Go SDK; the existing backend identity patch remains undeployed.
+
+## Response-format review
+
+Current source adds independent response headers while retaining JSON defaults,
+saved job IDs and the CLI output envelope. API-generated fixtures cover all 14
+realtime sources and 15 stored-result sources, text receipts, status, waiting and
+recovery. Review fixes redact signed URLs inside both Markdown response types,
+sanitize usage metadata and retain every candidate ID from malformed receipts.
+Format changes never repeat a paid query. See [response formats](response-formats.md).
+
+## Initial publication review
+
+| Area | Gap fixed |
+| --- | --- |
+| Environment overrides | Bulk recovery writes preserve the original saved credentials, proofs and phase instead of replacing them with an environment-only profile. |
+| Key import | Importing the same saved key verifies and reuses it without deleting onboarding/upload recovery data; explicit replacement remains available. |
+| Onboarding | Pending registration status gives a recovery command without creating access; whitespace in a repeated scope flag does not change the saved request. Verified connection fallback retains connection/expiry metadata. |
+| Source discovery | Secret redaction no longer corrupts public credential-property schemas. Restricted keys can inspect public schemas while pricing/permission status remains scoped. |
+| Batch access | One current access/identity check covers every distinct source, avoiding per-item reads against the management API rate limit. Dry-runs return available estimates by source and request count. |
+| Submission recovery | Failed commits after accepted batches return remote IDs in structured errors. No replacement submission is made. |
+| Recurring policy | Newly created recurring records retain their owner/installation requirement through flag omission, result reads and recovery. |
+| Journal integrity | Large batch records can be read back; history lists omit full payloads. Orphaned results block replay when a journal record is missing. |
+| Bulk recovery | Controls refresh local stages and remove spent upload capabilities. Uploads use a private snapshot matching the validated hash and byte count even if the original file changes. |
+| Private input/output | Generic query/batch files containing credentials or callbacks require private permissions. Windows output files receive a private ACL at creation. Callback metadata and accidental argument errors do not echo secret values. |
+| Bulk JSON/flags | Create/update field names are case sensitive; update accepts stdin. Realtime --wait, ignored job-output flags and runs --output without --result are rejected. |
+| Migration | A single source snapshot is hashed and decoded. Interrupted imports are source-bound and cannot replace unrelated history. Completed import retries preserve the current profile, including a later logout. |
+| Linux credential store | Explicit existing local Unix D-Bus endpoints only; no session-bus autolaunch or remote plaintext Secret Service transport. |
+| Documentation | Matching English/Chinese commands, runnable manual bulk JSON inputs, PowerShell stdin examples and accurate state-specific control guidance. |
+
+The optional check_backend_contracts.cjs development check compares all 15 SDK source definitions against the actual backend catalog, verifies the backend's filters:null compatibility, and exercises registration plus all five bulk-source option validators. It starts no server, database or cloud client. Default Go tests additionally submit every source-discovery example through the shared command path against a loopback API and exercise recovery/security failures.
+
+See the [joint release-readiness check](release-readiness.md) for retained candidate IDs, partial-export errors, lost-response acceptance and deterministic allowlisted packages.
+
+See [validation evidence](validation.md) for exact executed results. Native Linux/macOS credential-store checks, the race detector, production feature availability and backend deployment are not established by this Windows review. That local review preceded source publication; the CLI now uses an immutable public SDK dependency without a sibling replacement. No version tag or GitHub Release is created by the source push.

flashdata_cli/share/docs/runs.md

@@ -0,0 +1,47 @@
+# Durable runs and duplicate protection
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+A run belongs to one profile, account/credential identity and pair of service origins. Files use SHA-256-derived names rather than caller-provided paths. Run IDs allow 1–160 letters/digits plus dot, underscore, colon, at, plus and hyphen; the first character must be a letter/digit. Normalize the query before hashing: flat and nested parameters have the same wire form, object key order does not matter, and conflicting/duplicate fields are rejected. Source and mode are part of execution intent. Output path, waiting and recurring flags do not create a second execution identity.
+
+Before any paid mutation, a private, synced and atomically replaced intent record exists. Its request metadata is sanitized; cloud credentials stay in private configuration/vaults. Same ID/different input or account/origin conflicts. Same successful run returns its saved result after live access/source checks. A missing/corrupt result is an error, not permission to submit again. Credentials revoked since the first execution stop cached reads.
+
+New recurring records also retain their owner/installation requirement. Omitting --recurring on a later invocation or using runs show/recover cannot weaken that saved policy. An orphaned result whose journal record is missing blocks another submission with the same ID. Journal records have a 64 MiB serialized limit, checked before writing; this accommodates the CLI's 8 MiB batch input limit and JSON escaping. runs list returns metadata without full query inputs or acceptance receipts; runs show inspects an individual complete record.
+
+| Local status | Meaning and recovery |
+| --- | --- |
+| intent | Process may have crashed before or after dispatch. No automatic replay. |
+| uncertain | Response was lost; inspect account/server records before an intentional new execution. |
+| failed | A known rejection/local failure occurred; the ID is retained and is not automatically retried. |
+| accepted | Known job/bulk ID is durable. `runs recover` reads existing remote work. |
+| partial | A bulk result stream stopped; partial JSONL is kept and safe reads may be repeated. |
+| succeeded | Result hash and file were committed; verify current access before cache/export. |
+
+Realtime uncertain requests have no server receipt lookup in the current API. There is deliberately no force-retry switch that silently converts uncertain history into new paid work. One-off commands generate an ID; repeating without it is a new execution.
+
+Async/batch acceptance receipts retain remote IDs and usage. Recovery waits/fetches using those IDs only. Batch aggregation is bounded to 128 MiB; use individual `jobs result --output` for larger results. Bulk rows stream to a separate private file with a running checksum; partially completed exports are retained before an error is reported. Cache/export verifies the stored checksum. Failed/invalid item receipts cause nonzero exit after they have been saved.
+
+Batch access metadata is verified once per command and checked against every distinct source, avoiding per-item identity reads. Batch dry-runs include available source-specific estimates. If an accepted batch cannot be committed locally, its remote IDs are returned in error.details.remoteIds for explicit recovery. Bulk get/start/control refreshes local stages and removes spent upload capabilities after the job leaves awaiting_upload.
+
+The profile's kernel lock covers command mutation, including network submission and final state commit. Concurrent writers wait only within the command deadline. The lock file is not removed; Windows LockFileEx and POSIX flock release when the process exits/crashes. This avoids unsafe stale-lock unlink/reclaim races. A fresh installation child only reads the atomically committed candidate, without acquiring the writer lock.
+
+Run history has no automatic expiry or eviction. Profiles retain history on logout. Large results are separate from the credential vault. The host owns cron, Task Scheduler, Codex or other recurring invocation; the CLI writes no scheduler configuration and stores no key in scheduler text. This is local duplicate protection, not cross-machine exactly-once execution.
+
+Changing a saved response format retains earlier response versions. If saving fails
+or is interrupted, the last committed response remains available for reading and
+recovery.
+
+## Response formats
+
+The journal retains the selected response format. Cached results reuse that format
+when no flags are supplied. A different explicit format never causes another paid
+query: realtime cache changes fail with `run_response_format_conflict`; completed
+background results can be read again using `runs recover --accept ... --respond-with ...`.
+Plain-text receipts still retain confirmed job IDs, and malformed receipts retain
+candidate IDs on an uncertain run. See [response formats](response-formats.md).
+
+## Candidate IDs and partial exports
+
+Malformed responses can leave `candidateRemoteIds` on an uncertain record. These IDs do not populate the confirmed `remoteId`/`remoteIds` fields. Inspect each candidate with the original account and reconcile the entire request; repeating the run or `runs recover` does not promote candidate evidence or resubmit work.
+
+A saved partial NDJSON export always returns a `partial_result` error, even if every row received so far completed. Available rows can still be written to a new output file. Per-item failure exports return `bulk_item_failures`; failure metadata goes to stderr with no success envelope on stdout.

flashdata_cli/share/docs/sdk-parity.md

@@ -0,0 +1,126 @@
+# FlashData SDK and CLI comparison
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+Python, TypeScript, JavaScript and Go are the language entry points. TypeScript and
+JavaScript share one npm package and implementation. The standalone CLI uses the Go SDK.
+This comparison describes the current source on `main`; it is not a claim that every
+source change is included in previously published v1.0.0 archives.
+
+## Choose an integration
+
+| Concern | Python | TypeScript | JavaScript | Go | CLI |
+| --- | --- | --- | --- | --- | --- |
+| Best fit | Python applications, notebooks, data pipelines | Typed Node.js services and agents | Node.js scripts and integrations | Go services and workers | Terminal research, scripts and agents |
+| Runtime | Python 3.10+ | Node.js 22+; compiler for your application | Node.js 22+ | Go 1.25+ | Standalone Linux/macOS amd64/arm64 or Windows amd64 binary |
+| Client/key | `FlashData(api_key=...)` or `AsyncFlashData(api_key=...)` | `new FlashData({apiKey: ...})` | Same constructor | `flashdata.New(Options{APIKey: ...})` | `flashdata auth login`; hidden prompt or stdin |
+| Async model | Sync and asyncio clients | Promises and async iterators | Same | `context.Context`, goroutines and iterators | Background jobs, batch and bulk commands |
+| Time units | Seconds | Milliseconds | Milliseconds | `time.Duration` | Duration flags such as `--timeout 1h` |
+| Local credentials/history | Application-owned | Application-owned | Application-owned | Application-owned | Protected profiles, vault and persistent run journal |
+
+SDK examples pass the API key explicitly. Applications can read a key from the environment
+or a secret manager. The CLI can also use an explicit `FLASHDATA_API_KEY` override. No
+project automatically loads `.env` files. Run the Node.js SDK on your server.
+
+## Core API coverage
+
+| Capability | Python | TypeScript | JavaScript | Go | CLI |
+| --- | --- | --- | --- | --- | --- |
+| Core developer REST operations | 24 | 24 | Same package | Same 24 | Same 24 in CLI v1.0.1; v1.0.0 binaries omit public plans/status reads |
+| Source schemas | 15 | Identical 15 | Same | Identical 15 | Same schemas through Go SDK v1.0.0 |
+| Realtime / background / batch sources | 14 / 15 / 15 | Same | Same | Same | Same via `query`, `--mode async`, `batch submit` |
+| Google sources | Search, images, news, shopping, videos, places | Same six | Same | Same six | `search` shortcut; all six via `query` |
+| YouTube sources | Search, extended search, metadata, transcript, captions, license labels, channel, suggestions, download | Same nine | Same | Same nine | Dedicated shortcuts plus `query` for all nine |
+| Standard jobs | Get, wait, result | Same | Same | Same | `jobs get`, `jobs wait`, `jobs result` |
+| JSON, plain text and Markdown responses | Per-call `accept` / `respond_with` | Per-call `accept` / `respondWith` | Same | `WithFormat` methods | `--accept` / `--respond-with`; `--json` selects the CLI envelope |
+| Bulk sources | Metadata, transcript, captions, license labels, download | Same five | Same | Same | Same five via `bulk run` or manual commands |
+| Bulk operations | Create, upload file, start, get/list, update, pause/resume/cancel, wait, manifest/parts/rows | Same | Same | Same plus reader-based upload | Manual lifecycle commands and streamed `bulk results` |
+| Account reads | Access, balance, pricing, limits, usage | Same five | Same | Same plus verified identity | Auth/access checks, account reads and verified identity |
+| Public discovery | Sources, plans, health, status | Same four | Same | Same four | `sources list`, `discover`, `discover plans`, `discover status` |
+
+`discover plans` and `discover status` were added after the CLI v1.0.0 binary release.
+Install or upgrade to CLI v1.0.1 to use those commands without building from source. This
+distinction does not affect the existing search, YouTube, batch or bulk commands.
+
+The 15 sources are six `google_*` sources and nine `youtube_*` sources. Media downloads
+are background-only and require customer cloud storage. Other sources can run in realtime.
+No SDK or CLI invents a list/cancel endpoint for standard background jobs; those controls
+are available for bulk jobs only.
+
+Go and the CLI additionally implement agent onboarding and verified ownership reads.
+Python and the Node.js package do not expose that optional protocol. These are separate
+from the shared developer APIs; availability depends on the service deployment. The
+additional Go contract also documents browser-owned operations that are not SDK methods.
+
+## README and example coverage
+
+All four repositories keep English as the default README, with a Simplified Chinese link
+at the top. Both languages include the same eight workflow choices: web context, news,
+video discovery, metadata, transcripts, bulk datasets, media delivery and bulk recovery.
+
+All have copyable first-search examples, explicit key setup, manual-caption examples,
+background/batch guidance, bulk metadata exports and complete customer-storage download
+workflows. Each source has a runnable program in the SDK repositories; the CLI uses
+dedicated shortcuts or the source JSON returned by `sources show SOURCE`.
+
+The Python/Node.js media scripts default to MP4 and offer `--audio` for MP3. The Go bulk
+example defaults to MP3 and accepts `-options video-options.json` for MP4. The CLI has
+complete MP3 and MP4 bulk commands; its single-video `youtube download` shortcut is
+audio-oriented, while `query --mode async` exposes the complete download source input.
+Different defaults are examples, not differences in the media formats supported by APIs.
+
+README transcript snippets explicitly request an existing automatic English track;
+caption snippets request an existing uploaded track. Runnable track scripts document
+their manual/automatic selection flags and defaults. Availability depends on the video. The
+service does not generate missing transcripts, translate captions, summarize text or
+create embeddings. Those application steps use the data returned by FlashData.
+
+## Bulk lifecycle and recovery
+
+| Step | SDK runnable examples | CLI |
+| --- | --- | --- |
+| Prepare | A UTF-8 file with one 11-character video ID per line | Same; private storage/options files for credentials |
+| Create | Reserve fresh export/recovery paths before creating work | Commit a run ID and intent in the journal |
+| Save acceptance | Sync the accepted ID/job before upload; never save signed upload URLs in ordinary records | Save job ID and signed upload capability in the protected vault/journal |
+| Execute | Create → upload → start → wait → stream JSONL | `bulk run` performs the same lifecycle |
+| Export | Stream results and preserve partial rows; check row statuses and final counts | Stream results, preserve failed rows and exit nonzero for failures |
+| Repeat | Existing export or recovery record blocks creation | Same run ID prevents duplicate creation; changed input conflicts |
+| Recover | Explicit accepted ID and a fresh output path; no create/upload/resume | `runs recover RUN_ID` reads accepted work; no implicit replay |
+| Pre-upload interruption | ID-only records cannot restore a lost signed upload; application needs a secure store | Original capability is kept privately; explicit upload/start recovery is available while valid |
+
+The README's inline API examples explain the lifecycle. Use the repository's runnable
+bulk program as the starting point for file preflight, saved IDs, failure exits and recovery.
+An empty reserved recovery file after an uncertain create is not permission to create again:
+reconcile the account/server outcome first. None of the SDKs automatically retries paid
+queries or mutations. Local cancellation or a polling timeout does not cancel accepted work.
+
+`.jsonl` and `.ndjson` both mean one JSON object per line. Media bytes go to the configured
+customer bucket; local files contain per-item data or delivery receipts. A completed task
+can contain failed/invalid items. Export before internal results expire (24 hours after
+completion); signed input uploads expire after 15 minutes. Input files support 1 byte to
+2 GiB. Cloud credential validation and delivery permissions remain server responsibilities.
+
+Go and the CLI additionally validate/snapshot IDs before upload. The CLI owns OS credential
+storage and durable execution history; SDK applications own their persistence. These are
+intentional implementation differences, not cross-machine exactly-once guarantees.
+
+## Validation
+
+The comparison checks parsed source schemas and source contracts across all SDKs, the
+24 core OpenAPI operations, sync/async resource parity, and the local backend catalog and
+bulk option validators. The Go snapshot adds 14 identity/onboarding contract operations;
+five are browser-owned. Core source/API coverage does not depend on those additions.
+
+Tests execute README code and runnable examples using local mock transports, verify
+no accidental resubmission after an interrupted bulk start, preserve orphaned recovery
+records and inspect exported item statuses. Documentation checks cover translations,
+explicit key examples, official website links, relative links and workflow anchors.
+Package checks exercise clean consumers; GitHub Actions checks the supported runtimes.
+These checks do not perform paid API queries or customer-cloud writes.
+
+| Repository | README | Examples | API / commands | Bulk recovery |
+| --- | --- | --- | --- | --- |
+| Python | [README](https://github.com/flashdatadev/flashdata-python#readme) | [Examples](https://github.com/flashdatadev/flashdata-python/tree/main/examples) | [API](https://github.com/flashdatadev/flashdata-python/blob/main/docs/api-reference.md) | [Bulk](https://github.com/flashdatadev/flashdata-python/blob/main/docs/bulk.md) |
+| TypeScript / JavaScript | [README](https://github.com/flashdatadev/flashdata-typescript#readme) | [Examples](https://github.com/flashdatadev/flashdata-typescript/tree/main/examples) | [API](https://github.com/flashdatadev/flashdata-typescript/blob/main/docs/api-reference.md) | [Bulk](https://github.com/flashdatadev/flashdata-typescript/blob/main/docs/bulk.md) |
+| Go | [README](https://github.com/flashdatadev/flashdata-go#readme) | [Examples](https://github.com/flashdatadev/flashdata-go/tree/main/examples) | [API](https://github.com/flashdatadev/flashdata-go/blob/main/docs/api-reference.md) | [Bulk](https://github.com/flashdatadev/flashdata-go/blob/main/docs/bulk.md) |
+| CLI | [README](https://github.com/flashdatadev/flashdata-cli#readme) | [Inputs](https://github.com/flashdatadev/flashdata-cli/tree/main/examples) | [Commands](https://github.com/flashdatadev/flashdata-cli/blob/main/docs/commands.md) | [Bulk](https://github.com/flashdatadev/flashdata-cli/blob/main/docs/bulk.md) |

flashdata_cli/share/docs/security.md

@@ -0,0 +1,29 @@
+# Credential and storage model
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+| Platform | Automatic OS protection | Headless fallback |
+| --- | --- | --- |
+| Windows amd64 | Native current-user DPAPI, private owner/SYSTEM DACLs | DPAPI requires the same user profile; explicit file mode is available |
+| macOS amd64/arm64 | Native Security.framework Keychain key with UI disabled, AES-256-GCM vault | Use an unlocked accessible keychain or explicitly choose private file mode |
+| Linux amd64/arm64 | Unlocked Secret Service over session D-Bus, AES-256-GCM vault; never calls Unlock/Prompt | New profiles automatically use private files when no session bus is configured; explicit file mode is available |
+
+OS failures never silently downgrade an existing store. macOS uses pure-Go native bindings without CGo or a `security` subprocess; Windows uses native DPAPI calls without PowerShell. Secrets do not enter subprocess arguments or shell commands. Linux keyring calls do not ask for GUI unlock. The master key is distinct from the API key and bound to the canonical state-root/profile identity; copying an OS-protected vault to another user/location may require explicit migration/key import.
+
+`--credential-store file` is a documented protected plaintext mode: JSON is base64-encoded inside a versioned envelope, not encrypted. Use persistent storage owned by the scheduled account. Unix requires private directories (0700), private regular files (0600) and current-user ownership; symlink state paths are refused. Windows checks ACLs/ownership and writes private output ACLs. State writes use a synced temporary file, atomic replacement and directory synchronization where supported. Existing unsafe/corrupt state is never reset.
+
+Defaults live outside repositories: Windows/macOS use the OS user configuration directory under FlashData; Linux uses an absolute XDG_STATE_HOME/flashdata or ~/.local/state/flashdata. Each lowercase profile has an independent vault, lock, run journal and results directory. `--state-dir` is an explicit persistent-location override; keep it out of project repositories. Do not delete state to repair authentication or uncertainty.
+
+The same OS user, administrators/root, a compromised process or a malicious custom SDK transport are outside this local secrecy boundary. OS encryption protects copied credential blobs; it is not an isolation boundary against the logged-in user. Successful provider data may itself be sensitive. Store exported results appropriately.
+
+API keys, registration/setup/handoff proofs, cloud access/secret/private keys and signed capabilities are redacted from CLI diagnostics and sanitized metadata. Provider URLs and large numbers are otherwise retained. Successful data is never evaluated as shell commands, prompts or code. SDK requests pin service origins and authenticated signed-storage origins, isolate keys/cookies from storage, and never retry paid submissions automatically.
+
+Customer-storage config and option files must be private and outside source control. Unix: `chmod 600 /private/flashdata/storage.json`. On Windows use a directory accessible only to the scheduled user/SYSTEM, or set the file DACL explicitly using your organization's approved ACL tooling. The example storage file contains only placeholders and must not be used unchanged.
+
+Generic query/batch JSON files containing credential fields or callback URLs require the same private permissions; stdin is supported when a secret manager supplies the payload. Callback destinations are omitted from sanitized metadata because webhook URLs can contain secrets. Public credential-property schema definitions remain intact; they contain no secret values. Discovery also describes strict top-level fields and the optional background callback field enforced by SDK runtime validation. Windows exported files receive their private security descriptor at creation time, before any result bytes are written.
+
+An environment override changes only the current command's access. Saving upload/recovery updates preserves the profile's original key, proofs and phase; a new environment-only profile saves recovery metadata without persisting that environment key. Re-importing the same saved key is a verified reuse operation. Linux accepts an already configured local Unix D-Bus endpoint, never auto-launches a session bus, and refuses remote/autolaunch transports for Secret Service.
+
+An explicit auth login into an environment-only profile persists the chosen verified key while retaining accepted-job recovery capabilities; it does not require a destructive replacement. Existing run/account bindings still control which records that key can use.
+
+`auth logout` clears API keys, proofs and saved upload capabilities while retaining history. It reports that remote access is not revoked and whether an environment key remains set. Remove environment variables separately and revoke remote keys in your FlashData account when desired. `auth login --replace` explicitly replaces prior onboarding/upload capabilities; prefer a new profile if old work still needs those capabilities.