direct-cli 0.5.3__tar.gz → 0.5.4__tar.gz

{direct_cli-0.5.3 → direct_cli-0.5.4}/AGENTS.md

@@ -35,13 +35,33 @@ Naming rules:
 
 ### Input Rules
 
-- All user-facing input must be passed only through typed CLI flags.
+- In default headless mode, all user-facing input must be passed only through typed CLI flags.
+- Authentication input prompts require explicit `direct auth login --interactive`.
 - `--json` is not part of the public CLI contract.
 - User-facing parameters must not be passed through `--json`.
 - The CLI must not accept `SelectionCriteria`, nested payloads, update payloads, bidding rules, or any other user-facing command input through `--json`.
 - Typed flags and JSON blobs must not be mixed as part of one public command contract.
 - If the API requires a complex object, the CLI must expose explicit flags or subcommands instead of forwarding raw JSON.
 
+### Authorization Execution Mode
+
+- Authorization is headless and non-interactive by default, including when stdin and stdout are terminals. TTY detection must never enable login dialogs or browser UI by itself.
+- `direct auth login` defaults to the headless API flow: print the authorization URL and accept the completion code later through typed flags or explicit stdin input.
+- Login menus and OAuth code prompts require `direct auth login --interactive`.
+- Manual browser login requires explicit `--interactive` or `--headful`. `--allow-no-tty` only overrides the terminal check; it does not authorize browser UI by itself.
+- Chrome import is headless by default. Failed headless verification must not retry in a visible browser automatically.
+- Missing or expired credentials in ordinary commands produce an actionable error, never an implicit login.
+- Saving credentials into an existing profile requires explicit `--force`; the headless completion and token import refuse to overwrite otherwise.
+
+### Data Safety — No Silent Overwrites
+
+- Stored user data (auth profiles, credentials, folder bindings, browser sessions) is never replaced silently.
+- A write is either the command's declared purpose (the command then reports what was replaced) or requires an explicit confirmation flag (`--force`). Ordinary commands never write stored user data as a side effect.
+- Overwriting an existing auth profile requires explicit `--force` on the CLI layer and `overwrite=True` on the helper layer; the refusal names the current owner's login.
+- Replacing an existing `YANDEX_DIRECT_TOKEN` in the folder `.env` prints a warning naming the previous owner.
+- New write paths for stored user data must go through the guarded helpers (`save_oauth_profile`, `save_env_credentials`); bypassing the guard is a contract violation.
+- Production API mutations are always explicit commands, classified SAFE / WRITE_SANDBOX / DANGEROUS in `direct_cli/smoke_matrix.py`.
+
 ### Command Formatting Rules
 
 - Every canonical CLI command must be written strictly on a single line.

{direct_cli-0.5.3 → direct_cli-0.5.4}/CHANGELOG.md

@@ -1,5 +1,213 @@
 # Changelog
 
