Getting started¶

This guide takes you from zero to a working Belico environment: installing dependencies, configuring academic API keys, and running the pipeline for the first time. It is the recommended entry point for newcomers.

What you will achieve

By the end of this tutorial you will have the stack cloned, dependencies installed, credentials configured, and your first engram conectó running. From there, Your first paper shows you how to start a real paper.

Prerequisites¶

Dependency	Minimum version	How to check
Python	3.10+ (3.12 recommended)	`python --version`
Git	2.30+	`git --version`
Pandoc	2.19+	`pandoc --version` (to compile PDFs)
Engram	latest	`engram --version`

Platforms

Windows: use PowerShell 7+ (pwsh), not powershell.exe (v5). The stack ships modern .ps1 scripts that fail on the old version.
OpenSeesPy on Windows: not stable with Python 3.13 — use Python 3.12 for the structural backend.
macOS/Linux: bash 4+ or zsh.

Step 1 — Clone the repository¶

git clone --recurse-submodules https://github.com/Mikisbell/Belico_Jarvis.git my-paper
cd my-paper

The --recurse-submodules flag is mandatory: the stack includes submodules under .agents/. If you forgot it:

git submodule update --init --recursive

Step 2 — Set up the Python environment¶

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

pip install -e .

This installs the belico package with its CLI. Verify:

belico --help
belico --version

Step 3 — Configure API keys (`.env`)¶

Copy the template and fill in the keys:

cp .env.example .env

Minimum keys for the basic pipeline:

Variable	Purpose	Cost
`OPENALEX_API_KEY`	Literature search	Free (works without key)
`SEMANTIC_SCHOLAR_API_KEY`	Style calibration	Free (recommended)
`SUPABASE_URL` + `SERVICE_KEY`	reference_papers, patents	Optional

Never commit .env

.env is in .gitignore. If a key leaks, revoke it immediately and generate a new one. See Managing API keys.

Step 4 — Verify connectivity¶

Before starting, confirm the APIs respond:

belico smoke-check

If you are offline or want a quick check:

belico smoke-check --no-online

Step 5 — First session: "engram conectó"¶

Open your IDE (Claude Code recommended — also works in Antigravity, Cursor, Windsurf, OpenCode) and type exactly:

engram conectó

The orchestrator checks dependencies, queries Engram (cached constitution, active papers, risks), and prints a stack status report. Then it asks "What are we building?" (domain + quartile + institution).

Next steps¶

Your first paper with the CLI — start a paper end-to-end.
Agent / IDE setup — configure your preferred IDE and model.
The production pipeline — understand the 9 SDD phases.
Stack rules — what Belico enforces and why.

Canonical source

This tutorial derives from docs/shared/GETTING_STARTED.md, which keeps the extended version with all init_child steps.