edut/web
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
c96ec23bec
web/docs/vocabulary-registry.md
Joshua 2e03728583
Some checks are pending
check / secretapi (push) Waiting to run
Details
Apply EDUT ID user-facing naming pass and glossary registry
2026-02-19 06:35:06 -08:00

2.2 KiB
Raw Blame History

EDUT Vocabulary Registry (v1)

This registry defines canonical naming across user-facing copy, support language, and technical implementation.

Rule: one concept -> one preferred user phrase.

Identity and Access

  1. User-facing: EDUT ID Technical: membership (current code key and route family) Notes: Use EDUT ID in all UI/legal/public copy. Keep technical names stable until intentional internal refactor.

  2. User-facing: EDUT ID activation Technical: membership activation, membership mint Notes: One-time purchase event, non-recurring.

  3. User-facing: EDUT ID active Technical: membership_active Notes: Binary status text for user surfaces.

  4. User-facing: designation Technical: designation_code, designation_token Notes: Keep visible only when needed for evidence/diagnostics.

Commerce and Runtime

  1. User-facing: license Technical: entitlement Notes: Keep license language in customer copy; entitlement remains implementation object.

  2. User-facing: workspace Technical: org_root_id, workspace_id Notes: Avoid exposing raw boundary identifiers in default UI.

  3. User-facing: Auto capacity (or approved SKU title) Technical: lane, lane24 Notes: Avoid exposing lane as a default UI term outside diagnostics/trust surfaces.

  4. User-facing: offline continuity Technical: sovereign, capsule Notes: Reserve sovereign/capsule for technical docs unless explicitly required.

Terms To Keep Out of Default User Surfaces

  1. member_only
  2. workspace_member
  3. org_root_owner
  4. connector_surface
  5. pacing_tier
  6. membership_* internals

These remain valid in API contracts, logs, conformance vectors, and implementation docs.

Change Discipline

  1. Copy-only rename pass: user-facing surfaces first.
  2. Internal rename pass: only when routes/schemas/contracts are versioned for a clean break.
  3. Never mix names in one surface (Membership and EDUT ID together is prohibited).

Inline Glossary Pattern

  1. Keep technically accurate terms in UI when possible.
  2. Add a small help icon next to the term.
  3. Help text must be one sentence, plain language, no jargon.
  4. Use glossary help instead of inventing alternate names that diverge from implementation language.