### intent serve example output

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Example invocation of `intent serve` on a file, showing the startup output with the listening address, module name, and exposed endpoints.

```bash
$ intent serve examples/transfer.intent
intent serve: listening on http://127.0.0.1:3000
  module: TransferFunds
  POST /actions/Transfer
  GET  /
```

--------------------------------

### Create hello.intent with a minimal Task tracker

Source: https://krakenhavoc.github.io/IntentLang/getting-started/first-spec.html

Defines a module HelloWorld with a Task entity, a CompleteTask action with requires/ensures, and an invariant TasksHaveTitle. This is the starting point for the toolchain examples.

```intent
module HelloWorld

--- A minimal task tracker to demonstrate IntentLang basics.

entity Task {
  id: UUID
  title: String
  done: Bool
}

action CompleteTask {
  task: Task

  requires {
    task.done == false
  }

  ensures {
    task.done == true
  }
}

invariant TasksHaveTitle {
  forall t: Task => t.title != ""
}
```

--------------------------------

### Install Fish completions

Source: https://krakenhavoc.github.io/IntentLang/cli/completions.html

Writes the Fish completion script to the standard Fish completions directory.

```fish
intent completions fish > ~/.config/fish/completions/intent.fish
```

--------------------------------

### Install intent-lsp LSP server

Source: https://krakenhavoc.github.io/IntentLang/cli/editor.html

Install the intent-lsp binary from source or from crates.io. The binary is installed to the Cargo bin directory, typically ~/.cargo/bin/.

```bash
cargo install --path crates/intent-lsp

# Or, if published to crates.io
cargo install intent-lsp
```

--------------------------------

### Install intent-cli with cargo

Source: https://krakenhavoc.github.io/IntentLang/getting-started/installation.html

Installs the `intent` binary to `~/.cargo/bin/` using Cargo. Requires Rust to be installed.

```bash
cargo install intent-cli
```

--------------------------------

### Verify installation with intent --help

Source: https://krakenhavoc.github.io/IntentLang/getting-started/installation.html

Displays the available subcommands: `check`, `render`, `render-html`, `compile`, `verify`, `audit`, `coverage`.

```bash
intent --help
```

--------------------------------

### Run downloaded release binary

Source: https://krakenhavoc.github.io/IntentLang/getting-started/installation.html

Makes the downloaded binary executable and runs a check on an example file.

```bash
chmod +x intent-linux-x86_64
./intent-linux-x86_64 check examples/transfer.intent
```

--------------------------------

### GET / module info response

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Response from `GET /` showing module info: entities, actions, and invariants.

```json
{
  "name": "TransferFunds",
  "entities": [
    {
      "name": "Account",
      "fields": [
        { "name": "id", "type": "Named(\"UUID\")" },
        { "name": "balance", "type": "Decimal(2)" },
        { "name": "status", "type": "Union([\"Active\", \"Suspended\"]) }
      ]
    }
  ],
  "actions": [
    {
      "name": "Transfer",
      "params": [
        { "name": "from", "type": "Struct(\"Account\")" },
        { "name": "to", "type": "Struct(\"Account\")" },
        { "name": "amount", "type": "Decimal(2)" }
      ],
      "precondition_count": 4,
      "postcondition_count": 2
    }
  ],
  "invariants": ["BalanceNonNegative"]
}
```

--------------------------------

### Install Bash completions for current user

Source: https://krakenhavoc.github.io/IntentLang/cli/completions.html

Creates the user-local Bash completions directory and writes the completion script there. No sudo required.

```bash
mkdir -p ~/.local/share/bash-completion/completions
intent completions bash > ~/.local/share/bash-completion/completions/intent
```

--------------------------------

### Run IntentLang with Docker

Source: https://krakenhavoc.github.io/IntentLang/getting-started/installation.html

Builds a Docker image and runs the `check` subcommand on a mounted example file.

```bash
docker build -t intent .
docker run -v $(pwd)/examples:/work intent check /work/transfer.intent
```

--------------------------------

### Install Bash completions system-wide

Source: https://krakenhavoc.github.io/IntentLang/cli/completions.html

Writes the Bash completion script to the system-wide completions directory and sources it immediately. Requires sudo privileges.

```bash
intent completions bash | sudo tee /usr/share/bash-completion/completions/intent > /dev/null
source /usr/share/bash-completion/completions/intent
```

--------------------------------

### intent init - examples with flags

Source: https://krakenhavoc.github.io/IntentLang/cli/init.html

Shows how to use the `--name` and `-o, --out` flags. The first command uses the directory name as the module name, the second specifies a module name, and the third specifies both name and output path.

