### Build Ason from Source: Development Setup

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Sets up the development environment for building Ason from source. It includes cloning the repository, optionally installing the 'Task' build tool, and running a setup task that handles building, installation, and completion setup. A manual build option is also provided.

```bash
# Clone the repository
git clone https://github.com/madstone-tech/ason.git
cd ason

# Install Task (optional but recommended)
go install github.com/go-task/task/v3/cmd/task@latest

# Complete setup (builds, installs, and sets up completion)
task setup

# Or manual build
go mod tidy
go build -o ason .

# Install to GOPATH/bin
task install
```

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

### Check Ason Version and Help

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

These commands are used to verify the Ason installation and understand its available functionalities. They are essential for initial setup verification and exploring the tool's capabilities.

```bash
# Check available commands
ason --help

# Check version details
ason --version
```

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

### Verify Ason Installation and Version

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This snippet verifies that Ason is installed correctly by checking its version and displaying available commands. It's a fundamental step before proceeding with other Ason operations.

```bash
# Check Ason version
ason --version
# Should output: ※ Ason v1.0.0

# See available commands
ason --help
```

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

### Cleanup Commands for Ason Examples

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

Shell commands to remove generated projects, example templates from the registry, and template source directories.

```bash
# Remove generated projects
rm -rf my-awesome-project my-web-app user-api

# Remove example templates from registry
ason remove my-first-template
ason remove web-app
ason remove go-service

# Remove template source directories
rm -rf my-first-template web-app-template go-service-template
```

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

### Install Shell Completion for Ason

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Automates the setup of shell completion for Ason, enhancing user experience by providing context-aware command suggestions. Supports multiple shells like Bash, Zsh, and Fish.

```bash
# Install completion for current shell
./scripts/install-completion.sh

# Or if using task
task completion:install
```

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

### Quick Start Example

Source: https://github.com/madstone-tech/ason/blob/main/roadmap/phase2-quality/UOW-006-documentation.md

A basic Go program demonstrating how to use the Ason library for project generation.

```APIDOC
## Quick Start

```go
package main

import (
    "log"
    "github.com/your-org/ason/internal/engine"
    "github.com/your-org/ason/internal/generator"
)

func main() {
    // Create template engine
    eng := engine.NewPongo2Engine()

    // Configure generator options
    opts := &generator.Options{
        Verbose: true,
        DryRun:  false,
        Variables: map[string]string{
            "name": "my-project",
        },
    }

    // Create generator
    gen := generator.NewGenerator(eng, opts)

    // Generate project
    context := map[string]interface{}{
        "name": "my-project",
        "version": "1.0.0",
    }

    err := gen.Generate("/path/to/template", "/path/to/output", context)
    if err != nil {
        log.Fatal(err)
    }
}
```
```

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

### Example: Custom Engine Implementation Setup (Go)

Source: https://github.com/madstone-tech/ason/blob/main/docs/api/engine_interface.md

This snippet demonstrates the basic setup for creating a custom Ason engine, including initializing the generator with a custom engine implementation. It highlights the dependency on the `pkg` package and the `NewGenerator` function.

```go
engine := NewCustomEngine()
gen, err := pkg.NewGenerator(engine)
```

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

### Install Ason: Windows Binaries (x86_64)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on Windows by downloading a zip archive, extracting it, and moving the executable to a specified directory (e.g., C:\Program Files\ason). It assumes the directory is in the system's PATH or verifies installation afterwards.

```powershell
# Download and extract
Invoke-WebRequest -Uri "https://github.com/madstone-tech/ason/releases/latest/download/ason_Windows_x86_64.zip" -OutFile "ason.zip"
Expand-Archive -Path "ason.zip" -DestinationPath "."

# Move to a directory in PATH
Move-Item "ason.exe" "C:\Program Files\ason\"

# Add to PATH or verify installation
ason --version
```

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

### Install Ason: Go Install

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs the Ason binary directly using the Go toolchain. This method requires Go to be installed on the system. It supports installing the latest version or a specific version and requires that the Go binary path is included in the system's PATH environment variable for verification.

```bash
# Install latest version
go install github.com/madstone-tech/ason@latest

# Install specific version
go install github.com/madstone-tech/ason@v1.0.0

# Verify installation (ensure $GOPATH/bin is in PATH)
ason --version
```

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

### Manual Bash Shell Completion Setup

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Manually sets up Bash shell completion for Ason by generating the completion script and configuring the bash environment. Ensures command-line efficiency for Bash users.

