Glossary
The Glossary tab of a project's Dictionary pages: the words the project agrees on, with definitions, other names, related terms and a review status.
By the end of this page you will have written down the words a project agrees on, know every field a glossary term carries and what reads each one downstream, and know how a term moves through its review, who sees it at each step and how it is removed.
A glossary term is a word the project agrees on. The thing the client calls a "branch", the analyst a "site" and the developers a "location" gets one entry with one definition, the other names it goes by, the terms it leans on and where the definition comes from. Every story, requirement and test is read against these words, and Heimdall drafts in them, so the glossary is the project's own language written down once.
The Glossary tab is the first of the project's Dictionary pages; the second is the data dictionary, the things the project keeps records of.
Before you begin
| You want to | You need |
|---|---|
| Open the Glossary tab | glossary:view-any on the project. Every staff role has it; a client guest has it through their project membership and sees the approved terms only. |
| Add a term | glossary:create, through your role on the project or your team role, or to own the team. Business analysts have it by default. |
| Edit or move a term | glossary:update. |
| Delete a term | glossary:delete. |
The page lives under a project: open the project, choose Dictionary in the sidebar and you are on the Glossary tab; the tab strip above the table switches to Data Entities.
Read the glossary
The table lists one term per row, in the project's order:
| Column | What it shows |
|---|---|
| Term | The word, with the first line of its definition beneath it. Press the word to open the detail flyout. |
| Status | Where the term stands in its review: draft, in review, approved or deprecated, as a coloured badge. Staff only. |
| Other Names | The first three aliases as tags, and a count of the rest. |
| Related | How many other terms this one leans on. |
| Source | Where the definition comes from. |
| Updated | How long ago the record last changed. |
| Row menu | View Term, Edit Term, Move to (the statuses the term may move to), Activity, Delete Term. |
Sort by term, status or updated by pressing a column heading; press it again to flip the direction. Above the table, narrow the list with the search box (words in the term, an alias or the definition) and, for staff, the status filter. The filters travel in the page address; Clear Filters on the empty state drops them all.
A client guest sees the approved terms only, without the status column or the status filter: a draft is still the analyst's working note.
Add a term
- Press New Term.
- Type the Term: the word as the project says it, unique within the project.
- Add the Source when the definition comes from somewhere: a document, a person, a standard.
- Write the Definition: what the word means here, in one or two sentences, for the whole project to read.
- Under Connections, list the Other Names it goes by, separated by commas, and pick the Related Terms it leans on.
- Press Add Term.
The term appears in the table at once as a draft and glossary_term.created goes out to every
endpoint subscribed to it.
The word is all it needs
A term can start as a bare word; the definition, the other names and the related terms follow as the analyst learns the domain, and Heimdall can draft them from the brief for review. The one rule is uniqueness: two entries for the same word, however they are spelt, would make every story that uses it ambiguous.
Open a term
Press a term's word, or View Term in its row menu, to open the detail flyout: the status badge, the word and its source, the definition, the Other Names as tags, the Related Terms as buttons that open the term they name, and the created and updated stamps. From the flyout, Edit, Move to, Activity and Delete are one press away.
A link such as /projects/<project>/dictionary?show=<id> opens the tab with that term's flyout
already open; notifications and Heimdall's buttons use it.
Edit a term
- Press Edit Term in the row menu, or Edit in the flyout.
- Change what you need. A new word must be free within the project, and a term cannot be related to itself.
- Press Save Changes.
Every change travels as glossary_term.updated with its old and new values, the aliases and the
related ids as lists. An edit that changes nothing announces nothing. The status does not change
here; it moves from the list or the flyout.
Move a term along its review
A term starts as a draft, the analyst's working note. Put it in review when the people who
approve it should read it, mark it approved once they agree, and deprecate it when the
project stops using the word. Open Move to in the row menu or the flyout and choose the status;
a deprecated term offers only the way back to draft. The move is written to the term's history and
travels as glossary_term.status_changed with the status before and after.
A client guest sees a term while it is approved and not otherwise, so approving a term is also what shares it with the client.
Delete a term
Delete Term in the row menu or Delete in the flyout removes the term with its definition and its activity history after a confirmation; there is no undo. The terms that leaned on it drop the relation. Requirements and business rules that will name terms are not here yet; once they are, a term they name will be deprecated rather than deleted.
All the fields
What happens next
- Every add, edit, move and delete is written to the term's activity history with who did it and where from.
- The
glossary_term.created,glossary_term.updated,glossary_term.status_changedandglossary_term.deletedevents go out to every endpoint subscribed to them. - Requirements, business rules and stories will name terms as those modules land, which is why a term in use is deprecated rather than deleted.
Heimdall on this page
Heimdall reads the glossary through the same tools the MCP server offers and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
Writing the glossary is a person's work, with Heimdall drafting for review: an agent over MCP reads the words and never writes to them.
From the API and MCP
Glossary API
List, get, add, change, move and delete glossary terms over REST.
list_glossary_terms and get_glossary_term
The two MCP tools that read a project's glossary as the token sees it.
Permissions
| Action | Permission |
|---|---|
| See the glossary | glossary:view-any; a client guest sees the approved terms |
| Open a term | glossary:view |
| Add a term | glossary:create, or owning the team |
| Edit or move a term | glossary:update, through a project role or a team role |
| Delete a term | glossary:delete |
| Read or restore its versions | glossary:view to read, glossary:update to restore; never a client guest |
Frequently asked
Related
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- Data dictionary — the things the project keeps records of
- The project overview — the project the glossary belongs to
- Status reference — the review lifecycle
- Revisions and versions — every save kept, any version put back
glossary_term.*webhook events
How is this guide?
Last updated on
Personas
The Personas tab of a project's People pages: the archetypal users the project is built for, with their goals, frustrations, habits, proficiency and devices; adding, editing, archiving, restoring and deleting them.
Data Dictionary
The Data Entities tab of a project's Dictionary pages: the things the project keeps records of, their fields, owners, personal data, retention and review status.