[keegandonley]

What & why

Adds required machinery so that app-builder-cli can wrap this tool and call into it using provided oauth credentials

Jira: https://kizen.atlassian.net/browse/KZN-19166

Checklist

• Tests are green locally (uv run pytest), and I ran the wheel tier too if I touched packaging (pyproject.toml, docs/specs/, anything under src/kizen_builder/docs/).
• CHANGELOG.md is updated under [Unreleased] if a user of the CLI would notice this change. Internal refactors don't need an entry.
• No customer or test-environment names anywhere — code, tests, docs, commit messages. Neutral placeholders only.
• If this adds a new file under src/kizen_builder/docs/, it's covered by a package-data glob in pyproject.toml (tests/test_docs_packaging.py enforces this, but check before pushing).
• If this adds a new surface or cross-cutting doc topic, it's listed in specs/README.md / reference.md's router table (or GUIDE_TOPICS for cross-cutting topics).

[Copilot]

🔵 Needs a closer look

Human validation is needed to confirm that OAuth 401 responses always precede write execution, making automatic write replay safe.

No open issues 🎉

What changed in this PR

Adds helper-based OAuth authentication so app-builder-cli can invoke kizen without a local credential profile, while preserving directory identity checks.

Changes:

• Adds environment-based configuration, cached Bearer authentication, and one refresh-and-retry on a 401 response.
• Guards credential and installation management commands when app-builder owns the environment.
• Adds regression tests and documents the wrapper integration contract.

File	Description
tests/​test_auth_helper.py	Tests helper configuration, authentication, failures, retries, and command guards.
src/​kizen_builder/​docs/​operating.md	Documents helper-mode requirements and behavior.
src/​kizen_builder/​config.py	Adds authentication types and helper-mode configuration resolution.
src/​kizen_builder/​cli/​upgrade.py	Prevents managed upgrades while preserving --check behavior.
src/​kizen_builder/​cli/​init.py	Guards managed credentials and adopts the API-key authentication type.
src/​kizen_builder/​cli/​envs.py	Blocks profile listing in helper mode.
src/​kizen_builder/​auth_helper.py	Executes the helper, caches tokens, and refreshes on 401 responses.
src/​kizen_builder/​api/​client.py	Supports both authentication modes and helper-specific error guidance.
README.md	Clarifies that init does not read an environment variable for its base URL.
docs/​ARCHITECTURE.md	Describes the updated authentication flow.
CONTRIBUTING.md	Adds the helper module to the source map.
CHANGELOG.md	Records the new app-builder integration.

_{Review effort: Balanced}