Get started

Guides

End-to-end walkthroughs. Each one takes you from a system you run to a governed action with a receipt. Every guide is copy-and-go: real commands, real config, no placeholders. Pick one and ship it.

All guides #

Complete guides are inline on this page. Guides marked in progress are being written against the same contract and will land here as they finish.

Connect a system #

Sensing starts with a connection. A connector is how Fibric plugs into a real system: a CRM, a building controller, a warehouse WMS, a Magento store. Connectors are built on MCP and expose their capabilities as tools. You reach a system through a capability, not a brand. So swapping one vendor for another later is config, not a rewrite.

Install a connector from the marketplace, then create a connection that holds the credentials for your specific account.

# browse what's available, then install a connector
fibric marketplace search "support inbox"
fibric connector install kustomer

# create a connection. credentials live in the vault, never in code
fibric connection create \
  --connector kustomer \
  --name "support-prod" \
  --secret KUSTOMER_API_KEY=$KUSTOMER_API_KEY

# verify the connection can reach the system
fibric connection test support-prod

A healthy connection reports the capabilities it exposes. These are what an operator will be allowed to sense and act through.

{
  "connection": "support-prod",
  "connector": "kustomer",
  "status": "healthy",
  "capabilities": [
    "conversation.read",
    "conversation.note.write",
    "customer.read"
  ]
}

Define an operator #

An operator is a named AI worker that runs one operation: an order-risk watcher, a comfort tuner, a triage analyst. It senses through the capabilities you grant it, reasons with a base model, and proposes an ExecutionPlan. Then the executor, a deterministic check, approves or blocks that plan against your policy. The model never acts directly. You approve every step that has a side effect.

Operators are declared in a small manifest. Grant only the capabilities the job needs, and mark side-effecting steps so they route through the governed executor.

# operator.yaml: an order-risk watcher for a paper & print company
operator: order-risk-watcher
description: Flag orders that will not ship on time, before the carrier scans.

# what it is allowed to sense (read) and act through (write)
capabilities:
  read:
    - order.read
    - shipment.read
  write:
    - conversation.note.write   # leave an internal note
    - order.hold                # side-effecting: routes via the executor

# the base model that does the reasoning
model: fibric/reason-1

# how often it runs. on-event or on a schedule.
trigger:
  schedule: "every 30m"

Deploy it. The operator now runs on its trigger, senses through its connections, and proposes plans, but every side-effecting step waits for the executor and your policy.

fibric operator deploy ./operator.yaml --connection support-prod

# watch it think and propose, without letting it act yet
fibric operator run order-risk-watcher --dry-run

Write a trust policy #

A trust policy is the deterministic gate every action passes through. Policies are fail-closed: anything a rule does not explicitly allow is refused. The model proposes; the policy approves or blocks. This is how a runaway action, the classic 657-message flood, becomes structurally impossible rather than merely unlikely.

Policies are plain, reviewable rules. Allow what the operation needs, cap what could run away, and require a human for anything irreversible.

# policy.yaml: governs the order-risk-watcher
policy: order-risk-guardrails
applies_to: order-risk-watcher

rules:
  # allow internal notes freely
  - allow: conversation.note.write

  # holding an order is allowed, but rate-limited and single-flight
  - allow: order.hold
    limit:
      per: hour
      max: 25            # a flood cannot exceed this
    single_flight: order_id   # never two holds in flight for one order

  # anything touching money needs a person to confirm
  - require_confirmation: refund.issue

# default is deny. nothing not listed above can act.
default: deny

Attach the policy and validate it before it ever sees a live plan. Validation is static: it tells you what the operator can and cannot do, without running anything.

fibric policy apply ./policy.yaml
fibric policy validate order-risk-guardrails --against order-risk-watcher

Guard a refund flow #

Refunds are the canonical case for value-aware policy: most are routine, a few are large enough to deserve a person, and anything the operator invents on its own should never run. This guide writes that policy as a TrustPolicy array and walks three proposals through it: a $180 refund that runs, a $900 refund that escalates, and an account credit that is blocked because no rule mentions it.

