fix: correct token prefix mapping — EMU uses standard PAT prefixes

ghu_ is OAuth user-to-server (e.g. gh auth login), NOT EMU.
EMU users get regular ghp_ (classic) or github_pat_ (fine-grained)
tokens — there is no prefix that identifies EMU. EMU is a property
of the account, not the token format.

Changes:
- detect_token_type: ghu_ → 'oauth', gho_ → 'oauth',
  ghs_/ghr_ → 'github-app' (was all 'classic')
- build_error_context: replace token_type=='emu' check with
  host-based heuristics (*.ghe.com → enterprise msg, github.com →
  SAML/EMU mention)
- Auth docs: remove ghu_ as EMU prefix, clarify EMU uses standard PATs
- Agent persona: correct token prefix reference table
- Tests: update detect_token_type + build_error_context assertions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

.github/agents/auth-expert.agent.md

@@ -13,8 +13,8 @@ You are an expert on Git hosting authentication across GitHub.com, GitHub Enterp
 
 ## Core Knowledge
 
-- **Token types**: Fine-grained PATs (`github_pat_`), classic PATs (`ghp_`), EMU tokens (`ghu_`), OAuth tokens (`gho_`), server tokens (`ghs_`)
-- **GitHub EMU constraints**: Enterprise-scoped, cannot access public github.com, `ghu_` prefix
+- **Token prefixes**: Fine-grained PATs (`github_pat_`), classic PATs (`ghp_`), OAuth user-to-server (`ghu_` — e.g. `gh auth login`), OAuth app (`gho_`), GitHub App install (`ghs_`), GitHub App refresh (`ghr_`)
+- **EMU (Enterprise Managed Users)**: Use standard PAT prefixes (`ghp_`, `github_pat_`). There is NO special prefix for EMU — it's a property of the account, not the token. EMU tokens are enterprise-scoped and cannot access public github.com repos. EMU orgs can exist on github.com or *.ghe.com.
 - **Host classification**: github.com (public), *.ghe.com (no public repos), GHES (`GITHUB_HOST`), ADO
 - **Git credential helpers**: macOS Keychain, Windows Credential Manager, `gh auth`, `git credential fill`
 - **Rate limiting**: 60/hr unauthenticated, 5000/hr authenticated, primary (403) vs secondary (429)
@@ -38,7 +38,7 @@ When reviewing or writing auth code:
 
 ## Common Pitfalls
 
-- EMU PATs on public github.com repos → will fail silently
+- EMU PATs on public github.com repos → will fail silently (you cannot detect EMU from prefix)
 - `git credential fill` only resolves per-host, not per-org
 - `_build_repo_url` must accept token param, not use instance var
 - Windows: `GIT_ASKPASS` must be `'echo'` not empty string

docs/src/content/docs/getting-started/authentication.md

@@ -57,13 +57,13 @@ Per-org tokens take priority over global tokens. Use this when different orgs re
 
 ## Enterprise Managed Users (EMU)
 
-EMU orgs can live on **github.com** (e.g., `contoso-microsoft`) or on **GHE Cloud Data Residency** (`*.ghe.com`). EMU tokens (`ghu_` prefix) are enterprise-scoped and cannot access public repos on github.com.
+EMU orgs can live on **github.com** (e.g., `contoso-microsoft`) or on **GHE Cloud Data Residency** (`*.ghe.com`). EMU tokens are standard PATs (`ghp_` classic or `github_pat_` fine-grained) — there is no special prefix. They are scoped to the enterprise and cannot access public repos on github.com.
 
 If your manifest mixes enterprise and public packages, use separate tokens:
 
 ```bash
-export GITHUB_APM_PAT_CONTOSO_MICROSOFT=ghu_emu_token  # EMU org (any host)
-export GITHUB_APM_PAT=ghp_public_token                  # public github.com repos
+export GITHUB_APM_PAT_CONTOSO_MICROSOFT=github_pat_enterprise_token  # EMU org (any host)
+export GITHUB_APM_PAT=ghp_public_token                               # public github.com repos
 ```
 
 ### GHE Cloud Data Residency (`*.ghe.com`)
