Feature branch major release 8.0.0 main sync july 23

.agents/WORKFLOWS.md

@@ -9,7 +9,7 @@ specific one.
 1.  **Source of Truth:** `magic-modules` contains YAML schema definitions in `mmv1/` and templates. Code is generated into downstream providers.
 2.  **Use Skills:** Discover and leverage `.agents/skills/` to perform complex tasks.
 3.  **Verify before a PR:** generate, build, and run the tests relevant to the change. A task is not done because it compiles.
-4.  **Never weaken the baseline:** no disabling or skipping tests, and no test-dodging behavior flags (`ignore_read`, `default_from_api`, `ImportStateVerifyIgnore`) without an adjacent comment justifying the API behavior that requires them.
+4.  **Never weaken baseline test coverage:** no disabling or skipping tests, and no test-dodging behavior flags (`ignore_read`, `ImportStateVerifyIgnore`) without an adjacent comment justifying the API behavior that requires them.
 5.  **PR descriptions are brief:** what changed and why, in a few sentences.
 
 ## Available Workflows:

.agents/knowledge/README.md

@@ -0,0 +1,44 @@
+# Agent knowledge base
+
+The **funnel to the knowledge an agent needs**: [`index.md`](index.md) routes to the right source for a
+given decision. Agents read the index at decision points and open only what the task needs — never the
+whole base (loading everything degrades reasoning and wastes context).
+
+Most knowledge already lives in the **contributor documentation** (`docs/content/`), and that stays the
+single source of truth for everything it covers — the index points there. **Agent-only entries** exist in
+this directory only for knowledge that has no home in the docs: judgment rules that were never written
+down, pitfall catalogs, and (later) lessons proposed by agents from completed tasks. If something is
+covered by the contributor docs but covered badly, the fix is improving the docs — not writing a copy here.
+
+Planned entries: [`BACKLOG.md`](BACKLOG.md).
+
+## Entry format
+
+One Markdown file, one topic, ≤120 lines, YAML frontmatter:
+
+```yaml
+---
+name: enums-vs-strings              # kebab-case, unique, matches filename
+description: Model an API enum as Enum (strict) or String (forward-compatible).  # the index line; <=140 chars
+topics: [field]                     # index section(s) that list it
+task_types: [field-add, new-resource]
+source: docs/content/best-practices/validation.md   # provenance: doc, PR, or "authored"
+status: certified                   # certified (human-reviewed) | draft (proposed, unreviewed)
+last_verified: 2026-07-09
+---
+```
+
+Body rules: **rule + the why**, never bare imperatives; a real example per rule; a "do NOT use for" line
+where misuse is likely; reference the contributor docs rather than duplicating them.
+
+## Curation rules
+
+- **Nothing enters unreviewed.** Entries land via PR like code, **one entry at a time** — each one codifies
+  team judgment and deserves a real review conversation. Agent-proposed entries ship as `status: draft` in
+  the task PR that motivated them; a human review flips them to `certified`.
+- **Never bulk-rewrite.** Edit entry by entry. Do not have a model re-summarize or reorganize the base
+  wholesale — that is the documented failure mode (drift and self-contradiction).
+- **Contradictions are quarantined.** A proposed entry that contradicts an existing one is not merged; a
+  human adjudicates: update or retire the old entry, or discard the proposal.
+- **Keep the index true.** Index lines come from entry frontmatter (name + description). Adding or changing
+  an entry updates the index in the same commit.

.agents/knowledge/__BACKLOG.md

@@ -0,0 +1,32 @@
+# Knowledge backlog
+
+Tracks known work for growing the agent knowledge base. This document is not intended for agents themselves.
+
+## Not in the docs
+
+- **casing-and-pluralization** — how API names map to Terraform names; when `api_name` is required.
+- **raw-config-access** — when to use `d.GetRawConfig()` / `GetRawPlan()` / `GetRawState()` instead of
+  `Get`/`GetOk`, which conflate "unset in config" with "set to the zero value" (false/0/""); the raw cty
+  values distinguish null from zero for detecting whether a user actually set a field.
+
+## Overlaps the docs (entry would add the judgment layer)
+
+- **permadiff-decision-path** — choosing between `output`, `default_from_api`, diff suppression, or a real
+  fix; mechanics are in `docs/content/develop/diffs.md`.
+- **data-source-idioms** — pitfalls beyond the procedure in `docs/content/develop/add-handwritten-datasource.md`.
+- **test-adequacy-traps** — cases `docs/content/test/test.md` doesn't cover (identical-config update steps,
+  missing import-and-recheck).
+
+## Mostly covered by the docs (revisit only if agents misread them)
+
+- **immutability-nuances** — `docs/content/reference/field.md`, `docs/content/best-practices/immutable-fields.md`.
+- **sensitive-and-write-only** — `docs/content/reference/field.md`.
+
+## Lives elsewhere
+
+- **failure-troubleshooting-catalog** — `.agents/skills/operations/troubleshooting_reference.md`; migrates
+  here if it outgrows the skill.
+
+## Other future work
+
+- **PR mining** — mine historical PRs to discover new entries. These could be recurring review catches and per-service quirks that were only ever captured in the PR reviews themselves.