```bash
# Generate and install completion
ason completion bash > ~/.local/share/bash-completion/completions/ason

# Add to ~/.bashrc if needed
echo '. ~/.local/share/bash-completion/completions/ason' >> ~/.bashrc
```

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

### Verify Ason Installation and Version

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Checks if the Ason binary is correctly installed and accessible in the system's PATH. It also displays the currently installed version of Ason.

```bash
ason --version
```

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

### Verify Ason Installation and Basic Functionality

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

A series of verification steps to ensure Ason is correctly installed and operational. It checks for the executable's presence, permissions, and tests fundamental commands like `--help`, `--version`, and `list`.

```bash
# Check binary exists and is executable
ls -la $(which ason)

# Test basic functionality
ason --help
ason --version
ason list

# Check file permissions
stat $(which ason)

# Test template operations
mkdir test-template
echo "# {{ project_name }}" > test-template/README.md
ason new test-template test-output --dry-run
rm -rf test-template test-output
```

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

### Install Ason: APT (Debian/Ubuntu)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on Debian-based systems (like Ubuntu) by downloading a .deb package and installing it using 'dpkg'. It includes an option to install missing dependencies if needed and verifies the installation.

```bash
# Download and install DEB package
curl -sLO https://github.com/madstone-tech/ason/releases/latest/download/ason_amd64.deb
sudo dpkg -i ason_amd64.deb

# Or install dependencies if needed
sudo apt-get install -f

# Verify installation
ason --version
```

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

### Manual Fish Shell Completion Setup

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Configures Fish shell completion for Ason by generating the necessary completion script and placing it in the Fish configuration directory. This ensures seamless command auto-completion for Fish users.

```bash
# Generate completion
ason completion fish > ~/.config/fish/completions/ason.fish
```

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

### Install Ason: Linux Binaries (x86_64, ARM64)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on Linux by downloading and extracting pre-built binaries for x86_64 or ARM64 architectures. It then moves the executable to /usr/local/bin and verifies the installation.

```bash
# x86_64
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Linux_x86_64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

# ARM64
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Linux_arm64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

# Verify installation
ason --version
```

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

### Verify Ason Installation

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

A simple command to verify that the Ason executable is installed correctly and accessible in the system's PATH. It prints the installed version of Ason.

```bash
# Verify Ason is installed and accessible
ason --version
```

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

### Install Ason: macOS Binaries (Intel, Apple Silicon)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on macOS by downloading and extracting pre-built binaries for Intel (x86_64) or Apple Silicon (arm64) architectures. It then moves the executable to /usr/local/bin and verifies the installation.

```bash
# Intel Macs
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Darwin_x86_64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

# Apple Silicon (M1/M2)
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Darwin_arm64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

# Verify installation
ason --version
```

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

### Create Ason Configuration File

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Demonstrates how to create a user-specific configuration file for Ason. This file allows customization of default template directories, registry paths, and other operational parameters.

```bash
# Create configuration directory
mkdir -p ~/.ason

# Example configuration file (~/.ason/config.yaml)
cat > ~/.ason/config.yaml << EOF
# Ason Configuration
default_template_dir: ~/templates
registry_path: ~/.ason/templates
auto_backup: true
completion_cache: true

# Default variables
defaults:
  author: "Your Name"
  email: "your.email@example.com"
  license: "MIT"
EOF
```

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

### Implement Ason Configuration Best Practices

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/configuration.md

Guidelines for managing Ason configurations effectively. This covers using version control for tracking configuration files, setting up environment-specific configurations, structuring configurations modularly, and documenting the setup.

```bash
# Track your configuration
cd ~/.ason
git init
git add config.yaml
git commit -m "Initial Ason configuration"
```

```bash
# Development environment
~/.ason/config.dev.yaml

# Production environment
~/.ason/config.prod.yaml

# Use environment variable to switch
export ASON_CONFIG="~/.ason/config.${ENVIRONMENT}.yaml"
```

```bash
# Split configuration into modules
~/.ason/
├── config.yaml              # Main config
├── defaults.yaml            # Default variables
├── templates.yaml           # Template overrides
├── integrations.yaml        # External tool config
└── personal.yaml           # Personal preferences
```

