diff --git a/fastn.com/CLAUDE.md b/fastn.com/CLAUDE.md
new file mode 100644
index 000000000..d1e45cfad
--- /dev/null
+++ b/fastn.com/CLAUDE.md
@@ -0,0 +1,98 @@
+# Claude Instructions for fastn.com
+
+## Testing FTD Files
+
+**IMPORTANT**: Before committing any changes to `.ftd` files in this repository:
+
+1. **Use RELEASE mode fastn only**:
+   - **ALWAYS** build fastn from source:
+     ```bash
+     cd /Users/amitu/Projects/fastn
+     cargo build --release --bin fastn
+     cp target/release/fastn ~/.cargo/bin/fastn
+     ```
+   - Only use `~/.cargo/bin/fastn` (release build from local source)
+   - **NEVER** use debug builds as they are unstable and will crash
+   - **NEVER** use `cargo install fastn` (gets wrong package from crates.io)
+   - The installation script binary may have dependency issues - use local source
+
+2. **Start the fastn development server**:
+   ```bash
+   cd fastn.com
+   ~/.cargo/bin/fastn serve --port 8001
+   ```
+
+2. **Test your changes in browser**:
+   - Open the modified pages in browser via `http://127.0.0.1:8001/path/to/your/file`
+   - Ensure the page loads without compilation errors
+   - Check that all content renders correctly
+   - Verify any components or imports work as expected
+
+3. **Common paths to test**:
+   - Language spec: `http://127.0.0.1:8001/language-spec/`
+   - FTD components: `http://127.0.0.1:8001/ftd/audio/` 
+   - New documentation: `http://127.0.0.1:8001/your-new-path/`
+
+4. **Fix any compilation errors**:
+   - Check the fastn server output for error messages
+   - Common issues: missing imports, incorrect syntax, circular imports
+   - Test changes iteratively until they work
+
+5. **Only commit after successful testing**
+
+## Common FTD Patterns
+
+- Use existing imports like `fastn.com/assets` and design system components
+- Check existing files for proper component structure and naming
+- Follow the established documentation patterns in `/ftd/` directory
+
+## Lint/TypeCheck Commands
+
+None specifically required for FTD files - the fastn server will catch syntax errors.
+
+## FTD Common Mistakes Cheat Sheet
+
+### ❌ Most Common Errors and Solutions
+
+**1. Mismatched Section Ends**
+```
+Error: "No section found to end: component-name"
+```
+**Cause**: Unmatched `-- end:` statements in code blocks or missing escape
+**Fix**: Escape end statements in code blocks: `\-- end: component-name`
+
+**2. Wrong Type References**
+```
+Error: "fastn.type.heading-large not found"
+```
+**Cause**: Using `$fastn.type.*` instead of `$inherited.types.*`
+**Fix**: Use `$inherited.types.heading-large` not `$fastn.type.heading-large`
+
+**3. Component Attribute Not Found**
+```
+Error: "Header type 'preload' not found for component 'ftd.audio'"
+```
+**Cause**: Using unsupported attributes for components
+**Fix**: Check existing component docs, only use supported attributes
+
+**4. Unescaped Code in Examples**
+```
+Error: Section parsing errors in code blocks
+```
+**Cause**: FTD code in `-- ds.code:` blocks needs escaping
+**Fix**: Escape FTD syntax: `\-- ftd.text:` not `-- ftd.text:`
+
+**5. Custom Components Don't Exist**
+```
+Error: "terminal-output not found"
+```  
+**Cause**: Using imaginary components like `ds.terminal-output`
+**Fix**: Stick to documented `ds.*` components or build custom ones
+
+### ✅ Quick Fixes
+
+- **Always test pages**: `curl http://127.0.0.1:8004/path/` before committing
+- **Start simple**: Create minimal working version, then add complexity
+- **Check nesting**: Count `-- ftd.column:` vs `-- end: ftd.column` statements
+- **Use existing patterns**: Copy structure from working files like `/ftd/text.ftd`
+- **Escape examples**: Use `\--` in all code blocks showing FTD syntax
\ No newline at end of file
diff --git a/fastn.com/FASTN.ftd b/fastn.com/FASTN.ftd
index 2cbf6af99..58fe6b8a8 100644
--- a/fastn.com/FASTN.ftd
+++ b/fastn.com/FASTN.ftd
@@ -615,6 +615,9 @@ skip: true
 
 # Docs: /ftd/data-modelling/
 
