keboola · padak · May 6, 2026 · May 3, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -195,7 +195,7 @@ All three inherit from `BaseHttpClient` (`http_base.py`) which provides shared r
 
 11. **Error accumulation**: multi-project operations collect per-project errors without stopping. One project failing doesn't block others (see `lineage_service.py`, `org_service.py`).
 
-12. **Manage token security**: never persisted, never passed as CLI argument, never logged. Only via `KBC_MANAGE_API_TOKEN` env var or interactive hidden prompt.
+12. **Manage token security**: never persisted, never passed as CLI argument, never logged. Default-deny since 0.28.0: only via interactive hidden prompt; the `KBC_MANAGE_API_TOKEN` env var is **ignored** unless the top-level `--allow-env-manage-token` flag is passed. Default-deny closes the AI-exfiltration risk where any subprocess (including the AI agent itself) inherits the manage token via env. CI/CD callers must opt in explicitly.
 
 13. **Idempotency**: `org setup` skips already-registered projects by matching `project_id`. Safe to re-run.
 
@@ -251,7 +251,7 @@ plugins/kbagent/
 > "Plugin synchronization map" for the full list.
 
 ```
-# Global options: --json, --verbose, --no-color, --config-dir, --hint client|service, --deny-writes, --deny-destructive
+# Global options: --json, --verbose, --no-color, --config-dir, --hint client|service, --deny-writes, --deny-destructive, --allow-env-manage-token
 
 kbagent project add --project NAME --url URL --token TOKEN
 kbagent project list

diff --git a/README.md b/README.md
@@ -102,14 +102,22 @@ kbagent project add --project prod --url https://connection.keboola.com --token
 
 **Many projects by ID** — you have a Manage API or Personal Access Token + the project IDs:
 ```bash
+# Interactive: kbagent will prompt for the Manage API token (default since v0.28.0).
+kbagent org setup --project-ids 901,9621,10539 --url https://connection.keboola.com --yes
+
+# CI / non-interactive: opt in to env-var resolution with --allow-env-manage-token.
 KBC_MANAGE_API_TOKEN=your-manage-or-personal-token \
-  kbagent org setup --project-ids 901,9621,10539 --url https://connection.keboola.com --yes
+  kbagent --allow-env-manage-token org setup --project-ids 901,9621,10539 --url https://connection.keboola.com --yes
 ```
 
 **Whole organization** — you are org admin:
 ```bash
+# Interactive (default since v0.28.0): kbagent prompts for the Manage API token.
+kbagent org setup --org-id 123 --url https://connection.keboola.com --yes
+
+# CI / non-interactive:
 KBC_MANAGE_API_TOKEN=your-org-admin-manage-token \
-  kbagent org setup --org-id 123 --url https://connection.keboola.com --yes
+  kbagent --allow-env-manage-token org setup --org-id 123 --url https://connection.keboola.com --yes
 ```
 
 Run `kbagent doctor` to verify setup (token validity, CLI version, MCP server, Claude Code plugin install).

diff --git a/docs/TUTORIAL.md b/docs/TUTORIAL.md
@@ -102,12 +102,19 @@ use `org setup --project-ids`. kbagent creates a Storage API token in
 each listed project and registers them all locally, in parallel.
 
 ```bash
-export KBC_MANAGE_API_TOKEN=YOUR_MANAGE_OR_PAT_TOKEN
-
+# Interactive (default since v0.28.0): kbagent prompts for the Manage API
+# token on stdin. No env var, no shell history.
 kbagent org setup \
   --project-ids 901,9621,10539 \
   --url https://connection.keboola.com \
   --dry-run                           # always dry-run first
+
+# CI / non-interactive: opt in to env-var resolution.
+export KBC_MANAGE_API_TOKEN=YOUR_MANAGE_OR_PAT_TOKEN
+kbagent --allow-env-manage-token org setup \
+  --project-ids 901,9621,10539 \
+  --url https://connection.keboola.com \
+  --dry-run
 ```
 
 The dry-run prints what would happen (create token + register alias
@@ -132,10 +139,14 @@ Flags worth knowing:
 The command is **idempotent**: running it again skips projects that
 are already registered. Safe to re-run after adding new project IDs.
 
-**Security note**: `KBC_MANAGE_API_TOKEN` is read only from env or
-from an interactive hidden prompt. kbagent never accepts it as a CLI
-argument (`--token xxx`) -- that would leak into shell history and
-process listings.
+**Security note (since v0.28.0)**: `KBC_MANAGE_API_TOKEN` is **ignored
+by default** -- the env var is read only when the top-level
+`--allow-env-manage-token` flag is passed. Without the flag, kbagent
+prompts on stdin (hidden input). kbagent never accepts the token as a
+CLI argument (`--token xxx`) -- that would leak into shell history and
+process listings. The default-deny closes an AI-exfiltration risk where
+any subprocess running as the same user (including the AI agent itself)
+inherits env vars.
 
 ---
 
@@ -145,12 +156,18 @@ If you are an org admin with a Manage API token, register **every**
 project in an organization in one shot:
 
 ```bash
