docs(ISSUE-WP-0006): Forgejo-only language and projection boundary

Prefer Forgejo as the self-hosted forge product. Keep Gitea only as the
Gitea-compatible API identifier (module backends/gitea, type string
gitea). FORGEJO_TOKEN is preferred; GITEA_* remains a deprecated alias.

INTENT/SCOPE quote ACT-ADR-005: issue-core is not the fleet ops claim
queue. Connector docs describe repo work record → hub index → optional
Forgejo projection, not activity-core → issue-core → harness.

Assistant: grok
Assistant-Session: 01a09dc6-3f0d-7c93-8b11-8e83c0623d49

examples/agents/README.md

@@ -12,7 +12,8 @@ This directory contains working examples of autonomous agents using the Issue Co
 
 2. **Configure backend** (one-time setup):
    ```bash
-   export GITEA_API_TOKEN="your-token"
+   export FORGEJO_TOKEN="your-token"
+   # Deprecated alias: GITEA_API_TOKEN
    issue backend add myproject gitea
    # Enter: URL, owner, repo when prompted
    issue backend set-default myproject
@@ -20,10 +21,11 @@ This directory contains working examples of autonomous agents using the Issue Co
 
 3. **Set environment variables** for scripts:
    ```bash
-   export GITEA_URL=https://gitea.example.com
-   export GITEA_TOKEN=your-token
-   export GITEA_OWNER=your-org
-   export GITEA_REPO=your-repo
+   export FORGEJO_URL=https://forgejo.example.com
+   export FORGEJO_TOKEN=your-token
+   export FORGEJO_OWNER=your-org
+   export FORGEJO_REPO=your-repo
+   # Deprecated aliases: GITEA_URL, GITEA_TOKEN, GITEA_OWNER, GITEA_REPO
    ```
 
 ## Examples
@@ -212,7 +214,7 @@ issue backend add myproject gitea
 ### "Authentication failed"
 ```bash
 # Check token is valid
