getdevintern · danii1 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/docs/code/configuration.md b/docs/code/configuration.md
@@ -4,7 +4,7 @@ sidebarLabel: "Configuration"
 description: "Environment variables, settings.json, tracker credentials, and agent harness options for @devintern/code."
 section: "Code"
 order: 2
-dateModified: 2026-08-08
+dateModified: 2026-08-17
 ---
 
 # @devintern/code Configuration
@@ -81,37 +81,61 @@ MARKDOWN_TASKS_DIR=/path/to/tasks
 
 You can also pass file paths directly as arguments without setting `TASK_TRACKER=markdown` at all. In that mode no `.devintern-code/.env` is needed for tracker credentials. See the [Markdown File Tasks guide](./markdown-tasks.md) for details.
 
-## Optional PR Integration
+## GitHub authentication
 
-Choose one authentication method for pull request creation:
+**Personal / interactive:** a `GITHUB_TOKEN` (personal access token). That is enough for free CLI use from your terminal (`devintern TICKET-123`, `--create-pr`).
+
+**Team / unattended automation:** a GitHub App (`GITHUB_APP_ID` plus a private key). That is what `@mention` matching, `devintern worker --listen` / webhooks, and `slug[bot]` commit attribution need so the bot has a shared team identity. Unattended runs also need a `LICENSE_KEY`. See [Pricing](https://devintern.com/pricing/).
+
+The two credentials are complementary, not drop-in replacements. A team setup that also uses GitHub Issues as the tracker still needs `GITHUB_TOKEN`.
+
+| What you want | Need |
+| --- | --- |
+| Implement tickets and open PRs from the CLI (personal) | `GITHUB_TOKEN` |
+| Use GitHub Issues as the task tracker (`TASK_TRACKER=github`) | `GITHUB_TOKEN` (the App cannot substitute) |
+| Worker review polling on the agent's own PRs | `GITHUB_TOKEN` (solo) or GitHub App (if already configured) |
+| `@mention` the bot on any PR (worker sweep or webhook) | GitHub App (`GITHUB_APP_ID` + private key) |
+| Commits attributed to `slug[bot]` | GitHub App |
+
+Set both when you run mention-driven automation and also use GitHub Issues as a tracker. See [GitHub Issues Integration](./github-issues-integration.md) and [GitHub Integration](./github-integration.md).
+
+**Precedence when both are set:**
+
+- CLI and PR creation use `GITHUB_TOKEN`
+- `devintern worker --listen` and the webhook server prefer the App so the bot identity (`slug[bot]`) resolves
+
+Do not set `GITHUB_APP_ID` without `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY_BASE64`. The ID alone is ignored for auth, but the worker treats it as "GitHub credentials present."
 
 ### GitHub Personal Access Token
 
-For individual users:
+For personal / interactive CLI use, and for `TASK_TRACKER=github`:
 
 ```bash
 GITHUB_TOKEN=your-github-token
 ```
 
 - **Classic token**: Requires `repo` scope
-- **Fine-grained token** (recommended): Requires `Pull requests: Read and write` and `Contents: Read` permissions
+- **Fine-grained token** (recommended): Requires `Pull requests: Read and write` and `Contents: Read` permissions. Add `Issues: Read and write` when `TASK_TRACKER=github`
 - Create at: [https://github.com/settings/tokens](https://github.com/settings/tokens)
 
 ### GitHub App Authentication
 
-For organizations:
+For team / unattended automation (`@mention` matching, webhook / `worker --listen`, `slug[bot]` commit attribution):
 
 ```bash
 GITHUB_APP_ID=123456
 GITHUB_APP_PRIVATE_KEY_PATH=/secure/path/to/your-app.private-key.pem
 ```
 
+Both the ID and a private key are required.
+
 **Benefits:**
 
-- No individual tokens needed
+- Can create PRs without a personal token (team/automation setups)
 - Fine-grained permissions
 - Centralized control
 - Audit trail
+- Resolves the bot identity required for `@mention` matching
 
 **Setup steps:**
 
@@ -122,7 +146,7 @@ GITHUB_APP_PRIVATE_KEY_PATH=/secure/path/to/your-app.private-key.pem
 3. Generate and save a private key
 4. Install the App on your repositories
 
-> These permissions cover task implementation and PR creation. If you also run the webhook server to auto-address PR feedback, that App needs additional **Pull request review comments** and **Issue comments** permissions plus event subscriptions; see [GitHub Integration](./github-integration.md#update-app-permissions).
+> These permissions cover task implementation and PR creation. If you also run the webhook server or mention sweep to auto-address PR feedback, that App needs additional **Pull request review comments** and **Issue comments** permissions plus event subscriptions; see [GitHub Integration](./github-integration.md#update-app-permissions).
 
 For CI/CD environments, you can use a base64-encoded key:
 

diff --git a/docs/code/github-integration.md b/docs/code/github-integration.md
@@ -3,7 +3,7 @@ title: "GitHub Integration"
 description: "Deploy the @devintern/code webhook server for automated PR review handling"
 section: "Server Automation"
 order: 4
-dateModified: 2026-07-03
+dateModified: 2026-08-17
 ---
 
 # GitHub Integration Guide
@@ -69,7 +69,7 @@ Inline review comments are processed _as a batch_ with their parent review — t
 
 ## Prerequisites
 
-1. **GitHub App** configured with webhook permissions
+1. **GitHub App** (`GITHUB_APP_ID` + private key) configured with webhook permissions — the team / unattended-automation credential, required for `@mention` matching and `slug[bot]` commit attribution. A personal `GITHUB_TOKEN` still lets the server call the API, but mention-gated triggers will not fire. See [Configuration](./configuration.md#github-authentication) and [Pricing](https://devintern.com/pricing/).
 2. **Webhook Secret** - a random string for request verification
 3. **Agent Harness CLI** installed and configured
 4. **Git credentials** with push access to target repositories

diff --git a/docs/code/github-issues-integration.md b/docs/code/github-issues-integration.md
@@ -4,7 +4,7 @@ sidebarLabel: "GitHub Issues Integration"
 description: "Fetch GitHub issues, track status labels, implement with your coding agent, and open the PR in the same repository."
 section: "Code"
 order: 5
-dateModified: 2026-07-23
+dateModified: 2026-08-17
 tags: ["github", "github-issues", "devintern/code", "integration"]
 ---
 
@@ -39,6 +39,8 @@ GITHUB_REPO=owner/repo
 
 The same `GITHUB_TOKEN` used for pull request creation works here. It needs the `repo` scope (classic token) or `Issues: Read and write` plus `Pull requests: Read and write` (fine-grained token). `GITHUB_REPO` is the repository whose issues you want to implement, in `owner/repo` form.
 
+GitHub App credentials (`GITHUB_APP_ID` + private key) cannot substitute for this tracker. The Issues client only accepts `GITHUB_TOKEN`. Use a token for personal / interactive CLI use; add the App for team / unattended automation (`@mention` matching, `slug[bot]` commits). See [Configuration](./configuration.md#github-authentication) and [Pricing](https://devintern.com/pricing/).
+
 ### 3. Configure status labels
 
 GitHub has no built-in workflow states, so @devintern/code maps statuses to labels. Create the labels in your repository, then configure them in `.devintern-code/settings.json` using `owner/repo` as the project key:
@@ -111,7 +113,7 @@ GitHub Issues has no estimation field, so `--estimate` runs in comment-only mode
 
 **"Missing required GitHub environment variables"**
 
-Ensure `GITHUB_TOKEN` and `GITHUB_REPO` are set in `.devintern-code/.env`.
+Ensure `GITHUB_TOKEN` and `GITHUB_REPO` are set in `.devintern-code/.env`. A GitHub App ID and private key are not enough for this tracker.
 
 **"Label \"In Progress\" not found in the repository"**
 

diff --git a/docs/code/worker.md b/docs/code/worker.md
@@ -3,7 +3,7 @@ title: "Worker Daemon"
 description: "Run devintern as a single long-running worker that reacts to PR reviews and tracker changes"
 section: "Server Automation"
 order: 0
-dateModified: 2026-08-04
+dateModified: 2026-08-17
 ---
 
 # Worker Daemon
@@ -106,7 +106,7 @@ Guardrails apply before the agent acts:
 - The worker never force-pushes; if a human pushed to the branch meanwhile, the push is rejected instead of overwriting.
 - Mentions posted before the worker first started are not dug up.
 
-Mention matching requires a resolvable bot identity, so this feature needs GitHub App auth (the same requirement as webhook mention handling).
+Mention matching requires a resolvable bot identity, so this team/automation feature needs GitHub App auth (`GITHUB_APP_ID` plus a private key — the same requirement as webhook mention handling). A personal `GITHUB_TOKEN` is enough for review polling on the agent's own PRs, but not for `@mentions` on other people's PRs. See [Configuration](./configuration.md#github-authentication) and [Pricing](https://devintern.com/pricing/).
 
 ## How events are handled
 

diff --git a/docs/code/workspaces.md b/docs/code/workspaces.md
@@ -3,7 +3,7 @@ title: "Workspaces (Multi-Repo Fleet)"
 description: "Drive many repositories with one devintern worker: a single workspace.toml, routing rules, and per-task worktrees"
 section: "Server Automation"
 order: 1
-dateModified: 2026-07-04
+dateModified: 2026-08-17
 ---
 
 # Workspaces (Multi-Repo Fleet)
@@ -78,7 +78,7 @@ devintern workspace import
 
 ## Environment
 
-Secrets live in one shared `~/.devintern/.env` (tracker credentials, `GITHUB_TOKEN`, agent settings). Each repo can layer more on top:
+Secrets live in one shared `~/.devintern/.env` (tracker credentials, `GITHUB_TOKEN` and/or GitHub App credentials, agent settings). Each repo can layer more on top:
 
 1. Shared workspace `.env`
 2. The repo's `env_file` (if set)

diff --git a/packages/code/.env.example b/packages/code/.env.example
@@ -26,9 +26,11 @@ JIRA_API_TOKEN=your-api-token-here
 # LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
 
 # GitHub Issues Configuration (required when TASK_TRACKER=github)
-# Reuses GITHUB_TOKEN from the Pull Request Integration section below
-# (the token needs the 'repo' scope, or 'Issues: Read and write' for
-# fine-grained tokens). Additionally set the target repository:
+# Needs a personal access token (personal / interactive) — GitHub App
+# credentials cannot substitute.
+# The same GITHUB_TOKEN is used for pull request creation below
+# (classic: 'repo' scope; fine-grained: Issues + Pull requests Read/write).
+# GITHUB_TOKEN=your-github-token-here
 # GITHUB_REPO=owner/repo
 # Optional: comma-separated status label names treated as mutually exclusive.
 # When transitioning an issue, other labels in this list are removed.
@@ -104,32 +106,42 @@ AGENT_HARNESS=claude-code
 # Optional: Enable verbose logging by default
 # VERBOSE=true
 
-# Optional: Pull Request Integration
+# Optional: GitHub authentication (PRs, worker reviews, @mentions)
 #
-# Option 1: GitHub Personal Access Token (for individual users)
-# Create at: https://github.com/settings/tokens
-# Required permissions:
-#   - Classic token: 'repo' scope (or 'public_repo' for public repos only)
-#   - Fine-grained token (recommended): 'Pull requests: Read and write' + 'Contents: Read'
-# GITHUB_TOKEN=your-github-token-here
+# Personal / interactive (free CLI): GITHUB_TOKEN
+# Team / unattended automation: GitHub App (GITHUB_APP_ID + private key)
+# See https://devintern.com/pricing/
+# Complementary, not alternatives. Unattended runs also need LICENSE_KEY.
 #
-# Option 2: GitHub App Authentication (for organizations)
-# Each organization creates their own GitHub App for centralized control.
-# Create at: https://github.com/settings/apps (or your org's settings)
-# Required App permissions:
-#   - Repository permissions:
-#     - Contents: Read (to check branches)
-#     - Pull requests: Read and write (to create PRs)
-# After creating the App, generate a private key and install the App on your repositories.
+#   GITHUB_TOKEN (personal access token)
+#     Personal / interactive CLI use, and required for TASK_TRACKER=github
+#     (Issues). App credentials cannot substitute.
+#     Enough for --create-pr and worker review polling on the agent's own PRs.
+#     Create at: https://github.com/settings/tokens
+#     Classic: 'repo' scope (or 'public_repo' for public repos only)
+#     Fine-grained: 'Pull requests: Read and write' + 'Contents: Read'
+#     (add 'Issues: Read and write' when TASK_TRACKER=github)
+# GITHUB_TOKEN=your-github-token-here
 #
+#   GitHub App (GITHUB_APP_ID + private key)
+#     Team / unattended automation: @mention matching on any PR (worker
+#     mention sweep and webhook / `devintern worker --listen`) and slug[bot]
+#     commit attribution.
+#     Also creates PRs when no GITHUB_TOKEN is set.
+#     Both GITHUB_APP_ID and a private key are required; ID alone is ignored.
+#     Create at: https://github.com/settings/apps (or your org's settings)
+#     Install the App on your repositories after generating a private key.
+#     Permissions: Contents (Read), Pull requests (Read and write).
+#     Mentions/webhooks also need review-comment + issue-comment permissions:
+#     https://devintern.com/docs/code/github-integration
 # GITHUB_APP_ID=123456
-# Private key can be provided as a file path:
 # GITHUB_APP_PRIVATE_KEY_PATH=/path/to/your-app.private-key.pem
-# Or as base64-encoded content (useful for CI/CD environments):
-# To encode: base64 -i your-key.pem (macOS) or base64 -w 0 your-key.pem (Linux)
+# Or base64 (CI/CD): base64 -i your-key.pem (macOS) / base64 -w 0 (Linux)
 # GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==
 #
-# Note: If both GITHUB_TOKEN and GitHub App credentials are set, GITHUB_TOKEN takes precedence.
+# Precedence when both are set:
+#   CLI / PR creation: GITHUB_TOKEN is used.
+#   worker --listen / webhook server: the App is used (bot identity).
 
 # Bitbucket app password for creating pull requests
 # Create at: https://bitbucket.org/account/settings/app-passwords/

diff --git a/packages/code/CLAUDE.md b/packages/code/CLAUDE.md
@@ -30,12 +30,13 @@ This file provides guidance to Claude Code when working with this repository.
 - `ASANA_API_TOKEN` - Asana personal access token (required when `TASK_TRACKER=asana`); optional `ASANA_DEFAULT_PROJECT_GID`, `ASANA_STORY_POINTS_FIELD`
 - `AZURE_DEVOPS_ORG`, `AZURE_DEVOPS_PAT`, `AZURE_DEVOPS_PROJECT` - Azure DevOps credentials (required when `TASK_TRACKER=azure-devops`)
 - `LINEAR_API_KEY` - Linear personal API key (required when `TASK_TRACKER=linear`)
-- `GITHUB_REPO` - Target `owner/repo` for GitHub Issues (required when `TASK_TRACKER=github`; reuses `GITHUB_TOKEN`)
+- `GITHUB_REPO` - Target `owner/repo` for GitHub Issues (required when `TASK_TRACKER=github`; requires `GITHUB_TOKEN`, App credentials cannot substitute)
 - `GITHUB_STATUS_LABELS` - Optional comma-separated mutually-exclusive status label names for GitHub transitions
 - `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` - JIRA credentials
 - `TRELLO_API_KEY`, `TRELLO_API_TOKEN` - Trello credentials (required when `TASK_TRACKER=trello`)
 - `TRELLO_DEFAULT_BOARD_ID` - Optional Trello board ID for settings lookup and status transitions
-- `GITHUB_TOKEN` or `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY_PATH` - GitHub auth
+- `GITHUB_TOKEN` - Personal / interactive GitHub PAT (required for `TASK_TRACKER=github`; enough for free CLI PRs and own-PR review polling)
+- `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY_BASE64` - Team / unattended-automation GitHub App (required for `@mention` matching and `slug[bot]` commits; CLI uses token first, worker `--listen` uses App first). See https://devintern.com/pricing/
 - `BITBUCKET_TOKEN` - Bitbucket auth
 - `WEBHOOK_SECRET` - GitHub webhook verification
 - `DEVINTERN_OUTPUT_DIR` - Output directory (default: `/tmp/devintern-tasks`)

diff --git a/packages/code/ENV_SETUP.md b/packages/code/ENV_SETUP.md
@@ -49,13 +49,36 @@ Configure status transitions in `.devintern-code/settings.json` using the board
 }
 ```
 
-## Optional Environment Variables (PR Integration)
+## Optional Environment Variables (GitHub / PR Integration)
+
+**Personal / interactive:** a `GITHUB_TOKEN` (personal access token). Enough for free CLI use from your terminal.
+
+**Team / unattended automation:** a GitHub App (`GITHUB_APP_ID` plus a private key). Needed for `@mention` matching, `devintern worker --listen` / webhooks, and `slug[bot]` commit attribution. Unattended runs also need a `LICENSE_KEY`. See [Pricing](https://devintern.com/pricing/).
+
+The two credentials are complementary, not drop-in replacements. A team setup that also uses GitHub Issues as the tracker still needs `GITHUB_TOKEN`.
+
+| What you want | Need |
+| --- | --- |
+| Implement tickets and open PRs from the CLI (personal) | `GITHUB_TOKEN` |
+| Use GitHub Issues as the task tracker (`TASK_TRACKER=github`) | `GITHUB_TOKEN` (the App cannot substitute) |
+| Worker review polling on the agent's own PRs | `GITHUB_TOKEN` (solo) or GitHub App (if already configured) |
+| `@mention` the bot on any PR (worker sweep or webhook) | GitHub App (`GITHUB_APP_ID` + private key) |
+| Commits attributed to `slug[bot]` | GitHub App |
+
+Set both when you run mention-driven automation and also use GitHub Issues as a tracker.
+
+**Precedence when both are set:**
+
+- CLI and PR creation use `GITHUB_TOKEN`
+- `devintern worker --listen` and the webhook server prefer the App so the bot identity resolves
+
+Do not set `GITHUB_APP_ID` without `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY_BASE64`. The ID alone is ignored for auth, but the worker treats it as "GitHub credentials present."
 
 ```bash
-# Option 1: GitHub Personal Access Token (for individual users)
+# Personal access token (required for TASK_TRACKER=github)
 GITHUB_TOKEN=your-github-token-here
 
-# Option 2: GitHub App Authentication (for organizations)
+# GitHub App (required for @mentions / slug[bot] attribution)
 GITHUB_APP_ID=123456
 GITHUB_APP_PRIVATE_KEY_PATH=/path/to/private-key.pem
 # Or base64-encoded: GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==
@@ -66,9 +89,9 @@ BITBUCKET_TOKEN=your-bitbucket-token    # For Bitbucket PR creation
 
 **Note:** Task tracker status transitions are configured per-project in `settings.json`. The file supports tracker-specific sections (e.g., `jira`, `linear`, `trello`) based on the `TASK_TRACKER` environment variable.
 
-### Option 1: GitHub Personal Access Token
+### GitHub Personal Access Token
 
-When creating a GitHub personal access token, you need the following permissions:
+For personal / interactive CLI use. When creating a GitHub personal access token, you need the following permissions:
 
 **Classic Personal Access Token:**
 
@@ -79,6 +102,7 @@ When creating a GitHub personal access token, you need the following permissions
 
 - **Pull requests**: Read and write
 - **Contents**: Read (needed to read branch info for the PR)
+- **Issues**: Read and write (only when `TASK_TRACKER=github`)
 
 To create a GitHub token:
 
@@ -88,23 +112,25 @@ To create a GitHub token:
 4. Grant the permissions listed above
 5. Set the token as `GITHUB_TOKEN` in your `.env` file
 
-### Option 2: GitHub App Authentication
+### GitHub App Authentication
 
-For organizations that want centralized control, create a GitHub App instead of using individual tokens.
+For team / unattended automation (mention-driven worker, webhook / `worker --listen`, `slug[bot]` attribution), create a GitHub App.
 
-**Required App permissions:**
+**Required App permissions (PR creation):**
 
 - **Contents**: Read (to check branches)
 - **Pull requests**: Read and write (to create PRs)
 
+Mention matching and the webhook server also need **Pull request review comments** and **Issue comments**. See [GitHub Integration](https://devintern.com/docs/code/github-integration).
+
 **Setup steps:**
 
 1. Go to your organization's Settings → Developer settings → GitHub Apps → New GitHub App
 2. Set repository permissions: Contents (Read), Pull requests (Read and write)
-3. Disable webhooks (not needed)
+3. Disable webhooks unless you are running `devintern worker --listen`
 4. Generate a private key after creating the App
 5. Install the App on your repositories
-6. Configure in your `.env`:
+6. Configure **both** the ID and the key in your `.env`:
    ```bash
    GITHUB_APP_ID=123456
    GITHUB_APP_PRIVATE_KEY_PATH=/path/to/private-key.pem
@@ -119,8 +145,6 @@ GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==
 
 To encode: `base64 -i your-key.pem` (macOS) or `base64 -w 0 your-key.pem` (Linux)
 
-**Note:** If both `GITHUB_TOKEN` and GitHub App credentials are set, `GITHUB_TOKEN` takes precedence.
-
 ### Bitbucket Token Permissions
 
 When creating a Bitbucket app password: