Part of epic tracebloc/backend#1142. Decision-pending — for review with @saadqbal.
Make the CLI's user-facing copy consistent with tracebloc's vocabulary and keep it that way automatically. Prompted by tb doctor/tb output leaking Kubernetes jargon (namespace, PVC, pod, node, chart, release, appVersion, requests-proxy, Service Bus, kubectl, container, image pull secret).
Source of truth (use the v2 — latest)
TERMINOLOGY.md on the docs repo main branch — the 184-line v2 (PR tracebloc/docs#61, merged): https://github.com/tracebloc/docs/blob/main/TERMINOLOGY.md
It declares itself the product-wide single source of truth ("one concept, one word"), and says explicitly "this file leads; the codebase follows later." (Note: docs develop still has the old 40-line seed — main is canonical for this file.)
Decided terms the CLI must use (all ✅ in v2):
- secure environment — the on-prem environment (DECIDED 2026-07-12, supersedes "workspace"; the CLI's current wording is already correct).
client survives only as the deep-tech/FL synonym + Client ID.
- the tracebloc CLI /
tb — the tool (not "the client/binary/agent").
- this machine — the specific host; your infrastructure — the hardware generally.
- ingest (not upload/import/load/push/send), delete (keep table/PVC detail behind
--verbose), Online / Offline (not connected/disconnected).
- collaborators (not contributor/vendor), task (not category —
category is the internal wire field only), federated training (not distributed learning/FedAvg in user copy).
- job = the K8s Job — infra-internal only, never user-facing.
Open question that touches the CLI: the deploying person's label — owner (TBD) (🔵 OPEN in v2). Decide before enforcing.
The gap
The cleanup only reached data ingest. doctor/home/resources predate it and leak the whole Kubernetes vocabulary above — plus infra internals (chart/release/appVersion, requests-proxy, Service Bus) that per v2 must be hidden behind --verbose.
Mechanism (how consistency is enforced on every ticket)
- Vocabulary → TERMINOLOGY.md (v2 on
main) stays the single source of truth, product-wide. Extend it with any CLI-surfaced terms (the k8s vocabulary → don't-use / --verbose only).
- CLI voice/format layer — a thin
cli/docs/voice.md (or CONTRIBUTING section) for CLI-only rules that are NOT vocabulary: ✔/⚠/✖/· glyphs, remedy structure, one-liners, "no infra jargon in happy-path; --verbose only." References TERMINOLOGY.md; never duplicates it.
- CI voice-lint gate — a ratchet (like file-budget.sh / goldens-drift) that greps user-facing strings (Printer calls, cobra Short/Long/Example, error messages) for banned terms and fails the build outside an allowlist (
--verbose blocks, identifiers, comments). Makes it automatic.
- PR-template checklist item + CLAUDE.md rule.
- Backfill doctor/home/resources copy to the guide.
Part of epic tracebloc/backend#1142. Decision-pending — for review with @saadqbal.
Make the CLI's user-facing copy consistent with tracebloc's vocabulary and keep it that way automatically. Prompted by
tb doctor/tboutput leaking Kubernetes jargon (namespace, PVC, pod, node, chart, release, appVersion, requests-proxy, Service Bus, kubectl, container, image pull secret).Source of truth (use the v2 — latest)
TERMINOLOGY.mdon the docs repomainbranch — the 184-line v2 (PR tracebloc/docs#61, merged): https://github.com/tracebloc/docs/blob/main/TERMINOLOGY.mdIt declares itself the product-wide single source of truth ("one concept, one word"), and says explicitly "this file leads; the codebase follows later." (Note: docs
developstill has the old 40-line seed —mainis canonical for this file.)Decided terms the CLI must use (all ✅ in v2):
clientsurvives only as the deep-tech/FL synonym + Client ID.tb— the tool (not "the client/binary/agent").--verbose), Online / Offline (not connected/disconnected).categoryis the internal wire field only), federated training (not distributed learning/FedAvg in user copy).Open question that touches the CLI: the deploying person's label — owner (TBD) (🔵 OPEN in v2). Decide before enforcing.
The gap
The cleanup only reached
data ingest.doctor/home/resourcespredate it and leak the whole Kubernetes vocabulary above — plus infra internals (chart/release/appVersion, requests-proxy, Service Bus) that per v2 must be hidden behind--verbose.Mechanism (how consistency is enforced on every ticket)
main) stays the single source of truth, product-wide. Extend it with any CLI-surfaced terms (the k8s vocabulary → don't-use /--verboseonly).cli/docs/voice.md(or CONTRIBUTING section) for CLI-only rules that are NOT vocabulary: ✔/⚠/✖/· glyphs, remedy structure, one-liners, "no infra jargon in happy-path;--verboseonly." References TERMINOLOGY.md; never duplicates it.--verboseblocks, identifiers, comments). Makes it automatic.