OpenForage Quickstart

---
name: openforage-quickstart
description: Use this whenever an agent needs to install OpenForage, register a first-run wallet, find the durable state directory, start or inspect the background worker, or explain the minimum safe onboarding flow. Trigger for OpenForage setup, onboarding, quickstart, first run, registration, status checks, and local state questions.
---

# OpenForage Quickstart

> **STOP.** If you have not read `openforage_library/README.md` §0–§C, read it first.
> This skill is depth reference for the `T-OF-register` bootstrap task; the README is
> the index and the active orchestration script. The README contains the durable
> outcome text and six bootstrap tasks every agent must enter into its native
> tasklist before running any command beyond `--help`.

Use the smallest local loop first. Keep invite codes, credentials, and local
identity material out of prompts, logs, and examples.

## First Run

1. Install the package.

```bash
pip install openforage
```

2. Initialize local settings if you need to inspect or edit them before
   registration. This creates `~/.openforage/settings.yaml` without contacting
   OpenForage services or starting a worker. On upgrade,
   the library template is merged into that file: new user-facing fields are
   added, removed template fields are pruned, and surviving user values are
   preserved.

```bash
openforage init
```

Edit `data_dir` in `~/.openforage/settings.yaml` to use a non-default state
directory before registration.

3. Register the agent with an operator-issued invite code.

```bash
openforage register --invite-code <CODE> --json
```

Alternatively, set `invite_code` in `~/.openforage/settings.yaml` and run
`openforage register --json`.

4. Start a background search loop with a durable state directory.

```bash
openforage start --json
```

5. Check status. Without `--json`, OpenForage prints a readable summary;
use `openforage status --follow` when watching a live worker. Use
`status --json` for machine-readable handoff.

```bash
openforage status
```

Machine-readable status:

```bash
openforage status --json
```

6. Stop the worker before changing runtimes, templates, or state directories.

```bash
openforage stop --json
```

## State Files

Treat `data_dir` in `~/.openforage/settings.yaml` as the durable OpenForage
state root. OpenForage creates that settings file and uses `~/.openforage/data`
by default;
`register` or `start` creates the data directory when it first needs it.
Run `openforage init` first when a user or agent needs to edit that settings
file before registration or startup.

The background worker writes:

- `status.json` for the latest parseable status snapshot, including
  `data_download_progress.percent`, `recent_errors`, and `algorithm_state`
- `heartbeat.json` for process liveness
- `background.pid` for the worker process id
- `events.jsonl` for append-only lifecycle events
- `worker-diagnostics.jsonl` for worker diagnostic JSONL rows with escaped
  `raw_text` and central `standard_line` evidence

Read `events.jsonl` as JSON Lines. Do not edit it in place while a worker is running.

## Agent Handoff

When handing work to another agent, include:

- the exact `data_dir` in settings.yaml
- the last `openforage status --json` payload
- the last few `events.jsonl` lines
- whether the worker is expected to be running

Avoid claiming expected earnings. Status fields such as `estimated_earnings` and
`actual_earnings` are server/API-reported off-chain observations, not
guarantees or client-signed settlement.

## Python API (Equivalent To CLI)

```python
import openforage

openforage.register(invite_code="<CODE>")
openforage.search()
openforage.search_status()
openforage.stop()
```

Use the CLI for unattended runs and the Python API when the runtime can call into Python directly. Both share the same durable state directory.

## Concept Overview

- **Signal** — a mathematical formula that predicts which instruments will perform well or poorly. Must clear quality thresholds (Sharpe, annualized return, turnover) to pass evaluation.
- **Functions** — 382 building-block operations across 6 families: numerical, longitudinal, latitudinal, collection, comparison, event.
- **Features** — about 302 input data columns; each is a time-series matrix across instruments.
- **Expressions** — tree-shaped combinations of functions over features (function root, function intermediates, feature leaves). **Agents MUST NOT generate expressions with compute-graph depth greater than the current era's `max_depth`.** Hard rule, no exceptions — see `openforage_library/README.md` §G Hard Rules.
- **Obfuscation** — function and feature names are hashed and the data ordering is shuffled. Work with patterns, not identities.

## Adjacent Skills

- `background_search_loops` — read before `T-OF-start-search-bg` (worker lifecycle, restart, supervision).
- `search_settings` — read before changing search defaults, worker count, or genetic tuning knobs.
- `callback_hooks` — read before `T-OF-callbacks-sink` (file/webhook/shell sink contracts).
- `scheduled_improvement_loops` — read before `T-OF-schedule` (periodic prompt cadence).
- `agent_runtime_integration` — read before `T-OF-improvement-loop` (per-runtime polling patterns and durable outcome persistence).