syntaxis/shared/templates/documentation

# {{TOOL_NAME}}

{{SHORT_DESCRIPTION}}

## Features

- **Feature 1** - Brief description
- **Feature 2** - Brief description
- **Feature 3** - Brief description
- **Feature 4** - Brief description
- **Feature 5** - Brief description

## Quick Start

Get started in 5-10 minutes with [QUICKSTART.md](QUICKSTART.md).

For detailed instructions, continue reading below.

## Table of Contents

- [Installation](#installation)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [CLI Commands](#cli-commands)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [Development](#development)

## Installation

### From Source

**Requirements**:
- Rust 1.70+ ([install](https://rustup.rs/))
- Cargo (comes with Rust)

**Build**:

```bash
git clone https://github.com/yourusername/{{tool_name_kebab}}
cd {{tool_name_kebab}}
cargo build --release
```

**Install**:

```bash
cargo install --path crates/{{tool_name_kebab}}-cli
```

**Verify**:

```bash
{{tool_name_kebab}} --version
```

## Architecture

### 3-Tier Architecture

{{TOOL_NAME}} follows a production-grade 3-tier architecture:

**Tier 1: Core Library** (`crates/{{tool_name_kebab}}-core/`)
- Business logic and domain models
- Error handling and validation
- Reusable across different interfaces
- No UI dependencies

**Tier 2: REST API** (`crates/{{tool_name_kebab}}-api/`, optional)
- HTTP server using axum
- JSON request/response format
- Standard CRUD endpoints
- Health checks and monitoring

**Tier 3: CLI** (`crates/{{tool_name_kebab}}-cli/`)
- Command-line interface using clap
- Configuration discovery
- User-friendly commands
- Structured logging

### Module Organization

```
{{tool_name_kebab}}-core/
├── src/
│   ├── lib.rs          # Main module
│   ├── error.rs        # Error types
│   ├── types.rs        # Domain types ({{MainType}})
│   └── handlers/
│       ├── mod.rs
│       └── service.rs  # Business logic ({{MainType}}Service)
└── tests/              # Integration tests
```

### Data Flow

```
User Input
    ↓
CLI (main.rs)
    ↓
Configuration Discovery
    ↓
Core Service ({{MainType}}Service)
    ↓
Business Logic & Storage
    ↓
Response/Output
```

## Configuration

### Configuration Discovery

{{TOOL_NAME}} automatically searches for configuration in this order (uses first found):

1. **`.project/{{tool_name_kebab}}.toml`** - Project using Tools (priority)
2. **`.vapora/{{tool_name_kebab}}.toml`** - VAPORA platform project
3. **`.coder/{{tool_name_kebab}}.toml`** - Doc tracking project
4. **`./{{tool_name_kebab}}.toml`** - Current directory

The tool automatically uses the first existing location.

### Configuration File

See [Configuration Guide](docs/configuration.md) for complete documentation.

**Basic example**:

```toml
[{{tool_name_kebab}}]
# Your configuration here
setting1 = "value1"
setting2 = 42
```

**Complete example**: See [examples/config.toml](examples/config.toml)

### Environment Variables

You can override configuration with environment variables:

```bash
export {{TOOL_NAME}}_SETTING1=value1
{{tool_name_kebab}} list
```

## CLI Commands

### Getting Help

```bash
# Show all commands
{{tool_name_kebab}} --help

# Show help for specific command
{{tool_name_kebab}} list --help

# Show version
{{tool_name_kebab}} --version

# Enable verbose logging
{{tool_name_kebab}} -v list
```

### Available Commands

#### `list` - List all items

```bash
{{tool_name_kebab}} list                    # List all items
{{tool_name_kebab}} list --filter "pattern" # Filter by pattern
{{tool_name_kebab}} list --limit 50         # Limit results
```

**Output**: Shows all {{main_type_plural}} in your project

#### `create` - Create new item

```bash
{{tool_name_kebab}} create "My Item"
{{tool_name_kebab}} create "My Item" --description "Full description"
```

**Output**: Shows created item with ID and timestamp

#### `summary` - Show statistics

```bash
{{tool_name_kebab}} summary                 # Show all statistics
{{tool_name_kebab}} summary --group-by field # Group by field
```

**Output**: Shows counts, totals, and other metrics

#### `version` - Show version

```bash
{{tool_name_kebab}} version
```

**Output**: Shows installed version

## Examples

### Basic Workflow

```bash
# Create configuration
mkdir -p .project
cp examples/config.toml .project/{{tool_name_kebab}}.toml

# Create first item
{{tool_name_kebab}} create "My First Item" --description "Test item"

# List all items
{{tool_name_kebab}} list

# Show summary
{{tool_name_kebab}} summary
```

### Using with Tools Ecosystem

```bash
# Automatic setup
nu /Users/Akasha/Tools/scripts/setup-project-tools.nu

# Configuration is auto-discovered
{{tool_name_kebab}} list
```

### Advanced Usage

```bash
# Export with jq
{{tool_name_kebab}} list | jq '.[] | select(.status == "active")'

# Count items
{{tool_name_kebab}} list | wc -l

# Filter items
{{tool_name_kebab}} list --filter "important"
```

## REST API (Optional)

If using the API server:

```bash
# Start API server
cargo run -p {{tool_name_kebab}}-api --release

# Server runs on http://127.0.0.1:3000
```

### API Endpoints

- `GET /health` - Health check
- `GET /{{main_type_plural}}` - List all items
- `GET /{{main_type_plural}}/:id` - Get specific item
- `POST /{{main_type_plural}}` - Create new item
- `PUT /{{main_type_plural}}/:id` - Update item
- `DELETE /{{main_type_plural}}/:id` - Delete item

### Example API Usage

```bash
# List items
curl http://127.0.0.1:3000/{{main_type_plural}}

# Create item
curl -X POST http://127.0.0.1:3000/{{main_type_plural}} \
  -H "Content-Type: application/json" \
  -d '{"name": "New Item", "description": "Item description"}'

# Get specific item
curl http://127.0.0.1:3000/{{main_type_plural}}/item-id
```

## Troubleshooting

### Configuration Not Found

**Problem**: "No config found in standard locations"

**Solution**: Create configuration in one of the search locations:

```bash
mkdir -p .project
cp examples/config.toml .project/{{tool_name_kebab}}.toml
{{tool_name_kebab}} list  # Should now work
```

### Permission Denied

**Problem**: "Permission denied" error when running

**Solution**: Ensure binary is executable:

```bash
chmod +x ~/.cargo/bin/{{tool_name_kebab}}
```

### Database Lock

**Problem**: "Database is locked" (if using SQLite)

**Solution**: Only one process can write at a time. Wait for other operations to complete, or use PostgreSQL for concurrent access.

### Help Text Issues

**Problem**: Help text shows `{{VARIABLE}}`

**Solution**: Templates weren't properly filled in. Check for unreplaced variables:

```bash
grep -r "{{" crates/*/src/
```

## Development

### Building

```bash
# Development build
cargo build

# Release build (optimized)
cargo build --release
```

### Testing

```bash
# Run all tests
cargo test --workspace

# Run tests for specific crate
cargo test -p {{tool_name_kebab}}-core

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_name
```

### Code Quality

```bash
# Format code
cargo fmt --all

# Check formatting
cargo fmt --check

# Linting
cargo clippy --all-targets

# Security audit
cargo audit

# Check everything
cargo fmt --check && cargo clippy --all-targets && cargo audit
```

### Documentation

```bash
# Generate documentation
cargo doc --no-deps --open

# Run doc tests
cargo test --doc
```

### Extending {{TOOL_NAME}}

**Add a new command**:
1. Add variant to `Commands` enum in cli/main.rs
2. Add handler in match statement
3. Update help text
4. Add tests

**Add a new service method**:
1. Implement in `handlers/service.rs`
2. Add error handling
3. Add tests (test for success and failure)
4. Update core documentation

**Add a new error type**:
1. Add variant to `{{ToolName}}ErrorKind` enum
2. Update Display implementation
3. Add test
4. Use in appropriate places

### Running with Logging

```bash
# Enable debug logging
RUST_LOG=debug {{tool_name_kebab}} list

# Enable trace logging for specific module
RUST_LOG={{tool_name_kebab}}_core=trace {{tool_name_kebab}} list

# Using with API
RUST_LOG=debug cargo run -p {{tool_name_kebab}}-api
```

## Contributing

Contributions are welcome! Please:

1. Read this README completely
2. Check [Architecture](docs/architecture.md) for design
3. Review [QUICKSTART.md](QUICKSTART.md) for setup
4. Follow code quality standards:
   - No unsafe code
   - 100% public API documentation
   - Comprehensive tests (15+ per module)
   - Idiomatic Rust
5. Commit with clear messages
6. Include tests for new features

## License

This tool is part of the Tools ecosystem.

See LICENSE file for details.

## More Information

- **Quick Start**: [QUICKSTART.md](QUICKSTART.md)
- **Architecture**: [docs/architecture.md](docs/architecture.md)
- **Configuration**: [docs/configuration.md](docs/configuration.md)
- **Guidelines**: [/Users/Akasha/Tools/NEW_TOOL_GUIDELINE.md](https://github.com/Akasha/Tools/blob/main/NEW_TOOL_GUIDELINE.md)
- **Main Tools Documentation**: [/Users/Akasha/Tools/README.md](https://github.com/Akasha/Tools)