# {{ project_name }} - Quick Start Guide

Get up and running with {{ project_name }} provisioning in 5 minutes.

## Prerequisites

Install required tools:

```bash
# TypeDialog (interactive forms)
cargo install typedialog

# Nickel (configuration language)
cargo install nickel

# Optional: Format converters
apt-get install jq  # JSON processor
cargo install json2toml  # TOML converter
```

## Step 1: Run Configuration Wizard

Choose your preferred shell:

**Bash:**
```bash
chmod +x scripts/configure.sh
./scripts/configure.sh
```

**Nushell:**
```bash
chmod +x scripts/configure.nu
./scripts/configure.nu
```

The wizard will:
1. Display an interactive TypeDialog form
2. Collect configuration values
3. Generate Nickel configuration
4. Validate with schema/type contracts
5. Export to JSON, YAML, TOML

## Step 2: Review Generated Configuration

Check the `generated/` directory:

```bash
ls -lh generated/
```

You should see:
- `config.ncl` - Nickel source
- `config.json` - JSON export
- `config.yaml` - YAML export
- `user-input.json` - Raw form data

## Step 3: Validate Configuration

Type-check with Nickel:

```bash
nickel typecheck generated/config.ncl
```

If validation passes, your configuration is correct!

## Step 4: Deploy Infrastructure

{% if iac_templates.terraform_enabled %}
### Option A: Terraform/OpenTofu

```bash
cd templates/tofu/{{ infrastructure.providers[0] | default(value="common") }}

# Initialize Terraform
terraform init

# Preview changes
terraform plan -var-file="../../../generated/config.tfvars"

# Apply infrastructure
terraform apply -var-file="../../../generated/config.tfvars"
```
{% endif %}

{% if iac_templates.ansible_enabled %}
### Option B: Ansible

```bash
# Run deployment playbook
ansible-playbook templates/ansible/deploy.yml \
  -i templates/ansible/inventory.yml \
  -e @generated/config.yaml
```
{% endif %}

{% if iac_templates.docker_compose_enabled %}
### Option C: Docker Compose

```bash
# Start services
docker-compose -f templates/docker-compose/service.yml up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```
{% endif %}

## Customizing Configuration

### Edit Nickel Values Directly

1. Open `values/config.ncl` in your editor
2. Modify values (type contracts ensure correctness)
3. Validate: `nickel typecheck values/config.ncl`
4. Export: `nickel export values/config.ncl > generated/config.json`

### Re-run the Form

Simply run `./scripts/configure.sh` again to update values.

## Common Tasks

### Export to Different Format

```bash
# Nickel → JSON
./scripts/nickel-to-json.sh values/config.ncl generated/config.json

# Nickel → YAML
./scripts/nickel-to-yaml.sh values/config.ncl generated/config.yaml
```

### Import Existing JSON

```bash
# JSON → Nickel
./scripts/json-to-nickel.sh existing-config.json values/config.ncl
```

### Validate Without Exporting

```bash
nickel typecheck values/config.ncl
```

## Troubleshooting

### Error: "Type checking failed"

**Cause:** Configuration values don't match schema contracts.

**Fix:** Check the error message for the failing field and correct the value.

Example:
```
Error: contract violated by value
  --> port: 70000
  expected: ValidPort (1-65535)
```

Fix by setting `port = 8080` in `values/config.ncl`.

### Error: "Form file not found"

**Cause:** Missing form fragments or master form.

**Fix:** Ensure all files in `fragments/` directory exist:
```bash
ls -1 fragments/
```

### Error: "nickel command not found"

**Cause:** Nickel not installed.

**Fix:**
```bash
cargo install nickel
```

## Next Steps

- Read [NICKEL_ROUNDTRIP.md](NICKEL_ROUNDTRIP.md) for advanced workflows
- Explore `schemas/` to understand type contracts
- Customize `validators/` for custom validation logic
- Add locales in `locales/` for i18n support

## Support

For issues or questions:
- GitHub: {{ repository | default(value="https://github.com/yourusername/" ~ project_name) }}
- Documentation: `docs/`

---

**Generated by typedialog-prov-gen**