```bash
# Document your configuration
cat > ~/.ason/README.md << 'EOF'
# My Ason Configuration

## Overview
This configuration is optimized for:
- Go and Node.js development
- Team collaboration
- CI/CD integration

## Custom Variables
- `company_name`: Set to "MyCompany"
- `default_license`: Set to "MIT"

## Template Overrides
- `go-service`: Uses Go 1.25, PostgreSQL default
- `react-app`: Uses Node 18, TypeScript enabled

## Maintenance
- Backup monthly: `make backup-ason-config`
- Update quarterly: `make update-ason-config`
EOF
```

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

### Build Ason: Quick Build (Current Platform)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Builds the Ason executable for the current operating system and architecture. This can be done using the 'task build' command (if Task is installed) or directly using 'go build'.

```bash
# Build for current platform
task build

# Or with go directly
go build -o ason .
```

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

### Ason CLI Help and Information Commands

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

Commands to access help documentation for the Ason CLI, specific commands, and to display the current version.

```bash
# Help and information
ason --help                         # Show help
ason COMMAND --help                 # Show command help
ason --version                      # Show version
```

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

### Troubleshoot Permission Denied Errors

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Provides solutions for 'Permission Denied' errors encountered during Ason installation or execution. It includes steps for moving the binary to a system-wide location with appropriate permissions or installing it to a user-specific directory.

```bash
# If you get permission denied when installing to /usr/local/bin
sudo mv ason /usr/local/bin/
sudo chmod +x /usr/local/bin/ason

# Or install to user directory
mkdir -p ~/bin
mv ason ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
```

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

### Context7 Configuration Example (Folders)

Source: https://github.com/madstone-tech/ason/blob/main/CONTEXT7_PUBLISHING_GUIDE.md

Specifies which directories within the Ason repository Context7 should parse for documentation. This configuration ensures that relevant guides, API documentation, and examples are indexed.

```json
"folders": ["docs", "pkg", "examples"]
```

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

### Install Ason: AUR (Arch Linux)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Provides multiple methods for installing Ason on Arch Linux via the Arch User Repository (AUR). It covers installations using AUR helpers like 'yay' and 'paru', as well as a manual installation process involving cloning the repository and running 'makepkg'.

```bash
# Using yay
yay -S ason

# Using paru
paru -S ason

# Manual installation
git clone https://aur.archlinux.org/ason.git
cd ason
makepkg -si
```

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

### Replace Existing Binary with Ason

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Replaces the currently installed Ason binary with a new one, typically after a manual download or build. This ensures the latest version is active.

```bash
sudo mv ason /usr/local/bin/
```

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

### Create Ason Project Template Files

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This set of commands creates the necessary files for a basic Ason project template: README.md, package.json, and ason.toml. These files define the template structure and variables.

```bash
# Create a template directory
mkdir -p my-first-template

# Create some template files
cat > my-first-template/README.md << 'EOF'
# {{ project_name }}

{{ description | default:"A project created with Ason" }}

## Getting Started

Welcome to {{ project_name }}!

Author: {{ author | default:"Unknown" }}
Version: {{ version | default:"1.0.0" }}
EOF

cat > my-first-template/package.json << 'EOF'
{
  "name": "{{ project_name | lower | replace(" ", "-") }}",
  "version": "{{ version | default:"1.0.0" }}",
  "description": "{{ description }}",
  "author": "{{ author }}",
  "license": "MIT"
}
EOF

# Create a configuration file (optional)
cat > my-first-template/ason.toml << 'EOF'
name = "My First Template"
description = "A simple template for learning Ason"
version = "1.0.0"
type = "example"

[[variables]]
name = "project_name"
description = "Name of the project"
required = true

[[variables]]
name = "description"
description = "Project description"
required = false
default = "A project created with Ason"

[[variables]]
name = "author"
description = "Project author"
required = false
default = "Unknown"

[[variables]]
name = "version"
description = "Initial version"
required = false
default = "1.0.0"
EOF
```

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

### Update Ason Manually

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Guides users on how to manually update Ason by downloading the latest binary release directly. This method is useful when package managers are not available or preferred.

```bash
# Download latest binary
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_$(uname -s)_$(uname -m).tar.gz | tar xz
```

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

### Set Up Ason Shell Completion

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This optional step provides commands to set up shell completion for Ason in Bash and Zsh environments, enhancing the command-line user experience.

```bash
# Install completion for your shell
ason completion bash > ~/.local/share/bash-completion/completions/ason

# Or for zsh (Oh My Zsh)
mkdir -p ~/.oh-my-zsh/custom/plugins/ason
ason completion zsh > ~/.oh-my-zsh/custom/plugins/ason/_ason
# Add 'ason' to plugins in ~/.zshrc
```

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

