docs(terminology): expand the dictionary into the single source of truth

[LukasWodka]

What

Expands docs/TERMINOLOGY.md from the 9-term 2026-06-05 seed into a full working dictionary — the single source of truth for platform vocabulary that all copy (including the communication / persona / founder-voice skills) defers to. This is the doc we align on first; no code or UI renames happen off it until the open questions are settled.

What's added

• Core product terms · people · the 16-task taxonomy · per-task data layout (folder/CSV shape, sidecars, label/target column, from the di#347 layout contract + modality specs) · training (experiment / training / job) · models · federated learning · brand terms · CLI verb/flag vocabulary · component & code naming (the word "client" today names five different things) · casing.
• A "words to retire" section mapping every live drift term → canonical (competition→use case, edge→…, vendor→collaborators, dataset push→data ingest, category→task, "compliance by design"→"Compliance by architecture", …), with where each appears — for awareness, not a rename trigger.
• 7 open questions for the team to decide.

Decisions folded in (2026-07-11)

collaborators (not contributor/vendor) · experiment / training (job = infra-only) · task not category · Compliance by architecture (not "compliance by design") · single-source-of-truth structure (skills reference this file, don't redefine terms).

Still open (in the doc, for the team)

1. What we call the on-prem thing — leaning secure environment over workspace / client (load-bearing). 2. Hub vs dashboard. 3. the model verb. 4. workspace owner vs admin. 5. the client repo overload. 6. internal category vs task_type. 7. label vs image_label / timestamp vs time.

Scope

Doc only — no code, no reconciliation tickets, no skill edits. Those come after the vocabulary is aligned over the coming days and #1 is decided.

Merge

Docs repo (FR-gate/reviewer exempt) — merge at your discretion once the team's aligned; this PR is the review vehicle for the open questions.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only; no runtime or API changes—risk is copy/process alignment, not production behavior.

Overview
Turns TERMINOLOGY.md from a ~9-term seed into the authoritative vocabulary doc: skills must reference it instead of redefining terms, with ✅/🔵 status on rows and explicit no renames until open questions settle (except documenting decided terms).

Structural additions: numbered sections for core product (CLI, dashboard TBD, ingest/delete), people (collaborators ✅, owner label 🔵), task taxonomy (16 tasks + per-task layout/label columns), training (experiment / infra-only job), models, federated learning, brand terms, CLI verb/flag targets, engineering-internal naming (five meanings of “client”, EdgeDevice/Competition gaps), casing, a words to retire map with where drift lives, and 12 open questions.

Terminology shifts vs the seed: on-prem workspace → secure environment (decided 2026-07-12); contributor → collaborators; expands don’t-use lists (edge, push, category, etc.) and folds prior “open questions” into a longer decision backlog (Hub vs dashboard, model verb, column naming, …).

^{Reviewed by Cursor Bugbot for commit be490fa. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tracebloc	🟢 Ready	View Preview	Jul 11, 2026, 10:39 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[shujaatTracebloc]

Review — approve with changes ⚠️

Unusually well-researched — I cross-checked the claims against the actual repos and most hold up:

• The 16-task taxonomy matches tracebloc-engine/use_cases/ and the SDK TaskCategory enum exactly.
• The per-task data layout matches every shipped template CSV header in data-ingestors/templates/* (IC filename,label; OD filename,image_label; keypoint filename,Annotation,Visibility,image_label; semseg filename,mask_id,image_label; text/token/sentence-pair filename,extension,label; MLM/CLM/seq2seq/embeddings filename,extension; tabular id,…,label; TSF timestamp,…,value; survival …,time,DEATH_EVENT). Impressive.
• CLI "today" annotations (--intent, --category, rm <table>) and backend component names (EdgeDevice(User), PrivateCompetition, the client Helm chart, client-runtime) all check out. CI/Bugbot green.

Four items to fix before this is enforced as the single source of truth — a naming SSOT that ships a stale repo name or an undefined core term will propagate those defects:

HIGH — "use case" has no definition row. The seed's Core-terms row was dropped in the expansion, yet "use case" is used 6+ times as the preferred term (§3, §4, §5, §9, §11). The single most important product term is used-but-undefined. Restore a use case row in §1.

MEDIUM — §9 names the tracebloc-client repo, which no longer exists. It was renamed to tracebloc-engine (git remote confirms; no tracebloc-client dir). This also means the "client names five different things" header is now four live things. Update the name and the count.

MEDIUM — internal contradiction on where bare "client" survives. §1 Client-ID row says it survives "only here," but the secure-environment row + Open Q1 say it also survives as the deep-tech/FL synonym. Reconcile to one statement.

MEDIUM — the ingestor-PyPI "fix" instruction targets an accurate statement. §9 says to "fix data-ingestors/CLAUDE.md which claims the PyPI name is the underscore form," but data-ingestors/setup.py:49 declares name="tracebloc_ingestor" — CLAUDE.md is correct. Reword to "distribution normalizes to tracebloc-ingestor on PyPI; declared/import name is tracebloc_ingestor."

Low / nits:

• LOW — TSC layout sequence_id,timestamp,…,label: no TSC template ships in data-ingestors and the literal sequence_id appears nowhere in engine/ingestor/SDK (the SDK confirms 2 bookkeeping cols, consistent with the shape, but not the exact name). Verify against the real TSC ingestor spec before treating as canon.
• LOW — the authoritative header claims a founder-voice skill references this file, but no such skill exists on disk (only communication, persona). Confirm it exists/is planned.
• LOW — the enum has 18 categories (instance_segmentation, time_series_regression are members with no enabled use_case). A one-line "2 reserved-but-disabled" note prevents "I count 18" confusion.
• LOW — proposed data ingest collides with the existing tracebloc ingest command group (ingest validate). Flag so the rename doesn't create two "ingest" meanings.
• NIT — "collaborators" (plural) vs singular usage elsewhere; the §10 casing carve-out "except unavoidable title-case contexts" is vague — define or drop.

Verdict: Approve once items 1–4 land. The rest is polish.