1 · Scaffold a new frontier

A frontier is a named scope of findings. Use vela frontier new when you intend to publish; use vela init when you want a local .vela/ repo for solo work.

$ vela frontier new \
    --name "alzheimers-bbb" \
    --description "Blood-brain barrier delivery in Alzheimer's" \
    bbb.json

· frontier scaffolded frontier 'alzheimers-bbb' at bbb.json
  next steps:
    1. vela finding add bbb.json --assertion '...' --author 'reviewer:you' --apply
    2. vela sign generate-keypair --out keys
    3. vela actor add bbb.json reviewer:you --pubkey "$(cat keys/public.key)"
    4. vela registry publish bbb.json --owner reviewer:you --key keys/private.key --locator <url> --to https://vela-hub.fly.dev

2 · Add a finding manually

Without --apply, the finding lands as a pending proposal in the inbox. With --apply, it becomes a canonical event.

$ vela finding add bbb.json \
    --assertion "Focused ultrasound transiently opens the BBB in early-AD patients." \
    --type therapeutic \
    --evidence-type experimental \
    --doi "10.1038/s41591-024-XXXXX" \
    --author "reviewer:demo" \
    --confidence 0.55 \
    --apply

Finding proposal applied
  frontier: alzheimers-bbb
  finding:  vf_4c8a91d28e7b3712
  proposal: vpr_a3e7f12b9c4d8e15
  status:   applied
  event:    vev_8b3c194fd217ae62

3 · Generate a key, register an actor, sign

Three commands. The keypair lives at keys/; the actor record lives in the frontier; the signature is over canonical-JSON of each finding minus the signature field.

$ vela sign generate-keypair --out keys
· generated keypair · keys
  public key: 88ccb43144e9e228c37566554845dcd4e1f5afd3fab3e10d23df551dcdd87041

$ vela actor add bbb.json reviewer:demo --pubkey "$(cat keys/public.key)"
· registered actor reviewer:demo (pubkey 88ccb43144e9e228)

$ vela sign apply bbb.json --private-key keys/private.key
· signed 1 findings in bbb.json

4 · Link two findings

Typed edges between findings. Kinds: supports, depends, contradicts, narrows, supersedes. Cross-frontier targets use vf_<id>@vfr_<id> form once you've declared the dependency with vela frontier add-dep.

$ vela link add bbb.json \
    --from vf_4c8a91d28e7b3712 \
    --to vf_b3a219c845f01e7d \
    --type supports

· link added: vf_4c8a91d… --supports--> vf_b3a219c…

5 · Record a Correction event

A Correction supersedes an existing finding with a new content-addressed claim. The old finding is flagged superseded; both remain queryable; the new finding gets an auto-injected supersedes link back to the original.

$ vela finding supersede bbb.json \
    --supersedes vf_4c8a91d28e7b3712 \
    --assertion "Focused ultrasound opens the BBB in APOE4-positive early-AD patients only." \
    --author "reviewer:demo" \
    --confidence 0.71 \
    --apply

Supersede applied
  old: vf_4c8a91d28e7b3712 (now flagged: superseded)
  new: vf_e2f9018d7a4b3c6e (auto-link: supersedes → vf_4c8a91d…)
  event: vev_c19a4f7d825b1e30

6 · Publish to the hub

The hub verifies the signed manifest, checks the snapshot and event-log hashes, and promotes the frontier into event-first read state. Clients verify locally on read.

$ vela registry publish bbb.json \
    --owner reviewer:demo \
    --key keys/private.key \
    --to https://vela-hub.fly.dev

· publishing manifest to vela-hub.fly.dev
· vfr_id: vfr_72f8019b3d4c8a1e
· snapshot_hash: 7a91...0c4d
· signed_publish_at: 2026-05-02T18:14:33Z
· status: ok

7 · Verify a published frontier from disk

Anyone can pull the frontier file, recompute the snapshot hash through any of the three reducer implementations (Rust, Python, or TypeScript), and check it matches the hub manifest. No trust in the hub required.

$ vela registry pull vfr_72f8019b3d4c8a1e --out /tmp/pulled.json
· fetched manifest from vela-hub.fly.dev
· locator: https://your-host.example/bbb.json
· hash check: 7a91...0c4d == 7a91...0c4d  ok
· wrote: /tmp/pulled.json

$ vela sign verify /tmp/pulled.json

  VELA · SIGN · VERIFY · /TMP/PULLED.JSON
  ····························································
  total findings:   1
  signed:           1
  unsigned:         0
  valid:            1
  invalid:          0

8 · Validate a Bridge Kit packet

External runtimes hand Vela source material through a Carina artifact packet. Validation checks locators, hashes, parent lineage, candidate claims, and open needs without writing state.

$ vela bridge-kit validate examples/bridge-kit/packet.json --json
{
  "ok": true,
  "command": "bridge-kit.validate",
  "packet_count": 1,
  "valid_packet_count": 1,
  "packets": [
    {
      "packet_id": "cap_bridge_kit_minimal_demo",
      "artifact_count": 1,
      "candidate_claim_count": 1,
      "open_need_count": 1
    }
  ]
}

After validation, use vela artifact-to-state to write proposals. Claims and gaps become state only after review.

9 · Mirror a hub locally

Pull a signed manifest from one hub and POST it verbatim to another. Both hubs validate the signature against the embedded owner_pubkey; mirroring is a no-op for authenticity. Use this for resilience, seeding a fresh hub, or hub-deployment smoke tests.

$ vela registry mirror \
    vfr_72f8019b3d4c8a1e \
    --from https://vela-hub.fly.dev \
    --to https://my-hub.example/

· pulled manifest from vela-hub.fly.dev (signature verified)
· posted to my-hub.example (signature re-verified, accepted)
· status: ok

10 · Run an AI agent (Literature Scout)

Vela's agent commands run an LLM-backed pipeline against a folder of source material and write the results back as finding.add proposals tagged with an AgentRun record. Reviewers accept proposals via the inbox; nothing becomes canonical without a signed accept.

$ vela scout ./papers --frontier bbb.json --backend sonnet

Literature Scout · sonnet
  walking 12 PDFs in ./papers ...
  proposals: 38 candidate findings
  written:   bbb.json (proposals: 38, status: pending_review)
  inbox:     vela inbox bbb.json

Adjacent agents: vela compile-notes (Markdown / Obsidian), vela compile-code (Jupyter / Python / R), vela compile-data (CSV / TSV), vela review-pending, vela find-tensions, vela plan-experiments.

11 · Query the hub HTTP API

No authentication, no rate limit, CORS open. The signature is the bind.

$ curl https://vela-hub.fly.dev/entries | jq .
{
  "entries": [
    {
      "vfr_id": "vfr_bd91...",
      "name": "Alzheimer's Therapeutics",
      "owner_actor_id": "reviewer:will-blair",
      "snapshot_hash": "f23b4aba17...",
      "signed_publish_at": "2026-04-27T18:32:01Z"
    },
    ...
  ]
}

$ curl https://vela-hub.fly.dev/.well-known/vela
{
  "protocol_versions": [1],
  "signing_algorithms": ["ed25519-canonical-json-v1"],
  "admin": "ops@vela.science"
}

Full API at /sdk § Hub HTTP API; protocol details at /spec.