+## Unreleased
+
+### BREAKING CHANGES
+
+**`auth login`/`auth status`/`auth logout` use `api|browser` subcommands; `--method`, `--interactive` and `--headful` are removed without aliases (#924).**
+
+The two authorization domains — the Direct API OAuth token and the browser
+session used by `masters`/`history` — now have explicit names:
+
+- `direct auth login api` — OAuth login for API/v4 commands (what bare
+  `direct auth login` did and still does: the owner-decided default is the
+  API domain, and the old "Choose login method" menu is gone).
+- `direct auth login browser` — manual login in a visible window for browser
+  commands (`masters`, `history`, ...); visibility needs no flag anymore.
+  `--source chrome` keeps importing an existing Chrome session headless;
+  `--allow-no-tty` is the only surviving special flag — it lets a script
+  open the login window without a terminal.
+- `direct auth status api|browser` selects a domain; **bare `direct auth
+  status` now reports both domains** (an `API:` and a `Browser:` block,
+  previously the API-only default — parse the new `Browser:` section or use
+  `auth status api` for the old behavior; combined JSON is unchanged:
+  `{"api": ..., "browser": ...}`).
+- `direct auth logout api --profile NAME` / `direct auth logout browser`
+  (bare `auth logout` asks for a domain).
+- `--profile` is valid in both domains; in the browser domain it is accepted
+  and reported as ignored (browser sessions are shared). `--profile-dir`/
+  `--chrome-profile` live only in the browser domain.
+- In the API domain a terminal is now the interactive default: the login
+  prints the URL, opens the browser, reads the code and binds the folder's
+  `.env`. `--format json`, `--start-pkce` and `--code -` stay headless —
+  unattended scripts are unaffected.
+
+Every removed flag fails with `click.UsageError` naming the exact
+replacement from `direct_cli/_auth_hints.py` — the same pointer the live
+auth errors advise. Deprecated aliases (`playwright login`,
+`masters login`/`logout`/`status`) keep their stdout formats; their
+replacement notices now point at the new subcommand surface.
+
+### Added
+
+- **Optional diagnostics output is now env-switched and hidden by default
+  (#925).** Successful v5 API calls no longer print anything extra: the API
+  Units points line is opt-in via `DIRECT_SHOW_UNITS=1`, which prints one
+  stderr line per successful call — `API units: <spent>/<rest>/<daily limit>`
+  (e.g. `API units: 10/20828/64000`), plus ` (used-login: <login>)` when the
+  API returned `Units-Used-Login` (agency accounts). The v4 Live API returns
+  no Units headers, so v4 commands stay silent under this switch. stdout is
+  never touched,
+  so pipes and `--format json` parsing are unaffected. `DIRECT_QUIET=0`
+  restores the legacy behaviour for channels that had one (Units had none).
+  Safety output — inherited-credential warnings (#909), sandbox notices, API
+  warnings — is never suppressed. The switch registry
+  (`direct_cli/optional_output.py`) is extensible: future optional channels
+  (Reports `retryIn`/`reportsInQueue`) are added as one entry. Supported by a
+  success-response hook in the vendored `tapi_yandex_direct` client, mirrored
+  on `master` of the axisrow fork (axisrow/tapi-yandex-direct#28, merged) so
+  `update_vendor.sh` keeps it (#634).
+
+### Changed
+
+- **One canonical login pointer in every authorization error (#924, part 1 —
+  non-breaking).** A new leaf module `direct_cli/_auth_hints.py` defines the
+  canonical pointers — `direct auth login api`, `direct auth login browser`,
+  `direct auth login browser --source chrome` — and every auth error and
+  deprecated-command notice now advises exactly one domain-appropriate pointer.
+  Previously a stale `masters list` session printed four contradictory
+  suggestions, and a deprecated command's warning recommended different flags
+  than the error of the same command. Commands and flags are unchanged; the
+  `auth login api|browser` subcommand restructuring lands separately. An AST
+  guard in `tests/test_unified_auth.py` bans literal login-command strings
+  outside `_auth_hints.py`, so a second hint source fails CI.
+
+### Fixed
+
+- **`reports get`: API error 56 (method rate limit) now retries with
+  exponential backoff (#918).** Yandex allows only 1 request per 10 seconds
+  per method; with several `direct`/MCP clients sharing one account, each
+  keeps consuming the other's window and the first 56 used to kill the
+  command (the vendored client's own retry branches read the error code from
+  the wrong payload key and never fire). Now the reports POST is retried up
+  to 5 attempts, waiting 10/20/40/80s plus up to 50% jitter; each attempt
+  logs `attempt N/5 … retrying in Xs` to stderr so a waiting CLI is
+  distinguishable from a dead one. If the limit still doesn't clear, the
+  final error names the likely cause — another client or session working
+  with the same Yandex Direct account. Any other error code (53, 152, 506,
+  9000, …) fails immediately as before.
+- **`reports get`: `--from`/`--to` are bound to `--date-range-type
+  CUSTOM_DATE` (#898).** Relative periods (`TODAY`, `YESTERDAY`, `LAST_*`,
+  `ALL_TIME`, `AUTO`) no longer require the flags and build requests without
+  `DateFrom`/`DateTo`, per the Reports spec ("required at CUSTOM_DATE and
+  forbidden with other values"). Explicit dates alongside a relative period,
+  and `CUSTOM_DATE` with either date missing, fail with a usage error instead
+  of silently sending a forbidden combination.
+- **`--format csv`/`--format tsv`: export no longer fails when later records
+  carry optional fields missing from the first record (#900).** The column set
+  is now the union of keys across all records (in first-seen order) instead of
+  the first record's keys alone, so a record with an extra optional field
+  (e.g. `TextAd` present only on `TEXT_AD` rows) gets its own column and rows
+  missing a field export an empty cell — success no longer depends on row
+  order. Explicitly passed `headers` still define the columns exactly as
+  before.
+
+- **`masters list`: intermittent grid-load timeout now retries internally
+  (#912).** The campaigns grid's `GridCampaigns` data request is observed
+  across two attempts — 30s, then 60s, with a fresh page load per attempt —
+  before the command fails, so an ordinary slow page load no longer surfaces
+  as a terminal error requiring a manual retry. The exhausted-attempts error
+  is worded purely as the retryable timeout it is (the old text's "Yandex may
+  have changed the grid's internal API" clause is gone); an unrecognized
+  response structure keeps its separate, API-change message. New
+  `masters list --timeout SECONDS` scales both per-attempt budgets for slow
+  connections.
+- **`masters targetactions get`: a populated goals table is no longer
+  reported as empty (#910).** The "Целевые действия" table goes through a
+  genuine, non-throwing EMPTY interval mid-hydration (the same race
+  #750/#756 documented for the save guard), and the command answered with a
+  single immediate read — landing in that dip silently returned
+  `{"TargetActions": [], "Count": 0}` for a campaign whose table is
+  populated, indistinguishable from genuinely empty (the audit over 28
+  campaigns produced 2 false violations this way). The read is now the same
+  settled, failure-aware snapshot the `--preserve-target-actions` guard
+  uses: rows are reported only once their `{GoalId: Price}` identity is
+  stable, and a rendered section whose rows never settle into a readable
+  snapshot fails with an error instead of printing `Count: 0`. A genuinely
+  empty table still answers `Count: 0`, and so does a max-clicks campaign
+  (no section rendered) — the latter now pays the settle deadline (~20 s)
+  before that answer, same as the guard path, because the same dips briefly
+  unmount the section and its absence is only meaningful after settling had
+  its chance.
+
+## 0.5.4 — 2026-10-24
+
+### Unified authorization
+
+- **Existing profiles are never overwritten silently.** `direct auth login`
+  refuses to write credentials into an existing profile (including the default
+  `default`) without explicit `--force`; a fresh profile name is unaffected.
+  Previously a headless completion replaced the profile's token, refresh token
+  and OAuth client without warning. The refusal names the current owner's
+  login, and replacing an existing `YANDEX_DIRECT_TOKEN` in the folder `.env`
+  prints a warning.
+- Authorization is headless and non-interactive by default, including in a
+  terminal. Login dialogs require `--interactive`; manual browser login also
+  accepts explicit `--headful`. TTY detection never selects an interactive mode.
+- Chrome import no longer retries failed headless verification with a visible
+  browser. Legacy browser login paths also require an explicit UI flag.
+
+- Canonical API/browser login, status, logout and browser diagnostics now live
+  under `direct auth`. Existing explicit login paths and JSON remain supported
+  through deprecated adapters; credentials and browser storage are not migrated.
+- Resource commands use saved browser sessions only. Missing, expired or rejected
+  sessions fail with a login hint, without Chrome cookie import, Keychain access
+  or retrying an operation. Move resource Chrome flags to explicit
+  `direct auth login --method browser --source chrome`.
+- API logout removes the selected local profile and this folder's binding;
+  browser logout removes both CLI browser sessions. Source Chrome is untouched.
+- Browser diagnostics skip Keychain and cookie decryption, preserving check names.
+
+### BREAKING CHANGES
+
+**A folder with no bound credentials has no credentials — the global active
+profile is no longer inherited silently (#904).**
+
+Since #489 a folder with no explicit credential binding (no cwd `.env`, no
+`--profile`, no base env) silently resolved credentials from the global
+active profile in `~/.direct-cli/auth.json` — every new project started
+billing the last logged-in account, and `direct auth status` reported an
+indistinguishable `source=oauth`. Now an unbound folder has no credentials:
+
+- **Non-interactive sessions** (scripts, sub-processes — including the
+  Yandex Direct MCP plugin): every API command fails with `UsageError` and
+  binding hints until the folder is bound. New: `direct auth write --profile
+  <name>` binds a folder without any prompts — it writes the profile's
+  credentials to the cwd `.env` (merge, `0600`, the token is never printed);
+  `--profile` is required, nothing is bound implicitly.
+- **Terminal sessions** also fail without opening a login dialog. Explicit
+  `direct auth login --interactive` offers API or browser authorization. The API menu
+  binds a saved or newly authorized profile to the cwd `.env` immediately;
+  a newly named profile does not change the global active profile.
+  `--dry-run` still needs no credentials and stays silent.
+- **`direct auth status`** in an unbound folder reports
+  `source=null`/`has_token=false` plus a note about the global profile
+  (`global_profile`/`global_login` in JSON) — the global profile exists, but
+  it is not presented as this folder's credentials.
+- **Opt-in**: `YANDEX_DIRECT_INHERIT_GLOBAL=1` restores the #489 behavior —
+  the global active profile is inherited silently again, and `auth status`
+  labels it `source=global-profile-inherited`.
+
+Explicit bindings are unchanged and still win: `--token`, `--profile`,
+base env, cwd `.env`. `--sandbox` does not bypass the gate — the sandbox
+authenticates under the same profile login, so a wrong inherited account is
+the same mistake there. A folder with only a partial credential ref (e.g.
+an exported `YANDEX_DIRECT_LOGIN` and no token) no longer silently inherits
+the global active profile either — the bind gate applies there too.
+
+Migration: bind the folders you use via a `.env` file (`direct auth write`,
+or run `direct auth login --method api` once per folder), pass `--profile`, or set
+`YANDEX_DIRECT_INHERIT_GLOBAL=1` where inheritance is intended.
+
+Offline tests are insulated from the same nondeterminism: the suite now
+points `AUTH_STORE_PATH` at a per-test file by default (autouse fixture;
+live tiers keep the real store so their profile fallback still works) and
+runs under the inheritance opt-in, so offline tests no longer change
+behavior with the developer's active `direct auth` profile. The `ruff` dev
+pin moves to `>=0.16,<0.17` with the pre-0.16 default rule set pinned
+explicitly in `[tool.ruff.lint] select`, so lint behavior no longer drifts
+with the ruff version.
+
 ## 0.5.3 — 2026-10-07
 
 ### Fixed

{direct_cli-0.5.3 → direct_cli-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.5.3
+Version: 0.5.4
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: flake8>=4.0; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Requires-Dist: pyright>=1.1.400; extra == "dev"
-Requires-Dist: ruff<0.16,>=0.1; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Requires-Dist: requests>=2.0; extra == "dev"
 Requires-Dist: beautifulsoup4>=4.12; extra == "dev"
 Requires-Dist: lxml>=4.9; extra == "dev"
@@ -66,18 +66,16 @@ pip install direct-cli
 Мастер кампаний has **no Yandex Direct API surface at all** — it only exists
 in the web interface, and must not be confused with `UNIFIED_CAMPAIGN` (an
 unrelated v5 API campaign type already supported by `campaigns add/get --type
-unified_campaign`). `direct masters list` / `direct masters get <ids>` read it
-by decrypting your existing Chrome cookies for `yandex.ru` and injecting them
-into a Playwright-driven browser — no separate login. Only those cookies are
-ever read; the rest of your Chrome profile is never touched. On macOS the
-cookie key lives in your login Keychain, so the first run shows a one-time
-system permission dialog — click Allow. Linux is supported when Chrome uses
-its basic (non-keyring) password store; Windows isn't supported yet. Requires
-the optional `browser` extra:
+unified_campaign`). Browser-backed commands use a saved browser session,
+independent of the API token. Set it up explicitly with
+`direct auth login browser`. This opens a CLI-owned Chromium window
+and works on macOS/Linux/Windows without reading Chrome or Keychain.
+Requires the optional `browser` extra:
 
 ```bash
 pip install "direct-cli[browser]"
 playwright install chromium
+direct auth login browser
 direct masters list
 direct masters list --status archived
 direct masters get 72349978
@@ -245,18 +243,18 @@ never a silent skip, and the whole plan (including that local image/video
 files exist) is validated before the first save.
 
 A campaign that fails is reported with an `Error` and does not stop the rest;
-the command exits non-zero afterwards. If the browser session goes stale
-mid-plan it is re-opened once and the run continues from the first campaign
-that was never saved — an already-saved campaign is never saved twice.
+the command exits non-zero afterwards. If browser authorization fails mid-plan,
+the run stops with a login hint. It never imports cookies or repeats the
+operation under another session.
 `--pacing-ms` (default 1000) controls the pause between campaigns,
 `--moderation-statuses` additionally reads each campaign's current moderation
 statuses after its save (a snapshot — moderation usually has not run yet at
 that point, so a rejection can still appear later), and `--dry-run` prints
 what would be applied without opening a browser.
 
-If you see "Found no Yandex cookies", open https://direct.yandex.ru in Chrome
-and log in first. If you use a non-default Chrome profile, pass
-`--chrome-profile "Profile 1"`.
+To import an existing Chrome session instead, run
+`direct auth login browser --source chrome --chrome-profile "Profile 1"`.
+Chrome profile flags belong to explicit login, not resource commands.
 
 Since this data has no API contract, the parser degrades per-section (a
 warning, not a hard failure) if Yandex changes the page markup, rather than
@@ -334,33 +332,26 @@ running it twice creates a SECOND copy, not an update to the first. By
 default the copy is saved as a draft (`--draft`); pass `--launch` to launch
 it immediately in production instead. Same no-`--sandbox` caveat as `add`.
 
-**Browser session (optional but recommended):** `direct masters` decrypts
-your Chrome cookies fresh on every call by default, which means a Keychain
-prompt every time on macOS. Run `direct playwright login` once to decrypt
-and save a reusable session (`~/.direct-cli/playwright/session.json`, `0600`)
-— subsequent `direct masters` calls use it automatically and skip the
-Keychain round-trip. If something in the pipeline is broken (playwright not
-installed, wrong Chrome profile, expired session), `direct playwright
-doctor` reports the full chain of checks without logging in or writing
-anything.
-
-**Keychain-free alternative:** `direct masters login` opens a visible
-browser window on a persistent Chromium profile owned by the CLI
-(`~/.direct-cli/chrome-profile/`) — log in by hand once via Yandex Passport,
-and the command exits once the session is confirmed. This never touches your
-real Chrome profile or the macOS Keychain at all, so it works identically on
-macOS/Linux/Windows; the cost is a one-time manual login instead of a
-transparent cookie copy. When this profile exists, `direct masters` prefers
-it automatically over the saved `playwright login` session. It's interactive
-(blocks for up to `--timeout` seconds, default 300, waiting for you to sign
-in), so it can't run unattended. Run `direct masters logout` to delete the
-profile and revoke the on-disk session (a no-op warning, not an error, if
-none exists).
-
-Run `direct masters status` to check which of these two sessions `masters`
-commands would currently use — which tier is active, the persistent
-profile's path, and the saved session's expiry — without any network call
-or side effect (no browser launch, unlike every other `masters` command).
+**Browser authorization:** `direct auth login browser` opens the
+CLI's persistent Chromium profile (`~/.direct-cli/chrome-profile/`) and waits
+up to `--timeout` seconds (default 300) for manual login. It requires a
+terminal unless `--allow-no-tty` is explicitly supplied.
+
+Alternatively, `direct auth login browser --source chrome` imports
+Chrome cookies into `~/.direct-cli/playwright/session.json` (`0600`). Only
+this explicit import may request Keychain access. `--profile-dir` selects the
+source directory and `--chrome-profile` the Chrome profile subdirectory.
+
+Commands prefer an existing persistent Chromium session over an imported
+session. `direct auth status browser` inspects both without opening
+a browser; it reports saved state, not proof of current server-side validity.
+`direct auth doctor` diagnoses dependencies and saved session metadata;
+cookie decryption checks are skipped. Missing or rejected sessions produce
+a login hint; commands never start login or import cookies automatically.
+
+`direct auth logout browser` removes both CLI-owned browser sessions.
+It does not touch the original Chrome profile. Old browser-auth commands
+remain deprecated compatibility aliases; their stdout formats are preserved.
 
 ### История изменений (change history) — browser-only
 
@@ -370,8 +361,8 @@ changed IDs, and Live v4's `GetEventsLog` logs *system* events
 (`BannerModerated`, `MoneyOut`, …) — none of them can answer "who changed
 this field, when, and from what to what". That history exists only in the web
 interface's «История изменений» section, so `direct history` reads it through
-the same browser session `direct masters` uses (same `--headful`/
-`--profile-dir`/`--chrome-profile` options, same no-`--login` rule):
+the same saved browser session `direct masters` uses (same `--headful`
+option and no-`--login` rule):
 
 ```bash
 direct history get
@@ -399,6 +390,63 @@ A bare `--date-from`/`--date-to` date covers the whole day; pass
 `YYYY-MM-DDTHH:MM:SS` for an exact window. Without them, the period the
 section itself defaults to is used.
 
+### Authorization
+
+`auth login` has two explicit domains: `direct auth login api` (an OAuth
+token for API/v4 commands, saved in an auth profile) and
+`direct auth login browser` (a browser session for browser commands:
+`masters`, `history`, ...). Bare `direct auth login` is the API login.
+
+In a terminal the API login is interactive by default: it prints the
+authorize URL, opens the browser, reads the code, and binds the credentials
+to this folder's `.env`. In a non-interactive shell it prints the API
+authorization URL without opening a browser or asking questions. Complete
+the two-step flow with `--code` or `--code -` and bind a saved profile with
+`direct auth write --profile NAME`. Saving into an existing profile
+(including the default `default`) requires explicit `--force`; without it
+the save refuses to overwrite stored credentials. The CLI never replaces
+stored credentials, profiles or browser sessions silently: a replacement is
+either the command's declared purpose (and it reports what was replaced) or
+requires explicit `--force`.
+
+The API login in a terminal first offers to reuse a saved profile (bound to
+this folder's `.env` on the spot); otherwise a new profile name comes from
+the account login and gets a numeric suffix when the name is taken.
+API credentials and browser cookies stay separate and may belong to
+different accounts.
+
+```bash
+direct auth login                     # = direct auth login api
+direct auth login api
+direct auth login browser             # manual login in a visible window
+direct auth login browser --source chrome
+direct auth status                    # both domains
+direct auth status api
+direct auth status browser
+direct auth doctor
+direct auth logout api --profile agency1
+direct auth logout browser
+```
+
+Manual browser login is visible by definition; `--allow-no-tty` only
+overrides the terminal check for scripts that open the window on purpose.
+Chrome import stays headless, including when verification fails: there is no
+automatic headful retry. All resource commands fail with
+a helpful error when authorization is missing, including in a terminal.
+`direct` without arguments still shows help. API logout removes the named
+local profile and this folder's API binding, preserving other `.env` settings.
+The binding includes local token/login values, secret-manager references and
+the folder's global-profile inheritance setting.
+It does not revoke token copies in other folders, external environments, or
+secret managers. Browser logout removes both saved CLI sessions.
+
+`auth status` reports both domains (an `API:` and a `Browser:` block);
+combined JSON has `api` and `browser` sections. `auth status api` and
+`auth status browser` select one domain. Existing API flags and two-step
+PKCE/stdin login remain supported in unattended workflows. The old
+`--method`/`--interactive`/`--headful` flags were removed without aliases:
+each old form fails with the exact replacement command.
+
 ### Configuration
 
 Create a `.env` file in your working directory:
@@ -446,11 +494,12 @@ Notes:
 - In a non-interactive shell, run `direct auth login --profile NAME` first, then finish with `direct auth login --code - --profile NAME` and pass the browser code on stdin.
 - `direct auth login --code CODE --profile NAME` remains supported for compatibility, but automation should use `--code -` to avoid exposing the code in process arguments.
 - If the first non-interactive step includes `--client-secret`, the secret is remembered for the matching completion step.
-- If a profile already stores a confidential OAuth client, `direct auth login --code CODE --profile NAME` reuses the saved `client_id` and `client_secret`.
+- If a profile already stores a confidential OAuth client, `direct auth login --code CODE --profile NAME` reuses the saved `client_id` and `client_secret`. Re-logging into an existing profile requires `--force`.
 - `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
-- After a successful interactive login, Direct CLI asks whether to save the
-  access token and login to the current working directory `.env`; non-interactive
-  login flows do not prompt.
+- In a terminal, the interactive API login saves the selected API profile
+  directly to the current folder's `.env`. Headless flows never ask for save
+  confirmation; use `direct auth write --profile NAME` to bind the folder
+  explicitly.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -474,6 +523,44 @@ base `YANDEX_DIRECT_LOGIN`; this prevents mixing accounts. `direct auth status`
 without `--profile` reports the effective credential source; with `--profile` it
 reports that profile.
 
+**An unbound folder has no credentials (#904).** When credentials would come
+from the active profile fallback (priority 4) — e.g. a brand-new folder with
+no `.env` — the CLI no longer inherits them silently:
+
+- Non-interactive sessions (scripts, sub-processes): API commands fail with
+  `UsageError` and binding hints until the folder is bound. Bind a folder
+  without prompts via `direct auth write --profile <name>` — it writes the
+  profile's credentials to the cwd `.env` (merge, `0600`, token never
+  printed); `--profile` is required, nothing is bound implicitly.
+- Terminal sessions follow the same rule: an ordinary command never opens a
+  login dialog. Run `direct auth login api` to choose or
+  authorize a profile and bind it to this folder. A profile created through
+  the menu does not change the global active profile.
+- `direct auth status` in an unbound folder reports
+  `source=null`/`has_token=false` and notes the global profile
+  (`global_profile`/`global_login` in JSON) without presenting it as this
+  folder's credentials.
+- `--dry-run` needs no credentials and stays silent; `--sandbox` does not
+  bypass the gate — the sandbox authenticates under the same profile login.
+- Set `YANDEX_DIRECT_INHERIT_GLOBAL=1` to restore the former silent
+  inheritance for unattended workflows (auth status then labels it
+  `source=global-profile-inherited`).
+
+### Optional diagnostics output (#925)
+
+Optional output — data you did not ask for — is hidden by default and printed
+to stderr only, so stdout stays byte-identical for pipes and JSON parsing:
+
+| Env var | Effect |
+|---------|--------|
+| `DIRECT_SHOW_UNITS=1` | After each successful v5 API call, one stderr line with the API Units points: `API units: <spent>/<rest>/<daily limit>` (e.g. `API units: 10/20828/64000`), plus ` (used-login: <login>)` for agency accounts (`Units-Used-Login`). The v4 Live API returns no Units headers, so v4 commands (`direct balance`, …) stay silent under this switch |
+| `DIRECT_QUIET=0` | Master switch back to the legacy behaviour for optional output that existed before #925 (Units had none) |
+
+`DIRECT_SHOW_UNITS=1` works even with `DIRECT_QUIET=1`; an explicit
+`DIRECT_SHOW_UNITS=0` wins over `DIRECT_QUIET=0`. Safety output — inherited
+credential warnings (#909), sandbox notices, API warnings — is never
+suppressed. Limit errors already include Units in their text (#921).
+
 > **Tests follow the safe credential order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This prevents a developer machine with an active profile from silently hitting production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
 
 Install with `pip install direct-cli`, then run commands with `direct`.
@@ -1065,6 +1152,15 @@ direct dictionaries get-retargeting-goals --ids 19000000660,19000001592
 > more than one goal `Type` (e.g. `HOST` and `APPLICATION`) for similar names
 > — pick the entry with the `Type` your use case needs.
 
+> `retargeting get` returns each list's `Scope` (a default field):
+> `FOR_TARGETS_ONLY` / `FOR_TARGETS_AND_ADJUSTMENTS` /
+> `FOR_ADJUSTMENTS_ONLY`. There is no `--scope` flag: the WSDL declares
+> `Scope` only on `RetargetingListGetItem`, so the API assigns it
+> server-side. Verified live (#890): `retargeting get` returns
+> every documented scope class present in the account — an empty
+> adjustment-class section means the account has no such lists, not
+> server-side filtering.
+
 ```bash
 # Bids and modifiers
 direct bids get --campaign-ids 123 --fields CampaignId,AdGroupId,KeywordId,Bid
@@ -1076,6 +1172,10 @@ direct keywordbids set-auto --keyword-id 321 --target-traffic-volume 100 --incre
 direct bidmodifiers get --campaign-ids 123 --fields Id,CampaignId,AdGroupId,Level,Type
 direct bidmodifiers add --campaign-id 123 --type DEMOGRAPHICS_ADJUSTMENT --value 150 --gender GENDER_MALE --age AGE_25_34 --dry-run
 direct bidmodifiers add --campaign-id 123 --type MOBILE_ADJUSTMENT --value 120 --operating-system-type IOS --dry-run
+# RETARGETING_SEARCH_ADJUSTMENT is a live-only type (#871): the payload is
+# mirrored, but Yandex currently rejects its creation with 5005 on every
+# documented retargeting-list class (#890) — works once acceptance is enabled.
+direct bidmodifiers add --campaign-id 123 --type RETARGETING_SEARCH_ADJUSTMENT --retargeting-condition-id 12345 --value 120 --dry-run
 direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups