From 61d8408342b9258a87977e9b931494387e40e768 Mon Sep 17 00:00:00 2001
From: Nicolas Brousse <nicolas@brousse.info>
Date: Fri, 14 Aug 2026 18:11:08 -0700
Subject: [PATCH] docs: add Editor Integration guide + promote
 .yaml-workflow.yaml convention

Adds a discoverable docs-site page (guide/editor-integration.md, in the nav)
covering JSON Schema validation/autocomplete: the yaml-language-server modeline,
VS Code + JetBrains setup, check-jsonschema, and the SchemaStore submission.

Promotes a distinctive .yaml-workflow.yaml / .yml file-naming convention so the
SchemaStore entry (SchemaStore/schemastore#6213) enables zero-config editor
auto-detection without false positives. Updates schema/README.md to reflect the
submitted status and cross-link the guide.
---
 docs/guide/editor-integration.md | 112 +++++++++++++++++++++++++++++++
 mkdocs.yml                       |   1 +
 schema/README.md                 |  24 +++++--
 3 files changed, 131 insertions(+), 6 deletions(-)
 create mode 100644 docs/guide/editor-integration.md

diff --git a/docs/guide/editor-integration.md b/docs/guide/editor-integration.md
new file mode 100644
index 0000000..31035ee
--- /dev/null
+++ b/docs/guide/editor-integration.md
@@ -0,0 +1,112 @@
+# Editor Integration
+
+yaml-workflow ships a [JSON Schema](https://json-schema.org/) (draft-07) that
+describes the workflow file format. Point your editor at it to get **inline
+validation and autocomplete** for `name`, `params`, `settings`, `imports`,
+`steps`, `flows`, task types, and their inputs.
+
+The schema lives at
+[`schema/workflow-schema.json`](https://github.com/orieg/yaml-workflow/blob/main/schema/workflow-schema.json)
+and is served over HTTPS at its canonical `$id`:
+
+```
+https://raw.githubusercontent.com/orieg/yaml-workflow/main/schema/workflow-schema.json
+```
+
+There are three ways to wire it up, from most to least portable.
+
+## 1. Per-file modeline (works everywhere)
+
+Add a `yaml-language-server` modeline as the first line of any workflow file.
+This works in VS Code (Red Hat YAML extension), Neovim (via `yaml-language-server`),
+and any editor that speaks the YAML Language Server — no settings file required,
+and it works regardless of how the file is named:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/orieg/yaml-workflow/main/schema/workflow-schema.json
+name: My Workflow
+steps:
+  - name: hello
+    task: shell
+    inputs:
+      command: echo "hi"
+```
+
+Prefer a local copy (e.g. offline, or to pin a version)? Point at a schema file
+on disk with a path relative to the workflow file:
+
+```yaml
+# yaml-language-server: $schema=./schema/workflow-schema.json
+```
+
+The schema is also bundled inside the installed package (at
+`yaml_workflow/schema/workflow-schema.json`) for programmatic access via
+`importlib.resources`.
+
+## 2. VS Code workspace setting
+
+Install the [Red Hat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
+and map the schema to your workflow files in `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/orieg/yaml-workflow/main/schema/workflow-schema.json": [
+      "**/*.yaml-workflow.yaml",
+      "workflows/**/*.yaml"
+    ]
+  }
+}
+```
+
+Adjust the globs to match wherever your workflow files live.
+
+## 3. JetBrains IDEs (IntelliJ, PyCharm)
+
+1. Open **Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings**.
+2. Click **+** and set **Schema file or URL** to the URL above (or a local path).
+3. Set **Schema version** to `JSON Schema version 7`.
+4. Add a file path pattern such as `*.yaml-workflow.yaml` or `workflows/*.yaml`.
+
+## Recommended file-naming convention
+
+For **zero-config** autocomplete via [SchemaStore](https://www.schemastore.org/)
+(see below), name your workflow files with a `.yaml-workflow.yaml` (or
+`.yaml-workflow.yml`) suffix:
+
+```
+deploy.yaml-workflow.yaml
+etl/nightly.yaml-workflow.yaml
+```
+
+This distinctive suffix lets editors auto-detect the schema without any
+per-project configuration, and avoids clashing with the many other tools that
+use generically-named `*.yaml` files. Any filename still works with the
+modeline or the explicit mappings above — the suffix is only needed for
+SchemaStore auto-detection.
+
+## SchemaStore auto-detection
+
+The schema is [submitted to SchemaStore](https://github.com/SchemaStore/schemastore/pull/6213).
+Once merged, editors that consume the SchemaStore catalog — VS Code with the
+Red Hat YAML extension, JetBrains IDEs, and others — will automatically validate
+and autocomplete files matching `*.yaml-workflow.yaml` / `*.yaml-workflow.yml`
+with no manual configuration.
+
+## Command-line validation
+
+Validate workflow files in CI or a pre-commit hook with any JSON Schema
+validator, for example [`check-jsonschema`](https://check-jsonschema.readthedocs.io/):
+
+```bash
+check-jsonschema \
+  --schemafile https://raw.githubusercontent.com/orieg/yaml-workflow/main/schema/workflow-schema.json \
+  workflows/my_workflow.yaml
+```
+
+You can also validate with the built-in command, which uses the engine's own
+validator:
+
+```bash
+yaml-workflow validate workflows/my_workflow.yaml
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 69e7828..45fc285 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -97,6 +97,7 @@ nav:
       - Core Concepts: guide/concepts.md
       - Workflow Structure: workflow-structure.md
       - Configuration: guide/configuration.md
+      - Editor Integration: guide/editor-integration.md
       - CLI Usage: cli.md
       - Templating: guide/templating.md
       - State Management: state.md
diff --git a/schema/README.md b/schema/README.md
index 1c1ac78..3767ac1 100644
--- a/schema/README.md
+++ b/schema/README.md
@@ -57,10 +57,22 @@ check-jsonschema \
   workflows/my_workflow.yaml
 ```
 
-## SchemaStore auto-detection (planned)
+## Recommended file naming
 
-Submitting this schema to [SchemaStore](https://www.schemastore.org/) is on the
-roadmap. Once accepted, editors that consume the SchemaStore catalog (VS Code
-with the Red Hat YAML extension, JetBrains IDEs, etc.) will validate and
-autocomplete matching workflow files with no manual configuration. Until then,
-use one of the setup methods above.
+For zero-config auto-detection via SchemaStore (below), name workflow files with
+a distinctive `.yaml-workflow.yaml` (or `.yaml-workflow.yml`) suffix, e.g.
+`deploy.yaml-workflow.yaml`. Any filename still works with the modeline or the
+explicit editor mappings above — the suffix is only needed for SchemaStore
+auto-detection, and it avoids clashing with the many other tools that use
+generically-named `*.yaml` files.
+
+## SchemaStore auto-detection
+
+This schema is [submitted to SchemaStore](https://github.com/SchemaStore/schemastore/pull/6213).
+Once merged, editors that consume the SchemaStore catalog (VS Code with the Red
+Hat YAML extension, JetBrains IDEs, etc.) will validate and autocomplete files
+matching `*.yaml-workflow.yaml` / `*.yaml-workflow.yml` with no manual
+configuration.
+
+See the [Editor Integration guide](https://orieg.github.io/yaml-workflow/guide/editor-integration/)
+for full setup instructions.