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

# Template Overview

> Understanding the project template and optional examples

## What You Get

When you run `lua init`, you get a **minimal, clean project** ready for you to build your agent:

<CardGroup cols={2}>
  <Card title="Empty Agent" icon="rocket">
    A clean slate - no example code cluttering your project
  </Card>

  <Card title="TypeScript Setup" icon="code">
    Full type safety and configuration included
  </Card>

  <Card title="Ready to Deploy" icon="upload">
    All configuration files in place
  </Card>

  <Card title="Quick Start Guide" icon="book">
    Step-by-step instructions included
  </Card>
</CardGroup>

## Minimal vs Full Template

<Tabs>
  <Tab title="Minimal (Default)">
    ```bash theme={null}
    lua init
    ```

    Creates a clean project with just the essentials:

    ```
    your-project/
    ├── src/
    │   └── index.ts          # Empty agent ready to customize
    ├── lua.skill.yaml        # Configuration
    ├── package.json          # Dependencies
    └── tsconfig.json         # TypeScript config
    ```

    **Best for:** Experienced developers who want a clean slate
  </Tab>

  <Tab title="With Examples">
    ```bash theme={null}
    lua init --with-examples
    ```

    Creates a full project with 30+ working examples:

    ```
    your-project/
    ├── src/
    │   └── index.ts          # Agent configuration
    ├── examples/             # 👈 Example code
    │   ├── skills/           # Example skills & tools
    │   ├── webhooks/         # Example HTTP endpoints
    │   ├── jobs/             # Example scheduled tasks
    │   ├── preprocessors/    # Example message filters
    │   └── postprocessors/   # Example response formatters
    ├── lua.skill.yaml
    ├── package.json
    └── tsconfig.json
    ```

    **Best for:** New users who want to learn by example
  </Tab>
</Tabs>

## Quick Start (Minimal Template)

<Steps>
  <Step title="Initialize Your Project">
    ```bash theme={null}
    mkdir my-agent && cd my-agent
    lua init
    ```
  </Step>

  <Step title="Chat with Your Agent">
    ```bash theme={null}
    lua chat
    ```

    Select sandbox mode. Your agent works out of the box!
  </Step>

  <Step title="Create Your First Tool">
    Create `src/skills/tools/GreetingTool.ts`:

    ```typescript theme={null}
    import { LuaTool } from "lua-cli";
    import { z } from "zod";

    export default class GreetingTool implements LuaTool {
        name = "greet_user";
        description = "Generate a personalized greeting";
        
        inputSchema = z.object({
            name: z.string()
        });

        async execute(input: z.infer<typeof this.inputSchema>) {
            return { greeting: `Hello, ${input.name}!` };
        }
    }
    ```
  </Step>

  <Step title="Create a Skill">
    Create `src/skills/greeting.skill.ts`:

    ```typescript theme={null}
    import { LuaSkill } from "lua-cli";
    import GreetingTool from "./tools/GreetingTool";

    export default new LuaSkill({
        name: "greeting-skill",
        description: "Greeting tools",
        context: "Use when users want greetings",
        tools: [new GreetingTool()],
    });
    ```
  </Step>

  <Step title="Add to Your Agent">
    Update `src/index.ts`:

    ```typescript theme={null}
    import { LuaAgent } from "lua-cli";
    import greetingSkill from "./skills/greeting.skill";

    const agent = new LuaAgent({
        name: `My Agent`,
        persona: `You are a friendly assistant.`,
        skills: [greetingSkill],
    });
    ```
  </Step>

  <Step title="Test & Deploy">
    ```bash theme={null}
    lua test                           # Test your tool
    lua chat                           # Chat with your agent
    lua push all --force --auto-deploy # Deploy
    ```
  </Step>
</Steps>

## Examples (--with-examples)

When you use `lua init --with-examples`, you get comprehensive examples:

### Example Skills & Tools

<Tabs>
  <Tab title="Platform APIs">
    * `UserDataTool.ts` - User API (get/update user data)
    * `ProductsTool.ts` - Products API (CRUD operations)
    * `BasketTool.ts` - Baskets API (shopping cart)
    * `OrderTool.ts` - Orders API (order management)
    * `CustomDataTool.ts` - Data API (custom collections + semantic search)
  </Tab>

  <Tab title="External APIs">
    * `GetWeatherTool.ts` - External HTTP API integration
    * `PaymentTool.ts` - Stripe payment links
    * `CreatePostTool.ts` - Simple POST request example
  </Tab>

  <Tab title="Advanced Patterns">
    * `SmartBasketTool.ts` - Dynamic job creation from tools
    * `GameScoreTrackerTool.ts` - Interval jobs that self-deactivate
  </Tab>
</Tabs>

### Example Webhooks

HTTP endpoints for external integrations:

| File                  | Purpose                              |
| --------------------- | ------------------------------------ |
| `PaymentWebhook.ts`   | Stripe payment notifications         |
| `UserEventWebhook.ts` | External events + WhatsApp templates |

### Example Jobs

Scheduled background tasks:

| File                             | Schedule Type               |
| -------------------------------- | --------------------------- |
| `HealthCheckJob.ts`              | Interval (every 5 minutes)  |
| `DailyCleanupJob.ts`             | Cron (daily at 2 AM)        |
| `DataMigrationJob.ts`            | One-time (specific date)    |
| `AbandonedBasketProcessorJob.ts` | Interval (batch processing) |

### Example Processors

| Type | File                 | Purpose                        |
| ---- | -------------------- | ------------------------------ |
| Pre  | `messageMatching.ts` | Modify/block incoming messages |
| Post | `modifyResponse.ts`  | Transform agent responses      |

## Using the Examples

### Copy What You Need

```bash theme={null}
# Initialize with examples
lua init --with-examples

# Copy a tool to your src
cp examples/skills/tools/GetWeatherTool.ts src/skills/tools/

# Import and use it
```

### Move the Entire Structure

```bash theme={null}
# Move all examples into your src
mv examples/skills src/
mv examples/webhooks src/
mv examples/jobs src/
```

## Key Files

### src/index.ts

Your agent's main configuration:

```typescript theme={null}
import { LuaAgent } from "lua-cli";

const agent = new LuaAgent({
    name: `your-agent-name`,
    persona: `Your agent's personality...`,
    skills: [],        // Add your skills here
    // webhooks: [],   // Optional: HTTP endpoints
    // jobs: [],       // Optional: Scheduled tasks
});
```

### lua.skill.yaml

Auto-managed configuration file:

```yaml theme={null}
agent:
  agentId: agent_abc123
  orgId: org_xyz789
  persona: "..."

skills:
  - name: my-skill
    version: 1.0.0
    skillId: skill_xyz  # Auto-created
```

<Warning>
  Don't manually edit `skillId`, `webhookId`, or `jobId` - they're auto-managed by the CLI!
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Step-by-step tutorial
  </Card>

  <Card title="Project Structure" icon="folder-tree" href="/template/project-structure">
    Understanding file organization
  </Card>

  <Card title="API Reference" icon="server" href="/api/overview">
    Available platform APIs
  </Card>

  <Card title="Best Practices" icon="star" href="/template/best-practices">
    Tips for building great agents
  </Card>
</CardGroup>