Walkthrough: a repository end to end

Follow this sequence in your own Git repository. Terminal output below was captured on 10 September 2026 from this checkout and a scratch clone using CLI 2.0.0. The completed example run already existed. Setup and plan-only checks started no paid worker. Replace the example initiative, story, and run IDs with your own.

1. Install the CLI

Configure your package token as described in Install and initialise.

npm install -g @engineering11/e11-foundry@2.0.0
e11 --version

2.0.0

Keep e11 on PATH. Installed skills use the CLI to update the board.

2. Prepare your checkout

e11 init

For the captured clone, setup used a local release archive and an isolated Foundry Home. Replace the archive path with your local package when reproducing this command.

FOUNDRY_HOME=/private/tmp/guide-v2-home e11 init --yes --ide claude-code --no-register --from /path/to/engineering11-e11-foundry-2.0.0.tgz -d /private/tmp/guide-v2-checkout

  project file   kept     .foundry/project.toml (project_24a65729-12e3-460e-bc96-25d51eaebd9b, publication root foundry)
  workspace      wrote    workspace_71907506-c9d0-48f8-a9f2-d25e00fbbee6 at storage generation 2
  toolkit        kept     2.0.0 pinned, 436 files under .foundry/foundry
  configuration  wrote    .foundry/config.toml, config.user.toml, custom/ from the pinned module; foundry/planning-artifacts, foundry/implementation-artifacts, docs
  price list     kept     .foundry/pricing.json; confirm its rates
  profiles       kept     .foundry/profiles.toml
  ignore rules   kept     .gitignore managed blocks
  skills         wrote    42 skills for claude-code
  registry       skipped  --no-register
  preferences    wrote    IDEs: claude-code
Next: commit .foundry/project.toml, profiles.toml and pricing.json with the ignore rules, then e11 initiative new <slug> --title <text>.

The project file carries identity and publication root. Init restores the pinned Toolkit, configuration, skills, and local workspace. The price list and profile define cost and acceptance. Registry and editor preferences belong to your machine. Repeat init to bring a clone to the same state.

3. Check readiness

e11 doctor

  project file          ok    project_24a65729-12e3-460e-bc96-25d51eaebd9b, publication root foundry
  Toolkit pin           ok    2.0.0 (sha256:82cd76b4e1c0885ff045d059edad03408c3295c8cf7b21c3fc32b69b7bab5cf5)
  price list            ok    3 priced models at the published list rates
  execution profile     ok    default (6 commands)
  workspace             ok    p_mt6erm8pd46a8a0d4a4d at storage generation 2
  skills (claude-code)  fix   1 of 42 skills missing or behind the pin under .claude/skills: e11 init
  initiative            ok    operator-dashboard (Operator dashboard)
  story documents       ok    every document under foundry/initiatives/operator-dashboard is committed
  e11 on PATH           ok    skills can call e11 board

This checkout has one skill behind the pin. Run the correction in the fix row, then check again. Doctor writes no files. The scratch clone’s skill check passed after init.

4. Commit shared inputs

git add .foundry/project.toml .foundry/pricing.json .foundry/profiles.toml .gitignore
git commit -m "chore: configure Foundry"

The project file records the Toolkit pin. Pricing defines settlement rates. Profiles name trusted acceptance commands. Read the file examples before committing your changes.

5. Select an initiative

e11 initiative new operator-dashboard --title "Operator dashboard"
e11 initiative show

On a checkout where this initiative already exists, use e11 initiative use operator-dashboard. Captured show output follows.

{
  "slug": "operator-dashboard",
  "initiativeId": "initiative_102ae94b-70aa-49af-af29-3a76b5f68594",
  "title": "Operator dashboard",
  "dir": "/Users/mikiyasamdu/project/js/e11/lab/e11-foundry/foundry/initiatives/operator-dashboard",
  "isCurrent": true,
  "openIn": [
    "/Users/mikiyasamdu/project/js/e11/lab/e11-foundry"
  ]
}

foundry/initiatives/operator-dashboard/
  initiative.yaml
  stories/
  specs/
  board.yaml

The board file appears when you create the board. The selected initiative becomes the checkout’s current effort. Initiatives and the board explains selection and separate worktrees.

6. Write and commit stories

Ask e11-create-epics-and-stories or e11-dev-flow to write your story with context and acceptance criteria. This excerpt comes from the existing story foundry/initiatives/operator-dashboard/stories/2-6-artifacts.md.

# Story 2.6: Artifacts

Status: ready-for-dev

## Story

As an operator, I want an intent's artifacts on the page: the board as a board, and every brief,
PRD, design, architecture, epics, story and review with its state, its revision and who produced
it, linked both ways to the runs, so that what the project intends and what the runs delivered are
read in one place.

