@alzulejos/laranja-docs 0.2.4

package/content/reference/commands.md

@@ -0,0 +1,193 @@
+---
+title: CLI commands
+description: Every laranja command and flag.
+order: 1
+---
+
+# CLI commands
+
+```
+laranja <command> [project-dir] [flags]
+```
+
+`project-dir` defaults to the current directory, so most of the time you just run
+`laranja deploy`. Run `laranja --help` for a summary.
+
+> **Most commands need your account.** `plan`, `deploy`, and `eject` build your
+> template on the laranja server, so they need a `LARANJA_API_KEY` and a
+> `projectId` in your config. Run [`laranja init`](#init) once to sign in and link
+> a project; the key is stored in `~/.laranja/auth.json` so you don't re-export
+> it. Your **source code never leaves your machine** — only a description of your
+> infrastructure does
+> (see [how it works](../getting-started/how-it-works.md)).
+
+## Global flags
+
+| Flag | Applies to | Description |
+|---|---|---|
+| `--stage`, `-s <name>` | deploy, plan, destroy, logs, eject | Target [stage](../guides/stages-and-environments.md); overrides `config.stage`. |
+| `--verbose`, `-v` | deploy | Stream full CDK/CloudFormation output instead of the compact UI. |
+| `--strict` | deploy | Fail if any [`env()`](../guides/environment-variables.md#values-from-your-environment--env) value is unset (default: warn). |
+
+---
+
+## `init`
+
+Sign in and scaffold a `laranja.config.ts` in the project directory.
+
+```bash
+laranja init
+```
+
+`init` prompts for your **laranja API key** (from the dashboard) and validates it
+against the server before writing anything, then stores it in
+`~/.laranja/auth.json` so later commands don't need it re-exported. It then lets
+you **pick or create a dashboard project** and fills the scaffolded config's
+`name` and `projectId` for you. Edit the file afterwards to set your `region`,
+`env`, and `compute`. See the [config reference](./config-file.md).
+
+---
+
+## `logout`
+
+Remove the stored API key (`~/.laranja/auth.json`).
+
+```bash
+laranja logout
+```
+
+After this, commands that talk to the server (`init`, `plan`, `deploy`, `eject`)
+need `LARANJA_API_KEY` in the environment again, or another `laranja init`.
+
+---
+
+## `plan`
+
+Preview what a deploy would do — laranja synthesizes your template on the server,
+diffs it against the stack **currently deployed** in your AWS account, and prints
+your app's resources tagged **created / changed / unchanged**. Nothing is applied.
+
+```bash
+laranja plan
+laranja plan --stage prod
+```
+
+```
+Plan for "my-api-dev"
+
+= http     HTTP   2 routes → proxy Lambda + Function URL
++ daily    Cron   Lambda + EventBridge rule
+~ emails   Queue  SQS + consumer Lambda
+
+8 AWS resources  +3 created  ~2 changed  =3 unchanged
+```
+
+`+` is new, `~` changed, `=` unchanged. The bottom line tallies the underlying
+AWS resources.
+
+`plan` needs `LARANJA_API_KEY` (run [`laranja init`](#init) first) to synthesize,
+and a working **AWS credential chain** to read your live stack. It is
+**read-only** — it never creates a deployment or counts against your deploy limit.
+
+| Flag | Description |
+|---|---|
+| `--stage`, `-s` | Target stage. |
+
+---
+
+## `deploy`
+
+Deploy into your AWS account using your **local** AWS credentials. The template is
+synthesized on the laranja server first, then applied with your own credentials —
+so deploy needs both `LARANJA_API_KEY` (run [`laranja init`](#init) first) and a
+working AWS credential chain.
+
+```bash
+laranja deploy
+laranja deploy --stage prod
+laranja deploy --verbose
+```
+
+- The first deploy to a new account/region prompts to **bootstrap** (a one-time
+  setup in your account).
+- On success it prints your outputs — the HTTPS URL, queue URLs, and the cron
+  jobs deployed.
+
+| Flag | Description |
+|---|---|
+| `--stage`, `-s` | Target stage. |
+| `--verbose`, `-v` | Stream full CDK output. |
+| `--strict` | Fail the deploy if any [`env()`](../guides/environment-variables.md#values-from-your-environment--env) value is unset. By default these are deployed with a warning. |
+
+---
+
+## `destroy`
+
+Tear down the deployed stack and all its resources. Prompts for confirmation.
+
+```bash
+laranja destroy
+laranja destroy --stage prod
+```
+
+> Targets the stack for the resolved stage — make sure `--stage` matches the
+> environment you intend to remove.
+
+| Flag | Description |
+|---|---|
+| `--stage`, `-s` | Target stage. |
+
+---
+
+## `logs`
+
+Tail CloudWatch logs for your deployed functions. The live stack is the source of
+truth — no local state needed.
+
+```bash
+laranja logs                 # interactive picker (TTY)
+laranja logs sendEmail       # tail a specific function by name
+laranja logs --all           # tail every function, multiplexed
+laranja logs --no-follow     # print recent history and exit
+laranja logs --since 30m     # history look-back window
+laranja logs --stage prod    # functions for the prod stack
+```
+
+| Flag / arg | Description |
+|---|---|
+| `<name>` (positional) | Function to tail (matched against its short label or full name). |
+| `--all` | Tail every function in the stack, multiplexed. |
+| `--no-follow` | Print the recent history window and exit (no live tail). |
+| `--since <dur>` | History look-back, e.g. `30s`, `15m`, `1h`, `2d` (default `1h`). |
+| `--stage`, `-s` | Target stage. |
+
+Both a directory and a function name can be passed as positionals —
+`laranja logs ./app sendEmail` works.
+
+---
+
+## `eject`
+
+Generate a standalone, owned **CDK project** from your app and stop — for when
+you've outgrown the abstraction and want full control. **Paid feature.**
+
+```bash
+laranja eject
+laranja eject --force      # overwrite an existing ./infra
+laranja eject --stage prod
+```
+
+The CDK project is generated **on the laranja server** (which gates the paid
+entitlement) and written to `./infra` — a complete project you own and run
+yourself (`cd infra && npm install && npm run deploy`). Requires `LARANJA_API_KEY`
+and a `projectId`; if your account can't eject, the server returns a clear error.
+
+| Flag | Description |
+|---|---|
+| `--force` | Overwrite an existing `infra/` directory. |
+| `--stage`, `-s` | Target stage (baked into the generated project). |
+
+## Related
+
+- [Stages & environments](../guides/stages-and-environments.md)
+- [How it works](../getting-started/how-it-works.md)

package/content/reference/config-file.md

@@ -0,0 +1,114 @@
+---
+title: Config file
+description: Every field in laranja.config.ts, with defaults and behavior.
+order: 2
+---
+
+# `laranja.config.ts`
+
+Every project has a `laranja.config.ts` at its root that `export default`s a
+config object. It's a TypeScript module (loaded via `tsx`), so you get full type
+checking and can compute values if you need to.
+
+```ts
+import type { LaranjaConfig } from "@alzulejos/laranja-decorators";
+
+const config: LaranjaConfig = {
+  name: "my-api",
+  // From your laranja dashboard — identifies this project on the server.
+  projectId: "proj_…",
+  region: "us-east-1",
+  env: { LOG_LEVEL: "info" },
+  // Default compute for every function (the HTTP proxy + each cron/queue).
+  compute: { memory: 256, timeout: 30 },
+};
+
+export default config;
+```
+
+The config stays minimal because the HTTP app is declared in code with the
+[`http()`](./decorators-and-markers.md#http) marker — there's no config field for
+it. For a deploy with no HTTP app, just omit the marker (see
+[workers-only deployments](../guides/http-apps.md#workers-only-deployments)). Run
+[`laranja init`](./commands.md#init) to scaffold this file — it fills in
+`name` and `projectId` from the dashboard project you pick.
+
+## Fields
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `name` | ✅ | — | App name. Used for the CloudFormation stack and all resource names. |
+| `region` | | `AWS_REGION` / `AWS_DEFAULT_REGION` | AWS region to deploy to. |
+| `stage` | | `"dev"` | Deployment stage. Part of the stack + resource names and injected as the `STAGE` env var. Override per-run with [`--stage`](../guides/stages-and-environments.md). |
+| `profile` | | — | AWS named profile to deploy with. |
+| `framework` | | _auto-detected_ | Override framework detection (e.g. `"express"`). |
+| `env` | | `{}` | Plain environment variables injected into every Lambda. See [Environment variables](../guides/environment-variables.md). |
+| `compute` | | `{ memory: 256, timeout: 30 }` | Default memory (MB) and timeout (s) for **every** function. See [compute](#compute). |
+| `resources` | | `{}` | Per-resource overrides keyed by resource id (`http`, or a cron/queue id). See [resources](#resources). |
+| `projectId` | ✅ | — | Project id from the laranja dashboard. Required by the server-side build (`plan`/`deploy`/`eject`); `laranja init` fills it in. |
+| `provider` | | `"aws"` | Target cloud. Only `"aws"` is implemented today. |
+
+### `name`
+
+Drives the stack name (`‹name›-‹stage›`) and every resource name
+(`‹name›-‹fn›-‹stage›`). Choose something short and stable — renaming it after a
+deploy creates a _new_ stack rather than renaming the old one.
+
+### `region` and `profile`
+
+`region` falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`. If none is set,
+the CLI errors with a clear message. `profile` selects a named profile from your
+AWS credentials file; otherwise the default credential chain is used.
+
+### `stage`
+
+The default is `"dev"`. It's part of resource names and is injected into every
+Lambda as `process.env.STAGE`. The [`--stage`](../guides/stages-and-environments.md)
+flag overrides it per command — the recommended way to drive multiple
+environments from one config.
+
+### `compute`
+
+The default **memory** (MB) and **timeout** (seconds) applied to every function —
+the HTTP proxy and each cron/queue consumer. The scaffold sets
+`{ memory: 256, timeout: 30 }`:
+
+```ts
+const config: LaranjaConfig = {
+  name: "my-api",
+  projectId: "proj_…",
+  compute: { memory: 512, timeout: 20 },
+};
+```
+
+### `resources`
+
+Per-resource overrides, keyed by **resource id** — `http` for the proxy, or the
+[`id`](./decorators-and-markers.md#cron) of a cron/queue. Each entry
+merges field-by-field on top of `compute`, and queue/cron entries also accept
+their kind-specific knobs (e.g. a queue's `visibilityTimeout`). An unknown id is
+a hard error, so a typo can't silently no-op:
+
+```ts
+const config: LaranjaConfig = {
+  name: "my-api",
+  projectId: "proj_…",
+  compute: { memory: 256, timeout: 30 },
+  resources: {
+    http: { memory: 512 },               // beefier proxy
+    cleanup: { timeout: 60 },            // a slow cron by its id
+    emails: { visibilityTimeout: 180 },  // a queue by its name/id
+  },
+};
+```
+
+### Workers-only deployments
+
+To deploy only your workers (`@Cron` / `@Queue`) with no HTTP app — for teams
+whose API is hosted elsewhere — simply don't add an `http()` marker. No flag is
+needed. See [workers-only deployments](../guides/http-apps.md#workers-only-deployments).
+
+## Related
+
+- [Environment variables](../guides/environment-variables.md)
+- [Stages & environments](../guides/stages-and-environments.md)

package/content/reference/decorators-and-markers.md

@@ -0,0 +1,310 @@
+---
+title: Decorators & markers
+description: API reference for @Cron, @Queue, cron, queue, getQueue, and http.
+order: 3
+---
+
+# Decorators & markers
+
+All of these are imported from `@alzulejos/laranja-decorators`. They are **static markers**
+— the [scanner](../getting-started/how-it-works.md#1-scan) reads them at build time to
+shape your infrastructure. At runtime they are near-no-ops (they don't wrap or
+intercept your functions), so they're safe to leave in place.
+
+```bash
+npm install @alzulejos/laranja-decorators
+```
+
+The schedule builders [`rate`](../guides/schedules.md#ratevalue-unit) and
+[`every`](../guides/schedules.md#everyunit) are re-exported here too, so you can
+import them alongside `@Cron`. For `@nestjs/schedule` compatibility, the
+`CronExpression` enum, `@Interval`, and `@Timeout` are re-exported as well — so a
+Nest app can repoint its import at `@alzulejos/laranja-decorators` unchanged.
+
+---
+
+## `@Cron`
+
+Schedules a class method. Each `@Cron` becomes [its own Lambda + EventBridge
+rule](./what-gets-deployed.md#cron--lambda--eventbridge-rule).
+
+```ts
+function Cron(schedule: ScheduleInput): MethodDecorator
+function Cron(options: CronOptions): MethodDecorator
+function Cron(expression: string, options?: NestCronOptions): MethodDecorator  // @nestjs/schedule form
+```
+
+```ts
+import { Cron, rate, CronExpression } from "@alzulejos/laranja-decorators";
+
+export class Jobs {
+  @Cron(rate(5, "minutes"))
+  async refreshCache() {}
+
+  @Cron({ schedule: "cron(0 12 * * ? *)", id: "daily-report" })
+  async report() {}
+
+  // @nestjs/schedule style — a node-cron string or CronExpression, translated for you
+  @Cron("0 3 * * *", { name: "nightly", timeZone: "Europe/Lisbon" })
+  async nightly() {}
+
+  @Cron(CronExpression.EVERY_30_MINUTES)
+  async sweep() {}
+}
+```
+
+**`CronOptions`** (laranja form)
+
+| Field | Type | Description |
+|---|---|---|
+| `schedule` | `ScheduleInput` | A [`rate()`/`every()`](../guides/schedules.md) result, a `Schedule`, or a raw string. |
+| `id` | `string` _(optional)_ | Stable logical id. Defaults to `‹Class›-‹method›`; also drives the Lambda name. |
+
+**`NestCronOptions`** (the second argument in the `@nestjs/schedule` form)
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` _(optional)_ | Used as the resource `id`. |
+| `timeZone` | `string` _(optional)_ | IANA timezone the schedule is evaluated in. |
+
+See [Schedules → node-cron expressions](../guides/schedules.md#node-cron-expressions-nestjsschedule-compatibility)
+for the accepted syntax and what's rejected. Nest providers resolve through DI —
+declare your module with [`workers()`](#workers).
+
+---
+
+## `cron()` marker
+
+Function-style counterpart to `@Cron`, for codebases that don't use classes.
+Registers a standalone exported function on a schedule.
+
+```ts
+function cron(schedule: ScheduleInput, handler: JobHandler): void
+function cron(options: CronOptions, handler: JobHandler): void
+```
+
+```ts
+import { cron, rate } from "@alzulejos/laranja-decorators";
+
+export async function refreshCache() {}
+
+cron(rate(5, "minutes"), refreshCache);
+cron({ schedule: rate(1, "hour"), id: "hourly-sync" }, refreshCache);
+```
+
+The function's name becomes the resource id unless you pass an explicit `id`.
+
+---
+
+## `@Interval`
+
+`@nestjs/schedule`-compatible. Runs a method every _N_ milliseconds; laranja
+lowers it to a `rate(...)`, so the interval must be a whole number of minutes
+(EventBridge's 1-minute floor).
+
+```ts
+function Interval(milliseconds: number): MethodDecorator
+function Interval(name: string, milliseconds: number): MethodDecorator
+```
+
+```ts
+import { Interval } from "@alzulejos/laranja-decorators";
+
+export class Jobs {
+  @Interval(300000)          // every 5 minutes
+  async poll() {}
+}
+```
+
+---
+
+## `@Timeout`
+
+Re-exported for `@nestjs/schedule` source compatibility, but a one-shot timer
+relative to process start has no serverless equivalent — laranja **rejects it at
+build time** with a clear message. Use [`@Cron`](#cron) or [`@Interval`](#interval)
+instead.
+
+---
+
+## `@Queue`
+
+Consumes messages from an SQS queue. Each `@Queue` becomes [an SQS queue +
+consumer Lambda](./what-gets-deployed.md#queue--sqs-queue--consumer-lambda).
+The handler is called once per message with the JSON-parsed body.
+
+```ts
+function Queue(options: QueueOptions): MethodDecorator
+```
+
+```ts
+import { Queue } from "@alzulejos/laranja-decorators";
+
+export class Workers {
+  @Queue({ name: "emails", batchSize: 10 })
+  async sendEmail(body: unknown) {}
+
+  @Queue({ name: "orders.fifo", fifo: true })
+  async processOrder(body: unknown) {}
+}
+```
+
+**`QueueOptions`**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | _required_ | Queue name. A `.fifo` suffix marks a FIFO queue. |
+| `batchSize` | `number` | `10` | Max messages per consumer invocation. |
+| `fifo` | `boolean` | `false` | Force a FIFO queue (or end `name` with `.fifo`). When set, laranja appends `.fifo` to `name` if you left it off. |
+
+---
+
+## `queue()` marker
+
+Function-style counterpart to `@Queue`.
+
+```ts
+function queue(options: QueueOptions, handler: JobHandler): void
+```
+
+```ts
+import { queue } from "@alzulejos/laranja-decorators";
+
+export async function sendEmail(body: unknown) {}
+
+queue({ name: "emails", batchSize: 10 }, sendEmail);
+```
+
+---
+
+## `getQueue()`
+
+The queue **producer** — get a handle to a declared queue and `.send()` messages
+to it. The counterpart to the [`@Queue`](#queue) / [`queue()`](#queue-marker)
+consumers. Unlike the markers, this does real work at runtime (a single SQS
+`SendMessage`); laranja injects the queue URL and grants `sqs:SendMessage` to
+every function, so there's nothing to configure.
+
+```ts
+function getQueue(name: string): LaranjaQueue
+
+interface LaranjaQueue {
+  readonly url: string;
+  send(payload: unknown, options?: SendOptions): Promise<{ messageId?: string }>;
+}
+```
+
+```ts
+import { getQueue } from "@alzulejos/laranja-decorators";
+
+await getQueue("emails").send({ to, subject });
+await getQueue("orders.fifo").send(order, { groupId: order.customerId });
+```
+
+`payload` is JSON-serialized (strings are sent as-is). `name` is the queue's
+declared `name`; a send to an undeclared queue throws.
+
+**`SendOptions`**
+
+| Field | Type | Applies to | Description |
+|---|---|---|---|
+| `groupId` | `string` | FIFO (**required**) | `MessageGroupId` — orders messages within a group. A FIFO send throws without it. |
+| `dedupId` | `string` | FIFO | `MessageDeduplicationId` — only needed when content-based dedup is off. |
+| `delaySeconds` | `number` | Standard | Delay (0–900s) before the message becomes visible. Ignored by FIFO. |
+
+See [Queues → Sending messages](../guides/queues.md#sending-messages).
+
+---
+
+## `http()`
+
+Marks the HTTP app (the proxy target) in code — the only way to declare one.
+Export the result so the scanner can find it.
+
+```ts
+function http<T>(app: T): T
+```
+
+```ts
+import express from "express";
+import { http } from "@alzulejos/laranja-decorators";
+
+const app = express();
+export default http(app);          // or: export const api = http(app);
+```
+
+It returns its argument untouched — purely a static marker. Omit it for a
+[workers-only](../guides/http-apps.md#workers-only-deployments) deployment.
+
+For **NestJS**, wrap your async `bootstrap` factory (which `return`s the app)
+instead of an app instance — see [HTTP apps → NestJS](../guides/http-apps.md#nestjs):
+
+```ts
+export default http(bootstrap);    // bootstrap: () => Promise<INestApplication>
+```
+
+---
+
+## `workers()`
+
+**NestJS only.** Declares the module laranja builds a dependency-injection
+context from, so class-based [`@Cron`](#cron) / [`@Queue`](#queue) providers
+resolve their injected dependencies at runtime (via
+`NestFactory.createApplicationContext`) instead of a bare `new`. The DI
+counterpart to [`http()`](#http); export it so the scanner can find it.
+
+```ts
+function workers<T>(module: T): T
+```
+
+```ts
+import { workers } from "@alzulejos/laranja-decorators";
+import { AppModule } from "./app.module";
+
+export default workers(AppModule);   // or: export const jobs = workers(AppModule);
+```
+
+Pass `AppModule` for the whole graph, or a leaner module for a smaller cold
+start. There's exactly one per project. Required when a Nest project has
+class-based workers; standalone [`cron()`](#cron-marker)/[`queue()`](#queue-marker)
+functions don't need it (no DI). Returns its argument untouched — a static marker.
+
+---
+
+## `env()`
+
+Declares an environment variable your code needs. At runtime it just returns
+`process.env[name]`; laranja discovers each call and populates that variable on
+every deployed function, with the value supplied from your shell or CI at deploy
+time.
+
+```ts
+function env(name: string): string | undefined
+```
+
+```ts
+import { env } from "@alzulejos/laranja-decorators";
+
+const dbUrl = env("DATABASE_URL");
+```
+
+The name must be a **string literal** so it can be found statically. See
+[environment variables](../guides/environment-variables.md#values-from-your-environment--env)
+for supplying values, the `--strict` flag, and per-stage usage.
+
+---
+
+## Types
+
+| Type | Description |
+|---|---|
+| `ScheduleInput` | `Schedule \| string` — anything accepted where a schedule is expected. |
+| `Schedule` | Provider-neutral schedule: `{ kind: "rate", value, unit }` or `{ kind: "cron", expression, dialect }`. |
+| `RateUnit` | `"minute" \| "minutes" \| "hour" \| "hours" \| "day" \| "days"`. |
+| `CronExpression` | Enum of common cron strings, mirrored from `@nestjs/schedule`. |
+| `JobHandler` | `(...args) => unknown \| Promise<unknown>` — a `cron()`/`queue()` handler. |
+
+## Related
+
+- [Cron jobs](../guides/cron-jobs.md) · [Queues](../guides/queues.md) · [Schedules](../guides/schedules.md)
+- [HTTP apps](../guides/http-apps.md)

package/content/reference/what-gets-deployed.md

@@ -0,0 +1,84 @@
+---
+title: What gets deployed
+description: The exact AWS resources laranja creates and how they're named.
+order: 4
+---
+
+# What gets deployed
+
+laranja maps each thing it finds in your code to a small, predictable set of AWS
+resources — all in your own account.
+
+## HTTP app → proxy Lambda + Function URL
+
+Your entire Express app is deployed as **one Lambda function** fronted by a
+**Lambda Function URL**. There is no API Gateway.
+
+- All routes are served by this single proxy Lambda.
+- The Function URL is **public** (`authType: NONE`) and CORS is open
+  (`*` origins, all methods, all headers) — your app handles auth/CORS as it
+  sees fit.
+- Memory and timeout come from [`compute`](./config-file.md#compute)
+  in your config (the scaffold sets `{ memory: 256, timeout: 30 }`), overridable
+  per-resource under the `http` key in [`resources`](./config-file.md#resources).
+- The public HTTPS URL is emitted as the `HttpUrl` stack output.
+
+```
+GET  https://‹id›.lambda-url.‹region›.on.aws/
+```
+
+## `@Cron` → Lambda + EventBridge rule
+
+Each cron handler becomes **its own Lambda** plus an **EventBridge rule** that
+invokes it on schedule.
+
+- Memory and timeout come from [`compute`](./config-file.md#compute)
+  (default `{ memory: 256, timeout: 30 }`), overridable per cron id in
+  [`resources`](./config-file.md#resources).
+- The schedule comes from your [`rate()`/`every()`](../guides/schedules.md)
+  builder or raw expression.
+
+## `@Queue` → SQS queue + consumer Lambda
+
+Each queue handler becomes an **SQS queue** and a **consumer Lambda** wired to it.
+
+- Encryption: **SQS-managed (SSE-SQS)**.
+- **FIFO** queues are created when the name ends in `.fifo` or `fifo: true` is
+  set (content-based deduplication is enabled for FIFO).
+- Default **batch size**: 10. Your handler is invoked per message with the
+  JSON-parsed body.
+- **Partial-batch failures** are enabled: throwing for one message fails only
+  that message; the rest of the batch still succeeds.
+- Consumer memory/timeout come from [`compute`](./config-file.md#compute)
+  (default `{ memory: 256, timeout: 30 }`). The queue's **visibility timeout** is
+  derived to satisfy AWS's rule that it be ≥ the consumer timeout, and can be set
+  explicitly per queue via [`resources`](./config-file.md#resources).
+- The queue URL is emitted as a stack output.
+
+## Naming
+
+Everything is named deterministically — no random suffixes:
+
+| Resource | Pattern | Example |
+|---|---|---|
+| CloudFormation stack | `‹name›-‹stage›` | `my-api-prod` |
+| Lambda functions | `‹name›-‹fn›-‹stage›` | `my-api-app-prod`, `my-api-sendEmail-prod` |
+
+`‹fn›` is the handler's name (the method/function name), or the explicit `id` you
+set on `@Cron`/`@Queue`. The HTTP proxy uses `app`. Names are truncated to AWS's
+64-character limit and sanitized to allowed characters.
+
+Because the stage is part of the names, multiple stages can live in one account
+without colliding — see [Stages & environments](../guides/stages-and-environments.md).
+
+## Supporting resources
+
+Each Lambda gets an **IAM execution role** (and the queue consumers get the
+permissions to read their queue / EventBridge to invoke crons). The first deploy
+to an account/region also creates the one-time CDK **bootstrap** resources (an S3
+asset bucket and roles).
+
+## Related
+
+- [How it works](../getting-started/how-it-works.md)
+- [HTTP apps](../guides/http-apps.md) · [Cron jobs](../guides/cron-jobs.md) · [Queues](../guides/queues.md)