```bash
# Use directory name as module name
intent init

# Specify a module name
intent init --name Payments

# Specify both name and output path
intent init --name Payments -o specs/payments.intent
```

--------------------------------

### Install PowerShell completions

Source: https://krakenhavoc.github.io/IntentLang/cli/completions.html

Appends the PowerShell completion script to the user's PowerShell profile.

```powershell
intent completions powershell >> $PROFILE
```

--------------------------------

### Build VSCode extension

Source: https://krakenhavoc.github.io/IntentLang/cli/editor.html

Build the IntentLang VSCode extension from the editors/vscode directory. After compiling, install the extension via the Command Palette: 'Developer: Install Extension from Location...' and select the editors/vscode/ directory.

```bash
cd editors/vscode
npm install
npm run compile
```

--------------------------------

### Pipe compile output to file or jq

Source: https://krakenhavoc.github.io/IntentLang/cli/compile.html

Examples of piping the JSON output to a file or to jq for querying entities.

```bash
intent compile examples/transfer.intent > transfer.ir.json
intent compile examples/transfer.intent | jq '.entities'
```

--------------------------------

### GET /

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Returns the module's entities, actions, and invariants.

```APIDOC
## GET /

### Description
Returns the module's entities, actions, and invariants.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **name** (string) - Module name
- **entities** (array) - List of entity definitions
- **actions** (array) - List of action definitions
- **invariants** (array) - List of invariant names

#### Response Example
{
  "name": "TransferFunds",
  "entities": [
    {
      "name": "Account",
      "fields": [
        { "name": "id", "type": "Named(\"UUID\")" },
        { "name": "balance", "type": "Decimal(2)" },
        { "name": "status", "type": "Union([\"Active\", \"Suspended\"])" }
      ]
    }
  ],
  "actions": [
    {
      "name": "Transfer",
      "params": [
        { "name": "from", "type": "Struct(\"Account\")" },
        { "name": "to", "type": "Struct(\"Account\")" },
        { "name": "amount", "type": "Decimal(2)" }
      ],
      "precondition_count": 4,
      "postcondition_count": 2
    }
  ],
  "invariants": ["BalanceNonNegative"]
}
```

--------------------------------

### Install Zsh completions

Source: https://krakenhavoc.github.io/IntentLang/cli/completions.html

Writes the Zsh completion script to `~/.zfunc/_intent`. Ensure `~/.zfunc` is in your `fpath` (add `fpath=(~/.zfunc $fpath)` to `~/.zshrc` before `compinit`).

```zsh
intent completions zsh > ~/.zfunc/_intent
```

--------------------------------

### intent serve command

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Starts a stateless HTTP server that exposes the spec's actions as REST endpoints. The runtime enforces preconditions, computes postconditions, and validates invariants on every request.

```bash
intent serve <file>
```

--------------------------------

### intent check success output

Source: https://krakenhavoc.github.io/IntentLang/cli/check.html

Example of running `intent check` on a file, producing a success message with the number of top-level items and no issues.

```text
$ intent check examples/transfer.intent
OK: TransferFunds — 7 top-level item(s), no issues found
```

--------------------------------

### Check and verify with JSON output

Source: https://krakenhavoc.github.io/IntentLang/cli/agent-tools.html

Use these commands to get structured, machine-readable output for agent integration. Each command supports the --output json flag for structured output.

```CLI
intent --output json check examples/transfer.intent
```

```CLI
intent --output json verify examples/transfer.intent
```

--------------------------------

### Render HTML documentation

Source: https://krakenhavoc.github.io/IntentLang/cli/render.html

Produces a self-contained HTML document with color-coded sections and no external CSS or JavaScript dependencies. The second command shows a concrete example that writes to transfer.html and opens it in the default browser.

```bash
intent render-html <file> > output.html
```

```bash
intent render-html examples/transfer.intent > transfer.html
open transfer.html
```

--------------------------------

### intent check error: undefined_type

Source: https://krakenhavoc.github.io/IntentLang/cli/check.html

Example error output for an undefined type, showing source span, label, and help message.

```text
intent::check::undefined_type

  × undefined type `Customer`
   ╭─[5:13]
 4 │       id: UUID
 5 │ ╭─▶   customer: Customer
 6 │ ├─▶   items: List<LineItem>
   · ╰──── used here
 7 │     }
   ╰────
  help: define an entity named `Customer`, or use a built-in type
```

--------------------------------

### Entity and action with validation and check command

Source: https://krakenhavoc.github.io/IntentLang/reference/modules.html

Shows a complete example with `Types.intent` defining an `Account` entity and `Banking.intent` using it in a `Transfer` action. The `requires` block validates conditions and the `ensures` block specifies postconditions. The command `intent check Banking.intent` produces the output `OK: Banking — 1 top-level item(s), no issues found`.

```intent
module Types

entity Account {
  id: UUID
  balance: Decimal(precision: 2)
  status: Active | Frozen | Closed
}
```

```intent
module Banking

use Types

action Transfer {
  from: Account
  to: Account
  amount: Decimal(precision: 2)

  requires {
    from.status == Active
    to.status == Active
    amount > 0
    from.balance >= amount
  }

  ensures {
    from.balance == old(from.balance) - amount
    to.balance == old(to.balance) + amount
  }
}
```

```shell
$ intent check Banking.intent
OK: Banking — 1 top-level item(s), no issues found
```

--------------------------------

### Generated payments.intent template

Source: https://krakenhavoc.github.io/IntentLang/cli/init.html

The starter template created by `intent init --name Payments`. It includes an example entity, action, and invariant. The module name's first letter is automatically capitalized.

```intent
module Payments

--- TODO: Describe what this module specifies.

entity Example {
  id: UUID
  name: String
  status: Active | Inactive
}

action CreateExample {
  name: String

  requires {
    name != ""
  }

  ensures {
    exists e: Example => e.name == name
  }
}

invariant UniqueNames {
  forall a: Example => forall b: Example =>
    a.id != b.id => a.name != b.name
}
```

--------------------------------

### Module declaration

Source: https://krakenhavoc.github.io/IntentLang/reference/modules.html

Every .intent file begins with a module declaration. The module name must start with an uppercase letter and use PascalCase. It serves as a namespace for all definitions in the file.

```intent
module TransferFunds
```

--------------------------------

### curl example for /actions/Transfer

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Sends a POST request to the Transfer endpoint with a JSON body containing params and state. The state includes two Account objects with initial balances.

```bash

__
curl -X POST http://127.0.0.1:3000/actions/Transfer \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "from": {"id": "1", "balance": 1000.0, "status": "Active"},
      "to": {"id": "2", "balance": 500.0, "status": "Active"},
      "amount": 200.0
    },
    "state": {
      "Account": [
        {"id": "1", "balance": 1000.0, "status": "Active"},
        {"id": "2", "balance": 500.0, "status": "Active"}
      ]
    }
  }'

```

--------------------------------

### IntentLang contract example: ensures with old()

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Enforces a postcondition that the from.balance field must equal its pre-action value minus the amount. The runtime evaluates old(from.balance) against the pre-action parameter values.

```intentlang

ensures {
  from.balance == old(from.balance) - amount
}

```

--------------------------------

### Using old() in ensures block

Source: https://krakenhavoc.github.io/IntentLang/reference/expressions.html

Example of using old() in an ensures block. Compares pre-action balance to compute the effect; only valid in ensures and temporal invariants.

```intentlang
ensures {
  from.balance == old(from.balance) - amount
}
```

--------------------------------

### Quantifier syntax: forall and exists

Source: https://krakenhavoc.github.io/IntentLang/reference/expressions.html

Use to express universal and existential quantifiers in IntentLang. Binds a variable to a type (must be a defined entity or action) and applies a predicate. The existential example shows combining conditions with '&&'.

```intentlang
// Universal quantifier
forall a: Account => a.balance >= 0

// Existential quantifier
exists s: Session => s.user.email == email && s.revoked == false
```

--------------------------------

### intent init - basic usage

Source: https://krakenhavoc.github.io/IntentLang/cli/init.html

Creates a new `.intent` file with a starter template. The module name defaults to the current directory name, or `MyModule` if no name is provided.

```bash
intent init
```

--------------------------------

### Action FreezeAccount with inline documentation

Source: https://krakenhavoc.github.io/IntentLang/reference/actions.html

Defines a FreezeAccount action with inline documentation using ---. Includes parameters, preconditions, and postconditions.

```intentlang
action FreezeAccount {
  --- Freeze an account, preventing all transfers.
  account: Account
  reason: String

  requires {
    account.status == Active
  }

  ensures {
    account.status == Frozen
  }
}
```

--------------------------------

### Build IntentLang from source

Source: https://krakenhavoc.github.io/IntentLang/getting-started/installation.html

Clones the repository and builds the `intent-cli` binary. Requires Rust 1.70+.

```bash
git clone https://github.com/krakenhavoc/IntentLang.git
cd IntentLang
cargo build --release -p intent-cli
# Binary at target/release/intent
```

--------------------------------

### Generate Markdown summary: intent render hello.intent

Source: https://krakenhavoc.github.io/IntentLang/getting-started/first-spec.html

Generates a Markdown summary of the spec.

```bash
intent render hello.intent
```

--------------------------------

### intent check error: old_in_requires

Source: https://krakenhavoc.github.io/IntentLang/cli/check.html

Example error output for using `old()` in a `requires` block, with help explaining that `old()` is only meaningful in `ensures` blocks.

```text
intent::check::old_in_requires

  × `old()` cannot be used in a `requires` block
    ╭─[13:21]
 12 │       requires {
 13 │ ╭─▶     from.balance == old(from.balance)
 14 │ ├─▶   }
    · ╰──── used here
    ╰────
  help: `old()` references pre-state values and is only meaningful in `ensures` blocks
```

--------------------------------

### Authentication module in IntentLang — examples/auth.intent

Source: https://krakenhavoc.github.io/IntentLang/examples/auth.html

Complete IntentLang module defining entities `User` and `Session`, actions `Login` and `Logout`, invariants `MaxFailedAttempts` and `SessionExpiry`, and an `edge_cases` block. The source is marked as `examples/auth.intent`. It demonstrates existential quantifiers, domain functions (`lookup`, `now`, `password_verified`), conditional postconditions (`when ... =>`), implication (`=>`) in invariants, and action properties for rate limiting (`rate_limited`) and sensitive fields (`sensitive_fields`).

```intent
module Authentication

--- User authentication system with password-based login,
--- session management, and brute-force protection.

entity User {
  id: UUID
  email: Email
  password_hash: String
  status: Active | Suspended | Deactivated
  failed_attempts: Int
  locked_until: DateTime?
  last_login: DateTime?
  created_at: DateTime
}

entity Session {
  id: UUID
  user: User
  token: String
  expires_at: DateTime
  created_at: DateTime
  revoked: Bool
}

action Login {
  --- Authenticate a user with email and password.
  email: Email
  password: String

  requires {
    exists u: User => u.email == email
    lookup(User, email).status == Active
    lookup(User, email).locked_until == null ||
      lookup(User, email).locked_until < now()
  }

  ensures {
    when password_verified(password, lookup(User, email).password_hash) =>
      exists s: Session =>
        s.user.email == email &&
        s.revoked == false &&
        s.expires_at > now()
      &&
      lookup(User, email).failed_attempts == 0
      &&
      lookup(User, email).last_login == now()

    when !password_verified(password, lookup(User, email).password_hash) =>
      lookup(User, email).failed_attempts ==
        old(lookup(User, email).failed_attempts) + 1
  }

  properties {
    audit_logged: true
    rate_limited: { max: 10, window_seconds: 60, key: email }
    sensitive_fields: [password]
  }
}

action Logout {
  --- End a user session.
  session: Session

  requires {
    session.revoked == false
    session.expires_at > now()
  }

  ensures {
    session.revoked == true
  }

  properties {
    idempotent: true
    audit_logged: true
  }
}

invariant MaxFailedAttempts {
  --- Lock accounts after 5 consecutive failed login attempts.
  forall u: User =>
    u.failed_attempts >= 5 => u.locked_until != null
}

invariant SessionExpiry {
  --- All active sessions must have a future expiration.
  forall s: Session =>
    s.revoked == false => s.expires_at > now()
}

edge_cases {
  when lookup(User, email).status == Suspended =>
    reject("Account suspended. Contact support.")
  when lookup(User, email).status == Deactivated =>
    reject("Account deactivated.")
  when lookup(User, email).failed_attempts >= 5 =>
    reject("Account locked due to too many failed attempts.")
}

```

--------------------------------

### intent CLI general syntax

Source: https://krakenhavoc.github.io/IntentLang/cli/usage.html

Shows the general command syntax for the intent CLI. Replace <command> with one of the subcommands listed in the table and <file> with the path to an IntentLang spec file.

```text
intent <command> <file>
```

--------------------------------

### Configure API key and generate specs

Source: https://krakenhavoc.github.io/IntentLang/cli/generate.html

Set the required AI_API_KEY environment variable and use the intent generate command to create specifications from natural language descriptions.

```bash
export AI_API_KEY=your-key-here

intent generate "I want a program that greets a user by name"

intent generate --out hello.intent "a greeting service"
```

--------------------------------

### Run structural verification: intent verify hello.intent

Source: https://krakenhavoc.github.io/IntentLang/getting-started/first-spec.html

Runs structural verification on the compiled IR, checking that the IR is well-formed, all references resolve, and coherence obligations are satisfied.

```bash
intent verify hello.intent
```

--------------------------------

### Compile an IntentLang spec

Source: https://krakenhavoc.github.io/IntentLang/cli/compile.html

Basic command syntax for compiling an IntentLang spec to the Agent IR.

```bash
intent compile <file>
```

--------------------------------

