Understanding Roles and Permissions

Effective governance in high-performing engineering organizations requires a clear understanding of who holds the authority to commit the team to specific paths. Hopsule is designed with a robust role-based access control (RBAC) system that ensures your organizational judgment is preserved and enforced by the right individuals at the right time. This article provides an exhaustive guide to the roles, permissions, and access levels available within the Hopsule ecosystem, from the Hopsule Dashboard to the Hopsule CLI and Hopsule MCP.

By defining clear boundaries of authority, Hopsule ensures that "enforcement is remembrance, not control." Whether you are a CTO overseeing multiple projects or a senior developer ensuring architectural consistency, understanding these roles is fundamental to maintaining a high-integrity decision and memory layer for your AI teams and coding tools.

Prerequisites

Before managing roles and permissions within your organization, ensure the following requirements are met:

• You must have an active Hopsule account with an established Organization.

• To modify member roles or invite new users, you must hold the Owner or Admin role within that Organization.

• Users being invited must have a valid email address to receive their secure access token.

• For enterprise self-hosted environments, ensure your local identity provider (IdP) is correctly synchronized with the Hopsule Enterprise instance.

The Four Core Roles in Hopsule

Hopsule utilizes four distinct roles to manage the lifecycle of decisions, memories, and context packs. Each role is designed to map to specific responsibilities within an engineering hierarchy.

1. Owner

The Owner is the ultimate custodian of the organization’s memory. This role is typically held by the person who created the Hopsule organization, such as a CTO or VP of Engineering. Owners have unrestricted access to every facet of the Hopsule system.

• Accountability: Responsible for billing, subscription management, and organizational deletion.

• Authority: Can promote any member to Admin or Owner status.

• Governance: Can override any decision state and has full visibility into the Audit Trail for compliance reporting.

• Data Sovereignty: In Hopsule Enterprise, the Owner manages the infrastructure-level configurations and security protocols.

2. Admin

The Admin role is the operational governor of the team's decision-making process. Admins are responsible for the day-to-day maintenance of the decision layer, ensuring that the team's reasoning is captured and enforced correctly.

• Decision Lifecycle: Admins have the authority to move decisions from Pending to Accepted or Deprecated.

• Member Management: Can invite new members, remove existing members (except Owners), and assign roles up to the Admin level.

• Context Pack Management: Can create, activate, and freeze Capsules to ensure context is portable across the organization.

• API Management: Can generate and revoke Hopsule API keys for custom integrations and CI/CD pipelines.

3. Contributor

The Contributor is the active practitioner—the developer or engineer who interacts with Hopsule daily through the Hopsule CLI or Hopsule for VS Code. Contributors provide the raw material for the organization's memory.

• Creation: Can draft new decisions and append memories to explain the reasoning behind technical shifts.

• Interaction: Can use Hopper to draft decisions from natural language and detect conflicts in real-time.

• Enforcement: Receives warnings in the Hopsule IDE Extension when code contradicts accepted decisions and can provide intentional acknowledgments to override them.

• CLI Access: Full interactive TUI access via the Hopsule CLI to manage their own drafts and view project statistics.

4. Reader

The Reader role is designed for stakeholders who need to consume context without altering the established governance. This is ideal for cross-functional partners, junior developers in a learning phase, or automated systems that require read-only access.

• Visibility: Can browse the Knowledge Graph (Brain) to visualize decision relationships and read all accepted decisions and memories.

• AI Context: Can use Hopsule MCP to provide read-only context to AI agents (like Claude or Cursor), allowing agents to become context-aware without the risk of mutating the decision layer.

• Search: Full access to the search functionality in the Hopsule Dashboard to find historical reasoning and lessons learned.

Detailed Permission Matrix

The following table outlines the specific capabilities of each role across the Hopsule product surfaces.

*Note: While Hopsule MCP provides read-only access to AI agents, the user's role determines which decisions the agent can "see" and whether the user can prompt Hopper to draft changes based on that context.

Managing Roles in the Hopsule Dashboard

To manage members and their respective roles, follow these steps within the Hopsule Dashboard:

1. Log in to the Hopsule Dashboard.

2. In the left-hand navigation sidebar, click on the Settings icon (represented by a gear).

3. Select the Members tab from the top navigation menu within the Settings view.

4. To invite a new member:

   • Click the Invite Member button in the top-right corner.

   • Enter the individual's email address.

   • Select the desired role (Admin, Contributor, or Reader) from the dropdown menu.

   • Click Send Invitation.

5. To change an existing member's role:

   • Locate the member in the list.

   • Click the Role dropdown next to their name.

   • Select the new role. The change is applied instantly across all surfaces, including the Hopsule CLI and VS Code extension.

6. To remove a member:

   • Click the More Actions (three dots) icon next to the member's name.

   • Select Remove from Organization.

   • Confirm the action in the modal dialog. Note: This will immediately revoke their access to all Capsules and API tokens.

Role Enforcement Across Product Surfaces

Hopsule's role system is not limited to the web interface; it is enforced consistently across every tool in the Hopsule ecosystem.

Hopsule CLI

When a developer authenticates via the Hopsule CLI using hopsule login, their local session is bound to their organizational role. If a Contributor attempts to use the hopsule accept [decision-id] command, the CLI will return an "Unauthorized" error, as only Admins and Owners can move decisions to the Accepted state. However, the Contributor can freely use hopsule draft to propose new architectural constraints.

Hopsule for VS Code

The Hopsule IDE Extension respects roles by tailoring the information density and available actions. While all roles can see enforcement warnings (to prevent code from contradicting decisions), only Admins and Owners can resolve conflicts by updating the decision itself directly from the sidebar tree view. Contributors are encouraged to append a Memory to the decision if they find the current constraint is causing friction, providing a trail of reasoning for the Admin to review.

Hopsule MCP

The Hopsule MCP server acts as a secure bridge for AI agents. Regardless of the user's role, AI agents connected via MCP are strictly read-only. They can ingest decisions and memories to provide context-aware suggestions, but they can never mutate the state of a decision. This ensures that organizational authority remains exclusively in human hands.

Tips and Best Practices

• Principle of Least Privilege: Start new team members as Readers or Contributors. Only grant Admin status to those responsible for architectural governance or team leadership.

• Use Hopper for Audits: Admins should periodically ask Hopper, "Which decisions have the most overrides?" or "Are there conflicting memories in the latest Capsule?" to identify where governance may need adjustment.

• Append, Don't Edit: Encourage Contributors to frequently append Memories. Since memories are append-only and never deleted, they provide the "why" that is often lost in traditional documentation.

• Freeze Capsules for Milestones: Before a major release or project handoff, an Admin should "Freeze" the relevant Context Pack. This preserves the decision state at that point in time, creating a historical record that survives team changes.

• Token Security: Remind users that their Hopsule CLI tokens carry the weight of their role. If a laptop is lost or a token is compromised, an Admin should immediately revoke that user's access in the Hopsule Dashboard.

Troubleshooting

If you encounter issues with roles or permissions, refer to the following table for common causes and solutions.

Related Articles

• Creating Your First Decision: A guide to the decision lifecycle from Draft to Accepted.

• Managing Context Packs (Capsules): Learn how to bundle decisions and memories for portability.

• Setting Up Hopsule MCP: How to connect your AI agents to your team's preserved context.

For further assistance with roles and permissions, please contact your organization's Hopsule Owner or reach out to Hopsule Support through the feedback button in the Hopsule Dashboard. Remember, Hopsule is built to ensure your organization remembers its most vital judgments—proper role management is the first step in that preservation journey.