# Your first project

Fifteen minutes, most of it waiting. The only thing you write is one page.

---

## 1. A repository for the idea

One repository per project. They stay independent that way — separate state,
separate issues, separate history — and abandoning one is deleting a folder,
which is the point.

```bash
gh repo create my-idea --private --clone
cd my-idea
```

## 2. Install ekadant into it

```bash
bash /path/to/ekadant/scripts/bootstrap.sh
```

This copies the plugin into `.ekadant/plugin/`, installs the workflows, creates
`IDEA.md` and initialises the ledger.

The plugin is **copied rather than cloned at run time**, for two reasons. A
runner's `GITHUB_TOKEN` is scoped to its own repository, so while ekadant is
private it cannot fetch it. And the project ends up carrying the exact version
of the pipeline that built it, so a run from six months ago can be reproduced.

To update later, re-run the script.

## 3. Write IDEA.md

One page. Prose, not a feature list. Who it is for, what is painful today, what
done looks like, the hard constraints, and at least two things you are
deliberately not building.

Write it as you would explain it to a colleague. The scout reads this first and
will try to talk you out of it, so vagueness here costs you a worse answer.

## 4. Your token

```bash
claude setup-token
```

Add the result as a repository secret named **`CLAUDE_CODE_OAUTH_TOKEN`**:
Settings → Secrets and variables → Actions → New repository secret.

It authenticates as you, lives only in this repository, and is never shared or
pooled. Runs draw on your Claude plan rather than API billing. Everyone using
ekadant supplies their own.

## 5. Two settings that fail quietly if you skip them

**Settings → Actions → General → Workflow permissions → "Read and write".**
The default is read-only, and the pipeline needs to commit its ledger and open
the issues you read. Without it, runs look like they simply did nothing.

**Check `ekadant.yml`.** The budgets are deliberately conservative. `portfolio`
is the ceiling across every project on one machine — keep it meaningfully below
the sum of the per-project budgets, because one subscription pays for all of
them and that is what runs out.

## 6. Push, then scout

```bash
git add -A && git commit -m "ekadant" && git push
```

Actions → **ekadant scout** → Run workflow.

A few minutes and pennies later you have `SCOUT.md`. Read the **Verdict** and
**What will stop you** sections first — they are the two that change what you do
next.

If it talks you out of the idea, that is the system working. You paid the price
of a coffee to find out, and you can run the next idea this afternoon.

## 7. Then it runs itself

Once you continue past the scout, the schedules take over:

| When | What |
|---|---|
| 03:00 daily | one unit of work |
| 07:00 weekdays | the brief — what shipped, what needs you, what the world did |
| Mondays 06:00 | the radar — competitors, customers, the industry |

You answer questions by commenting on the issue that asked them. Everything
else waits for you rather than nagging.

---

## When something looks wrong

**Nothing is happening.** Workflow permissions are read-only, or the schedule is
firing from a branch that is not the default. GitHub runs scheduled workflows
only from the default branch.

**Runs stopped on their own.** Check the issues. Either the budget is spent, a
plan usage limit was reached and the schedule disabled itself, or more than a
handful of questions are waiting. Each says which.

**`ek status` shows unmetered runs.** The telemetry could not be parsed for
those runs, so their spend is unknown rather than zero. If it keeps happening,
the budget is not protecting you and it is worth raising.

**A check has been failing for days.** `ek attempt` will have escalated it with
everything that was tried. The pipeline stops on the second identical failure
rather than burning your allowance on a fifth variation.