Skip to content

English · Español

Getting started

A one-page tour for your first 30 minutes in the repo. Assumes you have git, Python 3.11.x (use pyenv or mise), and a recent shell.

1. Install the toolchain (5 min)

Clone:

git clone https://github.com/borjatarraso/lynx-cortex.git
cd lynx-cortex

Install uv (Python env + lockfile manager) and just (task runner). Pick the row for your OS — just and uv are the only two installs needed; everything else just setup will provide.

OS uv just
Fedora 43+ (the canonical target — CLAUDE.md §6) sudo dnf install uv or curl -LsSf https://astral.sh/uv/install.sh \| sh sudo dnf install just
Fedora ≤ 42 curl -LsSf https://astral.sh/uv/install.sh \| sh sudo dnf install just (in repos since F38)
Debian / Ubuntu curl -LsSf https://astral.sh/uv/install.sh \| sh sudo apt install just (Debian 13+ / Ubuntu 24.04+) or prebuilt-mpr for older releases
Arch / Manjaro sudo pacman -S uv sudo pacman -S just
macOS brew install uv brew install just
Anything else (last resort) curl -LsSf https://astral.sh/uv/install.sh \| sh cargo install just (requires a full Rust toolchain — avoid on Fedora, the distro package is one command)

Verify:

uv --version    # ≥ 0.4.18
just --version

🇪🇸 uv reemplaza a pip/venv/virtualenv con una sola herramienta. just es el make moderno: cada ritual del repo vive en el Justfile.

2. Provision the environment (5 min)

just setup        # uv sync with Phase 0 extras + pre-commit + pre-push hook
just lint         # ruff + ruff format --check + mypy on src/
just test         # pytest with the autouse seed fixture

If just lint or just test fail on a fresh clone, that is a bug — please open an issue.

3. Browse the curriculum (5 min)

just docs-serve   # http://127.0.0.1:8000

The site you are reading is the rendered docs. The same content is plain markdown under docs/, so reading it without the site is also fine.

4. Read the contract (10 min)

In order:

  1. LYNX_CORTEX.md §0 (pedagogical contract) and §7 (per-phase ritual).
  2. LYNX_CORTEX_ADDENDUM.md §A13 (the microscopic scope).
  3. CLAUDE.md (working agreements with Claude Code).

5. Walk through Phase 00 (5 min)

When the lab finishes, the phase is gated by PHASE_00_REPORT.md. No phase begins before the previous report is approved.

What's next

  • Active learner: see learners/borja/profile.md.
  • Want to track your own progress? Copy learners/_template/ to learners/<yourname>/ and start a daily journal under learners/<yourname>/journal/.

Conventions cheat sheet

Topic Convention
Python 3.11.x, pinned by .python-version
Env manager uv (lockfile is uv.lock); never pip install outside uv
Lint / format ruff
Type check mypy --strict on src/
Tests pytest; autouse seed fixture in tests/conftest.py
Notebooks stripped by nbstripout, linted via nbqa
Security bandit on src/, pip-audit on the lockfile
Commit messages English only

That's it. Open Phase 00 and start.