.agents/knowledge/field/enums-vs-strings.md

@@ -0,0 +1,37 @@
+---
+name: enums-vs-strings
+description: Model an API enum as Enum (strict, plan-time) or String (forward-compatible) - the deliberate trade-off.
+topics: [field]
+task_types: [field-add, new-resource]
+source: docs/content/best-practices/validation.md + the schema-review skill's original trade-off note
+status: draft
+last_verified: 2026-07-09
+---
+
+# Enum vs. String
+
+**The trade-off (decide deliberately, per field):**
+- **`Enum`** when the value set is exhaustive for a clearly-defined domain and new values are extremely
+  unlikely. Buys strict plan-time validation — users fail fast instead of mid-apply.
+- **`String`** (with allowed values named in the description and a link to API docs) when the API is
+  likely to add values. **Why:** an Enum's value list lives in the provider; when the API adds a value,
+  every user needs a provider upgrade before they can use it — and imports of resources using the new
+  value break. A String stays forward-compatible.
+
+```yaml
+- name: 'severity'
+  type: Enum
+  enum_values:
+    - 'LOW'
+    - 'MEDIUM'
+    - 'HIGH'
+```
+
+**Rules for Enum:**
+- Omit the `FIELD_NAME_UNSPECIFIED` value from `enum_values` — it is the proto convention's first enum
+  value, representing 0/unset, not a real choice.
+- Enums validate against the list automatically; a custom `validation` **overrides** that default — if you
+  add one, it must re-verify the enum values itself.
+
+**Rule for String-instead-of-enum:** list the allowed values in the field description with a link to the
+API docs — otherwise users only discover an invalid value when the API rejects it mid-apply.

.agents/knowledge/index.md

@@ -0,0 +1,56 @@
+# Knowledge index
+
+Read this index at decision points; open only the source the task needs. Format and curation rules:
+[README.md](README.md).
+
+## Contributor documentation (`docs/content/`)
+
+**Reference (what the schema properties mean):**
+
+- Field properties (`output`, `immutable`, defaults, `sensitive`, validation, enums, arrays, `api_name`, conflicts) — `docs/content/reference/field.md`
+- Resource-level properties (URLs, timeouts, async, custom code hooks) — `docs/content/reference/resource.md`
+- Resource metadata — `docs/content/reference/metadata.md`
+- Samples format — `docs/content/reference/sample.md`
+- Update test expectations — `docs/content/reference/update-test-changes.md`
+- Make commands — `docs/content/reference/make-commands.md`
+
+**Procedures (how to do a task):**
+
+- Add or change a field — `docs/content/develop/add-fields.md`
+- Add a resource — `docs/content/develop/add-resource.md`
+- Add a handwritten data source — `docs/content/develop/add-handwritten-datasource.md`
+- Add IAM support — `docs/content/develop/add-iam-support.md`
+- Custom code (expanders, flatteners, hooks) — `docs/content/develop/custom-code.md`
+- Fix diffs and permadiffs — `docs/content/develop/diffs.md`
+- Client-side fields — `docs/content/develop/client-side-fields.md`
+- Promote beta → GA — `docs/content/develop/promote-to-ga.md`
+- Generate the providers / set up the environment — `docs/content/develop/generate-providers.md`, `docs/content/develop/set-up-dev-environment.md`
+
+**Testing:**
+
+- Write acceptance tests (create, update, import) — `docs/content/test/test.md`
+- Run tests — `docs/content/test/run-tests.md`
+
+**Contributing (PRs, review, release notes):**
+
+- Contribution process end to end — `docs/content/contribution-process.md`
+- Create a PR — `docs/content/code-review/create-pr.md`
+- Write release notes — `docs/content/code-review/release-notes.md`
+- Review a PR — `docs/content/code-review/review-pr.md`
+
+**Documentation:**
+
+- Add resource documentation — `docs/content/document/add-documentation.md`
+- Handwritten docs style guide — `docs/content/document/handwritten-docs-style-guide.md`
+
+**Best practices (judgment calls with team positions):**
+
+- Immutable fields / ForceNew — `docs/content/best-practices/immutable-fields.md`
+- Deletion policy — `docs/content/best-practices/deletion-policy.md`
+- Labels and annotations — `docs/content/best-practices/labels-and-annotations.md`
+- Client-side validation — `docs/content/best-practices/validation.md`
+- Common resource patterns (singletons) — `docs/content/best-practices/common-resource-patterns.md`
+
+## Agent-only entries
+
+- **enums-vs-strings** — Model an API enum as Enum (strict, plan-time) or String (forward-compatible): the deliberate trade-off. — [field/enums-vs-strings.md](field/enums-vs-strings.md)