### Generate Ason Project from Template

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This commands demonstrate how to generate a new project from a registered Ason template. It includes a dry-run option for previewing changes and the actual command to create the project with specified variables.

```bash
# Test with dry run first
ason new my-first-template my-awesome-project --dry-run

# Generate the actual project
ason new my-first-template my-awesome-project \
  --var project_name="My Awesome Project" \
  --var description="A fantastic project built with Ason" \
  --var author="Your Name" \
  --var version="0.1.0"
```

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

### Generate Environment Configuration (.env.example)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/first-template.md

Creates a `.env.example` file for project configuration, including server settings, database connection details (MongoDB, PostgreSQL, MySQL, SQLite), and optional authentication settings. The content varies based on the selected database and whether authentication is included. This file serves as a template for the actual `.env` file.

```bash
cat > .env.example << 'EOF'
# Server Configuration
PORT={{ port }}
NODE_ENV=development

# Database Configuration
{% if database == "mongodb" %}
MONGODB_URI=mongodb://localhost:27017/{{ project_slug }}
{% elif database == "postgresql" %}
DB_HOST=localhost
DB_PORT=5432
DB_NAME={{ project_slug }}
DB_USER=postgres
DB_PASSWORD=
{% elif database == "mysql" %}
DB_HOST=localhost
DB_PORT=3306
DB_NAME={{ project_slug }}
DB_USER=root
DB_PASSWORD=
{% elif database == "sqlite" %}
DB_PATH=./{{ project_slug }}.sqlite
{% endif %}

{% if include_auth %}
# Authentication
JWT_SECRET=your-very-secure-secret-key-here
JWT_EXPIRES_IN=24h
{% endif %}

# API Configuration
API_VERSION=v1
CORS_ORIGIN=http://localhost:3000
EOF
```

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

### Go Quick Start for Project Generation

Source: https://github.com/madstone-tech/ason/blob/main/roadmap/phase2-quality/UOW-006-documentation.md

This snippet demonstrates how to use the Ason library to generate a project. It covers creating a template engine, configuring generator options, initializing the generator, and executing the project generation process. It requires the 'engine' and 'generator' internal packages.

```go
package main

import (
    "log"
    "github.com/your-org/ason/internal/engine"
    "github.com/your-org/ason/internal/generator"
)

func main() {
    // Create template engine
    eng := engine.NewPongo2Engine()

    // Configure generator options
    opts := &generator.Options{
        Verbose: true,
        DryRun:  false,
        Variables: map[string]string{
            "name": "my-project",
        },
    }

    // Create generator
    gen := generator.NewGenerator(eng, opts)

    // Generate project
    context := map[string]interface{}{
        "name": "my-project",
        "version": "1.0.0",
    }

    err := gen.Generate("/path/to/template", "/path/to/output", context)
    if err != nil {
        log.Fatal(err)
    }
}
```

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

### Basic Project Generation Examples

Source: https://github.com/madstone-tech/ason/blob/main/docs/commands/new.md

Demonstrates how to generate projects from both local template paths and template names from a registry.

```bash
# Generate from local template
ason new ./templates/react-app my-new-app
```

```bash
# Generate from registry template (once implemented)
ason new golang-service user-service
```

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

### Bash CLI Example: Generate from Template

Source: https://github.com/madstone-tech/ason/blob/main/llm.txt

Provides a step-by-step example of using the Ason command-line interface to create a new project from a registered template. It includes steps for creating a template, registering it, and generating a project with custom variables.

```bash
# Create a template
mkdir -p ~/templates/react-app
echo '# {{ project_name }}' > ~/templates/react-app/README.md.tmpl
echo 'Author: {{ author }}' >> ~/templates/react-app/README.md.tmpl

# Register template
ason register react_app ~/templates/react-app

# Generate project
ason new react_app my-app --var project_name=MyApp --var author=Alice

# View generated file
cat my-app/README.md
```

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

### Example Plugin Implementation

Source: https://github.com/madstone-tech/ason/blob/main/roadmap/phase4-architecture/UOW-010-plugin-architecture.md

A basic Go package structure for an example plugin. It includes necessary imports for context, formatting, I/O, and string manipulation, along with the internal engine package.

```go
// Example plugin implementation
package main

import (
    "context"
    "fmt"
    "io"
    "strings"

    "your-module/internal/engine"
)
```

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

### Ason CLI Quick Start Commands

Source: https://github.com/madstone-tech/ason/blob/main/README.md

