docs(plugin): close the reference gaps a 0.88.0 audit found

[padak]

Why

After shipping 0.88.0 I audited every changelog bullet in that release against the agent-facing reference surfaces — commands-reference.md, gotchas.md, the *-workflow.md set, and keboola-expert.md. Coverage was good: 14 of 15 bullets were documented in at least one surface, most in three or four.

One was documented nowhere, and two entries were accurate but incomplete.

The real gap: #636

data-app validate-repo's two setup.sh rules now match comment-stripped code. No reference file mentioned it. The existing text still just says the check exists ("no pip install in setup.sh").

It matters to an agent because the old behaviour was wrong in both directions:

• a script whose comment read # always uv sync here, never pip install was rejected as BLOCKING — penalising exactly the author who documented the rule;
• a script whose only mention of uv sync was in a comment satisfied golden-rule.setup-sh-uv-sync while installing nothing.

So an agent looking at a BLOCKING setup-sh-no-pip from an older kbagent may be looking at a comment, and should read the file before telling anyone to change what the script runs. The gotcha also states the stripper's limits — it tracks quotes but is deliberately not a shell parser, so heredocs and ${...#...} are out of scope — so nobody reads the rule as a guarantee.

Added to gotchas.md, commands-reference.md and data-app-workflow.md.

Incomplete entry: table-detail

Its commands-reference entry covers #621's definition object thoroughly but said nothing about #624's read side: the resolution precedence (native definition → columnMetadata KBC.description → legacy flat key, with the alias-table fallback), the always-present legacy_column_descriptions field, the human-mode warning pointing at describe-migrate, and that reading never writes so it is safe under --deny-writes.

The describe-column entry already said "read back in storage table-detail" — but table-detail itself did not advertise that it does this, or that it resolves descriptions written by the UI and by components, not just kbagent's own.

Note on the audit method

The first pass of this audit produced four false gaps, because grepping for a phrase I expected the docs to use is not the same as checking whether the topic is covered. keboola-expert.md does carry #621 and #624 — including the sharp version of the #621 warning ("create-table only echoes the layout you REQUESTED, so it proves nothing"). Every remaining -- in my matrix was verified by hand before concluding anything.

Verification

make check green: 5857 passed, 12 skipped. check_version_gates.py resolves 419 markers (up from 418), check_command_sync.py clean. Docs only — no source, no behaviour change, no version bump.

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

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