docs/README.md

Let'em Cook!

Unhinged, Accelerated DevOps for Agents & Users LEMC turns versioned recipes into discoverable, bounded actions that people click and agents run with LEMCSSH.

Key pages

  • Home — Product overview, sheriff field notes, and the human/agent action model.
  • Documentation — This clickable HTML field guide.
  • Contact — Reach out if you want help scaling your team with Let'em Cook!.
  • Instance guide — A LEMC instance at release 20261002v1 or later serves its own /llms.txt and /llms-full.txt for its commands and YAML. lemcli guide in the LEMCSSH shell prints the full guide.

1. Start here

  • What is Let'em Cook!? — Cookbooks, pages, recipes, steps, and shared execution.
  • Publish a cookbook and grant the team — First Development Image, Cookbook bundle, Provider integration binding, App install, team ACLs, and advanced multi-recipe Apps.
  • Tutorials — Six ordered lessons with complete maintained source, expected output, and cleanup proof.
  • Advanced examples — A Secret-backed GCP Cookbook with explicit teardown and cloud inventory proof.
  • Operational use cases — BYOK WordPress migrations, corporate Nmap PDF reports, timed infrastructure, Terraform labs, restore drills, and Day-2 self-service.
  • Deterministic computational units — The boundary, its limits, and why it helps agents.

Use the public demo

When you only need to run an already-reviewed Tool, open the browser UI at https://demo.letemcook.dev, follow the stock OpenSSH path on the homepage, or use the LEMCSSH field guide. Machine-readable copy lives at llms.txt.

  1. Prefer a browser? Open https://demo.letemcook.dev. Prefer stock OpenSSH? Register at demo.letemcook.dev. No beta request is required.
  2. Create a distinct Ed25519 key, keep the private file at mode 0600, and register only the public half. Add a Host demo.letemcook.dev block with User, IdentityFile, IdentitiesOnly yes, and StrictHostKeyChecking yes.
  3. A person signs up with ssh -t demo.letemcook.dev. If OpenSSH asks for a Password:, leave it empty and press Enter to open signup. Then set User to the username that LEMC shows.
  4. Verify the host-key fingerprint out of band. Pipe lemcli help --all --format=json and lemcli auth whoami --format=json to ssh -T demo.letemcook.dev in one batch (ssh -T demo.letemcook.dev <<'EOF' … EOF) to read the command manifest and confirm identity. A person can run the same lines in the shell that ssh demo.letemcook.dev opens. LEMCSSH refuses a one-shot command after the host name.
  5. Find the action with apps search WORDS, or list authorized apps. Inspect an action surface, and run only a returned action ID with its declared --set values, a new --idempotency-key, and --follow.
  6. Confirm task ID, terminal reason, system and recipe steps, logs, artifacts, and cleanup proof with jobs status, jobs logs, and jobs artifacts list.

Create your first governed capability

Teams author over LEMCSSH or in the Web UI. Each change needs its account permission or grant. The steps below are the product order of operations. The full role split, review checklist, and sample cookbook YAML live in Publish a cookbook and grant the team.

1. First Development Image (Builder)

  1. Inspect remote contracts: lemcli help --all --format=json and lemcli builder images --help.
  2. Create the image with lemcli builder images create --name NAME --description TEXT --format=json <<DOCKERFILE, the Dockerfile lines, and a closing DOCKERFILE line (an input block in a piped batch). Add each source file with builder images source-files put.
  3. Build and test with lemcli builder images compile-run IMAGE_UUID --expected-revision REVISION_UUID --idempotency-key REQUEST_UUID --follow. Wait for state succeeded.
  4. Bind the verified build to each step with cookbooks images use-build, or save its exact local/USERNAME/IMAGE@sha256:DIGEST reference in the YAML. Hosted runs accept only LEMC registry digests. Do not use :latest, :main, another mutable tag, or an outside registry.
  5. The SSH host is not a shell or Docker host. Builds run in fresh jailed guests under LEMC policy. Details: Build through the governed boundary.