Provides essential Ason command-line interface commands for quick usage, including viewing help, registering templates, listing available templates, and creating new projects from registered or local templates.

```bash
# View available commands
ason --help

# Register a template
ason register my-template ./path/to/template

# List registered templates
ason list

# Create a project from a template
ason new my-template my-project

# Or use a local template directly
ason new ./path/to/template my-project
```

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

### Manual Zsh (Oh My Zsh) Shell Completion Setup

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Integrates Ason shell completion into Zsh, specifically for users employing the Oh My Zsh framework. This involves creating a custom plugin directory and adding Ason to the shell's plugin list.

```bash
# Create plugin directory
mkdir -p ~/.oh-my-zsh/custom/plugins/ason

# Generate completion
ason completion zsh > ~/.oh-my-zsh/custom/plugins/ason/_ason

# Add to plugins in ~/.zshrc
# plugins=(... ason)
```

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

### Install Ason: YUM/DNF (RedHat/CentOS/Fedora)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on RedHat-based systems (like CentOS or Fedora) by downloading an RPM package and installing it using 'rpm' or 'dnf'. It verifies the installation with 'ason --version'.

```bash
# Download and install RPM package
curl -sLO https://github.com/madstone-tech/ason/releases/latest/download/ason_x86_64.rpm
sudo rpm -i ason_x86_64.rpm

# Or with dnf
sudo dnf install ason_x86_64.rpm

# Verify installation
ason --version
```

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

### Install Ason: Homebrew (macOS/Linux)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on macOS or Linux using the Homebrew package manager. It involves tapping a custom repository and then installing the Ason package. The installation is verified with 'ason --version'.

```bash
# Add the tap
brew tap madstone-tech/tap

# Install Ason
brew install ason

# Verify installation
ason --version
```

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

### Install Ason CLI

Source: https://github.com/madstone-tech/ason/blob/main/llm.txt

Instructions for installing the Ason command-line interface on macOS, Linux, and via Go.

```bash
# macOS (Homebrew)
brew tap madstone-tech/tap
brew install ason

# Linux
curl -sL https://github.com/madstone-tech/ason/releases/latest/download/ason_Linux_x86_64.tar.gz | tar xz
sudo mv ason /usr/local/bin/

# Go
go install github.com/madstone-tech/ason@latest
```

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

### Troubleshoot Command Not Found Errors

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Addresses the 'Command Not Found' error by guiding users to check their system's PATH environment variable. It includes instructions for verifying the PATH and adding Ason's installation directory if it's missing.

```bash
# Check if installation directory is in PATH
echo $PATH

# Add to PATH if needed
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or find where ason was installed
find / -name "ason" 2>/dev/null
```

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

### Create Advanced Ason Configuration (YAML Example)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/configuration.md

Illustrates an advanced Ason configuration using YAML syntax, which needs to be converted to TOML for actual use. It covers extensive settings for registry, discovery, defaults, processing, output, UI, completion, plugins, and integrations.

```bash
cat > ~/.config/ason/config.yaml << 'EOF'
# Advanced Ason Configuration

# Global settings
global:
  debug: false
  verbose: false
  quiet: false

# Registry configuration
registry:
  path: ~/.ason/templates
  auto_backup: true
  backup_dir: ~/.ason/backups
  backup_count: 10
  compression: gzip
  index_cache: true

# Template discovery
discovery:
  auto_scan: true
  scan_paths:
    - ~/templates
    - ~/projects/templates
    - ~/.local/share/ason/templates
  scan_depth: 3
  ignore_patterns:
    - ".*"
    - "node_modules"
    - "__pycache__"
    - "*.tmp"

# Default variables
defaults:
  # Personal info
  author: "Your Name"
  email: "your.email@example.com"
  github_username: "yourusername"
  organization: "Your Organization"

  # Project defaults
  license: "MIT"
  version: "1.0.0"
  go_version: "1.25"
  node_version: "18"
  python_version: "3.11"

  # Paths and URLs
  homepage: "https://github.com/yourusername"
  repository_base: "github.com/yourusername"

# Template processing
processing:
  # Variable resolution
  variable_prefix: "{{"
  variable_suffix: "}}"
  strict_variables: false

  # File processing
  binary_extensions:
    - ".png"
    - ".jpg"
    - ".jpeg"
    - ".gif"
    - ".ico"
    - ".pdf"
    - ".zip"
    - ".tar.gz"

  ignore_files:
    - ".DS_Store"
    - "Thumbs.db"
    - "*.tmp"
    - "*.swp"
    - ".git"
    - ".svn"

  # Size limits
  max_file_size: 10MB
  max_template_size: 100MB

# Output configuration
output:
  default_directory: ~/projects
  create_parent_directories: true
  overwrite_existing: confirm  # confirm, always, never
  permissions:
    files: 644
    directories: 755
    executables: 755

  # Backup before overwrite
  backup_on_overwrite: true
  backup_suffix: ".ason-backup"

# User interface
ui:
  colors: true
  emoji: true
  progress_bars: true
  animations: true
  confirm_destructive: true

  # Theme settings
  theme:
    primary: blue
    secondary: green
    warning: yellow
    error: red
    success: green

# Shell completion
completion:
  enabled: true
  cache_enabled: true
  cache_ttl: 3600
  template_suggestions: true
  variable_suggestions: true
  path_completion: true

# Plugin system (future feature)
plugins:
  enabled: true
  auto_install: false
  directory: ~/.ason/plugins
  repositories:
    - "github.com/madstone-tech/ason-plugins"

# External integrations
integrations:
  git:
    auto_init: true
    initial_commit: true
    commit_message: "Initial commit from Ason template"

  editors:
    preferred: "code"  # code, vim, emacs, etc.
    open_after_generation: ask  # always, never, ask


```

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

