Top-level setup is split across multiple documents

## Summary

The current onboarding flow requires first-time users to navigate between multiple documents to complete a successful setup.

The top-level `README.md` provides a high-level getting-started path, while the actionable installation steps and sandbox initialization commands reside in `docs/pipeline.md`. As a result, new users must manually piece together the complete setup sequence.

This creates a documentation discoverability gap and increases onboarding friction.

---

## Problem Statement

At present:

* `README.md` introduces the project and points users toward additional documentation.
* Essential setup steps are documented elsewhere.
* Users must switch between documents to determine the correct order of operations.

For example, a new user may naturally expect the following workflow to be completely documented in the README:

```bash
git clone
cd defending-code-reference-harness

python -m venv .venv
source .venv/bin/activate

pip install -e .

./scripts/setup_sandbox.sh
```

However, the setup sequence is distributed across multiple pages, making it easy to miss required steps.

---

## Impact

### User Onboarding

First-time users generally expect the top-level README to answer three questions:

1. What is this repository?
2. How do I install it?
3. How do I verify that it works?

Because installation instructions are fragmented, users may:

* overlook required setup steps;
* spend additional time searching documentation;
* encounter avoidable setup failures;
* assume the project is difficult to configure.

### Productivity

Documentation context-switching introduces unnecessary cognitive overhead.

Instead of following a linear setup process, users must:

```text
README.md
↓
docs/pipeline.md
↓
README.md
↓
additional docs
```

This slows down onboarding and increases support burden.

---

## Proposed Solutions

### Option 1: Add a "Quick Setup" Section to README (Recommended)

Include a minimal end-to-end setup sequence directly in `README.md`.

Example:

````markdown
## Quick Setup

```bash
git clone
cd defending-code-reference-harness

python -m venv .venv
source .venv/bin/activate

pip install -e .

./scripts/setup_sandbox.sh
````

For advanced configuration and pipeline details, see: `docs/pipeline.md`

This approach preserves the detailed documentation while allowing users to achieve a successful initial setup without leaving the README.

---

### Option 2: Add a Dedicated Installation Section

Introduce:

```markdown
## Installation

### Prerequisites

- Python
- Docker
- Virtual environment support

### Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
./scripts/setup_sandbox.sh
````

### Next Steps

See `docs/pipeline.md` for pipeline configuration and advanced usage.

````

This creates a more traditional documentation structure and improves discoverability.

---

### Option 3: Add Explicit Cross-References

If keeping setup instructions outside the README is intentional, adding clearer guidance would help.

Current flow:

```text
README
↓
Several documents
↓
Pipeline documentation
````

Suggested flow:

```text
README
↓
Quick Setup
↓
Advanced Documentation
```

For example:

```markdown
## Getting Started

For installation and sandbox initialization, follow:

docs/pipeline.md

The required sequence is:

1. Create a virtual environment.
2. Install the package.
3. Run `scripts/setup_sandbox.sh`.
4. Continue with pipeline configuration.
```

---

## Recommendation

I recommend **Option 1**.

Providing a small "Quick Setup" section in the top-level README offers several advantages:

* reduces onboarding friction;
* improves discoverability;
* decreases context switching;
* preserves detailed documentation in `docs/pipeline.md`;
* aligns with common open-source onboarding expectations.

This follows the Open Source Guides recommendation of making contribution and adoption paths clear and minimizing unnecessary barriers for users and contributors.

---

## Impact

After the change:

* first-time users can complete setup from a single page;
* onboarding becomes more predictable;
* support overhead is reduced;
* documentation becomes easier to maintain;
* advanced material remains available without overwhelming new users.

Overall, consolidating the initial setup path would improve developer experience while preserving the existing documentation structure.