Prerequisites are not summarized in the README

## Summary

The top-level `README.md` currently does not provide a concise "Requirements" or "Prerequisites" section, despite the autonomous execution workflow depending on several external components and setup steps.

From the documentation, users eventually discover that successful execution requires:

* Docker
* sandbox initialization
* editable package installation
* environment variables / API token configuration

However, these requirements are distributed across deeper documentation rather than being surfaced near the beginning of the repository.

This creates unnecessary friction for first-time users and makes it difficult to quickly determine whether their environment is ready.

---

## Problem Statement

A new user arriving at the repository typically wants answers to three questions:

1. What does this project do?
2. What do I need before I begin?
3. How do I get a successful first run?

Currently, the README focuses primarily on introducing the project and linking to additional documents, but it does not provide a compact checklist of prerequisites.

As a result, users may begin setup only to later discover missing dependencies or configuration requirements.

---

## Impact

### User Onboarding

The lack of an upfront requirements section means that users may:

* encounter failures partway through setup;
* spend time searching through multiple documents;
* restart the installation process after discovering missing dependencies;
* assume that configuration problems are bugs rather than missing prerequisites.

### Productivity

Without visibility into required components, setup becomes iterative:

```text id="c84h0v"
Clone repository
↓
Begin installation
↓
Encounter missing requirement
↓
Search documentation
↓
Install requirement
↓
Retry
```

This introduces unnecessary context switching and increases onboarding time.

### Developer Experience

Most mature open-source projects provide a lightweight prerequisites section because users benefit from understanding environmental requirements before executing commands.

Without this information, users cannot quickly answer:

* "Do I need Docker?"
* "Do I need to initialize a sandbox?"
* "Do I need an API token?"
* "What software should already be installed?"

---

## Proposed Solutions

### Option 1: Add a "Prerequisites" Section Near the Top (Recommended)

Introduce a compact checklist immediately after the project description.

Example:

````markdown id="s69u34"
## Prerequisites

Before getting started, ensure that you have:

- Python 3.x
- Docker installed and running
- Ability to create a virtual environment
- An API token configured (for autonomous runs)

Initial setup also requires:

```bash
pip install -e .
./scripts/setup_sandbox.sh
```

See `docs/pipeline.md` for advanced configuration details.
````

This approach provides quick visibility without duplicating detailed documentation.

---

### Option 2: Add a Requirements Table

A table improves discoverability and readability.

Example:

```markdown id="dshv89"
## Requirements

| Requirement | Purpose |
|-------------|---------|
| Python | Runtime |
| Docker | Sandbox execution |
| Virtual environment | Dependency isolation |
| API token | Autonomous runs |
| setup_sandbox.sh | Sandbox initialization |
```

This enables users to quickly verify readiness before starting installation.

---

### Option 3: Add a "Before You Begin" Checklist

Example:

```markdown id="g24t81"
## Before You Begin

Verify the following:

- [ ] Docker is installed and running.
- [ ] Python is installed.
- [ ] A virtual environment can be created.
- [ ] API credentials are available.
- [ ] The sandbox setup script will be executed.
```

This format is particularly helpful for first-time contributors.

---

## Recommendation

I recommend **Option 1**.

A concise "Prerequisites" section offers several advantages:

* improves discoverability;
* reduces onboarding friction;
* minimizes setup failures;
* decreases context switching;
* avoids duplicating deeper documentation;
* aligns with common open-source documentation practices.

Detailed setup instructions can remain in `docs/pipeline.md`, while the README serves as the primary entry point for understanding environmental requirements.

---

## Example Structure

A possible flow could look like:

```text id="fd4v2j"
Project Overview
↓
Prerequisites
↓
Quick Setup
↓
Advanced Documentation
↓
Pipeline Details
```

This provides a progressively deeper learning path and avoids surprising users with hidden dependencies.

---

## Impact

After introducing a compact prerequisites section:

* users can quickly determine whether their environment is ready;
* setup failures due to missing dependencies become less common;
* onboarding becomes more predictable;
* support overhead decreases;
* documentation becomes easier to navigate.

Overall, surfacing prerequisites in the README would improve developer experience and reduce the cognitive overhead associated with first-time setup, while preserving the existing detailed documentation structure.