Quick Start Guide: From Sign-Up to First Decision

Engineering organizations often suffer from a form of collective amnesia where the reasoning behind critical technical choices evaporates as teams scale or personnel shift. Hopsule provides the necessary infrastructure to arrest this decay by transforming fleeting conversations into permanent, enforceable organizational judgment. This guide provides a comprehensive walkthrough for establishing your first decision-first environment, ensuring that your team's most vital context is preserved, shared, and enforced across every development surface.

By the end of this guide, you will have established a Hopsule organization, configured your first project, and transitioned a decision from a mere thought into an active, enforceable constraint that your team can rely on. This process is designed to take less than ten minutes, providing an immediate foundation for long-term architectural and procedural governance.

Prerequisites

Before beginning the onboarding process, ensure you have the following requirements met to facilitate a seamless setup:

• Administrative Access: You should have the authority to define organizational structures and invite team members to a shared workspace.

• Verified Email: A professional email address is required for account verification and secure token generation.

• Development Environment: Access to a terminal for the Hopsule CLI and a supported IDE (VS Code or Cursor) to witness real-time decision enforcement.

• Defined Project Scope: A clear understanding of a specific project or repository where you intend to apply your first set of decisions and memories.

Step 1: Initializing Your Hopsule Organization

The journey begins at the Hopsule Dashboard, the central nervous system for your team's memory. Upon your first login, you will be prompted to create an Organization. An Organization serves as the highest level of your governance hierarchy, housing all subsequent projects, members, and context packs.

1. Navigate to the Hopsule Dashboard and select Create Organization.

2. Provide a name that reflects your engineering unit or company. This name will be used in CLI contexts and API requests.

3. Configure your Security Baseline. Ensure that End-to-End Encryption is confirmed; Hopsule applies AES-256 encryption at rest and TLS 1.3 in transit by default for all tiers.

4. Once the organization is initialized, you will be redirected to the Organization Overview. This screen provides a high-level view of your Knowledge Graph (also referred to as the Brain), which will eventually visualize the intricate web of decisions and memories you create.

Step 2: Creating Your First Project

Projects in Hopsule are logical containers for decisions that share a specific scope, such as a microservice, a frontend application, or a set of infrastructure-as-code scripts. Decisions made within a project are localized to that project unless they are later bundled into a portable Context Pack.

1. From the sidebar of the Hopsule Dashboard, click on the Projects tab.

2. Click the New Project button in the top-right corner.

3. Enter a descriptive name (e.g., "Core API Service") and an optional description. The description helps Hopper, our AI assistant, understand the broader context of your work when suggesting decision drafts.

4. Select the Enforcement Level. For your first project, we recommend "Advisory," which allows developers to see warnings in their IDE without blocking CI/CD pipelines until the team is comfortable with the workflow.

Step 3: Drafting Your First Decision with Hopper

Decisions are the core entities of Hopsule. They represent explicit commitments your team has agreed to follow. Unlike static documentation, decisions in Hopsule have a lifecycle and are enforceable. We will use Hopper to draft our first decision using natural language.

1. Inside your new project, click the Create Decision button.

2. In the decision editor, look for the Hopper Assistant panel.

3. Type a natural language prompt such as: "We should use snake_case for all database column names to maintain consistency with our legacy reporting tools."

4. Hopper will generate a structured draft including a Title, Description, and Constraint Logic. Review this draft carefully.

5. Note that the decision status is currently set to Draft. In this state, the decision is visible to your team but is not yet enforced in the Hopsule CLI or Hopsule for VS Code.

Step 4: Anchoring Decisions with Memories

A decision without context is merely a rule; a decision with Memories is organizational wisdom. Memories are append-only entries that explain the "Why" behind a decision. They are never deleted or overwritten, ensuring a permanent audit trail of your team's reasoning.

1. Scroll to the Memories section at the bottom of your decision draft.

2. Click Add Memory.

3. Enter the historical context. For example: "In Q3 2023, we attempted to use camelCase for database columns, but this caused significant failures in our data warehouse ingestion scripts. We reverted to snake_case after 48 hours of downtime."

4. Click Save Memory. This entry is now permanently linked to the decision, providing future developers with the "Why" they need to respect the "What."

Step 5: Review and Acceptance

To move a decision from a suggestion to an enforceable reality, it must pass through the Accepted stage of its lifecycle. This transition represents the point of governance where the team agrees to be held accountable to this choice.

1. Review the decision draft and its associated memories.

2. If you are satisfied, click the Submit for Review button. This changes the status to Pending.

3. As an administrator, you can now click Accept Decision.

4. Once accepted, the decision becomes an active constraint. It will now appear in the Knowledge Graph and will be synchronized with all connected surfaces, including the Hopsule CLI and Hopsule for VS Code.

Step 6: Configuring the Hopsule CLI

The Hopsule CLI allows developers to interact with the memory system directly from their terminal. It is essential for CI/CD integration and for developers who prefer a keyboard-centric workflow.

1. Install the CLI using your preferred package manager (refer to the Downloads section in the Dashboard).

2. Run the command hopsule login in your terminal. This will open a browser window for secure authentication.

3. Once authenticated, run hopsule project list to verify that you can see the project you created in Step 2.

4. Run hopsule decision list --project [your-project-id]. You should see your newly accepted decision listed with its current status.

5. Try running hopsule status. This provides a high-level summary of your project's health and any active decision conflicts.

Step 7: Enabling IDE Enforcement

The final step in the quick start process is bringing your decisions into the code editor. Hopsule for VS Code ensures that enforcement is an act of remembrance, not control, by surfacing context exactly where code is written.

1. Search for "Hopsule" in the VS Code Marketplace and install the extension.

2. Open the Hopsule sidebar icon in VS Code.

3. Click Sign In and follow the prompts to link your IDE to your Hopsule account.

4. Open a file in your project. If your code contradicts an Accepted decision, the extension will highlight the relevant section.

5. Hover over the highlighted code to see the decision title and a link to the Memories explaining why that decision exists. This immediate feedback loop prevents technical debt before it is even committed.

Tips and Best Practices

To get the most out of Hopsule, consider these strategic approaches to decision management and context preservation:

• Atomic Decisions: Keep each decision focused on a single constraint. Instead of one large "Style Guide" decision, create smaller, linked decisions for "Variable Naming," "Error Handling," and "Import Ordering." This makes the Knowledge Graph more useful and allows for granular deprecation.

• Memory First: Before drafting a decision, encourage your team to add Memories about past failures or lessons learned. This builds a foundation of evidence that makes the eventual decision easier to accept.

• Use Hopper as a Peer: Treat Hopper as an advisor. Use it to check for conflicts between a new draft and existing decisions. Hopper can identify if a new "snake_case" decision contradicts an older, forgotten "camelCase" decision in a different project.

• Leverage Context Packs: If you find yourself recreating the same decisions across multiple projects, bundle them into a Context Pack (Capsule). This allows you to share a "Standard Security Context" or "Team Workflow Context" across your entire organization with a single click.

• Enforcement is Not Punishment: Use the Hopsule Dashboard to monitor how often decisions are overridden in the IDE. Frequent overrides may indicate that a decision is outdated and needs to be Deprecated or updated with new Memories.

Troubleshooting

If you encounter issues during your initial setup, refer to the following table for common resolutions:

Related Articles

• Managing Decision Lifecycles: From Draft to Deprecation

• Advanced Context Pack Orchestration for Multi-Repo Teams

• Configuring Hopsule MCP for Autonomous AI Agents

• Security and Data Sovereignty: Understanding Hopsule Encryption