Skip to content

[docs] Update documentation for v0.8.12 features #776

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
danielmeppiel wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −3
Open

[docs] Update documentation for v0.8.12 features #776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/src/content/docs/getting-started/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence says proxy mode covers "GitHub API archive downloads" and "codeload.github.com-style tarball URLs". The proxy code-path actually builds GitHub/GitLab/codeload-style archive paths (zip) for Artifactory (see build_artifactory_archive_url()), not GitHub API tarball endpoints. Recommend rewording to avoid implying GitHub API tarball support here, and to describe the codeload zip archive path behavior more precisely.

Suggested change
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.
When `PROXY_REGISTRY_URL` is set, APM rewrites archive downloads to go through the proxy and sends `PROXY_REGISTRY_TOKEN` as the `Authorization: Bearer` header instead of the GitHub PAT. In proxy mode, APM builds Artifactory-compatible GitHub, GitLab, and `codeload.github.com`-style zip archive paths, so JFrog Artifactory proxies configured for those archive paths work correctly in proxy-only mode.

Copilot uses AI. Check for mistakes.

### Lockfile and reproducibility

Expand Down Expand Up @@ -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:
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling is inconsistent with the rest of this page (which uses "organization"). Consider changing "organisation" to "organization" for consistency.

Suggested change
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:
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 organization. ADO does not fall back to unauthenticated access -- all ADO installs require an explicit PAT:

Copilot uses AI. Check for mistakes.

```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.
Expand Down
1 change: 1 addition & 0 deletions docs/src/content/docs/guides/compilation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example implies apm compile --target minimal is a valid explicit invocation. In the current CLI (src/apm_cli/commands/compile/cli.py), --target choices do not include minimal, and target detection does not honor explicit_target="minimal", so the command will fail. Either drop the explicit --target minimal example or update the implementation to support it.

Copilot uses AI. Check for mistakes.
```

You can set a persistent target in `apm.yml`:
Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/reference/cli-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

apm compile does not currently accept --target minimal (Click choices in src/apm_cli/commands/compile/cli.py omit minimal, and detect_target() does not handle explicit_target == "minimal"). As written, this option list + description will mislead users; either remove minimal from the explicit --target list (and document it as an auto-detected fallback), or update the CLI implementation to accept/route explicit minimal.

Suggested change
- `-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.
- `-t, --target [vscode|agents|claude|codex|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. If no target is specified, APM auto-detects the best target and may fall back to `minimal`, which generates `AGENTS.md` only with no folder integration.

Copilot uses AI. Check for mistakes.
- `--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
Expand Down
Loading