# 01: Hello World

## Outcome

Build one Development Image, bind its verified managed digest to one Cookbook
step, run the recipe, and see `Hello from Let'em Cook!` as a safe output event.

## Prerequisites

- A LEMC account and a verified Web or LEMCSSH login.
- Permission to create Cookbooks, Apps, and Development Images.
- Stock OpenSSH only if you use the optional LEMCSSH path.
- About 20 minutes. This lesson uses no cloud service and has no external cost.

## Files

- `Dockerfile` uses a digest-pinned BusyBox base image.
- `run.sh` emits one literal `lemc.output;` event.
- `cookbook.yaml` declares one `now` step with a local development image name.

## Web

1. Sign in and open **Builder > Development Images**.
2. Create an image named `tutorial-hello-world`. Set `Dockerfile` and `run.sh`
   from this directory as its source files.
3. compile and test the saved source revision. Wait for the Builder execution
   to reach a successful terminal state. Record the verified build.
4. Open **Cookbooks**, create `Tutorial 01 Hello World`, and set its individual
   YAML to `cookbook.yaml`.
5. For page 1, recipe `hello-world`, phase `now`, step 1, select the verified
   Development Image build. LEMC replaces the `:dev` source reference with its
   managed digest in the server copy.
6. Publish the Cookbook, create an App from it, open page 1, and run
   **Hello World** once.

Do not publish or run a Cookbook while its server copy still has the `:dev`
reference. Hosted jobs require the managed digest selected by LEMC.

## LEMCSSH

This optional path uses commands in `lemc.remote-command/v1`. Replace the
uppercase placeholders and use a new request UUID for each intended mutation.
Values returned by one command supply the next image, revision, build,
Cookbook, and App identifiers.

```sh
ssh LEMC_ALIAS builder images create \
  --name tutorial-hello-world \
  --description Tutorial-01-image \
  --idempotency-key REQUEST_UUID --format=json < Dockerfile

ssh LEMC_ALIAS builder images source-files put IMAGE_UUID run.sh \
  --expected-revision SOURCE_REVISION \
  --idempotency-key REQUEST_UUID --mode 0755 \
  --content-type text/x-shellscript --format=json < run.sh

ssh LEMC_ALIAS builder images compile-run IMAGE_UUID \
  --expected-revision SOURCE_REVISION \
  --idempotency-key REQUEST_UUID --follow --format=json

ssh LEMC_ALIAS cookbooks create \
  --name tutorial-01-hello-world --format=json

ssh LEMC_ALIAS cookbooks yaml set COOKBOOK_UUID \
  --view-type individual --format=json < cookbook.yaml

ssh LEMC_ALIAS cookbooks images use-build COOKBOOK_UUID \
  --image IMAGE_UUID --build BUILD_UUID --view-type individual \
  --page 1 --recipe hello-world --phase now --step 1 --format=json

ssh LEMC_ALIAS cookbooks lifecycle published COOKBOOK_UUID \
  --value true --format=json

ssh LEMC_ALIAS apps create \
  --name tutorial-01-hello-world \
  --cookbook-uuid COOKBOOK_UUID --format=json

ssh LEMC_ALIAS jobs run app --uuid APP_UUID --page 1 \
  --scope individual --recipe hello-world \
  --idempotency-key REQUEST_UUID --follow --render plain
```

## Expected result

The Builder execution and recipe task both reach a successful terminal state.
The job output contains exactly this lesson marker:

```text
Hello from Let'em Cook!
```

The Cookbook image coordinate shows a LEMC-managed `@sha256:` reference. It
does not show `tutorial-hello-world:dev` at run time.

## Cleanup and retry

In Web, remove the test App, archive the Cookbook, and archive the Development
Image. Confirm that no job remains active. If a mutation has an unknown result,
retry it with the same idempotency key. Use a new key only for a new action.

LEMCSSH can archive the Cookbook with `cookbooks lifecycle archived
COOKBOOK_UUID --value true`. Read the image lifecycle first, then archive the
current revision with `builder images lifecycle archive IMAGE_UUID
--expected-revision REVISION --idempotency-key REQUEST_UUID`.

## Security and cost

The source contains no credential or secret. The Builder runs on the server in
a jailed guest. LEMCSSH sends bounded source bytes; it does not open a shell or
run Docker on the SSH host. The lesson has no external cloud cost.

## Troubleshooting

- `permission denied` means your current account lacks the named create or run
  permission. Ask an account administrator; do not use a host shell.
- `expected revision` means another source or lifecycle mutation won. Read the
  current object and retry with its returned revision.
- An image preflight error for `:dev` means step 5 was not complete. Bind the
  verified build and confirm the managed digest before another run.
- A replayed idempotency result is success for the earlier accepted request.
  Do not submit a different payload with the same key.
- A failed Builder or job state is terminal. Open its exact execution or task
  detail, fix the source, save a new revision, and start a new intended run.

## Internal validation

Repository maintainers can run `./scripts/validate.sh` from the examples root.
This is a static and local parity gate, not a public `lemcli` workflow.