Usable dashboard user guide

Dashboard: https://usable.dev/dashboard

The Usable dashboard is the human interface for workspaces, fragments, files, collections, settings, organizations, billing, marketplace, and applications. This guide covers public user workflows.

Main dashboard routes

First-time user workflow

1. Open https://usable.dev and sign in or sign up.
2. Accept terms and privacy policy if prompted.
3. Open /dashboard.
4. Go to Workspaces.
5. Create a workspace, join one through an invitation, or discover public workspaces.
6. Open the workspace and review its fragment types.
7. Create your first fragment.
8. Search for it to verify it is retrievable.
9. Create a PAT only when a REST/MCP integration needs one.

Workspace workflows

Create a workspace

1. Navigate to Dashboard → Workspaces.
2. Choose Create Workspace.
3. Enter a concise name and description.
4. Select visibility: Private (invite-only) or Public (discoverable).
5. Save.
6. Open it and create initial fragments: purpose, tagging rules, and contribution policy.

Discover or subscribe to a public workspace

1. Open Dashboard → Workspaces.
2. Switch from Mine to Discover.
3. Search by workspace name or description.
4. Choose Subscribe for ongoing read-style access.
5. The subscribed workspace appears in Mine with a Subscriber role label.

Subscription is read-only. Creating fragments, uploading files, or changing settings requires collaborator or owner access.

Manage workspace members

1. Open the workspace.
2. Go to Settings → Members.
3. Invite a user by email.
4. Choose the least-privileged role: Owner, Collaborator, or Viewer.
5. Update or remove members when responsibilities change.

Fragment workflows

Create a fragment

1. Open a workspace and navigate to Fragments.
2. Choose Create.
3. Select the fragment type.
4. Enter a short, searchable title.
5. Write markdown content in the body.
6. Add a concise summary and tags.
7. Choose status if the form exposes draft/published/archived.
8. Save and verify the fragment detail page.

Good fragment body structure:

# Topic title
 
## Summary
One paragraph describing what this fragment is for.
 
## When to use this
- Situation A
- Situation B
 
## Steps or details
1. Step one
2. Step two
 
## References
- Links or related fragment IDs

Fragment writing guidelines

• Put durable facts in the content body.
• Use a title a teammate would type into search.
• Add tags consistently: docs, public, api, repo:<name>, version:<release>.
• Choose the most specific fragment type.
• For public fragments, include release/version context.

Fragment-type sort

Workspace fragment-type pills have a Sort by selector:

• Default — server order.
• Name (A–Z) — alphabetical, case-insensitive.
• Colour — approximate Tailwind hue order.
• Most used — descending active fragment count.

The sort is stored in browser local storage under usable.fragmentTypeSort.

Connect MCP

The dashboard home page exposes Connect MCP directly. The dialog shows:

1. Copy the MCP URL: https://usable.dev/api/mcp
2. Add it to a client using one of the provided examples: Claude Code, Claude Desktop, Codex, OpenCode, or generic Streamable HTTP.
3. Authenticate with OAuth 2.1 browser sign-in.
4. Optionally copy the workspace system prompt.

Collections workflows

Create a collection

1. Open the workspace.
2. Navigate to collections where exposed.
3. Create a collection with a clear name and description.
4. Add related fragments.

Good collection names: Public platform docs v1.195.0, Customer onboarding guide, API integration recipes.

Maintain a collection

1. Review collection membership after documentation changes.
2. Remove outdated fragments and add newly published ones.
3. Keep collection descriptions current.

Files workflows

Upload a file

1. Open a workspace.
2. Select the Files tab.
3. Choose upload and select a file safe for the workspace audience.
4. Wait for upload/processing status to complete.
5. Attach the file to a fragment if applicable.

The public API documents a 50 MB upload limit.

Attach a file to a fragment

1. Upload or locate the file.
2. Open file actions or fragment attachment controls.
3. Select the target fragment and attach.
4. Confirm the attachment is visible on the fragment detail page.

Workspace settings

Fragment types

1. Open workspace settings.
2. Review existing fragment types.
3. Create a new type only if existing types do not cover the use case.
4. Use clear names and descriptions; avoid overlapping types.

Auto-link rules

Auto-link rules watch tags on fragments in the source workspace and create symlinked fragments in a target workspace when the match succeeds.

1. Open the source workspace overview and find Auto-link rules.
2. Choose a match mode: Any tag or All tags.
3. Add 1–25 tags.
4. Pick a target workspace (must be different from source; you must be owner/collaborator in both).
5. Review the live Preview before saving.
6. Use Reprocess to apply the rule to existing fragments.

Webhooks

1. Open workspace settings and navigate to webhooks.
2. Add a webhook endpoint URL.
3. Select event types.
4. Save and use the manual trigger/test flow before production.
5. Rotate secrets or disable the webhook if exposed.

Hosted Zones page

Organization owners/admins on Pro organizations can open Hosted Zones from the organization dashboard. See the Hosted Zones guide for full details.

Ask Usable embedded assistant (beta)

Ask Usable is a beta assistant embedded from the configured Usable Chat embed URL. Available only to users with the ask-usable-embed-chat beta grant.

Modes:

1. Bubble — compact floating launcher.
2. Panel — chat panel for normal dashboard use.
3. Canvas — wider two-column view with chat and canvas panel.

The assistant receives page context: current path, workspace/fragment/collection IDs, page heading, and theme.

Dashboard troubleshooting