feat: Add utf8proj init command for new users

- Add `init` subcommand that creates a starter project file
- Generated template includes: project declaration, sample resources,
  sample tasks with dependencies, and a milestone
- Template has helpful comments explaining DSL syntax and next steps
- Sanitizes project name for safe filenames (spaces → underscores)
- Refuses to overwrite existing files
- Add 5 integration tests for init command
- Update README with proper installation instructions (binary first)

Improves onboarding for users discovering utf8proj via YouTube/Reddit.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: alanbld

README.md

@@ -48,6 +48,52 @@
 
 ---
 
+## Installation
+
+### Download Binary (Recommended)
+
+**Linux:**
+```bash
+curl -LO https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.9.1-x86_64-unknown-linux-gnu.tar.gz
+tar xzf utf8proj-v0.9.1-x86_64-unknown-linux-gnu.tar.gz
+sudo mv utf8proj /usr/local/bin/
+```
+
+**macOS (Apple Silicon):**
+```bash
+curl -LO https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.9.1-aarch64-apple-darwin.tar.gz
+tar xzf utf8proj-v0.9.1-aarch64-apple-darwin.tar.gz
+sudo mv utf8proj /usr/local/bin/
+```
+
+**macOS (Intel):**
+```bash
+curl -LO https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.9.1-x86_64-apple-darwin.tar.gz
+tar xzf utf8proj-v0.9.1-x86_64-apple-darwin.tar.gz
+sudo mv utf8proj /usr/local/bin/
+```
+
+**Windows (PowerShell):**
+```powershell
+Invoke-WebRequest -Uri "https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.9.1-x86_64-pc-windows-msvc.zip" -OutFile utf8proj.zip
+Expand-Archive utf8proj.zip -DestinationPath .
+```
+
+### Build from Source (Rust users)
+
+```bash
+cargo install utf8proj-cli
+```
+
+### Verify Installation
+
+```bash
+utf8proj --version
+# utf8proj 0.9.1
+```
+
+---
+
 ## Quick Start (60 seconds)
 
 **1. Create `example.proj`:**
@@ -62,10 +108,9 @@ task build "Build" { effort: 5d, assign: dev, depends: design }
 milestone done "Done" { depends: build }
 ```
 
-**2. Install and run:**
+**2. Run:**
 
 ```bash
