Skip to content

Add canonical terminology glossary - #639

Open
hey-august wants to merge 8 commits into
mainfrom
august-20260825-add-glossary
Open

Add canonical terminology glossary#639
hey-august wants to merge 8 commits into
mainfrom
august-20260825-add-glossary

Conversation

@hey-august

@hey-august hey-august commented Aug 28, 2026

Copy link
Copy Markdown
Collaborator

Description

SignalWire has renamed and merged products over the years, and the docs still use the old names sometimes: "Realtime SDK" and "Agents SDK" for what is now the Server SDKs, LaML for cXML, etc.

This PR adds /docs/platform/glossary defining key terms and labels and listing aliases and historical names, and disambiguating between related items.

Glossary page

In addition to the definitions, this page adds:

  • A themed SVG diagram showing the Account → Space → Project → Subproject hierarchy, following the existing diagram conventions
  • The Segment ID ≡ leg call_id relationship, verified against the backend source.

This PR also updates the contributor terminology rule in .claude/rules/mdx-style.md to point at the glossary instead of maintaining its own list.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Code cleanup / refactor

Related Issues

Closes the first half of #561 (audit #559, §3 and §10).

Testing

  • Added/updated unit tests
  • Tested manually
  • Tested with live SignalWire credentials (if applicable)

Checklist

  • I have read the CONTRIBUTING guidelines
  • My code follows the project's style guidelines
  • I have added tests for my changes (if applicable)
  • I have updated documentation (if applicable)
  • All existing tests pass

@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

@hey-august hey-august linked an issue Aug 28, 2026 that may be closed by this pull request
Devon-White
Devon-White previously approved these changes Sep 3, 2026
Comment thread fern/products/platform/pages/platform/core/glossary.mdx Outdated
Comment thread fern/products/platform/pages/platform/core/glossary.mdx Outdated
Comment thread fern/products/platform/pages/platform/core/glossary.mdx Outdated

The [document type][swml-calling] for voice calls. JavaScript expressions in `${...}` are a Calling SWML feature.

#### Messaging SWML [#messaging-swml]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure these need to be two separate sections? We have a SWML document, and it supports calling handling and message handling

Comment thread fern/products/platform/pages/platform/core/glossary.mdx Outdated
@hey-august hey-august changed the title Add canonical glossary + machine-readable registry Add canonical terminology glossary Sep 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Publish a canonical terminology registry and glossary

2 participants