### Development Setup

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/CONTRIBUTING.md

Clone the repository, install dependencies, and run initial type checking.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install
npx turbo run typecheck
```

--------------------------------

### Provider Setup for OpenCode

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

Install the OpenCode SDK and verify its installation before registering agents with the `opencode` provider.

```bash
# Install OpenCode
npm install -g @opencode-ai/sdk

# Verify it's working
opencode --version

# Register agents with OpenCode provider
sf agent register e-worker-2 --role worker --provider opencode
```

--------------------------------

### Install and Initialize Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/introducing-stoneforge.mdx

Install the Stoneforge CLI globally, navigate to your project directory, and initialize a new Stoneforge project. Then, start the development server.

```bash
npm install -g @stoneforge/smithy
cd your-project
sf init
sf serve
```

--------------------------------

### Install and Initialize Stoneforge CLI

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Install the Stoneforge CLI globally using npm or pnpm. Then, initialize a workspace in your project directory and start the server.

```bash
# Install via npm or pnpm
npm install -g @stoneforge/smithy
# or
pnpm add -g @stoneforge/smithy

# Initialize workspace in your project (creates .stoneforge/ directory)
cd your-project
sf init

# Start the server and web dashboard at http://localhost:3457
sf serve

# Check system health
sf doctor
# Output:
# [OK] workspace: Workspace found at /Users/you/my-project/.stoneforge
# [OK] database: Database connection successful
# [OK] schema_version: Schema is at version 9 (up to date)
# Summary: 9 ok, 0 warnings, 0 errors
```

--------------------------------

### Install, Initialize, and Serve Stoneforge

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/use-cases/free-open-source-ai-coding.mdx

Use these bash commands to install the Stoneforge CLI globally, initialize it in your project directory, and start the orchestration server. Ensure you have Node.js and npm installed.

```bash
# Install globally
npm install -g @stoneforge/smithy

# Initialize in your project
cd your-project
sf init

# Start the orchestration server
sf serve
```

--------------------------------

### Stoneforge CLI Installation and Initialization

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Instructions for installing the Stoneforge CLI globally and initializing a workspace in a git repository. Also includes commands to start the server and check system health.

```APIDOC
## Installation

Install the Stoneforge CLI globally and initialize a workspace in any git repository.

```bash
# Install via npm or pnpm
npm install -g @stoneforge/smithy
# or
pnpm add -g @stoneforge/smithy

# Initialize workspace in your project (creates .stoneforge/ directory)
cd your-project
sf init

# Start the server and web dashboard at http://localhost:3457
sf serve

# Check system health
sf doctor
```

### Output Example for `sf doctor`
```
[OK] workspace: Workspace found at /Users/you/my-project/.stoneforge
[OK] database: Database connection successful
[OK] schema_version: Schema is at version 9 (up to date)
Summary: 9 ok, 0 warnings, 0 errors
```
```

--------------------------------

### Quick Start: Create and Initialize Storage

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

Create a storage instance, which auto-detects the runtime, and then initialize the database schema. This example demonstrates synchronous operations.

```typescript
import { createStorage, initializeSchema } from '@stoneforge/storage';

// Auto-detects runtime (Bun, Node, or browser)
const storage = createStorage({ path: './data.db' });

// Run migrations to set up tables
initializeSchema(storage);

// Query rows
const tasks = storage.query('SELECT * FROM elements WHERE type = ?', ['task']);

// Insert a row
const result = storage.run(
  'INSERT INTO elements (id, type, data, created_at, updated_at, created_by) VALUES (?, ?, ?, ?, ?, ?)',
  ['el-1', 'task', '{}', new Date().toISOString(), new Date().toISOString(), 'system']
);
console.log(result.changes); // 1
```

--------------------------------

### Create a Deployment Playbook Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Example of creating a playbook named 'deploy' with specific steps and variables.

```bash
# Create a deployment playbook
sf playbook create -n deploy -t "Deployment Process" \
  -s "build:Build app" \
  -s "test:Run tests:build" \
  --variable "env:string" \
  --variable "debug:boolean:false:false"
