Connector Recipes (`fh add`)

Pipe Markdown connector recipes into Claude / Codex / Cursor / Aider / OpenCode and have them scaffold a Fabric Harness sandbox, MCP, knowledge-base, or data adapter into your project.

fabric-harness add (alias fh add) supports direct scaffold recipes and TTY-aware Markdown connector guides. Use a scaffold when Fabric owns the file shape; use a guide when provider SDK versions, authentication, or project conventions need local adaptation.

Recipes today are thin wiring on top of the package helpers — the package owns the tested implementation, the recipe wires it into your specific project layout, env vars, and lifecycle. For most providers you can also import the helper directly without scaffolding (see Connector catalog).

Common usage

# List all available recipes (and the agent the CLI auto-detected for you)
fh add
fh add --json

# Scaffold implementation + env example + test
fh add slack
fh add modal
fh add channel slack
fh add channel discord
fh add database postgres
fh add databricks lakebase
fh add lakehouse
fh add sandbox e2b --dir ./service
fh add policy safe-defaults
fh add channel slack --no-install
fh add channel slack --dry-run

# Review and apply a managed upgrade
fh update slack --dry-run
fh update channel slack --dry-run
fh update channel slack

# Pipe a known recipe to your coding agent
fh add daytona | claude
fh add github-mcp | codex
fh add discord --install-deps | codex
fh add mintlify-mcp | cursor-agent
fh add fumadocs | aider

# Build a brand-new connector from a provider's docs URL
fh add https://e2b.dev --category sandbox | claude

# Print the markdown without piping (for inspection)
fh add daytona --print

For a unique managed alias, fh add <name> installs the recipe. Use --print to request the legacy Markdown guide explicitly. Names without a managed recipe retain the TTY-aware guide behavior.

Categories

Direct scaffold kinds:

Kind	Current recipes
`channel`	18 maintained provider adapters plus generic webhook
`database`	Postgres, MySQL, MongoDB, Redis, SQLite, libSQL, Turso, Supabase, Valkey
`sandbox`	Daytona, E2B, Modal, Vercel, Cloudflare Sandbox, Cloudflare Shell, Boxd, exe.dev, Islo, Mirage, smolvm
`databricks`	core, sql, lakebase, ai-search, rag-chain, lakeflow, jobs, system-tables-cost, apps, agent-services, genie, analyst (see Databricks recipes)
`tooling`	Braintrust, Jetty, OpenTelemetry, Sentry, Vitest Evals
`model-provider`	OpenAI, Azure OpenAI
`skill`	Analyze table
`policy`	Safe defaults

Connector-guide categories:

The Markdown recipes are grouped into four categories that map to Fabric Harness primitives:

Category	Maps to	Examples
`sandbox`	`SandboxFactory`	Daytona, E2B, Modal, Vercel Sandbox
`mcp`	`connectMcpServer`	GitHub, Linear, Mintlify, Slack
`kb`	`FilesystemSource`	Fumadocs (also `localDirectorySource`, `r2FilesystemSource`, `s3FilesystemSource`, `azureBlobFilesystemSource`, `httpFilesystemSource` in the SDK)
`data`	`Command` / `ToolDef`	Postgres, Notion REST
`channel`	`Channel` + outbound `ToolDef`	Discord, Messenger, Slack, Stripe, Teams, and the remaining channel catalog
`database`	Scoped data tools and first-party unified persistence	libSQL/Turso, MongoDB, MySQL, Redis/Valkey, Supabase/Postgres
`tooling`	Event/eval integration	Braintrust, Jetty, OpenTelemetry, Sentry, Vitest evals

Auto-detected coding agents

fh add detects the agent you're running under and shows the matching pipe hint:

Detected	Pipe hint
Claude Code (`CLAUDE_CODE`, `CLAUDE_PROJECT_DIR`)	`\| claude`
OpenAI Codex (`CODEX_AGENT`, `CODEX_HOME`)	`\| codex`
Cursor Agent (`CURSOR_AGENT`, `CURSOR_TRACE_ID`)	`\| cursor-agent`
Aider (`AIDER_RUNNING`)	`\| aider`
OpenCode (`OPENCODE`)	`\| opencode`
(none detected)	`\| claude` (canonical default)

Override by passing --print and piping yourself.

Versions and safe updates

Direct scaffolds declare aliases, a positive recipe version, compatible package ranges, managed files, upgrade notes, and package-manager-specific verification commands. Generated TypeScript and Markdown begin with fabric-harness-recipe: <kind>/<name>@<version>.

fh update reads those markers and creates a complete plan before changing the project. It adopts unmarked legacy files only when they exactly match generated content, stops on user modifications, preserves compatible dependency ranges, and rejects ranges that cannot overlap the recipe contract. Use --dry-run --json in CI or automation.

URL-form recipes

When you pass a URL instead of a known recipe name, fh add emits a generic "scaffold a connector from these docs" prompt. The agent then fetches the URL and writes the adapter:

fh add https://docs.modal.com --category sandbox | claude
fh add https://api.intercom.io --category data | codex

The receiving agent gets:

The docs URL.
The category (so it knows whether to produce a SandboxFactory, connectMcpServer call, FilesystemSource, or Command/ToolDef).
A short template showing the file shape and the secret(<env-var>) pattern for credentials.

Where the recipes live

Direct scaffold recipes are typed definitions and ship with the CLI. Connector guides are Markdown files with local and bundled lookup:

Recipes are Markdown files in connectors/ at the repo root. The CLI looks for them in:

The user's current project (walking up to find ./connectors/<file>.md)
The CLI's own bundled copy (when developing this repo locally) The installed CLI's managed recipes work without cloning the source repository. Repository-only guides and authoring files require source access; public documentation does not link to the restricted raw GitHub origin.

Authoring a new recipe

For a direct scaffold, add a typed recipe with a version, dependency ranges, managed files, and a verification command.
For a guide, create connectors/<category>--<name>.md. Use the existing guides as templates: short, agent-friendly, no secrets.
Add guide metadata to CONNECTOR_RECIPES in packages/cli/bin/fabric-harness.ts.
Add clean-install and update/conflict fixtures when changing generated files or dependencies.
Open a change through the authorized source workflow. Once released, the direct recipe alias and its bundled guide are available from the installed CLI.