docs update (#1125)

- **Add all the attributes as reference material**
- **Better completeness**

<!-- ELLIPSIS_HIDDEN -->

----

> [!IMPORTANT]
> Adds detailed documentation for BAML attributes and updates navigation
in `docs.yml`.
> 
>   - **Documentation**:
> - Adds detailed documentation for BAML attributes: `@alias`,
`@assert`, `@check`, `@description`, `@skip`, and `@@dynamic`.
> - Each attribute has its own `.mdx` file explaining usage, benefits,
and prompt impact.
>   - **Navigation**:
> - Updates `docs.yml` to include new attribute documentation pages
under the "Attributes" section.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=BoundaryML%2Fbaml&utm_source=github&utm_medium=referral)<sup>
for 250a3d5. It will automatically
update as commits are pushed.</sup>

<!-- ELLIPSIS_HIDDEN -->

fern/03-reference/baml/attributes/alias.mdx

@@ -0,0 +1,69 @@
+The `@alias` attribute in BAML is used to rename fields or values for better understanding by the LLM, while keeping the original name in your code. This is particularly useful for prompt engineering, as it allows you to provide a more intuitive name for the LLM without altering your existing codebase.
+
+## Prompt Impact (class)
+
+### Without `@alias`
+
+```baml BAML
+class MyClass {
+  property1 string
+}
+```
+
+**ctx.output_format:**
+
+```
+{
+  property1: string
+}
+```
+
+### With `@alias`
+
+```baml BAML
+class MyClass {
+  property1 string @alias("name")
+}
+```
+
+**ctx.output_format:**
+
+```
+{
+  name: string
+}
+```
+
+## Prompt Impact (enum)
+
+```baml BAML
+enum MyEnum {
+  Value1 
+  // Note that @@alias is applied to the enum itself, not the value
+  @@alias("My Name")
+}
+```
+
+**ctx.output_format:**
+
+```
+My Name
+---
+Value1
+```
+
+## Prompt Impact (enum value)
+
+```baml BAML
+enum MyEnum {
+  Value1 @alias("Something")
+}
+```
+
+**ctx.output_format:**
+
+```
+MyEnum
+---
+Something
+```

fern/03-reference/baml/attributes/assert.mdx

@@ -0,0 +1,39 @@
+The `@assert` attribute in BAML is used for strict validations. If a type fails an `@assert` validation, it will not be returned in the response, and an exception will be raised if it's part of the top-level type.
+
+## Usage
+
+Asserts can be named or unnamed.
+
+### Field Assertion
+
+```baml BAML
+class Foo {
+  // @assert will be applied to the field with the name "bar"
+  bar int @assert(between_0_and_10, {{ this > 0 and this < 10 }})
+}
+```
+
+```baml BAML
+class Foo {
+  // @assert will be applied to the field with no name
+  bar int @assert({{ this > 0 and this < 10 }})
+}
+```
+
+```baml BAML
+class MyClass {
+  // @assert will be applied to each element in the array
+  my_field (string @assert(is_valid_email, {{ this.contains("@") }}))[]
+}
+```
+
+### Parameter Assertion
+
+Asserts can also be applied to parameters.
+
+```baml BAML
+function MyFunction(x: int @assert(between_0_and_10, {{ this > 0 and this < 10 }})) {
+  client "openai/gpt-4o"
+  prompt #"Hello, world!"#
+}
+```

fern/03-reference/baml/attributes/attributes-overview.mdx

@@ -0,0 +1,46 @@
+In BAML, attributes are used to provide additional metadata or behavior to fields and types. They can be applied at different levels, such as field-level or block-level, depending on their intended use.
+
+## Field-Level Attributes
+
+Field-level attributes are applied directly to individual fields within a class or enum. They modify the behavior or metadata of that specific field.
+
+### Examples of Field-Level Attributes
+
+- **`@alias`**: Renames a field for better understanding by the LLM.
+- **`@description`**: Provides additional context to a field.
+- **`@skip`**: Excludes a field from prompts or parsing.
+- **`@assert`**: Applies strict validation to a field.
+- **`@check`**: Adds non-exception-raising validation to a field.
+
+```baml BAML
+class MyClass {
+  property1 string @alias("name") @description("The name of the object")
+  age int? @check(positive, {{ this > 0 }})
+}
+```
+
+## Block-Level Attributes
+
+Block-level attributes are applied to an entire class or enum, affecting all fields or values within that block. They are used to modify the behavior or metadata of the entire block.
+
+### Examples of Block-Level Attributes
+
+- **`@@dynamic`**: Allows dynamic modification of fields or values at runtime.
+
+```baml BAML
+class MyClass {
+  property1 string
+  property2 int?
+
+  @@dynamic // allows adding fields dynamically at runtime
+}
+```
+
+## Key Differences
+
+- **Scope**: Field-level attributes affect individual fields, while block-level attributes affect the entire class or enum.
+- **Usage**: Field-level attributes are used for specific field modifications, whereas block-level attributes are used for broader modifications affecting the whole block.
+
+Understanding the distinction between these types of attributes is crucial for effectively using BAML to define and manipulate data structures.
+
+For more detailed information on each attribute, refer to the specific attribute pages in this section. 

fern/03-reference/baml/attributes/check.mdx