```

--------------------------------

### External Sync Configuration Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples demonstrating how to set tokens, projects, and auto-link settings for GitHub and Linear.

```bash
sf external-sync config set-token github ghp_xxxxxxxxxxxx
```

```bash
sf external-sync config set-token linear lin_api_xxxxxxxxxxxx
```

```bash
sf external-sync config set-project github org/repo
```

```bash
sf external-sync config set-auto-link github
```

```bash
sf external-sync config disable-auto-link --type document
```

--------------------------------

### Install @stoneforge/core

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/core/README.md

Install the core package using npm.

```bash
npm install @stoneforge/core
```

--------------------------------

### Install @stoneforge/storage

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

Install the core package using npm.

```bash
npm install @stoneforge/storage
```

--------------------------------

### Install and Initialize Stoneforge

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/run-multiple-ai-coding-agents-parallel.mdx

Commands to clone the Stoneforge repository, install dependencies, link it globally, and then initialize it within your project.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
bun install
bun link

```

```bash
cd your-project
sf init

```

--------------------------------

### Install and Initialize Stoneforge

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/integrations/opencode.mdx

Install the Stoneforge CLI globally and then initialize it within your project directory. This prepares your project for Stoneforge orchestration.

```bash
# Install Stoneforge
npm install -g @stoneforge/cli

# Initialize in your project
sf init

# Configure for OpenCode in .stoneforge/config.yaml
# Start orchestrating
sf serve
```

--------------------------------

### Install Stoneforge CLI from source

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Clone the Stoneforge repository, install dependencies, build the project, and link the CLI globally.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install && pnpm build
pnpm link --global --filter @stoneforge/quarry
```

--------------------------------

### Install @stoneforge/ui Package

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/ui/README.md

Install the core UI package using npm. Ensure peer dependencies are also installed.

```bash
npm install @stoneforge/ui
```

```bash
npm install react react-dom @tanstack/react-query @tanstack/react-router
```

--------------------------------

### Provider Setup for Codex

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

Register agents with the `codex` provider. Ensure the `codex` CLI tool is installed separately.

```bash
# Register agents with Codex provider
sf agent register e-worker-3 --role worker --provider codex
```

--------------------------------

### Install Optional Provider

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

For additional providers like OpenCode, install the corresponding optional dependency.

```bash
# OpenCode provider
npm install @opencode-ai/sdk
```

--------------------------------

### Install and Serve Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/tools/seo/output/directory-submissions.md

Install the Stoneforge CLI globally using npm and then initialize and serve the application. Access the running instance at http://localhost:3457.

```bash
npm install -g @stoneforge/smithy
sf init
sf serve
```

--------------------------------

### Install @stoneforge/smithy

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

Install the main package using npm. The default Claude provider is included.

```bash
npm install @stoneforge/smithy
```

--------------------------------

### Start the Daemon

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/auto-dispatch.mdx

Use this command to start the Stoneforge daemon process.

```bash
sf daemon start
```

--------------------------------

### Install Stoneforge and Initialize for Codex

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/integrations/codex.mdx

Install the Stoneforge CLI globally and initialize a new project. After initialization, update the `.stoneforge/config.yaml` file to specify the 'codex' provider for your agents.

```bash
# Install Stoneforge
npm install -g @stoneforge/cli

# Initialize and configure for Codex
sf init

# Update .stoneforge/config.yaml to use codex provider
# Start orchestrating
sf serve
```

--------------------------------

### Install Stoneforge CLI with npm

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Use npm to install the Stoneforge CLI globally on your system.

```bash
npm install -g @stoneforge/quarry
```

--------------------------------

### sf install skills

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Installs Claude skills files to the `.claude/skills/` directory.

```APIDOC
## `sf install skills`

### Description
Installs Claude skills files to `.claude/skills/`. Use `--force` to overwrite existing files.

### Usage
```bash
sf install skills [--force]
```

### Parameters
#### Query Parameters
- **force** (boolean) - Optional - Overwrites existing files if true.
```

--------------------------------

### Install @stoneforge/quarry

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/quarry/README.md

Install the core SDK using npm. This command adds the package to your project's dependencies.

```bash
npm install @stoneforge/quarry
```

--------------------------------

### Clone and Install Stoneforge Dependencies

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Instructions for cloning the Stoneforge repository and installing development dependencies using pnpm.

```bash
# Clone the repository
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge

