feat(storage): show column descriptions in table-detail human output

[padak]

Why

0.88.0 (#624) was specifically about making column descriptions visible everywhere: the write moved to the native PUT .../tables/{id}/definition endpoint so the text reaches the Keboola UI, the MCP server's get_tables, and the Snowflake COMMENT / BigQuery column description. --json carried it too, on column_details[].description.

kbagent's own human-mode Columns table was the one surface still showing nothing. So this sequence — the obvious way to check your own work — was the one way that did not work:

kbagent storage describe-column --project P --table-id T --column amount_usd="Gross order value in USD"
kbagent storage table-detail   --project P --table-id T     # ...no descriptions anywhere

The column has never existed: git log -S "Description" -- src/keboola_agent_cli/commands/_storage_table_detail.py is empty.

What changed

A Description column on that Rich table, populated from col.get("description").

Before / after (100-column terminal, all three description tiers):

┏━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name       ┃ Type      ┃ Nullable ┃ Description                                                  ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ order_id   │ INTEGER   │          │                                                              │
│ created_at │ TIMESTAMP │          │ Order creation time (UTC).                                   │
│ amount_usd │ NUMERIC   │ yes      │ Gross order value in USD, excluding tax and shipping;        │
│            │           │          │ refunds appear as separate negative rows.                    │
│ notes      │           │          │ Free-text note [see runbook]                                 │
└────────────┴───────────┴──────────┴──────────────────────────────────────────────────────────────┘

Three decisions worth stating, since the issue left them open:

Hidden when empty. The column is added only when at least one column actually has a description — the same "no data, no chrome" rule render_table_layout already follows for the partitioning lines. An undocumented table's output is byte-identical to before. This is a real emptiness test, not a test for "": services/_table_detail._column_details sets description only when one of the three tiers resolved.

Wrapped and capped, never truncated. Verifying what you just wrote is the whole point, so an ellipsis would defeat it. overflow="fold" breaks even a long unbroken token instead of hiding its tail, and max_width=60 stops a wide terminal from stretching the cell across the screen while Rich shrinks it further on a narrow one. Both directions are asserted.

Escaped. Descriptions are user-authored free text and Rich renders str cells as markup — [note] would vanish and an unbalanced tag can raise. escape() matches what the display_name line above already does.

--json is untouched. All three tiers the service already resolves (native definition → columnMetadata KBC.description → legacy flat KBC.column.*) render, and the legacy-key migration warning still prints below the table.

Tests

Five tests in TestColumnDescriptions, alongside the existing human-render tests for that module. Each was verified to fail against the matching mutation of the production code — drop max_width → the sprawl test dies; drop escape() → the markup test dies; force show_description = True → the empty-column test dies.

One trap worth flagging for future readers, and called out in the test docstring: tests/conftest.py has an autouse fixture pinning COLUMNS=200 for every test (added after a host-dependent width silently cut a value in half on Windows CI). A "fits in 80 columns" assertion that does not override it asserts nothing at all — the first draft of that test passed for the wrong reason.

Version — no bump

Deliberately not bumped: v0.88.0 shipped earlier today and the next number is the release step's call, so this PR stays on 0.88.0 and gets renumbered at release time.

Two consequences worth knowing about, both handled:

• No changelog key. A 0.88.1 entry with no matching release fails make changelog-check, so the entry was removed. Paste-ready text for whoever cuts the release:

  UX: kbagent storage table-detail now shows column descriptions in its human-mode Columns table. 0.88.0 (storage describe-column writes column descriptions where the MCP server never reads them #624) made a description visible in the Keboola UI, in the MCP server's get_tables and in the warehouse's own COMMENT, and --json has carried it on column_details[].description all along -- kbagent's own terminal output was the one surface still showing nothing, so storage describe-column followed by storage table-detail (the obvious way to check your own work) was the one way that did not work. The column appears only when at least one column actually has a description, the same rule the partitioning block follows, so an undocumented table's output is byte-identical to before. Long text wraps rather than truncating -- verifying what you just wrote is the point -- and the cell is width-capped so a wide terminal does not stretch it across the screen. --json is unchanged.

• No (since vX.Y.Z) markers. make version-gate-check rejects a gate naming a version with no changelog entry — an agent reading a gate for a version that never ships refuses a command the user actually has. The three doc notes (CLAUDE.md, references/commands-reference.md, references/gotchas.md) therefore anchor on 0.88.0, a real release, and state what that version does not do: "On 0.88.0 it did NOT — there the descriptions were readable only through --json, so a blank-looking terminal table on that version does not mean the write failed." True whatever number this ships under. gotchas.md carries an inline release-step reminder to tag it once the version is known.

make check is green end to end: lint, format, SKILL.md, version sync, version gates, command sync, changelog completeness, error codes, sentinel guards, LOC budget, 5862 tests.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.