Build paths

1. MyOS + Blink

The easiest entry point. Describe the interaction you want in natural language.

Blink turns that into Blue-backed blocks in MyOS. This is the right path if you want speed, zero setup, a visual or conversational interface, and working examples quickly.

When to use MyOS

• You want to see Blue ideas land in a usable product immediately.
• You want identity, timelines, processing, and a UI to come for free.
• You want to prototype a world with non-technical participants.
• You will move into SDK or raw Blue later, after inspecting the generated documents.

2. JavaScript SDK

If you want programmatic control but still want ergonomic APIs, use the SDK. The SDK path is right when you want backend integration, automation, tests, type safety, and your own runtime around Blue blocks.

When to use the SDK

• You are integrating Blue into an existing service or worker.
• You want unit tests around document evolution.
• You want to process documents yourself, not via a hosted runtime.
• You want type-safe access to BlueId, parsing, and the document processor.

Install the published packages:

npm install @blue-labs/language @blue-labs/document-processor @blue-repository/types

Run the verified Counter document:

import { Blue } from "@blue-labs/language";
import {
  DocumentProcessor,
  ContractProcessorRegistryBuilder,
  createDefaultMergingProcessor,
} from "@blue-labs/document-processor";
import { repository } from "@blue-repository/types";

const blue = new Blue({
  repositories: [repository],
  mergingProcessor: createDefaultMergingProcessor(),
});

const registry = ContractProcessorRegistryBuilder.create()
  .registerDefaults()
  .build();

const processor = new DocumentProcessor({ blue, registry });

const document = blue.yamlToNode(`
name: Demo Counter
counter: 0
contracts:
  ownerChannel:
    type: Conversation/Timeline Channel
    timelineId: owner-1
  increment:
    type: Conversation/Operation
    channel: ownerChannel
    request:
      type: Integer
  incrementHandler:
    type: Conversation/Sequential Workflow Operation
    operation: increment
    steps:
      - name: ApplyIncrement
        type: Conversation/Update Document
        changeset:
          - op: replace
            path: /counter
            val: ${event.message.request + document('/counter')}
`);

const init = await processor.initializeDocument(document);

const event = blue.jsonValueToNode({
  type: "Conversation/Timeline Entry",
  timeline: { timelineId: "owner-1" },
  message: {
    type: "Conversation/Operation Request",
    operation: "increment",
    request: 1,
  },
});

const result = await processor.processDocument(init.document, event);
// result.document is the next state, result.totalGas is the gas consumed,
// result.triggeredEvents are any side-effect events emitted by the workflow.

The example APIs above are real and stable enough for documentation. Specific helpers around higher-level wrappers (MyOS clients, hosted timelines) may evolve as the SDK grows.

3. Raw Blue

If you want full control, you can author Blue directly. This is the right path when you want exact structure, custom documents, protocol-level understanding, and no abstraction between you and the language.

When to use raw Blue

• You are designing a new contract pattern that does not exist in repo.blue yet.
• You want to read or audit a document the SDK or Blink generated.
• You are building tests, fixtures, or examples for the docs and stepper.
• You want the deepest understanding of the language.

name: Demo Counter
counter: 0
contracts:
  ownerChannel:
    type: Conversation/Timeline Channel
    timelineId: owner-1
  increment:
    type: Conversation/Operation
    channel: ownerChannel
    request:
      type: Integer
  incrementHandler:
    type: Conversation/Sequential Workflow Operation
    operation: increment
    steps:
      - name: ApplyIncrement
        type: Conversation/Update Document
        changeset:
          - op: replace
            path: /counter
            val: ${event.message.request + document('/counter')}

The same Counter at three depths

The same document can be expressed via Blink, the SDK, or raw YAML. The protocol-level shape is identical.

How to move between paths

This is one of the most important design goals of Blue: different entry points, one model.

• Start with Blink, then click through to the underlying YAML.
• Take that YAML into the document stepper to watch it process.
• Drop the same YAML into the SDK to embed processing into your own service.
• When a pattern stabilizes, contribute it to repo.blue so others can reference it by BlueId.

Recommended progression

If you are new:

1. Start with MyOS + Blink.
2. Read the mental model pages.
3. Inspect the generated block in code or YAML.
4. Move into the SDK or raw Blue as needed.

If you are already technical:

1. Read the mental model.
2. Open the document stepper.
3. Build one world with the SDK.
4. Read the spec only when you need exact semantics.