### Validating and Fixing Ason Templates

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This example demonstrates how to validate Ason templates for correctness and potential issues. The `--strict` flag enforces stricter validation rules. The `--fix` flag attempts to automatically resolve common validation errors. This is crucial for ensuring template integrity before registration.

```bash
# Always validate templates before adding
ason validate ./my-template --strict

# Fix common issues automatically
ason validate ./my-template --fix
```

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

### Ason CLI: Create Project from Registry Template

Source: https://context7.com/madstone-tech/ason/llms.txt

Command-line examples for creating a new project using Ason. This includes registering a template, creating a project with inline variables, using a variable file, overriding file variables with CLI flags, and performing a dry run to preview changes without generating files.

```bash
# Register a template first
ason register golang-api /templates/golang-api "Go REST API template"

# Create project with inline variables
ason new golang-api my-service \
  --var project_name=my-service \
  --var author="Dev Team" \
  --var version=1.0.0

# Create project with variable file
ason new golang-api my-service --var-file prod.yaml

# Variable file (prod.yaml):
# project_name: my-service
# author: Dev Team
# version: 1.0.0
# environment: production
# enable_metrics: true

# Override file variables with CLI flags
ason new golang-api my-service \
  --var-file base.yaml \
  --var environment=production \
  --var enable_debug=false

# Preview without creating files
ason new golang-api my-service --dry-run --var-file dev.yaml

```

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

### Docker: Run Pre-built Ason Image

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Pulls the latest Ason Docker image from GitHub Container Registry and runs it. The command mounts the current working directory to `/workspace` inside the container and executes `ason --version`. It also provides an example of creating a bash alias for easier containerized execution.

```bash
# Pull the image
docker pull ghcr.io/madstone-tech/ason:latest

# Run Ason in container
docker run --rm -v $(pwd):/workspace ghcr.io/madstone-tech/ason:latest --version

# Create alias for easier use
echo 'alias ason="docker run --rm -v $(pwd):/workspace ghcr.io/madstone-tech/ason:latest"' >> ~/.bashrc
source ~/.bashrc
```

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

### Complete ASON Project Generation Workflow with Go

Source: https://context7.com/madstone-tech/ason/llms.txt

This Go example demonstrates a comprehensive ASON workflow, from setting up a temporary registry and registering templates to generating a project and cleaning up resources. It includes error handling and utilizes context for operations. The code requires the 'github.com/madstone-tech/ason/pkg' package.