## Context

Workstream W6 of `docs/roadmap/OPERATOR-DASHBOARD-PLAN-2026-09-10.md` (read it first). Artifacts
are the initiative's managed documents: the vocabulary is
`packages/foundry/tools/foundry/contracts/artifacts.ts` (`ARTIFACT_KINDS`, `ArtifactMetadata`
with `contentDigest`, `predecessorDigest`, `revision`, `producer` naming a run and item when one
produced it, `ArtifactSnapshot` with `state` in `published | externally-modified | missing`); the
store, layout and journal are under `packages/foundry/tools/foundry/adapters/local/artifacts/`;
the operations are `packages/foundry/tools/foundry/application/initiatives/operations.ts`
(`readBoard`, `listBoards`, `readArtifact` and its neighbours) and the board snapshot names its
entries' `storyId`, `status` and `evidence` (runs and items, with `at`). The intent page, its
contract (`contract/intents.ts`) and its route came from story 2.2; the live stream's
`artifacts` event from story 2.4. The run page and its composed view are
`packages/foundry/dashboard/src/sections/runs/run-screen.tsx` and
`packages/foundry/tools/cli/commands/run-read-compose.ts`; `RunDocument` in
`packages/foundry/tools/cli/lib/dashboard/contract/runs.ts` lists paths an attempt touched, which
is not the artifact store. The client renders Markdown already (`sections/runs/run-documents.tsx`).

## Acceptance Criteria

