fix(storage): write column descriptions where the MCP server reads them (#624)

[padak]

What

storage describe-column / describe-batch now write column descriptions as
KBC.description inside the table's native columnMetadata store, instead of as
flat KBC.column.{name}.description entries on the table's metadata.

Why

Two incompatible conventions never met:

	Key	Location
kbagent wrote	KBC.column.{name}.description	flat entry in table metadata
MCP server reads	KBC.description	inside columnMetadata[{name}]

The client/storage_tables.py docstring justified the flat convention with "Keboola
Storage API does not expose a user-writable column-metadata endpoint". That is not
correct. The same POST /v2/storage/tables/{id}/metadata kbagent already calls accepts
a columnsMetadata payload with provider: user; keboola/mcp-server's
StorageClient.table_metadata_update() does exactly that, and its read paths
(tools/storage/tools.py, tools/storage/search.py) resolve column descriptions only
from columnMetadata.

So every column description kbagent ever wrote was invisible to every AI client using
the Keboola MCP server — precisely the audience those descriptions are written for.

The failure was silent in both directions: storage table-detail read back
kbagent's own convention, so the descriptions were reported as correctly applied.

Changes

• client (client/storage_tables.py) — new set_table_column_metadata() posting a
  JSON {provider, columnsMetadata} payload. It sends JSON rather than form data
  because the nested per-column shape has no form-encoded equivalent; the table-level
  set_table_metadata() is untouched and still form-encoded. Entries carry the
  redundant columnName key, mirroring what the platform's own clients send.
• service — write (services/storage_service.py::describe_columns) — writes
  KBC.description per column through the new client method. describe_batch picks
  this up for free via its columns: section.
• service — read (services/storage_service.py::get_table_detail) — reads
  KBC.description from columnMetadata as the primary source, keeping the flat
  KBC.column.* keys as a fallback so descriptions written by an older kbagent stay
  visible here. When both carry a value, columnMetadata wins.
• line budget — storage_service.py is a grandfathered file that may not grow, so
  the repetitive five-branch per-column elif chain became a _COLUMN_META_FIELDS
  mapping. Adding a pass-through field is now a one-line data change, and the file
  stays at its 1733 ceiling.
• docs — corrected the incorrect claim in the client and service docstrings, the
  describe-column command help, AGENT_CONTEXT, storage-describe-workflow.md,
  commands-reference.md, and a rewritten gotchas.md entry tagged (since v0.87.1).

Migration

There is no bulk migration command. Re-running describe-column (or
describe-batch) on an affected table rewrites the description into the right place;
until then those tables stay invisible to MCP clients. The read fallback means nothing
disappears from kbagent's own output in the meantime.

A dedicated migration command was left out deliberately — it would be a new CLI surface
(with the full set of drift surfaces to update) for a one-shot operation that re-running
an existing command already performs. Happy to add one if you would rather have it.

Version

Bumped to 0.87.1 with a changelog entry. This changes where data is written and
carries a migration note, so shipping it without a changelog entry would leave users
unaware they need to re-run describe-column. Renumber freely if it should land under a
different version.

Testing

• make check green: lint, format, typecheck, skill-check, version-check,
  command-sync-check, changelog-check, error-codes, sentinel-guards, loc-check, and
  5703 tests passed.
• New service tests: KBC.description read from columnMetadata; columnMetadata
  beating the legacy flat key when both are present.
• Rewritten client tests: asserts the exact JSON columnsMetadata body and the
  application/json content type, plus the branch-scoped endpoint.
• Updated write-path tests assert the legacy set_table_metadata call no longer happens
  for columns; the pre-existing flat-key read tests now stand as legacy-fallback
  regression cover.
• Not verified against a live project — no live-project write access in this run. The
  endpoint contract is corroborated by the issue author's live reproduction on project
  9432 and by keboola/mcp-server's implementation.

Fixes #624

[padak]

Superseded by #631, which merged the same issue (#624) with a different — and better — write path.

#628 writes to columnMetadata via POST /v2/storage/tables/{id}/metadata with a columnsMetadata payload.
#631 writes through the native PUT /v2/storage/branch/{branch}/tables/{id}/definition endpoint — the one the web UI uses — and the backend mirrors the value into columnMetadata KBC.description on its own.

Two things #631 gets that this approach cannot:

1. isDescriptionSystemManaged: false, which is what stops the next component run's Output Mapping from overwriting a hand-authored description (DMD-1662). The metadata POST has no equivalent.
2. The mirroring only runs one way. The merged gotchas entry records it explicitly: a POST .../metadata write never reaches the native field. So this PR's descriptions would be visible to the MCP server but still absent from the native definition — and from the Snowflake COMMENT / BigQuery column description.

Merging this on top of #631 would therefore regress the fix rather than extend it. The branch is also DIRTY against main and carries a pyproject/plugin.json/uv.lock version bump that conflicts with the 0.88.0 renumber in #638.

Closing as superseded. The analysis here — in particular that columnsMetadata with provider: user is accepted, contradicting the old client/storage_tables.py docstring — is what pointed at the native endpoint in the first place.