Configuration | FlyDocs

FlyDocs stores its local configuration in .flydocs/config.json. This file is created during installation and updated by setup commands and workspace validation. Most fields are managed automatically.

On the cloud tier, the portal is the source of truth for operational configuration. Provider type, team mapping, status mapping, label config, and custom workspace rules all live on the workspace record server-side. The local config file stores the workspaceId that tells the CLI which workspace to resolve. See API Keys for how the relay resolves configuration at request time.

Core Fields

Field	Type	Description
`tier`	string	`"local"` (free) or `"cloud"` (connected). Determines whether scripts use file-based tracking or call the relay API.
`setupComplete`	boolean	Set to `true` after successful workspace validation. Gates certain operations until setup is finished.
`workspaceId`	string	Cloud tier only. The workspace identifier from the FlyDocs relay. Assigned during workspace connection.

Workspace Configuration

The workspace object controls how FlyDocs interacts with your project management tool and repository.

Field	Type	Description
`workspace.activeProjects`	string[]	Array of project IDs. Controls which projects' issues are surfaced in commands like `/status` and `/start-session`.
`workspace.defaultMilestoneId`	string	Default milestone assigned to new issues. Can be overridden per-issue during capture.
`workspace.repoSlug`	string	GitHub repository slug in `"org/repo"` format. Used for PR creation and linking.
`workspace.product`	object	Product scope filtering. Contains `name`, `labelIds`, `icon`, and `color`. Only issues matching these labels are shown.

Issue Labels

The issueLabels object maps FlyDocs categories and roles to your provider's label IDs. These are populated during workspace setup.

Category Labels

Key	Purpose
`issueLabels.category.feature`	Label ID for feature issues
`issueLabels.category.bug`	Label ID for bug reports
`issueLabels.category.chore`	Label ID for maintenance tasks
`issueLabels.category.idea`	Label ID for ideas and proposals

Role Labels

Key	Purpose
`issueLabels.role.design`	Label ID for design work
`issueLabels.role.development`	Label ID for development work
`issueLabels.role.operations`	Label ID for ops and infrastructure
`issueLabels.role.client`	Label ID for client-facing work

Detected Stack

The detectedStack object is auto-populated during installation by analyzing your project's dependencies and configuration files. It informs skill installation and context generation.

Field	Example Value
`detectedStack.frameworks`	`["astro", "react"]`
`detectedStack.database`	`["postgres", "prisma"]`
`detectedStack.auth`	`["clerk"]`
`detectedStack.styling`	`["tailwind"]`
`detectedStack.language`	`["typescript"]`
`detectedStack.testing`	`["vitest"]`

Skills

The skills object tracks which skills are active in your project.

Field	Type	Description
`skills.installed`	string[]	Skills installed from the FlyDocs registry (e.g., `"astro-best-practices"`)
`skills.custom`	string[]	Custom skills you've added to `.claude/skills/`

Topology

The topology object describes your repository structure for multi-repo setups. This enables cross-repo context via service descriptors.

Field	Type	Description
`topology.type`	number (1-4)	1 = single repo, 2 = monorepo, 3 = multi-repo, 4 = hybrid
`topology.label`	string	Human-readable label (e.g., `"multi-repo"`)
`topology.siblings`	string[]	Related repository slugs for cross-repo awareness

Environment Variables

Cloud tier requires two environment variables. Set these in your shell profile or CI environment.

Variable	Required	Description
`FLYDOCS_API_KEY`	Cloud tier	Your API key (prefixed with `fdk_`). Generated in the FlyDocs dashboard.
`FLYDOCS_RELAY_URL`	No	Relay API endpoint. Defaults to `https://app.flydocs.ai`. Only override for enterprise on-prem deployments.

Complete Example

A fully populated config.json for a cloud tier project:

.flydocs/config.json

{
  "tier": "cloud",
  "setupComplete": true,
  "workspaceId": "ws_abc123",
  "workspace": {
    "activeProjects": ["proj_001", "proj_002"],
    "defaultMilestoneId": "ms_beta",
    "repoSlug": "acme/web-app",
    "product": {
      "name": "Web App",
      "labelIds": ["lbl_product_web"],
      "icon": "globe",
      "color": "#3B82F6"
    }
  },
  "issueLabels": {
    "category": {
      "feature": "lbl_feature",
      "bug": "lbl_bug",
      "chore": "lbl_chore",
      "idea": "lbl_idea"
    },
    "role": {
      "design": "lbl_design",
      "development": "lbl_dev",
      "operations": "lbl_ops",
      "client": "lbl_client"
    }
  },
  "detectedStack": {
    "frameworks": ["next", "react"],
    "database": ["postgres", "prisma"],
    "auth": ["clerk"],
    "styling": ["tailwind"],
    "language": ["typescript"],
    "testing": ["vitest", "playwright"]
  },
  "skills": {
    "installed": ["flydocs-workflow", "next-best-practices"],
    "custom": ["internal-api-patterns"]
  },
  "topology": {
    "type": 3,
    "label": "multi-repo",
    "siblings": ["acme/api-server", "acme/mobile-app"]
  }
}

For local tier, many fields are omitted. A minimal local config looks like this: