@blinkhost/cli 2.4.0 → 2.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,183 @@
2
2
 
3
3
  This file records customer-visible CLI changes. BlinkHost uses semantic versioning for the CLI, while security and migration impact are classified separately. A patch may therefore require prompt action, and a major release may coexist with an earlier supported line during its documented migration window.
4
4
 
5
+ ## 2.5.1 — Saved-session concurrency
6
+
7
+ Commands sharing a saved profile now serialize credential refresh and sign-out.
8
+ This prevents concurrent CLI processes from reusing a rotated refresh credential
9
+ and revoking the session. Sign-in verifies the new session using its original
10
+ access token, and temporary refresh errors preserve the saved credential.
11
+
12
+ If a command exits unexpectedly while holding the sign-in lock, the CLI reports
13
+ the lock path. Confirm that no command for that profile is running before
14
+ removing that file. Idam remains limited preview; workspace policy is unchanged.
15
+
16
+ ## 2.5.0 — Idam limited preview
17
+
18
+ This release adds Idam commands for eligible accounts on an enabled control plane.
19
+ Idam remains a limited preview. Workspace permissions, feature availability and
20
+ spending limits are checked by the server. Installing the CLI does not enable
21
+ Idam or change a subscription. Node.js 22.12 or newer is required; no project
22
+ migration is needed from 2.4.0.
23
+
24
+ - Connected-review plans default to GPT-6 Luna and accept GPT-6 Luna and Sol
25
+ alongside GPT-5.6 Terra. Existing GPT-5.6 plan selections remain readable and
26
+ editable. Plan confirmation, approval and credit limits are unchanged.
27
+
28
+ - Windows sign-in allows up to 15 seconds for the read-only credential-tool
29
+ startup check. A timeout still stops sign-in safely; credential operations
30
+ retain their 30-second limit, with no automatic retry or plaintext fallback.
31
+
32
+ - Added named code review: list eligible reviewers, explicitly share
33
+ selected changes, inspect the shared review, approve or request changes, and
34
+ withdraw sharing. Decisions are bound to the reviewed version and current
35
+ access; they never save, build or publish. Conversations stay private.
36
+ Sharing is optional, but withdrawing a review does not bypass independent
37
+ approval required by a workspace for Idam source saves. This policy does not
38
+ cover starter creation, builds or deployments.
39
+ Reviewer options validate the server's explicit review-required flag; a missing
40
+ or malformed flag is not treated as permission to skip review.
41
+
42
+ - Windows sign-in no longer removes a saved credential before writing its
43
+ replacement. Vault failures stop the operation without retrying or displaying
44
+ private diagnostics; refresh credentials remain confined to an input pipe.
45
+
46
+ - macOS credential writes now send refresh tokens through a private input pipe,
47
+ not process arguments. A bounded single-command input rejects control
48
+ characters and preserves write failures; no temporary credential file or
49
+ automatic write retry is used.
50
+
51
+ - Added sign-in recovery guidance for globally revoked sessions and server-side
52
+ security updates. When a fresh sign-in is required, use the same profile and
53
+ explicitly request the permissions you need; an old approval link cannot
54
+ reconnect your device. This does not migrate project files or change billing.
55
+
56
+ - Bounded operating-system credential helpers and removed raw helper diagnostics
57
+ from errors. Linux keyring failures are no longer treated as missing credentials;
58
+ Windows missing-item handling distinguishes other vault errors. Sign-in guidance
59
+ explains recovery after browser approval without retrying an uncertain write.
60
+ Added a separate hosted-CI native-vault check for Linux, macOS and Windows
61
+ using only temporary synthetic credentials; ordinary local tests do not
62
+ modify the user's keyring. Linux and macOS checks also exercise a locked
63
+ synthetic keyring, bounded errors and recovery without losing saved credentials.
64
+ Windows checks cover normal vault operations, not a simulated desktop lock.
65
+ Linux also checks for retained locked credentials before reporting a missing
66
+ credential or successful removal when the keyring silently refuses to unlock.
67
+
68
+ - Added `projects export PROJECT_UUID --source-only --output ./source.zip` for
69
+ backend-only projects and unchanged source downloads. No build configuration,
70
+ README, schema or lockfile is generated or validated. The server must confirm
71
+ the requested mode. Access checks, credential screening and download limits
72
+ remain in effect; default portable exports are unchanged.
73
+
74
+ - Added safe, actionable source-export guidance for unsupported frontend
75
+ configurations, HTML package/lockfile issues and credential-screening blocks.
76
+ Error bodies are bounded and never printed; unknown failures retain their HTTP
77
+ status and request ID. Offline help explains portable and source-only exports.
78
+
79
+ - Fixed source exports returning HTTP 406 during API content negotiation.
80
+ Successful downloads still require a complete ZIP archive; JSON responses
81
+ cannot be saved as source exports.
82
+
83
+ - Fixed upload requests combining the default JSON content type with an explicit
84
+ multipart or binary content type, which could cause HTTP 415 errors. Custom
85
+ headers now replace defaults regardless of capitalization. Failed uploads are
86
+ still not retried automatically.
87
+
88
+ - Sign-in now explains expired codes and how to request a new one. Authorization
89
+ polling backs off when requested by the server and stops at expiry; uncertain
90
+ token-delivery or network failures are not retried automatically. Sign-in
91
+ addresses are validated before display or browser launch, and malformed token
92
+ responses cannot overwrite a saved credential.
93
+
94
+ - Corrected offline workflow help: approving a plan requires `ai:approve`,
95
+ separate from `ai:execute` for drafting, revising and stopping it.
96
+
97
+ - Added `projects export PROJECT_UUID --output ./project.zip` for source ZIPs,
98
+ distinct from Idam task exports. Existing authorization and secret screening
99
+ apply. Bounded downloads refuse redirects and overwrites; nothing is extracted
100
+ or executed. Database rows, runtime secrets and running deployments are excluded.
101
+
102
+ - Added backend starter choices, file review, explicit save approval and read-only
103
+ receipt recovery. Normal permissions, source revisions and module limits apply.
104
+ No builds, publication or AI charges; uncertain saves are never auto-retried.
105
+
106
+ - Added saved-module build choices, review, explicit approval and read-only status.
107
+ Normal compiler rollout, plan capacity and build metering remain authoritative;
108
+ no AI credits are used. Approval never publishes. CLI scope, exact digest and
109
+ review confirmation are required; uncertain responses are never auto-retried.
110
+
111
+ - Added explicitly confirmed `ai resume` for eligible multi-step checkpoints.
112
+ It preserves active work, retry delays, original spending limits and receipts;
113
+ it cannot restart stopped tasks or approve changes. Requires `ai:execute`.
114
+ Ambiguous responses are not retried automatically; inspect task status.
115
+
116
+ - Added `ai sources --project PROJECT_UUID` and bounded `research_source_ids`
117
+ selection for research requests. Reviewed excerpts are inspectable in task
118
+ details and exports, with attribution and citation status. This is not live
119
+ web search; sources are checked before admission and dispatch and count toward
120
+ the existing credit estimate. The separate source gate remains off by default.
121
+
122
+ - Extended declaration review to bounded `requirements.txt` files. Python server
123
+ frameworks and selected native packages receive qualified guidance, not a
124
+ promise of runtime support. Includes, URLs and pip options are not followed;
125
+ environment markers and extras are not evaluated. No code runs or changes.
126
+
127
+ - Extended the same bounded review to static `pyproject.toml` dependencies,
128
+ optional dependencies and build-system requirements, with separate fixed
129
+ labels. Dynamic/tool-specific declarations stay unknown. No build hooks run,
130
+ optional-group names are not disclosed, and older rule responses remain valid.
131
+
132
+ - Task exports identify the reviewed file selection separately from the full
133
+ proposal. An applied timestamp records a save, not a successful build or the
134
+ current contents of files. Review contents and approval tokens stay excluded.
135
+
136
+ - Made invisible direction and terminal controls visible in source review diffs.
137
+ Approval hashes still bind the original source. Structured CLI output uses
138
+ JSON escapes that preserve decoded values, including filenames and source.
139
+
140
+ - Added `ai compatibility --project PROJECT_UUID`: a read-only, revision-bound
141
+ declaration review with explicit inspection limits and no runtime certification.
142
+ Requires `ai:read`; no uploads, model calls, credit reservations or source edits.
143
+
144
+ - Added optional personal project guidance with `ai memory-show`, `memory-save`
145
+ and `memory-clear`. Saving uses an explicitly selected, bounded UTF-8 file,
146
+ reviewed version and project confirmation. Changes stop queued work using
147
+ older guidance; clearing does not erase existing task records or backups.
148
+ - Workload identities are refused across the personal Idam preview, so automated
149
+ jobs cannot inherit the creator's guidance, history or source approvals.
150
+
151
+ - Added `ai workflow-plan`, `workflow-revise`, `workflow-approve`, `workflow-status`
152
+ and `workflow-cancel` for bounded investigation-and-review drafts. Saving and
153
+ editing do not start follow-ups. Approval binds the inspected revision and
154
+ digest with exact workflow confirmation. `workflow-start` is a draft-only
155
+ compatibility alias. Saved version history remains available on each task.
156
+ Separately gated; plan approval does not authorize tools, tests, source writes
157
+ or deployments.
158
+
159
+ - Added `ai rollback-review` and `ai rollback-approve` for an explicitly reviewed,
160
+ source-only undo. Later file edits are protected; unchanged new files are removed
161
+ only when no active co-editing session references them. Original history and
162
+ charges remain unchanged. This is not deployment rollback or project recovery.
163
+
164
+ - `ai export` now retrieves a versioned, private task snapshot with credit totals,
165
+ removal status and explicit history limits. Proposed source is opt-in with
166
+ `--include-source`; internal context, approval tokens and input files are excluded.
167
+
168
+ - Optional, explicitly selected workspace source files for a task, with credential
169
+ screening and byte limits before funding. No implicit local-file upload.
170
+
171
+ - Added `ai start`, `list`, `status`, `events`, `export`, `review`, `approve` and `cancel`.
172
+ - Start requests use a bounded JSON file with a stable request ID and explicit budget.
173
+ - Source approval requires the reviewed action digest and exact task confirmation;
174
+ saving does not build, test, publish, purchase resources or create a Git commit.
175
+ - Added repeated `auth login --scope` for explicit AI permissions. Existing sessions,
176
+ default sign-ins and workload identities do not receive AI permissions automatically.
177
+ - Included offline `docs ai` with scope, privacy, retry and verification limits.
178
+
179
+ These commands require the matching control-plane integration and current project
180
+ access. They were not included in 2.4.0. No automatic update is performed.
181
+
5
182
  ## 2.4.0 — 2026-09-02
