Public Sharing: Generating and Managing Share Tokens

The ability to communicate organizational judgment beyond the immediate boundaries of an engineering team is critical for alignment, transparency, and long-term preservation of context. This article provides a comprehensive guide on how to utilize the Hopsule Dashboard to generate, manage, and audit secure share tokens, allowing external stakeholders and collaborators to access specific decisions and context packs without requiring a Hopsule account.

Public sharing in Hopsule is designed with the philosophy that enforcement is remembrance. By providing a secure, read-only window into the reasoning and commitments of your team, you ensure that external partners, consultants, or cross-departmental leaders can align with your established governance without compromising the integrity of your internal memory system.

Prerequisites for Public Sharing

Before you can generate share tokens for your organizational memory, ensure that you meet the following requirements within the Hopsule environment:

• Verified Account: You must have an active account with appropriate permissions (Admin or Editor) to manage sharing settings on the Hopsule Dashboard.

• Accepted Entities: While drafts can be shared for internal review, it is recommended that only decisions in the Accepted or Deprecated state are shared publicly to maintain the authority of your governance.

• Active Context Packs: If you are sharing a Capsule, ensure it is in the Active or Frozen state. Draft Capsules cannot be shared via public tokens to prevent the accidental exposure of incomplete reasoning.

• Security Policy Alignment: Ensure your organization’s security policy allows for external token generation. For Hopsule Enterprise (Self-Hosted) users, verify that your local network configuration allows for public-facing token resolution if intended for external use.

Generating Share Tokens for Decisions

A decision is an explicit commitment. Sharing a decision via a token allows others to see not just the "what," but the "why" by including linked memories and the full version history. Follow these steps to generate a token for an individual decision:

1. Log in to the Hopsule Dashboard and navigate to the Decisions tab in the primary sidebar.

2. Locate the specific decision you wish to share from the list. You can use the search bar or filter by category to find it quickly.

3. Click on the decision title to open the Decision Detail View.

4. In the top-right action menu, click the Share button. This will open the Share Token Management modal.

5. Click Generate New Token. You will be prompted to provide a Token Label (e.g., "External Audit Q3" or "Consultant Access"). This label is for internal tracking only.

6. Configure the Access Scope. You can choose to share the decision text only, or include all Linked Memories. Including memories is highly recommended as it provides the necessary context and reasoning that constitutes organizational memory.

7. Set an Expiration Date. For maximum security, Hopsule recommends setting tokens to expire after 30, 60, or 90 days. You may also select "Never" for permanent public documentation.

8. Click Create Token. The Hopsule Dashboard will generate a unique, cryptographically secure URL.

9. Copy the URL and distribute it to your stakeholders. Note that for security reasons, the full token is only displayed once.

Generating Share Tokens for Context Packs (Capsules)

Context Packs, or Capsules, are portable bundles of decisions and memories. Sharing a Capsule is the most effective way to provide a comprehensive overview of a project’s governance or a team’s architectural standards. To share a Capsule:

1. Navigate to the Capsules section of the Hopsule Dashboard.

2. Select the Capsule you intend to share. Ensure the Capsule contains all the relevant decisions and memories required for the recipient to understand the context.

3. Click the Manage Sharing button located within the Capsule header.

4. In the Public Access tab, click Enable Public Token.

5. Define the Visibility Level. You can choose to share only the Active Decisions within the Capsule or include the entire Memory Append-Log for full traceability.

6. Toggle the Knowledge Graph option if you want the recipient to be able to visualize the relationships between decisions using the Brain view.

7. Click Generate Token. The resulting link will provide a dedicated public landing page for that specific Capsule.

Managing and Revoking Tokens

Governance requires the ability to rescind access as easily as it is granted. Hopsule provides a centralized interface for auditing all active share tokens to ensure that organizational memory remains protected.

To audit and manage your tokens, go to the Settings menu in the Hopsule Dashboard and select Security & Sharing. Here, you will find a list of every active token generated across your projects. The list includes the creator, the creation date, the expiration status, and the total number of views the token has received.

To revoke a token immediately, click the Revoke (trash can) icon next to the token entry. Once revoked, the URL will immediately cease to function, and any attempts to access the decision or Capsule will result in a 404 error. This action is permanent and cannot be undone; if access is required again, a new token must be generated.