@@ -0,0 +1,18 @@
+The `@check` attribute in BAML adds validations without raising exceptions if they fail. This allows the validations to be inspected at runtime.
+
+## Usage
+
+### Field Check
+
+```baml BAML
+class Foo {
+  bar int @check(less_than_zero, {{ this < 0 }})
+}
+```
+
+## Benefits
+
+- **Non-Intrusive Validation**: Allows for validation checks without interrupting the flow of data processing.
+- **Runtime Inspection**: Enables inspection of validation results at runtime.
+
+See more in [validations guide](/guide/baml-advanced/validations). 

fern/03-reference/baml/attributes/description.mdx

@@ -0,0 +1,94 @@
+The `@description` attribute in BAML provides additional context to fields or values in prompts. This can help the LLM understand the intended use or meaning of a field or value.
+
+## Prompt Impact
+
+### Without `@description`
+
+```baml BAML
+class MyClass {
+  property1 string
+}
+```
+
+**ctx.output_format:**
+
+```
+{
+  property1: string
+}
+```
+
+### With `@description`
+
+```baml BAML
+class MyClass {
+  property1 string @description("The name of the object")
+}
+```
+
+**ctx.output_format:**
+
+```
+{
+  // The name of the object
+  property1: string
+}
+```
+
+## Prompt Impact (enum - value)
+
+### Without `@description`
+
+```baml BAML
+enum MyEnum {
+  Value1
+  Value2
+}
+```
+
+**ctx.output_format:**
+
+```
+MyEnum
+---
+Value1
+Value2
+```
+
+### With `@description`
+
+```baml BAML
+enum MyEnum {
+  Value1 @description("The first value")
+  Value2 @description("The second value")
+}
+```
+
+**ctx.output_format:**
+
+```
+MyEnum
+---
+Value1 // The first value
+Value2 // The second value
+```
+
+## Prompt Impact (enum)
+
+```baml BAML
+enum MyEnum {
+  Value1
+  Value2
+
+  @@description("This enum represents status codes")
+}
+```
+
+**ctx.output_format:**
+
+```
+MyEnum: This enum represents status codes
+---
+Value1
+Value2
+```

fern/03-reference/baml/attributes/dynamic.mdx

@@ -0,0 +1,80 @@
+The `@@dynamic` attribute in BAML allows for the dynamic modification of fields or values at runtime. This is particularly useful when you need to adapt the structure of your data models based on runtime conditions or external inputs.
+
+## Usage
+
+### Dynamic Classes
+
+The `@@dynamic` attribute can be applied to classes, enabling the addition of fields dynamically during runtime.
+
+```baml BAML
+class MyClass {
+  property1 string
+  property2 int?
+
+  @@dynamic // allows adding fields dynamically at runtime
+}
+```
+
+### Dynamic Enums
+
+Similarly, the `@@dynamic` attribute can be applied to enums, allowing for the modification of enum values at runtime.
+
+```baml BAML
+enum MyEnum {
+  Value1
+  Value2
+
+  @@dynamic // allows modifying enum values dynamically at runtime
+}
+```
+
+## Using `@@dynamic` with TypeBuilder
+
+To modify dynamic types at runtime, you can use the `TypeBuilder` from the `baml_client`. Below are examples for Python, TypeScript, and Ruby.
+
+### Python Example
+
+```python
+from baml_client.type_builder import TypeBuilder
+from baml_client import b
+
+async def run():
+  tb = TypeBuilder()
+  tb.MyClass.add_property('email', tb.string())
+  tb.MyClass.add_property('address', tb.string()).description("The user's address")
+  res = await b.DynamicUserCreator("some user info", { "tb": tb })
+  # Now res can have email and address fields
+  print(res)
+```
+
+### TypeScript Example
+
+```typescript
+import TypeBuilder from '../baml_client/type_builder'
+import { b } from '../baml_client'
+
+async function run() {
+  const tb = new TypeBuilder()
+  tb.MyClass.addProperty('email', tb.string())
+  tb.MyClass.addProperty('address', tb.string()).description("The user's address")
+  const res = await b.DynamicUserCreator("some user info", { tb: tb })
+  // Now res can have email and address fields
+  console.log(res)
+}
+```
+### Ruby Example
+
+```ruby
+require_relative 'baml_client/client'
+
+def run
+  tb = Baml::TypeBuilder.new
+  tb.MyClass.add_property('email', tb.string)
+  tb.MyClass.add_property('address', tb.string).description("The user's address")
+
+  res = Baml::Client.dynamic_user_creator(input: "some user info", baml_options: {tb: tb})
+  # Now res can have email and address fields
+  puts res
+end
+```
+

fern/03-reference/baml/attributes/skip.mdx

@@ -0,0 +1,38 @@
+The `@skip` attribute in BAML is used to exclude certain fields or values from being included in prompts or parsed responses. This can be useful when certain data is not relevant for the LLM's processing.
+
+## Prompt Impact
+
+### Without `@skip`
+
+```baml BAML
+enum MyEnum {
+  Value1
+  Value2
+}
+```
+
+**ctx.output_format:**
+
+```
+MyEnum
+---
+Value1
+Value2
+```
+
+### With `@skip`
+
+```baml BAML
+enum MyEnum {
+  Value1
+  Value2 @skip
+}
+```
+
+**ctx.output_format:**
+
+```
+MyEnum
+---
+Value1
+```