[skills-sync] Update skills after SuperPlane main @ 9c9164307a0c8edc5b6b2f13cc69e0c398e0947c

[superplanehq-integration]

Opened automatically by SuperPlane (Skills and Docs Sync canvas).

What changed in this push

Commit 9c9164307a0c (PR #4258, fixes issue #3250) changes how SuperPlane handles unknown fields in two places:

1. CLI YAML parsing – A new decoder (pkg/cli/core/decoder.go) is introduced that rejects unknown fields instead of silently ignoring them. This affects canvas YAMLs and any other resource YAMLs parsed by the CLI (canvases, groups, roles, secrets).
2. API server – pkg/public/server.go is updated so that API requests containing unknown JSON/protobuf fields are rejected with an error rather than silently dropped.

Previous behavior: Unknown fields in CLI YAML files or API request bodies were silently ignored, which could mask typos or structural mistakes — particularly problematic when AI/coding agents generate these inputs.

New behavior: Any unknown field in a CLI YAML or API request body causes an explicit error to be returned early. The operation is rejected entirely.

---

Which skills files are likely affected

File	Why
skills/superplane-cli/SKILL.md	Documents how to author and apply canvas/resource YAMLs via the CLI. Must warn that unknown fields are now rejected, not silently ignored.
skills/superplane-canvas/SKILL.md	If this file documents the structure of canvas YAML files, it should note that strict field validation is now enforced.
skills/superplane-api/SKILL.md	If this file documents API request construction, it must note that unknown fields in request bodies now return errors.

Uncertainty note: The exact filenames and directory structure under skills/ are inferred from common conventions. Adjust paths as needed to match the actual repo layout.

---

Concrete edits to make

skills/superplane-cli/SKILL.md

• Add a clearly labeled warning or note (e.g., under a "Common Pitfalls" or "Validation" section) stating:

  Unknown fields in YAML files are now rejected with an error. Previously, unknown fields were silently ignored. If the CLI returns an unexpected error, check that all field names in your YAML exactly match the documented schema — typos and extra fields will cause the command to fail.

• Add an example error scenario, e.g.:

  # BAD: 'naem' is not a valid field — will now produce an error
  naem: my-canvas

  # GOOD: correct field name
  name: my-canvas

• Update any existing guidance that implies unknown fields are harmless or that the CLI will "use what it recognizes." Remove or correct such language.
• Add a note that this behavior is especially relevant when using AI/coding agents to generate YAML, as previously silent mistakes will now surface as explicit errors.

skills/superplane-canvas/SKILL.md (if it exists)

• Add a validation note in any section describing canvas YAML authorship:

  Canvas YAML files are validated strictly. Any field not defined in the canvas schema will cause the CLI to return an error and refuse to apply the file. Validate field names carefully against the schema before running apply or equivalent commands.

• Remove or correct any language suggesting that extra or unrecognized fields are tolerated.

skills/superplane-api/SKILL.md (if it exists)

• Add a note in the request body / payload section:

  API requests that include unknown fields are now rejected. The server returns an error for any request body containing fields not defined in the API schema. Ensure request payloads are constructed strictly from documented fields.

• Update any integration or agent-facing guidance to reflect that field validation is strict at ingestion time.

---

Verification

A human reviewer should confirm the skills still match product behavior by:

1. CLI smoke test – unknown field rejection:

   • Author a canvas YAML (or any resource YAML) that includes a deliberately misspelled or fabricated field (e.g., naem: test).
   • Run the relevant CLI command (e.g., superplane apply -f bad.yaml).
   • Confirm the CLI returns an explicit error referencing the unknown field, and does not silently proceed.

2. CLI smoke test – valid YAML still works:

   • Run the same command with a fully valid YAML.
   • Confirm the command succeeds as before.

3. API smoke test – unknown field rejection:

   • Send an API request (e.g., via curl or a test client) with an extra unknown field in the JSON body.
   • Confirm the server returns a non-2xx error response (not a silent success).

4. API smoke test – valid request still works:

   • Send a valid API request and confirm it succeeds normally.

5. Review skills diff: After edits, do a side-by-side read of each updated SKILL.md against the commit's changed files (pkg/cli/core/decoder.go, pkg/public/server.go) and the PR description to confirm no documented behavior contradicts the new strict-validation mode.

6. Check for agent-specific guidance: Confirm that any sections in the skills files aimed at AI/coding agents explicitly call out the strict field validation, since this change was specifically motivated by agent-generated input being silently wrong.