```go
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"path/filepath"
	"time"
	"github.com/madstone-tech/ason/pkg"
)

func main() {
	// Setup: Create a temporary registry for this example
	tmpDir := os.TempDir()
	registryPath := filepath.Join(tmpDir, "example-registry.toml")
	templateDir := filepath.Join(tmpDir, "my-template")
	outputDir := filepath.Join(tmpDir, "generated-project")

	defer func() {
		os.RemoveAll(templateDir)
		os.RemoveAll(outputDir)
		os.Remove(registryPath)
	}()

	// Step 1: Create a simple template directory
	if err := os.MkdirAll(templateDir, 0755); err != nil {
		log.Fatal(err)
	}

	// Create a template file
	templateContent := `# {{ project_name }}\n\nCreated by: {{ author }}\nVersion: {{ version }}\nDate: {{ date }}\n\n`
	err := os.WriteFile(filepath.Join(templateDir, "main.md"), []byte(templateContent), 0644)
	if err != nil {
		log.Fatal(err)
	}

	// Step 2: Create and populate the registry
	reg, err := pkg.NewRegistryAt(registryPath)
	if err != nil {
		log.Fatal(err)
	}

	err = reg.Register("sample-project", templateDir, "A basic sample project template")
	if err != nil {
		log.Fatal(err)
	}

	// Step 3: Initialize generator with default engine and the custom registry
	gen, err := pkg.NewGenerator(nil) // Use default engine (Pongo2)
	if err != nil {
		log.Fatal(err)
	}

	gen.WithRegistry(reg)

	// Step 4: Define project variables and generate
	variables := map[string]interface{}{
		"project_name": "MyAwesomeProject",
		"author":       "Example User",
		"version":      "0.1.0",
		"date":         time.Now().Format("2006-01-02"),
	}

	ctx := context.Background()
	err = gen.Generate(ctx, "sample-project", variables, outputDir)
	if err != nil {
		log.Fatalf("Project generation failed: %v", err)
	}

	fmt.Printf("Project successfully generated at: %s\n", outputDir)

	// Example of accessing generated file content
	generatedFilePath := filepath.Join(outputDir, "main.md")
	content, err := os.ReadFile(generatedFilePath)
	if err != nil {
		log.Printf("Could not read generated file %s: %v", generatedFilePath, err)
	} else {
		fmt.Printf("\nContent of %s:\n%s\n", filepath.Base(generatedFilePath), string(content))
	}
}
```

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

### Uninstall Ason using Homebrew

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Removes Ason installed via Homebrew and untaps the repository. This is the standard method for Homebrew users.

```bash
brew uninstall ason
brew untap madstone-tech/tap
```

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

### Go Example for Custom Template Engine Implementation

Source: https://github.com/madstone-tech/ason/blob/main/roadmap/phase2-quality/UOW-006-documentation.md

Provides an example implementation of the `Engine` interface for a custom template engine. This snippet shows how to define a `CustomEngine` struct and implement the `Render` and `RenderFile` methods, including basic file reading and custom rendering logic.

```go
type CustomEngine struct{}

func (e *CustomEngine) Render(template string, context map[string]interface{}) (string, error) {
    // Custom rendering logic
    return processedTemplate, nil
}

func (e *CustomEngine) RenderFile(filepath string, context map[string]interface{}) (string, error) {
    content, err := os.ReadFile(filepath)
    if err != nil {
        return "", err
    }
    return e.Render(string(content), context)
}
```

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

### Generate Projects from Ason Templates

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This bash script demonstrates how to generate new projects using Ason templates. It shows commands for creating a web application and a Go service, specifying project names and variables using the `--var` flag. It also includes commands to list the contents of the generated project directories.

```bash
# Generate a web app
ason new web-app my-web-app \
  --var project_name="My Web App" \
  --var description="A cool web application" \
  --var author="Your Name"

# Generate a Go service
ason new go-service user-api \
  --var service_name="UserAPI" \
  --var description="User management API" \
  --var port="8080" \
  --var module_name="github.com/yourname/user-api"

# Check what was created
ls -la my-web-app/
ls -la user-api/
```

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

### Registering Ason Templates by Type

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This example demonstrates how to register Ason templates with the Ason registry, organizing them by type. It shows commands for registering a React template as 'web', a Vue template as 'web', a Go API template as 'backend', and a Python API template as 'backend'. This allows for easier categorization and retrieval of templates.

```bash
# Organize templates by type
ason register react-app ./templates/web/react --type web
ason register vue-app ./templates/web/vue --type web
ason register go-api ./templates/backend/go --type backend
ason register python-api ./templates/backend/python --type backend
```

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

### Uninstall Ason using APT

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Removes Ason installed using the APT package manager, common on Debian-based systems like Ubuntu.

```bash
sudo apt remove ason
```

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

### Go Implementing Custom Template Engines

Source: https://github.com/madstone-tech/ason/blob/main/llm.txt

Demonstrates how to implement custom template engines by satisfying the `Engine` interface. Includes `MyCustomEngine` for custom logic and `SimpleEngine` for basic variable replacement. These implementations must be thread-safe.

```go
package main

import (
	"fmt"
	"strings"
	"github.com/madstone-tech/ason/pkg"
	"context"
)