.agents/rules/general.md

@@ -0,0 +1,10 @@
+---
+trigger: always_on
+description: Mandatory starting action to read the knowledge index at the beginning of each session.
+---
+
+# General Rules
+
+## 1. Mandatory Starting Action
+- **Rule:** At the start of any session or conversation, you MUST first open and read the Knowledge Index file ([.agents/knowledge/index.md](.agents/knowledge/index.md)) before taking any other action or starting any research/implementation.
+- **Purpose:** To check for relevant patterns, guides, or workspace-specific instructions.

.agents/skills/operations/create-pr/SKILL.md

@@ -79,7 +79,10 @@ git push -u "$FORK_REMOTE" "$BRANCH"
 Every PR must contain at least one release note block in the PR body.
 
 Refer to the official guide for detailed release note rules, categories, and examples:
-* [docs/content/code-review/release-notes.md](../../../docs/content/code-review/release-notes.md)
+* [docs/content/code-review/release-notes.md](../../../../docs/content/code-review/release-notes.md)
+
+> [!IMPORTANT]
+> **Note to AI Agents:** View `docs/content/code-review/release-notes.md` from the repository root to determine the correct release note type (e.g., `enhancement`, `bug`, `none`, `new-resource`, `deprecation`, etc.) and follow the end-user impact guidelines.
 
 #### Release Note Block Format
 ```markdown
@@ -88,8 +91,6 @@ CONTENT
 ```
 ```
 
-Common types include `new-resource`, `new-datasource`, `new-list-resource`, `enhancement`, `bug`, `deprecation`, `breaking-change`, `note`, and `none`.
-
 #### Sample PR Body Content
 ```markdown
 Summary of what changed and why in a few concise sentences.

.agents/skills/utils/schema-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: schema-review
-description: "Stub skill for reviewing Magic Modules schemas. Currently covers Enum vs. String trade-offs."
+description: "Skill for reviewing Magic Modules schemas. Currently covers the Enum vs. String decision via the knowledge base."
 ---
 
 # `schema-review`
@@ -14,17 +14,11 @@ description: "Stub skill for reviewing Magic Modules schemas. Currently covers E
 ## Execution Steps
 
 ### 1. Enum vs. String Trade-off
-When adding a field that is defined as an Enum in the API, you must decide between `Enum` and `String` in Magic Modules.
-
-#### The Trade-off:
-*   **Prefer `Enum`** when you want strict, plan-time validation of values to fail fast.
-*   **Prefer `String`** (with allowed values documented) when the API is dynamic or likely to add values. This prevents Terraform from crashing with a validation error for users when the API updates *before* the provider catches up.
+When adding a field that is defined as an Enum in the API, you must decide between `Enum` and `String` in Magic Modules. Read the knowledge entry [.agents/knowledge/field/enums-vs-strings.md](../../../knowledge/field/enums-vs-strings.md) and apply its trade-off.
 
 > [!NOTE]
-> This skill is a **stub** and will be expanded over time with more schema review checklist items (such as `api_name` overrides, array flattening, output-only fields, etc.).
+> This skill will be expanded over time with more schema review checklist items. The judgment content lives in [.agents/knowledge/](../../../knowledge/index.md) — this skill references it and does not hold its own copy.
 
 ### 2. Verification & Handoff
-Instructions on how the agent should verify the command succeeded, and what workflow or rule it should return to next.
 
-* Proceed with your field addition or PR review based on this stylistic choice.
-* Reference the `modernization_roadmap.md` for upcoming expansions to this checklist.
+* Proceed with your field addition or PR review based on the decision.

.agents/skills/workflows/add_list_resource/SKILL.md

@@ -9,6 +9,8 @@ description: "Opt resource into MMv1 list-resource generation by setting `genera
 
 This workflow produces a single PR scoped to **one product** that flips `generate_list_resource: true` on every eligible MMv1 resource in that product, generates the downstream code, runs the generated list-query tests, and opens the PR. Do **one product per PR**, with as many eligible resources as pass.
 
