Sync fork with unmodified upstream v1.22.1

.agents/prompts/outdated-agent-rules.md

@@ -0,0 +1,4 @@
+Review if the agent instructions (`.agents/`, `.claude/`, `.cursor/`) are still up to date and correct.
+
+- Paths might need to be updated if files have been moved.
+- There might be drift (e.g. missing symlinks for rules)

.agent/rules/auto-generated-files.md → .agents/rules/auto-generated-files.md

@@ -1,7 +1,7 @@
 ---
 description: Rules for how to deal with auto-generated files
 globs:
-  - ".codegen/openapi.json"
+  - ".codegen/cli.json"
   - ".gitattributes"
   - "acceptance/**/out*"
   - "acceptance/**/output.txt"
@@ -13,17 +13,14 @@ globs:
   - "cmd/workspace/**/*.go"
   - "internal/genkit/tagging.py"
   - "internal/mocks/**/*.go"
-  - "bundle/direct/dresources/*.generated.yml"
-  - "bundle/docsgen/output/**/*.md"
-  - "bundle/internal/schema/annotations_openapi.yml"
+  - "bundle/direct/dresources/configs/*.generated.yml"
   - "bundle/internal/validation/generated/*.go"
   - "bundle/schema/jsonschema.json"
-  - "bundle/schema/jsonschema_for_docs.json"
   - "python/databricks/bundles/version.py"
   - "python/databricks/bundles/*/__init__.py"
   - "python/databricks/bundles/*/_models/*.py"
 paths:
-  - ".codegen/openapi.json"
+  - ".codegen/cli.json"
   - ".gitattributes"
   - "acceptance/**/out*"
   - "acceptance/**/output.txt"
@@ -35,12 +32,9 @@ paths:
   - "cmd/workspace/**/*.go"
   - "internal/genkit/tagging.py"
   - "internal/mocks/**/*.go"
-  - "bundle/direct/dresources/*.generated.yml"
-  - "bundle/docsgen/output/**/*.md"
-  - "bundle/internal/schema/annotations_openapi.yml"
+  - "bundle/direct/dresources/configs/*.generated.yml"
   - "bundle/internal/validation/generated/*.go"
   - "bundle/schema/jsonschema.json"
-  - "bundle/schema/jsonschema_for_docs.json"
   - "python/databricks/bundles/version.py"
   - "python/databricks/bundles/*/__init__.py"
   - "python/databricks/bundles/*/_models/*.py"
@@ -67,16 +61,14 @@ Files matching this rule's glob pattern are most likely generated artifacts. Aut
 - Everything, in one shot:
   - `./task generate` — aggregator that runs all generators below
 - OpenAPI SDK/CLI command stubs and related generated artifacts:
-  - `./task generate-genkit`
-  - Includes generated `cmd/account/**`, `cmd/workspace/**`, `.gitattributes`, `internal/genkit/tagging.py`.
+  - `./task generate-cligen` — regenerates `cmd/account/**`, `cmd/workspace/**` and `.gitattributes` from the checked-in `.codegen/cli.json`.
+  - `./task generate-clijson` — refreshes `.codegen/cli.json` from the OpenAPI spec via genkit (requires universe repo); also updates `internal/genkit/tagging.py`.
 - Direct engine generated YAML:
   - `./task generate-direct` (or `./task generate-direct-apitypes`, `./task generate-direct-resources`)
 - Bundle schemas:
   - `./task generate-schema`
-  - `./task generate-schema-docs`
-  - This can also refresh `bundle/internal/schema/annotations_openapi.yml` when OpenAPI annotation extraction is enabled.
-- Bundle docs:
-  - `./task generate-docs`
+  - Rewrites `bundle/internal/schema/annotations.yml` in place: upstream docs are sourced from `.codegen/cli.json` at generation time, and the file is synced with the config structure (placeholders added, stale entries dropped).
+  - The docs schema (`jsonschema_for_docs.json`) is not generated on main; it is built and published to the `docgen` branch on release by `.github/workflows/update-schema-docs.yml`.
 - Validation generated code:
   - `./task generate-validation`
 - Mock files:

.agents/rules/changelog.md

@@ -0,0 +1,8 @@
+---
+description: New changelog entries go in .nextchanges/, not CHANGELOG.md
+globs:
+  - "CHANGELOG.md"
+  - ".nextchanges/**"
+---
+
+**RULE: Do not add new release entries to `CHANGELOG.md`.** For a user-visible change, add a fragment file under `.nextchanges/<section>/` (sections: `notable-changes`, `cli`, `air`, `bundles`, `dependency-updates`, `api-changes`). Each PR adds its own file, so entries never conflict. `CHANGELOG.md` is generated automatically from these fragments by the release process — never hand-edit it. See `.nextchanges/README.md`.

.agents/rules/comments.md

@@ -0,0 +1,62 @@
+---
+description: Comment conventions for source files
+globs:
+  - "**/*.go"
+  - "**/*.py"
+  - "**/*.pyi"
+  - "**/*.sh"
+  - "**/*.scala"
+  - "**/*.js"
+  - "**/*.java"
+  - "**/*.sql"
+  - "**/*.r"
+  - "**/*.yml"
+  - "**/*.yaml"
+paths:
+  - "**/*.go"
+  - "**/*.py"
+  - "**/*.pyi"
+  - "**/*.sh"
+  - "**/*.scala"
+  - "**/*.js"
+  - "**/*.java"
+  - "**/*.sql"
+  - "**/*.r"
+  - "**/*.yml"
+  - "**/*.yaml"
+---
+
+# Comment conventions
+
+**RULE: Do not modify or remove existing comments in code you didn't write.** Comments often encode non-obvious context (a bug reference, a workaround, a reason the code is shaped a certain way) that is lost if rewritten. Leave them alone unless the user explicitly asks for a change.
+
+**RULE: Comments should explain "why", not "what".** Reviewers consistently reject comments that merely restate the code.
+
+**RULE: Keep comments concise, and avoid redundant or verbose ones.** Say only what the code cannot, then stop — only add a comment if it complements the code rather than repeating it or its signature. A doc comment gives the caller the contract and any surprising behavior, not a line-by-line re-spec. AI-generated comments trend long and explanatory, so tighten them before committing.
+
+**RULE: When code relies on a non-obvious invariant, workaround, or backend quirk, add a short comment stating the reason.** The inverse of the rule above: noise comments are bad, but missing comments are the single most common thing reviewers catch. Triggers include: API quirks (PATCH-like semantics, no get-by-name, stripped prefixes), fields intentionally included or excluded (output-only, etag, `ForceSendFields`), branches that look dead but are kept as guards, and tests where the expectation isn't obvious from the assertions.
+
+GOOD:
+
+```go
+// The Workspace API strips the "/Workspace" prefix from parent_path on GET,
+// so we re-add it here to match the local configuration.
+parentPath = "/Workspace" + parentPath
+```
+
+BAD:
+
+```go
+parentPath = "/Workspace" + parentPath
+```
+
+**RULE: In Go, document functions with a doc comment that starts with the function name and ends with a period.**
+
+```go
+// SomeFunc does something.
+func SomeFunc() {
+	...
+}
+```
+
+**RULE: When integrating external tools or detecting environment variables, include source reference URLs as comments.** This lets future readers trace where the behavior came from.