// MyCustomEngine implements pkg.Engine
type MyCustomEngine struct{}

func (e *MyCustomEngine) Render(template string, 
	context map[string]interface{}) (string, error) {
	// Your custom template rendering logic
	// Must be thread-safe
	return template, nil
}

func (e *MyCustomEngine) RenderFile(filePath string,
	context map[string]interface{}) (string, error) {
	// Your custom file rendering logic
	// Must be thread-safe
	return "", nil
}

// SimpleEngine example - basic variable replacement
type SimpleEngine struct{}

func (e *SimpleEngine) Render(template string, 
	context map[string]interface{}) (string, error) {
	result := template
	for key, value := range context {
		placeholder := "{{" + key + "}}"
		result = strings.ReplaceAll(result, placeholder, 
			fmt.Sprintf("%v", value))
	}
	return result, nil
}

func (e *SimpleEngine) RenderFile(filePath string,
	context map[string]interface{}) (string, error) {
	return "", nil
}

func main() {
	engine := &MyCustomEngine{}
	gen, _ := pkg.NewGenerator(engine)
	gen.Generate(context.Background(), "./template", nil, "./output")
}
```

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

### Remove Ason Binary

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Removes the Ason binary executable from the system. This can be done from the standard binary location or from the GOPATH if installed via Go.

```bash
sudo rm /usr/local/bin/ason
```

```bash
rm $GOPATH/bin/ason
```

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

### Integrate Ason List into Scripts

Source: https://github.com/madstone-tech/ason/blob/main/docs/commands/list.md

Scripting examples showing how to dynamically select a template for project generation and how to prepare template names for shell completion.

```bash
# Generate project from first available template
template=$(ason list --format json | jq -r '.templates[0].name')
ason new "$template" "my-project"

# List templates for shell completion
ason list --format json | jq -r '.templates[].name' | sort
```

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

### Create Projects with Ason CLI

Source: https://github.com/madstone-tech/ason/blob/main/llm.txt

Demonstrates various ways to create new projects using the Ason CLI, including from registered templates, local directories, with variables, and dry runs.

```bash
# From registered template
ason new <template-name> <output-directory>
ason new golang-service my-service

# From local directory
ason new ./my-template ./output

# With variables
ason new golang-service my-service --var name=MyService --var author=Alice

# Dry run (preview without writing)
ason new golang-service my-service --dry-run
```

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

### Uninstall Ason using DNF/YUM

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Removes Ason installed using the DNF or YUM package manager, typically found on Fedora and RHEL-based systems.

```bash
sudo dnf remove ason
```

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

### Install Ason: Scoop (Windows)

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Installs Ason on Windows using the Scoop package manager. This involves adding a custom bucket (repository) and then installing Ason. Verification is done using 'ason --version'. Note: The bucket addition might be a placeholder ('coming soon').

```powershell
# Add the bucket (coming soon)
scoop bucket add madstone-tech https://github.com/madstone-tech/scoop-bucket

# Install Ason
scoop install ason

# Verify installation
ason --version
```

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

### Update Ason from Source

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/installation.md

Updates the Ason tool by pulling the latest changes from the main branch of its Git repository and then rebuilding and installing it. Requires development dependencies.

```bash
cd ason
git pull origin main
task clean
task build
task install
```

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

### Ason CLI Usage Examples

Source: https://github.com/madstone-tech/ason/blob/main/CONTEXT7_PUBLISHING_GUIDE.md

Demonstrates common commands for using Ason as a command-line tool. This section is intended for DevOps engineers and template creators. Documentation for these commands is typically found in `docs/commands/`.

```bash
# Using Ason as a command-line tool
ason register my-template ./templates/my-template
ason list
ason new my-template my-project --var name=value
ason validate my-template
```

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

### Using Pongo2 Filters in Ason Templates

Source: https://github.com/madstone-tech/ason/blob/main/docs/getting-started/quick-start.md

This snippet showcases the usage of Pongo2 filters within Ason templates for variable manipulation. It provides examples of common filters like 'lower' for converting text to lowercase, 'replace' for substituting characters, 'default' for setting fallback values, and 'title' for title-casing text. These filters enhance template flexibility.

```bash
# Common Pongo2 filters
{{ project_name | lower }}                    # Convert to lowercase
{{ project_name | replace(" ", "-") }}        # Replace spaces with dashes
{{ description | default:"No description" }}  # Provide default value
{{ author | title }}                          # Title case
```