feat: Add craft init, validate commands and improve onboarding

docs/src/content/docs/configuration.md

@@ -485,6 +485,39 @@ Require a minimum Craft version:
 minVersion: '0.5.0'
 ```
 
+### Smart Defaults
+
+Setting `minVersion` to `2.21.0` or higher enables smart defaults that simplify configuration:
+
+```yaml
+minVersion: '2.21.0'
+```
+
+| Feature             | Default with `minVersion >= 2.21.0` | Default without |
+| ------------------- | ----------------------------------- | --------------- |
+| `changelog.policy`  | `auto`                              | `none`          |
+| `versioning.policy` | `auto` (with `>= 2.14.0`)           | `manual`        |
+
+This means a minimal configuration like this:
+
+```yaml
+minVersion: '2.21.0'
+targets:
+  - name: npm
+  - name: github
+```
+
+Will automatically:
+
+- Generate changelogs from conventional commits
+- Determine version bumps from commit analysis
+- Create `CHANGELOG.md` if it doesn't exist
+
+:::tip[Recommended for New Projects]
+Use `minVersion: '2.21.0'` for new projects to take advantage of smart defaults.
+Run `craft init` to automatically generate this configuration.
+:::
+
 ## Required Files
 
 Ensure specific artifacts exist before publishing:

docs/src/content/docs/getting-started.md

@@ -21,16 +21,59 @@ pnpm add -g @sentry/craft
 npm install -g @sentry/craft
 ```
 
+## Quick Start with `craft init`
+
+The fastest way to get started is using `craft init`, which auto-detects your project type and generates configuration:
+
+```shell
+cd your-project
+craft init
+```
+
+This will:
+
+1. Detect your project type (npm, PyPI, Cargo, etc.)
+2. Generate a `.craft.yml` configuration file
+3. Create GitHub Actions workflows for release automation
+
+Example output:
+
+```
+[info] Detecting project type...
+[info] ✓ Found GitHub repository: your-org/your-repo
+[info] ✓ Detected 2 target(s):
+  - npm
+  - github
+[info] ✓ Detected Node.js project (pnpm)
+
+Proposed .craft.yml:
+────────────────────────────────────────
+minVersion: "2.21.0"
+targets:
+  - name: npm
+  - name: github
+────────────────────────────────────────
+? Create .craft.yml? (Y/n)
+```
+
+After initialization, validate your configuration:
+
+```shell
+craft validate
+```
+
 ## Usage
 
 ```shell
 $ craft -h
 craft <command>
 
 Commands:
-  craft prepare NEW-VERSION  🚢 Prepare a new release branch
+  craft init                 Initialize Craft configuration for a new project
+  craft prepare [NEW-VERSION] 🚢 Prepare a new release branch
                           [aliases: p, prerelease, prepublish, prepare, release]
   craft publish NEW-VERSION  🛫 Publish artifacts         [aliases: pp, publish]
+  craft validate             Validate Craft configuration and workflows
   craft targets              List defined targets as JSON array
   craft config               Print the parsed, processed, and validated Craft
                              config for the current project in pretty-JSON.
@@ -48,17 +91,74 @@ Options:
 
 ## Workflow
 
+### `craft init`: Initialize a New Project
+
+Auto-detect your project type and generate configuration:
+
+```shell
+craft init
+
+Initialize Craft configuration for a new project
+
+Options:
+  --skip-workflows  Skip generating GitHub Actions workflow files
+  --force           Overwrite existing files
+  -h, --help        Show help
+```
+
+The `init` command detects:
+
+- **Package managers**: npm, pnpm, yarn, pip, cargo, etc.
+- **Project files**: package.json, pyproject.toml, Cargo.toml, Dockerfile, etc.
+- **GitHub info**: owner and repo from git remote
+
+Generated files:
+
+- `.craft.yml` - Main configuration
+- `.github/workflows/release.yml` - Release preparation workflow
+- `.github/workflows/changelog-preview.yml` - PR changelog preview
+
+:::note
+Publishing is typically handled via a separate repository that stores secrets securely. See [Publishing Configuration](/configuration#publishing) for details.
+:::
+
+### `craft validate`: Validate Configuration
+
+Check your configuration for errors and best practices:
+
+```shell
+craft validate
+
+Options:
+  --skip-workflows  Skip validating GitHub Actions workflow files
+  -h, --help        Show help
+```
+
+Validates:
+
+- YAML syntax and schema
+- Target names exist
+- No duplicate target IDs
+- Regex patterns are valid
+- Workflow files use recommended patterns
+
 ### `craft prepare`: Preparing a New Release
 
 This command creates a new release branch, checks the changelog entries, runs a version-bumping script, and pushes this branch to GitHub. CI triggered by pushing this branch will build release artifacts and upload them to your artifact provider.
 
 **Version Specification**
 
-The `NEW-VERSION` argument can be specified in three ways (or omitted to use `auto`):
+The `NEW-VERSION` argument can be specified in several ways (or omitted to use `auto`):
+
+1. **Omitted**: Uses `auto` by default (or `versioning.policy` from `.craft.yml` if configured)
+2. **Explicit version** (e.g., `1.2.3`): Release with the specified version
+3. **Bump type** (`major`, `minor`, or `patch`): Automatically increment the latest tag
+4. **Auto** (`auto`): Analyze commits since the last tag and determine bump type from conventional commit patterns
+5. **CalVer** (`calver`): Use calendar-based versioning
 
-1. **Explicit version** (e.g., `1.2.3`): Release with the specified version
-2. **Bump type** (`major`, `minor`, or `patch`): Automatically increment the latest tag
-3. **Auto** (`auto` or omit the argument): Analyze commits since the last tag and determine bump type from conventional commit patterns
+**First Release**
+
+When no git tags exist (first release), Craft defaults to a `minor` bump from `0.0.0` (resulting in `0.1.0`) when using auto-versioning. This ensures a sensible starting point for new projects.
 
 ```shell
 craft prepare [NEW-VERSION]