### intent CLI global flags

Source: https://krakenhavoc.github.io/IntentLang/cli/usage.html

Global flags for the intent CLI: --output json for JSON output, --help to show help, and --version to show version.

```text
intent --output json    JSON output (for agent consumption)
intent --help           Show help
intent --version        Show version
```

--------------------------------

### Generate self-contained HTML document: intent render-html hello.intent

Source: https://krakenhavoc.github.io/IntentLang/getting-started/first-spec.html

Generates a self-contained HTML document from the spec, redirecting output to hello.html.

```bash
intent render-html hello.intent > hello.html
```

--------------------------------

### Render Markdown documentation

Source: https://krakenhavoc.github.io/IntentLang/cli/render.html

Generates a Markdown document containing module name and documentation, entity field tables, action signatures with pre/postconditions, invariant descriptions, and edge case rules. Suitable for sharing with non-technical stakeholders or embedding in project documentation.

```bash
intent render <file>
```

--------------------------------

### Verify invariants with intent verify command

Source: https://krakenhavoc.github.io/IntentLang/reference/invariants.html

Runs the IR verifier on examples/transfer.intent to detect coherence obligations. The output lists obligations connecting each invariant to actions that might affect it.

```shell
intent verify examples/transfer.intent
```

--------------------------------

### Use interactive mode

Source: https://krakenhavoc.github.io/IntentLang/cli/generate.html

Forces the CLI to ask clarifying questions before and during the generation process.

```bash
intent generate --interactive "build me a shopping cart"
```

--------------------------------

### Importing a module with a state machine

Source: https://krakenhavoc.github.io/IntentLang/reference/state-machines.html

Two separate files: `Types` defines a state machine `OrderStatus`, and `Main` imports `Types` with `use` and uses `OrderStatus` as a field type in an entity. This demonstrates that state machines are included when importing a module.

```intentlang
module Types

state OrderStatus {
  Pending -> Confirmed -> Shipped
}
```

```intentlang
module Main

use Types

entity Order {
  id: UUID
  status: OrderStatus
}
```

--------------------------------

### Lower spec to Agent IR: intent compile hello.intent

Source: https://krakenhavoc.github.io/IntentLang/getting-started/first-spec.html

Compiles the spec to Agent IR, outputting a JSON representation of the typed intermediate representation that agents can consume.

```bash
intent compile hello.intent
```

--------------------------------

### Import all definitions from another module

Source: https://krakenhavoc.github.io/IntentLang/reference/modules.html

Imports all entities, actions, and invariants from another module. The resolver looks for `Types.intent` in the same directory as the importing file.

```intent
module Banking

use Types
```

--------------------------------

### State machine in a module with entity and action

Source: https://krakenhavoc.github.io/IntentLang/reference/state-machines.html

Defines a `TaskStatus` state machine with five states and valid transitions, then uses it as a field type in an `entity` and as a parameter type in an `action`. The action includes `requires` and `ensures` clauses that reference the state.

```intentlang
module TaskTracker

state TaskStatus {
  Open -> InProgress -> Done
  Open -> Cancelled
  InProgress -> Blocked -> InProgress
}

entity Task {
  id: UUID
  title: String
  status: TaskStatus
}

action StartTask {
  task: Task

  requires {
    task.status == Open
  }

  ensures {
    task.status == InProgress
  }
}
```

--------------------------------

### intent check command usage

Source: https://krakenhavoc.github.io/IntentLang/cli/check.html

Shows the basic syntax for the `intent check` command, which parses a `.intent` file and runs six semantic analysis passes.

```text
intent check <file>
```

--------------------------------

### Show coverage summary: intent coverage <file>

Source: https://krakenhavoc.github.io/IntentLang/cli/verify.html

Shows a coverage summary: counts of entities, actions, invariants, and edge cases, along with their verification status. Useful for quick assessment of spec completeness.

```bash
intent coverage <file>
```

--------------------------------

### Run incremental verification: intent verify --incremental <file>

Source: https://krakenhavoc.github.io/IntentLang/cli/verify.html

Caches per-item verification results in `.intent-cache/`. On subsequent runs, only re-verifies items whose content has changed. Reports how many items were re-verified vs cached.

```bash
intent verify --incremental <file>
```

--------------------------------

### Run semantic checker: intent check hello.intent

Source: https://krakenhavoc.github.io/IntentLang/getting-started/first-spec.html

Runs the semantic checker on hello.intent. The output shows OK: HelloWorld — 3 top-level item(s), no issues found. The checker validates types, field accesses, old() usage, quantifier bindings, and tautological comparisons.

```bash
intent check hello.intent
```

```text
OK: HelloWorld — 3 top-level item(s), no issues found
```