@@ -128,7 +128,7 @@ Authorize your PAT for SSO at [github.com/settings/tokens](https://github.com/se
 
 ### EMU token can't access public repos
 
-EMU tokens (`ghu_` prefix) are enterprise-scoped and cannot access public github.com repos. Use a standard PAT for public repos alongside your EMU token — see [Enterprise Managed Users (EMU)](#enterprise-managed-users-emu) above.
+EMU PATs use standard prefixes (`ghp_`, `github_pat_`) — there is no EMU-specific prefix. They are enterprise-scoped and cannot access public github.com repos. Use a standard PAT for public repos alongside your EMU PAT — see [Enterprise Managed Users (EMU)](#enterprise-managed-users-emu) above.
 
 ### Diagnosing auth failures
 
@@ -138,7 +138,7 @@ Run with `--verbose` to see the full resolution chain:
 apm install --verbose your-org/package
 ```
 
-The output shows which env var matched (or `none`), the detected token type (`fine-grained`, `classic`, `emu`), and the host classification (`github`, `ghe_cloud`, `ghes`, `ado`, `generic`).
+The output shows which env var matched (or `none`), the detected token type (`fine-grained`, `classic`, `oauth`, `github-app`), and the host classification (`github`, `ghe_cloud`, `ghes`, `ado`, `generic`).
 
 ### Git credential helper not found
 

src/apm_cli/core/auth.py

@@ -67,7 +67,7 @@ class AuthContext:
 
     token: Optional[str]
     source: str  # e.g. "GITHUB_APM_PAT_ORGNAME", "GITHUB_TOKEN", "none"
-    token_type: str  # "fine-grained", "classic", "emu", "ado", "artifactory", "unknown"
+    token_type: str  # "fine-grained", "classic", "oauth", "github-app", "unknown"
     host_info: HostInfo
     git_env: dict = field(compare=False, repr=False)
 
@@ -142,15 +142,33 @@ def classify_host(host: str) -> HostInfo:
 
     @staticmethod
     def detect_token_type(token: str) -> str:
-        """Classify a token string by its prefix."""
+        """Classify a token string by its prefix.
+
+        Note: EMU (Enterprise Managed Users) tokens use standard PAT
+        prefixes (``ghp_`` or ``github_pat_``).  There is no prefix that
+        identifies a token as EMU-scoped — that's a property of the
+        account, not the token format.
+
+        Prefix reference (docs.github.com):
+        - ``github_pat_`` → fine-grained PAT
+        - ``ghp_``        → classic PAT
+        - ``ghu_``        → OAuth user-to-server (e.g. ``gh auth login``)
+        - ``gho_``        → OAuth app token
+        - ``ghs_``        → GitHub App installation (server-to-server)
+        - ``ghr_``        → GitHub App refresh token
+        """
         if token.startswith("github_pat_"):
             return "fine-grained"
         if token.startswith("ghp_"):
             return "classic"
         if token.startswith("ghu_"):
-            return "emu"
-        if token.startswith(("gho_", "ghs_", "ghr_")):
-            return "classic"
+            return "oauth"
+        if token.startswith("gho_"):
+            return "oauth"
+        if token.startswith("ghs_"):
+            return "github-app"
+        if token.startswith("ghr_"):
+            return "github-app"
         return "unknown"
 
     # -- core resolution ----------------------------------------------------
@@ -264,15 +282,24 @@ def build_error_context(
 
         if auth_ctx.token:
             lines.append(f"Token was provided (source: {auth_ctx.source}, type: {auth_ctx.token_type}).")
-            if auth_ctx.token_type == "emu":
+            host_info = self.classify_host(host)
+            if host_info.kind == "ghe_cloud":
                 lines.append(
-                    "EMU tokens are scoped to your enterprise and cannot "
-                    "access public github.com repos."
+                    "GHE Cloud Data Residency hosts (*.ghe.com) require "
+                    "enterprise-scoped tokens. Ensure your PAT is authorized "
+                    "for this enterprise."
+                )
+            elif host.lower() == "github.com":
+                lines.append(
+                    "If your organization uses SAML SSO or is an EMU org, "
+                    "ensure your PAT is authorized at "
+                    "https://github.com/settings/tokens"
+                )
+            else:
+                lines.append(
+                    "If your organization uses SAML SSO, you may need to "
+                    "authorize your token at https://github.com/settings/tokens"
                 )
-            lines.append(
-                "If your organization uses SAML SSO, you may need to "
-                "authorize your token at https://github.com/settings/tokens"
-            )
         else:
             lines.append("No token available.")
             lines.append(

tests/integration/test_auth_resolver.py

@@ -286,13 +286,13 @@ def test_no_token_suggests_env_vars(self):
             assert "GITHUB_APM_PAT" in msg
             assert "--verbose" in msg
 
-    def test_emu_token_warns(self):
-        with patch.dict(os.environ, {"GITHUB_APM_PAT": "ghu_emu_abc"}, clear=True), _NO_GIT_CRED:
+    def test_github_com_error_mentions_emu_sso(self):
+        """github.com errors should mention EMU/SSO as possible causes."""
+        with patch.dict(os.environ, {"GITHUB_APM_PAT": "ghp_some_token"}, clear=True), _NO_GIT_CRED:
             resolver = AuthResolver()
             msg = resolver.build_error_context("github.com", "clone")
 
-            assert "EMU" in msg
-            assert "enterprise" in msg.lower()
+            assert "EMU" in msg or "SAML" in msg
 
     def test_org_hint_included(self):
         with patch.dict(os.environ, {"GITHUB_APM_PAT": "ghp_tok"}, clear=True), _NO_GIT_CRED:

tests/unit/test_auth.py

@@ -60,17 +60,17 @@ def test_fine_grained(self):
     def test_classic(self):
         assert AuthResolver.detect_token_type("ghp_abc123") == "classic"
 
-    def test_emu(self):
-        assert AuthResolver.detect_token_type("ghu_abc123") == "emu"
+    def test_oauth_user(self):
+        assert AuthResolver.detect_token_type("ghu_abc123") == "oauth"
 
-    def test_oauth(self):
-        assert AuthResolver.detect_token_type("gho_abc123") == "classic"
+    def test_oauth_app(self):
+        assert AuthResolver.detect_token_type("gho_abc123") == "oauth"
 
-    def test_server_to_server(self):
-        assert AuthResolver.detect_token_type("ghs_abc123") == "classic"
+    def test_github_app_install(self):
+        assert AuthResolver.detect_token_type("ghs_abc123") == "github-app"
 
-    def test_refresh(self):
-        assert AuthResolver.detect_token_type("ghr_abc123") == "classic"
+    def test_github_app_refresh(self):
+        assert AuthResolver.detect_token_type("ghr_abc123") == "github-app"
 
     def test_unknown(self):
         assert AuthResolver.detect_token_type("some-random-token") == "unknown"
@@ -328,14 +328,27 @@ def test_no_token_message(self):
                 assert "GITHUB_APM_PAT" in msg
                 assert "--verbose" in msg
 
-    def test_emu_detection(self):
-        with patch.dict(os.environ, {"GITHUB_APM_PAT": "ghu_emu_token"}, clear=True):
+    def test_ghe_cloud_error_context(self):
+        """*.ghe.com errors mention enterprise-scoped tokens."""
+        with patch.dict(os.environ, {"GITHUB_APM_PAT_CONTOSO": "token"}, clear=True):
+            with patch.object(
+                GitHubTokenManager, "resolve_credential_from_git", return_value=None
+            ):
+                resolver = AuthResolver()
+                msg = resolver.build_error_context(
+                    "contoso.ghe.com", "clone", org="contoso"
+                )
+                assert "enterprise" in msg.lower()
+
+    def test_github_com_error_mentions_emu(self):
+        """github.com errors mention EMU/SSO possibility."""
+        with patch.dict(os.environ, {"GITHUB_APM_PAT": "ghp_token"}, clear=True):
             with patch.object(
                 GitHubTokenManager, "resolve_credential_from_git", return_value=None
             ):
                 resolver = AuthResolver()
                 msg = resolver.build_error_context("github.com", "clone")
-                assert "EMU" in msg
+                assert "EMU" in msg or "SAML" in msg
 
     def test_multi_org_hint(self):
         with patch.dict(os.environ, {"GITHUB_APM_PAT": "token"}, clear=True):