Each policy in the array matches by connector and tool (leaving either undefined matches any), can carry a maxValue cap that reads the action's value field, and declares a decision: ALLOW, ALERT, or BLOCK. Evaluation is default-closed. An action with no matching policy is blocked; you do not write the blocking rule, you get it by omission.

import type { TrustPolicy } from "@fibric/sdk";

// governs the refund-guard operator. everything not listed here is
// blocked by omission: there is no "allow the rest" rule to forget.
export const policies: TrustPolicy[] = [
  // refunds at or under $250 run without a person in the loop
  {
    connector: "payments",
    tool: "refunds.create",
    maxValue: 250,
    decision: "ALLOW",
  },
  // refunds above $250 stop and page a human instead of running
  {
    connector: "payments",
    tool: "refunds.create",
    predicate: (action) => (action.value ?? 0) > 250,
    decision: "ALERT",
  },
];

The operator proposes refunds as PlannedAction entries inside its ExecutionPlan. Note the two keys every side-effecting action carries: entity_key serializes work per order so two runs cannot both touch SO-10884, and idempotency_key makes a retry collapse into the original instead of refunding twice. The value field is what maxValue reads.

{
  "reasoning": "Three make-goods owed after the reprint delay on 2026-06-28.",
  "actions": [
    {
      "connector": "payments",
      "tool": "refunds.create",
      "args": { "order": "SO-10884", "reason": "reprint-delay" },
      "value": 180,
      "entity_key": "order:SO-10884",
      "idempotency_key": "refund-guard:SO-10884:refund"
    },
    {
      "connector": "payments",
      "tool": "refunds.create",
      "args": { "order": "SO-10891", "reason": "reprint-delay" },
      "value": 900,
      "entity_key": "order:SO-10891",
      "idempotency_key": "refund-guard:SO-10891:refund"
    },
    {
      "connector": "payments",
      "tool": "credits.apply",
      "args": { "account": "AC-2210", "amount": 50 },
      "value": 50,
      "entity_key": "account:AC-2210",
      "idempotency_key": "refund-guard:AC-2210:credit"
    }
  ]
}

The deterministic executor evaluates each action against the policy array before anything touches the payment system. The three actions land three different ways.

1. $180 refund: ALLOW.

   The refund policy matches on connector and tool, the value is inside the $250 cap, and the decision is ALLOW. The action runs immediately and leaves a receipt recording the rule that passed it.

2. $900 refund: ALERT.

   The value is above the routine band, so the escalation rule decides: ALERT. The action does not run. It is parked for human approval with the operator's reasoning attached, and the receipt records the pending disposition. A person approves or declines it from the console or CLI; approval executes the original action under its original idempotency key.

3. $50 account credit: BLOCK.

   No policy in the array mentions credits.apply. No match means BLOCK, fail closed. The operator was never granted the ability to invent a new kind of compensation, so the proposal is refused and receipted, and nothing reaches the payment system.

Connect Amazon Connect call audio #

The cn-amazon-connect connector senses your Amazon Connect instance's contact events stream, its contact trace records, and the call recordings that land in the instance's S3 bucket. Acting, it syncs call status onto the customer record idempotently and updates contact attributes within limits. This guide takes you from an untouched Connect instance to contact events arriving in Fibric and call status landing on the Kustomer customer timeline.

Prerequisites #

• An Amazon Connect instance with call recording writing to its S3 bucket.
• Permission to create an IAM role in the AWS account that owns the instance.
• For the timeline step: the cn-kustomer connector already installed (see Connect a system).

Enable the contact event stream #

In the Amazon Connect console, enable the contact event stream for your instance. This is the feed the connector senses: contact initiated, connected, and disconnected events, plus the contact trace records that follow each call. Recordings continue landing in your S3 bucket exactly as they do today; Fibric reads them there rather than copying them out.

Create the cross-account IAM role #

