# v0.5.1 — Zero-friction Paseo entrypoint

v0.5.1 makes `aeh start` the interactive product entrypoint for a Harness-enabled repository. After startup, the user can work from Paseo by writing normal engineering requests; repository-changing prompts are automatically routed through the Harness instead of requiring the user to invoke triage, QUICK, SPEC, SDD, TaskContracts, workers, validators or reviewers manually.

## Start

With AEH installed in the project:

```bash
aeh start
```

Equivalent package-manager invocations include:

```bash
npx aeh start
npm exec aeh -- start
```

`npm aeh start` is not the canonical npm bin syntax. Use `npm exec aeh -- start` when invoking the locally installed package through npm.

By default `aeh start`:

1. loads `.harness/project.yaml` and the resolved agent topology;
2. selects the configured interactive lead, normally `lead`/Codex;
3. verifies that Paseo and the lead runtime are available;
4. reconciles managed toolchain dependencies automatically when they are missing;
5. starts `paseo daemon start --web-ui` only when the daemon is not already running;
6. creates a persistent Paseo session for the project or reuses the compatible prior session;
7. bootstraps that lead with the `engineering-workflow` invariant;
8. waits until initialization reaches `AEH READY` before reporting the session ready.

State is machine-local and gitignored under:

```text
.harness/paseo/lead-session.json
.harness/paseo/lead-bootstrap.md
```

The command deliberately does not rewrite the user's global `~/.paseo/config.json`.

## Prompt semantics

Once the generated lead is open in Paseo, a normal prompt such as:

```text
Add rate limiting to the public authentication endpoints and cover it with tests.
```

is interpreted as:

```text
natural-language prompt
        ↓
repository inspection
        ↓
automatic triage evidence
        ↓
QUICK or SPEC
        ↓
QuickContract or SDD/TaskContract
        ↓
seal
        ↓
Harness execution
        ↓
planner DAG / worker waves
        ↓
deterministic validators + evidence
        ↓
review quality convergence
        ↓
lead semantic acceptance
        ↓
configured deterministic delivery
```

The parent Paseo lead must not implement a repository-changing prompt directly as a shortcut around this pipeline.

Read-only questions may be answered directly when they do not mutate repository state. Existing GitHub issue requests enter the issue-driven path automatically. If a task initially appears QUICK but implementation reveals architecture, security, schema, public API, cross-module or otherwise unsafe scope, the lead escalates it to SPEC rather than widening the QuickContract.

## Session reuse

`aeh start` reuses `.harness/paseo/lead-session.json` when the previous session still exists and its bootstrap version, project root, selected lead, provider, model and title remain compatible.

Create a clean lead explicitly with:

```bash
aeh start --new
```

Other startup controls:

```bash
aeh start --no-web-ui
aeh start --no-setup
aeh start --lead lead
aeh start --title "AEH Lead"
aeh start /path/to/repository
```

`--no-setup` disables automatic toolchain reconciliation. If Paseo or the selected lead runtime is unavailable in that mode, startup fails instead of silently falling back to a different agent/runtime.

## Configuration

New projects receive:

```yaml
orchestration:
  provider: paseo
  interactive:
    autoSetup: true
    webUi: true
    leadAgent: lead
    reuseSession: true
    stateDir: .harness/paseo
    title: AEH Lead
```

The lead is resolved from the active topology; the start implementation does not hard-code Codex. Projects can therefore replace the logical lead while preserving the same Harness entry semantics.

## Defense in depth

The automatic path is enforced at two conversational layers:

- the persistent `aeh start` bootstrap makes the rule part of the Paseo lead conversation;
- generated `AGENTS.md` independently states that repository-changing conversational prompts must enter `engineering-workflow`.

The deterministic Harness remains the acceptance authority. Paseo and the lead decide how to interpret and route the prompt, but do not replace sealing, scope enforcement, validators, evidence, review convergence or final acceptance gates.
