Add documentation test report from alpha environment dogfooding

docs/DOCUMENTATION_TEST_REPORT.md

@@ -0,0 +1,147 @@
+# Documentation Test Report - Alpha Environment
+**Date:** 2026-04-19  
+**Tester:** BarnacleBoy  
+**Environment:** alpha
+
+---
+
+## Executive Summary
+
+Most wrapper functions work correctly. Several wrappers hit API server errors (500/502) which suggests alpha API endpoints are not fully operational for social operations (follow, trust, react, update).
+
+---
+
+## Test Results
+
+### Working Wrappers
+
+| Wrapper | Status | Notes |
+|---------|--------|-------|
+| `create_post` | ✅ Working | Verified - post created with Spongebob quotes |
+| `create_comment` | ✅ Working | Verified - comments attach to posts correctly |
+
+### Wrappers with API Errors
+
+| Wrapper | Status | Error | Notes |
+|---------|--------|-------|-------|
+| `follow` | ❌ Error | 502 Bad Gateway | Endpoint `/alpha/relfollow` returns学师 Bad Gateway |
+| `react` | ❌ Error | 500 Internal Server Error | Endpoint `/alpha/reacttosomething` returns 500 |
+| `trust` | ❌ Error | 500 Internal Server Error | Endpoint `/alpha/reltrust` returns 500 |
+| `update_post` | ❌ Error | 500 Internal Server Error | Endpoint `/alpha/post/update` returns 500 |
+
+### Wrappers with Unclear Behavior
+
+| Wrapper | Status | Notes |
+|---------|--------|-------|
+| `votecast` | ⚠️ Unclear | Returns empty dict `{}` - no error thrown but no data returned |
+
+---
+
+## Static Documentation Issues Found
+
+### 1. APIClient.wrapped() Docstring (Code Bug)
+
+**File:** `src/trustcafeapiwrapper/apiclient.py` lines 207, 209
+
+**Issue:** Docstring says `'job'` but code reads `"job_function"`
+
+```python
+# Docstring says (incorrect):
+wrapped_data (dict): A dictionary with 'job' (string) and 'payload' (dict) keys.
+
+# But code reads:
+return self.run_job(wrapped_data.get("job_function"), wrapped_data.get("payload", {}))
+```
+
+**Impact:** Low - all wrapper functions return `{"job_function": ..., "payload": ...}` which matches what `wrapped()` reads. Only the docstring is misleading.
+
+**Proposed Fix (code):** Update docstring:
+```python
+wrapped_data (dict): A dictionary with 'job_function' (string) and 'payload' (dict) keys.
+```
+
+---
+
+### 2. update_post wrapper docstring (Code Bug)
+
+**File:** `src/trustcafeapiwrapper/wrappers/post/update_post.py` line 16
+
+**Issue:** Internal docstring references `post_slug` but parameter is `post_path`
+
+```python
+def update_post(
+    post_text:str, 
+    post_path:str|None=None,  # Parameter is post_path
+    ...
+):
+    """
+    Args:
+        post_slug (str): The slug of the post to update.  # Docstring says post_slug - WRONG
+    """
+```
+
+**Impact:** Low - parameter names in function signature are correct. Only internal docstring is wrong.
+
+**Proposed Fix (code):**
+```python
+post_path (str, optional): The path of the post to update.
+```
+
+---
+
+### 3. feed.followingfeed vs feed.following (Documentation Bug)
+
+**File:** `docs/API_REFERENCE.md` line 688
+
+**Issue:** Documents `feed.followingfeed()` but actual job function is `feed.following`
+
+```python
+# Documentation says:
+feed = API.run_job('feed.followingfeed')
+
+# But actual job is:
+feed = API.run_job('feed.following')
+```
+
+**Impact:** Medium - user will get AttributeError trying to use undocumented job name.
+
+**Proposed Fix (docs):** Update line 688 from:
+```markdown
+### feed.followingfeed()
+```
+to:
+```markdown
+### feed.following()
+```
+
+And update example from:
+```python
+following_feed = API.run_job('feed.followingfeed')
+```
+to:
+```python
+following_feed = API.run_job('feed.following')
+```
+
+---
+
+## Recommendations
+
+1. **For Alpha API:** Several social operations (follow, trust, react, update_post) are returning 500 errors. These need backend fixes before wrappers can be verified working.
+
+2. **For Documentation:** Fix the three static issues above to match code reality.
+
+3. **For votecast:** Verify if empty dict return is expected behavior or if there's a response that should be returned.
+
+---
+
+## Test Assets Created
+
+Five Spongebob-themed posts created for testing:
+1. "I wumbo, you wumbo, he wumbo, we wumbo!"
+2. "The best time to wear a sweater is all the time."
+3. "I'm a Goofy Goober, yeah!"
+4. "Life is fun. But fun is different."
+5. "Patrick, you in danger, homie."
+
+Post IDs saved to `/home/agent/trustcafe-test-posts.json`