lemma-work/lemma-platform/lemma-builder

Lemma Builder

What Is A Pod

A pod is one team's operating system: a shared workspace inside an organization that holds everything one use case needs — tables and files (data, with documents auto-indexed for built-in RAG), functions, agents, workflows, schedules, and connectors (automation), and apps and surfaces (interfaces) — under one permission boundary. Two rules run through all of it: every workload starts with zero access and is granted resources explicitly by name, and a workload acts under the delegated identity of the user who invoked it — so RLS and the personal /me area resolve to that user, and the run can do only what that user could do and the workload was granted. Good pod scope = one team, one operating loop, one coherent data model.

Read `references/pod-model.md` first. It is the canonical model every other

doc grounds in — identity & permissions, the data/automation/interface layers,

how the resources interact, and how a pod is authored. This file is the build

entry point on top of it.

The Resources

Choosing among them — six heuristics (full text in references/pod-model.md → "Choosing a primitive"; pod-design.md turns them into decision tables):

1. One step, one agent. One agent returning rich output_schema beats an agent→agent chain; split only for orthogonal judgments.
2. Workflow = checkpoints + humans. Reach for a workflow when people approve, are assigned steps, or watch progress — not for a lone call.
3. Surface = a human is talking. A chat-platform conversation is a surface; a system event driving unattended work is a schedule → workflow/agent.
4. Events choreograph workloads. A table write or connector trigger starts the next workload (server-side); an app stays live via watchChanges (client-side).
5. Occam's razor. Build the fewest agents and nodes that satisfy the use case.
6. Reach for the most direct primitive. A single record write is a direct records-API call, not a function; a bare agent is called directly or granted as a tool — never wrapped. A function earns its place only for deterministic multi-step work (coordinated writes, write + compute, or a connector call).

The Build Loop

Pods are built as local directory bundles and imported with upsert. This is the primary path — inline lemma <resource> create --data ... is only for quick experiments.

Scaffold, don't hand-write. lemma <resource> init writes a near-runnable, commented bundle file (JSONC — // and /* */ comments and trailing commas are allowed) with the right shape, folder==name wiring, and the backend defaults (visibility, RLS, function headers). Edit it, then import.

lemma pod init my-pod                  # whole starter pod on disk (pod.json + table + agent + AGENTS.md)
# or scaffold into an existing bundle (auto-finds pod.json upward):
lemma tables init tickets [--shared]   # tables/tickets/tickets.json  (--shared = enable_rls:false)
lemma functions init score_ticket      # functions/score_ticket/{score_ticket.json,code.py} with headers
lemma agents init triage [--runtime ID] # agents/triage/{triage.json,instruction.md}
lemma workflows init intake            # a valid FORM->END graph to extend
lemma schedules init nightly           # schedules/nightly/nightly.json
lemma surfaces init slack              # surfaces/slack/slack.json
 
lemma agents grant triage tickets:read,write /knowledge:read connector:gmail:use agent:helper:execute function:score_ticket:execute
#   ^ merges into permissions.grants in place (keeps your JSONC comments): name:perms (table) | /path:perms (folder) | type:name:perms
#     types: table folder document connector app function agent workflow schedule — see references/authorization-model.md §4b
lemma agents permissions add triage tickets:read     # the same grammar against a LIVE pod (read -> merge -> replace)
lemma agents schema                    # or `lemma schema agent` — print the example/shape for a resource type
 
lemma pods create my-pod --with-starter   # create the pod AND scaffold+import a starter in one shot

By hand, or after scaffolding — the bundle is always the source of truth:

lemma pods create my-pod --org <org> --description "..."   # import never creates the pod shell
export LEMMA_POD_ID=<id it printed>                        # a new pod is NOT made active; or pass --pod on each command
 
mkdir my-pod                                               # author the bundle locally
# pod.json + one folder per resource (see layout below)
 
