feat: add hand-authored manifest JSON schema for editor validation

cmd/cascade/main.go

@@ -19,6 +19,7 @@ import (
 	"github.com/stablekernel/cascade/internal/release"
 	"github.com/stablekernel/cascade/internal/reset"
 	"github.com/stablekernel/cascade/internal/rollback"
+	"github.com/stablekernel/cascade/internal/schema"
 	"github.com/stablekernel/cascade/internal/status"
 	versionpkg "github.com/stablekernel/cascade/internal/version"
 )
@@ -76,6 +77,7 @@ change detection, and changelog generation.`,
 	rootCmd.AddCommand(release.NewCommand())
 	rootCmd.AddCommand(reset.NewCommand())
 	rootCmd.AddCommand(rollback.NewCommand())
+	rootCmd.AddCommand(schema.NewCommand())
 	rootCmd.AddCommand(status.NewCommand())
 	rootCmd.AddCommand(versionpkg.NewCommand())
 	rootCmd.AddCommand(newVersionCmd())

docs/src/content/docs/adoption.md

@@ -67,6 +67,8 @@ ci:
 
 cascade manages `state:` and `latest_release:`; the empty skeleton is enough. See the [Manifest Reference](/cascade/configuration/) for every field.
 
+For autocomplete and inline validation while you edit the manifest, register the JSON Schema with your editor. See [Editor support](/cascade/configuration/#editor-support).
+
 ### 3. Provide the callback workflows
 
 Each callback is a reusable workflow with an `on: workflow_call` trigger. cascade passes a fixed set of inputs and reads back any `outputs:` you declare. The exact, full YAML for each lives in the [Callback Contract](/cascade/callback-contract/); the contract below is the summary.

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

@@ -544,6 +544,26 @@ cascade reset --state --push
 
 Deletes all GitHub releases and tags. With `--state`, also clears the state section.
 
+### schema
+
+Print the manifest JSON Schema. Point your editor at it for autocomplete, type checking, and hover docs while authoring `.github/manifest.yaml`. See [Editor support](/cascade/configuration/#editor-support) for registration.
+
+```bash
+# Print the schema to stdout
+cascade schema
+
+# Write the schema to a file
+cascade schema --output manifest.schema.json
+```
+
+#### Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--output`, `-o` | string | stdout | Write the schema to a file instead of stdout |
+
+The same schema is published at `https://stablekernel.github.io/cascade/manifest.schema.json`. `parse-config` remains the authority for semantic and cross-field rules; the schema covers structure, types, enums, and hover docs.
+
 ## Environment Variables
 
 | Variable | Description |

docs/src/content/docs/configuration.md

@@ -29,6 +29,43 @@ ci:
 
 The wrapper key (`ci:` by default) is configurable via `config.manifest_key`. The file path is configurable via `config.manifest_file`.
 
+## Editor support
+
+cascade ships a hand-authored JSON Schema for the manifest. Registering it with your editor gives you autocomplete, type checking, enum hints, and hover documentation while you author `.github/manifest.yaml`. The schema covers structure, types, and enums; `cascade parse-config` remains the authority for semantic and cross-field rules.
+
+The schema is published at:
+
+```
+https://stablekernel.github.io/cascade/manifest.schema.json
+```
+
+You can also print the embedded copy with `cascade schema` (write it to a file with `cascade schema --output manifest.schema.json`).
+
+### YAML language server directive
+
+Add this comment to the top of `.github/manifest.yaml`. The YAML language server (used by VS Code, Neovim, and others) reads it automatically:
+
+```yaml
+# yaml-language-server: $schema=https://stablekernel.github.io/cascade/manifest.schema.json
+ci:
+  config:
+    trunk_branch: main
+```
+
+### VS Code settings
+
+Alternatively, map the schema to your manifest path in `settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://stablekernel.github.io/cascade/manifest.schema.json": ".github/manifest.yaml"
+  }
+}
+```
+
+If your manifest uses a different path or wrapper key, point the mapping at your file. Either registration path works; the directive travels with the file, while the settings mapping is per-workspace.
+
 ## Config Section
 
 ### Top-Level Fields

go.mod

@@ -12,5 +12,7 @@ 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

@@ -6,13 +6,17 @@ github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLf
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
+golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/schema/command.go

@@ -0,0 +1,51 @@
+package schema
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+// NewCommand creates the schema command, which prints the embedded manifest
+// JSON Schema. Editors can use the schema for autocomplete, type checking, and
+// hover documentation while authoring a manifest.
+func NewCommand() *cobra.Command {
+	var output string
+
+	cmd := &cobra.Command{
+		Use:   "schema",
+		Short: "Print the manifest JSON Schema",
+		Long: `Print the JSON Schema for the cascade manifest.
+
+The schema describes the structure, types, and allowed values of a manifest
+file. Point your editor at it for autocomplete, type checking, and hover docs
+while authoring .github/manifest.yaml. cascade parse-config remains the
+authority for semantic and cross-field rules.
+
+Examples:
+  # Print the schema to stdout
+  cascade schema
+
+  # Write the schema to a file
+  cascade schema --output manifest.schema.json`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			data := Bytes()
+			if output != "" {
+				if err := os.WriteFile(output, data, 0o644); err != nil {
+					return fmt.Errorf("writing schema to %q: %w", output, err)
+				}
+				return nil
+			}
+			if _, err := cmd.OutOrStdout().Write(data); err != nil {
+				return fmt.Errorf("writing schema: %w", err)
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVarP(&output, "output", "o", "", "Write the schema to a file instead of stdout")
+
+	return cmd
+}