feat: add cascade init command to scaffold a project

cmd/cascade/main.go

@@ -13,6 +13,7 @@ import (
 	"github.com/stablekernel/cascade/internal/generate"
 	"github.com/stablekernel/cascade/internal/globals"
 	"github.com/stablekernel/cascade/internal/hotfix"
+	initcmd "github.com/stablekernel/cascade/internal/initcmd"
 	"github.com/stablekernel/cascade/internal/log"
 	"github.com/stablekernel/cascade/internal/orchestrate"
 	"github.com/stablekernel/cascade/internal/promote"
@@ -72,6 +73,7 @@ change detection, and changelog generation.`,
 	rootCmd.AddCommand(external.NewCommand())
 	rootCmd.AddCommand(generate.NewCommand())
 	rootCmd.AddCommand(hotfix.NewCommand())
+	rootCmd.AddCommand(initcmd.NewCommand())
 	rootCmd.AddCommand(orchestrate.NewCommand())
 	rootCmd.AddCommand(promote.NewCommand())
 	rootCmd.AddCommand(release.NewCommand())

docs/src/content/docs/adoption.md

@@ -22,6 +22,21 @@ The flow in one line: you write a manifest plus callback workflows, run `cascade
 
 ## Build a pipeline from scratch
 
+**Fast path:** `cascade init` does the first three steps below for you. It
+scaffolds the manifest and the callback stubs, verifies them through the real
+generator, and writes them into your repository:
+
+```bash
+cascade init --topology two-env          # dev, prod
+cascade init --envs staging,production   # your own ordered names
+```
+
+Pick a preset with `--topology` (`no-env`, `two-env`, `three-env`, `four-env`)
+or supply your own ordered list with `--envs`. Then jump to step 4 to generate
+and commit. The walkthrough below explains each piece `init` produces, so you
+understand what you are filling in. See the [CLI Reference](/cascade/cli-reference/#init)
+for every flag.
+
 ### 1. Choose your environments
 
 Environments are **positional**, not named by meaning. cascade attaches no semantics to a name like `prod`; it reads the list by position:

docs/src/content/docs/cli-reference.md

@@ -160,6 +160,37 @@ Breaking changes detected via:
 - `!` suffix: `feat!: breaking change`
 - Footer: `BREAKING CHANGE: description` (case-sensitive, line start)
 
+### init
+
+Scaffold a starter manifest and matching callback workflow stubs, verified through the real generator before anything is written.
+
+```bash
+# Two-environment pipeline (dev, prod) in the current directory
+cascade init --topology two-env
+
+# Custom ordered environments; the last is the release stage
+cascade init --envs staging,production --name my-service
+
+# Preview without writing
+cascade init --topology three-env --dry-run
+```
+
+`init` renders `.github/manifest.yaml` plus build (and, when environments are set, deploy) stubs under `.github/workflows`, runs the manifest through parse, validation, and generation, and only then writes the files. The manifest carries a `$schema` directive for editor autocomplete and validation. After running it, fill in the stub callbacks, commit, and run `cascade generate-workflow`.
+
+#### Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--topology` | string | `two-env` | Preset shape: one of `no-env`, `two-env`, `three-env`, `four-env` |
+| `--envs` | string | - | Comma-separated ordered environment names; the last is the release stage (overrides `--topology`) |
+| `--name` | string | dir base name | Project name woven into the stubs |
+| `--dir` | string | `.` | Target directory to scaffold into |
+| `--cli-version` | string | pinned release | cascade CLI version pinned in the manifest |
+| `--force`, `-f` | bool | false | Overwrite existing files |
+| `--dry-run` | bool | false | Print what would be written without writing anything |
+
+Environment names are positional, not semantic: the last name is the release stage. An empty list (`--topology no-env`) produces a release-only project with no deploy stub. If any target file already exists and `--force` is not set, `init` aborts and lists the conflicts, writing nothing.
+
 ### generate-workflow
 
 Generate the orchestrate and promote workflows from the manifest.

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

@@ -40,6 +40,34 @@ If you need to invoke it manually:
 
 The setup action downloads the release archive (`tar.gz`) from GoReleaser and installs the `cascade` binary on `PATH`.
 
+## Fast path: scaffold with `cascade init`
+
+If you want a working configuration in one step, run `cascade init`. It renders
+the manifest and the callback workflow stubs for you, verifies them through the
+real generator, and writes them into your repository:
+
+```bash
+# Two-environment pipeline (dev, prod) in the current directory
+cascade init --topology two-env
+
+# Or choose your own ordered environments; the last is the release stage
+cascade init --envs staging,production --name my-service
+
+# Preview without writing anything
+cascade init --topology two-env --dry-run
+```
+
+This produces `.github/manifest.yaml` plus build and deploy stubs under
+`.github/workflows`. The manifest already carries a `$schema` directive, so your
+editor gives you autocomplete and validation while you fill in the stubs. If a
+target file already exists, `init` aborts and lists the conflicts unless you
+pass `--force`.
+
+Once scaffolded, skip ahead to [Step 3](#step-3-create-callback-workflows) to
+fill in the callbacks, then generate the orchestration workflows. The manual
+walkthrough below covers the same files step by step if you would rather build
+them yourself.
+
 ## Step 2: Create the manifest
 
 Create `.github/manifest.yaml` in your repository:

go.mod

@@ -3,6 +3,7 @@ module github.com/stablekernel/cascade
 go 1.23
 
 require (
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1
 	gopkg.in/yaml.v3 v3.0.1
@@ -12,7 +13,6 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
 	golang.org/x/text v0.14.0 // indirect
 )

go.sum

@@ -1,6 +1,8 @@
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
+github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=