Using Hopper to Draft Sharing Descriptions

When sharing a decision or Capsule, it is often helpful to provide a summary or a "TL;DR" for the public viewer. Hopper, the built-in AI assistant, can help you draft these summaries based on the existing memories and decision history.

While in the Share Token Management modal, you can prompt Hopper: "Hopper, summarize the reasoning for this decision for an external stakeholder." Hopper will analyze the Accepted decision and its linked Memories to produce a concise summary. Remember that Hopper is advisory only; you must review and approve the summary before it is included in the public view. This ensures that the authority remains with the human decision-makers while leveraging AI for efficiency.

The Public View Experience

When a stakeholder clicks a Hopsule share token, they are presented with a clean, read-only version of the Hopsule interface. This view is optimized for clarity and preservation of context. The public interface includes:

• The Decision Statement: The core commitment the team has agreed to follow.

• The Reasoning Log: An append-only list of memories that explain the history and lessons leading to the decision.

• Traceability Links: If the decision is part of a larger Capsule, the viewer can see the relationship to other governed entities (if permissions allow).

• Status Indicators: Clear badges showing whether the decision is Accepted or Deprecated.

• Metadata: Creation dates and version numbers to ensure the viewer knows they are looking at the current source of truth.

Importantly, the public view does not allow for comments, edits, or the creation of new memories. It is a preservation-first interface designed for consumption and alignment, not for active collaboration. For active collaboration, users must be invited as full members of the Hopsule organization.

Tips and Best Practices

• Use Descriptive Labels: Always label your tokens with the name of the recipient or the purpose of the share. This makes the audit trail much easier to navigate when you need to revoke access later.

• Apply Expiration Dates: Unless you are creating a permanent public roadmap, always set an expiration date. This follows the principle of least privilege and reduces the long-term surface area of your shared context.

• Verify Linked Memories: Before sharing a decision, review the linked memories. Ensure that the reasoning preserved in those memories is appropriate for external eyes and does not contain sensitive internal references.

• Leverage the Knowledge Graph: When sharing complex Capsules, enable the Knowledge Graph (Brain) view. This helps external partners understand the "web" of decisions and how one architectural choice influences another.

• Regularly Audit Tokens: Schedule a monthly review of all active share tokens in the Hopsule Dashboard to ensure that no legacy access remains active longer than necessary.

• Avoid Over-Sharing: Share only what is necessary for the stakeholder to achieve alignment. Use specific decision tokens rather than full Capsule tokens when a narrow scope is sufficient.

Troubleshooting

If you or your stakeholders encounter issues with share tokens, refer to the table below for common causes and solutions.

Integrating Share Tokens with Hopsule API

For organizations that require automated workflows, the Hopsule API provides endpoints to programmatically generate and manage share tokens. This is particularly useful for CI/CD pipelines where a successful deployment might trigger the generation of a shareable Capsule for the QA team or external auditors.

Using the /v1/tokens endpoint, you can create tokens with specific scopes and durations. The API returns the same secure URL structure as the Hopsule Dashboard, ensuring consistency across your toolchain. Note that API-generated tokens are subject to the same rate-limiting and security policies as those created via the web interface. For more technical details on the API structure, refer to the official Hopsule API documentation.

Security and Data Sovereignty

At Hopsule, security is a baseline guarantee. All share tokens are protected by TLS 1.3 during transit and are stored using AES-256 encryption at rest. When a public viewer accesses a token, Hopsule only serves the specific data entities associated with that token. No other part of your organizational memory, decision history, or project structure is exposed.

For users of Hopsule Enterprise (Self-Hosted), public sharing remains entirely within your control. You manage the infrastructure where the tokens are resolved, ensuring that your data never leaves your environment unless you explicitly configure your network to allow external access. This provides the ultimate level of data sovereignty while still allowing for the benefits of portable, shareable context.

Related Articles

• Managing Decision Lifecycles: Learn how to move decisions from Draft to Accepted to ensure they are ready for public sharing.

• Building Effective Context Packs: Discover how to group decisions and memories into Capsules that provide maximum value to external stakeholders.

• Understanding the Knowledge Graph: A deep dive into how the Brain visualizes the connections between your team's choices.