# Install dependencies (uses pnpm)
pnpm install
```

--------------------------------

### Install Node.js/Browser Dependencies

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

For Node.js or browser environments, install the corresponding optional dependencies.

```bash
# Node.js
npm install better-sqlite3

# Browser
npm install sql.js
```

--------------------------------

### Push Linked Elements Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples of pushing a single element, all elements, and all tasks with force.

```bash
sf external-sync push el-abc123
```

```bash
sf external-sync push --all
```

```bash
sf external-sync push --all --force --type task
```

--------------------------------

### Register and Start a Director Agent

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/agent-roles.mdx

Use these commands to register a new director agent and then start it. The director runs as a persistent session.

```bash
sf agent register director --role director
sf agent start <id>
```

--------------------------------

### Start Stoneforge Server and Dashboard

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Starts the Stoneforge server and makes the web dashboard accessible at http://localhost:3457.

```bash
sf serve
```

--------------------------------

### Start Development Server

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/community/contributing.mdx

Start the development server for the Stoneforge project. Use 'pnpm dev:smithy' for orchestrator services only, or 'pnpm dev' for all services.

```bash
# Orchestrator only (smithy-server + smithy-web)
pnpm dev:smithy

# Everything (all 4 services)
pnpm dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/community/contributing.mdx

Install all necessary project dependencies using pnpm, the monorepo package manager.

```bash
pnpm install
```

--------------------------------

### Install Skills

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Installs Claude skills files to the `.claude/skills/` directory. Use `--force` to overwrite existing files.

```bash
sf install skills [--force]
```

--------------------------------

### Install Stoneforge from Source

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Clone the Stoneforge repository, install dependencies, and build the project from source. This method is useful for developers contributing to Stoneforge or needing the latest unreleased changes.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install
pnpm build
```

--------------------------------

### Install OpenCode Provider

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Install the OpenCode agent provider CLI globally using npm. This is an alternative provider for Stoneforge.

```bash
npm install -g @opencode-ai/sdk
```

--------------------------------

### Start Stoneforge Server

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Starts the Stoneforge server and web dashboard. You can specify the component to serve (orchestrator or data platform) and the port.

```bash
# Start the orchestrator server + dashboard
sf serve
# or explicitly:
sf serve smithy --port 3457
```

```bash
# Start just the Quarry data server
sf serve quarry --port 3456
```

--------------------------------

### Start Stoneforge Development Services

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Commands to start different components of the Stoneforge development environment, including the orchestrator and the full stack.

```bash
# Start the orchestrator (most common)
pnpm dev:smithy

# Start everything (all 4 services)
pnpm dev

# Start just the data platform (quarry only)
pnpm dev:platform
```

--------------------------------

### Plan Creation and Task Management Workflow

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

This example demonstrates a recommended workflow for managing plans and tasks: creating a plan, adding tasks, setting dependencies, and activating the plan.

```bash
# Recommended workflow
sf plan create --title "Feature X"                        # 1. Create (draft)
sf create task --title "Task 1" --plan "Feature X"        # 2. Add tasks
sf dependency add --type=blocks el-task2 el-task1          # 3. Set deps
sf plan activate <plan-id>                                 # 4. Activate
```

--------------------------------

### Observe Daemon and Worker Activity

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/run-multiple-ai-coding-agents-parallel.mdx

Example logs showing the daemon dispatching tasks to workers and workers starting in their respective worktrees.

```text
[daemon] Dispatching "Refactor auth module" → e-worker-1
[daemon] Dispatching "Fix integration tests" → e-worker-2
[daemon] Dispatching "Add /api/v2/users endpoint" → worker-3

[e-worker-1] Starting in worktree: .stoneforge/.worktrees/e-worker-1-auth/
[e-worker-2] Starting in worktree: .stoneforge/.worktrees/e-worker-2-tests/
[worker-3] Starting in worktree: .stoneforge/.worktrees/worker-3-users/
```

--------------------------------

### Provider Setup for Claude Code

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

If the `claude` CLI is already set up, you can register agents for Claude Code without needing to specify the provider. Verify the CLI installation first.

```bash
# Verify Claude Code is working
claude --version