@@ -67,9 +167,10 @@ craft prepare [NEW-VERSION]
 
 Positionals:
   NEW-VERSION  The new version to release. Can be: a semver string (e.g.,
-               "1.2.3"), a bump type ("major", "minor", or "patch"), or "auto"
-               to determine automatically from conventional commits. When
-               omitted, defaults to "auto".                            [string]
+               "1.2.3"), a bump type ("major", "minor", or "patch"), "auto"
+               to determine automatically from conventional commits, or "calver"
+               for calendar versioning. When omitted, defaults to "auto".
+                                                                        [string]
 
 Options:
   --no-input       Suppresses all user prompts                  [default: false]
@@ -80,6 +181,8 @@ Options:
   --no-changelog   Do not check for changelog entries [boolean] [default: false]
   --publish        Run "publish" right after "release"[boolean] [default: false]
   --remote         The git remote to use when pushing [string] [default: "origin"]
+  --config-from    Load .craft.yml from specified remote branch
+  --calver-offset  Days to go back for CalVer date calculation
   -v, --version    Show version number                                 [boolean]
   -h, --help       Show help                                           [boolean]
 ```
@@ -179,6 +282,7 @@ preview|pre|rc|dev|alpha|beta|unstable|a|b
 ```
 
 Examples:
+
 - `1.0.0-preview`
 - `1.0.0-alpha.0`
 - `1.0.0-beta.1`
@@ -227,10 +331,12 @@ diff --git a/CHANGELOG.md b/CHANGELOG.md
 ```
 
 **What's blocked:**
+
 - Git push (nothing leaves your machine)
 - GitHub API mutations (no releases, uploads, or changes)
 
 **What's allowed:**
+
 - All local operations (in a temporary worktree)
 - Reading from GitHub API (requires `GITHUB_TOKEN`)
 
@@ -264,6 +370,20 @@ export NUGET_API_TOKEN=abcdefgh
 
 ## Integrating Your Project
 
+### Quick Setup (Recommended)
+
+Use `craft init` to automatically generate configuration:
+
+```shell
+cd your-project
+craft init
+craft validate
+```
+
+Then set up required secrets in your GitHub repository and run your first release.
+
+### Manual Setup
+
 1. **Set up a workflow** that builds assets and runs tests. Allow building release branches:
 
    ```yaml
@@ -295,3 +415,34 @@ export NUGET_API_TOKEN=abcdefgh
 5. **Configure environment variables** for your targets.
 
 6. **Run** `craft prepare <version> --publish`!
+
+## First Release
+
+For new projects with no existing releases, Craft provides a streamlined experience:
+
+1. **Initialize**: Run `craft init` to generate configuration
+2. **Validate**: Run `craft validate` to check your setup
+3. **Release**: Run `craft prepare` (version defaults to `0.1.0`)
+
+Example first release workflow:
+
+```shell
+# Initialize (one-time setup)
+craft init
+craft validate
+
+# Set up secrets in GitHub (GH_RELEASE_PAT, NPM_TOKEN, etc.)
+
+# Create your first release
+craft prepare  # Defaults to 0.1.0 for first release
+# Or explicitly: craft prepare 0.1.0
+
+# After CI completes, publish
+craft publish 0.1.0
+```
+
+With smart defaults enabled (`minVersion: "2.21.0"`), Craft will:
+
+- Auto-detect version bumps from commits
+- Automatically generate changelogs
+- Create `CHANGELOG.md` if it doesn't exist

docs/src/content/docs/index.mdx

@@ -21,28 +21,36 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 ## Features
 
 <CardGrid stagger>
-  <Card title="Automated Releases" icon="rocket">
-    Prepare and publish releases with a single command. Craft handles version bumping, changelog management, and artifact publishing.
+  <Card title="Quick Setup" icon="rocket">
+    Run `craft init` to auto-detect your project and generate configuration.
+    Works with npm, PyPI, Cargo, Docker, and more.
   </Card>
   <Card title="Auto Versioning" icon="star">
-    Automatically determine version bumps from conventional commits. Just run `craft prepare auto` and let Craft figure out the rest.
+    Automatically determine version bumps from conventional commits. Just run
+    `craft prepare` and let Craft figure out the rest.
   </Card>
   <Card title="Multiple Targets" icon="list-format">
-    Publish to GitHub, NPM, PyPI, Docker, NuGet, Crates.io, and many more registries from a single configuration.
+    Publish to GitHub, NPM, PyPI, Docker, NuGet, Crates.io, and many more
+    registries from a single configuration.
   </Card>
   <Card title="Changelog Management" icon="document">
-    Automatic changelog generation using conventional commits or manual changelog policies.
+    Automatic changelog generation using conventional commits or manual
+    changelog policies.
   </Card>
   <Card title="CI/CD Integration" icon="setting">
-    Works seamlessly with GitHub Actions and other CI systems. Fetch artifacts and publish them to your targets.
+    Works seamlessly with GitHub Actions and other CI systems. Fetch artifacts
+    and publish them to your targets.
   </Card>
 </CardGrid>
 
 ## Quick Example
 
 ```bash
+# Initialize a new project (one-time setup)
+craft init
+
 # Auto-determine version from conventional commits
-craft prepare auto
+craft prepare
 
 # Or specify a bump type
 craft prepare minor