Refactor agent documentation and establish core guidelines (#3820)

* update the factories overview

* update agent rules

* update main GEMINI file

* add preferred workflow to GEMINI file

GEMINI.md

@@ -17,13 +17,15 @@ Cloud Foundation Fabric is a comprehensive suite of Terraform modules and end-to
     *   Self-contained: Dependency injection via context variables is preferred over complex remote state lookups within modules.
     *   Flat: avoid using sub-modules to reduce complexity and minimize layer traversals.
     *   **Naming:** Avoid random suffixes; use explicit `prefix` variables.
+*   **Factories:** Many modules implement a data-driven "factory" pattern (often via a `factories_config` variable) to manage resources at scale using YAML data files. See `FACTORIES.md` for a comprehensive list.
+    *   **Validation:** Factory YAML files must conform to JSON schemas (typically stored in a `schemas/` folder). Use a modeline (e.g., `# yaml-language-server: $schema=../schemas/project.schema.json`) to enable IDE validation.
 *   **Usage:** Modules are designed to be forked/owned or referenced via Git tags (e.g., `source = "github.com/...//modules/project?ref=v30.0.0"`).
 
 ### 2. FAST (`/fast`)
 
 *   **Purpose:** Rapidly set up a secure, scalable GCP organization.
 *   **Architecture:** Divided into sequential "stages" (0-org-setup, 1-vpcsc, 2-security, 2-networking, etc.).
-*   **Factories:** Uses YAML-based "factories" (e.g., Project Factory) to drive configuration at scale.
+*   **Factories:** Extensively uses YAML-based datasets and module factory patterns to drive configuration at scale, acting as a "translation machine" that expresses different architectural designs without changing the underlying stage code.
 
 ### 3. Tools (`/tools`)
 
@@ -61,6 +63,7 @@ terraform fmt -recursive modules/<module-name>
 python3 tools/check_documentation.py modules/<module-name>
 
 # Regenerate README variables/outputs tables when check fails
+# Note: tfdoc uses special HTML comments (<!-- BEGIN TFDOC -->) in READMEs. Do not manually edit these sections.
 python3 tools/tfdoc.py --replace modules/<module-name>
 
 # YAML linting
@@ -74,7 +77,20 @@ python3 tools/check_boilerplate.py --scan-files <files>
 
 #### 2. Testing
 
-Tests are written in Python using `pytest` and the [`tftest`](https://pypi.org/project/tftest/) library.
+Our testing philosophy is simple: test to ensure the code works and does not break due to dependency changes. **Example-based testing via `README.md` is the preferred approach.** 
+
+Tests are triggered from HCL Markdown fenced code blocks using a special `# tftest` directive at the end of the block.
+
+```hcl
+module "my-module" {
+  source = "./modules/my-module"
+  # ...
+}
+# tftest modules=1 resources=2 inventory=my-inventory.yaml
+```
+
+*   **Inventory files (`YAML`):** Used to assert specific values, resource counts, or outputs from the terraform plan against an expected dataset.
+*   **Legacy Tests:** Python-based tests using `pytest` and `tftest` are supported but example-based tests should be used whenever possible.
 
 ```bash
 # Run all tests
@@ -83,8 +99,8 @@ pytest tests
 # Run specific module examples
 pytest -k 'modules and <module-name>:' tests/examples
 
-# Run tests from a specific file
-pytest tests/examples/test_plan.py
+# Automatically generate an inventory file from a successful plan
+pytest -s 'tests/examples/test_plan.py::test_example[terraform:modules/<module-name>:Heading Name:Index]'
 ```
 
 **Note:** `TF_PLUGIN_CACHE_DIR` is recommended to speed up tests.
@@ -181,9 +197,24 @@ Modify one existing README example (do not add a new one) to demonstrate context
 
 ## Architecture & Conventions
 
-*   **Variables:** Prefer object variables (e.g., `iam = { ... }`) over many individual scalar variables.
+*   **Variables & Interfaces:** 
+    *   Prefer object variables (e.g., `iam = { ... }`) over many individual scalar variables.
+    *   Design compact variable spaces by leveraging Terraform's `optional()` function with defaults extensively.
+    *   Use maps instead of lists for multiple items to ensure stable keys in state and avoid `for_each` dynamic value issues.
+*   **Naming:** Never use random strings for resource naming. Rely on an optional `prefix` variable implemented consistently across modules.
 *   **IAM:** Implemented within resources (authoritative `_binding` or additive `_member`) via standard interfaces.
 *   **Outputs:** Explicitly depend on internal resources to ensure proper ordering (`depends_on`).
 *   **File Structure:**
     *   Move away from `main.tf`, `variables.tf`, `outputs.tf`.
     *   Use descriptive filenames: `iam.tf`, `gcs.tf`, `mounts.tf`.
+*   **Style & Formatting:**
+    *   **Line Length:** Enforce a 79-character line length limit for legibility (relaxed for long resource attributes and descriptions).
+    *   **Ternary Operators & Functions:** Wrap complex ternary operators in parentheses and break lines to align `?` and `:`. Split function calls with many arguments across multiple lines.
+    *   **Locals Separation:** Use module-level locals for values referenced directly by resources/outputs. Use block-level "private" locals prefixed with an underscore (`_`) for intermediate transformations.
+    *   **Complex Transformations:** Move complex data transformations in `for` or `for_each` loops to `locals` to keep resource blocks clean.
+
+## Preferred Workflow
+
+- Always break down complex requests into small, iterative tasks.
+- For each task, propose the necessary edits and explicitly wait for user confirmation or discussion before proceeding.
+- Always use the `replace` tool to both perform and cleanly display the proposed text modifications. Do not silently overwrite files or use shell commands for text edits.