Docs

Workspaces

Create and configure workspaces in the FlyDocs portal. Status mapping, label configuration, custom rules, and member management.

Workspaces are where you configure your team's workflow. Each workspace maps a PM provider team to repos, members, and settings. Configuration set here is authoritative -- every CLI session resolves it automatically.

This page covers how to create and manage workspaces in the portal. For the conceptual model behind workspaces and topology, see Workspaces & Topology.

Creating a workspace

Create a workspace from the org home page or during the onboarding wizard after signing up.

  1. Click Create Workspace
  2. Enter a workspace name (e.g., "Product", "Platform", "Client X")
  3. Select the provider team -- the Linear team or Jira project this workspace maps to

The workspace is created with sensible defaults for status mapping and labels. You can customize everything from the workspace settings page.

Workspace settings

Access workspace settings at /{workspaceSlug}/settings in the portal. Settings are organized into sections:

Details

Workspace name and icon. The name appears in the portal navigation and in the CLI when selecting a workspace during flydocs init.

Version control

Connected VCS provider and associated repositories. Manage which repos are linked to this workspace.

Project management

The core configuration section. This is where you define how FlyDocs maps to your PM tool:

  • Provider team selection -- which Linear team or Jira project this workspace targets
  • Status mapping -- maps FlyDocs canonical statuses to provider workflow states (see below)
  • Label mapping -- maps FlyDocs issue type labels to provider labels
  • Issue type mapping -- Jira only: maps FlyDocs categories to Jira issue types (Story, Bug, Task, etc.)
  • Custom workspace rules -- markdown editor for workspace-specific rules

FlyDocs details

Shows the installed FlyDocs version and last update timestamp. The update button pulls the latest managed artifacts to the workspace.

Danger zone

Delete workspace. This is irreversible (see Deleting a workspace below).

Status mapping

Status mapping defines how FlyDocs canonical statuses translate to your PM tool's workflow states. FlyDocs uses these canonical statuses:

FlyDocs Status Purpose
BACKLOG Captured but not prioritized
READY Refined and ready to implement
IMPLEMENTING Actively being built
BLOCKED Work paused due to a dependency
REVIEW Code review in progress
TESTING QA validation
COMPLETE Done, accepted
ARCHIVED Closed and archived
CANCELED Closed without completion
DUPLICATE Duplicate of another issue

Each canonical status maps to one of your provider's workflow states. For example, IMPLEMENTING might map to "In Progress" in Linear or "Development" in Jira.

Configure the mapping via the inline editor in workspace settings. The editor shows your provider's available workflow states as a dropdown for each FlyDocs status. The AI always uses FlyDocs canonical status names. The relay translates transparently.

Label configuration

FlyDocs uses issue type labels to classify work: feature, bug, chore, and idea. These labels drive template selection during issue capture and help filter issues by type.

For Linear, the label mapping connects FlyDocs label types to Linear labels. If the matching labels do not exist in Linear, FlyDocs creates them automatically when you save the configuration.

For Jira, issue types are mapped separately using the issue type mapping editor, since Jira uses issue types (Story, Bug, Task) rather than labels for classification.

Custom rules

The custom rules editor accepts markdown content that is replicated to every repo in the workspace as part of the context layer. Use this for workspace-specific standards that should apply across all repositories:

  • Code review requirements
  • Testing expectations
  • Architecture constraints
  • Naming conventions specific to this team
  • Deployment procedures

Custom rules are appended to each repo's project.md during sync. They appear under a "Workspace Rules" section that the AI reads alongside the project-specific context.

Managing members

Add and remove workspace members at /{workspaceSlug}/members. Members who are added to a workspace can:

  • See the workspace in their portal home view
  • Use the relay API for this workspace (issue operations, status transitions)
  • Run flydocs init and select this workspace during setup

Membership is separate from organization roles. Org admins can access all workspaces regardless of explicit membership. Regular members only see workspaces they have been added to.

Deleting a workspace

Delete a workspace from the Danger Zone section in workspace settings. This action is irreversible and removes:

  • Workspace configuration (status mapping, labels, rules)
  • Workspace membership records
  • Managed artifact associations

Deleting a workspace does not affect your PM tool data. Issues, comments, and labels in Linear or Jira are untouched. Repos that referenced this workspace will need to be re-initialized with a different workspace using flydocs init.

Next