--------------------------------

### Built-in function calls and old() reference

Source: https://krakenhavoc.github.io/IntentLang/reference/expressions.html

Demonstrates built-in functions and special references: old() for pre-state, now() for current time, lookup() for entity lookup, and domain functions with named arguments. Note that old() is only valid in ensures blocks and temporal invariants.

```intentlang
old(from.balance)           // pre-state reference
now()                       // current time
lookup(User, email)         // entity lookup
password_verified(a, b)     // domain function
require_approval(level: "manager")  // with named args
```

--------------------------------

### Run structural verification: intent verify <file>

Source: https://krakenhavoc.github.io/IntentLang/cli/verify.html

Runs structural verification and coherence analysis on the compiled IR. Checks type references, field accesses, and valid contexts for `old()`. Output lists verification errors and coherence obligations.

```bash
intent verify <file>
```

--------------------------------

### POST /actions/<name>

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Executes the named action against caller-provided state. The server is stateless — you provide all entity state in each request and receive the new state in the response.

```APIDOC
## POST /actions/<name>

### Description
Executes the named action against caller-provided state. The server is stateless — you provide all entity state in each request and receive the new state in the response.

### Method
POST

### Endpoint
/actions/<name>

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the action to execute.

#### Request Body
- **params** (object) - Required - Action parameters by name. Primitive values or objects for entity-typed params.
- **state** (object) - Required - Entity instances by type name. Used for `forall`/`exists` evaluation and invariant checking.

### Request Example
{
  "params": {
    "from": { "id": "1", "balance": 1000.0, "status": "Active" },
    "to": { "id": "2", "balance": 500.0, "status": "Active" },
    "amount": 200.0
  },
  "state": {
    "Account": [
      { "id": "1", "balance": 1000.0, "status": "Active" },
      { "id": "2", "balance": 500.0, "status": "Active" }
    ]
  }
}

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **new_params** (object) - Reflects state after postconditions have been applied.
- **violations** (array) - List of violations (empty on success).

#### Response Example
{
  "ok": true,
  "new_params": {
    "from": { "id": "1", "balance": 800.0, "status": "Active" },
    "to": { "id": "2", "balance": 700.0, "status": "Active" },
    "amount": 200.0
  },
  "violations": []
}

#### Error Response (422)
- **ok** (boolean) - Indicates failure.
- **new_params** (object) - State after postconditions (may be partial).
- **violations** (array) - List of violation objects.

#### Error Response Example
{
  "ok": false,
  "new_params": {
    "from": { "id": "1", "balance": 50.0, "status": "Active" },
    "to": { "id": "2", "balance": 500.0, "status": "Active" },
    "amount": 200.0
  },
  "violations": [
    {
      "kind": "precondition_failed",
      "message": "precondition failed: from.balance >= amount"
    }
  ]
}
```

--------------------------------

### Multiple imports in a module

Source: https://krakenhavoc.github.io/IntentLang/reference/modules.html

Shows multiple `use` declarations in one module. `use Foo` looks for `Foo.intent` in the same directory as the importing file. Circular imports are detected and produce an error. Diamond dependencies are handled correctly -- each module is parsed only once. Imported definitions do not shadow local definitions; local definitions take precedence.

```intent
module App

use Types
use Auth.User
use Billing
```

--------------------------------

### Basic state machine syntax

Source: https://krakenhavoc.github.io/IntentLang/reference/state-machines.html

Defines a state machine named `StatusName` with two transition chains: `StateA -> StateB -> StateC` and `StateA -> StateD`. Each chain declares valid transitions between adjacent states, and multiple chains can share states to express branching.

```intentlang
state StatusName {
  StateA -> StateB -> StateC
  StateA -> StateD
}
```

--------------------------------

### Generate completions for a shell

Source: https://krakenhavoc.github.io/IntentLang/cli/completions.html

Run `intent completions <shell>` to generate a completion script for the specified shell. Supported shell values are `bash`, `zsh`, `fish`, `powershell`, and `elvish`. The script is written to stdout.

```bash
intent completions <shell>
```

--------------------------------

### Entity with documentation block

Source: https://krakenhavoc.github.io/IntentLang/reference/entities.html

Includes a documentation block inside the entity for TransferRecord.

```intentlang
entity TransferRecord {
  --- Records a completed or pending transfer for audit purposes.
  id: UUID
  amount: Decimal(precision: 2)
  status: Pending | Completed | Failed | Reversed
}
```

--------------------------------

### Edit existing intent files

Source: https://krakenhavoc.github.io/IntentLang/cli/generate.html

Modifies an existing .intent file based on a natural language description, with an optional flag to show a diff.