-export KBC_MANAGE_API_TOKEN=YOUR_ORG_ADMIN_MANAGE_TOKEN
-
+# Interactive (default since v0.28.0):
 kbagent org setup \
   --org-id 123 \
   --url https://connection.keboola.com \
   --dry-run
+
+# CI / non-interactive:
+export KBC_MANAGE_API_TOKEN=YOUR_ORG_ADMIN_MANAGE_TOKEN
+kbagent --allow-env-manage-token org setup \
+  --org-id 123 \
+  --url https://connection.keboola.com \
+  --dry-run
 ```
 
 The dry-run reports how many projects will be registered and the
@@ -859,7 +876,8 @@ kbagent --json data-app create \
 deploy. To retrieve it:
 
 ```bash
-# Requires KBC_MANAGE_API_TOKEN in env (org-scoped Manage API token).
+# Manage API token: interactive prompt by default (since v0.28.0). For CI,
+# add `--allow-env-manage-token` and set KBC_MANAGE_API_TOKEN in env.
 kbagent --json data-app password \
   --project prod --app-id 12345678 \
   | jq -r '.data.password'
@@ -949,7 +967,8 @@ shapes, and the `--hint client|service` code-generation contract, see
 | `kbagent: command not found` after `uv tool install` | Ensure `~/.local/bin` (or uv's tool dir) is on your PATH. `uv tool update-shell` can help. |
 | `kbagent doctor` reports `warn` for plugin | Run the two `/plugin` commands shown in the warning, from inside Claude Code. |
 | Plugin version != CLI version | In Claude Code: `/plugin update kbagent`. |
-| `org setup` fails with `401 Unauthorized` | Your `KBC_MANAGE_API_TOKEN` is wrong for this stack or role. Manage tokens are stack-specific and require the right scope. |
+| `org setup` exits 2 with `Warning: KBC_MANAGE_API_TOKEN found in environment but ignored` | Default-deny since v0.28.0 -- pass `--allow-env-manage-token` (top-level flag) to opt in to env resolution, or run interactively to use the prompt. |
+| `org setup` fails with `401 Unauthorized` | Your manage token is wrong for this stack or role. Manage tokens are stack-specific and require the right scope. |
 | `org setup --org-id` fails with `403` | You are not an org admin. Use `--project-ids` with a Personal Access Token instead (works for any project member). |
 | Changes from `kbagent config update` do not show in UI | You are on a dev branch. Run `kbagent branch list` and `kbagent project current` to verify the active branch; changes in a dev branch merge to production only via the UI merge step (`kbagent branch merge` returns the merge URL). |
 | The specialist subagent does not spawn when I type `/keboola X` | Plugin is not installed or is outdated. Run `kbagent doctor` and follow the reported commands. |

diff --git a/docs/e2e-scenarios.md b/docs/e2e-scenarios.md
@@ -211,8 +211,8 @@ Skipped if `keboola-mcp-server` is not installed.
 
 | Command | Reason |
 |---------|--------|
-| `project refresh` | Requires Manage API token (`KBC_MANAGE_API_TOKEN`) |
-| `org setup` | Requires Manage API token + destructive (registers projects in org) |
+| `project refresh` | Requires Manage API token (interactive prompt by default since v0.28.0; `--allow-env-manage-token` + `KBC_MANAGE_API_TOKEN` for non-interactive runners) |
+| `org setup` | Requires Manage API token (same prompt-or-flag as above) + destructive (registers projects in org) |
 | `sharing share/unshare` | Requires org-level permissions or second project |
 | `sharing link/unlink` | Requires shared bucket from another project |
 | `permissions set/reset` | Interactive random-code confirmation blocks automated testing |

diff --git a/plugins/kbagent/agents/keboola-expert.md b/plugins/kbagent/agents/keboola-expert.md
@@ -64,8 +64,12 @@ a critical failure.
    needed for the current task (e.g. `flow update` needs 0.22.0+,
    `schedule find` needs 0.23.0+, `config set-default-bucket` needs
    0.26.0+, `data-app create / deploy / start / stop / delete / password`
+<<<<<<< HEAD
    need 0.27.0+, `config update` script[] auto-normalize against #245
    trap needs 0.28.0+, `storage swap-tables` needs 0.28.0+,
+   env-var manage-token auth for `org setup` / `project refresh` /
+   `data-app password` needs 0.28.0+ with `--allow-env-manage-token`
+   (the env var is default-deny on 0.28.0+),
    `storage retype` is a future composite), you
    MUST refuse the task and return a handoff message to the parent:
    `"Cannot proceed safely on kbagent <version>. Missing: <commands>.
@@ -106,7 +110,7 @@ a critical failure.
 | Roll out a new code or config version on a data app | `kbagent data-app deploy --project P --app-id N --wait` (0.27.0+) -- always sends the §9 trio | `kbagent --hint client data-app deploy ...` to inspect the generated `patch_app(desired_state=, config_version=, restart_if_running=True)` call | `tool call update_config` then `tool call run_component` (data apps are not jobs -- the queue runner does not deploy them) |
 | Wake an auto-suspended data app | `kbagent data-app start --project P --app-id N` (0.27.0+) -- does NOT bump configVersion | hitting the app's URL (auto-restart triggers a 30-60s cold boot) | `kbagent data-app deploy` (overkill -- bumps the deployed configVersion unnecessarily) |
 | Pause a running data app | `kbagent data-app stop --project P --app-id N` (0.27.0+) | -- | `kbagent data-app delete` (irreversible; cascades to Storage config) |
-| Read the simpleAuth password for a password-gated app | `kbagent data-app password --project P --app-id N` (0.27.0+) -- requires `KBC_MANAGE_API_TOKEN` | -- | trying to "rotate" the password (not supported by the API; delete + recreate to mint a new one) |
+| Read the simpleAuth password for a password-gated app | `kbagent data-app password --project P --app-id N` (0.27.0+) -- needs Manage API token (interactive prompt by default; `--allow-env-manage-token` + `KBC_MANAGE_API_TOKEN` for CI on 0.28.0+) | -- | trying to "rotate" the password (not supported by the API; delete + recreate to mint a new one) |
 | Tear down a data app | `kbagent data-app delete --project P --app-id N` (0.27.0+) -- cascades to Storage config; URL retired | -- | manually `tool call delete_config keboola.data-apps` while leaving the deployment record orphaned |
 
 If the table does not cover the user's task, **ask clarifying
@@ -273,6 +277,20 @@ success, not a failure.
   `bigquery_path` will be dataset-qualified only -- if the user needs a
   fully-qualified GCP path, ask them for the project name explicitly.
 
+- **Manage-token env-var is opt-in (since 0.28.0)**.
+  `KBC_MANAGE_API_TOKEN` is no longer auto-resolved for `org setup`,
+  `project refresh`, or `data-app password`. Default behaviour: emit a
+  warning, ignore the env var, fall through to a TTY hidden-input prompt;
+  exit 2 with no TTY. To opt in (CI/CD), pass the top-level flag:
+  `kbagent --allow-env-manage-token --json org setup ...`. The flag is
+  session-only -- not persisted, no env-var equivalent. Default-deny
+  closes the AI-exfiltration risk where a subprocess running as the same
+  user (including the agent itself) inherits the manage token. If you
+  see `Warning: KBC_MANAGE_API_TOKEN found in environment but ignored`
+  in stderr, that is the expected default; tell the user to add
+  `--allow-env-manage-token` to their invocation, never strip the
+  warning by suppressing stderr.
+
 ---
 
 ## 4. WORKFLOWS (reference playbooks)

diff --git a/plugins/kbagent/skills/kbagent/SKILL.md b/plugins/kbagent/skills/kbagent/SKILL.md
@@ -273,8 +273,10 @@ Then add projects:
 kbagent --json project add --project prod --url https://connection.keboola.com --token YOUR_TOKEN
 
 # Or bulk-onboard from organization (org admin)
-KBC_MANAGE_API_TOKEN=xxx kbagent --json org setup --org-id 123 --url https://connection.keboola.com --yes
+# Manage token: interactive prompt by default; for CI add --allow-env-manage-token
+# alongside KBC_MANAGE_API_TOKEN (required since v0.28.0).
+KBC_MANAGE_API_TOKEN=xxx kbagent --allow-env-manage-token --json org setup --org-id 123 --url https://connection.keboola.com --yes
 
 # Or onboard specific projects (any project member, uses Personal Access Token)
-KBC_MANAGE_API_TOKEN=xxx kbagent --json org setup --project-ids 901,9621,10539 --url https://connection.keboola.com --yes
+KBC_MANAGE_API_TOKEN=xxx kbagent --allow-env-manage-token --json org setup --project-ids 901,9621,10539 --url https://connection.keboola.com --yes
 ```
diff --git a/plugins/kbagent/skills/kbagent/references/commands-reference.md b/plugins/kbagent/skills/kbagent/references/commands-reference.md
@@ -24,11 +24,12 @@ All commands support `--json` for structured output. Multi-project flags (`--pro
 ## Permission flags (top-level, session-only)
 - `--deny-writes` -- block all write/destructive/admin operations for this single invocation. Merges with any persisted permission policy; never written to config.json. Exit code 6 (PERMISSION_DENIED) on blocked operations
 - `--deny-destructive` -- block only destructive operations (delete-table, delete-bucket, terminate-job, etc.) for this invocation. Pure-write ops like create-table stay allowed. Use this when you want to keep build-up capabilities but lock out tear-downs
-- Both flags compose: `kbagent --deny-writes --deny-destructive ...` is the safest read-only run
+- `--allow-env-manage-token` -- opt in to reading `KBC_MANAGE_API_TOKEN` from env (default-deny since v0.28.0). Without it the env var is ignored and an interactive hidden prompt is required for `org setup` / `project refresh` / `data-app password`. Closes the AI-exfiltration risk where any subprocess inherits the manage token via env. Session-only; not persisted; no env-var equivalent (intentional, would re-create the hole). REPL forwards this flag to nested invocations the same way it forwards the deny-* flags
+- All three flags compose: `kbagent --deny-writes --deny-destructive --allow-env-manage-token ...` is the safest CI-friendly invocation
 
 ## Organization
-- `org setup --org-id ID --url URL [--dry-run] [--yes]` -- bulk-onboard all projects from an org (org admin, needs `KBC_MANAGE_API_TOKEN`)
-- `org setup --project-ids 1,2,3 --url URL [--dry-run] [--yes]` -- onboard specific projects by ID (any project member, works with Personal Access Token via `KBC_MANAGE_API_TOKEN`)
+- `org setup --org-id ID --url URL [--dry-run] [--yes]` -- bulk-onboard all projects from an org (org admin; manage token via interactive prompt by default, or `--allow-env-manage-token` + `KBC_MANAGE_API_TOKEN` for CI on 0.28.0+)
+- `org setup --project-ids 1,2,3 --url URL [--dry-run] [--yes]` -- onboard specific projects by ID (any project member; manage token / Personal Access Token via interactive prompt by default, or `--allow-env-manage-token` + `KBC_MANAGE_API_TOKEN` for CI on 0.28.0+)
 
 ## Component Discovery
 - `component list [--project NAME] [--type TYPE] [--query "text"]` -- list/search components (AI-powered with `--query`)
@@ -126,7 +127,7 @@ Lifecycle for `keboola.data-apps`. Combines Storage API (config body, git block,
 - `data-app start --project NAME --app-id ID [--wait] [--timeout SECONDS]` -- wake an auto-suspended app at the currently-pinned version. Distinct from deploy: does NOT bump configVersion.
 - `data-app stop --project NAME --app-id ID [--wait] [--timeout SECONDS]` -- stop a running app (URL and Storage config preserved).
 - `data-app delete --project NAME --app-id ID [--yes]` -- destructive, cascades to Storage config; URL retired permanently.
-- `data-app password --project NAME --app-id ID` -- read the simpleAuth password. Requires `KBC_MANAGE_API_TOKEN`. Auto-generated, not rotatable -- delete + recreate to mint a new one.
+- `data-app password --project NAME --app-id ID` -- read the simpleAuth password. Manage token via interactive prompt by default, or `--allow-env-manage-token` + `KBC_MANAGE_API_TOKEN` for CI on 0.28.0+. Auto-generated, not rotatable -- delete + recreate to mint a new one.
 
 ## MCP Tools
 - `tool list [--project NAME] [--branch ID]` -- list available MCP tools (multi_project annotation)
@@ -187,7 +188,7 @@ Lifecycle for `keboola.data-apps`. Combines Storage API (config body, git block,
 |----------|---------|
 | `KBC_TOKEN` | Fallback for `--token` |
 | `KBC_STORAGE_API_URL` | Default stack URL |
-| `KBC_MANAGE_API_TOKEN` | Manage API token (org setup) |
+| `KBC_MANAGE_API_TOKEN` | Manage API token (org setup, project refresh, data-app password). Default-DENY since 0.28.0: requires top-level `--allow-env-manage-token` to opt in, otherwise ignored with a warning. |
 | `KBAGENT_CONFIG_DIR` | Override config directory |
 
 ## Exit Codes

diff --git a/plugins/kbagent/skills/kbagent/references/data-app-workflow.md b/plugins/kbagent/skills/kbagent/references/data-app-workflow.md
@@ -58,7 +58,9 @@ with:
 
 ```bash
 kbagent data-app password --project prod --app-id <ID>
-# Requires KBC_MANAGE_API_TOKEN in addition to the project's Storage token.
+# Manage token: interactive prompt by default (since v0.28.0); for CI add
+# --allow-env-manage-token alongside KBC_MANAGE_API_TOKEN. Storage token
+# is read from .kbagent/config.json as usual.
 ```
 
 The simpleAuth password CANNOT be rotated (writeup §11.2). To change it,