-curl -H "Authorization: token $GITEA_TOKEN" $GITEA_URL/api/v1/user
+curl -H "Authorization: token $FORGEJO_TOKEN" $FORGEJO_URL/api/v1/user
 ```
 
 ### "No issues found"

examples/agents/human_in_loop.py

@@ -9,10 +9,10 @@ This agent demonstrates agent-human collaboration:
 4. Agent can ask questions and wait for answers
 
 Usage:
-    export GITEA_URL=https://gitea.example.com
-    export GITEA_TOKEN=your-token
-    export GITEA_OWNER=your-org
-    export GITEA_REPO=your-repo
+    export FORGEJO_URL=https://forgejo.example.com
+    export FORGEJO_TOKEN=your-token
+    export FORGEJO_OWNER=your-org
+    export FORGEJO_REPO=your-repo
 
     python human_in_loop.py
 """
@@ -40,11 +40,11 @@ class HumanInLoopAgent:
         self.backend = None
 
     def connect(self):
-        """Connect to backend."""
-        base_url = os.environ['GITEA_URL']
-        token = os.environ['GITEA_TOKEN']
-        owner = os.environ['GITEA_OWNER']
-        repo = os.environ['GITEA_REPO']
+        """Connect to Forgejo backend."""
+        base_url = os.environ.get('FORGEJO_URL') or os.environ['GITEA_URL']
+        token = os.environ.get('FORGEJO_TOKEN') or os.environ.get('FORGEJO_API_TOKEN') or os.environ['GITEA_TOKEN']
+        owner = os.environ.get('FORGEJO_OWNER') or os.environ['GITEA_OWNER']
+        repo = os.environ.get('FORGEJO_REPO') or os.environ['GITEA_REPO']
 
         self.backend = GiteaBackend()
         self.backend.connect({

examples/agents/monitoring_agent.py

@@ -9,10 +9,10 @@ This agent monitors issue health and sends alerts:
 - Reports on project velocity and bottlenecks
 
 Usage:
-    export GITEA_URL=https://gitea.example.com
-    export GITEA_TOKEN=your-token
-    export GITEA_OWNER=your-org
-    export GITEA_REPO=your-repo
+    export FORGEJO_URL=https://forgejo.example.com
+    export FORGEJO_TOKEN=your-token
+    export FORGEJO_OWNER=your-org
+    export FORGEJO_REPO=your-repo
 
     python monitoring_agent.py [--stale-days=7] [--check-interval=3600]
 """
@@ -42,11 +42,11 @@ class MonitoringAgent:
         self.backend = None
 
     def connect(self):
-        """Connect to backend."""
-        base_url = os.environ['GITEA_URL']
-        token = os.environ['GITEA_TOKEN']
-        owner = os.environ['GITEA_OWNER']
-        repo = os.environ['GITEA_REPO']
+        """Connect to Forgejo backend."""
+        base_url = os.environ.get('FORGEJO_URL') or os.environ['GITEA_URL']
+        token = os.environ.get('FORGEJO_TOKEN') or os.environ.get('FORGEJO_API_TOKEN') or os.environ['GITEA_TOKEN']
+        owner = os.environ.get('FORGEJO_OWNER') or os.environ['GITEA_OWNER']
+        repo = os.environ.get('FORGEJO_REPO') or os.environ['GITEA_REPO']
 
         self.backend = GiteaBackend()
         self.backend.connect({

examples/agents/multi_agent_pipeline.py

@@ -11,10 +11,10 @@ Demonstrates a CI/CD-like pipeline with multiple specialized agents:
 Each agent monitors for issues in their stage and advances them through the pipeline.
 
 Usage:
-    export GITEA_URL=https://gitea.example.com
-    export GITEA_TOKEN=your-token
-    export GITEA_OWNER=your-org
-    export GITEA_REPO=your-repo
+    export FORGEJO_URL=https://forgejo.example.com
+    export FORGEJO_TOKEN=your-token
+    export FORGEJO_OWNER=your-org
+    export FORGEJO_REPO=your-repo
 
     # Run all agents in parallel (in separate terminals)
     python multi_agent_pipeline.py --agent=coder
@@ -50,11 +50,11 @@ class BaseAgent:
         self.backend = None
 
     def connect(self):
-        """Connect to backend from environment."""
-        base_url = os.environ['GITEA_URL']
-        token = os.environ['GITEA_TOKEN']
-        owner = os.environ['GITEA_OWNER']
-        repo = os.environ['GITEA_REPO']
+        """Connect to Forgejo backend from environment."""
+        base_url = os.environ.get('FORGEJO_URL') or os.environ['GITEA_URL']
+        token = os.environ.get('FORGEJO_TOKEN') or os.environ.get('FORGEJO_API_TOKEN') or os.environ['GITEA_TOKEN']
+        owner = os.environ.get('FORGEJO_OWNER') or os.environ['GITEA_OWNER']
+        repo = os.environ.get('FORGEJO_REPO') or os.environ['GITEA_REPO']
 
         self.backend = GiteaBackend()
         self.backend.connect({

examples/agents/simple_task_executor.py

@@ -9,10 +9,10 @@ This agent demonstrates a basic workflow:
 4. Report completion and close the issue
 
 Usage:
-    export GITEA_URL=https://gitea.example.com
-    export GITEA_TOKEN=your-token
-    export GITEA_OWNER=your-org
-    export GITEA_REPO=your-repo
+    export FORGEJO_URL=https://forgejo.example.com
+    export FORGEJO_TOKEN=your-token
+    export FORGEJO_OWNER=your-org
+    export FORGEJO_REPO=your-repo
 
     python simple_task_executor.py
 """
@@ -39,16 +39,22 @@ class SimpleTaskExecutor:
         self.backend = None
 
     def connect(self):
-        """Connect to Gitea backend from environment variables."""
-        base_url = os.environ.get('GITEA_URL')
-        token = os.environ.get('GITEA_TOKEN')
-        owner = os.environ.get('GITEA_OWNER')
-        repo = os.environ.get('GITEA_REPO')
+        """Connect to Forgejo backend from environment variables."""
+        base_url = os.environ.get('FORGEJO_URL') or os.environ.get('GITEA_URL')
+        token = (
+            os.environ.get('FORGEJO_TOKEN')
+            or os.environ.get('FORGEJO_API_TOKEN')
+            or os.environ.get('GITEA_TOKEN')
+            or os.environ.get('GITEA_API_TOKEN')
+        )
+        owner = os.environ.get('FORGEJO_OWNER') or os.environ.get('GITEA_OWNER')
+        repo = os.environ.get('FORGEJO_REPO') or os.environ.get('GITEA_REPO')
 
         if not all([base_url, token, owner, repo]):
             raise ValueError(
                 "Missing required environment variables: "
-                "GITEA_URL, GITEA_TOKEN, GITEA_OWNER, GITEA_REPO"
+                "FORGEJO_URL, FORGEJO_TOKEN, FORGEJO_OWNER, FORGEJO_REPO "
+                "(deprecated aliases: GITEA_URL, GITEA_TOKEN, GITEA_OWNER, GITEA_REPO)"
             )
 
         self.backend = GiteaBackend()