User Guide

Role Dictionary is a collaborative catalogue of organisational roles and the relationships between them, built by the E-CARGO Research Team. Roles are curated through a community submission and review workflow, visualised as an interactive graph, and used as the foundation for AI-assisted group role assignment (GRA).

The app has three layers:

• Explore & contribute — browse the role graph, read role definitions, and submit new roles or improvements. Submissions go through an admin review before they appear publicly.
• Groups & agents — join a group, declare your current, past and potential roles, and maintain an agent profile (skills, experience, preferences) that describes you as a candidate for roles.
• AI evaluation & assignment — score how well each group member fits selected roles using an LLM (Gemini), then run the GRA algorithm to propose an optimal role assignment for the group.

Role Dictionary uses passwordless email sign-in. There is no password to remember — a one-time verification code is emailed to you, and signing in with a new email address automatically creates an account.

1. Click Sign In in the header and enter your email address, then click Send Verification Code.
2. Check your inbox for a 6-character code and enter it, then click Verify & Sign In. You can resend the code or change the email after a 60-second cooldown.

Your session stays active for a couple of hours and refreshes automatically in the background. Use Logout in the user menu to end it. The home page graph can be browsed without signing in, but contributing, editing, and all other pages require an account.

Access levels

Contributor levels

The badge on your avatar is your contributor level. It grows with the number of role submissions you have made — from level 0 with no submissions up to level 18 — so contributing roles is the way to level up.

The header is always visible: the Guides button opens this guide, and your avatar opens the user menu. Menu entries open in a new browser tab, so your place in the graph is never lost.

• Your email — opens your user profile.
• Group membership — your group, roles, and agent profile.
• LLM evaluation & GRA — the AI evaluation and assignment workflow.
• User Management / Role Management / Review — visible to super administrators only.
• History — the status of your submissions. A red badge shows how many unread review results you have.

The home page shows every approved role as a node in an interactive force-directed graph. Edges are typed relationships between roles; each type has its own colour and can be toggled with the legend checkboxes below the graph. Your own pending submissions are visible to you (and only you) until they are approved.

Working with the graph

• Search — type in the search box to filter the graph to matching roles and their direct neighbours; pick a suggestion to jump to an exact role.
• Hover a node to highlight it and its connections; click a node to select it and fan its related roles out in a circle around it. Click the background to deselect.
• Role Details — after selecting a node, this button opens a popup with a link to the full role page (and a Delete option for super admins).
• Pan & zoom — drag the canvas, use the mouse wheel, or the +/− buttons in the corner. Drag nodes to pin them where you want.
• Show Title toggles role labels; Reset clears the search, highlights, and zoom.

Click Add Role on the home page to propose a new role. New roles do not appear in the public graph immediately — they are submitted for review, and you can track the outcome on the History page.

1. Fill in the required fields: Title, Description, Responsibilities, Rights, Requirements. Working Conditions and Benefits are optional. Each field has a ? tooltip explaining what belongs there.
2. Watch the similar roles dropdown as you type the title — if the role already exists, open it from the list instead of creating a duplicate.
3. Link the role to existing roles with the relationship pickers (super role, promotion, report-to, requester, conflict, peer, competition). If a related role doesn't exist yet, choose "Not found, add a new role" to create it inline, or -TBD- to leave it open.
4. Click Save and confirm. The role enters the review queue with status Under Review.

The role page (opened via Role Details → Details on the graph) shows the full definition: description, responsibilities, rights, requirements, working conditions, and all seven relationship lists.

Editable roles show an Edit button. Editing never changes the live role directly — saving creates a pending update that a super administrator must approve before it replaces the original. Track it on the History page like any other submission.

The History page lists every role you have submitted (new roles and edits) with its review status. Unread results are counted in the red badge on the History menu item.

• Under Review — waiting for a super administrator.
• Approved — the role is now public in the graph.
• Disapproved — open View to read the reviewer's reason, then click Resubmit to fix the role in a pre-filled form and send it back to the review queue.

The Group membership page describes you as a member of your organisation group. It is also where you maintain the agent profile that the LLM evaluation uses to judge your fit for roles — the richer your profile, the better the evaluation.

1. Click Edit membership.
2. Set your current role and add any past and potential roles within the group.
3. Fill in your agent profile: age, years of experience, a professional summary, and tag lists for hard skills, soft skills, personality traits, and preferences (type a tag and press Enter).
4. Click Save changes.

The page also shows the group's role limits — the minimum and maximum number of people per role, with a live count of how many members currently fill each role — and a members table of everyone in the group. Administrators can additionally switch or rename the group and edit the role limits; these limits drive the GRA assignment.

This page scores how well each agent in a group qualifies for selected roles using Google Gemini, and runs GRA (Group Role Assignment) — an optimisation that proposes who should play which role, respecting the group's role limits.

Setting the scope

• Group (required) and Roles (required) — what to evaluate against.
• Agents (optional) — narrow the run to specific members; leave empty to include all active agents in the group.
• Model and Rubric version (optional) — override the server defaults if you need a specific Gemini model or rubric.
• GRA threshold — the minimum qualification score for an agent-role pair to be considered in the assignment (default 0.5).
• Persist results — store scores on the agents so later GRA runs can reuse them. Re-evaluate existing pairs — redo pairs that already have a stored score.

The four actions

1. Check coverage — read-only: see which agent-role pairs already have stored scores before spending LLM time.
2. Run LLM evaluation — score the selected pairs with Gemini. Each result includes an overall score, confidence, five rubric sub-scores (skill, experience, responsibility, domain, seniority), and the evidence the model found or was missing.
3. Run evaluation + GRA — the full workflow: evaluate, then immediately run the assignment on the fresh scores.
4. Run GRA only (existing scores) — skip the LLM and run the assignment over previously stored scores using the current threshold.

Reading the results

The GRA assignment card lists each agent's top role matches with their qualification index and rank. Below it, the raw result shows the overall GRA scores (weighted and unweighted), runtime, and the full assignment and qualification matrices for anyone who wants the numbers behind the proposal.