+Consult `.agents/knowledge/index.md` for the topics this task touches and open the relevant sources.
+
 ## Prerequisites
 
 * You are in the `magic-modules` root directory.

.agents/skills/workflows/default/SKILL.md

@@ -14,6 +14,7 @@ This document outlines the structured 5-step lifecycle for formal implementation
 
 ### 2. Triage
 *   Gather context on the change or bug. Plan the change (New feature or bug fix) within schema or logic. 
+*   Consult `.agents/knowledge/index.md` for the topics the change touches and open the relevant sources.
 *   Execute the `triage` skill (located in `.agents/skills/operations/triage/`) to perform this work.
 *   **Transfers to Step 3:** Approved implementation plan and file paths file.
 

.agents/skills/workflows/new_resource/SKILL.md

@@ -31,5 +31,6 @@ There are two ways to generate the initial YAML definition for the resource:
     - If the subagent reports test failures, enter the **Default Workflow** ([default/SKILL.md](../default/SKILL.md)) at **Step 5 (Fix)** to plan remediation.
 
 ### 2B. Manual Path
+*   Consult `.agents/knowledge/index.md` for the topics the resource touches and open the relevant sources.
 *   Follow the standard process to draft the YAML definition in `mmv1/products/...` based on API documentation and repository patterns.
 *   **Handoff:** Once the YAML is drafted, enter the **Default Workflow** ([default/SKILL.md](../default/SKILL.md)) at **Step 3 (Generate)** to compile the provider and continue with testing.

AGENTS.md

@@ -12,13 +12,13 @@ here, upstream — never in the downstream repos.
   provider task.
 - **`.agents/skills/`** — reusable skills the workflows compose (generation, testing, log parsing,
   troubleshooting). Each skill's `SKILL.md` frontmatter states when to use it.
-- **`.agents/knowledge/`** — the curated knowledge base (initial seeding in progress). When present,
-  consult its `index.md` at decision points and open only the entries the task needs.
+- **[.agents/knowledge/index.md](.agents/knowledge/index.md)** — the knowledge index: a short map of
+  where provider knowledge lives. Refer to this to check for relevant patterns or instructions.
 - **`.agents/archive/`** — parked tracks (currently TGC). Not maintained; do not use as reference.
 
 ## Ground rules
 
-- **Never weaken a test or check to make it pass.** No disabling or skipping tests, and no test-dodging
-  behavior flags (`ignore_read`, `default_from_api`, `ImportStateVerifyIgnore`) without an adjacent
+- **Never weaken baseline test coverage to make a test pass.** No disabling or skipping tests, and no test-dodging
+  behavior flags (`ignore_read`, `ImportStateVerifyIgnore`) without an adjacent
   comment justifying the API behavior that requires them.
 - **Verify before opening a PR**: generate, build, and run the tests relevant to what you changed.

docs/content/develop/diffs.md

@@ -181,27 +181,11 @@ In the flattener for the field, return the value of the field in the user's conf
 
 {{% tabs "ignore_read" %}}
 {{< tab "MMv1" >}}
-On top-level fields, this can be done with:
+Set:
 
 ```yaml
 ignore_read: true
 ```
-
-For nested fields, `ignore_read` is [not currently supported](https://github.com/hashicorp/terraform-provider-google/issues/12410), so this must be implemented with a [custom flattener]({{< ref "/develop/custom-code#custom_flatten" >}}). You will also need to add the field to `ignore_read_extra` on any examples that are used to generate tests; this will cause tests to ignore the field when checking that the values in the API match the user's configuration.
-
-```go
-func flatten{{$.GetPrefix}}{{$.TitlelizeProperty}}(v interface{}, d *schema.ResourceData, config *transport_tpg.Config) interface{} {
-    // We want to ignore read on this field, but cannot because it is nested
-    return d.Get("path.0.to.0.nested.0.field")
-}
-```
-
-```yaml
-examples:
-   # example configuration
-   ignore_read_extra:
-     - "path.0.to.0.nested.0.field"
-```
 {{< /tab >}}
 {{< tab "Handwritten" >}}
 Use `d.Get` to set the flattened value to be the same as the user-configured value (instead of a value from the API).

mmv1/api/resource.go

@@ -1387,7 +1387,7 @@ func (r Resource) Updatable() bool {
 	if !r.Immutable {
 		return true
 	}
-	for _, p := range r.AllPropertiesInVersion() {
+	for _, p := range r.AllNestedProperties(r.RootProperties()) {
 		if p.UpdateUrl != "" {
 			return true
 		}