+-- FTD 0.4 Language Specification: /spec/
+  document: spec/index.ftd
+
 ## `fastn` Made Easy: /book/
 
 - Introduction: 
diff --git a/fastn.com/spec/components/index.ftd b/fastn.com/spec/components/index.ftd
new file mode 100644
index 000000000..d37229a33
--- /dev/null
+++ b/fastn.com/spec/components/index.ftd
@@ -0,0 +1,18 @@
+-- ds.page: Components
+
+Component definition, invocation, and usage in FTD
+
+-- ds.h1: Component Definition
+
+Components are reusable building blocks defined with the `component` keyword.
+
+-- ds.h1: Component Usage
+
+Components are invoked like sections with optional captions and properties.
+
+-- ds.code: Component Examples
+lang: ftd
+
+\-- ftd.text: Hello World
+\-- custom-component: With Caption
+property: value
\ No newline at end of file
diff --git a/fastn.com/spec/functions/index.ftd b/fastn.com/spec/functions/index.ftd
new file mode 100644
index 000000000..749954895
--- /dev/null
+++ b/fastn.com/spec/functions/index.ftd
@@ -0,0 +1,54 @@
+-- ds.page: Functions
+
+Function definitions, calls, expressions, and built-in functions in FTD
+
+-- ds.h1: Function Definition
+
+Functions encapsulate reusable logic and can accept parameters.
+
+-- ds.code: Basic Function
+lang: ftd
+
+\-- string greeting(name):
+string name:
+
+Hello $name! Welcome to fastn.
+
+-- ds.h1: Function Calls
+
+Functions are called using standard invocation syntax.
+
+-- ds.code: Function Usage
+lang: ftd
+
+\-- ftd.text: $greeting("Alice")
+\-- ftd.text: $greeting("Bob")
+
+-- ds.h1: Function Parameters
+
+Functions can accept multiple typed parameters.
+
+-- ds.code: Multi-Parameter Function
+lang: ftd
+
+\-- string format-price(amount, currency):
+decimal amount:
+string currency:
+
+$currency $amount
+
+\-- ftd.text: $format-price(29.99, "USD")
+
+-- ds.h1: Built-in Functions
+
+FTD provides several built-in functions for common operations.
+
+-- ds.code: Built-in Function Examples
+lang: ftd
+
+\-- string upper-name: $upper($name)
+\-- string formatted: $format("{}: {}", "Name", $name)
+\-- integer length: $len($name)
+
+\-- ftd.text: $upper-name
+\-- ftd.text: Length: $length
\ No newline at end of file
diff --git a/fastn.com/spec/index.ftd b/fastn.com/spec/index.ftd
new file mode 100644
index 000000000..7253ae912
--- /dev/null
+++ b/fastn.com/spec/index.ftd
@@ -0,0 +1,82 @@
+-- ftd.column:
+spacing.fixed.px: 24
+width: fill-container
+
+-- ftd.text: FTD 0.4 Language Specification
+role: $inherited.types.heading-large
+color: $inherited.colors.text-strong
+
+-- ftd.text: Complete specification for the fastn Template Definition (FTD) language version 0.4
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- ftd.text: 
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+This comprehensive language specification covers all aspects of FTD 0.4, providing
+developers with the definitive reference for fastn template development.
+
+-- ftd.column:
+spacing.fixed.px: 32
+width: fill-container
+margin-top.px: 32
+
+-- spec-section: Syntax
+url: /spec/syntax/
+description: Core syntax rules, sections, headers, comments, and complete BNF grammar
+
+-- spec-section: Types  
+url: /spec/types/
+description: Primitive types, built-in types, records, or-types, and type inference rules
+
+-- spec-section: Components
+url: /spec/components/
+description: Component definition, invocation, arguments, children, and inheritance
+
+-- spec-section: Variables
+url: /spec/variables/
+description: Variable declaration, scoping rules, mutability, and references
+
+-- spec-section: Functions
+url: /spec/functions/
+description: Function definitions, calls, expressions, and built-in functions
+
+-- spec-section: Modules
+url: /spec/modules/
+description: Import semantics, export rules, aliases, and package system
+
+-- end: ftd.column
+
+-- end: ftd.column
+
+-- component spec-section:
+caption title:
+string url:
+string description:
+
+-- ftd.column:
+spacing.fixed.px: 8
+width: fill-container
+padding.px: 24
+border-width.px: 1
+border-color: $inherited.colors.border
+border-radius.px: 8
+background.solid: $inherited.colors.background.step-1
+
+-- ftd.text: $spec-section.title
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+
+-- ftd.text: $spec-section.description
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- ftd.text: → Explore
+role: $inherited.types.copy-regular
+color: $inherited.colors.accent.primary
+margin-top.px: 8
+
+-- end: ftd.column
+
+-- end: spec-section
\ No newline at end of file
diff --git a/fastn.com/spec/modules/index.ftd b/fastn.com/spec/modules/index.ftd
new file mode 100644
index 000000000..ed9fde0f6
--- /dev/null
+++ b/fastn.com/spec/modules/index.ftd
@@ -0,0 +1,35 @@
+-- ds.page: Modules
+
+Import semantics, export rules, and package system in FTD
+
+-- ds.h1: Import Statements
+
+Modules are imported at the top of files.
+
+-- ds.code: Basic Imports
+lang: ftd
+
+\-- import: some-package
+\-- import: ui-components
+\-- import: design-system as ds
+
+-- ds.h1: Import Aliases
+
+Modules can be imported with aliases.
+
+-- ds.code: Aliased Imports
+lang: ftd
+
+\-- import: long-package-name as short
+
+\-- short.component: Using alias
+
+-- ds.h1: Exports
+
+Modules expose components and functions through exports.
+
+-- ds.code: Export Examples
+lang: ftd
+
+\-- export: my-component
+\-- export: my-function
\ No newline at end of file
diff --git a/fastn.com/spec/syntax/comments.ftd b/fastn.com/spec/syntax/comments.ftd
new file mode 100644
index 000000000..bcd472c17
--- /dev/null
+++ b/fastn.com/spec/syntax/comments.ftd
@@ -0,0 +1,26 @@
+-- ds.page: Comment Syntax
+
+Single-line and multi-line comment syntax in FTD
+
+-- ds.h1: Single-Line Comments
+
+Single-line comments begin with `;;` and continue to the end of the line.
+
+-- ds.code: Comment Examples
+lang: ftd
+
+;; This is a comment
+\-- ftd.text: Hello World ;; Inline comment
+color: red ;; Another comment
+
+-- ds.h1: Comment Placement
+
+Comments can be placed in various locations within FTD documents.
+
+-- ds.code: Comment Placement
+lang: ftd
+
+;; File-level comment
+\-- ftd.text: Content
+;; Before properties  
+color: blue ;; After values
\ No newline at end of file
diff --git a/fastn.com/spec/syntax/headers.ftd b/fastn.com/spec/syntax/headers.ftd
new file mode 100644
index 000000000..71bd9016f
--- /dev/null
+++ b/fastn.com/spec/syntax/headers.ftd
@@ -0,0 +1,205 @@
+-- ftd.column:
+spacing.fixed.px: 24
+width: fill-container
+
+-- ftd.text: Header Syntax
+role: $inherited.types.heading-large
+color: $inherited.colors.text-strong
+
+-- ftd.text: Header syntax, property assignment, and value types in FTD
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- ftd.column:
+spacing.fixed.px: 32
+width: fill-container
+margin-top.px: 24
+
+-- ftd.text: Basic Header Syntax
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+
+-- ftd.text:
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+Headers are property assignments within sections. They consist of a property 
+name followed by a colon and the value. Headers must be indented relative to 
+their parent section.
+
+-- ds.code: Basic Header Examples
+lang: ftd
+
+\-- ftd.text: Hello World
+role: $inherited.types.heading-large
+color: red
+width.fixed.px: 200
+margin.px: 16
+
+-- ftd.text: Property Names
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+margin-top.px: 32
+
+-- ftd.text:
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+Property names follow these rules:
+- Must start with a letter or underscore
+- Can contain letters, numbers, hyphens, dots, and underscores
+- Case-sensitive
+- Can be nested using dot notation
+
+-- ds.code: Property Name Examples
+lang: ftd
+
+\-- component:
+width: 100
+height: 200
+margin.top.px: 16
+margin.bottom.px: 8
+background.solid: red
+border.width.px: 1
+border.color: #333333
+
+-- ftd.text: Value Types
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+margin-top.px: 32
+
+-- ftd.text:
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+FTD supports various value types in headers:
+
+-- ftd.text: String Values
+role: $inherited.types.heading-small
+color: $inherited.colors.text-strong
+margin-top.px: 24
+
+-- ds.code: String Value Examples
+lang: ftd
+
+\-- ftd.text: Simple string value
+\-- ftd.text: String with spaces
+src: /path/to/file.jpg
+url: https://example.com
+
+-- ftd.text: Integer Values
+role: $inherited.types.heading-small
+color: $inherited.colors.text-strong
+margin-top.px: 24
+
+-- ds.code: Integer Value Examples  
+lang: ftd
+
+\-- component:
+width: 100
+height: 200
+count: 42
+negative: -10
+
+-- ftd.text: Decimal Values
+role: $inherited.types.heading-small
+color: $inherited.colors.text-strong
+margin-top.px: 24
+
+-- ds.code: Decimal Value Examples
+lang: ftd
+
+\-- component:
+opacity: 0.5
+ratio: 1.618
+temperature: -2.5
+percentage: 100.0
+
+-- ftd.text: Boolean Values
+role: $inherited.types.heading-small
+color: $inherited.colors.text-strong
+margin-top.px: 24
+
+-- ds.code: Boolean Value Examples
+lang: ftd
+
+\-- component:
+visible: true
+enabled: false
+required: true
+optional: false
+
+-- ftd.text: Variable References
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+margin-top.px: 32
+
+-- ftd.text:
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+Header values can reference variables using the `$` prefix:
+
+-- ds.code: Variable Reference Examples
+lang: ftd
+
+\-- string name: John Doe
+\-- integer age: 25
+\-- boolean is-student: true
+
+\-- ftd.text: $name
+color: $theme.primary-color
+width: $container.width
+visible: $is-student
+
+-- ftd.text: Expression Values
+role: $inherited.types.heading-medium  
+color: $inherited.colors.text-strong
+margin-top.px: 32
+
+-- ftd.text:
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+Headers can contain expressions for dynamic values:
+
+-- ds.code: Expression Examples
+lang: ftd
+
+\-- ftd.text: Hello $name
+width: $MOUSE-IN ? 200 : 100
+color: $dark-mode ? white : black
+visible: $user.age >= 18
+
+-- ftd.text: Multi-line Values
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+margin-top.px: 32
+
+-- ftd.text:
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+For long values, FTD supports multi-line syntax using indentation:
+
+-- ds.code: Multi-line Value Examples
+lang: ftd
+
+\-- ftd.text:
+
+This is a multi-line text value
+that spans several lines.
+Each line is indented.
+
+\-- component:
+css: 
+  background: linear-gradient(
+    45deg, 
+    red, 
+    blue
+  );
+  border-radius: 8px;
+
+-- end: ftd.column
+
+-- end: ftd.column
\ No newline at end of file
diff --git a/fastn.com/spec/syntax/index.ftd b/fastn.com/spec/syntax/index.ftd
new file mode 100644
index 000000000..7f35cffcb
--- /dev/null
+++ b/fastn.com/spec/syntax/index.ftd
@@ -0,0 +1,70 @@
+-- ftd.column:
+spacing.fixed.px: 24
+width: fill-container
+
+-- ftd.text: FTD Syntax Specification
+role: $inherited.types.heading-large
+color: $inherited.colors.text-strong
+
+-- ftd.text: Core syntax rules and grammar for the fastn Template Definition (FTD) language
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- ftd.text: 
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+margin-top.px: 16
+
+This section defines the fundamental syntax elements of FTD 0.4, including
+sections, headers, comments, and the complete BNF grammar specification.
+
+-- ftd.column:
+spacing.fixed.px: 24
+width: fill-container
+margin-top.px: 32
+
+-- syntax-section: Sections
+url: /language-spec/syntax/sections/
+description: Section definition syntax, nesting rules, and component invocations
+
+-- syntax-section: Headers  
+url: /language-spec/syntax/headers/
+description: Header syntax, property assignment, and value types
+
+-- syntax-section: Comments
+url: /language-spec/syntax/comments/
+description: Single-line and multi-line comment syntax
+
+-- syntax-section: Complete Grammar
+url: /language-spec/syntax/grammar/
+description: Complete BNF grammar specification for FTD 0.4
+
+-- end: ftd.column
+
+-- end: ftd.column
+
+-- component syntax-section:
+caption title:
+string url:
+string description:
+
+-- ftd.column:
+spacing.fixed.px: 8
+width: fill-container
+padding.px: 20
+border-width.px: 1
+border-color: $inherited.colors.border
+border-radius.px: 6
+background.solid: $inherited.colors.background.step-1
+
+-- ftd.text: $syntax-section.title
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+
+-- ftd.text: $syntax-section.description
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- end: ftd.column
+
+-- end: syntax-section
\ No newline at end of file
diff --git a/fastn.com/spec/syntax/sections.ftd b/fastn.com/spec/syntax/sections.ftd
new file mode 100644
index 000000000..306db6958
--- /dev/null
+++ b/fastn.com/spec/syntax/sections.ftd
@@ -0,0 +1,17 @@
+-- ds.page: Section Syntax
+
+Section definition syntax, nesting rules, and component invocations in FTD
+
+-- ds.h1: Basic Section Syntax
+
+A section in FTD starts with `--` followed by the section name.
+
+-- ds.code: Basic Sections
+lang: ftd
+
+\-- ftd.text: Hello World
+\-- component-name: Component with caption
+
+-- ds.h1: Section Nesting
+
+Sections can contain nested child sections using indentation.
\ No newline at end of file
diff --git a/fastn.com/spec/types/built-in-types.ftd b/fastn.com/spec/types/built-in-types.ftd
new file mode 100644
index 000000000..108d1d9ae
--- /dev/null
+++ b/fastn.com/spec/types/built-in-types.ftd
@@ -0,0 +1,60 @@
+-- ds.page: Built-in Types
+
+FTD's built-in types: ftd.color, ftd.length, ftd.spacing, and more
+
+-- ds.h1: ftd.color
+
+The `ftd.color` type represents color values in various formats.
+
+-- ds.code: Color Examples
+lang: ftd
+
+\-- ftd.color primary: red
+\-- ftd.color secondary: #3366cc
+\-- ftd.color transparent: rgba(255, 0, 0, 0.5)
+\-- ftd.color theme: $inherited.colors.text
+
+\-- ftd.text: Colored Text
+color: $primary
+
+-- ds.h1: ftd.length
+
+The `ftd.length` type represents sizing values with units.
+
+-- ds.code: Length Examples  
+lang: ftd
+
+\-- ftd.length width: 100px
+\-- ftd.length height: 50%
+\-- ftd.length margin: 2em
+\-- ftd.length padding: 16
+
+\-- ftd.container:
+width: $width
+height: $height
+
+-- ds.h1: ftd.spacing
+
+The `ftd.spacing` type represents spacing values for layouts.
+
+-- ds.code: Spacing Examples
+lang: ftd
+
+\-- ftd.spacing gap: 16px
+\-- ftd.spacing large: 32px
+
+\-- ftd.column:
+spacing: $gap
+
+-- ds.h1: ftd.resizing
+
+The `ftd.resizing` type controls how elements resize.
+
+-- ds.code: Resizing Examples
+lang: ftd
+
+\-- ftd.resizing mode: fill-container
+\-- ftd.resizing fixed: hug-content
+
+\-- ftd.text: Dynamic text
+width: $mode
\ No newline at end of file
diff --git a/fastn.com/spec/types/index.ftd b/fastn.com/spec/types/index.ftd
new file mode 100644
index 000000000..3c08d7f8e
--- /dev/null
+++ b/fastn.com/spec/types/index.ftd
@@ -0,0 +1,57 @@
+-- ds.page: Type System Specification
+
+Complete specification of FTD's type system including primitive types, derived types, records, and or-types
+
+-- ds.h1: Overview
+
+FTD has a rich type system that supports both static typing and dynamic features. The type system includes primitive types, derived types, user-defined records, and discriminated unions (or-types).
+
+-- ds.h1: Type Categories
+
+-- ds.h2: Primitive Types
+
+FTD's built-in primitive types:
+
+- `string` - Text values
+- `integer` - Whole numbers
+- `decimal` - Floating point numbers  
+- `boolean` - True/false values
+
+-- ds.h2: Derived Types
+
+Built-in structured types:
+
+- `ftd.color` - Color values (hex, rgb, named)
+- `ftd.length` - Length units (px, em, rem, %)
+- `ftd.resizing` - Sizing behavior
+- `ftd.spacing` - Spacing values
+
+-- ds.h2: User-Defined Types
+
+- `record` - Structured data with named fields
+- `or-type` - Discriminated unions with variants
+
+-- ds.h1: Type Declaration Examples
+
+-- ds.code: Basic Type Usage
+lang: ftd
+
+\-- string name: John Doe
+\-- integer age: 25
+\-- boolean active: true
+\-- ftd.color theme-color: red
+
+\-- record person:
+string name:
+integer age:
+boolean active:
+
+\-- or-type status:
+
+\-- status.loading:
+
+\-- status.success:
+string message:
+
+\-- status.error:
+string error:
\ No newline at end of file
diff --git a/fastn.com/spec/types/or-types.ftd b/fastn.com/spec/types/or-types.ftd
new file mode 100644
index 000000000..046168d0d
--- /dev/null
+++ b/fastn.com/spec/types/or-types.ftd
@@ -0,0 +1,66 @@
+-- ds.page: Or-Types
+
+Or-type (discriminated union) definitions and usage in FTD
+
+-- ds.h1: Or-Type Definition
+
+Or-types define a type that can be one of several variants.
+
+-- ds.code: Basic Or-Type
+lang: ftd
+
+\-- or-type status:
+
+\-- status.loading:
+
+\-- status.success:
+string message:
+
+\-- status.error:
+string error:
+
+-- ds.h1: Or-Type Usage
+
+Or-types are instantiated by specifying the variant.
+
+-- ds.code: Or-Type Instance
+lang: ftd
+
+\-- status current-status: $status.success
+message: Operation completed successfully
+
+\-- status error-status: $status.error
+error: Network connection failed
+
+-- ds.h1: Pattern Matching
+
+Or-types are commonly used with conditional expressions.
+
+-- ds.code: Conditional Usage
+lang: ftd
+
+\-- ftd.text: Status
+color: $current-status is status.error ? red : green
+
+\-- ftd.text: $current-status.message
+visible: $current-status is status.success
+
+-- ds.h1: Complex Or-Types
+
+Or-types can contain multiple fields and nested data.
+
+-- ds.code: Complex Or-Type
+lang: ftd
+
+\-- or-type api-response:
+
+\-- api-response.loading:
+string progress:
+
+\-- api-response.success:
+string data:
+integer count:
+
+\-- api-response.error:
+string message:
+integer code:
\ No newline at end of file
diff --git a/fastn.com/spec/types/primitive-types.ftd b/fastn.com/spec/types/primitive-types.ftd
new file mode 100644
index 000000000..0d422ba2b
--- /dev/null
+++ b/fastn.com/spec/types/primitive-types.ftd
@@ -0,0 +1,65 @@
+-- ds.page: Primitive Types
+
+FTD's built-in primitive types: string, integer, decimal, and boolean
+
+-- ds.h1: String Type
+
+The `string` type represents text values.
+
+-- ds.code: String Examples
+lang: ftd
+
+\-- string name: John Doe
+\-- string empty: 
+\-- string multiline:
+
+This is a multi-line
+string value with
+multiple lines.
+
+\-- ftd.text: $name
+\-- ftd.text: Hello $name
+
+-- ds.h1: Integer Type
+
+The `integer` type represents whole numbers (positive, negative, or zero).
+
+-- ds.code: Integer Examples
+lang: ftd
+
+\-- integer count: 42
+\-- integer negative: -10
+\-- integer zero: 0
+
+\-- ftd.text: Count: $count
+\-- ftd.text: Total: $count + 5
+
+-- ds.h1: Decimal Type
+
+The `decimal` type represents floating-point numbers.
+
+-- ds.code: Decimal Examples
+lang: ftd
+
+\-- decimal price: 19.99
+\-- decimal ratio: 1.618
+\-- decimal percentage: 0.85
+
+\-- ftd.text: Price: $price
+opacity: $percentage
+
+-- ds.h1: Boolean Type
+
+The `boolean` type represents true/false values.
+
+-- ds.code: Boolean Examples
+lang: ftd
+
+\-- boolean enabled: true
+\-- boolean visible: false
+\-- boolean is-admin: true
+
+\-- ftd.text: Status
+visible: $enabled
+\-- ftd.text: Admin Panel
+visible: $is-admin
\ No newline at end of file
diff --git a/fastn.com/spec/types/records.ftd b/fastn.com/spec/types/records.ftd
new file mode 100644
index 000000000..0dcf30782
--- /dev/null
+++ b/fastn.com/spec/types/records.ftd
@@ -0,0 +1,69 @@
+-- ds.page: Record Types
+
+Record type definitions and usage in FTD
+
+-- ds.h1: Record Definition
+
+Records define structured data types with named fields.
+
+-- ds.code: Basic Record
+lang: ftd
+
+\-- record person:
+string name:
+integer age:
+optional string email:
+
+-- ds.h1: Record Usage
+
+Once defined, records can be instantiated and used.
+
+-- ds.code: Record Instance
+lang: ftd
+
+\-- person user:
+name: Alice Smith
+age: 30
+email: alice@example.com
+
+\-- ftd.text: $user.name
+\-- ftd.text: Age: $user.age
+
+-- ds.h1: Optional Fields
+
+Record fields can be marked as optional.
+
+-- ds.code: Optional Fields
+lang: ftd
+
+\-- record profile:
+string username:
+optional string bio:
+optional string avatar-url:
+
+\-- profile my-profile:
+username: johndoe
+bio: Software developer
+
+-- ds.h1: Nested Records
+
+Records can contain other record types.
+
+-- ds.code: Nested Record Example
+lang: ftd
+
+\-- record address:
+string street:
+string city:
+string country:
+
+\-- record user:
+string name:
+address location:
+
+\-- user current-user:
+name: John Doe
+location:
+  street: 123 Main St
+  city: New York  
+  country: USA
\ No newline at end of file
diff --git a/fastn.com/spec/variables/index.ftd b/fastn.com/spec/variables/index.ftd
new file mode 100644
index 000000000..d1ab3702b
--- /dev/null
+++ b/fastn.com/spec/variables/index.ftd
@@ -0,0 +1,25 @@
+-- ds.page: Variables
+
+Variable declaration, scoping, and references in FTD
+
+-- ds.h1: Variable Declaration
+
+Variables store values that can be referenced throughout the document.
+
+-- ds.code: Basic Variables
+lang: ftd
+
+\-- string name: John Doe
+\-- integer age: 25
+\-- boolean active: true
+
+-- ds.h1: Variable References
+
+Variables are referenced using the `$` prefix.
+
+-- ds.code: Variable Usage
+lang: ftd
+
+\-- ftd.text: Hello $name
+\-- ftd.text: Age: $age
+visible: $active
\ No newline at end of file