```bash
intent generate --edit cart.intent "add a discount code feature"
intent generate --edit cart.intent --diff "add rate limiting"  # show diff instead
```

--------------------------------

### Literal value syntax for data types

Source: https://krakenhavoc.github.io/IntentLang/reference/expressions.html

Shows the literal syntax for basic data types: integer, decimal, string, boolean, and null. Comments indicate expected types.

```intentlang
42              // integer
10000.00        // decimal
"hello"         // string
true / false    // boolean
null            // null (for optional comparisons)
```

--------------------------------

### Shopping Cart IntentLang Module

Source: https://krakenhavoc.github.io/IntentLang/examples/shopping-cart.html

Defines the ShoppingCart module with entities (Product, CartItem, Cart, Order), actions (AddItem, RemoveItem, UpdateQuantity, Checkout), invariants (StockNonNegative, CartItemsPositive), and edge cases. Demonstrates collection types, nested references, negated existentials, and quantifiers.

```intent
module ShoppingCart

--- A shopping cart system supporting item management,
--- quantity updates, and checkout with inventory validation.

entity Product {
  id: UUID
  name: String
  price: Decimal(precision: 2)
  stock: Int
  status: Available | Discontinued
}

entity CartItem {
  product: Product
  quantity: Int
}

entity Cart {
  id: UUID
  owner: UUID
  items: List<CartItem>
  created_at: DateTime
  checked_out: Bool
}

entity Order {
  id: UUID
  cart: Cart
  total: Decimal(precision: 2)
  status: Pending | Confirmed | Shipped | Delivered | Cancelled
  created_at: DateTime
}

action AddItem {
  --- Add a product to the cart, or increase quantity if already present.
  cart: Cart
  product: Product
  quantity: Int

  requires {
    cart.checked_out == false
    product.status == Available
    quantity > 0
    product.stock >= quantity
  }

  ensures {
    exists item: CartItem =>
      item.product == product &&
      item.quantity == quantity
  }

  properties {
    idempotent: false
  }
}

action RemoveItem {
  --- Remove a product from the cart entirely.
  cart: Cart
  product: Product

  requires {
    cart.checked_out == false
    exists item: CartItem =>
      item.product == product
  }

  ensures {
    !(exists item: CartItem =>
      item.product == product)
  }
}

action UpdateQuantity {
  --- Change the quantity of an item already in the cart.
  cart: Cart
  product: Product
  new_quantity: Int

  requires {
    cart.checked_out == false
    new_quantity > 0
    product.stock >= new_quantity
    exists item: CartItem =>
      item.product == product
  }

  ensures {
    exists item: CartItem =>
      item.product == product &&
      item.quantity == new_quantity
  }
}

action Checkout {
  --- Convert the cart into a confirmed order.
  cart: Cart

  requires {
    cart.checked_out == false
    forall item: CartItem =>
      item.product.stock >= item.quantity
  }

  ensures {
    cart.checked_out == true
    exists o: Order =>
      o.cart == cart &&
      o.status == Confirmed
  }

  properties {
    atomic: true
    audit_logged: true
  }
}

invariant StockNonNegative {
  --- Product stock can never go below zero.
  forall p: Product => p.stock >= 0
}

invariant CartItemsPositive {
  --- Every item in a cart must have a positive quantity.
  forall item: CartItem => item.quantity > 0
}

edge_cases {
  when product.status == Discontinued => reject("Product is no longer available")
  when product.stock < quantity => reject("Insufficient stock")
  when cart.checked_out == true => reject("Cart has already been checked out")
}
```

--------------------------------

### IntentLang spec: TransferFunds module with entity, action, and invariant

Source: https://krakenhavoc.github.io/IntentLang

A complete IntentLang specification for a fund transfer between two accounts. It defines an Account entity, a Transfer action with requires and ensures clauses, and a NoNegativeBalances invariant. Use this as a template for writing declarative specs with pre/postconditions and invariants.

```intentlang
module TransferFunds

--- A fund transfer between two accounts within the same currency.

entity Account {
  id: UUID
  balance: Decimal(precision: 2)
  currency: CurrencyCode
  status: Active | Frozen | Closed
}

action Transfer {
  from: Account
  to: Account
  amount: Decimal(precision: 2)

  requires {
    from.status == Active
    to.status == Active
    from.currency == to.currency
    amount > 0
    from.balance >= amount
  }

  ensures {
    from.balance == old(from.balance) - amount
    to.balance == old(to.balance) + amount
  }
}

invariant NoNegativeBalances {
  forall a: Account => a.balance >= 0
}
```

--------------------------------

### POST /actions success response

Source: https://krakenhavoc.github.io/IntentLang/cli/serve.html

