feat(project): accept a project ID in --project and other alias options (CLI-22)

[soustruh]

What was wrong

--project and the other options that name a registered project accepted only its alias. A user who knows a project by its ID had to find the alias first, although kbagent stores the ID of each registered project (project_id).

What changed

• A project ID works where these values take an alias: --project on every command (single and repeatable), project use, KBAGENT_PROJECT, sync clone --target, config clone --target-project, the project options of semantic-layer promote and diff, --stack on the auth commands, and the {project}, ?project=, {alias}, ?alias= and /auth/*?stack= parameters of kbagent serve.
• An alias wins. A registered alias 1234 keeps its meaning, and kbagent looks up the ID only when no alias matches. When that alias is also the ID of another registered project, stderr shows a warning that names the alias of the other project, also with --json.
• An ID that matches more than one registered project gives CONFIG_ERROR with the list of aliases and stacks. Exception: when all matches are on the same stack and exactly one has a session token, kbagent uses that alias.
• kbagent translates the ID once, before the command body runs. commands/_project_ref.py adds a Click parameter callback to each of these options when the root group is built, so services receive only aliases. project add, project create and lineage show are excluded, because their --project names a new alias or filters an offline file.
• Human output prints Project ID 4242 resolved to alias 'prod' to stderr. JSON output does not change, because targets and project_alias already name the alias.
• The not-found messages name the alias and say that these options also take a project ID.

Behavior changes

• project invite --from-csv: the project column follows the same rules (alias first, an ambiguous ID is an error). Before, a numeric value was always an ID, and the first matching project was used. The project_id column is still always an ID. One difference from --project: when a digits-only alias is also the ID of a different registered project, the row fails and names both, because an invite grants membership and a bulk run has no notice that a person reads first.
• project current reports an ambiguous KBAGENT_PROJECT in the new field env_error.

Limits

• kbagent serve does not translate request bodies.
• The query translation removes Starlette's cached query from the request (request._query_params), because FastAPI reads the query before the dependency changes it. tests/test_server_project_ref.py::test_query_param_project_ids_reach_service_as_aliases fails if a Starlette upgrade changes this.

Tests

• tests/test_project_ref.py walks the Click tree, checks the walk against a second one, and runs each command that has --project, and each entry of the alias-option tables, through the real root with a project ID. Each command must receive the alias, and the excluded commands must receive the ID. Another test requires each option whose flag contains project, alias or stack to be translated or listed with a reason.
• Unit tests cover the resolver rules, including the session-token cases and a 19-digit value. Other tests cover the env var, project use, project current, the CSV invite and REST.
• make check passes. The CLI also starts with Typer 0.24.2, which does not include typer._click.

Docs: gotchas.md (since vNEXT), commands-reference.md, keboola-expert.md, context.py, CLAUDE.md, CONTRIBUTING.md. No version bump, no changelog entry.

Fixes CLI-22

[linear-code]

CLI-22

[keboola-pr-reviewer-bot]

⚠️ Reviewer error — this is not a verdict. The PR reviewer could not complete this review, so no approval is implied. The failure has been logged for the operator.

reviewer could not complete: opencode exited 1: (no stderr — check the reviewer logs for the trace summary)

Retry with @keboola-pr-reviewer review once the underlying issue clears.

[soustruh]

@keboola-pr-reviewer review

[keboola-pr-reviewer-bot]

⚠️ Reviewer error — this is not a verdict. The PR reviewer could not complete this review, so no approval is implied. The failure has been logged for the operator.

reviewer could not complete: reviewer model call errored (subtype=success, api_status=400) after 1/18 turn(s).

Retry with @keboola-pr-reviewer review once the underlying issue clears.

[zajca]

Actionable findings from the automated review.

[zajca]

No actionable findings were found by the automated review.