refactor: remove deprecated --hint flag and hints/ subsystem (0.55.0)

[padak]

Summary

Completely removes the deprecated --hint client|service global flag and its entire hints/ code-generation subsystem. The flag was deprecated since 0.45.0 in favour of the kbagent serve REST API, which covers every command (not just the ~45 that had hint definitions). Passing --hint now errors as an unknown option.

Bumps the version to 0.55.0 with a changelog entry (rebased on top of the 0.54.0 encrypt security fix already on main).

What was removed

Code

• src/keboola_agent_cli/hints/ — the whole package: registry, renderer, models, and all 21 definitions/*.py
• should_hint / emit_hint / _resolve_hint_stack_url helpers in commands/_helpers.py, plus the hint branch in check_cli_permission
• ~146 if should_hint(ctx): emit_hint(...) guard blocks at the head of every command across 20 command modules
• the --hint option + hint_mode plumbing in cli.py

Docs / agent surfaces

• deleted docs/hint-mode.md and plugins/kbagent/skills/kbagent/references/programming-with-cli.md
• scrubbed AGENT_CONTEXT (kbagent context), SKILL.md, keboola-expert.md, kbagent-pr-reviewer.md, gotchas.md, commands-reference.md, storage-types-workflow.md, README.md, CONTRIBUTING.md, docs/TUTORIAL.md, and CLAUDE.md

Tests

• deleted tests/test_hints.py and removed every --hint test class across test_cli.py, test_data_app_cli.py, test_data_app_secrets_cli.py, test_member_cli.py, test_e2e_lineage_deep.py

Explicitly left untouched

• --no-hint-next (data-app secrets), --role-hint / role_hint (dev-portal), and error-message hints — unrelated uses of the word "hint"
• Historical changelog entries that mention --hint — they record what shipped in those releases (only a new 0.55.0 entry was added)

Migration

Run kbagent serve and call the equivalent REST endpoint instead of generating a one-off Python snippet.

Verification

• ruff check + ruff format --check clean (src + tests)
• ty check clean
• make changelog-check — all 48 stable releases have entries
• version consistency (pyproject / plugin.json / marketplace.json / uv.lock all 0.55.0)
• full non-e2e suite: 3793 passed, 26 skipped
• smoke: kbagent --hint client ... → No such option: --hint; kbagent context carries no --hint reference

[padak]

Review of #384 — refactor: remove deprecated --hint flag and hints/ subsystem (0.55.0)

Generated by kbagent-pr-reviewer subagent. Verdict and findings below
are advisory; the human author retains every veto. CI-coverable issues
(lint, format, tests) are confirmed via make check, not duplicated here.

Summary

This PR is a clean removal of the --hint client|service global flag and its entire hints/ code-generation subsystem (~9 400 lines deleted, 44 added), deprecated since v0.45.0 in favour of the kbagent serve REST API. The removal is thorough: all 21 definitions/*.py files, every if should_hint(ctx): emit_hint(...) guard across 20 command modules, the Typer option plumbing in cli.py, docs/hint-mode.md, plugins/kbagent/skills/kbagent/references/programming-with-cli.md, and tests/test_hints.py are gone. Every relevant agent/plugin/doc surface (AGENT_CONTEXT, SKILL.md, keboola-expert.md, kbagent-pr-reviewer.md, gotchas.md, commands-reference.md, storage-types-workflow.md, README.md, CONTRIBUTING.md, TUTORIAL.md, CLAUDE.md) has been updated. As a bonus, this PR also fixes a pre-existing gap: kbagent permissions list|show|set|reset|check was missing from the CLAUDE.md ## All CLI Commands block and the Project Structure section. make check passes (3 796 passed, 8 skipped), make skill-check passes, make version-check passes.

Verdict: APPROVE. There are no blocking findings. Two non-blocking findings and two nits are noted below.

Verdict

• Verdict: APPROVE
• Blocking findings: 0
• Non-blocking findings: 2
• Nits: 2

Blocking findings

(none)

Non-blocking findings

[NB-1] docs/axi-mapping-report.md:26,81,660,662,775 — tracked research doc retains stale --hint references

docs/axi-mapping-report.md is a git-tracked file (added in e6e11dd) that still references --hint codegen, --hint client|service code generation, and even proposes a --hint toon extension. After 0.55.0, those lines describe a flag that no longer exists. The file is clearly a historical research artefact (dated 2026-04-20, from an AXI mapping exercise) and does not affect runtime or AI-agent behaviour, but it will confuse contributors who read it expecting current facts.

Suggested fix: add a one-line front-matter notice > **Historical research document (2026-04-20). --hint was removed in v0.55.0; references below are stale.** or move the file to docs/archive/ so it falls outside normal doc-search results.

[NB-2] pyproject.toml:3 / commit title — refactor: prefix understates a breaking change

Per CONTRIBUTING.md: "refactor: for no-behavior-change". Removing a previously-valid global flag (--hint) is a user-visible breaking change: existing CI pipelines or shell scripts that call kbagent --hint client ... will now exit with No such option: --hint instead of the deprecation warning. Conventional commits do not define a standard remove: prefix, but feat!: (breaking feat) or chore(remove-hint): would communicate the nature of the change more accurately.

This is a NIT-adjacent classification (CONTRIBUTING.md does not explicitly prohibit this use of refactor:), but given that the deprecation window was 10 minor releases and the PR description is thorough, downstream consumers should be able to locate this in changelog.py. No action strictly required before merge, but worth noting for release-note readers.

Nits

• [NIT-1] CLAUDE.md (entire diff) — The diff includes a substantial rewrite of the Project Structure block (adding seven HTTP client entries, collapsing the per-file test list, adding a server/ and sync/ layer description) that goes well beyond the --hint removal scope stated in the PR description. The changes appear correct and are improvements, but they were not mentioned in "What was removed / Explicitly left untouched" sections. A follow-up reader bisecting blame for a CLAUDE.md line will land in this PR unexpectedly. Consider adding a bullet to the PR description: "Bonus: updated CLAUDE.md Project Structure to reflect current seven-client architecture and permissions command block."

• [NIT-2] src/keboola_agent_cli/commands/context.py renumbering — After removing item 10 ("Python code generation with --hint"), items 11–N are renumbered to 10–N-1. The renumbering is correct, but any external bookmark or reference that cites "section 11 (Parquet export)" will now point to a section numbered 10. The section headings use only a number with no stable anchor slug, so this is a cosmetic concern only.

Verification log

• gh pr view 384 --json ... → 76 files, +44/-9419, state=OPEN, conventional title refactor: remove deprecated --hint flag and hints/ subsystem (0.55.0) ✓
• git rev-parse --abbrev-ref HEAD in worktree → claude/dreamy-roentgen-d2edc9 matches <branch> input ✓
• grep typer/click/httpx in services from diff → empty ✓ (no layer violation)
• grep bare except / print() / raw error_code strings / magic numbers in diff → all empty ✓
• ls src/keboola_agent_cli/hints/ → No such file or directory ✓ (directory deleted)
• grep -rn 'should_hint|emit_hint|hint_mode|HintMode|CommandHint|HintRegistry|from.*hints' src/keboola_agent_cli/commands/ → empty ✓
• grep -rn '\-\-hint client|\-\-hint service|HintMode|hints/definitions' . (excl. changelog.py + axi-mapping-report.md) → empty ✓
• grep '\-\-hint\b' plugins/ docs/ src/ tests/ (excl. no-hint-next, role-hint, changelog, axi-mapping) → empty ✓ (all hint references cleaned up)
• grep 'programming-with-cli|hint-mode.md' . (excl. changelog.py) → empty ✓ (no dangling links to deleted files)
• make check → 3796 passed, 8 skipped, 119 deselected, 16 warnings in 81.31s ✓
• make skill-check → SKILL.md is up-to-date ✓
• make version-check → version is in sync (plugin.json, marketplace.json, uv.lock) ✓
• pyproject.toml version → 0.55.0 ✓
• plugins/kbagent/.claude-plugin/plugin.json version → 0.55.0 ✓
• src/keboola_agent_cli/changelog.py → "0.55.0" entry present ✓
• context.py AGENT_CONTEXT → --hint MODE line removed, no hint references remain ✓
• CLAUDE.md ## All CLI Commands global options → --hint client|service removed ✓
• keboola-expert.md Rule 4 / Rule 5 → old --hint client fallback replaced by kbagent serve REST API ✓
• keboola-expert.md Rule 6 VERSION GATE → old exhaustive per-command list replaced by "use §2/§3 inline (X.Y.Z+) tags" approach; key version gates (data-app app_id 0.33.0+, stream 0.50.0+, agent 0.44.0+, etc.) verified to exist in §2 matrix entries inline ✓
• gotchas.md → two --hint sections (deprecated since 0.45.0 and removal note) deleted ✓
• commands-reference.md → --hint client|service global-option row deleted ✓
• CONTRIBUTING.md checklist → deprecated ~~**--hint support**~~ line removed ✓
• kbagent-pr-reviewer.md → hints/definitions/*.py row removed from plugin synchronization table; downstream-search grep updated ✓
• data_app_service.py comment updates → three docstring references to --hint service snippet users reworded to kbagent serve REST API ✓
• config_store.py CLAUDE_CONFIG_WARNING → warning text updated to reference kbagent serve ✓
• docs/axi-mapping-report.md → still contains stale --hint references (NOT changed in this PR; flagged as NB-1) — file is gitignore-exempt (tracked), research-only context, no runtime impact
• Behavior reproduction: kbagent --hint client ... → No such option: --hint (confirmed by PR author smoke test in description; independent reproduction not attempted — no credentials needed for this negative test, and the Typer option was clearly removed from cli.py:229-235 in the diff) ✓

Open questions for the author

(none)