Reference for the graph.manifest.json file that describes your graph.

Overview

The graph.manifest.json file describes your graph:

Identity - Graph name and company
Metadata - Title, description, discovery
Versions - Which versions are available
Visibility - Who can see and use the graph

This file is used during flutch graph deploy to register your graph.

The manifest describes the graph itself, not agent configurations.

Basic Structure

json
{
  "companySlug": "acme-corp",
  "name": "support-workflow",
  "title": "Support Workflow",
  "description": "Customer support workflow with docs search",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0"]
  },
  "versions": {
    "1.0.0": {
      "status": "stable",
      "visibility": "public"
    }
  }
}

Required Fields

companySlug

Your company identifier on Flutch.

json
"companySlug": "acme-corp"

Rules:

Lowercase letters, hyphens only
Must match your Flutch account
Assigned during onboarding

Forms graph type: acme-corp.support::1.0.0

name

Unique graph identifier within your company.

json
"name": "support-workflow"

Rules:

Lowercase letters, numbers, hyphens
Unique within company
Stable (rarely change)

Forms graph type: acme-corp.support-workflow::1.0.0

title

Human-readable name for console UI.

json
"title": "Support Workflow"

Keep under 50 characters.

description

Short description of what the graph does.

json
"description": "Customer support workflow with knowledge base search"

1-3 sentences, under 200 characters.

Optional Fields

icon

Emoji or URL for graph avatar.

json
"icon": "🤖"

Versioning

Configuration

json
{
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0", "1.1.0"]
  }
}

strategy: Always "semver"

defaultVersion: Version used when not specified by agent

supportedVersions: List of active versions

Example: Multiple Versions

json
{
  "versioning": {
    "defaultVersion": "2.0.0",
    "supportedVersions": ["1.5.0", "2.0.0", "2.1.0-beta"]
  },
  "versions": {
    "1.5.0": {
      "status": "deprecated",
      "visibility": "public",
      "changelog": "Migrate to 2.0.0 by June 1st"
    },
    "2.0.0": {
      "status": "stable",
      "visibility": "public",
      "changelog": "Complete redesign, 40% faster"
    },
    "2.1.0-beta": {
      "status": "beta",
      "visibility": "private",
      "changelog": "Testing new features"
    }
  }
}

Version Metadata

Each version needs metadata in versions object:

json
"versions": {
  "1.0.0": {
    "status": "stable",
    "visibility": "public",
    "changelog": "Initial release"
  }
}

status

Values: "stable", "beta", "deprecated"

stable - Production ready
beta - Testing, may change
deprecated - Scheduled for removal

visibility

Values: "private", "corporate", "public"

private - Visible only to creator (for testing)
corporate - Visible to all company admins
public - Visible to all Flutch users

changelog (optional)

What changed in this version:

json
"changelog": "Added French support, improved response time by 20%"

Complete Examples

Simple Single Version

json
{
  "companySlug": "acme",
  "name": "support-workflow",
  "title": "Support Workflow",
  "description": "Customer support with docs search",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0"]
  },
  "versions": {
    "1.0.0": {
      "status": "stable",
      "visibility": "public"
    }
  }
}

Multiple Versions

json
{
  "companySlug": "techcorp",
  "name": "support-workflow",
  "title": "Support Workflow",
  "description": "Customer support with knowledge base",
  "icon": "🎧",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "2.0.0",
    "supportedVersions": ["1.5.0", "2.0.0", "2.1.0-beta"]
  },
  "versions": {
    "1.5.0": {
      "status": "deprecated",
      "visibility": "public",
      "changelog": "Legacy version. Migrate to 2.0.0 by May 1st"
    },
    "2.0.0": {
      "status": "stable",
      "visibility": "public",
      "changelog": "Complete redesign, 40% faster, multilingual"
    },
    "2.1.0-beta": {
      "status": "beta",
      "visibility": "private",
      "changelog": "Testing new knowledge base integration"
    }
  }
}

Validation

Validate before deploying:

bash
flutch graph validate

Common Errors

Missing required fields:

bash
Error: Missing required field 'companySlug'

Fix: Add all required fields

Invalid version format:

bash
Error: Version '1.0' does not follow semver

Fix: Use MAJOR.MINOR.PATCH: 1.0.0

Version mismatch:

bash
Error: defaultVersion '1.1.0' not in supportedVersions

Fix: Ensure defaultVersion is in supportedVersions

Missing metadata:

bash
Error: Version '1.0.0' missing from versions object

Fix: Add entry in versions for each supportedVersions