6
183
 
7
184
  ### Added
package/README.md CHANGED
@@ -7,7 +7,7 @@ The BlinkHost CLI brings project setup, local development, source control, previ
7
7
  Node.js 22.12 or newer is required.
8
8
 
9
9
  ```bash
10
- npm install --global @blinkhost/cli@2.4.0
10
+ npm install --global @blinkhost/cli@2.5.0
11
11
  blinkhost --version
12
12
  ```
13
13
 
@@ -15,16 +15,204 @@ Signed release archives, checksums, the CycloneDX SBOM, and Sigstore verificatio
15
15
 
16
16
  ## Current release
17
17
 
18
- ### 2.4.0 — release intelligence and compatibility guidance
18
+ ### 2.5.1 — saved-session concurrency
19
19
 
20
- - Added `blinkhost update notes [VERSION]` for terminal-accessible, verified release history.
21
- - Added cached, time-bounded update awareness that stays silent in CI, structured output, and non-interactive sessions.
22
- - CLI token refresh now records the installed client version so project compatibility guidance does not rely on a stale login record.
20
+ Commands sharing a saved profile serialize credential refresh and sign-out so
21
+ concurrent processes do not reuse a rotated credential. Temporary refresh
22
+ failures preserve the saved credential; rejected sessions still require a fresh
23
+ sign-in. Explicit environment credentials remain the caller's responsibility.
24
+ If a command reports `credential_busy`, let the other command finish. After a
25
+ crash, confirm that no command for that profile is running before removing the
26
+ reported lock file. The file contains process metadata, never credentials.
27
+
28
+ ### 2.5.0 — Idam limited preview
29
+
30
+ - Added Idam task, source-review, starter, build, export and connected-review commands.
31
+ - Connected-review plans default to GPT-6 Luna and support GPT-6 Sol and GPT-5.6 Terra; older GPT-5.6 plans remain readable.
32
+ - Improved scoped sign-in and operating-system credential handling on Linux, macOS and Windows.
33
+
34
+ Idam remains a limited preview. Access depends on the server rollout, current
35
+ project permissions and available credits. Installing this CLI does not enable
36
+ Idam or change a subscription. No project migration is required from 2.4.0.
23
37
 
24
38
  Run `blinkhost update notes` to read published notes in the terminal. The complete version history and compatibility policy are maintained in [CHANGELOG.md](./CHANGELOG.md) and the [developer release notes](https://app.blinkhost.me/docs/releases).
25
39
 
26
40
  ## Start safely
27
41
 
42
+ ### Idam limited preview
43
+
44
+ Request a review of selected code with
45
+ `ai peer-options TASK_UUID --project PROJECT_UUID`, then
46
+ `ai peer-invite TASK_UUID --project PROJECT_UUID --reviewer USER_ID --digest ACTION_DIGEST --confirm TASK_UUID`.
47
+ Prepare and inspect `ai review` first. Only the selected before-and-after code
48
+ is shared with the named owner or administrator; conversations and other
49
+ proposed files remain private. The reviewer uses `ai peer-inbox --project PROJECT_UUID`,
50
+ `ai peer-review PEER_UUID --project PROJECT_UUID`, then
51
+ `ai peer-approve PEER_UUID --project PROJECT_UUID --digest REVIEW_DIGEST --confirm PEER_UUID`
52
+ or `peer-decline` with the same options. Read commands need `ai:read`; sharing
53
+ and decisions need `ai:approve`. Decisions never save, build or publish.
54
+ The requester saves separately after approval, or explicitly withdraws with
55
+ `ai peer-withdraw TASK_UUID --project PROJECT_UUID --peer PEER_UUID --confirm TASK_UUID`.
56
+ Sharing is optional, but your workspace may require independent approval before
57
+ Idam source saves. Withdrawal ends sharing and preserves history; it does not
58
+ bypass workspace-required review.
59
+ Reviews expire after at most 15 minutes and changes to source or permissions
60
+ require fresh review. Inspect current status after a timeout; do not retry
61
+ automatically. This policy covers Idam source saves only, not starter creation,
62
+ builds or deployments; those retain their separate permissions and approvals.
63
+ These commands require current Idam access. See `blinkhost docs ai`.
64
+
65
+ Create a supported backend starter with `ai starters --project PROJECT_UUID` and
66
+ `ai starter-review --project PROJECT_UUID --name api --language LANGUAGE_ID --revision SOURCE_REVISION --request-id REQUEST_UUID`.
67
+ Inspect the returned files and retain the review UUID before approving with
68
+ `ai starter-approve REVIEW_UUID --project PROJECT_UUID --digest ACTION_DIGEST --confirm REVIEW_UUID`.
69
+ This saves new source through normal module limits; it does not build or publish.
70
+ No AI credits are used. After an uncertain response, use
71
+ `ai starter-status REVIEW_UUID --project PROJECT_UUID` to reconcile the original
72
+ save, never another create. Read, preparation and approval require `ai:read`,
73
+ `ai:execute` and `ai:approve` respectively.
74
+
75
+ Saved WASM modules can be reviewed for a normal, metered build using
76
+ `ai build-modules --project PROJECT_UUID`, followed by
77
+ `ai build-review --project PROJECT_UUID --module MODULE_UUID --revision SOURCE_REVISION --request-id REQUEST_UUID`.
78
+ Retain the request UUID. Review the source in the IDE and the returned digest,
79
+ usage policy and expiry. Then explicitly approve with
80
+ `ai build-approve REVIEW_UUID --project PROJECT_UUID --digest ACTION_DIGEST --confirm REVIEW_UUID`.
81
+ Read/list needs `ai:read`, preparation needs `ai:execute`, and approval needs
82
+ `ai:approve`. This uses normal build allowance, configured overages and duration
83
+ usage—not AI credits. It does not publish, promote an artifact or commit files.
84
+ Unsaved edits are excluded. After a timeout, use
85
+ `ai build-status REVIEW_UUID --project PROJECT_UUID` before any further action;
86
+ do not create a new review to repeat an uncertain build. See `blinkhost docs ai`.
87
+ These commands require current Idam access and an available module compiler.
88
+
89
+ For an eligible multi-step task, use
90
+ `blinkhost ai resume TASK_UUID --confirm TASK_UUID` with `ai:execute` to request
91
+ continuation from its saved checkpoint. This keeps the same task, original
92
+ credit limit and confirmed usage. Active work and retry delays are preserved;
93
+ it does not restart stopped or completed tasks, increase spending, approve
94
+ changes or repeat confirmed execution. Project access, revision and guidance
95
+ are checked again. After a timeout, inspect `ai status` before taking another
96
+ action.
97
+
98
+ Reviewed public sources have a separate feature gate that is off by default. Use
99
+ `blinkhost ai sources --project PROJECT_UUID` with `ai:read` to inspect the
100
+ available excerpts, attribution and capture/review dates. To use them, set
101
+ `"mode": "research"` and `"research_source_ids": ["SOURCE_SHA256"]` in the
102
+ request JSON (up to four unique IDs). This does not browse or fetch websites.
103
+ Source text counts toward the credit estimate. Expired or withdrawn sources
104
+ cannot start new work; already dispatched work can finish. Task status/export
105
+ retains the excerpts provided, not later versions of the source website. A model
106
+ citation is not proof that a conclusion is correct.
107
+
108
+ Source-review diffs use `[U+…]` markers for invisible control characters and
109
+ annotations for line endings. They are review displays, not patches to copy.
110
+ Approvals bind the original source, which these annotations do not modify.
111
+ Structured terminal output escapes controls while preserving the exact decoded
112
+ JSON values. Ordinary Unicode is retained; this is not a confusable-character
113
+ detector or a guarantee that proposed code is safe.
114
+
115
+ Version 2.5.0 includes `blinkhost ai` task and reviewed-change commands, with
116
+ offline help at `blinkhost docs ai`. They require an enabled Idam preview.
117
+ AI task execution (`ai:execute`) and source
118
+ approval (`ai:approve`) are separate, explicitly requested permissions; existing
119
+ sessions do not gain these permissions automatically. See the [changelog](./CHANGELOG.md).
120
+
121
+ Saving an approved proposal changes workspace source only. Build, test and preview
122
+ before publishing. To share source with Azure OpenAI for a task, include optional
123
+ `source_paths` in its request JSON (up to eight project-relative paths of saved
124
+ workspace files, 16 KiB each / 24 KiB total). No local files are uploaded. Review
125
+ selected files for credentials; automated screening is not exhaustive. Omit the
126
+ field to share structural metadata only.
127
+
128
+ Unknown model usage is never automatically retried or refunded.
129
+
130
+ To review only part of a proposal, use `blinkhost ai review TASK_UUID --path
131
+ src/example.ts` (repeat `--path` for more files). With no paths, all proposed files
132
+ are included. Inspect every returned diff before approval. Changing the selection
133
+ requires a fresh review; saving finishes the task and omitted files may still be
134
+ needed for the application to work. Task exports distinguish the full proposal
135
+ from `review.paths`; only a populated review `applied_at` records that selection's
136
+ save. This is file selection, not automatic dependency analysis or project copying.
137
+
138
+ Use `blinkhost ai compatibility --project PROJECT_UUID` for a read-only review of
139
+ the saved project's declared dependencies. It requires `ai:read` and the enabled
140
+ Idam preview. Results identify the workspace
141
+ revision, manifest paths, declaration sections and inspection limits. Only a fixed
142
+ set of npm and Python package names is checked in `package.json` and single-line
143
+ `requirements.txt` and static `pyproject.toml` declarations. Runtime, optional and
144
+ build-system requirements keep distinct labels; build-only use is not runtime
145
+ use. Python markers and extras are not evaluated. Dynamic dependencies, tool
146
+ overrides, includes, pip options, URLs and other manifest formats need manual
147
+ review. No lockfile or transitive dependency graph is resolved.
148
+ No findings is **not a compatibility pass**. This command uploads no local
149
+ files, makes no model calls, reserves no credits and does not install, build, test,
150
+ adapt or deploy code. Customer backend execution remains WASM-only. Review project
151
+ metadata before sharing command output, and rerun after workspace changes.
152
+
153
+ You can save optional project guidance for your own future tasks using the
154
+ `ai memory-show`, `memory-save` and `memory-clear` commands. First run
155
+ `blinkhost ai memory-show --project PROJECT_UUID` and inspect the saved version.
156
+ Then use `blinkhost ai memory-save --project PROJECT_UUID --file @guidance.txt
157
+ --expected-version VERSION --confirm PROJECT_UUID` to upload a regular UTF-8 file
158
+ of at most 4 KiB. Saving authorizes sending this guidance with future model tasks;
159
+ it does not change permissions, runtime support or billing. Keep credentials out.
160
+ `memory-show` prints private text: take care with logs and shared terminals.
161
+
162
+ To clear it, run `blinkhost ai memory-clear --project PROJECT_UUID
163
+ --expected-version VERSION --confirm PROJECT_UUID`. Editing or clearing prevents
164
+ queued tasks and later workflow steps from using an older version. Work already
165
+ sent may finish. Existing task copies and backups are not erased. After a timeout
166
+ or conflict, reload and compare with `memory-show` before another write; the CLI
167
+ never retries it automatically. Reading requires `ai:read`; saving and clearing
168
+ require `ai:execute`. CI workload identities cannot use the personal Idam preview,
169
+ including indirectly through task creation or history, regardless of token scopes.
170
+
171
+ Connected investigation-and-review sequences require a separate feature gate.
172
+ Inspect `ai status TASK_UUID` first. Then
173
+ `ai workflow-plan TASK_UUID --maximum-units TOTAL_LIMIT --confirm TASK_UUID`
174
+ saves a draft with two follow-ups of 80 credits each. `TOTAL_LIMIT` must
175
+ cover the original task's approved limit plus 160 credits, up to 2,000 total.
176
+ Saving does not approve follow-ups; the original task continues independently.
177
+ `workflow-start` remains a draft-only compatibility alias. Use
178
+ `ai workflow-status WORKFLOW_UUID` to inspect the saved plan and version history.
179
+ To change a draft, use `ai workflow-revise WORKFLOW_UUID --request @plan.json
180
+ --expected-revision VERSION --digest PLAN_DIGEST --confirm WORKFLOW_UUID`.
181
+ The regular UTF-8 JSON file (16 KiB maximum) contains exactly `steps`,
182
+ `maximum_units` and `maximum_context_units`; see `blinkhost docs ai` for the schema.
183
+ Then approve the version you inspected with `ai workflow-approve WORKFLOW_UUID
184
+ --expected-revision VERSION --digest PLAN_DIGEST --confirm WORKFLOW_UUID`.
185
+ Changed drafts require fresh review; approved or stopped plans cannot be edited.
186
+ Reading requires `ai:read`, preparing or revising a plan requires `ai:execute`,
187
+ and approving it requires the separate `ai:approve` permission. Approval permission
188
+ does not grant access to another user's plan or bypass current project access.
189
+ These operations grant no funding and reserve no additional credits. Each later
190
+ step checks available balance and current project access. Use
191
+ `ai workflow-cancel WORKFLOW_UUID --confirm WORKFLOW_UUID` to stop later steps.
192
+ After a timeout, task status exposes `analysis_workflow.id`; inspect it before
193
+ making another write. Never automatically retry approval or reuse stale versions.
194
+ These are drafts, not executed tests or deployments.
195
+ Follow-ups retain the original request and previous draft under their own task
196
+ retention periods. Removing one task does not remove copies in another.
197
+
198
+ `blinkhost ai export TASK_UUID --json` prints a versioned private task record.
199
+ Add `--include-source` only when you want proposed source-file copies included.
200
+ Requests and narrative may still contain private information: review before
201
+ sharing. This is not a project backup or deployment certificate. Removed content
202
+ is not reconstructed; long histories are marked partial, and existing downloads
203
+ are outside task-history retention. See `blinkhost docs ai` for limits.
204
+
205
+ To undo an Idam source save in the limited preview, run
206
+ `blinkhost ai rollback-review TASK_UUID --json`, inspect its file restorations and
207
+ removals, then run `blinkhost ai rollback-approve TASK_UUID --digest UNDO_ACTION_DIGEST --confirm TASK_UUID`.
208
+ This is a separate, expiring approval, not the original source-save digest.
209
+ Preparing requires `ai:execute`; confirming requires `ai:approve`. Later edits to
210
+ affected files block undo. Other files and folders are preserved. Removed task
211
+ content cannot be recovered. Undo does not reverse deployments, charges or Git
212
+ commits. Check the task after a timeout; these commands do not automatically retry.
213
+
214
+ ### Local readiness
215
+
28
216
  ```bash
29
217
  blinkhost quickstart
30
218
  blinkhost docs
@@ -51,8 +239,28 @@ blinkhost profile use work
51
239
 
52
240
  Revoke a device with `blinkhost auth revoke SESSION_ID` or disconnect all CLI sessions for the active profile with `blinkhost auth logout`.
53
241
 
242
+ If your CLI session is rejected after signing out of all devices, an account
243
+ security change or a BlinkHost security update, run `blinkhost auth login` again
244
+ with the same `--profile` and any explicit `--scope` options you need. Sign in to
245
+ the correct account in your browser and review the new request before approving.
246
+ Reopening an old approval link does not reconnect the CLI. Reauthentication does
247
+ not change your project files, deployments or billing plan. If the new sign-in is
248
+ blocked, check email verification and any required legal acceptance in the
249
+ dashboard; do not copy credentials from another device to work around it.
250
+
54
251
  Interactive credential storage uses macOS Keychain, Windows Password Vault, or Linux Secret Service (`secret-tool` with an available, unlocked session keyring). The CLI intentionally does not fall back to a plaintext refresh-token file. Headless systems should use a registered GitHub OIDC workload or a short-lived runtime access token.
55
252
 
253
+ Before opening browser authorization, the CLI checks that the credential tooling can run. This does not prove that your keyring is unlocked; on Linux, start an unlocked Secret Service session first. Missing tooling is reported before a device authorization is requested.
254
+
255
+ Credential-tool checks stop after five seconds on macOS and Linux, or 15 seconds
256
+ on Windows to allow PowerShell to start. Credential reads and writes stop after
257
+ 30 seconds. These checks do not retry. Keyring errors use safe messages without displaying helper
258
+ output. On Linux, an unavailable session keyring is reported as a credential-service
259
+ failure rather than a missing sign-in. Unlock or restart your Secret Service session.
260
+ If browser approval succeeded but saving the session failed or timed out, review
261
+ your CLI sessions in BlinkHost settings before starting another sign-in. The CLI
262
+ does not automatically retry credential writes or fall back to plaintext storage.
263
+
56
264
  ## Create or adopt a project
57
265
 
58
266
  ```bash
@@ -84,6 +292,44 @@ blinkhost test .
84
292
 
85
293
  ## Remote workflows
86
294
 
295
+ ### Download project source
296
+
297
+ ```bash
298
+ blinkhost projects export PROJECT_UUID --output ./project-source.zip --json
299
+ ```
300
+
301
+ This downloads source and portable configuration through BlinkHost's existing
302
+ export service. It requires `projects:read` and an owner, admin or developer role;
303
+ connecting GitHub is optional. Choose a new `.zip` filename in an existing
304
+ directory without symbolic links. Downloads are limited to 32 MiB and 30 seconds.
305
+ The CLI does not follow redirects, replace existing files, extract the ZIP or run
306
+ its contents. It returns a SHA-256 checksum and saves with private permissions
307
+ where POSIX permissions apply.
308
+
309
+ The default portable export requires a supported frontend configuration. For
310
+ backend-only projects, or to download source without generating build files, use:
311
+
312
+ ```bash
313
+ blinkhost projects export PROJECT_UUID --source-only --output ./source.zip --json
314
+ ```
315
+
316
+ Source-only mode preserves workspace files and validated project assets, including
317
+ any existing configuration. It does not generate or validate build configuration,
318
+ README files, database schemas or lockfiles. A connected repository's saved base
319
+ is overlaid with the workspace; files outside the application root are preserved.
320
+ It is not a fresh fetch of the remote branch. The server must explicitly confirm
321
+ source-only mode, so an older server cannot silently return generated files.
322
+ The same authorization, credential screening and size limits apply in both modes.
323
+ Known configuration and credential-screening errors include next steps and a
324
+ request ID; raw server details are not printed. Export never repairs your stored
325
+ configuration, installs dependencies or changes source on your behalf.
326
+
327
+ The archive is **not a database backup or a running deployment**. Database rows,
328
+ runtime secrets, deployed artifacts and complete Git history are not included.
329
+ Source is screened for possible credentials, but review it before sharing.
330
+ Configure resources and secrets separately, and check compatibility before running
331
+ the exported application elsewhere. `ai export` instead exports a task record.
332
+
87
333
  Resource commands use the same pattern:
88
334
 
89
335
  ```bash
@@ -190,7 +436,7 @@ Pin or roll back explicitly with `npm install --global @blinkhost/cli@VERSION`.
190
436
  ```bash
191
437
  cosign verify-blob \
192
438
  --bundle SHA256SUMS.sigstore.json \
193
- --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.4.0" \
439
+ --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.5.0" \
194
440
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
195
441
  SHA256SUMS
196
442
  ```
package/dist/api.d.ts CHANGED
@@ -10,7 +10,12 @@ export declare class ApiClient {
10
10
  private accessToken;
11
11
  private constructor();
12
12
  static create(profileName?: string): Promise<ApiClient>;
13
+ private static refresh;
14
+ static logout(profileName?: string): Promise<{
15
+ profile: string;
16
+ }>;
13
17
  static fromAccessToken(profileName: string, profile: Profile, accessToken: string): ApiClient;
18
+ projectArchive(projectId: string, mode?: 'portable' | 'source'): Promise<Buffer>;
14
19
  request(path: string, init?: RequestInit): Promise<unknown>;
15
20
  rememberIdentity(identity: {
16
21
  id?: number;