Successful response from `POST /actions/<name>`: `new_params` reflects state after postconditions have been applied. Postconditions with the pattern `param.field == old(param.field) +/- expr` are extracted as state assignments.

```json
{
  "ok": true,
  "new_params": {
    "from": { "id": "1", "balance": 800.0, "status": "Active" },
    "to": { "id": "2", "balance": 700.0, "status": "Active" },
    "amount": 200.0
  },
  "violations": []
}
```

--------------------------------

### State machine with doc block

Source: https://krakenhavoc.github.io/IntentLang/reference/state-machines.html

Shows a state machine with a doc block comment that describes the purpose of the state machine. The doc block is placed before the `state` keyword.

```intentlang
--- Tracks the lifecycle of a customer order.
state OrderStatus {
  Pending -> Confirmed -> Shipped -> Delivered
  Pending -> Cancelled
}
```

--------------------------------

### Query spec items

Source: https://krakenhavoc.github.io/IntentLang/cli/agent-tools.html

Query specific items from a spec. Available targets include entities, actions, invariants, edge-cases, obligations, summary, and <Name>. Combine with --output json for structured output that agents can parse directly.

```CLI
intent query <file> <target>
```

--------------------------------

### Action Transfer with requires, ensures, and properties

Source: https://krakenhavoc.github.io/IntentLang/reference/actions.html

Defines a Transfer action with parameters, preconditions, postconditions, and metadata. The requires block must not use old(); ensures uses old() to reference pre-action values. Properties are metadata for downstream tooling and are not semantically validated.

```intentlang
action Transfer {
  from: Account
  to: Account
  amount: Decimal(precision: 2)

  requires {
    from.status == Active
    to.status == Active
    from.currency == to.currency
    amount > 0
    from.balance >= amount
  }

  ensures {
    from.balance == old(from.balance) - amount
    to.balance == old(to.balance) + amount
  }

  properties {
    idempotent: true
    atomic: true
    audit_logged: true
  }
}
```

--------------------------------

### Documentation block after module declaration

Source: https://krakenhavoc.github.io/IntentLang/reference/modules.html

Documentation blocks use `---` and can appear after the module declaration or before any entity, action, or invariant. Documentation blocks are preserved in rendered output and audit traces, making them useful for explaining design intent to both humans and tooling.

```intent
module TransferFunds

--- A fund transfer system between accounts within the same currency.
--- Supports basic account-to-account transfers with balance validation,
--- idempotency guarantees, and manager approval for large amounts.
```

--------------------------------

### Diff two spec files

Source: https://krakenhavoc.github.io/IntentLang/cli/agent-tools.html

Shows a spec-level diff between two versions of a spec file. Reports added, removed, and modified spec items.

```CLI
intent diff <old-file> <new-file>
```

--------------------------------

### properties block with metadata

Source: https://krakenhavoc.github.io/IntentLang/reference/actions.html

Shows the properties block syntax for key-value metadata. Properties are not validated semantically; they are metadata for downstream tooling.

```intentlang
properties {
  idempotent: true
  idempotency_key: request_id
  atomic: true
  audit_logged: true
  max_latency_ms: 500
  requires_role: "compliance_officer"
}
```

--------------------------------

### Import a single item from another module

Source: https://krakenhavoc.github.io/IntentLang/reference/modules.html

Imports only the `Account` entity from `Types`.

```intent
module Banking

use Types.Account
```

--------------------------------

### Define a basic invariant with forall quantifier

Source: https://krakenhavoc.github.io/IntentLang/reference/invariants.html

Defines an invariant named NoNegativeBalances that ensures no account has a negative balance. Uses the forall quantifier over Account instances.

```intentlang
invariant NoNegativeBalances {
  --- No account may ever have a negative balance.
  forall a: Account => a.balance >= 0
}
```

--------------------------------

### Basic entity definition with typed fields

Source: https://krakenhavoc.github.io/IntentLang/reference/entities.html

Defines an Account entity with a UUID, owner String, Decimal with precision, CurrencyCode, a status union type, and a DateTime.

```intentlang
entity Account {
  id: UUID
  owner: String
  balance: Decimal(precision: 2)
  currency: CurrencyCode
  status: Active | Frozen | Closed
  created_at: DateTime
}
```

--------------------------------

### Entity with optional and collection types

Source: https://krakenhavoc.github.io/IntentLang/reference/entities.html

Shows entity CartItem with a reference field (Product), primitive Int, optional String?, and a list of strings.

```intentlang
entity CartItem {
  product: Product       // reference to another entity
  quantity: Int          // primitive type
  notes: String?         // optional type
  tags: List<String>     // collection type
}
```