-cargo install --path crates/utf8proj-cli
 utf8proj schedule example.proj
 ```
 

crates/utf8proj-cli/src/main.rs

@@ -232,6 +232,17 @@ enum Commands {
         #[command(subcommand)]
         fix_command: FixCommands,
     },
+
+    /// Initialize a new project file with a working example
+    Init {
+        /// Project name (default: "my-project")
+        #[arg(value_name = "NAME", default_value = "my-project")]
+        name: String,
+
+        /// Output directory (default: current directory)
+        #[arg(short, long)]
+        output: Option<std::path::PathBuf>,
+    },
 }
 
 #[derive(Subcommand)]
@@ -350,12 +361,14 @@ fn main() -> Result<()> {
                 in_place,
             } => cmd_fix_container_deps(&file, output.as_deref(), in_place),
         },
+        Some(Commands::Init { name, output }) => cmd_init(&name, output.as_deref()),
         None => {
             println!("utf8proj - Project Scheduling Engine");
             println!();
             println!("Usage: utf8proj <COMMAND>");
             println!();
             println!("Commands:");
+            println!("  init       Initialize a new project file");
             println!("  check      Parse and validate a project file");
             println!("  schedule   Schedule a project and output results");
             println!("  gantt      Generate a Gantt chart (SVG)");
@@ -2022,3 +2035,131 @@ fn cmd_classify(file: &std::path::Path, by: &str) -> Result<()> {
 
     Ok(())
 }
+
+// ============================================================================
+// Init Command
+// ============================================================================
+
+/// Initialize a new project file with a working example
+fn cmd_init(name: &str, output_dir: Option<&std::path::Path>) -> Result<()> {
+    use chrono::Local;
+
+    // Determine output directory
+    let dir = output_dir
+        .map(std::path::PathBuf::from)
+        .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| ".".into()));
+
+    // Sanitize project name for filename (replace spaces/special chars with underscores)
+    let filename: String = name
+        .chars()
+        .map(|c| if c.is_alphanumeric() || c == '-' || c == '_' { c } else { '_' })
+        .collect();
+    let filepath = dir.join(format!("{}.proj", filename));
+
+    // Check if file already exists
+    if filepath.exists() {
+        anyhow::bail!(
+            "File '{}' already exists. Use a different name or delete the existing file.",
+            filepath.display()
+        );
+    }
+
+    // Get today's date for the project start
+    let today = Local::now().format("%Y-%m-%d");
+
+    // Generate project template
+    let template = format!(
+        r#"# {name}
+#
+# This is a utf8proj project file. Edit this file to define your project schedule.
+#
+# Quick reference:
+#   - Tasks have duration (calendar time) or effort (work time)
+#   - Dependencies: FS (finish-to-start, default), SS, FF, SF
+#   - Lag: +2d (delay), -1d (lead)
+#   - Resources: assign tasks to named resources
+#
+# Commands:
+#   utf8proj schedule {filename}.proj       # Show schedule
+#   utf8proj gantt {filename}.proj -o gantt.html -f html  # Visual Gantt chart
+#   utf8proj check {filename}.proj          # Validate only
+#
+# Docs: https://github.com/alanbld/utf8proj
+
+project "{name}" {{
+    start: {today}
+}}
+
+# Define your resources
+resource dev "Developer" {{
+    rate: 800/day
+}}
+
+resource design "Designer" {{
+    rate: 600/day
+}}
+
+# Define your tasks
+# Tip: Tasks with 'depends:' create a schedule chain
+
+task planning "Planning" {{
+    duration: 3d
+    assign: dev
+}}
+
+task design "Design Phase" {{
+    duration: 5d
+    depends: planning
+    assign: design
+}}
+
+task development "Development" {{
+    duration: 10d
+    depends: design
+    assign: dev
+}}
+
+task testing "Testing" {{
+    duration: 3d
+    depends: development
+    assign: dev
+}}
+
+milestone launch "Project Launch" {{
+    depends: testing
+}}
+
+# Next steps:
+# 1. Edit the tasks above to match your project
+# 2. Run: utf8proj schedule {filename}.proj
+# 3. Generate Gantt: utf8proj gantt {filename}.proj -o gantt.html -f html
+"#,
+        name = name,
+        filename = filename,
+        today = today
+    );
+
+    // Create parent directory if needed
+    if let Some(parent) = filepath.parent() {
+        if !parent.exists() {
+            fs::create_dir_all(parent)
+                .with_context(|| format!("Failed to create directory '{}'", parent.display()))?;
+        }
+    }
+
+    // Write the file
+    fs::write(&filepath, &template)
+        .with_context(|| format!("Failed to write '{}'", filepath.display()))?;
+
+    println!("Created: {}", filepath.display());
+    println!();
+    println!("Next steps:");
+    println!("  1. Edit {} to define your project", filepath.display());
+    println!("  2. Run: utf8proj schedule {}", filepath.display());
+    println!(
+        "  3. Generate Gantt: utf8proj gantt {} -o gantt.html -f html",
+        filepath.display()
+    );
+
+    Ok(())
+}

crates/utf8proj-cli/tests/init_command.rs

@@ -0,0 +1,131 @@
+//! Tests for the `utf8proj init` command
+
+use std::fs;
+use std::path::PathBuf;
+use std::process::Command;
+use tempfile::tempdir;
+
+fn utf8proj_binary() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .join("target/debug/utf8proj")
+}
+
+#[test]
+fn init_creates_project_file() {
+    let dir = tempdir().unwrap();
+    let expected_file = dir.path().join("test-project.proj");
+
+    let output = Command::new(utf8proj_binary())
+        .args(["init", "test-project", "-o"])
+        .arg(dir.path())
+        .output()
+        .expect("Failed to execute command");
+
+    assert!(output.status.success(), "Command should succeed");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("Created:"), "Should show 'Created:'");
+    assert!(
+        stdout.contains("test-project.proj"),
+        "Should show filename"
+    );
+    assert!(expected_file.exists(), "File should be created");
+
+    // Verify content has expected structure
+    let content = fs::read_to_string(&expected_file).unwrap();
+    assert!(
+        content.contains("project \"test-project\""),
+        "Should have project declaration"
+    );
+    assert!(
+        content.contains("task planning"),
+        "Should have planning task"
+    );
+    assert!(content.contains("depends:"), "Should have dependencies");
+}
+
+#[test]
+fn init_refuses_overwrite() {
+    let dir = tempdir().unwrap();
+    let existing_file = dir.path().join("existing.proj");
+
+    // Create existing file
+    fs::write(&existing_file, "# existing").unwrap();
+
+    let output = Command::new(utf8proj_binary())
+        .args(["init", "existing", "-o"])
+        .arg(dir.path())
+        .output()
+        .expect("Failed to execute command");
+
+    assert!(!output.status.success(), "Command should fail");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("already exists"),
+        "Should say file already exists"
+    );
+}
+
+#[test]
+fn init_sanitizes_filename() {
+    let dir = tempdir().unwrap();
+
+    let output = Command::new(utf8proj_binary())
+        .args(["init", "My Cool Project!", "-o"])
+        .arg(dir.path())
+        .output()
+        .expect("Failed to execute command");
+
+    assert!(output.status.success(), "Command should succeed");
+
+    // Special chars replaced with underscores
+    assert!(
+        dir.path().join("My_Cool_Project_.proj").exists(),
+        "Filename should be sanitized"
+    );
+}
+
+#[test]
+fn init_generated_file_schedules() {
+    let dir = tempdir().unwrap();
+    let project_file = dir.path().join("demo.proj");
+
+    // Create project
+    let output = Command::new(utf8proj_binary())
+        .args(["init", "demo", "-o"])
+        .arg(dir.path())
+        .output()
+        .expect("Failed to execute command");
+    assert!(output.status.success(), "init should succeed");
+
+    // Schedule it
+    let output = Command::new(utf8proj_binary())
+        .args(["schedule"])
+        .arg(&project_file)
+        .output()
+        .expect("Failed to execute schedule");
+
+    assert!(output.status.success(), "schedule should succeed");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("Critical Path:"), "Should show critical path");
+}
+
+#[test]
+fn init_default_name() {
+    let dir = tempdir().unwrap();
+
+    let output = Command::new(utf8proj_binary())
+        .args(["init", "-o"])
+        .arg(dir.path())
+        .output()
+        .expect("Failed to execute command");
+
+    assert!(output.status.success(), "Command should succeed");
+    assert!(
+        dir.path().join("my-project.proj").exists(),
+        "Default name should be my-project"
+    );
+}