syntaxis/docs/core/quickstart.md

# Syntaxis - Quick Start Guide

## Building

### Debug Build
```bash
just build
# or
cargo build
```

### Release Build
```bash
just build-release
# or
cargo build --release
```

## Running Tests

Run all tests:
```bash
just test-all
# or
cargo test --workspace
```

Run specific test:
```bash
cargo test --lib phase::tests::test_phase_manager_transition
```

## Using the CLI

You can run the CLI tool with:

```bash
just cli --help
```

Or directly:
```bash
cargo run -p syntaxis-cli -- --help
```

### Available Commands

```bash
# Initialize a project
cargo run -p syntaxis-cli -- init my-project --type rust-web

# Show current phase
cargo run -p syntaxis-cli -- phase current

# Transition to new phase
cargo run -p syntaxis-cli -- phase transition devel

# Show project status
cargo run -p syntaxis-cli -- status
```

## Development Workflow

### Format Code
```bash
just fmt
# or
cargo fmt --all
```

### Check for Issues
```bash
just check-all
# runs: cargo fmt && cargo clippy && cargo check
```

### Run Full Linter
```bash
just lint
# or
cargo clippy --all-targets
```

### View Documentation
```bash
just doc
# Opens generated Rust documentation in browser
```

## Project Structure

```
crates/
├── syntaxis-core/       # Core library with domain types
│   └── src/
│       ├── lib.rs
│       ├── error.rs          # Error handling
│       ├── types.rs          # Core types (ProjectPhase, ToolConfig, etc)
│       ├── phase.rs          # Phase manager
│       ├── tools.rs          # Tool manager
│       ├── config.rs         # Configuration
│       ├── checklist.rs      # Checklist system
│       ├── templates.rs      # Template engine
│       ├── provisioning.rs   # Provisioning integration
│       └── publication.rs    # Publication management
│
├── syntaxis-cli/        # Command-line interface
│   └── src/main.rs      # CLI entry point
│
├── syntaxis-tui/        # TUI dashboard
│   └── src/main.rs      # Dashboard entry point
│
└── syntaxis-vapora/     # VAPORA integration
    └── src/lib.rs
```

## Core Concepts

### ProjectPhase
An enumeration representing the syntaxis phase:
- `Creation` - Project setup
- `Devel` - Active development
- `Update` - Enhancement phase
- `Review` - Quality review
- `Status` - Health monitoring
- `Publish` - Release phase
- `Archive` - Deprecated
- `Mvp` - Minimum viable product
- `Prototype` - Prototype mode

### PhaseManager
Manages phase transitions:
```rust
let mut manager = PhaseManager::new(ProjectPhase::Creation);
manager.transition_to(ProjectPhase::Devel, false)?;
```

### ToolConfig
Configuration for individual tools:
```rust
let mut tool = ToolConfig::new("tracking");
tool.enable();
tool.with_phases(vec![ProjectPhase::Devel, ProjectPhase::Review]);
```

### Checklist
Track progress within a phase:
```rust
let mut checklist = Checklist::new(ProjectPhase::Devel);
checklist.add_item(ChecklistItem::new("setup-ci", "Set up CI/CD"));
checklist.mark_item_complete("setup-ci")?;
```

## Common Tasks

### Check if code compiles
```bash
cargo check --workspace
```

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

### See all available recipes
```bash
just --list
```

### Watch code changes
```bash
cargo watch -x check
```

## Integration with Tools

Enable tools in configuration:

### Documentation Tools
```toml
[tools.docs]
enabled = true
phases = ["devel", "review", "publish"]
```

### Tracking Tools
```toml
[tools.tracking]
enabled = true
phases = ["devel", "update", "review"]
```

### Development System
```toml
[tools.dev_system]
enabled = true
phases = ["devel"]
```

## Troubleshooting

### Build fails with "unresolved import"
Clean and rebuild:
```bash
cargo clean
cargo build
```

### Tests fail
Run with backtrace:
```bash
RUST_BACKTRACE=1 cargo test --lib
```

### Need to format code
```bash
cargo fmt --all
```

## Support

For issues or questions about:
- **Architecture**: See ARCHITECTURE.md
- **Development**: See README.md
- **Project guidelines**: See CLAUDE.md

---

**Happy developing!** 🚀