docs: restructure temporary file management and establish Helm naming conventions

- enforce strict isolation of scratch work into categorized subfolders
  to prevent pollution of the project root and temporary root
- prohibit obfuscating Helm resource names behind complex logic
  functions to prioritize readability in internal deployment manifests

.ai/instructions/skills/analysis.instructions.md

@@ -5,7 +5,7 @@ Analysis documents are scratch work — comparisons, evaluations, investigations
 ## Where to write
 
 ```
-tmp/<TOPIC>/filename.md
+tmp/<TOPIC>/<title>.md
 ```
 
 Examples:
@@ -13,7 +13,9 @@ Examples:
 - `tmp/curl-installer/design.md`
 - `tmp/harness-options/analysis.md`
 
-`TOPIC` is a short slug describing the subject area. `filename` describes what the document contains. Use lowercase and hyphens.
+`TOPIC` is a short slug describing the subject area. `<title>.md` describes what the document contains. Use lowercase and hyphens.
+
+**CRITICAL RULE:** Do NOT create analysis files or any temporary files in the project root. Always use the `tmp/<topic>/` folder structure.
 
 ## Scope
 

.ai/instructions/skills/file-editing.instructions.md

@@ -45,48 +45,52 @@
 
 ---
 
-## 📁 Output File Management
+## 📁 Scratch and Temporary Files (Testing, Terminal outputs, Work drafts)
 
-**CRITICAL: Save all reports, test results, and temporary outputs to project's tmp/ directory**
+**CRITICAL: NEVER create temporary, testing, or intermediate files in the project root or source directories.** 
+
+All scratch work, terminal outputs, test scripts, and experimental code MUST be created in the project's `tmp/` directory using a specific structure:
+
+```
+tmp/<topic>/<title>.<extension>
+```
+
+- **`topic`**: A short, hyphenated slug describing the feature, bug, or task you are working on (e.g., `auth-flow-tests`, `db-migration`).
+- **`title`**: What the file actually contains (e.g., `curl-test`, `raw-manifest`).
+- **`<extension>`**: The appropriate file extension for the content (e.g., `.sh`, `.json`, `.yaml`, `.py`).
 
 ### File Output Rules:
-- ✅ **ALWAYS use:** `kube-log/tmp/` for all generated files
+- ✅ **ALWAYS use topic subfolders:** `tmp/<topic>/<filename>` for all generated temporary files, scripts, and logs.
-- ❌ **NEVER use:** `/tmp/` (system temp - outside project)
+- ❌ **NEVER use `tmp/` root:** Do NOT create files directly under `tmp/` (e.g., `tmp/test.sh`). The folder will bloat and become impossible to navigate.
-- ❌ **NEVER use:** `~/` (user home - outside project)
+- ❌ **NEVER use Project root:** (e.g., `./test.py`, `./output.txt`).
+- ❌ **NEVER use System `/tmp/` or user home `~/`:** (They are outside project context and invisible to the user).
 
 ### Examples:
 
 **Correct:**
 ```bash
 # Helm template outputs
-helm template monitoring . > kube-log/tmp/monitoring-manifests.yaml
+helm template monitoring . > tmp/monitoring-setup/rendered-manifests.yaml
 
-# Test results
+# Temporary test scripts
-cat > kube-log/tmp/test-results.md << 'EOF'
+create_file("tmp/auth-flow/test-token.sh", "...")
-# Test Results
-...
-EOF
 
-# Analysis reports
+# JSON payload for curl
-cat > kube-log/tmp/analysis-report.txt << 'EOF'
+create_file("tmp/payment-api/test-payload.json", "...")
-...
-EOF
 ```
 
 **Wrong:**
 ```bash
+# DON'T write to project root!
+helm template monitoring . > rendered-manifests.yaml
+create_file("test-token.sh", "...")
+
 # DON'T use system /tmp
 helm template monitoring . > /tmp/monitoring-manifests.yaml
-
-# DON'T use user home
-cat > ~/test-results.md << 'EOF'
 ```
 
-### Why Project tmp/ Directory:
+### Why use `tmp/<topic>/`:
-- ✅ Keeps all project artifacts together
+- ✅ Keeps the project root clean.
-- ✅ Easy for user to find and review
+- ✅ Groups related investigation files together by topic.
-- ✅ Can be added to .gitignore
+- ✅ The entire `tmp/` folder is `.gitignore`d, preventing accidental commits of test data.
-- ✅ Preserved across sessions
+- ✅ Easy for the user to review or delete later.
-- ✅ Part of project context
-
-**Note:** Create `kube-log/tmp/` directory if it doesn't exist before writing files.

.ai/instructions/skills/helm.instructions.md

@@ -119,6 +119,16 @@ name: {{ include "mychart.fullname" . }}
 name: {{ .Release.Name }}-service
 ```
 
+### 🏷️ Explicit Resource Naming (Readability over Helpers)
+
+**❌ FORBIDDEN:** Hiding resource names behind complex `fullname`, `name`, or `chart` helper functions in umbrellas (e.g., `name: {{ include "mychart.fullname" . }}`).
+**✅ REQUIRED:** Write explicit, readable resource names directly in the manifest using `.Release.Name` and the component name (e.g., `name: {{ .Release.Name }}-keycloak`).
+
+### Why — Clean Code Readability Principle
+Helm's default `_helpers.tpl` generators are designed for publicly distributed charts that require aggressive overriding. For internal or umbrella charts, this obfuscates the codebase. A developer reading a `deployment.yaml` should instantly see the exact name of the resource without opening `_helpers.tpl` to parse logical conditionals. 
+
+*Exception: Standardized Kubernetes labels (`app.kubernetes.io/*` and `helm.sh/chart`) MUST still be centralized in a `common` library chart using helpers (e.g., `{{ include "common.labels" . }}`) to keep the DRY principle intact across hundreds of files.*
+
 ### Why — IaC Principle
 
 The chart is infrastructure code. It must be deployable to any cluster, any namespace, any environment, by any deployer — without editing the chart itself. Installation-specific decisions belong exclusively in `values.<installation>.yaml` in the deployment repo.