[#1] Add Developer and Agent Productivity Guidelines to guides and agent workflows

.agents/workflows/agent_productivity.md

@@ -0,0 +1,45 @@
+---
+description: AI Agent environment productivity, paths, and git rules
+---
+
+# Agent Workflow: Productivity & Safety Guidelines
+
+This workflow provides critical instructions for autonomous agents when running commands, configuring paths, and managing Git operations in this repository.
+
+## Rule 1: Execute Non-Interactive Commands
+* **Context:** Agents running terminal commands do not have interactive input access to pipe standard input prompts (like `sudo` password requests).
+* **Action:**
+  1. **Strictly avoid** running interactive commands.
+  2. Always use non-interactive flags (e.g., `docker exec -d`, `npm install -y`, `apt-get install -y`).
+  3. Sourcing credentials must be done via reading the `.env` file instead of prompting.
+
+## Rule 2: Git Mirror Privacy Check
+* **Context:** Command-line pushes to GitHub mirror repositories will fail with error `GH007` if the user's local git commits expose a private/protected email address.
+* **Action:**
+  1. Before executing `git push` to a GitHub mirror, check if the developer's git configuration matches their GitHub account's public email settings.
+  2. If a mirror push fails with `GH007`, instruct the user to temporarily disable **"Block command line pushes that expose my email"** under their GitHub profile settings page: `https://github.com/settings/emails`.
+
+## Rule 3: Use Absolute Paths with Forward Slashes
+* **Context:** Windows and WSL handle paths differently (e.g. `C:\...` vs `/mnt/c/...`). Rendering and layout engines (like MuPDF/PyMuPDF or Docker mounts) fail when using backslashes (`\`) or relative paths.
+* **Action:**
+  1. Always resolve paths dynamically using Python's `os.path.abspath()`.
+  2. Normalize all path strings by replacing backslashes with forward slashes: `.replace('\\', '/')`.
+  3. Write absolute forward-slash paths inside configurations (like `@font-face` styles or Docker compose scripts) to guarantee compatibility across Windows, WSL, and Linux containers.
+
+## Rule 4: Safely Recover from Git Filter Loops
+* **Context:** Clean/smudge attributes filters can trigger checkout loops if the filter script (`local_tools/git-ident-filter.py`) is missing from the working directory during checkout.
+* **Action:**
+  1. If `git checkout` fails with filter errors, restore the filter script first from the HEAD commit:
+     ```bash
+     git checkout HEAD -- local_tools/git-ident-filter.py
+     ```
+  2. Once the script is restored, re-run the clean checkout:
+     ```bash
+     git checkout -f
+     ```
+
+## Rule 5: Keep Credentials Ignored
+* **Context:** Temporary scripts containing tokens (such as `add_mirror_repos.bat` with a `GITHUB_TOKEN`) must never be committed.
+* **Action:**
+  1. Always save temporary scripts containing credentials in the `scratch/` directory.
+  2. The `scratch/*` rule inside `.gitignore` will automatically prevent these scripts from being tracked or pushed.

INSTALL_WSL.md

@@ -107,4 +107,27 @@ Once the stack is fully running, you can connect to all system components in you
 
 ---
 
+## ⚡ Developer Productivity & Troubleshooting
+
+### 1. Dynamic LLM Pulls (Non-Interactive)
+To pull updates to your reasoning models in a single line without entering an interactive shell, use:
+```bash
+docker exec -it $(docker ps -q -f name=ollama) ollama pull $(grep '^[ \t]*LLM_MODEL[ \t]*=' .env | cut -d'=' -f2)
+```
+
+### 2. Path Resolutions inside WSL
+If you need to configure container volumes or load local files (like the datasets or PDF fonts), remember that the host's `C:` drive is mounted under `/mnt/c/` in WSL:
+* **Windows Path:** `C:/Users/lanfr144/Documents/DOPRO1/Antigravity/Food/docs/fonts/`
+* **WSL Path:** `/mnt/c/Users/lanfr144/Documents/DOPRO1/Antigravity/Food/docs/fonts/`
+* *Tip:* Always use forward slashes `/` in path configurations, as they are natively supported by both PowerShell on the Windows host and Bash inside WSL.
+
+### 3. Git Attributes Clean/Smudge Loops
+If running a clean checkout (e.g. `git checkout -f`) triggers an error about a missing `git-ident-filter.py` script, restore the filter script first before executing the checkout:
+```bash
+git checkout HEAD -- local_tools/git-ident-filter.py
+git checkout -f
+```
+
+---
+
 *Prepared by Francois Lange for the Local Food AI Delivery.*