syntaxis/shared/templates/documentation/QUICKSTART.md.template

# {{TOOL_NAME}} - Quick Start

Get {{TOOL_NAME}} up and running in 5-10 minutes.

## Installation

### Prerequisites

- **Rust 1.70+** - [Install Rust](https://rustup.rs/)
- **Cargo** - Comes with Rust

### Build and Install

```bash
# Clone or navigate to tool directory
cd ~/Tools/{{tool_name_kebab}}

# Build release binary
cargo build --release

# Install globally (optional)
cargo install --path crates/{{tool_name_kebab}}-cli
```

**Verify installation**:

```bash
{{tool_name_kebab}} --version
# Output: {{tool_name_kebab}} v0.1.0
```

## Configuration

### Quick Setup (Recommended)

```bash
# Create project tools directory
mkdir -p .project

# Copy example configuration
cp examples/config.toml .project/{{tool_name_kebab}}.toml

# That's it! Tool will auto-discover the config
```

### Alternative Locations

Configuration can also go in:
- `.vapora/{{tool_name_kebab}}.toml` (VAPORA projects)
- `.coder/{{tool_name_kebab}}.toml` (Doc tracking)
- `./{{tool_name_kebab}}.toml` (Current directory)

Tool automatically uses the first one it finds.

## First Steps

### 1. Check Help

```bash
{{tool_name_kebab}} --help
```

Shows all available commands and options.

### 2. Create First Item

```bash
{{tool_name_kebab}} create "My First Item" --description "Testing the tool"
```

**Output**:
```
✨ Creating: My First Item
   Description: Testing the tool

Created item with ID: <uuid>
```

### 3. List Items

```bash
{{tool_name_kebab}} list
```

**Output**:
```
📋 {{TOOL_NAME}} Items

ID              | Name            | Created
-------------  | --------------- | ----
<uuid>          | My First Item   | 2024-01-15
```

### 4. View Summary

```bash
{{tool_name_kebab}} summary
```

**Output**:
```
📊 {{TOOL_NAME}} Summary

Total items:  1
Active items: 1
Last updated: 2024-01-15 10:30:00
```

## Common Tasks

### Create Multiple Items

```bash
{{tool_name_kebab}} create "Item 1" --description "First item"
{{tool_name_kebab}} create "Item 2" --description "Second item"
{{tool_name_kebab}} create "Item 3" --description "Third item"
```

### Filter Items

```bash
# Filter by name pattern
{{tool_name_kebab}} list --filter "Item"

# Limit results
{{tool_name_kebab}} list --limit 5
```

### Show Verbose Logging

```bash
# Enable debug logging
{{tool_name_kebab}} -v list

# Shows internal processing and decisions
```

### Check Configuration Location

```bash
# Tool prints which config file it's using
{{tool_name_kebab}} list
# Output includes: "Using config: .project/{{tool_name_kebab}}.toml"
```

## Using with Tools Ecosystem

If you're using the full Tools ecosystem:

```bash
# Automatic setup (installs everything)
nu /Users/Akasha/Tools/scripts/setup-project-tools.nu

# Now {{tool_name_kebab}} is ready to use
{{tool_name_kebab}} list
```

This automatically:
- Creates `.project/` directory
- Sets up configuration
- Symlinks shared resources
- Prepares for integration

## API Server (Optional)

If you need HTTP access:

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

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

**Test with curl**:

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

# Health check
curl http://127.0.0.1:3000/health
```

## Troubleshooting

### Tool Not Found

**Error**: `command not found: {{tool_name_kebab}}`

**Solution**: Ensure you installed globally:

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

# Or run directly:
cargo run -p {{tool_name_kebab}}-cli -- --help
```

### No Configuration Found

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

**Solution**: Create configuration:

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

### Permission Denied

**Error**: `permission denied: {{tool_name_kebab}}`

**Solution**: Make binary executable:

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

### Port Already in Use (API)

**Error**: `bind: Address already in use`

**Solution**: Change port in code or stop other service using port 3000

## Next Steps

### Learn More

- **Full Documentation**: [README.md](README.md)
- **Architecture**: [docs/architecture.md](docs/architecture.md)
- **Configuration Guide**: [docs/configuration.md](docs/configuration.md)
- **All Commands**: `{{tool_name_kebab}} --help`

### Common Workflows

1. **Integrate into project** - Add to .project/
2. **Use with other Tools** - See Tools ecosystem documentation
3. **Extend functionality** - Check Contributing section in README.md
4. **Deploy to production** - See deployment guide (if available)

### Get Help

- Check help text: `{{tool_name_kebab}} --help`
- Read full README.md for examples
- Check docs/ directory for detailed guides
- See [Troubleshooting](#troubleshooting) section above

## What's Next?

### For Users

- Read [README.md](README.md) for complete feature list
- Check [docs/configuration.md](docs/configuration.md) for advanced config
- Look at [examples/config.toml](examples/config.toml) for real examples

### For Developers

- Check architecture in [docs/architecture.md](docs/architecture.md)
- Look at core library in `crates/{{tool_name_kebab}}-core/`
- Run tests: `cargo test --workspace`
- Build documentation: `cargo doc --no-deps --open`

### For Integrators

- Learn about configuration discovery
- Integrate with other Tools via `.project/`
- See Tools ecosystem guidelines: [/Users/Akasha/Tools/NEW_TOOL_GUIDELINE.md](https://github.com/Akasha/Tools)

## Summary

✅ You now have {{TOOL_NAME}} installed and working!

**You can**:
- Create and list items
- View summaries
- Configure the tool
- Use with other Tools ecosystem projects

**Next**: Read [README.md](README.md) for all features and advanced usage.

---

**Questions?** Check [Troubleshooting](#troubleshooting) or read [README.md](README.md) for details.