lemma pods import ./my-pod --dry-run                       # validate, fix errors
lemma pods import ./my-pod                                 # upsert by resource name (default)
lemma pods import ./my-pod/functions/score_ticket          # partial imports work too
lemma pods doctor my-pod                                   # check grants/targets/surfaces wiring
 
lemma functions run score_ticket --data '{"title":"test"}' # test each layer
lemma workflows run intake --data '{"id":"REQ-1"}'         # waits for completion by default
lemma agents chat triage-agent "Classify this ticket"
 
# edit files -> re-import -> re-test. Export an existing pod for a baseline (or a template):
lemma pods export ./bundles --force [--as-template]

Bundle layout (folder name must equal the resource's name):

my-pod/
  pod.json
  tables/tickets/tickets.json
  functions/score_ticket/score_ticket.json    + code.py        (JSON carries permissions.grants)
  agents/triage-agent/triage-agent.json       + instruction.md (JSON carries permissions.grants)
  workflows/intake/intake.json
  schedules/nightly/nightly.json
  surfaces/slack/slack.json
  connectors/gmail/gmail.json                  # a pod connector: catalog id, mode, purpose (no credentials)
  apps/ops-app/ops-app.json                + source/
  files/knowledge/.folder.json
  seed/seed.sh                                 # sample data so the pod demos itself (not imported — run after)
  payloads/                                    # test fixtures, not a pod resource
  README.md                                    # operator setup + verification runbook

Build order follows dependencies: connectors → tables → files → functions → agents → workflows → schedules → surfaces → app → seed (grants, schedules and surfaces name a pod connector by slug, so it is declared first). Verify each layer with realistic data before adding the next.

Build for the hero moment, not just for correctness. A pod that imports cleanly and passes its tests can still be plumbing nobody wants to open. Before building, name the one screenshottable "oh" — the agent doing real work on its own, behind an interface someone adopts (see references/pod-design.md). The app (or surface) is usually the product — design it like the thing people live in, not an afterthought tacked on last. And seed the pod so it demos itself: a seed/seed.sh of sample rows, files, and one completed run, so opening the app shows the hero moment immediately instead of an empty state. (Rows and file bytes can travel — pods export --data-table <t> --folder <path> names them one at a time on the way out, and pods import --with-data --with-files applies them on the way in — but a seed/seed.sh is still the better demo path: it is re-runnable and readable. Record it in the README.)

Three rules that bite everyone:

1. Zero access by default, capped by whoever invoked it, and no destructive power without a grant or approval. Agents and functions are created with NO access to anything — not tables, not files/folders, not connectors. Every resource they touch must be granted explicitly, either via permissions.grants in their bundle JSON (exported automatically, replaced on import) or, against a live pod, lemma functions|agents permissions add <name> <resource>:<perms>. Import and lemma pods doctor both flag a workload that ends up with no grants at all — the usual reason a fresh pod 403s. A grant is a ceiling on the workload, not a promotion for the person: a run does the intersection of the workload's grants and the invoking member's own access, so a VIEWER running a write-granted agent still cannot write. MISSING_WORKLOAD_RESOURCE_GRANT means the workload half is missing (grant it); DELEGATION_EXCEEDS_INVOKER means the person half is (fix their role — more grants change nothing); DESTRUCTIVE_ACTION_REQUIRES_APPROVAL means a delete/manage action needs an explicit destructive grant or a user's session approval, which opens the gate without conferring authority. Full 403 decoder + the complete model in references/authorization-model.md.
2. Not everything bundles. Pod connectors (connectors/<slug>/<slug>.json) round-trip, but the org's installations and each member's connected accounts never do — record in the pod's README who has to connect what. Surfaces and workload permissions do round-trip. File bytes and table rows round-trip only when you ask, and the two ends spell it differently: export names each one (--data-table <table>, --folder <path>, repeatable — there is deliberately no "everything" flag), while import takes --with-data / --with-files.
3. Leave a runbook. Every production-quality bundle should include a README with: purpose, required CLI context, non-bundled setup steps, required uploaded files, which connectors each member must connect (or which account is shared), verification payloads, and the final end-to-end smoke test.