> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# context

> The context block declares a named label group that stacks opt into via meta { context = "name" }.

The `context` block declares a named set of deployment labels and settings. Stacks opt in by naming the context in their `meta {}` block. A context sits between a `workspace {}` and a per-stack `meta {}` in the resolution chain.

## Syntax

```xcl theme={"theme":"css-variables"}
context prod_us {
    labels {
        env    = "prod"
        region = "us-east-1"
    }
    engine  = "native"
    runtime = "xcl"
}
```

The context name (`prod_us`) is a **bare identifier** immediately after the `context` keyword — not a quoted string. Use underscores, not hyphens: `prod_us` not `prod-us`.

Context names must be unique across the compilation unit. A duplicate produces a hard compile error.

## Opting in from a stack

A stack opts in to a context via the `context` field inside its `meta {}` block:

```xcl theme={"theme":"css-variables"}
stack "networking" {
    meta {
        context = "prod_us"
    }
    // ...
}
```

Referencing an undeclared context name is a hard compile error:

```
meta context "prod_eu" is not declared — add: context prod_eu { ... }
```

## labels {} sub-block

Declares the labels that this context contributes to the resolution chain. Labels are key-value string pairs. They are used by `workspace {}` blocks with `match {}` to select which scoped workspace applies.

```xcl theme={"theme":"css-variables"}
context prod_us {
    labels {
        env    = "prod"
        region = "us-east-1"
        tier   = "critical"
    }
}
```

When a stack opts into `prod_us`, its effective labels include `env = "prod"`, `region = "us-east-1"`, and `tier = "critical"`. A label-scoped workspace with `match { env = "prod" }` then applies to that stack.

## Fields

A `context {}` supports the same fields as `workspace {}`, except `name`, `match {}`, and `plugins {}` (which belong only to `workspace {}`).

| Field          | Type   | Default    | Description                                             |
| -------------- | ------ | ---------- | ------------------------------------------------------- |
| `engine`       | string | `"native"` | Execution engine — overrides any workspace value        |
| `runtime`      | string | `"xcl"`    | Codegen runtime — overrides any workspace value         |
| `backend {}`   | block  | —          | State backend override                                  |
| `provider {}`  | block  | —          | Provider config override                                |
| `tags {}`      | block  | —          | Additional tags (merged additively with workspace tags) |
| `hooks {}`     | block  | —          | Hook scripts (concatenated with workspace hooks)        |
| `ai {}`        | block  | —          | AI feature toggle override                              |
| `scan {}`      | block  | —          | Security scan settings override                         |
| `telemetry {}` | block  | —          | Telemetry settings override                             |
| `history {}`   | block  | —          | History settings override                               |

For `engine`, `runtime`, and all sub-blocks except `tags` and `hooks`, the context value wins over the workspace value for any stack that opts into this context. Tags and hooks are always additive — they extend rather than replace.

## backend {} sub-block

```xcl theme={"theme":"css-variables"}
context prod_us {
    backend s3 {
        bucket = "prod-state"
        key    = "stacks/prod-us"
        encryption {
            provider = "awskms"
            key      = "alias/prod-secrets"
        }
    }
}
```

## tags {} sub-block

Tags declared in a context are **added** to any tags set by a workspace block. They do not replace them.

```xcl theme={"theme":"css-variables"}
context prod_us {
    tags {
        environment = "production"
        criticality = "high"
    }
}
```

## hooks {} sub-block

Hooks declared in a context are **appended** to the workspace hooks list. Order follows the resolution chain: workspace hooks first, then context hooks.

```xcl theme={"theme":"css-variables"}
context prod_us {
    hooks {
        before_ship = ["./scripts/prod-checks.sh"]
        after_ship  = ["./scripts/notify-oncall.sh"]
    }
}
```

## Full example

```xcl theme={"theme":"css-variables"}
// contexts.xcl

context prod_us {
    labels {
        env    = "prod"
        region = "us-east-1"
    }
    engine  = "native"
    runtime = "xcl"
    backend s3 {
        bucket = "prod-state"
        key    = "platform/prod-us"
        encryption {
            provider = "awskms"
            key      = "alias/prod-secrets"
        }
    }
    tags {
        environment = "production"
    }
    hooks {
        before_ship = ["./scripts/prod-checks.sh"]
    }
}

context staging_us {
    labels {
        env    = "staging"
        region = "us-east-1"
    }
    engine  = "native"
    runtime = "xcl"
    tags {
        environment = "staging"
    }
}
```

```xcl theme={"theme":"css-variables"}
// networking.xcl
stack "networking" {
    meta {
        context = "prod_us"
    }

    vpc = aws.ec2.Vpc {
        cidr_block = "10.0.0.0/16"
    }
}
```

```xcl theme={"theme":"css-variables"}
// app.xcl
stack "app" {
    meta {
        context = "staging_us"
    }

    bucket = aws.s3.BucketV2 {
        bucket = "app-staging"
    }
}
```

## Resolution chain position

Context sits at step 3 in the four-level resolution chain:

1. Universal `workspace {}` — lowest priority
2. Label-matched `workspace {}` — fields override step 1
3. **`context {}` named by the stack's `meta { context = "..." }`** — fields override step 2
4. `meta {}` inside `stack {}` — highest priority

Fields declared in the context override fields from any workspace block. Fields declared in `meta {}` override the context.

See [meta](/v1/xcl/language/meta) for the full resolution reference.

## Error conditions

### Duplicate context name

```
context "prod_us" is declared more than once
```

### Invalid engine value

```
engine "lambda" is not valid — valid values: native, pulumi, terraform
```

### Invalid runtime value

```
runtime "ruby" is not valid — valid values: xcl, python, typescript, go
```

### Incompatible engine / runtime

```
runtime "xcl" requires engine "native" — engine "pulumi" is not compatible
```