From 938ebfadc9740dc292a327a3be00a9cae01d171a Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 20 Apr 2026 03:57:24 +0000 Subject: [PATCH] docs: update documentation for v0.8.12 features - cli-commands.md: clarify --target claude creates .claude/ on first run - cli-commands.md: add 'minimal' to --target values in apm compile options - compilation.md: add --target minimal example to code block - authentication.md: add ADO troubleshooting entry for auth failures - authentication.md: note codeload.github.com archive URL proxy support Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/getting-started/authentication.md | 13 ++++++++++++- docs/src/content/docs/guides/compilation.md | 1 + docs/src/content/docs/reference/cli-commands.md | 4 ++-- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/src/content/docs/getting-started/authentication.md b/docs/src/content/docs/getting-started/authentication.md index 8768531e1..ffde87daa 100644 --- a/docs/src/content/docs/getting-started/authentication.md +++ b/docs/src/content/docs/getting-started/authentication.md @@ -175,7 +175,7 @@ export PROXY_REGISTRY_ONLY=1 # optional -- enforces proxy-only mode apm install ``` -When `PROXY_REGISTRY_URL` is set, APM rewrites download URLs to go through the proxy and sends `PROXY_REGISTRY_TOKEN` as the `Authorization: Bearer` header instead of the GitHub PAT. +When `PROXY_REGISTRY_URL` is set, APM rewrites download URLs to go through the proxy and sends `PROXY_REGISTRY_TOKEN` as the `Authorization: Bearer` header instead of the GitHub PAT. This includes both GitHub API archive downloads and `codeload.github.com`-style tarball URLs, so JFrog Artifactory proxies configured against `codeload.github.com` work correctly in proxy-only mode. ### Lockfile and reproducibility @@ -282,6 +282,17 @@ git config --global credential.helper osxkeychain # macOS gh auth login # GitHub CLI ``` +### Azure DevOps authentication errors + +If `apm install` fails with an ADO-specific error (e.g., `Authentication failed for dev.azure.com`), ensure `ADO_APM_PAT` is set and has **Code (Read)** permission for the target organisation. ADO does not fall back to unauthenticated access -- all ADO installs require an explicit PAT: + +```bash +export ADO_APM_PAT=your_ado_pat +apm install dev.azure.com/myorg/myproject/myrepo +``` + +See [Azure DevOps](#azure-devops) above for PAT creation steps. + ### SSH connection hangs on corporate/VPN networks When no token is available, APM tries SSH before falling back to plain HTTPS. Firewalls that silently drop SSH packets (port 22) can make `apm install` appear to hang. APM sets `GIT_SSH_COMMAND="ssh -o ConnectTimeout=30"` so SSH attempts fail within 30 seconds and the fallback proceeds to HTTPS with git credential helpers. diff --git a/docs/src/content/docs/guides/compilation.md b/docs/src/content/docs/guides/compilation.md index 23de213bf..01123cf19 100644 --- a/docs/src/content/docs/guides/compilation.md +++ b/docs/src/content/docs/guides/compilation.md @@ -31,6 +31,7 @@ apm compile # Auto-detects target from project structure apm compile --target copilot # Force GitHub Copilot, Cursor, Gemini apm compile --target codex # Force Codex CLI apm compile --target claude # Force Claude Code, Claude Desktop +apm compile --target minimal # AGENTS.md only, no folder integration ``` You can set a persistent target in `apm.yml`: diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md index 1f93856ce..ffffeee3e 100644 --- a/docs/src/content/docs/reference/cli-commands.md +++ b/docs/src/content/docs/reference/cli-commands.md @@ -229,7 +229,7 @@ apm install --dry-run APM automatically detects which integrations to enable based on your project structure: - **VSCode integration**: Enabled when `.github/` directory exists -- **Claude integration**: Enabled when `.claude/` directory exists +- **Claude integration**: Enabled when `.claude/` directory exists (using `--target claude` explicitly creates `.claude/` even if it does not exist yet) - **Cursor integration**: Enabled when `.cursor/` directory exists - **OpenCode integration**: Enabled when `.opencode/` directory exists - All integrations can coexist in the same project @@ -1187,7 +1187,7 @@ apm compile [OPTIONS] **Options:** - `-o, --output TEXT` - Output file path (for single-file mode) -- `-t, --target [vscode|agents|claude|codex|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified. +- `-t, --target [vscode|agents|claude|codex|opencode|minimal|all]` - Target agent format. `agents` is an alias for `vscode`. `minimal` generates `AGENTS.md` only with no folder integration. Auto-detects if not specified. - `--chatmode TEXT` - Chatmode to prepend to the AGENTS.md file - `--dry-run` - Preview compilation without writing files (shows placement decisions) - `--no-links` - Skip markdown link resolution