Authentication is a cross-account IAM role scoped to the Connect instance and the recording bucket. No long-lived keys leave your account: Fibric assumes the role for each read, and revoking access is deleting the role. Scope the policy to exactly the instance ARN and the recording bucket prefix.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SenseContactEvents",
      "Effect": "Allow",
      "Action": ["connect:DescribeContact", "connect:ListContactEvents"],
      "Resource": "arn:aws:connect:us-east-1:111111111111:instance/YOUR_INSTANCE_ID/*"
    },
    {
      "Sid": "ReadRecordings",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::your-connect-recordings",
        "arn:aws:s3:::your-connect-recordings/connect/*"
      ]
    }
  ]
}

Install the connector #

Add the connector and bind it to the telephony role. Operators ask for telephony capabilities, not for Amazon Connect by name, so a future move to another voice platform is a rebinding, not a rewrite.

# install and bind to the telephony role
fibric connectors add amazon-connect --as telephony

# supply the role Fibric should assume, then confirm what it exposes
fibric connectors configure amazon-connect \
  --role-arn arn:aws:iam::111111111111:role/fibric-connect-reader
fibric capabilities ls

Verify contact events are arriving #

Place or receive a test call, then tail the event stream. Each contact event arrives as a tenant-scoped envelope; the recording reference resolves to the object in your bucket.

fibric events tail --source amazon-connect

Bind status-sync to the customer timeline #

The last step closes the loop: calls.status-sync writes call status onto the customer record, and the cn-kustomer connector works with it, so an agent opening a Kustomer conversation sees the call on the customer timeline. The sync is idempotent; a replayed contact event updates the same timeline entry rather than duplicating it.

# call status flows from amazon-connect onto the kustomer customer record
fibric capabilities bind calls.status-sync --connector kustomer

Review receipts & audit #

Every action Fibric takes leaves a receipt: what was proposed, which rule allowed it, the idempotency key that made it run exactly once, and the result. Receipts are not a log you opt into. They are the record of the action itself. If it is not in the receipt ledger, it did not happen.

List recent receipts for an operator, then open one to see the full chain from proposal to disposition.

# the last 24h of actions taken by this operator
fibric receipts list --operator order-risk-watcher --since 24h

# open one receipt in full
fibric receipts show rcpt_8f2a91c4

{
  "receipt": "rcpt_8f2a91c4",
  "operator": "order-risk-watcher",
  "action": "order.hold",
  "entity": "order:SO-44817",
  "idempotency_key": "order.hold:SO-44817:2026-06-13",
  "proposed_by": "fibric/reason-1",
  "reason": "Proof not approved + ship-by in 18h; will miss carrier cutoff.",
  "policy": { "rule": "allow order.hold", "decision": "allow" },
  "single_flight": "acquired",
  "result": "ok",
  "tenant_id": "t_paperco",
  "at": "2026-06-13T14:22:07Z"
}

Add a connector to the marketplace #

Built a connector for a system the marketplace does not cover yet? Publish it so any workspace can install it. A connector is defined with the SDK (see SDKs & CLI), declares the capabilities it provides, and is packaged with a manifest the marketplace reads.

The lifecycle is five steps:

1. Scaffold.

   Generate a connector project from the template, then implement your tools against the system's API.

2. Declare capabilities.

   Map each tool to a capability such as order.read so operators bind to the capability, not your brand.

3. Validate.

   Run the conformance check. It confirms auth works, side-effecting tools are marked, and every tool is reachable.

4. Publish.

   Push a versioned build to the marketplace as private (your workspace) or public (everyone).

5. Maintain.

   Ship new versions with semver. Installs pin a version, so an update never silently changes behavior.

# scaffold a new connector
fibric connector scaffold acme-wms --lang ts

# validate it meets the marketplace contract
fibric connector validate ./acme-wms

# publish a version (private to your workspace, or --public)
fibric connector publish ./acme-wms --version 0.1.0 --private

Once published, your connector behaves exactly like a first-party one: installable from the marketplace, bound by capability, and governed by the same policies and receipts as everything else on Fibric.