2. First cookbook

  1. Keep one reviewable bundle: cookbook.yaml, image sources, optional terraform/, tests, and README.
  2. Define each provider: NAME requirement once in the top-level secrets alias catalog. Each requirement also names secret: USERNAME/SECRET_NAME. A recipe or callback lists only the aliases that it needs.
  3. Point every step image: at a verified Builder build, local/USERNAME/IMAGE@sha256:DIGEST, never :latest. Put exactly one step in each now, in, every, and callback. Hosted jobs do not run a sequence of steps.
  4. Never place Secret values in Git, YAML, agent prompts, command arguments, logs, or artifacts. A Custom Provider requirement names an owner-qualified Secret but carries no value or binding.
  5. A human reviews least privilege, network boundary, idempotency, timeouts, teardown, and proof before promote.

3. First app

  1. Publish the reviewed Cookbook with cookbooks lifecycle published COOKBOOK_UUID --value true. This needs the Cookbook edit grant and a verified build on each Local Image step.
  2. Review and approve the exact Provider Profile version. Create each owner-qualified Secret in the write-only User Secrets catalog.
  3. The Cookbook owner binds every selected Provider requirement on the Cookbook's Providers tab. The app needs no separate setup. Only a selected Custom Provider guest receives plaintext. Each NOW, IN, EVERY, or callback job receives one validated direct alias map of its selected aliases through LEMC_PROVIDER_RESULTS_YAML and its fixed integration context.
  4. Create the app with apps create --cookbook-uuid COOKBOOK_UUID --name NAME. It keeps its own copy of the YAML. apps refresh, or apps versions and apps sync, picks up later Cookbook changes.

4. Share with users and agents

  1. App owners grant only the teammate or agent scope that should run the action: apps acls add APP_UUID --user-id ID gives individual, and apps acls toggle ... --permission shared adds shared.
  2. A run grant does not grant cookbook edit, image publication, secret retrieval, or account administration. Account permissions are separate View and Create switches for Apps, Cookbooks, Development Images, Secrets, and Providers.
  3. Callers discover with apps search, apps list, and jobs surface, then run with jobs run ... --follow.
  4. Browser and LEMCSSH share one durable task identity, step stream, terminal reason, logs, and artifacts. Custom Provider Secret values stay in the selected owner catalog and admitted Provider guest. Callers receive the bounded result, fixed integration context, and redacted proof.

5. More advanced apps

  1. Split capabilities into separate recipes (create, list, delete, launch-from-image) instead of one unbounded shell surface.
  2. Use callbacks and timed or recurring jobs for cleanup, TTL destroy, and governed child jobs with preflight and proof.
  3. Keep Terraform or other durable state under authorized /lemc mounts so later jobs hydrate reviewed state. See Recipe state and LEMC verbs.
  4. Expand form inputs carefully. A hosted guest drops lemc.env lines, so do not depend on them. Use a reviewed Provider for Secret-backed work.
  5. Prefer small, named recipes with explicit proof over a multi-purpose tool that looks like a scanner shell.

2. Humans and agents

3. Runtime and output

  • Architecture — Server-owned execution, isolation, event fanout, and storage.
  • Themes — Managed export, upload, preview, and promote of token-and-PNG bundles; account-admin selection; and agent authority.
  • Recipe state and LEMC verbs — Wire format verb.name;payload, form fields → env, Provider results and context, durable workspaces, artifacts, and visible output.
  • Form fields → env — Field types, variable vs name, value not label, and non-secret precedence.
  • Builder over LEMCSSH — Bounded stdin, jailed compile, digest pin; not a shell or Docker host.

Agent quick path

  1. Fetch /llms.txt for the machine-readable map and both demo and author paths.
  2. Authenticate with the target LEMC server.
  3. List authorized apps, then inspect an action surface with lemcli jobs surface ... --format=json.
  4. Choose a returned action ID and supply only its declared form values. Skip an action that jobs surface marks needs_setup.
  5. Run it with lemcli jobs run ... --action <action-id> --follow --render plain.
  6. Confirm task ID, terminal reason, steps, logs, and artifacts.
  7. When authoring, follow the first-capability steps above and the publish guide before promoting digests or ACLs.

Execution mode, runner selection, and isolation policy are server/operator decisions. Clients do not choose them per request.