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

README.md

@@ -1,10 +1,10 @@
 # Issue Core — External Tracker Connector
 
-**A backend-agnostic connector to third-party issue trackers (Gitea/Forgejo, GitHub, …), not the fleet's internal work-origin or coordination substrate.**
+**A backend-agnostic connector to third-party issue trackers (Forgejo, GitHub, …), not the fleet's internal work-origin or coordination substrate.**
 
 ## Purpose
 
-**issue-core** is a standardized abstraction layer for talking to external issue-tracking backends (Gitea, GitHub, GitLab, local SQLite cache). Instead of each agent or automation implementing platform-specific APIs, they use one consistent CLI and Python interface — and, going forward, a durable **work-record UUID ↔ external issue id** mapping when a tracker projection is switched on.
+**issue-core** is a standardized abstraction layer for talking to external issue-tracking backends (Forgejo, GitHub, GitLab, local SQLite cache). Instead of each agent or automation implementing platform-specific APIs, they use one consistent CLI and Python interface — and, going forward, a durable **work-record UUID ↔ external issue id** mapping when a tracker projection is switched on. The self-hosted forge is **Forgejo** only (ACT-ADR-005); the HTTP API is Gitea-compatible.
 
 ### Fleet coordination vs external trackers
 
@@ -32,7 +32,7 @@ For agent coordination *inside* the Coulomb fleet, use work records + state-hub,
 
 ✅ **Fully Implemented:**
 - Complete CRUD operations (issues, labels, users, milestones, comments)
-- Gitea backend (production-ready with full API integration)
+- Forgejo backend (Gitea-compatible API; production-ready)
 - Local SQLite backend (offline work with sync capability)
 - CLI with JSON output for machine parsing
 - Python API for programmatic access
@@ -72,15 +72,20 @@ Clients authenticate with `Authorization: Bearer <key>` or `X-API-Key: <key>`.
 See `SCOPE.md` "TaskSpec payload" for the request schema, or visit
 `http://<host>:<port>/docs` once the server is running for live OpenAPI docs.
 
+Internal scheduled automation (FI/Binky, mail, …) does **not** poll this
+server. Claim/execute is activity-core **`ops_run`** (ACT-ADR-005).
+`POST /issues/` is external tracker create/link only.
+
 ### Configuration (One-Time Setup)
 
-**For Gitea-backed projects:**
+**For Forgejo-backed projects:**
 
 ```bash
-# Set your Gitea token
-export GITEA_API_TOKEN="your-token-here"
+# Preferred token name (CLI also accepts FORGEJO_API_TOKEN)
+export FORGEJO_TOKEN="your-token-here"
+# Deprecated aliases still work: GITEA_API_TOKEN, GITEA_TOKEN
 
-# Configure backend
+# Configure backend (type string `gitea` = Forgejo Gitea-compatible API)
 issue backend add myproject gitea
 # Prompts for: URL, owner, repo (reads token from environment)
 
@@ -185,7 +190,7 @@ for issue in issues:
        ┌───────┴────────┐
        │                │
 ┌──────▼─────┐   ┌──────▼──────┐
-│   Local    │   │   Gitea     │
+│   Local    │   │  Forgejo    │
 │  (SQLite)  │   │  (REST API) │
 └────────────┘   └─────────────┘
 ```
@@ -200,7 +205,7 @@ for issue in issues:
 
 | Backend | Status | Features |
 |---------|--------|----------|
-| **Gitea** | ✅ Production | Full API, rate limiting, state mapping |
+| **Forgejo** (Gitea-compatible API) | ✅ Production | Full API, rate limiting, state mapping |
 | **Local SQLite** | ✅ Production | Offline work, fast queries, sync support |
 | **GitHub** | 🚧 Planned (v1.1) | Full API integration |
 | **GitLab** | 🚧 Planned (v1.2) | Full API integration |
@@ -209,7 +214,7 @@ for issue in issues:
 
 ### 1. External tracker ops (when a backend is in use)
 
-Agents or humans work issues that already live in Gitea/GitHub (e.g. OSS
+Agents or humans work issues that already live in Forgejo/GitHub (e.g. OSS
 inbound, customer Jira, or an intentional projection):
 
 ```bash
@@ -227,7 +232,7 @@ Fleet-internal task claim/execute should use workplan task status in the repo
 
 ### 2. Human collaboration through a tracker UI
 
-When the counterparty only uses GitHub/Gitea, project or update the external
+When the counterparty only uses GitHub/Forgejo, project or update the external
 issue and keep comments there. Mapping design (UUID ↔ external id) will tie
 that projection back to the work record — see `docs/uuid-external-id-mapping.md`.
 
@@ -238,14 +243,14 @@ Work offline with local backend, sync when online:
 ```bash
 # Setup local backup
 issue backend add backup local
-issue sync pull gitea-production backup
+issue sync pull forgejo-production backup
 
 # Work offline
 issue backend set-default backup
 issue create "Offline tracker note" --label=offline
 
 # Sync back
-issue sync push backup gitea-production
+issue sync push backup forgejo-production
 ```
 
 ## CLI Commands Reference
@@ -318,7 +323,7 @@ issue-core/
 │   │   ├── models.py      # Issue, Label, User, etc.
 │   │   └── interfaces.py  # IssueBackend, SyncableBackend
 │   ├── backends/
-│   │   ├── gitea/         # Gitea backend implementation
+│   │   ├── gitea/         # Forgejo backend (Gitea-compatible API)
 │   │   └── local/         # SQLite backend implementation
 │   └── cli/               # Click-based CLI
 │       ├── commands.py    # Issue operations
@@ -358,7 +363,7 @@ issue map detach --uuid <work-record-uuid>
 ```
 
 Mappings live in `~/.config/issue-tracker/mappings.db` (bookkeeping), independent
-of whether CRUD targets Gitea or local SQLite.
+of whether CRUD targets Forgejo or local SQLite.
 
 ## Roadmap (summary)
 
@@ -412,7 +417,7 @@ The Issue Core is designed to be extensible:
 - [ ] Integration tests with mock API
 - [ ] Documentation
 
-See existing backends (Gitea, Local) as reference implementations.
+See existing backends (Forgejo / `gitea` module, Local) as reference implementations.
 
 ## Why "Facade" / connector?
 
@@ -421,7 +426,7 @@ The **Facade Pattern** still describes the *implementation* style:
 > *"Provide a unified interface to a set of interfaces in a subsystem."*
 > — Gang of Four, Design Patterns
 
-Instead of agents learning different APIs for GitHub (`gh`), GitLab (`glab`), Gitea, JIRA, etc., they use one consistent interface. The facade does not replace issue trackers — and it does **not** replace work records as the origin of fleet work. It connects the fleet to trackers at the boundary.
+Instead of agents learning different APIs for GitHub (`gh`), GitLab (`glab`), Forgejo, JIRA, etc., they use one consistent interface. The facade does not replace issue trackers — and it does **not** replace work records as the origin of fleet work. It connects the fleet to trackers at the boundary.
 
 ## License