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

AGENT_INTEGRATION.md

@@ -1,24 +1,55 @@
 # Agent Integration Guide
 
-**Issue Core for Autonomous Coding Agent Coordination**
+**Issue Core for external tracker projection** — not the fleet ops queue.
 
 ## Purpose
 
-The **Issue Core** capability provides a standardized interface for autonomous coding agents to operate on **external issue trackers** (GitHub, GitLab, Gitea/Forgejo). Instead of agents learning platform-specific APIs, they use a unified abstraction.
+The **Issue Core** capability provides a standardized interface for autonomous
+coding agents to operate on **external issue trackers** (Forgejo, GitHub,
+GitLab, Jira). Instead of agents learning platform-specific APIs, they use a
+unified abstraction. The self-hosted forge is **Forgejo** only; the HTTP API
+is Gitea-compatible (`issue_core.backends.gitea`, backend type `gitea`).
 
-**Fleet note (2026-07-20):** Internal work originates as repo work records (ADR-001 / work-record canon), not as issue-core issues. Use this guide when an agent must project to or work inside a third-party tracker. See `INTENT.md` and `docs/uuid-external-id-mapping.md`.
+**Fleet note (2026-07-20 / ISSUE-WP-0006):** Internal work originates as repo
+work records (ADR-001 / work-record canon), not as issue-core issues. Use this
+guide when an agent must project to or work inside a third-party tracker. See
+`INTENT.md` and `docs/uuid-external-id-mapping.md`.
+
+### Happy path (projection, not automation loop)
+
+```
+  1. Author work record in repo (ADR-001)
+           │
+           │  fix-consistency
+           v
+     state-hub index (UUIDv7 write-back)
+           │
+           │  optional project / link
+           v
+  2. issue-core ──► Forgejo  (or GitHub / Jira later)
+  3. mapping: work-record UUID ↔ (backend=forgejo, external_id)
+              stored backend type string is currently `gitea`
+              (Forgejo Gitea-compatible API)
+```
+
+Internal scheduled automation (FI/Binky, mail, …) does **not** follow
+`activity-core → issue-core → harness`. That path is **legacy / external
+tickets only**. Claim/execute for fleet ops is activity-core **`ops_run`**
+(ACT-ADR-005). See rein-aharness `docs/task-intake.md` and ISSUE-WP-0006.
 
 ### When to use a tracker (and when not to)
 
-**Fleet claim/execute** runs on work records (repo files + state-hub), not on
-Forgejo by default. Use issue-core when:
+**Fleet claim/execute** runs on work records (repo files + state-hub) or on
+`ops_run` for scheduled automation — not on Forgejo by default. Use
+issue-core when:
 
-- A counterparty or OSS workflow lives in Gitea/GitHub/Jira
+- A counterparty or OSS workflow lives in Forgejo/GitHub/Jira
 - You need to **project or link** a work record (`issue project` / `issue map`)
 - You must update or comment on an **external** issue already in a tracker
 
-Do **not** treat issue-core as the org task board or as origin of intake/tasks.
-Findings → `kind: intake` + promotion; optional later projection.
+Do **not** treat issue-core as the org task board, the ops claim queue, or
+the origin of intake/tasks. Findings → `kind: intake` + promotion; optional
+later projection.
 
 ## Current Status: Production-Ready with Manual Setup
 
@@ -31,7 +62,7 @@ Findings → `kind: intake` + promotion; optional later projection.
 - Milestone operations
 - Comment threads
 
-✅ **Gitea Backend** (Production-Ready)
+✅ **Forgejo Backend** (Production-Ready; Gitea-compatible API)
 - Complete API integration
 - Rate limiting and error handling
 - State mapping (open/in_progress/blocked → open/closed)
@@ -76,18 +107,19 @@ pip install -e .
 
 ### 2. Backend Configuration (One-Time Setup)
 
-**For Gitea Projects:**
+**For Forgejo Projects:**
 
 ```bash
-# Configure Gitea backend
-export GITEA_API_TOKEN="your-token-here"
+# Configure Forgejo backend (type string `gitea` = Gitea-compatible API)
+export FORGEJO_TOKEN="your-token-here"
+# Deprecated aliases: FORGEJO_API_TOKEN, GITEA_API_TOKEN, GITEA_TOKEN
 
 issue backend add my-project gitea
 # Prompts for:
-# - Gitea URL: https://gitea.example.com
+# - Forgejo URL: https://forgejo.example.com
 # - Owner: your-org
 # - Repo: your-project
-# - Token: (reads from GITEA_API_TOKEN)
+# - Token: (reads FORGEJO_TOKEN, then deprecated GITEA_* aliases)
 
 # Verify connection
 issue backend test my-project
@@ -187,8 +219,8 @@ from datetime import datetime, timezone
 
 backend = GiteaBackend()
 backend.connect({
-    'base_url': 'https://gitea.example.com',
-    'token': os.environ['GITEA_API_TOKEN'],
+    'base_url': os.environ.get('FORGEJO_URL', 'https://forgejo.example.com'),
+    'token': os.environ.get('FORGEJO_TOKEN') or os.environ['GITEA_API_TOKEN'],
     'owner': 'myorg',
     'repo': 'myproject'
 })
@@ -236,10 +268,10 @@ import os
 # Initialize backend
 backend = GiteaBackend()
 backend.connect({
-    'base_url': os.environ['GITEA_URL'],
-    'token': os.environ['GITEA_API_TOKEN'],
-    'owner': os.environ['GITEA_OWNER'],
-    'repo': os.environ['GITEA_REPO']
+    '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_API_TOKEN'],
+    'owner': os.environ.get('FORGEJO_OWNER') or os.environ['GITEA_OWNER'],
+    'repo': os.environ.get('FORGEJO_REPO') or os.environ['GITEA_REPO']
 })
 
 # Query issues
@@ -421,14 +453,14 @@ results = read_agent_messages(42, 'implementation_complete')
 ```bash
 # Pull all issues to local backup
 issue backend add backup local
-issue sync pull gitea-remote backup
+issue sync pull forgejo-remote backup
 
 # Work offline with local backend
 issue backend set-default backup
 issue create "Offline work item" --label=offline
 
 # Sync back when online
-issue sync push backup gitea-remote
+issue sync push backup forgejo-remote
 ```
 
 ### Conflict Handling
@@ -509,20 +541,20 @@ Create a setup script for each project:
 # setup-issue-tracking.sh
 
 cat > .issue-core-config << EOF
-GITEA_URL=https://gitea.example.com
-GITEA_OWNER=myorg
-GITEA_REPO=myproject
-GITEA_TOKEN_FILE=~/.secrets/gitea-token
+FORGEJO_URL=https://forgejo.example.com
+FORGEJO_OWNER=myorg
+FORGEJO_REPO=myproject
+FORGEJO_TOKEN_FILE=~/.secrets/forgejo-token
 EOF
 
 # Load config and configure backend
 source .issue-core-config
-export GITEA_API_TOKEN=$(cat $GITEA_TOKEN_FILE)
+export FORGEJO_TOKEN=$(cat $FORGEJO_TOKEN_FILE)
 
 issue backend add $(basename $(pwd)) gitea <<INPUT
-$GITEA_URL
-$GITEA_OWNER
-$GITEA_REPO
+$FORGEJO_URL
+$FORGEJO_OWNER
+$FORGEJO_REPO
 INPUT
 
 issue backend set-default $(basename $(pwd))
@@ -642,7 +674,7 @@ issue backend add myproject gitea
 issue backend test myproject
 
 # Reconfigure with correct token
-export GITEA_API_TOKEN="new-token"
+export FORGEJO_TOKEN="new-token"
 issue backend remove myproject
 issue backend add myproject gitea
 ```
@@ -650,7 +682,7 @@ issue backend add myproject gitea
 ### "Issue not found"
 
 ```python
-# Gitea uses backend_id, not number
+# Forgejo uses backend_id, not number
 issue = backend.get_issue_by_number(42)  # Correct
 # issue = backend.get_issue("42")  # Wrong - needs backend_id
 ```