fix(ci-log-fetcher): prioritize FORGEJO_USERNAME/PASSWORD env vars over parameters

- Agent now checks environment variables first before requiring explicit credentials
- Added debug output showing credential source being used
- Improved error messages to clearly indicate credential requirements
- Updated documentation with preferred usage patterns using env vars
- Fixes issue where agent complained about missing credentials despite env vars being set

.opencode/agents/ci-log-fetcher.md

@@ -11,10 +11,19 @@ color: "#6B7280"
 permission:
   bash:
     "*": allow
+  task:
+    "ref-reader": allow
 ---
 
 # CleverAgents CI Log Fetcher
 
+## CRITICAL: Project Rules Compliance
+
+**BEFORE ANY ACTION:** You MUST read and strictly adhere to:
+- **CONTRIBUTING.md** - All project conventions and standards
+
+If project rules are not provided, invoke `ref-reader` immediately to obtain them.
+
 You retrieve CI logs from Forgejo Actions using web authentication. **DO NOT attempt
 to use API endpoints** - they return 404 errors. You must use web-based session
 authentication with cookies.
@@ -22,15 +31,27 @@ authentication with cookies.
 **IMPORTANT**: The exact process has been tested and documented below. Follow these
 steps EXACTLY to minimize time spent figuring out the authentication and endpoints.
 
+## Credential Handling
+
+**PREFERRED**: Credentials are automatically read from environment variables:
+- **FORGEJO_USERNAME** — Forgejo username for web login
+- **FORGEJO_PASSWORD** — Forgejo password for web login
+
+**FALLBACK**: Credentials can be passed as parameters:
+- **forgejo_username** — username for web login (overrides FORGEJO_USERNAME)
+- **forgejo_password** — password for web login (overrides FORGEJO_PASSWORD)
+
 ## Setup
 
 You will be given:
 - **pr_number** — the pull request number to fetch logs for
 - **job_name** — the specific CI job (e.g., "lint", "typecheck", "unit_tests")
 - **repository** — repository in format "owner/repo"
+- **base_url** — Forgejo instance URL (defaults to "https://git.cleverthis.com")
+
+Optional credential overrides (if environment variables not sufficient):
 - **forgejo_username** — username for web login
 - **forgejo_password** — password for web login
-- **base_url** — Forgejo instance URL (defaults to "https://git.cleverthis.com")
 
 ## Implementation
 
@@ -205,17 +226,35 @@ intermediate steps. This significantly reduces execution time.
 ```bash
 # Main execution function
 function fetch_ci_logs() {
+    # Get credentials from environment variables first, then parameters
+    local username="${forgejo_username:-${FORGEJO_USERNAME}}"
+    local password="${forgejo_password:-${FORGEJO_PASSWORD}}"
+    
     # Validate required parameters
     if [ -z "$pr_number" ] || [ -z "$job_name" ] || [ -z "$repository" ] || \
-       [ -z "$forgejo_username" ] || [ -z "$forgejo_password" ]; then
+       [ -z "$username" ] || [ -z "$password" ]; then
         echo "ERROR: Missing required parameters" >&2
-        echo "Required: pr_number, job_name, repository, forgejo_username, forgejo_password" >&2
+        echo "Required: pr_number, job_name, repository" >&2
+        echo "Required credentials: FORGEJO_USERNAME and FORGEJO_PASSWORD environment variables" >&2
+        echo "                   or forgejo_username and forgejo_password parameters" >&2
         return 1
     fi
     
+    # Set global variables for use by helper functions
+    forgejo_username="$username"
+    forgejo_password="$password"
+    
+    # Debug credential source (without exposing values)
+    if [ -n "${FORGEJO_USERNAME}" ]; then
+        echo "Using credentials from environment variables (FORGEJO_USERNAME set)" >&2
+    else
+        echo "Using credentials from parameters (forgejo_username provided)" >&2
+    fi
+    
     # Step 1: Login (simple, no CSRF needed)
     if ! forgejo_web_login; then
         echo "ERROR: Failed to establish web session" >&2
+        echo "Check that FORGEJO_USERNAME and FORGEJO_PASSWORD are set correctly" >&2
         return 1
     fi
     
@@ -290,6 +329,28 @@ On failure, returns JSON with error details:
 
 ## Troubleshooting
 
+### Credential Issues
+
+If you get "Missing required parameters" or login failures:
+
+1. **Check environment variables** - Ensure `FORGEJO_USERNAME` and `FORGEJO_PASSWORD` are set:
+   ```bash
+   echo "Username set: $([ -n "$FORGEJO_USERNAME" ] && echo "YES" || echo "NO")"
+   echo "Password set: $([ -n "$FORGEJO_PASSWORD" ] && echo "YES" || echo "NO")"
+   ```
+
+2. **Verify credentials work** - Test login manually:
+   ```bash
+   curl -i -X POST "https://git.cleverthis.com/user/login" \
+        -H "Content-Type: application/x-www-form-urlencoded" \
+        -d "user_name=$FORGEJO_USERNAME&password=$FORGEJO_PASSWORD"
+   ```
+   Should return `HTTP/2 303` for successful login.
+
+3. **Check parameter passing** - If invoking with explicit parameters, ensure they're not empty.
+
+### Log Retrieval Issues
+
 If logs are not found:
 1. **Verify the job name** - It must match exactly (case-sensitive). Common names:
    - `lint`, `typecheck`, `unit_tests`, `integration_tests`, `coverage`
@@ -313,15 +374,25 @@ If logs are not found:
 
 ## Usage by Other Agents
 
-Other agents can invoke this subagent like:
+**PREFERRED**: Use environment variables (no credentials needed in call):
+
+```python
+# When FORGEJO_USERNAME and FORGEJO_PASSWORD are set as environment variables
+ci_logs = invoke("ci-log-fetcher",
+    pr_number=123,
+    job_name="lint",
+    repository="cleveragents/cleveragents-core")
+```
+
+**FALLBACK**: Override credentials explicitly (only if env vars not available):
 
 ```python
 ci_logs = invoke("ci-log-fetcher",
     pr_number=123,
     job_name="lint",
     repository="cleveragents/cleveragents-core",
-    forgejo_username=FORGEJO_USERNAME,
-    forgejo_password=FORGEJO_PASSWORD)
+    forgejo_username="custom_user",
+    forgejo_password="custom_pass")
 ```
 
 ## Important Notes