# Register agents (claude-code is the default, no --provider needed)
sf agent register director --role director
sf agent register e-worker-1 --role worker
```

--------------------------------

### Ephemeral Worker Worktree and Branch Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/worktree-isolation.mdx

Illustrates the directory path for an ephemeral worker's worktree and its corresponding git branch name. This setup ensures each task has a unique, isolated environment.

```shell
Worktree: .stoneforge/.worktrees/e-worker-1-implement-login/
Branch:   agent/e-worker-1/el-3a8f-implement-login
```

--------------------------------

### Runtime Detail Configuration Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Illustrates the configuration details displayed for a runtime, including mode, host, mode-specific settings, and timestamps.

```text
- Mode: Worktree / Docker
- Host: {host name} — {os} {arch}
- Worktree Path or Docker Image (mode-specific)
- Created: timestamp
- Last Health Check: timestamp
```

--------------------------------

### Install Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Installs the Stoneforge command-line interface globally. Ensure Node.js 18+ or Bun is installed.

```bash
npm install -g @stoneforge/smithy
```

--------------------------------

### Initialize Documentation Library

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Bootstraps the Documentation library and directory for a workspace. This operation is idempotent.

```bash
sf docs init [--json] [--quiet]
```

--------------------------------

### sf embeddings install

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Installs a local model for embeddings.

```APIDOC
## `sf embeddings install`

### Description
Installs a local model for embeddings.

### Usage
```bash
sf embeddings install
```
```

--------------------------------

### Get top-level help

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Display general help information for the Stoneforge CLI.

```bash
sf --help
```

--------------------------------

### Clone and Initialize Stoneforge Repository

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Steps to clone the Stoneforge repository, install dependencies, and initialize the workspace.

```bash
# Clone the repo
git clone https://github.com/stoneforge-ai/stoneforge
cd stoneforge

# Init Stoneforge (make sure you've globally installed stoneforge NPM package)
pnpm install && sf init

# Start stoneforge server
sf serve
```

--------------------------------

### Install @stoneforge/shared-routes

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/shared-routes/README.md

Install the package using npm. Hono is included as a dependency.

```bash
npm install @stoneforge/shared-routes
```

--------------------------------

### Initialize and Wire Up Services

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/orchestrator-services.mdx

Demonstrates the creation and integration of various services like dependency, cache, priority, and inbox services, including wiring up status transition callbacks.

```typescript
import {
  createDependencyService,
  createBlockedCacheService,
  createPriorityService,
  createInboxService,
  createIdLengthCache,
} from '@stoneforge/quarry';

const depService = createDependencyService(storage);
const blockedCache = createBlockedCacheService(storage);
const priorityService = createPriorityService(storage);
const inboxService = createInboxService(storage);
const idLengthCache = createIdLengthCache(storage);

// Wire up auto-transitions
blockedCache.setStatusTransitionCallback({
  onBlock: (elementId, previousStatus) => {
    storage.run(
      'UPDATE elements SET data = json_set(data, "$.status", ?) WHERE id = ?',
      ['blocked', elementId],
    );
  },
  onUnblock: (elementId, statusToRestore) => {
    storage.run(
      'UPDATE elements SET data = json_set(data, "$.status", ?) WHERE id = ?',
      [statusToRestore, elementId],
    );
  },
});
```

--------------------------------

### CLI: Start and Manage Agents

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Start, list, and stop agents using the 'sf agent' command. Agents can be started with custom prompts and model overrides. List agents with various filters.

```bash
# Start the Director (use ID from register output)
sf agent start <director-id>

# Start with a custom prompt and model override
sf agent start <id> --prompt "Focus on the authentication module" --model claude-opus-4

# List agents (with filters)
sf agent list
sf agent list --role worker --status idle
sf agent list --workerMode ephemeral --hasSession

# Stop an agent
sf agent stop <id>
sf agent stop <id> --no-graceful --reason "Rate limit hit"

# Stream live agent output
sf agent stream <id>