- Given a served checkout, when `GET /api/projects/:id/intents/:slug/artifacts` is read, then it
  lists the intent's artifacts under a new contract module `contract/artifacts.ts`: id, kind,
  location, title (the document's first heading), state, revision, published time, producer (and the
  run and item when one produced it); `GET …/artifacts/:artifactId` answers the artifact's body
  (the recorded revision's content, and the observed content when `externally-modified`, both) and
  its revision lineage; `GET …/board` answers the board view: columns by status in the board's
  order, each entry with its story id and title, its story artifact id when one exists, and the runs
  in its evidence.
- Given the intent page, when it renders, then an Artifacts section groups the artifacts by kind
  with their state as a badge and their revision, opens an artifact's rendered body in place, and
  shows the board as columns; each board entry links to its story artifact and to each run in its
  evidence; an `externally-modified` artifact shows both texts with a note saying which is
  recorded.
- Given a run's page, when it renders, then its delivery card links to the artifacts the run
  produced (by `producer.run`), and an artifact's body links to the runs that produced its
  revisions.
- Given the live stream's `artifacts` event, when it arrives, then the intent page's artifacts and
  board refetch without a refresh.
- Given the change, when the suites run, then tests hold the artifacts listing and body contracts
  (state derived from the observed digest), the board view (columns in the board's order, the
  evidence links), and the run-to-artifact derivation; each fails when its guard is removed.
- Given the guide, when the page that describes the dashboard is read, then it names the
  artifacts section and the board view.

e11 board create --title "Operator dashboard" --stories 2-1,2-2,2-3,2-4,2-5,2-6
e11 board show

Captured board output after the example initiative’s work finished follows. Your new board starts with undelivered stories.

Operator dashboard (published)
  2-1  done  (story 2.1)
  2-2  done  (story 2.2)
  2-3  done  (story 2.3)
  2-4  done  (story 2.4)
  2-5  done  (story 2.5)
  2-6  done  (story 2.6)

git add foundry/initiatives/operator-dashboard
git commit -m "docs: define operator dashboard stories"

Commit the source documents. Staged or modified files do not satisfy the run’s baseline check.

7. Preview and start a run

e11 run story 2.6 --model anthropic/claude-opus-5 --max-cost-usd 60 --plan-only

Captured from the same plan-only request using the full story path in the scratch clone.

Planned 1 work item(s) under the ceiling of 60.00 USD given; nothing started.

e11 run story 2.6 --model anthropic/claude-opus-5 --max-cost-usd 60

The second command starts paid work. The engine seals a plan and works in its own worktree under Foundry Home. Acceptance commands from your profile judge the result. The final Page: line names the run’s dashboard URL and a serving command when needed. Run a story explains the plan and flags.

8. Watch the run

Open a second terminal in the same checkout while the worker runs.

e11 dashboard

Select your project, intent, and run. A running page opens on the item in progress. The operations bar links to the worktree and branch and provides commands to copy. Details holds evidence and gate output. The dashboard describes each view.

9. Read the result

e11 runs status run_44598575

Run run_44598575-ecf1-43c9-a967-6eb05074bec5 completed
  w1 done (2 attempt(s)): Landed at b490a22c47. Nothing left for this item; release its worktree with: e11 runs cleanup run_44598575
    Checkout changed during an attempt: packages/foundry/test/foundry/activation.test.ts, packages/foundry/test/foundry/report-render.test.ts, packages/foundry/test/foundry/run-command-next.test.ts, packages/foundry/test/foundry/runs/local-composition.test.ts, packages/foundry/test/foundry/runs/report-fixture.ts, packages/foundry/test/foundry/runs/report-shape.test.ts, packages/foundry/test/foundry/runs/report.test.ts, packages/foundry/test/foundry/runtime/process-fixture.ts, packages/foundry/tools/cli/commands/runs-render.ts, packages/foundry/tools/cli/commands/runs.ts, packages/foundry/tools/foundry/adapters/local/evidence.ts, packages/foundry/tools/foundry/adapters/local/execution.ts, packages/foundry/tools/foundry/adapters/local/foundry.ts, packages/foundry/tools/foundry/adapters/runtime/live-execution.ts, packages/foundry/tools/foundry/adapters/runtime/process-narration.ts, packages/foundry/tools/foundry/application/runs/controller.ts, packages/foundry/tools/foundry/application/runs/report.ts, packages/foundry/tools/foundry/domain/runs/report/render.ts. The worker edits the run's worktree, not the checkout, so this is recorded as evidence and the delivery is judged on its own.
Spent 17.65 of 60.00 USD; the provider reported 19.03 USD
Next: Every item landed and the worktree and branch are released. Nothing left to do.
Report: All 1 item delivered and accepted within budget. (/Users/mikiyasamdu/.e11-foundry/workspaces/p_mt6erm8pd46a8a0d4a4d/runs/run_44598575-ecf1-43c9-a967-6eb05074bec5/artifacts/run.report.md)

e11 runs report run_44598575

# Story 2.6

All 1 item delivered and accepted within budget.

## Delivered

1 work item accepted at commit b490a22c4754cb197a4883f75acff972ade28602. Ready to land but not yet landed. Changes span 26 files, verified by linting, TypeScript checks, and unit tests.

## What to do next

Every item accepted. 1 not yet landed: e11 runs land run_44598575 --work-item <id> --merge

## Cost and time

Spent $17.65 against a $60.00 budget. Used 2 of 40 attempts. Elapsed time: 1 hour 24 minutes.

## Worth knowing

- The provider reported 19.03 USD against a settlement of 17.65 USD.
- 2 attempt(s) over 1 item(s): some were retried or continued.
- The project checkout changed while an attempt was in flight; the worker edits the run worktree, so that was somebody else.

The report records settlement time. This example report predates landing, while the current status shows landing and cleanup complete. Follow current status for your next action. Narration uses the engine’s recorded facts. Without a narration model, the factual brief serves as the report.

10. Read a refusal

e11 runs status run_nope

no run of this workspace is run_nope; a run is named by its id, a unique prefix of it, or <project-id>/<workspace-id>/<run-id>
Next: e11 runs list

An uncommitted source produces this captured refusal from the scratch clone.

the source has 1 problem(s): foundry/initiatives/operator-dashboard/stories/2-6-artifacts.md is not committed; staged or modified is not committed
Next: git add foundry/initiatives/operator-dashboard/stories/2-6-artifacts.md && git commit -m "<why>"; a run plans from committed documents only

Commit the named file before planning again. For a money pause, read status and raise the total ceiling with e11 runs resume <run> --raise-ceiling <usd>. When a run refuses lists common next steps.

11. Understand money and turns

An over-reservation charge still receives acceptance checks. Passing delivery stays accepted, and the run pauses before more paid work. Raising the ceiling continues the same run with completed items preserved.

A turn allowance limits one worker invocation. A continuation resumes the same attempt and worktree, including modified and untracked files. The engine judges the attempt once from its starting point. Money and turns explains the limits.

12. Land and release your work

For your own accepted, unlanded item, use the run and work-item IDs from status. The historical example below has already completed these steps.

e11 runs land <run> --work-item <id> --merge
e11 runs cleanup <run>

Landing fast-forwards your branch to the accepted commit and records delivery. Resolve branch or overlapping file conflicts named in a refusal. Cleanup releases the worktree and branch when you request cleanup.

If you finish the item by hand in the run worktree, use e11 runs adopt <run> --work-item <id> first. Adopt verifies the run branch head, then records the result. Adopt, land, and cleanup covers this path.

13. Find the completed work

Your branch holds the accepted commit. The board shows done entries. The intent page shows artifacts with their kind, state, and revision. The report stays in the run’s evidence directory, and cleanup releases the worktree.

Continue with Running work, the Catalog, or Ship a story.