[docs] Update documentation for v0.8.12 features#776
[docs] Update documentation for v0.8.12 features#776danielmeppiel wants to merge 1 commit intomainfrom
Conversation
- 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>
danielmeppiel
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
Documentation refresh for v0.8.12 release features, covering target behavior, compilation discoverability, and enterprise auth/proxy troubleshooting.
Changes:
- Clarifies Claude integration auto-detection and notes that explicit
--target claudebootstraps.claude/. - Documents
minimalas a compilation target and adds it to examples/CLI reference. - Expands authentication docs with ADO troubleshooting and clarifies registry proxy behavior for codeload-style archives.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/cli-commands.md | Updates CLI reference text for install auto-detection and compile --target options. |
| docs/src/content/docs/guides/compilation.md | Adds apm compile --target minimal to the quick-start examples. |
| docs/src/content/docs/getting-started/authentication.md | Adds ADO auth troubleshooting and expands proxy registry explanation (including codeload behavior). |
Copilot's findings
- Files reviewed: 3/3 changed files
- Comments generated: 4
| **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. |
There was a problem hiding this comment.
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.
| - `-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. |
| 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 |
There was a problem hiding this comment.
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.
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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.
| 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. |
|
|
||
| ### 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: |
There was a problem hiding this comment.
Spelling is inconsistent with the rest of this page (which uses "organization"). Consider changing "organisation" to "organization" for consistency.
| 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: |
Documentation Updates - 2026-04-20
This PR updates the documentation based on features shipped in v0.8.12 (released 2026-04-19, #774).
Features Documented
--target claudenow creates.claude/on first run, even when the directory does not already exist (fix: create target dir for explicit --target claude; content hash fallback when .git absent #763)apm compile --target minimaladded as an explicit, discoverable CLI invocation (apm compile --target codexis a silent no-op in distributed mode, leaving staleAGENTS.mdwith missing dependency instructions #766)codeload.github.comarchive URL proxy rewriting clarified in registry proxy docs ([fix] support codeload github archive urls for artifactory (#710) #712)Changes Made
docs/src/content/docs/reference/cli-commands.md:--target claudecreates.claude/even when absent (previously the wording implied the directory must pre-exist, actively misleading users bootstrapping a new Claude setup)minimalto the--targetflag value list forapm compile(it was missing, making--target minimalundiscoverable)docs/src/content/docs/guides/compilation.md:apm compile --target minimalto the example code blockdocs/src/content/docs/getting-started/authentication.md:ADO_APM_PATsetup (fix(auth): provide ADO-specific authentication error message for dev.… #742 added an actionable ADO-specific error message but there was no backing docs entry)codeload.github.com-style archive URLs are also rewritten ([fix] support codeload github archive urls for artifactory (#710) #712), which is critical for air-gapped/proxy-only environmentsMerged PRs Referenced
--target claudenot creating.claude/when absentapm compile --target codexis a silent no-op in distributed mode, leaving staleAGENTS.mdwith missing dependency instructions #766 - Fixapm compile --target codex/opencode/minimalsilent no-opcodeload.github.comarchive URLs in Artifactory proxyNotes
The only commit in the last 24 hours was the v0.8.12 release preparation (#774). All gaps identified are from features included in that release that were not yet reflected in the docs site.