```

--------------------------------

### Runtime List Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Displays a flat list of runtimes with inline host information, including name, mode, host, status, and agent count.

```text
staging-worktree    Worktree   staging-1    ● Online    0 agents
my-macbook          Worktree   adam-macbook ● Online    3 agents   default
docker-sandbox      Docker     adam-macbook ● Online    1 agent
gpu-docker          Docker     gpu-rack-3   ○ Offline   2 agents
```

--------------------------------

### Initialize Stoneforge Project

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/_template.mdx

Use this command to initialize a new Stoneforge project. Ensure the Stoneforge CLI is installed and accessible in your PATH.

```bash
stoneforge init
```

--------------------------------

### Verify CLI installation

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Check if the Stoneforge CLI is installed correctly by displaying its version.

```bash
sf --version
```

--------------------------------

### Initialize Storage and Quarry API

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/quarry/README.md

Set up the storage backend and initialize the Quarry API. This involves creating a storage instance and then passing it to `createQuarryAPI`.

```typescript
import { createStorage, initializeSchema } from '@stoneforge/storage';
import { createQuarryAPI } from '@stoneforge/quarry/api';
import type { Task } from '@stoneforge/core';

// Create a StorageBackend (auto-detects Bun/Node runtime)
const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);

// Create the API
const api = createQuarryAPI(storage);
```

--------------------------------

### Quick Start with @stoneforge/ui Components and Hooks

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/ui/README.md

Demonstrates basic usage of @stoneforge/ui components like Card and Button, along with hooks for theme management (useTheme) and WebSocket communication (useWebSocket).

```tsx
import '@stoneforge/ui/styles/tokens.css';
import { Button, Card, CardHeader, CardTitle, CardContent } from '@stoneforge/ui';
import { useTheme, useWebSocket } from '@stoneforge/ui/hooks';

function App() {
  const { isDark, toggleDarkMode } = useTheme();
  const { connectionState } = useWebSocket({
    url: 'ws://localhost:3456/ws',
    channels: ['tasks'],
  });

  return (
    <Card>
      <CardHeader>
        <CardTitle>Dashboard</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Connection: {connectionState}</p>
        <Button variant="primary" onClick={toggleDarkMode}>
          {isDark ? 'Light Mode' : 'Dark Mode'}
        </Button>
      </CardContent>
    </Card>
  );
}
```

--------------------------------

### Quick Start: Initialize and Register Agents

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

Initialize storage and the schema, create the OrchestratorAPI, and register a director and an ephemeral worker.

```typescript
import { createOrchestratorAPI } from '@stoneforge/smithy';
import { createStorage, initializeSchema } from '@stoneforge/storage';

// Create a storage backend and initialize the schema
const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);

// Create the OrchestratorAPI (extends QuarryAPI)
const api = createOrchestratorAPI(storage);

// Register a director agent
const director = await api.registerDirector({
  name: 'lead',
  createdBy: humanEntityId,
});

// Register an ephemeral worker
const worker = await api.registerWorker({
  name: 'dev-1',
  workerMode: 'ephemeral',
  createdBy: director.id,
  reportsTo: director.id,
});

// Assign a task to the worker (auto-generates branch and worktree names)
await api.assignTaskToAgent(taskId, worker.id);
```

--------------------------------

### sf daemon start

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-orchestration.mdx

Starts the dispatch daemon, which automatically assigns tasks to idle workers.

```APIDOC
## sf daemon start

### Description
Starts the dispatch daemon, responsible for auto-assigning tasks to idle workers. This command is typically only needed if running the daemon separately from `sf serve`.

### Method
CLI Command

### Endpoint
sf daemon start [--server <url>]

### Parameters
#### Query Parameters
- **--server** (string) - Optional - The URL of the orchestrator server.
```

--------------------------------

### Create Documentation Directory

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/src/prompts/director.md

Use this command to create the initial Documentation Directory document. This serves as the central index for all workspace documentation.

```bash
sf document create --title "Documentation Directory" --type markdown --category reference \
  --metadata '{"purpose": "document-directory"}' \
  --content "# Documentation Directory\n\nIndex of all workspace documents.\n\n## Specs\n\n(none yet)\n\n## References\n\n(none yet)\n\n## Decision Log\n\n(none yet)"
```

--------------------------------

### Initialize a Stoneforge workspace

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Run `sf init` in your project root to set up the necessary Stoneforge configuration files and directories.

```bash
sf init --name my-project
```

--------------------------------

### Create Documentation Plan with Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/use-cases/documentation-generation.mdx

Use the Stoneforge CLI to create a plan for generating documentation. Specify the title, a detailed description of the desired output, and the target directory.

```bash
sf plan create --title "Generate API documentation" \
  --description "Generate API docs for all public endpoints. Include request/response examples, error codes, and authentication requirements. Output as MDX files in docs/api/."
```

--------------------------------

### Initialize and Configure Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/claude-code-teams-vs-self-hosted.mdx

Set up a self-hosted AI coding agent environment using the Stoneforge CLI. Configure the AI provider and API key, then start the orchestration daemon.

```bash
sf init
sf config set provider anthropic
sf config set api-key $ANTHROPIC_API_KEY
sf daemon start --workers 3
```

--------------------------------

### sf agent start

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-orchestration.mdx

Starts a registered agent, optionally with an initial prompt or specific session parameters.

```APIDOC
## sf agent start

### Description
Starts a registered agent, allowing for an initial prompt, specific spawn mode, and environment variables.

### Method
CLI Command

### Endpoint
sf agent start <id> [options]

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent to start.

#### Query Parameters
- **-p, --prompt** (string) - Optional - Initial prompt to send to agent.
- **-m, --mode** (string) - Optional - Spawn mode: `headless`, `interactive`.
- **-r, --resume** (string) - Optional - Provider session ID to resume.
- **-w, --workdir** (string) - Optional - Working directory for agent.
- **--cols** (integer) - Optional - Terminal columns for interactive mode (default: 120).
- **--rows** (integer) - Optional - Terminal rows for interactive mode (default: 30).
- **--timeout** (integer) - Optional - Timeout in milliseconds (default: 120000).
- **-e, --env** (string) - Optional - Environment variable (repeatable, format: `KEY=VALUE`).
- **-t, --taskId** (string) - Optional - Task ID to assign to agent.
- **--stream** (boolean) - Optional - Stream agent output after starting.
- **--provider** (string) - Optional - Override agent provider for this session.
- **--model** (string) - Optional - Override model for this session.
```

--------------------------------

### Link External Item Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples of linking a task to a GitHub issue and a document to a Linear item.

```bash
sf external-sync link el-abc123 https://github.com/org/repo/issues/42
```

```bash
sf external-sync link el-doc456 https://linear.app/team/DOC-1 --provider linear --type document
```

--------------------------------

### Example Goal for Director

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/agent-roles.mdx

This is an example of a focused goal that can be sent to the Director agent for planning and task creation.

```plaintext
# Example goal
Add OAuth login with Google and GitHub providers.
Include error handling and rate limiting.
```

--------------------------------

### Create a Feature Plan with Tasks

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/task-planning.mdx

Demonstrates creating a plan and then adding multiple tasks with priorities. This example outlines a typical feature decomposition workflow.

```bash
sf plan create --title "Shopping Cart"
sf task create --title "Cart data model and API" --priority 1 --plan "Shopping Cart"
sf task create --title "Add-to-cart UI" --priority 2 --plan "Shopping Cart"
sf task create --title "Cart summary sidebar" --priority 2 --plan "Shopping Cart"
sf task create --title "Checkout flow" --priority 2 --plan "Shopping Cart"
sf task create --title "Integration tests" --priority 3 --plan "Shopping Cart"
```

--------------------------------

### Override Model at Session Start

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

You can override the default or registered model for an agent on a one-time basis when starting a session.

```bash
sf agent start <id> --model claude-opus-4-6
```

--------------------------------

### Example of using --json flag

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Demonstrates how to use the `--json` flag for machine-readable output, often piped to tools like `jq`.

```bash
sf create task --title "Fix bug" --json
```

--------------------------------

### Start the Director Agent

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Starts the previously registered Director agent. Use the ID provided by the registration command.

```bash
sf agent start <id>
```

--------------------------------

### Daemon Runtime Detail Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Shows the additional 'Dispatch Daemon' info section that appears when viewing the daemon host's runtime, including status and uptime.

```text
When viewing the daemon host's runtime, a "Dispatch Daemon" info section appears showing daemon status and uptime.
```