# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.31.0] - 2026-09-15

### Added

- `apm init --discover` previews existing agent content; consented `--apply` declares supported local packages without changing source files, ready for a separate `apm install`. Builds on discovery work by @chkp-roniz. (#2937)
- Windows installation guidance now includes `winget install --id Microsoft.APM --exact --source winget` and updates through `winget upgrade` instead of `apm self-update`. (by @Gijsreyn, #2520)

### Changed

- **BREAKING:** Non-dry-run `apm install` now exits `1` when Agent Plugins v1 target exclusion leaves no package deployed; mixed installs that deploy another package still succeed. Install a direct skill subpath for the desired target or select `--target copilot` for native registration. (#2806)
- **BREAKING:** Re-vendored shared gh-aw APM imports require a concrete `target`; set the engine's target and recompile, with optional read-only `token-source: github-token` for same-repository private packages (`cascade` and APM 0.28.0 remain defaults). Dependency-policy matching now follows canonical repository casing, closing mixed-case deny bypasses; keep lowercase workarounds until all runners use APM 0.31.0 or later. (#2706)

### Fixed

- Git-subpath cache checkouts now preserve committed LF content regardless of host `core.autocrlf` settings; older unpinned cache shards rematerialize on the next install. (by @sergio-sisternes-epam, #2982)
- `apm uninstall` now preserves unmanaged Claude and Kiro skills when removing an MCP-only package whose lockfile has no deployed files. (by @mfroembgen, #2947)
- Private Git dependencies rewritten from HTTPS to SSH no longer fail the HTTP-header safety probe; that probe now runs only for HTTP(S) effective URLs. (by @arnaudoisel, #2906)
- GitLab `path:` dependencies now preserve the selected SSH transport, username, and port instead of silently using HTTPS; REST fallback requires an executed same-origin HTTPS attempt admitted by the transport policy. (#2939)
- Exact registry version selectors now prefer the matching published build, preventing selection of a different build with the same semantic version but different build metadata. (by @nadav-y, #2894)
- `apm install` again accepts `skills:` subsets from Git collections with nested `skills/<name>/SKILL.md` files but no root manifest or skill, without a `path:` workaround. (#2891)
- Registry `apm outdated` now separates installed `Current`, constraint-bound `Wanted`, and published `Latest`, so exact pins no longer hide newer releases. It leaves legacy lockfiles unchanged, while `apm update` continues respecting manifest constraints. (#2874)

### Security

- File-lock retry diagnostics no longer include paths or exception text that may contain secrets, while retaining retry counts and delays. (#2742)

## [0.30.0] - 2026-09-07

### Security

- **BREAKING:** Unix binary installs now require matching original publisher SHA-256 sidecars before extraction or execution, with no pip fallback after integrity failures. For historical releases or mirrors, select a release with sidecars or update the mirrored installer and publish the original publisher sidecars alongside its archives. (#2842)

### Changed

- **BREAKING:** Fresh Unix native installs default to `~/.local`, add `install.sh --prefix PATH`, and configure eligible bash/zsh/fish profiles without implicit `sudo`; set `APM_NO_MODIFY_PATH=1` to opt out of shell setup. Existing destinations are preserved, and root-owned or package-managed installs require their original administrator or package manager to update or uninstall before [migration](https://microsoft.github.io/apm/getting-started/installation/#unix-install-ownership-and-migration). (#2844)
- macOS onboarding now recommends Homebrew core (`brew install apm`, no tap) for existing Homebrew users, with `brew upgrade apm` for updates and visible standalone alternatives. (#2846)

### Fixed

- Public CLI release discovery can recover from a rejected environment token: one anonymous retry after a selected token's 401/non-rate-limit 403 only for canonical public APM metadata; metadata redirects require `APM_RELEASE_METADATA_URL` at the final JSON endpoint or a `VERSION` pin. (#2843)
- `apm cache prune` now counts only successfully deleted SHA groups, continues after removal errors, and exits `1` with failed paths and causes when pruning is incomplete. Fix permissions or release file locks, then rerun the command. (#2865)
- `apm prune` now exits `1` when orphan deletion fails, continues processing remaining packages, and retains failed packages' lockfile entries. Resolve the reported deletion errors and rerun `apm prune`. (#2863)
- `apm cache prune --days` now rejects negative ages before touching the cache, preventing accidental eviction from invalid input. (#2862)
- `apm cache prune` now retains recently reused Git checkouts by refreshing shared SHA-group recency when either a full or sparse variant is reused. (#2861)
- `apm uninstall` now preserves declarations and deployed ownership after package deletion failures, keeping retry and reinstall recovery available after partial removal. (#2860)
- Successful HTTP cache hits now refresh LRU recency without extending response freshness, retaining frequently used MCP registry responses. (#2859)
- `apm cache clean` now continues removing other entries after deletion errors, reports affected paths, and exits non-zero instead of claiming complete cleanup. Resolve permissions or file locks and retry; `--force` only skips confirmation. (#2864)

### Performance

- Dependency policy checks now reuse canonical dependency names across required-package and executable checks, avoiding repeated name computation without changing policy results. (by @aryansk, #2588)
- `apm compile` now reuses the resolved project base path during instruction matching and placement, avoiding repeated filesystem path resolution. (by @aryansk, #2587)

## [0.29.1] - 2026-09-06

### Security

- `apm install` and registry access now bind credentials to user-configured
  HTTPS destinations and reject redirects, insecure credential transport, and
  lockfile-altered endpoints. Inherited policy restrictions are preserved,
  executable approvals bind to canonical dependency identities, symlinked
  project deployment roots are rejected, and `git`/`gh` resolve outside the
  project tree. (#2810)

### Changed

- Hermes is now a stable explicit-only target, and state-mutating APM commands
  share one per-user cross-process lock to prevent concurrent updates from
  losing state. Global audit and cleanup now preserve same-named user
  configuration outside recorded runtime ownership. (by @lkshrk, #2655)
- Plain `apm install` now uses the repository-pinned `copilot` target for
  deterministic contributor installs. (by @tillig, #2771)

### Fixed

- `apm install` now keeps transitive plugin MCP launchers usable after publication and cached replay by resolving plugin-root placeholders from the published package directory. Lockfiles and MCP configurations reject remaining resolution-staging paths without echoing configuration values. (by @lkshrk, #2827)
- Git dependency downloads retry one narrowly classified HTTPS connection failure without changing credentials or transport. (#2839)
- `apm install` now preserves SSH transport for semver discovery, keeps
  inactive hooks when targets are not declared in the manifest, and honors
  explicitly configured HTTP registries during MCP integration. (#2814)
- Abandoned install transactions now release their state-update lock without
  releasing locks still owned by other operations. (#2817)
- `apm install` now fails before state writes when a host-qualified package
  path uses an unknown platform host, and routes all host/reference coordinate
  parsing through one canonical parser. (#2800)
- Release-blocking regressions in global compile, root context protection,
  lockfile unions, hooks, and deployed-file manifests are fixed. (#2804)
- `apm install` now performs a hash-verified cached APM 0.28
  marketplace-plugin upgrade before stale cleanup, preserving prior Claude and
  Codex deployments instead of deleting them. (#2787)
- `apm install` launched from Git hooks now isolates dependency Git operations
  from the invoking repository, preventing installs from detaching or mutating
  the caller's branch. Credential-bearing, insecure, and cross-host network
  rewrites now fail before network use. (#2759)
- Install, lock, and update commands now report authoritative outcomes instead
  of returning success after skipped or failed deployment work. (#2799)
- Primitive classification now consistently honors declaration-first package
  semantics across local bundles, plugins, and integrations. (#2797)
- Inactive experimental targets no longer influence manifest reconciliation or
  lockfile target unions. (#2791)
- `apm compile` now protects every target catalog's hand-authored root context
  file, including `GEMINI.md`, from replacement. (#2790)
- Windows users no longer get repeated line-ending churn when APM rewrites
  `apm.yml`; rewrites now produce deterministic LF output. (by @McNultyyy,
  #2675)
- `apm compile` now preserves hand-authored root context files, including
  `--root` destinations, instead of replacing them. (#2779)
- `apm uninstall` now removes MCP servers only from recorded owning runtimes,
  accepts JetBrains Copilot JSONC, and reports target cleanup failures after
  attempting every owner. (by @aryansk, #2591)
- `apm uninstall --global` now removes managed Copilot hook files from
  `~/.copilot/hooks/` while preserving user-authored hooks. (by @aryansk,
  #2559)
- `apm install --dry-run -g` no longer creates `~/.apm` when the user
  manifest is absent; preview state now stays temporary. (by @aryansk, #2592)
- Install dry runs now include LSP dependencies in their deployment previews.
  (by @aryansk, #2580)
- Install dry runs now include positional packages in their deployment
  previews. (#2664)
- `apm install` now preserves previously deployed skills when package
  integration is skipped instead of treating them as stale cleanup candidates.
  (#2758)
- `apm compile -g` now honors `target:` and `targets:` in `~/.apm/apm.yml`,
  limiting output to declared harnesses and avoiding stray `$HOME` directories
  when targets are configured. (by @tillig, #2772)
- Distributed `apm compile` now reconciles existing managed-section
  `AGENTS.md` files without overwriting hand-authored content, generates new
  placements safely, and never discovers, writes, or cleans content across
  nested Git repository or linked-worktree boundaries. (by @aryansk, #2578)
- Claude project LSP servers now load from a discoverable APM-managed plugin
  manifest instead of a path Claude Code ignored. Upgrade users can rerun
  `apm install --target claude`. (#2733)
- Repositories that publish plugin metadata alongside an eligible root
  `apm.yml` now install as APM packages; metadata-only manifests continue to
  select the plugin layout. (#2776)
- Legacy lockfile synthesis now leaves shared `.agents/` deployment paths
  unattributed instead of assigning them to Copilot's `.github/` target. (#2774)
- Packed Claude plugin commands now install as native Copilot
  `.github/prompts/*.prompt.md` files instead of `.github/commands/*.md`.
  (#2778)
- `apm install` no longer silently drops instruction Markdown whose
  unfenced bodies contain `---` horizontal rules. It now stops the whole package
  before deploying any primitive when instruction frontmatter is invalid YAML or
  decodes critical hidden characters. (by @manideep-malyala, #2666)
- OpenCode MCP generation now preserves safe passthrough fields while preventing
  custom fields from injecting the modeled `environment` alias. (by @aryansk,
  #2593)
- Generic marketplace Git now prevents platform tokens from reaching native
  credential-helper subprocesses while preserving HTTPS helper access. HTTP and
  HTTPS-to-HTTP rewrites suppress credentials. (by @aryansk, #2594)
- `apm install` now resolves `dependencies.mcp` entries against the registry
  selected by the shared registry precedence chain. (by @edenfunf, #2745)
- `apm pack --check-clean` is now read-only and detects marketplace drift
  without overwriting artifacts. Release pipelines that produce artifacts must
  run `apm pack` separately. (#2730)
- `apm update` now retains full-SHA pins without an eligible stable annotated
  semver tag while continuing unrelated updates. (#2667)
- `apm install --frozen` no longer reports repo-root Claude skills as
  lockfile drift in projects that also carry MCP state. (by @cffnpwr, #2446)
- `apm pack` now reports unavailable remote package metadata, exposes
  certifiability in JSON, prevents `--check-clean` from certifying degraded
  regeneration, and lets `--strict-metadata` fail before writes. (#2693)
- `apm install -g --mcp NAME` now creates or updates the user manifest and
  deploys only to global-capable runtimes instead of rejecting `--global`.
  Registry identities are validated before user-state writes. (#2734)
- Windows admin lifecycle policies now resolve from `%ProgramData%` instead of
  assuming `C:\ProgramData`, while retaining the historical fallback.
  (by @lukiod, #2686)
- Marketplace installs now materialize catalog-only LSP and MCP metadata
  without requiring a package manifest in the downloaded source. (by @lkshrk,
  #2709)
- Private `github.com` packages now populate the persistent Git cache through
  repository-scoped credential fallback without storing credentials in cache
  keys or remote URLs. (#2722)
- Plugin refreshes now keep the existing package and its registered hooks live
  while replacement content downloads and validates. Failed refreshes retain
  the prior package instead of accepting stale content. (#2723)
- Successful installs now safely clean up temporary backups left by interrupted
  lock-aware runs and inactive resolution staging directories. (#2720)
- `apm doctor` now reports malformed project executable-trust configuration
  under either `executables` or the deprecated `allowExecutables` key as an
  actionable informational warning instead of omitting the check. (#2719)
- Newly generated `apm.lock.yaml` files no longer include volatile
  `generated_at` metadata, preventing timestamp-only merge conflicts. (by
  @lachieh, #2616)
- Fully qualified `ssh://` marketplace URLs now retain their SSH username,
  host, and custom port through registration and Git fetching. (#2760)
- Explicit GitLab URLs now accept deep repository namespaces whose names match
  APM primitive directories, while an unambiguous `.git` repository boundary
  followed by a primitive path still fails before writes. (by @aryansk, #2581)
- Frozen Artifactory installs now fall back to commit archives when the primary
  archive endpoint is unavailable. (by @aryansk, #2582)
- Dot-prefixed marketplace paths are now classified as local sources instead of
  remote package coordinates. (by @mikemikimike, #2766)
- Plugin `.lsp.json` intake now accepts Copilot-dialect `fileExtensions` and
  `warmupTimeoutMs` aliases, preserving C# LSP setup from dotnet/skills.
  (by @normandev92, #2513)
- Git subdirectory dependencies with symlinks to files elsewhere in the same
  repository now install successfully where Git materializes symlinks; APM
  widens the checkout only when needed. (by @MohammedAlkindi, #2710)
- Manifestless hook packages now participate in audit MCP configuration views.
  (#2732)
- Generated managed-section footers now describe only content that APM actually
  owns. (#2731)
- UTF-8 BOMs no longer hide Markdown frontmatter fences during package parsing.
  (by @lukiod, #2685)

## [0.29.0] - 2026-08-30

### Added

- `apm install --target copilot` now registers portable Agent Plugins 1.0
  packages natively while keeping each plugin intact under `apm_modules/`.
  Copilot CLI `1.0.81` or newer can load the installed plugin without copies or
  `--plugin-dir`. (closes #2703, #2705)
- `apm install` now accepts `--trust-bin` and `--no-trust-bin` for
  per-invocation consent over marketplace-plugin executables. Non-interactive
  installs default to no deployment unless consent or policy permits it.
  (closes #1620, #2508)
- `apm pack --format agent-plugin` and
  `apm plugin init --format agent-plugin` now emit strict, portable Agent
  Plugins 1.0 bundles while preserving the existing Claude-compatible default.
  (closes #2522, #2654)
- The lifecycle scripts guide now documents the Windows admin-tier policy path
  alongside the Linux and macOS path. (by @WilliamK112, closes #2621, #2640)

### Changed

- **BREAKING:** A plugin `skills` declaration now exclusively controls which
  skills deploy. Declare every intended skill or remove the key to retain
  conventional `skills/` discovery; conventional containers deploy at the
  expected depth, while `"skills": []` deploys no skills.
  (by @edenfunf, closes #2530, #2537, #2540)

### Fixed

- Agent Plugin inventory on Windows now compares physical file bytes without
  CRLF translation, preventing valid assets from being rejected as changed
  during inventory. (#2694)
- GitLab organization-policy discovery now uses the valid `apm-policy` project
  convention and treats a missing policy project as no policy. (#2662)
- `apm audit` now compares only APM-owned entries in shared native hook configs,
  preserving user-authored hooks while still detecting altered APM hooks.
  (closes #2641, #2682)
- `apm install` and surviving-package reintegration now scan only deployable
  package content, preventing false-positive security blocks from source-only
  files. (by @aryansk, #2598)
- Root-declared plugin components no longer copy a plugin into its own staging
  tree, preventing recursive writes during `apm install`.
  (by @YoraiLevi, closes #2556, #2557)
- OpenCode global installs now deploy user-scope skills to its native config
  root, and `apm compile -g` retains scoped package instructions in the user
  `AGENTS.md`. (by @aryansk, #2596)
- Marketplace `sourceBase` and full HTTPS repository paths now preserve safe
  percent-encoded segments, enabling Azure DevOps project names such as
  `My%20Projects`. (by @aryansk, fixes #2554, #2584)
- `apm install --frozen` now hydrates git-sourced `apm_package` dependencies
  that declare MCP servers on a cold cache. (by @sergio-sisternes-epam,
  closes #2456, #2502)
- `apm install` now resolves virtual-subdirectory git semver ranges before
  literal-ref preflight while preserving registry version validation.
  (by @aryansk, closes #2514, #2590)
- `apm lock export --timestamp` now rejects malformed or timezone-naive values
  before they enter CycloneDX or SPDX metadata. (by @manideep-malyala, fixes
  #2659, #2660)
- Generated bundle and plugin metadata now uses deterministic LF line endings,
  keeping generated metadata byte-stable across operating systems.
  (by @WilliamK112, #2638)
- Lockfiles generated on Windows for marketplace-plugin / skill-subset git
  dependencies now pass `apm install --frozen` on Linux, and vice versa, by
  hashing synthetic manifests with deterministic LF line endings.
  (by @McNultyyy, closes #2619, #2620)
- Codex MCP configuration now accepts plain HTTP for loopback endpoints while
  retaining HTTPS for every non-loopback host.
  (by @normandev92, #2468)
- Azure DevOps organization-policy discovery now reads repository `_apm` from
  project `apm`, keeping direct and inherited policy coordinates consistent.
  (closes #2429, #2450)
- Hook commands such as `"${CLAUDE_PLUGIN_ROOT}"/hooks/probe.py` now rewrite to
  `"${CLAUDE_PLUGIN_ROOT}/hooks/probe.py"` and warn when a supported plugin-root
  placeholder remains unresolved instead of silently deploying a dead hook.
  (by @MohammedAlkindi, closes #2639, #2645)
- `apm audit --ci` now accepts valid local Claude-skill dependencies without an
  `apm.yml` while retaining strict package-shape validation.
  (by @lukiod, closes #2611, #2643)
- Copilot CLI and VS Code MCP configurations now route through separate adapter
  paths, preventing one target's configuration from being written for the
  other. (#2669)
- Private-repository installs no longer skip credential retry when Git emits
  localized diagnostics. (by @Naofel-eal, closes #2533, #2534)
- `compilation.source_attribution: false` now suppresses cosmetic annotations
  on distributed `AGENTS.md` targets as it already did for `CLAUDE.md`.
  (by @MohammedAlkindi, closes #2634, #2646)
- `apm uninstall --global` now cleans removed-only target files before deleting
  their ownership state while preserving files owned by surviving packages.
  (#2658)
- `apm pack --dry-run` now honors the same existing `plugin.json` overwrite
  policy as a real non-force pack, avoiding misleading write previews.
  (by @aryansk, #2583)
- `apm marketplace validate` now reports malformed plugin structure by JSON path
  and exits 1 instead of emitting misleading success output. (#2474)
- CLI help for compile, dependency updates, and MCP install now follows the
  target catalog and exposes the forwarded target and trust options.
  (by @sergio-sisternes-epam, #2499)
- `deployed-files-present` no longer false-positives on gitignored deploy
  paths (e.g. `.agents/`), enabling `apm audit --ci` to pass on a fresh
  checkout when deployed outputs are intentionally not committed.
  (by @sergio-sisternes-epam, closes #2452, #2496)
- YAML expansion guard no longer rejects large anchor-free lockfiles (150K+
  entries) with a false-positive "billion-laughs" error.
  (#2518)
- SSH-based installs now fail promptly with a useful error when a key needs an
  unavailable passphrase instead of hanging until timeout.
  (by @sergio-sisternes-epam, fixes #1976, #2360)

### Performance

- The contributor dashboard now refreshes GitHub every 15 minutes by default,
  backs off for at least one hour after rate limits, and caches unchanged PR
  enrichment, reducing scheduled GraphQL list traffic from 240 to 8 queries per
  hour. (by @sergio-sisternes-epam, #2679)
- `apm compile` now scopes literal `applyTo` walks to their roots, reducing
  matching work in large repositories without changing placement.
  (by @aryansk, #2595)
- Multi-target `apm compile` now reuses project placement analysis across
  targets, scaling like a single-target run without changing generated output.
  (closes #2482, #2486)

### Security

- Windows release binaries are now Authenticode-signed, preventing the Windows
  Defender false positive caused by unsigned PyInstaller bundles.
  (by @sergio-sisternes-epam, closes #2435, #2497)

### Removed

- Retired the credential-dependent roadmap project sync. Release commitments
  now live solely in the active milestone. (#2672)

## [0.28.0] - 2026-08-04

### Added

- New xAI Grok targets: `grok-build` deploys native `.grok/` rules, agents,
  commands, and skills alongside compiled `AGENTS.md` context, and the
  explicit-only experimental `grok-cloud` target deploys skills to project or
  user `.grok/skills/`. (closes #2419, #2420)
- Kiro IDE/CLI v3 now receives agents from `.apm/agents/` as Markdown files
  under `.kiro/agents/<relative-stem>.md`, forwarding only `description`,
  `model`, and `tools` frontmatter. Tools are permission-bearing, so APM fails
  closed with no partial write when a tool value falls outside Kiro's approved
  capability set. (closes #2089, #2440)
- Registry object-form dependencies (`- id: owner/repo`) now support `skills:`
  and `targets:` subset installs, matching git-longhand parity -- no need to
  switch to verbose git-longhand form just to narrow what gets deployed.
  Registry deps also serialize back to `apm.yml` as object-form entries instead
  of collapsing to a plain git string. (by @nadav-y, #2166)
- `apm pack --check-versions` now reads `plugin.json` for local Plugin
  collections without `apm.yml`; when present, `apm.yml` remains authoritative.
  (#2454)

### Fixed

- `apm install` now re-downloads an aliased dependency after its `ref:` changes
  in `apm.yml`. Previously the pinned-ref and already-resolved cache-reuse
  shortcuts skipped the fetch, so `apm_modules/<alias>/` and every primitive
  deployed from it stayed on the old revision. (#2484)
- `apm install --target all` no longer aborts on targets that have no MCP
  client, such as `grok-build`. Non-MCP targets are skipped with a note instead
  of raising `Unsupported client type`. (#2484)
- `apm outdated` no longer exits 1 when the Rich progress renderer fails. The
  command now owns its own `Console` instead of borrowing Rich's process-global
  singleton, and falls back to plain-text progress if rendering still raises.
  (#2507)
- `apm init` and install-time auto-bootstrap now reject empty or
  whitespace-only project names, falling back to `my-project` at a filesystem
  root. APM no longer writes an `apm.yml` that every later install, lock, or
  compile command rejects. (by @nadav-y, #2200)
- `apm pack` now treats `dependencies: {}` as a declared mapping and emits the
  local bundle; omitted or null `dependencies:` still produce no bundle.
  (closes #2431, #2458)
- `apm compile --clean` preserves APM-generated `AGENTS.md` files tracked by
  nested Git worktrees. (#2473)
- Required MCP runtime defaults are now overrideable prompts, while secret
  defaults remain hidden and VS Code OCI launchers resolve every runtime
  placeholder without writing secret values to `mcp.json`. (#2455)
- `apm marketplace audit --strict` now fails when a local marketplace source
  is skipped, so CI cannot report success after an incomplete local audit.
  (#2460)
- Claude project hooks now run reliably when Claude launches them outside the
  repository while keeping generated settings portable across clones.
  (closes #2408, #2442)
- Marketplace package sources now accept full HTTPS repository URLs with nested
  paths while retaining strict shorthand validation. (#2439)
- YAML-list `applyTo` entries now preserve every pattern during compilation
  and target-native instruction conversion, including explicitly targeted
  supported hidden tool roots. (#2441)
- `apm pack --check-clean` now honors `--marketplace-path` overrides.
  (closes #2427, #2461)
- `apm marketplace validate` now reports malformed plugin structures without
  rewriting the registered marketplace or its source manifest. (#2445)
- Azure DevOps policy discovery now uses the valid `apm` project and
  `apm-policy` repository for organization policy files, with a 404-only
  compatibility fallback for legacy `_apm/_apm` locations. (#2450)
- Release publication now excludes opt-in live ADO PAT tests and credentials; those tests fail closed in the Auth Acceptance workflow instead. (#2426)
- Release promotions now run marker-bounded lifecycle integration on macOS Intel
  while retaining the full corpus on macOS ARM and Linux, preventing Intel
  runner capacity timeouts. (#2423)
- Public `github.com` dependency installs now preserve caller-owned Git URL
  rewrites and transport policy across anonymous and authenticated retries;
  policy cache metadata and diagnostics also omit credentials embedded in
  direct policy URLs. (#2422)

### Performance

- Policy discovery now performs one remote lookup per discovery, compilation
  uses one project traversal plus in-memory directory indexes, and uninstall
  pre-indexes lockfile entries for marketplace lookup. (#2472)

## [0.27.0] - 2026-07-31

### Added

- `apm.lock.yaml` can now record `materialization_repo_url` separately from
  canonical dependency identity, preserving source casing in `apm_modules/` and
  generated links while safely migrating stale case-only paths. Reported by
  @rcollette. (#2409)

### Fixed

- `apm self-update` now downloads GitHub and GHES installers from the selected
  release tag and passes that same normalized version to the installer.
  Configured installer mirrors remain authoritative. (by @fallintoplace, #2026)
- `apm install --dry-run` no longer lists self-managed `includes: auto` files
  as removals, matching the real install behavior. (by @mia106dev, #2069)
- Repeated `apm install` runs now preserve unchanged MCP target mappings,
  deployment ownership, and lockfile timestamps instead of rewriting
  `apm.lock.yaml`. (#2306)
- Declared `apm.yml` targets now determine MCP lockfile ownership before local
  harness detection, so teammates no longer rewrite each other's target state.
  Reported by @rrazvd. (#2307)
- `apm lock` now defers disk deletion for dropped dependencies, preserving
  deployed files until normal install reconciliation can remove them safely.
  (by @atulya-singh, #2312)
- `apm audit --ci` can now hydrate a cold cache from trusted lockfile pins
  without mutating project state, closing false failures and false-green audit
  results. (by @hugoguitton-lucca, #2329)
- Consuming projects no longer inherit a dependency author's
  `devDependencies.mcp`; direct and transitive runtime MCP dependencies still
  propagate normally. (by @sergio-sisternes-epam, #2361)
- Package-declared targets now restrict primitive deployment without expanding
  project authorization, preventing target-specific hooks from leaking into
  sibling harnesses and cleaning stale owned entries on update.
  (by @sergio-sisternes-epam, #2362)
- Copilot and VS Code hook deployment now excludes generated `package.json` and
  nested JSON sidecars that recursive hook loaders could mistake for
  descriptors. (by @sergio-sisternes-epam, #2363)
- `apm update` and `apm update --force` now resolve mutable Git refs from the
  authenticated remote even when the local bare-repository cache is stale;
  normal installs retain cache reuse. (by @sergio-sisternes-epam, #2364)
- Marketplace semver resolution now honors the producer's `tagPattern` instead
  of assuming `{name}--v{version}`, while manifests without a pattern retain
  the legacy convention. (by @sergio-sisternes-epam, #2366)
- `apm audit` now reports deployed files that no lockfile entry claims as
  `unrecorded` drift; shared hook merge targets remain exempt.
  (by @salpers, #2380)
- MCP Registry v0.1 `oci` packages now render Docker launchers and follow the
  documented adapter package-selection order instead of falling through to
  npm or PyPI launchers. (by @edenfunf, #2385)
- VS Code container launchers now preserve MCP Registry v0.1 runtime arguments,
  including collected bind mounts, instead of falling back to a bare Docker
  command. (by @edenfunf, #2387)
- MCP-only projects now create `apm.lock.yaml` during normal install and audit
  cleanly on the first run; frozen install still fails without writing when
  state is missing or stale. (by @edenfunf, #2390)
- Copilot hooks now normalize lifecycle aliases to the documented
  `sessionStart` and `agentStop` keys while preserving Claude's native event
  names. Reported by @SaulMoro. (#2405)
- Public `github.com` dependencies now try anonymous HTTPS before credential
  resolution, avoiding repeated credential prompts while retaining private
  repository fallback. Reported by @RuiRomano. (#2406)
- Non-container npm, PyPI, and generic MCP launchers now preserve typed Registry
  v0.1 arguments while retaining legacy `value_hint` compatibility. (#2407)
- `apm install --target intellij` now writes MCP servers to the JetBrains
  Copilot plugin-read path, migrating only APM-owned entries and preserving user
  configuration. Reported by @xalvarez. (#2410)
- `apm uninstall` now accepts the portable `_local/<name>` key printed by
  `apm deps list` and rejects missing or ambiguous batches before writing.
  Reported by @sproott. (#2412)
- Saved targets from `apm config set target` now drive package, MCP, and LSP
  phases in `apm install` and `apm update`; failed required service writes exit
  nonzero with a next step instead of silently succeeding. Reported by
  @ryodocx. (#2414)

### Security

- On-prem Azure DevOps Server hosts are no longer misclassified as GitHub
  Enterprise Server when host settings overlap, keeping ADO credentials isolated
  end to end. (by @sergio-sisternes-epam, #2365)
- `apm audit` now scans every governed deploy-tree file for hidden Unicode,
  including files omitted from `apm.lock.yaml`; `--package` remains
  lockfile-scoped. (by @salpers, #2381)
- Corporate git security settings -- SSL CA pins (`http.sslCAInfo`), bare-repo
  protection, and inherited `GIT_CONFIG_*` hardening -- are now preserved when
  APM injects authorization headers for Git operations.
  (by @edenfunf, #2382)

## [0.26.0] - 2026-07-18

### Added

- APM now verifies Python HTTPS traffic against the operating-system trust store
  by default, with `APM_DISABLE_TRUSTSTORE=1` available for certifi-only
  behavior. Explicit `REQUESTS_CA_BUNDLE` and `CURL_CA_BUNDLE` settings still
  take precedence. (by @fangkangmi, closes #2004, #2005)

### Changed

- **BREAKING:** Object-form Git dependencies now reject unsupported keys instead
  of silently ignoring them. Migration: rename `version` to `ref` and remove
  inert `name` fields under `git:`; `apm audit --ci` also rejects altered
  full-SHA `resolved_commit` values. (#2209)

### Fixed

- Transient GitHub preflight failures no longer reject packages that the
  authoritative download can still retrieve; authentication, permission, TLS,
  and not-found failures remain closed. (#2313)
- `apm install` target contraction no longer reintroduces an inactive target's
  removed deployment path, so a fresh checkout converges to an audit-clean
  lockfile in one run. (#2310)
- Selective `apm update <package>` plans no longer report unselected direct or
  transitive dependencies as removed; true removals from the complete
  post-update graph remain visible. Reported by @IldarMinaev. (closes #2291, #2305)
- `apm audit --ci` now reports trusted manifest-driven `ref-consistency`
  remediation before deployment-ledger repair when source identity is
  tampered, avoiding guidance that could entrench the altered lockfile. (#2300)
- Project-scope Gemini, Codex, OpenCode, and experimental Hermes installs now
  prompt for `apm compile` when dependency instructions require root-context
  compilation. Contributed by @sergio-sisternes-epam. (closes #2057, #2293)
- Narrowing project targets now removes unchanged, APM-owned instruction files
  for dropped targets while preserving active-target and user-edited files.
  (#2295)
- `apm prune` now removes departed deployment ownership while preserving shared
  deployments, surviving owners, user-edited files, and failed-cleanup state;
  `apm audit` flags owners absent from the lockfile. (#2292)
- Bare `apm install` now reports a stale persisted `skills:` subset that
  matches no available skill, naming the package plus requested and available
  names while retaining successful install status. Contributed by
  @sergio-sisternes-epam. (#2294)
- Narrowing active targets now removes shared-root skill copies owned only by a
  dropped target while preserving user edits and surviving ownership. (#2299)
- `apm install <pkg>` now works at a filesystem root (e.g. Docker containers
  with `WORKDIR /`) by falling back to `my-project` as the manifest name;
  explicit empty or whitespace-only names are rejected early with a clear error
  -- by @nadav-y (#2200).
- Installing packages that share `.agents/skills` no longer leaves duplicate
  lockfile state or drops prior integrity information when APM must keep a file
  for a later retry. (#2283)
- Virtual-file installs now recover from confirmed GitHub throttling with one
  credential-safe sparse Git attempt while keeping authentication, permission,
  and missing-content failures closed. (#2284)
- Copilot hooks installed with `apm install -g` now resolve from any working
  directory by writing absolute user-scope script commands, while project-scope
  hooks remain repo-relative for portability. Reported by @sproott.
  (closes #2232, #2236)
- `apm uninstall` no longer deletes a shared transitive dependency that a
  surviving direct dependency still needs; uncertain reachability now preserves
  the package until its true last parent is removed. (#2269)
- Release binaries no longer crash with missing Rich Unicode modules when
  `apm deps list` renders non-ASCII package names, and repeated
  `apm runtime setup llm` no longer recurses through TLS setup. (#2264)
- SSH clone failures caused by passphrase prompts or public-key denial now
  include key, deploy-key, and token-backed HTTPS guidance without echoing
  captured SSH output. (#2244)
- Legacy manifests that declared `targets: [all]` are no longer hard-rejected;
  APM treats the field as omitted with a deprecation warning, restoring
  installability for older packages. (by @kotalab, closes #2271, #2272)
- `apm uninstall` and `apm prune` no longer wipe still-installed dependencies'
  merged hooks from harnesses dropped from the project's target list. The wipe
  now matches the target set rebuilt afterward. (closes #2250, #2252)
- `apm prune` and `apm uninstall` now rebuild merged hooks from every surviving
  lockfile package, including transitive dependencies. (by @Shaurya2k06,
  closes #2254, #2256)
- Packages with per-target hook files (for example separate Claude and Codex
  hooks) no longer cross-contaminate sibling tool configs when a dependency
  `targets:` list is set. (by @srobroek, closes #2258, #2259)
- `apm prune` no longer leaves stale, executable hook entries behind for a
  removed package; sibling and manually authored entries remain intact.
  (closes #2245, #2249)
- Narrowing project `targets:` now removes the dropped target's merged hooks and
  ownership sidecar during `apm install`, `apm compile`, or `apm update` while
  preserving hand-authored and still-declared entries. (closes #2253, #2275)
- Windows JSON reports, path diagnostics, Git subprocess resolution, and
  WebSocket shutdown no longer fail on platform-specific path, newline, or
  thread behavior. (closes #2233, #2237)
- `apm update` now automatically repairs a locked dependency whose
  materialized `apm_modules` cache is wholly absent -- including local
  filesystem dependencies -- without prompting for ref-change consent or
  changing any resolved refs. (#2240)
- Azure DevOps dependencies now report real latest versions in `apm outdated`
  and resolve correctly during bounded `apm update`. (closes #2197, #2226)
- Govern policy cache freshness now honors the effective policy's `cache.ttl`;
  malformed refreshes retain the last good policy bytes. (#2235)
- Git-source semver ranges now honor explicit SSH and `prefer-ssh` during tag
  enumeration instead of invoking HTTPS. (closes #2184, #2229)
- HTTPS Git dependency shorthand with custom ports now reparses after APM writes
  it to `apm.yml`. (by @atulya-singh, closes #2203, #2211)
- Codex agent generation now warns when `.agent.md` `tools` restrictions cannot
  be preserved instead of silently widening effective MCP access.
  (by @jstar0, #2186)
- `apm audit --ci` now accepts valid manifestless virtual Claude skills while
  continuing to reject malformed package shapes and real MCP drift.
  (by @hugoguitton-lucca, closes #2207, #2213, #2214)
- Marketplace packages emitted as remote URL or subdirectory sources now
  preserve the package host, path, and ref through `apm install`, fixing
  cross-host enterprise validation and self-hosted GitLab monorepo installs.
  (closes #2190, #2216, #2228)
- HTTP git dependency URLs now preserve custom ports when persisted to
  `apm.yml`, so later commands reconnect to the exact endpoint the user
  specified. (by @atulya-singh, closes #2202, #2210)
- Virtual Claude Skill subpath dependencies now keep `SKILL.md`-derived names
  and unversioned metadata stable across install, frozen cache replay, and
  update, avoiding spurious lockfile rewrites. (#2217)
- Synthetic virtual-package manifests now use canonical LF bytes before hashing,
  so equivalent Windows and Unix installs converge on one lock hash. (#2223)
- Changing a literal Git ref in `apm.yml` no longer silently keeps old bytes;
  `apm install` re-resolves the new ref and preserves the last good deployment
  when the new ref is invalid. (#2219)
- `apm pack` and local-bundle install now have a real binary parity contract,
  and `apm audit --ci` no longer reports clean bundle deployments as orphaned. (#2215)
- Warm policy-cache reads now preserve every enforceable field and strict denial;
  inherited stale policies no longer appear fresh or bypass status and
  executable-approval checks. (#2193)
- `apm install` now keeps complete nested GitLab project paths in its shared
  and persistent clone-cache identities, preventing sibling projects under a
  common group prefix from reusing the wrong repository.
  (by @lidorcg, closes #2191, #2192)
- `apm pack` now emits the `category` field in the Claude marketplace output
  when a package sets it, matching the existing Codex output.
  (by @mbeacom, closes #2188, #2189)
- `apm pack` now matches source-relative skill selectors such as
  `productivity/grill-me` against flattened deployed skill names.
  (closes #2171, #2176)
- `apm update` no longer reports or reinstalls semver dependencies already at
  their locked tag. (by @srobroek, #2165)
- `apm update` no longer produces a plan for branch dependencies already at the
  locked tip, while real tip advances remain visible. (#2212)
- `apm audit` no longer reports drift for skills intentionally excluded by a
  dependency's `skills:` subset filter. (#2177)
- `apm audit --ci` no longer reports false drift for package-relative links in
  nested local dependency skills. (closes #2154, #2179)
- The Windows installer now exposes a version-stable `apm.exe` path for Git Bash
  and direct process launch while preserving the `apm.cmd` shell launcher.
  (closes #2076, #2094)
- `apm update` now re-checks transitive dependencies' own semver ranges at any
  depth, so newly published matching versions are no longer ignored.
  (by @nadav-y, #2053)

### Performance

- Best-effort commits API lookups now fall through promptly to Git when
  rate-limited, avoiding multi-minute dependency-resolution stalls. (#2238)

## [0.25.0] - 2026-07-12

### Added

- The Contributor Dashboard now includes triaged-issue views, inline comments,
  bulk pull-request actions, and direct navigation to active Copilot sessions.
  (by @sergio-sisternes-epam, #2043)
- GitHub policy discovery now checks `.github-private` before `.github`, so
  organizations can keep `apm-policy.yml` private without changing existing
  fallbacks. (by @sergio-sisternes-epam, #2058)

### Changed

- `apm compile --target`, compile help and errors, and `apm init --target`
  now use one canonical target catalog, so every advertised target is accepted
  consistently. (closes #2138, #2147; #2155)
- Generated hooks now use canonical upstream contracts: Claude matcher/hooks
  nesting, Kiro v1 schema, Copilot's required top-level version, and provenance
  outside vendor payloads. (closes #2062, #2071, #2128, #2157; #2155)
- Homebrew formula updates now use the tap's daily poller instead of an obsolete
  PAT-backed dispatch, restoring release propagation without cross-repository
  credentials. (#2088)

### Fixed

- `apm install` now fails before commit when declared plugin components or a
  requested `--skill` are missing, and total positional-URL failure exits `1`.
  (closes #2103, #2116, #2126; #2155)
- Failed global Claude installs now clean up bootstrap state, corrected cyclic
  dependency graphs resume without deleting `apm_modules`, and exception output
  routes through the command logger. (closes #2129, #2140, #2161; #2155)
- `apm audit --ci` now detects both changed and removed MCP declarations from
  local-path sub-packages. (closes #2127, #2136; #2155)
- Contracting the target set now reconciles `deployed_files`, removes
  APM-managed MCP servers from dropped targets, and safely adopts exact matches
  from legacy lockfiles. (closes #2139, #2149, #2158; #2155)
- Manifest and policy parsers now reject invalid identity values and unknown
  policy keys. Migration: quote numeric manifest versions and use the declared
  mapping/list types for policy blocks. (closes #2137; #2155)
- `apm compile --clean` now removes the stale context artifact when the final
  primitive is removed. (closes #2130; #2155)
- `apm uninstall` now transfers shared deployed-file ownership to a surviving
  package and persists deployment state atomically. (closes #2148, #2160; #2155)
- Semver install and update now preserve Azure DevOps bearer authentication and
  retry a stale PAT `401` with the Azure CLI bearer. (closes #2150, #2156; #2155)
- `apm prune` and `apm deps list` now treat nested `apm.yml` files as part of
  their installed parent package instead of exposing or deleting them as
  top-level orphans. (#2092)
- `apm pack` now selects `.apm/` as the authoritative source only when it exists,
  preserves root plugin directories after `apm init`, and fails closed on invalid
  explicit `includes:` paths. (#2122)
- Azure DevOps marketplace checks now preserve suffix-free `/_git/<repo>` URLs
  and pass Azure CLI bearer authentication through to `git ls-remote`.
  (closes #2119, #2121)
- `apm install` now removes stale deployment records for inactive targets, so
  fresh checkouts can return `apm audit --ci` to green. (by @edenfunf, closes
  #2059, #2114)
- `apm install --target intellij` now configures JetBrains Copilot MCP support
  while routing package file primitives through the Copilot profile.
  (by @sergio-sisternes-epam; closes #1957) (#2041)
- The Windows installer now exposes a version-stable `current\apm.exe` on
  `PATH` (via a junction to the active release bundle) alongside the existing
  `bin\apm.cmd` shim, so Git Bash and Python `subprocess.run(["apm", ...])`
  resolve `apm` without `cmd.exe` PATHEXT expansion. (closes #2076) (#2094)

### Performance

- Deployment-ledger reconciliation now uses indexed mutation paths, avoiding
  quadratic scans as deployment history grows. (closes #2159; #2155)
- Dependency lookup, HTTP cache enforcement, marketplace ref selection, and
  host classification now use indexed or cached paths, avoiding repeated linear
  scans at scale. (by @sergio-sisternes-epam, #2124)

## [0.24.1] - 2026-07-10

### Fixed

- Skill ownership tracking now keys on the full `owner/repo` identity, so
  packages with the same leaf name no longer suppress collision warnings or
  claim the same deployed files. (by @nadav-y, #2052)
- Repeated `apm install` runs now preserve existing LSP server and config state
  before lockfile comparison, avoiding no-op rewrites caused only by
  `generated_at`. (by @paul-ww, closes #2078, #2079)
- OpenAPM v0.1 now defines deterministic Antigravity glob frontmatter and
  limits `AGENTS.md` deduplication to resolved instruction files, preventing
  unrelated rule files from suppressing instructions. (#2087)
- Codex MCP installs and stale-server cleanup now preserve literal Windows
  path keys in `config.toml` instead of rejecting or corrupting per-project
  preferences. (closes #2075, #2100)
- `apm audit --ci` no longer reports transitive MCP servers from local-path
  sub-packages as orphaned configs. (by @edenfunf, closes #2081, #2084)
- In-repository plugins from SSH-registered GitLab and generic git
  marketplaces now preserve SSH transport in generated `git:` and `path:`
  dependencies. (#2091)
- GitHub and package-registry dependency identities are now case-insensitive,
  preventing duplicate lock, cache, and install paths while preserving
  case-sensitive paths for unknown git hosts. (closes #2073, #2098)
- `apm deps tree` no longer repeats same-repository virtual packages, keeping
  large monorepo dependency trees accurate and scannable. (#2093)
- Claude user-scope MCP installs now honor `CLAUDE_CONFIG_DIR`, with
  `~/.claude.json` retained as the fallback. (closes #2060, #2096)
- Dev dependencies now survive `apm prune`, pass `apm audit --ci`, and remain
  represented in lockfile and MCP config checks. (by @sergio-sisternes-epam,
  closes #2033, #2102; supersedes #2042)
- `apm deps list` now matches local transitive dependencies by their canonical
  install path instead of incorrectly reporting valid packages as orphaned.
  (closes #2068, #2099)
- Failed installs from unrecognized self-hosted GitLab hosts now suggest
  `GITLAB_HOST`, `APM_GITLAB_HOSTS`, or an explicit `git:` plus `path:` entry.
  (by @rrazvd, closes #2066, #2074)
- `apm update` now reconciles MCP and LSP servers after an accepted plan,
  removing stale runtime config and recording newly declared servers.
  (by @cffnpwr, closes #2077, #2085)

## [0.24.0] - 2026-07-05

### Added

- `apm install` and `apm compile` now emit Antigravity-native `trigger: glob`
  and `globs` frontmatter in `.agents/rules/*.md`, and `apm compile` omits
  instructions from `AGENTS.md` when they already exist in `.agents/rules/`
  (compile-time dedup). (by @okamiconcept, #1984)
- `apm config list` is now available as a discoverable alias for `apm config
  get` with no key, listing all resolved configuration values. (by @WilliamK112,
  #1991)

### Security

- Artifactory registry-proxy ZIP installs now use the shared safe-extraction
  path with traversal, symlink, and zip-bomb guards instead of direct ZIP
  extraction. (by @fallintoplace, #1948)
- `apm runtime setup codex` now verifies GitHub Releases SHA-256 asset digests
  before extracting downloaded archives. (by @fallintoplace, #1949)
- Marketplace plugin `bin/` executables now deploy with user-only `0o700`
  permissions (group/other bits cleared) and legacy `bin_deploy.deny` GitHub
  forms are normalized before matching. (by @WilliamK112, #1971, #2024)

### Performance

- `apm install` with a committed lockfile no longer re-resolves branch-pinned
  and tagless locked dependencies over the network -- the tiered ref resolver's
  L0 cache is seeded from the lockfile before resolution runs (2 commits-API
  calls -> 0 on a 1-direct + 1-transitive branch-pinned install), skipped under
  `--update`/`--refresh`. (by @srobroek, #1973)
- `apm install` and `apm outdated` now issue a single `git ls-remote` per
  repository when resolving multiple semver git dependencies that share one
  upstream, cutting network round-trips for monorepos with many shared-origin
  deps. (by @srobroek, #1975)
- Repeated `git config` subprocess calls during cache operations were collapsed
  from 3 to 1 per repository, and promisor config is now applied on the clone,
  cutting process-spawn overhead on `apm install` and `apm update`. (by
  @srobroek, #1974)
- `apm compile` fast-paths universal (`**`) `applyTo` matching by reusing the
  built directory-analysis cache, speeding up compilation for repos with many
  universal instructions. (by @WilliamK112, #1993)

### Fixed

- `apm install` no longer aborts with a false "package not accessible" error
  when GitHub's API rate limit (primary 60/hr or secondary concurrency) throttles
  the pre-flight probe; a throttled response is now treated as indeterminate and
  the download step confirms the package. Genuine 404s and permission 403s still
  fail closed. (#2032)
- Generated `CLAUDE.md` now uses a single H1 title with nested H2/H3 sections,
  fixing duplicate top-level headings in Claude Code. (by @WilliamK112, #2016)
- `apm install` now deploys hook script directories as self-contained bundles
  for Claude-family targets, Copilot, and Kiro so sibling helper modules resolve
  at runtime, and JS/TS hook bundles get a minimal module-type `package.json`
  sidecar so a consumer repo's `type: module` no longer breaks CommonJS hooks.
  (closes #2023, #2025)
- Combined hook manifests such as `claude-codex-hooks.json` now deploy to every
  named target instead of only the last suffix target, so one deprecated
  filename-routed manifest still reaches both Claude Code and Codex. (by @garyj,
  closes #2020, #2021)
- Copilot hooks declared with Claude-shape event names (`PreToolUse`,
  `PostToolUse`) are now renamed to Copilot's camelCase during merge, fixing a
  casing mismatch that left the hooks inert. (closes #1977, #1979)
- `apm audit --help` now describes the command's full scope -- hidden-Unicode
  scanning, drift detection, and lockfile/policy checks -- instead of naming
  only Unicode scanning. (by @WilliamK112, #2017)
- `apm mcp install --help` now surfaces the forwarded `apm install` options
  inside the command description under a clearer "Forwarded install options"
  heading. (by @WilliamK112, #2018)
- `apm pack` now packs dependency content exclusively from lockfile-attested
  `deployed_files`, verifying each against its recorded SHA-256 before bundling,
  so tampered or unattested content fails the pack instead of shipping silently.
  This closes a supply-chain provenance hole in both `--format apm` and `--format
  plugin`; unattested dependency hooks/MCP config is no longer packed and
  directory entries are walked with per-child symlink containment. (closes #1999,
  #2013)
- `apm install --frozen` no longer spuriously rejects private Git dependencies
  on non-default hosts (Bitbucket Server, GitLab, GitHub Enterprise); lockfile
  matching now uses the same host-qualified identity as `apm install`. (closes
  #1996, #2011)
- Self-hosted Git hosts such as GitBucket that serve smart-HTTP only at the
  `.git` path now install over anonymous HTTPS -- `apm install` no longer drops
  the `.git` suffix. (by @mia106dev, closes #1995, #1997)
- `apm install` and `apm uninstall` no longer strip comments from `apm.yml` when
  updating dependency entries, so inline annotations and section notes survive.
  (closes #2000, #2012)
- `apm pack` now emits a `marketplace.json` the Copilot App accepts when the
  manifest `name` contains dots or underscores: the `name` is normalized to
  kebab-case with a warning naming the original and emitted values, while
  internal resolution keeps the original name. (by @sergio-sisternes-epam, #2008)
- `targets:`, `skills:`, and `alias:` on a `path:` dependency entry are no longer
  silently ignored during `apm install`, and now round-trip on serialization.
  (by @sergio-sisternes-epam, closes #1982, #1987)
- Self-defined stdio MCP env `${VAR}` placeholders now resolve from the
  install-process environment for Claude Code and Codex instead of being written
  verbatim. (closes #1963, #1966)
- `apm audit --ci` no longer reports phantom drift for root-local hook files when
  audit replay writes into a scratch project root. (closes #1978, #1980)

## [0.23.1] - 2026-06-29

### Fixed

- `apm audit --ci` no longer reports a false `content-integrity` hash-drift
  failure when a deployed text file is checked out with Windows (`\r\n`) line
  endings on one platform and POSIX (`\n`) line endings on another. Per-
  deployed-file hashes are now computed over canonical content (UTF-8 text
  normalized `\r\n` -> `\n` with a lone `\r` preserved so the carriage-return
  smuggling vector is still caught, binary hashed raw), so they match across
  platforms; lockfiles recorded on Windows before this fix re-record once on
  the next `apm install`. (#1952, #1959)

- `apm install <bundle> --skill X` is now properly additive: a later
  `apm install <bundle> --skill Y` adds `Y` on top of the existing pin instead
  of silently removing the previously deployed `X` from disk. Reset the pin to
  the full bundle with `--skill '*'`, or drop a single skill by editing the
  `skills:` list in `apm.yml` and re-running `apm install`. (#1955)

## [0.23.0] - 2026-06-28

### Added

- Added a general-purpose lifecycle hooks framework: embed shell-command or
  HTTPS-webhook scripts in `apm.yml` under a `lifecycle:` key that fire at
  `pre`/`post` install/update/uninstall events, gated behind `apm lifecycle trust`
  so nothing runs without explicit consent. The new `apm lifecycle` command
  (`init`/`validate`/`test`/`trust`/`untrust`) manages and dry-runs them, with
  cross-platform Windows support. (by @sergio-sisternes-epam) (#1798, #1947)
- `apm view <package> versions` now routes plain shorthands (e.g.
  `acme/web-skills`) to the configured default registry, matching `apm install`
  routing. Added `--registry [NAME]` for explicit control: bare `--registry` uses
  the lockfile entry or configured default, `--registry NAME` forces a named
  registry, and a full git URL forces the git path. (by @nadav-y) (#1938)

### Removed

- **BREAKING:** Removed the legacy `.chatmode.md` primitive format and
  `chatmodes/` directory support across discovery, integration, the watcher, and
  extension maps. Use `.agent.md` files in `.apm/agents/` instead. (closes #840)
  (#1931)

### Fixed

- Fixed startup version-check hint to reference `apm self-update` instead
  of the deprecated `apm update` command. (by @syf2211; closes #1939) (#1943)
- Fixed GFM table rendering in the documentation site by enabling `markdown.gfm` in the Astro
  config, restoring pipe tables, strikethrough, and task-list support for all `.mdx` content.
  (by @syf2211; closes #1940) (#1944)
- `apm outdated` tag-pattern matching for monorepo virtual subdirectory
  dependencies now derives the `{name}` segment from the `virtual_path`
  basename (e.g., `packages/my-pkg` -> `my-pkg`), aligning with `apm update`
  behavior. (by @kevinbeier-enbw; closes #1893) (#1893)
- Skipped startup update checks for unknown `apm` commands and bare help
  invocations so invalid CLI input fails without update-check latency. (by
  @maro114510) (#1541)
- Fixed `apm install` lockfile pruning when all `apm.yml` dependencies are
  removed, so stale `apm.lock.yaml` entries no longer survive. (by @nadav-y)
  (#1926)
- Fixed `apm update` final summary counts so unchanged re-materialized
  dependencies are not reported as updated. (by @nadav-y) (#1927)
- Fixed spurious version-range diffs for cached transitive registry
  dependencies during `apm update`. (by @nadav-y) (#1921)
- Fixed `apm install -g --mcp NAME` ignoring the package `targets:` field and
  `--target` flag at user scope; previously user-scope MCP install wrote to all
  detected runtimes unconditionally, creating unintended folders (e.g. `~/.kiro/`)
  when a package targets only a subset. (by @sergio-sisternes-epam) (#1941)
- Applied six `--help` and flag-naming consistency fixes from the CLI Consistency
  Report: surfaced the `apm deps update` deprecation and `apm install --runtime`
  legacy-alias status in help text, dropped the misleading `vscode` runtime value,
  and promoted `apm compile --force-instructions` as the primary flag (`--no-dedup`
  kept as a hidden alias). (by @sergio-sisternes-epam; closes #1928) (#1929)
- Fixed `apm preview <script>` crashing with `ValueError: too many values to
  unpack` by unpacking all three values returned by the auto-compile step. (by
  @fmferrari) (#1721)
- Fixed two false-positive `unintegrated` drift reports in `apm audit --ci` by
  honoring per-dependency `targets:` and the plural `targets:` key during drift
  replay. (by @sergio-sisternes-epam) (#1930)

### Security

- Bumped `llm` to `>=0.28` (resolved to 0.31) to clear the Critical code-injection
  advisory GHSA-g76p-4vg5-f4qh (Dependabot #62) affecting `llm <= 0.27.1`, and
  raised the `llm-github-models` floor to `>=0.18.0`. Forced patched transitive
  `vite` (`>=7.3.5`) and `esbuild` (`>=0.28.1`) in the `docs/` site via
  `package.json` overrides to clear GHSA-fx2h-pf6j-xcff, GHSA-v6wh-96g9-6wx3,
  and GHSA-g7r4-m6w7-qqqr (Dependabot #68, #69, #65). (#1936)

## [0.22.0] - 2026-06-26

### Added

- Per-dependency `targets:` scopes a dependency's target-specific primitives
  to selected harnesses (for example `targets: [copilot, claude]`), preventing
  hooks from leaking across tools. Filename-suffix hook routing
  (`*-<harness>-hooks.json`) is deprecated. (#1902)
- Executable Trust Governance v1 (#1875): executable trust is now one concept
  with one resolver and deny-wins precedence. Organizations can now declare an
  `executables:` block in `apm-policy.yml` (`deny_all`, `deny`, `require`,
  `recommend`) that is carried through policy inheritance, closing the
  GRANT/MANDATE asymmetry where projects could allow executables but orgs
  could not deny them. Org `deny` patterns support `fnmatch` globs (e.g.
  `evil/*`) so an admin can block a whole publisher fleet-wide; the GRANT
  side (`allow`/`recommend`/`require`) is exact-match in v1. A single deny-wins precedence resolver
  (`resolve_exec_decision`) is now shared by both the install gate and the
  `apm audit` policy checks, so the gate and the audit can never disagree.
  Precedence (first match wins): org `deny_all`/`deny` > user deny > project
  deny > project allow > user allow > org `recommend` > default-deny. The lockfile records a
  per-dependency `exec_status` (`deployed`, `gated_pending_approval`,
  `denied`, `absent`). No cryptographic signing or `enforce`-mandate
  execution is introduced in v1 (an unverified `enforce` rung fail-safe
  degrades to `recommend`). (by @sergio-sisternes-epam; closes #1873) (#1875)
- `apm policy explain <pkg>` prints the effective executable-trust decision
  for a package: whether it is allowed, the deciding policy layer, and any
  layers it shadows. `apm doctor` adds a fleet-level executable-trust drift
  check that flags packages allowed locally but denied by org policy. (#1875)
- `apm approve --recommended` bulk-accepts an organization's `recommend`
  set, and `apm approve --list` shows the effective trust state of every
  installed package with executables. (#1875)
- The shared gh-aw workflow `.github/workflows/shared/apm.md` exposes an optional `apm-version` import input that pins the apm CLI version for both the pack and restore `microsoft/apm-action` steps (so the two cannot skew), surviving `gh aw update` without hand-editing the vendored file. Omitting it falls through to the action's pinned default via a gh-aw schema default, so non-opting consumers stay reproducible instead of floating to `latest`. (#1842)
- `apm config set target <env>` configures a default install target so a bare
  `apm install` deploys to it -- set the target once, then install everywhere
  without repeating `--target`. Precedence is `--target` > `apm.yml` `target:` >
  config default > auto-detect, and `apm config get/unset target` inspect and
  clear it. (#1881)
- Org-wide policy discovery now cascades through candidate repo names
  (`.github`, then `.apm`, then `_apm`) and speaks the Azure DevOps Items
  API, so Azure DevOps organizations -- which forbid repo names that begin
  or end with `.` -- can host an APM governance policy repo for the first
  time. (by @sergio-sisternes-epam; closes #1813) (#1830)
- `apm compile -g` / `--global` compiles global (apply_to-less) instructions
  into user-scope root context files (`~/.claude/CLAUDE.md`,
  `~/.codex/AGENTS.md`, ...). `apm install -g` now prints a read-only hint
  pointing at it; no root context file is written on install. (closes #1485)
  (#1632)
- Each `apm.lock.yaml` dependency entry now records the installed package's own
  `name` and `version` -- for direct and transitive deps across git, local,
  registry, and cached sources -- so dependency inventory and upgrade planning
  are answerable straight from the lockfile. (closes #1888) (#1904)
- `apm config` gains `self-update.channel` and `self-update.install-dir` keys
  so `apm self-update` reads persisted non-secret installer defaults;
  credentials, tokens, and mirror URLs stay out of persisted config. (closes
  #667) (#1915)

### Changed

- **BREAKING:** Windsurf (Devin Desktop) skills now deploy to the cross-tool
  `.agents/skills/<name>/SKILL.md` path instead of `.windsurf/skills/`, joining
  the other five harnesses. Existing `.windsurf/skills/` deployments are
  orphaned (not auto-migrated) on next `apm install`; opt out with
  `--legacy-skill-paths`. (refs #1520) (#1802)
- Azure DevOps marketplace metadata now resolves through the Azure DevOps
  Items API instead of cloning the whole repo, with transparent fallback to
  the existing git path when REST is unavailable. (by @Aaryan-Dadu; closes
  #1808) (#1852)
- Executable-trust vocabulary is unified onto one noun, `executables`.
  `apm approve` / `apm deny` now default to the project `apm.yml`
  `executables: {allow, deny}` block (the committed, team-wide admin
  decision); pass `--user` to write personal consent to
  `~/.apm/config.json` (the lowest-authority, machine-local override that
  can only narrow). (#1875)
- The `required-packages-deployed` audit check now asserts package
  PRESENCE in the lockfile rather than materialized `deployed_files`, so an
  install SUCCEEDS when a required package is present-but-parked (its
  executables gated pending approval) and prints a one-command remedy
  instead of hard-failing. A separate `required-executable-untrusted`
  signal hard-fails CI when a required package's executables are untrusted.
  (#1875)

### Deprecated

- The project `allowExecutables:` block is deprecated in favor of
  `executables.allow`. It remains a read alias for one minor cycle and is
  migrated to `executables.allow` on the next `apm approve`/`apm deny`
  write. The org `bin_deploy` deny policy is folded into
  `executables.deny[bin]` as a deprecated alias. (#1875)
- The org `executables.enforce` tier (the v2 mandate rung) is accepted but
  INERT in v1: writing it emits a validation warning and the resolver
  degrades it to `recommend` (no force-execute; a user deny still
  overrides). (#1875)

### Removed

- **Breaking (security):** executable dependencies -- including MCP servers and
  canvas extensions -- now require explicit, persistent approval via `apm approve`,
  closing the gap where canvas extensions were trusted per-run. The
  `--trust-canvas-extensions` flag is removed as a consequence; canvas extensions
  are now governed by the executable-trust gate like every other executable
  surface. (by @sergio-sisternes-epam) (#1865)

  ```diff
  - apm install --trust-canvas-extensions   # before: per-run trust flag
  + apm approve <pkg>                        # after: one-time, persistent approval
  ```

  CI / non-interactive pipelines that previously passed the flag should
  instead pre-seed approvals before `apm install`, e.g.
  `apm approve <pkg>`, so the gate finds the package already trusted and
  never prompts.
- The standalone `~/.apm/approvals.yml` personal-consent file is removed;
  its contents are migrated into `~/.apm/config.json` under
  `executables: {allow, deny}` on first read (net-new control-surface
  files = 0). (#1875)

### Fixed

- Reinstalling on Windows no longer falsely re-reports unchanged files as
  freshly installed. A dependency whose source carries CRLF line endings
  (text-mode checkout or `core.autocrlf`) now adopts the already-deployed LF
  file, so no-op installs report `(files unchanged)` as they do on
  Linux/macOS. (#1916)
- `apm update` on a registry semver dependency now re-resolves and re-downloads
  when a newer matching version exists, instead of leaving the old version in
  place; registry deps are now first-class across install, update, and every
  display surface. (by @nadav-y) (#1908)
- APM-written deployed text files now use LF line endings on every platform,
  so identical content no longer produces different
  `local_deployed_file_hashes` / `deployed_file_hashes` between Windows and
  Linux (which previously churned the lockfile across machines and CI).
  (#1913)
- `apm install <pkg>@<marketplace>` now preserves GitLab and other
  non-GitHub hosts from url-type marketplace plugin sources, so auth
  resolution no longer falls back to `github.com` for those installs.
  (by @sergio-sisternes-epam; closes #1848) (#1853)
- `apm pack` no longer drops the per-plugin `version` field for INTERNAL or
  private `github.com` marketplace repos; all GitHub host types now resolve
  metadata through the REST Contents API instead of the raw CDN, which
  returned 404 for private repos. (by @sergio-sisternes-epam) (#1854)
- `apm audit --ci` no longer flags pinned remote dependencies declared by
  local-path sub-packages as orphaned when they are resolved transitively.
  (by @sergio-sisternes-epam; closes #1846) (#1855)
- `apm update` stale-file cleanup no longer deletes a file when another
  installed package also deploys one at the same path; a cross-package
  ownership guard now excludes shared paths from the stale set.
  (by @sergio-sisternes-epam; closes #1831) (#1856)
- `apm install -g --target codex` now honors `CODEX_HOME` for user-scope
  Codex MCP config writes, falling back to `~/.codex/config.toml` when unset.
  (closes #1861) (#1863)
- Windows installer staging now honors `APM_TEMP_DIR` and reports actionable
  guidance when the temporary staging root is not writable. (closes #1874)
  (#1876)
- Windows pip fallback no longer terminates early when native pip writes stderr
  under `$ErrorActionPreference = "Stop"`. (closes #1874) (#1876)
- `apm install plugin@marketplace` now correctly fetches from the
  marketplace's registered `--ref` branch instead of silently falling back
  to the repository's default branch. Root cause: `resolve_marketplace_plugin`
  did not propagate `source.ref` to downstream resolution calls. Covers both
  GitHub-family hosts (ref appended to canonical as `#ref`) and GitLab-hosted
  marketplaces (ref injected into `DependencyReference`). Guards prevent
  double-injection when a plugin's own dict source already carries an explicit
  `ref`, and skip `main`/`HEAD` as implicit defaults. (by @chkp-roniz,
  #1880; mirrors #1824)
- GitLab archive URLs with slash-containing branch names (e.g.
  `feat/my-feature`) now produce correctly-formed Artifactory-proxyable
  filenames. The slash is preserved in the path segment (as the GitLab
  archive API expects) but replaced with `-` in the archive filename,
  matching GitLab's own naming convention. Previously,
  `PROXY_REGISTRY_ONLY=1` installs from such branches returned HTTP 404
  from the proxy because the generated filename contained a literal slash.
  (by @chkp-roniz, #1880; fixes the proxy scenario not covered by #1824)
- `apm install <pkg> --target X` in a directory with no `apm.yml` now persists
  the selected harness(es) into the auto-created manifest's `targets:`, so a
  later bare `apm update` redeploys to the same targets without re-specifying
  `--target`. (closes #1743) (#1901)
- `apm update` / self-update on macOS no longer prints `-e` literally before
  each colored line (caused by invoking `install.sh` under `/bin/sh`), and now
  shows a progress bar during binary download. (by @nadav-y) (#1872)

### Security

- The `allowExecutables` default-deny gate now enforces `mcp` server writes and
  `canvas` extensions in addition to `hooks` and `bin`, bringing all four executable
  surfaces under one approval model. `apm approve` decisions are also stored
  user-local in `~/.apm/approvals.yml` instead of the committed project `apm.yml`,
  so cloning a repository no longer silently inherits another developer's executable
  approvals. (by @sergio-sisternes-epam) (#1865)

## [0.21.0] - 2026-06-19

### Added

- `apm audit` now surfaces unmanaged files in governance directories as a single enriched report: each finding states a factual reason (`not tracked in apm.lock.yaml`), a lazy primitive-type tag (`[type: skill|agent|instruction|mcp]`), and a deny-conflict note (`matches deny rule (<pattern>)`) when the path matches the policy's own `dependencies.deny` / `mcp.deny`. A new `unmanaged_files.exclude` policy key suppresses known harness-managed paths, and a symlink guard prevents following links out of the workspace. This is drift / divergence visibility, not supply-chain-attack prevention. (closes #1775) (#1793)
- Azure DevOps is now documented as a first-class marketplace authoring host: a `marketplace.sourceBase` of `https://dev.azure.com/{org}/{project}/_git` composes relative package sources and preserves the `dev.azure.com` host through to the consumer (authenticated with `ADO_APM_PAT`). The end-to-end authoring -> consume path is pinned by a hermetic test. (closes #1010) (#1810)
- `apm install --target antigravity` and `apm compile -t antigravity` add
  Google Antigravity CLI (`agy`, successor to Gemini CLI) as a new target.
  Instructions deploy as rules to `.agents/rules/<name>.md`, skills to
  `.agents/skills/<name>/SKILL.md`, hooks merge into a single
  `.agents/hooks.json` using Antigravity's native schema
  (`PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/`Stop`), and
  MCP servers write to a dedicated `.agents/mcp_config.json` (project) or
  `~/.gemini/config/mcp_config.json` (`--global`). `compile` emits `AGENTS.md`.
  Antigravity shares the cross-tool `.agents/` root, so it is explicit-only:
  select it with `--target antigravity` or in `apm.yml` `targets:`; it is
  never auto-detected and is not part of `--target all`. (by @sergio-sisternes-epam;
  closes #1650) (#1770)
- Two additive, default-off policy keys under the existing `security:` namespace: `security.integrity.require_hashes` makes `apm install` fail closed when any non-local lockfile entry lacks a content hash, and `security.audit.fail_on_drift` makes `apm audit` exit non-zero when the workspace drifts from the lockfile. Both only tighten through policy inheritance. (#1794)
- MCP dependencies can now carry harness-specific passthrough keys (for example Claude Code's remote-MCP `oauth` block with `clientId`/`callbackPort`); previously any key outside the modeled set was silently dropped on render. Passthrough keys round-trip into the generated config for every installed harness and cannot shadow a modeled field (`command`/`url`/`headers`/`env`/...), which are rejected with a warning. A future fail-closed tightening to an explicit `extra:` block is tracked in #1806. (closes #1670) (#1765)
- `apm install owner/repo#ref` now routes to the configured default registry (project `registries.default` or `registry.<name>.default true` in `~/.apm/config.json`) instead of probing GitHub. A version selector (`#<ref>`) is required; omitting it exits `1`. Non-semver selectors (`stable`, `main`, a branch name, or any opaque string) are exact-matched against the registry's published version list. Use the `git:` URL form in `apm.yml` to force the GitHub path. (#1816)
- `apm lock export --format cyclonedx|spdx` emits a standard SBOM inventory of installed packages, and a new declared-license recorder stores each package's manifest-declared license (`apm.yml` `license:` / `plugin.json`) in the lockfile after offline SPDX-id validation. APM records what a package declares -- it does not scan LICENSE text or gate installs on a license. (closes #1777) (#1820)
- `apm install` / `apm pack` can now deploy an experimental Copilot-only `canvas` primitive: a package declaring `.apm/extensions/<name>/` ships verbatim to `.github/extensions/<name>/` (or `~/.copilot/extensions/<name>/` with `--global`), where Copilot CLI discovers it in-session. The surface is gated twice -- `apm experimental enable canvas` plus `--trust-canvas-extensions` for dependency-provided canvases -- and is fail-closed when the flag is off. (#1689)
- `apm install` now blocks dependency-provided executables (hooks and `bin/`) by default, mirroring npm v12's default-deny model. A dependency's hooks or binaries deploy only after explicit approval in an `allowExecutables` block of `apm.yml`, managed via `apm approve` / `apm deny`; root-authored content and text-only primitives are unaffected. (#1723)
- `apm compile --global` / `-g` compiles user-scope root context files such as
  `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and `~/.gemini/GEMINI.md` from
  globally installed instructions. Compilation stays explicit; `apm install -g`
  prints a one-line hint pointing at `apm compile -g` when global instructions
  land on a root-context-only target, but writes no root context file. (#1632)

### Changed

- Windsurf skills now deploy to the cross-tool `.agents/skills/<name>/SKILL.md` path (was `.windsurf/skills/`), converging with Copilot, Cursor, Codex, Gemini, and OpenCode. Pass `--legacy-skill-paths` or set `APM_LEGACY_SKILL_PATHS=1` to restore the per-client `.windsurf/skills/` layout. The lockfile pack-time cross-target skill map for Windsurf is swept separately in #1805. (closes #1520) (#1802)

### Removed

- `apm marketplace publish` command and consumer-repo fan-out workflow; consumers should run `apm install --update` instead. (#1134)
- `apm marketplace doctor` subcommand alias (deprecated); use `apm doctor` instead. (#1134)

### Fixed

- Registry deps with non-semver version selectors (e.g. `stable`, `main`) no longer report perpetual `outdated`. The drift check now uses literal equality for non-semver registry pins rather than range comparison, which always returned `True` against a semver range. (#1816)
- Non-semver registry version selectors are now exact-matched against the registry's published version list at install time. Previously they were rejected with "not a valid semver range". (#1816)
- Cursor hook integration: emit required top-level `version: 1` in `.cursor/hooks.json`.
  Affected versions: v0.14.1-v0.20.0. Hooks were silently ignored by Cursor on those
  versions. Run `apm install` (or `apm install --target cursor`) to repair existing
  installations. (closes #1823) (#1840)
- `apm update --target` help text now lists `kiro` as a valid example
  target, matching `apm install`. (#1821)
- `apm marketplace check` no longer fails with exit 128 for entries on
  non-default hosts, including relative entries composed onto
  `marketplace.sourceBase` (self-managed GitLab / GHES / Azure DevOps). It now
  resolves each entry against its effective host and per-org token, matching
  `apm pack`; local `./` packages skip the network.
  (closes #1762, follows up #1736)
- Policy inheritance no longer drops `fetch_failure`, `registry_source`, and `bin_deploy` when a policy `extends` another; these fields now carry and tighten through the merge like sibling sections. (closes #1778) (#1791)
- `apm install` no longer silently ignores MCP servers declared in `devDependencies.mcp`; dev MCP configs and lockfile entries now stay in sync on fresh installs. (closes #1780) (#1787)
- `apm compile` now honors `managed_section` mode on distributed root
  `AGENTS.md` and `--single-agents` writes, preserving hand-authored
  content outside the APM markers. (closes #1764) (#1768)
- `apm install` now removes orphaned skill directories when a package is uninstalled or its skills are renamed. Previously, individual files were deleted but the skill folder remained with a "Refused to remove directory entry" warning. (closes #1483) (#1767)
- `apm install --skill <name>` now merges additively with skills already pinned for the same package in `apm.yml` instead of overwriting them, so installing a second skill subset no longer drops the first. (#1786)
- `apm publish` and the registry resolver no longer emit stale `tar.gz` / `--tarball` references after the switch to zip-by-default; help text, docs, and extractor paths now match the actual artifact format. (#1779)
- `apm marketplace` now propagates `--ref` to relative plugin sources, so pinning a marketplace ref resolves nested relative packages at that ref instead of the default branch. (closes #1811) (#1824)
- `apm pack` now substitutes the `{name}` placeholder during marketplace version resolution; previously the literal `{name}` was left unresolved, breaking version lookups for templated entries. (closes #1822) (#1841)
- `apm outdated` now degrades gracefully when a single dependency check fails, reporting the error for that entry instead of crashing the whole command. (#1836)

## [0.20.0] - 2026-06-11

### Added

- `apm install --target kiro` deploys Kiro IDE steering, skills, hooks,
  and MCP config to the documented `.kiro/` layout. (by @TibRib; closes #702) (#1741)
- APM now catches accidental subpath embeds in git URLs (for example, `org/repo/skills/name.git`) and points at the supported `path:` key form. (#1740)
- SHA-pinned dependencies now stay current automatically: `apm update` resolves the newest annotated release tag, rewrites the pin, and `apm outdated` reports drift. (#1738)
- `apm install --target hermes` and `apm compile -t hermes` add the Hermes
  agent (Nous Research) as a new experimental target (opt in via
  `apm experimental enable hermes`). Skills deploy to `.agents/skills/<name>/SKILL.md`
  (project) or `~/.hermes/skills/<name>/SKILL.md` (`--global`), `compile`
  emits `AGENTS.md`, and MCP servers are written to the `mcp_servers:` block
  of `~/.hermes/config.yaml` (written atomically with `0o600` perms, preserving
  unrelated config keys and refusing to overwrite a malformed file). `HERMES_HOME`
  overrides the Hermes home directory. See the [Hermes integration guide](https://microsoft.github.io/apm/integrations/hermes/). (#1726)
- Enterprise marketplace authors can stop repeating shared git base paths by
  setting `sourceBase` (one line replaces repeated URLs), while host-prefixed,
  full-URL, and local entries remain per-entry overrides. (#1736)
- `apm marketplace add` now accepts git URLs with `#ref`, local file paths,
  and hosted `marketplace.json` URLs -- so teams can consume private,
  offline, or hosted catalogs without publishing a GitHub repo (closes
  #676). (#1739)
- Enterprise bootstrap mirror mode (`APM_RELEASE_METADATA_URL`, `APM_RELEASE_BASE_URL`, `APM_INSTALLER_BASE_URL`, `APM_PYPI_INDEX_URL`, `APM_NO_DIRECT_FALLBACK`) routes `install.sh`, `install.ps1`, and `apm self-update` through internal mirrors with fail-closed public fallback; closes #1680. (#1733)
- `apm pack --archive-format [zip|tar.gz]` escape hatch (default `zip`) lets
  CI pipelines that depended on the previous `.tar.gz` default opt back in without
  changing the project default. Passing `--archive-format` without `--archive` is
  now a `UsageError`. (#1720)

### Changed

- **BREAKING:** `apm pack --archive` now produces `.zip` by default instead of `.tar.gz`, matching the format produced by `apm publish` and expected by Claude Code and plugin hosts while staying natively extractable on Windows without WSL or a tar binary. Note: ZIP archives are typically 30-130% larger than `.tar.gz` for text-heavy skill bundles due to per-file compression; use `--archive-format tar.gz` if archive size is a priority. (#1720)

### Fixed

- `apm pack` now fills local-path marketplace package `description` and `version` from each package's own `apm.yml` when the root `marketplace.packages[]` entry omits them, so monorepo marketplaces no longer show empty browse columns -- matching the existing remote-source fallback. (closes #1725) (#1755)
- `apm install --target` with a comma-separated list containing `copilot` (or the `vscode`/`agents` aliases) no longer silently drops the Copilot target. (by @Addono, closes #1746, #1749)
- `apm install` now resolves relative `path:` deps declared by remote monorepo packages when they stay inside the same remote repo, while still rejecting absolute, escaping, or cross-repo paths; closes #1571. (#1732)
- Optional-auth MCP registry servers now install without token prompts when values are unset; `apm install` also omits empty runtime config entries and preserves user-edited optional values on reinstall; refs #20. (#1734)
- Dependencies with the same path on different git hosts no longer collide in `apm.lock.yaml`; `apm install` keeps GitHub/GitLab PATs off generic-host file downloads, routes bespoke GitLab hosts through `type: gitlab`, and surfaces non-404 download failures with host and endpoint context. Reading private files from a generic non-default host now requires a whole-repo git dependency or explicit backend signal; see the dependency and lockfile docs (closes #773). (#1735)
- GitLab `path:` files now just work on self-hosted instances where the REST API is disabled or restricted -- APM fetches via git transport automatically. `GITLAB_APM_PAT` / `GITLAB_TOKEN` remain available as a thin REST API fallback; closes #1014. (#1740)
- `apm compile --clean --target claude` now removes a stale APM-generated
  `CLAUDE.md` when instructions have already been deployed to `.claude/rules/`
  (the dedup path introduced in #1138), so the duplicate-context problem #1138
  set out to eliminate is fully resolved even for projects that compiled before
  `.claude/rules/` existed. Hand-authored `CLAUDE.md` files (those lacking the
  `<!-- Generated by APM CLI -->` marker) are never deleted; a warning is
  emitted instead. Plain `apm compile` (without `--clean`) remains
  non-destructive. (closes #1729, follow-up to #1138)
- `apm compile --target copilot` no longer writes empty `AGENTS.md`
  shell files when `.github/instructions/` already holds deployed
  instructions; `--clean` also removes stale APM-generated shells while
  preserving hand-authored files. Use `--no-dedup` / `--force-instructions`
  to write full `AGENTS.md` files anyway. (by @tillig; closes #1730, related:
  #1138, #1550) (#1742)

## [0.19.0] - 2026-06-09

### Added

- `apm install <package> --target openclaw` adds OpenClaw as a new experimental
  skills consumer target (opt in via `apm experimental enable openclaw`). Skills
  deploy to `.agents/skills/<name>/SKILL.md` (project) or
  `~/.openclaw/skills/<name>/SKILL.md` (global). (by @sergio-sisternes-epam, #1677)
- `apm publish` auto-pack now includes `README.md`, `CHANGELOG.md`, and `LICENSE` / `LICENCE` (case-insensitive, symlinks excluded) in the flat registry archive, matching npm's behaviour of bundling standard root-level documentation files alongside the package source. (by @nadav-y, #1695)
- `apm install` now surfaces per-event hook action summaries as it integrates
  hook primitives, with the fully rewritten hook JSON shown under `--verbose`,
  so you can audit exactly what each hook runs at install time. The summary is
  built from the post-rewrite data actually written to disk and executed -- it
  faithfully reflects on-disk content across Copilot, Claude, and Gemini
  targets (including OS-specific `windows`/`linux`/`osx` hook keys). (by
  @harshitlarl, closes #316, #1700)
- Experimental, Copilot-only `canvas` primitive: `.apm/extensions/<name>/extension.mjs` deploys to `.github/extensions/<name>/` on `apm install`/`apm pack`, gated by `apm experimental enable canvas` + `--trust-canvas-extensions` for dependencies. (by @sergio-sisternes-epam, #1689)
- Experimental canvas: `apm install --global --trust-canvas-extensions` deploys dependency canvases to `~/.copilot/extensions/<name>/`; `apm uninstall --global` prunes them. (by @sergio-sisternes-epam, #1689)
- Experimental canvas: package validation recognises canvas extensions (canvas-only packages valid, gated-executable warning); `apm audit` (text) lists deployed canvas bundles. (by @sergio-sisternes-epam, #1689)

### Changed

- **BREAKING:** `apm publish` auto-pack now produces a `.zip` archive (ZIP\_DEFLATED) instead of `.tar.gz`, aligning with the de facto standard used by Anthropic Claude, OpenAI, and Google Gemini agent platforms. The `--tarball` option is renamed to `--zip`. Output filename: `{name}-{version}.zip`. (by @nadav-y, #1695)
- `MCPDependency.from_dict()` now emits a `[!]` warning naming every unknown
  key dropped during parsing (e.g. harness-specific fields like `oauth`) instead
  of discarding them silently, making forward-compat config mismatches
  diagnosable. (#1674)
- Auth credential cascade now emits debug-level logs for every fallback step,
  making token misconfiguration diagnosable without adding noise to normal output.
  Enable with ``apm --verbose`` or ``APM_LOG_LEVEL=DEBUG``.
  (by @danielmeppiel, closes #935, #1664)

### Fixed

- `apm audit` now detects drift and tampering in committed deployed skill
  bundles under `.agents/skills/**`. The lockfile integrity manifest is now
  target-complete (per-file `deployed_files` + `deployed_file_hashes` for every
  committed file-based deploy target, not just one), the drift differ walks each
  primitive's `deploy_root`, and the `apm-self-check` CI job runs the drift gate
  (dropped `--no-drift`). Previously a multi-target deploy left the manifest
  single-target, so deployed skill content could silently diverge from its
  `packages/**` / `.apm/**` source with every gate staying green. (by
  @danielmeppiel, closes #1716, #1718)
- `apm install` now falls back to an AAD bearer token (via `az login`) when no
  `ADO_APM_PAT` is configured for Azure DevOps file downloads, and fail-closes
  when ADO returns an interactive HTML sign-in page with HTTP 200 instead of
  writing corrupt HTML to disk. (by @danielmeppiel, closes #1671, #1675)
- `apm install` now splits FQDN monorepo subpath shorthand on GitHub
  Enterprise Server hosts. With `GITHUB_HOST` set, a dependency string like
  `ghe.example.com/org/repo/packages/skill` resolves to `git: org/repo` plus
  `path: packages/skill` instead of embedding the whole subpath into the clone
  URL. (by @sergio-sisternes-epam, closes #1673, #1684)
- `apm compile` now keeps instruction content in `AGENTS.md` for non-Copilot
  targets (Codex, OpenCode, Windsurf) instead of suppressing it whenever
  `.github/instructions/` contains `.md` files, so those targets no longer lose
  their instructions. (by @sergio-sisternes-epam, closes #1678, #1685)
- `apm install` now unwraps the `{ "lspServers": { ... } }` envelope in plugin
  `.lsp.json` files instead of silently skipping them with a misleading
  validation error. (by @sergio-sisternes-epam, closes #1683, #1686)
- `apm install` now preserves transitive dependencies declared in `apm.yml`
  when installing dual-format packages (those colocating `plugin.json` with
  `apm.yml`) from the marketplace or a remote subdirectory, instead of silently
  dropping them when the synthesized manifest overwrote the file. A malformed
  existing `apm.yml` now also surfaces a warning instead of failing silently.
  (by @sergio-sisternes-epam, closes #1666, #1687)
- `apm audit` external skill-scanner UX is clearer, with improved messaging and
  error handling around external scanners. (by @sergio-sisternes-epam, #1692)
- `install.sh` now validates `APM_LIB_DIR` before running `rm -rf`, preventing
  data loss when the override points at a directory holding unrelated
  application data. (by @dohwi, closes #1690, #1694)
- `apm install` now preserves scoped MCP package config keys such as
  `@playwright/mcp` across Claude, Codex, and Copilot harness configs instead
  of truncating them to `mcp`. (#1699)
- `apm install` now accepts marketplace git-subdir refs with package-version
  tags such as `package@v1.0.1` inside the `#ref` fragment while still
  rejecting retired string-form `@alias` shorthand. (closes #1696, #1698)
- `apm install` now keeps format-transformed rule files (`.claude/rules`,
  `.cursor/rules`, `.windsurf/rules`) tracked in `managed_files` and rewrites
  them when the source instruction changes, instead of mis-classifying them as
  user-authored collisions and skipping them; also fixes a mislabeled
  `windsurf_rules` entry in install output. (by @srid, closes #1662, #1665)
- `apm install <local-path>` now dereferences in-package symlinks into regular
  files so that local and remote installs produce consistent output. Symlinks
  whose resolved target escapes the package root hard-fail with a
  `PathTraversalError`; circular directory-symlink chains and unreadable
  package directories are detected deterministically. Previously, in-package
  symlinks were silently dropped by the downstream deploy filter. (by
  @danielmeppiel, closes #1668, #1676)
- `apm install --skill <name>` is now honored for non-package skill-collection
  installs (plugin-manifest collections), promoting only the selected skills
  instead of the entire set; both leaf names and nested manifest paths are
  accepted. (by @danielmeppiel, closes #1707, #1709)
- `apm install` no longer rewrites `apm.lock.yaml` when a project combines a
  remote APM dependency with unchanged local `.apm/instructions` content.
  (by @danielmeppiel, closes #1702, #1710)

## [0.18.0] - 2026-06-04

### Added

- `apm marketplace audit`: new command that flags dependencies bypassing
  marketplace pinning, so you can catch unpinned or non-marketplace deps before
  they ship. (by @edenfunf, #881)
- Marketplace dependency object entries in `apm.yml` and `plugin.json` now
  resolve to concrete git refs during install, support optional semver-style
  `version` constraints, and fail closed when resolution errors occur. (by
  @stbenjam, #1422)
- LSP server management: declare language servers in `apm.yml` and `apm install`
  wires them into Claude Code and GitHub Copilot CLI automatically. (by
  @stbenjam, #1424)
- `apm outdated` now recognizes monorepo `{name}-v{version}` tag naming, so
  per-package version checks work in repositories that publish multiple packages
  under subpath tags. (by @kevinbeier-enbw, #1504)

### Changed

- **BREAKING:** `apm` now rejects string-form `@alias` dependency shorthand at
  parse time with a migration error; use the object form with `alias:` instead.
  (#1655)

### Fixed

- `apm compile` now matches `applyTo` globs without following symlinks into
  `node_modules`, avoiding spurious matches and slow traversals in projects with
  symlinked dependencies. (by @srid, #1576)
- `apm install` now rewrites outbound relative links inside skill bundles so the
  links keep resolving after a skill is materialized into an agent target.
  (closes #1625, #1657)
- Git-source semver ranges for virtual subdirectory dependencies now match
  per-package `{name}-v{version}` tags, derive `{name}` from the subpath, and
  reject malformed range-like refs with an actionable manifest error. (closes
  #1633, #1658)
- `apm install` now preserves env-var placeholders (e.g. `${VAR}`) when writing
  IntelliJ `mcp.json`, so configured environment references survive install
  instead of being expanded or dropped. (closes #1656, #1659)

## [0.17.0] - 2026-06-03

### Added

- `apm lock`: new command that resolves all dependencies and writes
  `apm.lock.yaml` **without** deploying any files to agent targets. Mirrors
  the lockfile-only ergonomics of `cargo generate-lockfile` and `pnpm lock`;
  accepts `--update`, `--verbose`, `--global`, `--no-policy`, `--target`, and
  `--parallel-downloads`. (#1639)
- `apm find <file>`: trace a materialized file back to its contributing
  package(s) via a reverse index over `apm.lock.yaml`. Supports `--source` and
  `--path`; untracked paths exit 1 (a missing or corrupt lockfile exits 2),
  each with an ASCII `[x]` message, and the command performs zero network or
  write operations. (#1631)
- `apm update` now accepts `-g/--global`, positional `[PACKAGES]...`,
  `--force`, and `--parallel-downloads`, making it a strict superset of
  `apm deps update` -- one verb covering project and user scope, per-package
  refresh, and collision overwrite. (closes #1525, #1574)
- `apm config set mcp-registry-url <url>` / `get` / `unset` persistently
  configures a private MCP registry endpoint in `~/.apm/config.json`, sitting
  between the `MCP_REGISTRY_URL` env var and the built-in default in the
  resolution chain (CLI flag > env > config > default). Accepts `http://` or
  `https://` only; `apm mcp search` prints a `Registry (config): <url>`
  diagnostic when active. (closes #818, #1637)
- `apm init` now suggests creating an `agentrc` in its Next Steps output when no
  instructions exist, guiding new projects toward a first primitive. (#1611)
- `apm self-update` and the version checker now respect air-gapped env vars
  (`GITHUB_URL`, `APM_REPO`, `VERSION`), so self-update and update checks work
  behind a mirror without reaching public GitHub. (#1615)
- Target-aware hook event diagnostics: `apm install` now reports hook wiring
  per target so misconfigured or unsupported hook events surface clearly
  instead of failing silently. (#1635)
- JetBrains users (IntelliJ IDEA, PyCharm, GoLand, WebStorm, and other IDEs)
  can now install MCP servers with `apm install --mcp --runtime intellij
  <package>` -- no manual `mcp.json` editing required. Auto-detected when the
  OS-specific Copilot-for-JetBrains config directory exists; runtime `${VAR}`
  env substitution is not supported for this target, so `--env` values are
  written verbatim (avoid plaintext secrets). (#1636)
- `apm install` and `apm compile` now accept `--root DIR` to redirect every
  generated artifact (`apm_modules/`, `apm.lock.yaml`, `.gitignore`, and
  harness/`AGENTS.md`/per-target files) under `DIR`, while `apm.yml`, `.apm/`,
  and local-path dependencies still resolve from `$PWD` -- mirroring
  `pip install --target` and `npm install --prefix`. `--root` is rejected with
  `--global` (install) and `--watch` (compile). Thanks to @srid (juspay) for
  the original implementation. (closes #888, #1628)
- `apm pack` now generates an ecosystem-specific `plugin.json` when
  `target:`/`targets:` includes `claude` or `copilot`, synthesised from
  `apm.yml` identity fields so one source tree drops into a Claude Code or
  Copilot plugin path with zero hand-editing. Claude manifests embed
  `mcpServers` from `.mcp.json` with credential-bearing keys and secret-shaped
  values stripped recursively; Copilot manifests omit `mcpServers`. An existing
  `plugin.json` is preserved unless `--force` is passed. (#1623)
- `apm pack` also synthesises `homepage`, `repository`, `keywords`, and a
  structured `author` (`{name, email?, url?}`) from `apm.yml` into
  `plugin.json`. All fields are additive and `author` still accepts a plain
  string (backward-compatible). (closes #1621, #1624)
- `apm install -g` now deploys `bin/` executables from `marketplace_plugin`
  packages into `~/.claude/skills/<name>/bin/` and makes them executable,
  giving Claude Code direct access to plugin-provided binaries. The
  `bin_deploy` policy field lets administrators opt out globally
  (`deny_all: true`) or per-package. (#1591)
- `apm compile` with `compilation.agents_md.mode: managed_section` updates only
  the APM-owned block between configurable markers, so teams with existing
  `AGENTS.md` content can adopt `apm compile` without losing hand-written
  rules. Missing or duplicate markers raise a loud error so no content is
  silently lost. (closes #1540, #1589)
- `apm compile --no-dedup` (alias `--force-instructions`) forces the
  instructions section into `CLAUDE.md` even when `.claude/rules/` is already
  populated. Claude target only; Copilot deduplication is always on. (closes
  #1463, #1616)
- `apm publish` auto-pack now includes `README.md`, `CHANGELOG.md`, and
  `LICENSE`/`LICENCE` (case-insensitive, symlinks excluded) in the flat
  registry archive, matching npm's bundling of standard root-level docs.
  (#1562)
- `install.sh` and `apm self-update` now send a conditional `Authorization`
  header on GitHub release-lookup API calls when `GITHUB_APM_PAT`,
  `GITHUB_TOKEN`, or `GH_TOKEN` is set, improving reliability on shared IPs and
  corporate NAT. Anonymous fallback is preserved when no token is configured.
  (closes #1582, #1588)
- **Experimental (`external-scanners`):** `apm audit` can now ingest findings
  from external SARIF 2.1.0 scanners (e.g. NVIDIA SkillSpector) via `--external
  <name>` and `--external-sarif <file>`, merging them into APM's own report and
  exit codes. APM's native content scan always runs; external findings are
  purely additive. Enable with `apm experimental enable external-scanners`.
  (#1579)
- **Experimental (`external-scanners`):** `apm install` can run an optional
  content audit over freshly deployed files (native hidden-character scan plus
  any policy-required external scanners). Off by default; opt in with
  `apm install --audit warn|block` (or `--no-audit`), set a default via
  `apm config set audit-on-install`, or mandate it org-wide via `apm-policy.yml`
  `security.audit.on_install`. Policy is a floor: it can raise the mode but
  never relax an org `block` (`--no-policy` opts out per-invocation), and a
  policy-required scanner missing at install time fails closed. (#1579)
- **Experimental (`external-scanners`):** `apm audit` exposes a configuration
  surface for external scanners -- `--external-llm/--no-external-llm` toggles a
  scanner's LLM analysis and `--external-args TEXT` passes shlex-split extra
  flags validated against a per-adapter allowlist (non-allowlisted,
  secret-looking, or out-of-cwd args are rejected fail-closed). Persist
  defaults with `apm config set external.<name>.{llm,args}`; orgs can restrict
  via `security.audit.scanners.<name>.allow_args: false`. LLM mode prints an
  egress banner, forwards `OPENAI_API_KEY`/`NVIDIA_INFERENCE_KEY` only for that
  run, and secret-redacts scanner stderr. (#1647)

### Changed

- `apm compile` no longer emits cosmetic debug comments (APM version,
  source-file headers, footer) in generated `CLAUDE.md` and
  `copilot-instructions.md` by default: `compilation.source_attribution` now
  defaults to `false` (was `true`), cutting token overhead in every LLM context
  that reads these files. Load-bearing markers are always emitted; set
  `compilation: source_attribution: true` to restore. (closes #1341, #1584)
- `apm pack` bundle export now strips credential-bearing keys and secret-shaped
  values from `.mcp.json` recursively before writing the bundle's merged
  `.mcp.json`. If consumers rely on those keys, replace them with `$ENV_VAR`
  references and inject values at MCP-host startup. (#1623)

### Deprecated

- `apm deps update` is deprecated in favor of `apm update`, which now exposes
  every flag it had. It prints a one-line banner and keeps working for one
  release; it will be removed in the next breaking release. (closes #1525,
  #1574)

### Removed

- **BREAKING:** `apm pack --marketplace-output PATH` has been removed.
  Deprecated in v0.14 with a stderr warning and auto-translated to
  `--marketplace-path claude=PATH`; use `--marketplace-path claude=PATH` to
  override the Claude output path. (closes #1318, #1585)

### Fixed

- `apm pack --check-clean` now emits a copy-pasteable recovery recipe
  (`git commit --amend --no-edit` + `git push --force-with-lease`, or a
  follow-up commit variant) when `marketplace.json` drifts from source, so
  producers get the right command at the point of failure. (closes #1381,
  #1610)
- `apm mcp install --help` epilog now references `apm install --help` instead
  of the invalid `apm install --mcp --help` combination that always raised a
  UsageError. (closes #1586, #1604)
- Custom-port credential errors now include a ready-to-run `git credential fill`
  verification command and a link to the auth troubleshooting docs. (closes
  #799, #1608)
- `apm install` now shows a recovery hint (`apm install --no-policy`) when the
  `required-packages-deployed` policy check fails, so users know how to unblock.
  (closes #1314, #1617)
- `apm install -g` now deploys `instructions` primitives for the Copilot target
  by concatenating each package's `*.instructions.md` into
  `~/.copilot/copilot-instructions.md` (the single file Copilot CLI reads at
  user scope); previously this primitive type was silently skipped for global
  installs. Each contribution is wrapped in an HTML provenance comment for
  auditability. (closes #650, #1619)
- `apm compile` with `managed_section` mode now raises a clear error when the
  target file does not exist instead of a confusing "markers not found"; create
  the file with markers first, or use `mode: full` for the initial generation.
  (closes #1593, #1606)
- `apm compile --target copilot` (and `agents`) no longer writes instructions
  into `AGENTS.md` when `apm install` already deployed them to
  `.github/instructions/`, eliminating duplicate context Copilot would read from
  both locations. Mirrors the existing Claude-path dedup. (closes #1550, #1590)
- `apm install` skips the `.gitignore` update for global-scope installs, so
  user-scope installs no longer touch a project `.gitignore`. (#1587)
- The primitive parser now normalizes list-valued `applyTo` and parses
  `handoffs` in agent frontmatter, so multi-glob `applyTo` and agent handoff
  declarations are honored instead of silently dropped. (#1629)
- `apm compile` managed-section error messages were polished for clarity when
  markers are missing or malformed. (#1609)
- `apm install` now always writes `apm.lock.yaml` when resolution succeeds,
  closing a gap where the lockfile could be skipped in some local-dependency
  flows. (#1652)
- **Experimental (`external-scanners`):** external SARIF ingestion now strips
  ANSI escape codes from scanner message text and passes `--no-llm` to
  SkillSpector by default while tolerating non-JSON stdout, hardening the
  experimental scanner path. (#1644, #1645)

### Security

- `apm install -g` now deploys `marketplace_plugin` `bin/` executables with
  user-only execute (owner +x; group and other execute bits cleared).
  Previously-deployed files are hardened in place on reinstall, so upgrading APM
  tightens permissions left by older versions. (#1626)

### Performance

- `apm install --update` no longer re-downloads a dependency when the in-flight
  resolution callback already fetched it at the correct SHA, eliminating a
  redundant network round-trip per up-to-date dependency. (closes #551, #1612)

## [0.16.1] - 2026-06-01

### Added

- `apm doctor` is now a top-level command (promoted from `marketplace doctor`) that diagnoses environment problems such as runtime setup, PATH wiring, and configuration, so users can health-check an install without remembering the `marketplace` namespace. (#1539)

### Fixed

- `apm install -g` (USER scope) no longer writes `apm_modules/` to the working-directory `.gitignore`; only project-scope installs update it. (closes #1577)
- `apm install -g --target copilot` now deploys prompt primitives to `~/.copilot/prompts/` while continuing to filter unsupported user-scope instructions. (closes #1482, #1570)
- Linux standalone `apm` binaries no longer fail git shared-cache clones with shared-library symbol lookup errors caused by PyInstaller dynamic-library paths leaking into child processes. (closes #1534)
- Avoid 13-minute `apm install` hangs in large local projects by limiting synthetic `_local` discovery to `.apm/` and `.github/`, while preserving package metadata discovery. (closes #1507) -- by @ioannispoulios
- `apm install -g <package>#<ref>` now updates an existing unpinned global dependency entry instead of leaving the manifest floating. (#1559)
- `apm install` no longer rewrites `apm.lock.yaml` when MCP dependencies are unchanged, keeping no-op installs byte-stable. (#1568)
- `apm install` now honors manifest `targets:` without falling back to the legacy Copilot target when singular `target:` is absent. (#1560)
- `apm install` now preserves executable permission bits when materializing package files through the reflink copy fast path and Artifactory ZIP extraction, so installed executables stay runnable. (closes #1563, #1566)
- `apm install` summary now reflects actual file mutations: a re-install with identical deployed files reports `No changes -- install state already up to date` instead of falsely claiming `Installed 1 APM dependency`. (closes #1557, #1569)
- `apm install --update <pkg>` no longer falls through to all manifest dependencies when the positional request already validates as present; lockfile serialization also de-duplicates `deployed_files` paths. (closes #1558, #1567)
- `apm install` no longer fails on a second run with a false-positive `Content hash mismatch ... supply-chain attack` error for unpinned git or virtual-file dependencies; the redundant re-download is skipped when the on-disk hash matches the lockfile. (closes #1548, #1553)
- `apm uninstall <pkg>` now scans `devDependencies.apm`, so packages added with `apm install --dev` can be removed instead of leaking in `apm.yml`. (closes #1549, #1552)

### Performance

- `apm install` is substantially faster on large projects and monorepos: primitive discovery is memoized across (integrator, target) pairs, the per-file `Path.resolve()` call is dropped, and skipped directories are expanded (up to 30-40x faster in the worst cases). (closes #1533, #1538)

### Documentation

- Surface the `compilation.strategy: distributed` default in the
  concepts ramp and `apm compile` reference so users understand why
  `apm compile` may add `AGENTS.md` / `CLAUDE.md` files in
  subdirectories driven by `applyTo:` scopes. Adds a new "Where
  compiled context files land" section to the primitives-and-targets
  page and a distributed-layout example in the compile reference.
  Default behavior is unchanged. (closes #1447) -- by @tillig

## [0.16.0] - 2026-05-28

### Added

- OpenAPM v0.1 normative spec at `docs/src/content/docs/specs/openapm-v0.1.md` with JSON Schemas for manifest/lockfile/policy and conformance fixtures under `tests/fixtures/spec-conformance/`, so third-party integrators can build conformant tools without reading the rest of the APM docs. (closes #1502, #1517)
- `ref:` on git-source dependencies now accepts semver ranges (`^1.2.0`, `~1.4`, `>=2.0 <3`, `1.5.x`). `apm install` resolves the highest matching remote tag and pins the resolved tag, SHA, and constraint in `apm.lock.yaml`; subsequent installs replay offline, `apm install --update` re-resolves. (closes #1488, #1496)
- `apm deps why <package>` explains why a transitive dependency was installed by walking the lockfile back to your direct declaration in `apm.yml`. Supports `--global` and `--json`; analogue of `npm why` / `yarn why`. (#1495)
- `policy.dependencies.require_pinned_constraint: true` bans unbounded version ranges across `apm.yml`, blocking accidental drift in governed environments. (#1494)
- Deterministic Artifactory boundary probe at install time, so nested GitLab group/subgroup repos behind a JFrog proxy install correctly via the bare-shorthand form (previously failed with HTTP 404). Auth errors (401/403) are now distinguishable from missing-repo errors, and bearer tokens cannot leak cross-host via redirect. (#1472)

### Changed

- **BREAKING:** `apm install` now exits `1` whenever the diagnostic summary reports `Installation failed with N error(s)`. Previously it exited `0` even after reporting errors, so CI could not detect failure. `--force` continues to bypass only the security scan's critical-finding block; it does not suppress general install errors (matches `npm` / `pip` / `cargo`). Callers that asserted `exit_code == 0` while errors were reported must update. (#1496)
- Artifactory parse-time boundary detection no longer relies on directory-name heuristics (`skills/`, `prompts/`, `agents/`, `collections/`, `instructions/`); the install-time HEAD probe is now authoritative for the `(owner, repo, virtual_path)` split. Explicit FQDN refs use a shallow `owner/repo` split; bare shorthand under `PROXY_REGISTRY_ONLY` uses a structural file-extension rule. (#1472)

### Fixed

- `install.ps1` on Windows now works on accounts whose profile path contains non-ASCII characters (e.g. an accented username): the generated `apm.cmd` shim embeds the literal `%LOCALAPPDATA%` token instead of a baked, code-page-mangled path. Previously `apm --version` reported `The system cannot find the path specified.` (closes #1509, #1512)
- `apm.cmd` Windows shim is now written as ASCII so `cmd.exe` parses it correctly when invoked via `PATH`. A previous attempt to write the shim as UTF-16LE broke fresh installs with garbled output and exit code 1. (#1522)
- `install.ps1` is now strict ASCII, so `apm self-update` on `cp1252` Windows consoles no longer crashes with `UnicodeEncodeError: 'charmap' codec can't encode characters`. (#1523)
- `apm install --target opencode` now warns at install time when an agent's frontmatter has shapes OpenCode's Zod schema rejects (`tools:` as list/string, non-hex/non-theme `color:`), so users learn why OpenCode refuses the agent instead of hitting only a runtime crash. (Phase 1 of #581, #1513)
- `apm compile --target claude` now honors `compilation.strategy: single-file` and `--single-agents`, collapsing into one root `CLAUDE.md` instead of silently emitting per-subdirectory files. (closes #1445, #1514)
- `apm install git@gitlab.com:owner/repo.git#ref` now succeeds for users with an SSH key and no `GITLAB_APM_PAT` / `GITLAB_TOKEN`: the validator honors the explicit SSH transport instead of demanding an HTTPS-token probe. GitLab SSH-key users get parity with GitHub SSH users. (closes #1501, #1515)
- `apm install -g` now correctly integrates hook JSON files authored in the "naked" Claude settings-slice format (event names at top-level, no outer `hooks:` wrap). Previously the file parsed cleanly but merged nothing while the summary still reported `1 hook(s) integrated`; the counter now reflects actual contributions and malformed shapes fail closed with a warning. (closes #1499, #1516)
- `apm install --update` now re-resolves direct git-source semver dependencies even when the dependency's install path already exists; previously the BFS resolver short-circuited and `--update` was a silent no-op for git-semver refs. (#1496)
- `policy.dependencies.require_pinned_constraint: true` no longer misclassifies the npm/cargo explicit-equality form `=1.2.3` as `BARE_BRANCH`. Both `1.2.3` and `=1.2.3` are pinned; pip-style `==1.2.3` is still rejected. (follow-up to #1494, #1506)
- `apm uninstall` now fully cleans `.windsurf/skills/<pkg>/` directories on the `windsurf` target. (by @yoelabril, #1486)
- `apm unpack` deprecation banner softened from "will be removed in v0.14" to "will be removed in a future release"; the previous wording shipped past v0.14.0 and contradicted reality. (#1511)

## [0.15.0] - 2026-05-27

### Security

- **BREAKING:** `apm install` against a `*.ghe.com` marketplace now refuses bare cross-repo `repo:` fields in `marketplace.json` before any network request runs, closing a dependency-confusion attack vector where `repo: owner/repo` could silently resolve to an attacker-controlled namespace on public `github.com`. Qualify with `corp.ghe.com/owner/repo` for same-host enterprise deps or `github.com/owner/repo` for declared cross-host deps. (closes #1326) -- by @edenfunf (#1459)

### Added

- `apm config set prefer-ssh true` / `apm config set allow-protocol-fallback true` persist transport preferences to `~/.apm/config.json` so SSH-only and corporate GHES users stop re-passing `--ssh` / `--allow-protocol-fallback` on every `apm install`. Resolution order: CLI flag > env var > `apm config` > default. (closes #1243, #1308)
- Experimental package registry resolver and `apm-policy.yml` source-mandate enforcement -- controlled sources, locked versions, byte-level SHA-256 verification. Git-based dependencies unchanged. Enable with `apm experimental enable registries`; configure per-registry credentials via `apm config set registry.<name>.{url,token}`; mandate via `registry_source: {require: [...], allow_non_registry: false}`. Package signing, SBOM, and SLSA provenance are out of scope for v1. (#1471)
- `marketplace.packages[].source` in `apm.yml` accepts non-default git hosts via the `host.tld/owner/repo` shorthand or the full `https://host.tld/owner/repo[.git]` URL for `apm pack`, unlocking GitHub Enterprise and self-hosted GitLab as first-class marketplace package sources. (#1288)
- `apm marketplace add` now accepts local filesystem paths, `file://` URIs, SSH URLs, and HTTPS URLs to any git host (Azure DevOps via `ADO_APM_PAT`, GitLab, Gitea, Bitbucket Server, self-hosted). Generic-git registrations fetch `marketplace.json` via `GitCache` and never forward APM tokens; local marketplaces read the manifest directly. Same change hardens `GitCache` against malicious upstreams: every clone/fetch/checkout sets `core.hooksPath=/dev/null` and skips submodule recursion. (#1476)

### Changed

- `apm compile` internals: deduplicated compilation config and registry-cursor refactor; no user-visible behaviour change but reduces drift between paths. (#1367)
- `triage-panel` skill: replace invalid `difc:` block with `tools.github.min-integrity` so the gh-aw workflow lints clean and integrity gating actually applies. (#1487)
- `triage-panel` skill: DIFC read-integrity exemption for external issues so triage can read community-reported issue bodies without the gate blocking. (#1462)
- CodeQL integration tests now assert on parsed URL components instead of substrings, removing a class of false-positive matches and matching the repo test convention. (#1492)

### Performance

- Scaling guards on variant-key and cache-lookup paths, wired into the CI integration gate so per-dep resolution regressions fail PRs instead of slipping to main. (#1439)

### Fixed

- `apm install` re-resolves a dependency when its ref pin changes in `apm.yml` and `--refresh` actually re-resolves all pins (previously accepted but no-op) -- by @sergio-sisternes-epam (#1473)
- Copilot, Codex, Cursor, Claude, Windsurf, OpenCode, and Gemini adapters handle MCP v0.1 `runtimeArguments`/`packageArguments` with `variables` (no `type` key), matching the VS Code fix from #1444. (#1461, closes #1452, thanks @sergio-sisternes-epam)
- `apm compile --target claude` omits the "Project Standards" section from `CLAUDE.md` when instructions are already deployed to `.claude/rules/` by `apm install`, avoiding duplicate content in Claude Code's context window. `CLAUDE.md` is still generated for constitution and dependency imports. (closes #1138, #1146)
- `apm compile --watch` now live-reloads `apm.yml` edits instead of caching the initial snapshot, and warns when combined with `--clean` so a watch session does not silently wipe state on every change. (#1403)
- Windows: `_local_path_from_source` handles `file://` URI shapes (drive-letter, UNC) so local marketplaces on Windows resolve correctly, and preserves POSIX separators on plain POSIX-shaped inputs (`Path().expanduser()` was rewriting `/home/user` to `\home\user`); local-path pass-through is now cross-platform. (#1484)
- `apm install` rewrites skill-shipped MCP `command` paths for the Claude target so portable installs resolve relative to `.claude/` instead of the source skill's checkout. (#1465)
- Unstuck 3 flaky integration tests that were intermittently blocking the merge queue. (#1477)

## [0.14.2] - 2026-05-22

### Added

- **Experimental:** `copilot-app` target scopes workflows to a real project row via loopback WS IPC (App running) or direct SQLite (App closed); `--global` workflow installs emit a one-time CWD-pivot warning. (#1431)
- `apm pack --marketplace=FORMATS` filters which marketplace formats build in a single run; accepts comma-separated names and `all`/`none` sentinels. (#1324)
- `apm pack --marketplace-path FORMAT=PATH` overrides the output path for a specific marketplace format at invocation time. (#1324)
- `apm pack --json` emits a stable JSON contract to stdout (`{ok, dry_run, warnings, errors, marketplace: {outputs: [...]}}`); all logs move to stderr so downstream tooling can `jq` the output. (#1324)
- `marketplace.outputs` in `apm.yml` accepts a map form keyed by format name (`outputs: {claude: {}, codex: {path: ...}}`), replacing the deprecated list form; the list form still parses with a one-cycle deprecation warning. `apm marketplace init` now scaffolds the explicit map form. (#1324)

### Changed

- PR-time CI shards unit tests, moves the 80% coverage gate off the critical path, and parallelises the PyInstaller build for faster contributor signal. (#1437)
- Unit coverage raised to 88% (gate 80%); integration coverage raised to 71% (gate 55%). (#1402)
- Replace logic-replay tests for #763 with real-flow coverage to catch real regressions. (#1340)

### Performance

- Cold `apm install` for subdirectory git deps is ~30x-75x faster on large monorepos via partial bare clones plus sparse-cone materialization; transparent fallback when servers reject `--filter=blob:none`. (#1436, closes #1433)

### Fixed

- Windows: GitCache sparse-cone consumer clone no longer fails with `Filename too long`; `git clone`/`checkout` pass `-c core.longpaths=true` on Windows so the nested `checkouts_v1/<shard>/<sha>/<variant>.incomplete.<pid>.<ns>/` layout stays within the Win32 path limit. (#1454)
- Windows: `copilot-app` WS handshake no longer rejects `~/.copilot/run/ws.token` because Windows synthesises group/other bits from the read-only flag; the POSIX-only mode check now short-circuits to accept on Windows. (#1454)
- `apm install` honours per-dependency `registry:` URLs in MCP deps instead of warning and ignoring them. (#1443, closes #1393)
- VS Code adapter handles MCP v0.1 `runtimeArguments` with `variables`, unblocking Docker MCP servers that need workspace mounts. (#1444, closes #1391)
- `apm install --skill <name>` persists the skill filter to `apm.yml` so subsequent runs honour the selection. (#1442, closes #1395)
- `apm audit` no longer false-flags non-skill primitives as orphaned drift on `auto_create=False` targets. (#1441, closes #1411)
- Copilot harness auto-detection recognises `.github/instructions/`, `agents/`, `prompts/`, and `hooks/` as valid markers. (#1440, closes #1435)
- `apm install` (project-scope) keeps hook `command` paths repo-relative so committed configs stay portable across clones and CI. (#1396, closes #1394)
- PyInstaller binary restores `optimize=2`, shrinking the Windows Defender ML false-positive surface. (#1450)
- Comma-separated `applyTo` globs emit proper YAML lists in Claude, Cursor, and Windsurf instruction outputs (brace-aware split). (#1387, #1449, closes #1366)
- `GitCache` no longer crashes on Windows `file://` URLs where `urllib.parse.port` raises `ValueError`. (#1446)
- `apm compile` discovers local-bundle instructions inside `apm_modules/` again. (#1388)
- `apm install --target copilot-app` warns instead of failing when the App schema is newer than expected. (#1434)
- Plugin packaging no longer destroys pre-positioned `.apm/` content during artifact mapping. (#1416)
- `apm update` against private ADO deps no longer fails on Windows with a misleading "az not logged in" -- `az.cmd` is now resolved via `shutil.which`; ADO preflight preserves `GIT_*` env so GCM can fall back. (#1432, closes #1430)
- Windows unit-test job is green again (Codex CLI path quoting + ADO subprocess env). (#1427)
- Root `.apm` hooks no longer duplicate after directory renames or worktrees; hook source-ids derive from `apm.yml` `name` and self-heal stale entries. (#1392, closes #1329)
- Codex and Gemini stdio MCP configs expand `${env:VAR}` placeholders in self-defined env vars. (#1277, closes #1266)
- Codex CLI now supports Streamable HTTP MCP servers, matching the other harnesses. (#1262, closes #1260)
- `apm install` preflight uses ssh (not https) on ssh-based dependency URLs. (#1303, closes #1293)

## [0.14.1] - 2026-05-20

### Added

- **Experimental:** `copilot-app` target deploys prompts (with optional workflow frontmatter) directly into the GitHub Copilot desktop App's `~/.copilot/data.db` workflows table; shape-dispatched `.prompt.md` (workflow keys `interval` / `schedule_hour` / `schedule_day` route to the App, plain prompts route to slash-command targets) so each prompt lands on exactly one surface. Gated behind `apm experimental enable copilot-app`; works in project (`apm install --target copilot-app`) and user (`--global`) scope; workflows install disabled, user opts in from the App. See [Copilot App integration](https://microsoft.github.io/apm/integrations/copilot-app/). (#1405)

### Fixed

- `apm install` honors the SSH user portion of dependency URLs (`ssh://user@host/...` and scp shorthand `user@host:org/repo`) instead of hardcoding `git@`; unblocks EMU accounts and other non-`git` SSH identities. (#1385, closes #1383)
- Windows installer and `apm self-update` detect Windows Defender / antivirus blocks (HRESULT `0x800700E1`, PUA messages) and surface three actionable recovery options (`Add-MpPreference -ExclusionPath`, `pip --user`, false-positive submission URL) instead of falling through to a generic "failed to run" and a pip fallback that itself dies on unsupported Python. (#1408)
- Windows installer and `apm self-update` survive AppLocker / App Control for Business (WDAC) policies by staging the release into the allow-listed per-user install root before running the `apm.exe --version` smoke test, and emit AppLocker-specific guidance on `0x80070005` Access Denied instead of silently falling back to pip. (#1390, closes #1389)
- `apm uninstall <local-path>` on Windows no longer rejects absolute paths (`C:\...\my-pkg`) as "Invalid package format" and silently leaves deployed copilot-app workflow DB rows behind. Local paths are now detected on every platform, so install/uninstall round-trips cleanly. (#1413)

### Changed

- `apm compile --watch` picks up mid-session edits to `apm.yml`'s `target:` / `targets:` on the next file event instead of caching the resolved target until the watcher is restarted; previously the value resolved at startup was reused on every recompile. Follow-up to #1349. (#1403)
- `apm compile --watch --clean` prints an explicit `[!]` warning that `--clean` is ignored in watch mode and continues; previously the flag was silently dropped. Run `apm compile --clean` separately between watch sessions to remove orphaned outputs. (#1403)

## [0.14.0] - 2026-05-18

### Breaking

- **MCP Registry v0.1**: self-hosted registries must serve `/v0.1/` paths (legacy `/v0/`-only registries return 404). `api.mcp.github.com` and `registry.modelcontextprotocol.io` are unaffected. Python API: `get_server_info(uuid)` -> `get_server(server_name, version)`; old name remains one minor as `DeprecationWarning`. Thanks @fassmus for the report. (#1337, closes #1210)

### Added

- `apm plugin init` is the canonical noun-verb command for scaffolding a plugin project; composes with `apm marketplace init` so single-plugin, aggregator, and hybrid repo shapes emerge from verb composition (no `--shape` flag). New docs: [Repo shapes](https://microsoft.github.io/apm/producer/repo-shapes/), [Releasing from any CI](https://microsoft.github.io/apm/producer/releasing-from-any-ci/), [Versioning strategies](https://microsoft.github.io/apm/producer/versioning-strategies/). (#1370)
- `apm init` prints a "Next steps" panel surfacing both `apm plugin init` and `apm marketplace init` alongside consumer commands, teaching the noun-verb taxonomy at zero migration cost. (#1370)
- `apm pack --check-versions` validates per-package versions against `marketplace.versioning.strategy` (`lockstep` / `tag_pattern` / `per_package`); exits `3` on misalignment. (#1365)
- `apm pack --check-clean` regenerates each `marketplace.json` into a temp dir and diffs against the committed copy; exits `4` on drift. Never writes to the working tree. (#1365)
- `apm.yml` schema: new optional `marketplace.versioning: { strategy: ... }` block (default `lockstep`); existing manifests unaffected. (#1365)
- `apm marketplace doctor` adds `format coverage` and `version alignment` rows surfacing missing supported outputs and per-package drift. (#1362, #1365)
- `apm pack --marketplace=FORMATS` filters which marketplace formats build in a run; accepts comma-separated names and sentinels `all`/`none`. (#1317)
- `apm pack --marketplace-path FORMAT=PATH` overrides the output path for a specific format at invocation time. (#1317)
- `apm pack --json` emits a stable JSON contract on stdout; all logs move to stderr so tooling can `jq` the output safely. (#1317)
- `marketplace.outputs` in `apm.yml` accepts map form `outputs: {claude: {}, codex: {path: ...}}` (the deprecated list form still parses with warning). (#1317)
- `apm uninstall` accepts marketplace notation (`my-plugin@official`), symmetric with `apm install`; offline-first via lockfile with registry fallback guarded against canonical injection. (#1325)
- `apm update` adds `--target/-t` to scope refresh to a single agent. (#1358)
- `install.ps1` accepts air-gapped / GHES env vars (`VERSION`, `GITHUB_URL`, `APM_REPO`, `APM_INSTALL_DIR`, `APM_SKIP_CHECKSUM`) for Windows pinned installs, matching `install.sh`. (#1246)
- Prefer APM-managed runtime binaries over system PATH; warn at setup time on Codex >= v0.116 + GitHub Models incompatibility instead of failing silently later. (#1356)

### Changed

- **`apm update` is roughly two orders of magnitude faster on multi-dep manifests**: a four-tier resolver (in-memory cache -> GitHub commits API -> bare `rev-parse` -> legacy clone) collapses redundant `git clone --depth=1` calls. Same wiring benefits install, outdated, and publish. (#1376, closes #1369)
- `shared/apm.md` gh-aw workflow no longer fails with `no apm bundles found` for form-2 (single-app) and form-3 (`apps[]`) consumers: GitHub Actions was silently stripping the private-key PEM from the `apm-prep` job's matrix output as a secret leak. (#1373)
- `apm pack` appends a vendor-neutral catalog after per-output success listing each marketplace artifact and a single docs anchor; never names a vendor CLI surface. (#1362)
- `apm marketplace init` scaffolds map-form `outputs: {claude: {}}` with a single-line `# codex: {}` commented toggle; flip one line to enable Codex output. (#1362)
- `apm install` from `*.ghe.com` (GHE Cloud) marketplaces routes auth at the registered enterprise host instead of silently defaulting to `github.com` and 401'ing; the resulting `apm.yml` records the correct enterprise `git:` URL. (#1292)
- `apm install` from `*.ghe.com` marketplaces surfaces a warning-level hint when a bare-`repo` cross-repo plugin source fails validation, naming the enterprise host and the host-qualified `repo` value to set. (#1319)
- `extends: org` correctly layers `dependencies.require` / `dependencies.deny` and `unmanaged_files` when the child omits the block entirely (`None` = transparent, `[]` = explicit override). (#1290, #1248)
- `--marketplace-output PATH` is hidden from `--help` and emits a stderr deprecation warning; auto-translates to `--marketplace-path claude=PATH`. (#1317)
- `apm view --help` and the `view` row in `apm --help` render in release binaries again; PyInstaller `optimize=2` was stripping `__doc__` from every Click command. (#1307)

### Deprecated

- `apm init --plugin` and `apm init --marketplace` are deprecated in favor of `apm plugin init` and `apm marketplace init`; legacy flags still work and print a one-line stderr warning, **removal in v0.16**. (#1370)

### Fixed

- `apm compile --watch` honors `targets: [...]` on every recompile instead of silently regenerating all-target outputs. (#1349, closes #1345)
- `apm install` no longer permanently blocks installs gated by `required-packages-deployed` after a degraded `deployed_files=[]` lockfile: non-skill integrators silently adopt byte-identical pre-existing files. (#1313)
- `apm audit` drift check returns skip-with-info (`passed=True`) when the install cache is cold, instead of failing the audit; CI pipelines that have not yet run `apm install` are not incorrectly red-marked. (#1289)
- `apm pack` no longer prints a misleading "No plugin.json found" warning for marketplace-publishing projects. (#1362)
- `apm marketplace init` scaffolds the snake_case `tag_pattern: "{name}-v{version}"` example instead of the schema-invalid camelCase `tagPattern`. (#1362)
- `apm install` respects the `targets:` whitelist for MCP servers exactly like skills, dropping non-listed runtimes even when their on-disk signal exists; greenfield projects (no `targets:`, no `--target`, no signals) now error consistently between `apm install` and MCP-only invocations. (#1336, closes #1335)
- Gemini CLI: `apm install -g --mcp NAME` writes to `~/.gemini/settings.json` (user scope); project-scope writes land at `<project_root>/.gemini/settings.json` instead of `cwd`. (#1306, closes #1299)
- Claude target: hook commands with relative paths now resolve to absolute paths in `settings.json`. (#1354, closes #1310)
- Claude target: hook ownership metadata is stored in a `.claude/apm-hooks.json` sidecar so APM can track owned hooks without violating the Claude `additionalProperties` schema. (#1359, closes #1279)
- Claude target: `apm install` preserves self-defined stdio MCP `env` values from `apm.yml` and stringifies non-string values like `PORT: 3000` for MCP compatibility. (#1224, closes #1222)
- Direct GitHub API and ADO/GHES `git ls-remote` calls now respect `PROXY_REGISTRY_ONLY` mode; all four validation paths skip outbound network probes. (#1357, closes #615)
- Target propagation no longer drops mid-pipeline at the intermediate `CompilationConfig` stage. (#1355, closes #765)
- `apm pack` and `apm install` now warn when `apm.yml` is missing but APM artifacts exist on disk. (#1255, closes #1056)
- `apm install` accepts Bitbucket Data Center / Server personal-repo URLs containing `~` (e.g. `https://example.com/scm/~user/repo.git`); the path-component whitelist on non-ADO hosts now includes `~` (RFC 3986 unreserved). Sourcehut `~user` paths are incidentally unblocked too. (#1377, closes #1375)

## [0.13.0] - 2026-05-11

### Breaking Changes

- The CLI self-updater moved from `apm update` to `apm self-update`. Inside an `apm.yml` project the bare `apm update` verb now refreshes project dependencies (matching `npm update`, `uv lock --upgrade`, `cargo update`); outside a project it forwards to `apm self-update` with a deprecation banner for one release. CI scripts that called `apm update` to refresh the binary should migrate now: `sed -i 's/apm update/apm self-update/g' your_scripts`. (#1244)

### Added

- `apm update` refreshes project dependencies the way npm/pip/cargo users expect: resolves `apm.yml` against latest refs, shows an added/updated/removed/unchanged plan, and prompts before mutating anything (`--yes` skips, `--dry-run` previews). (#1244)
- `apm self-update` updates the APM CLI binary itself (or shows distributor guidance when self-update is disabled at build time); `--check` only checks for a newer version. (#1244)
- `apm install --frozen` performs a CI-safe, read-only install that fails fast (exit 1) when `apm.lock.yaml` is missing or out of sync with `apm.yml`; mutually exclusive with `--update`. (#1244)
- Zero-config private-package auth on github.com, `*.ghe.com`, and GHES when the `gh` CLI is logged in: APM uses `gh auth token --hostname <host>` before falling back to `git credential fill`. (#630)
- GitLab marketplace and install support: `gitlab.com` and self-managed instances (via `GITLAB_HOST` / `APM_GITLAB_HOSTS`) use GitLab REST v4 for `marketplace.json` and raw file reads; nested group paths are disambiguated via object-form `git:` + `path:`. (#1149)
- **Windows installer parity:** CI and GHES/air-gapped runners can **pin `VERSION`**, set **`GITHUB_URL`** (https only) and **`APM_REPO`**, and use **`APM_INSTALL_DIR`** like `install.sh`. Pinned installs verify the release **`.sha256`** unless **`APM_SKIP_CHECKSUM=1`** or **`-SkipChecksum`** (emergency only); `GITHUB_URL` drives GitHub.com (`api.github.com`) vs GHES (`{host}/api/v3`) for latest discovery. (#668)
- Virtual subdirectory and raw-file packages now resolve from self-hosted Git services (Gitea, Gogs) via raw URL with API v1/v3 fallback. (#587)
- `git: parent` lets packages in a git monorepo reference sibling paths via `{ git: parent, path: ... }` without repeating the full `git:` URL; the lockfile stores expanded host, repo, and resolved ref like every other virtual git dependency. (#1149)
- `shared/apm.md` gh-aw workflow exposes a `target:` import input (default `all`) so consumer workflows can ship slim, single-harness bundles. (#1184)

### Changed

- `apm marketplace browse/search/add/update` route through the registry proxy when `PROXY_REGISTRY_URL` is set; `PROXY_REGISTRY_ONLY=1` blocks direct GitHub and GitLab host fallbacks; a plaintext-bearer warning fires on `http://` proxies unless `PROXY_REGISTRY_ALLOW_HTTP=1` is set. (#1149)
- `apm install --force` help text now states the flag does NOT refresh refs; the no-op nudge now reads "Lockfile already satisfied -- run `apm update` to resolve latest refs"; a one-time CI banner fires when `apm update` runs under `CI`/`GITHUB_ACTIONS` so pipelines see the dependency-refresh shift. (#1244)
- Tier-2 smoke job runs `tests/integration/test_core_smoke.py` against the built binary, exercising `init` / `install` / `compile` / `audit` / `policy status` to fail fast on the README promises; replaces `test_runtime_smoke.py`. (#1251)
- Integration tests now use marker-driven discovery: `requires_*` markers replace 21 `pytestmark = pytest.mark.skipif(...)` chains, `scripts/test-integration.sh` is a thin orchestrator, and new test files dropped into `tests/integration/` are picked up automatically. (#1167, #1247, #1249)
- Integration test apm-binary resolution prefers the local build (`./dist/apm-<os>-<arch>/apm`) over a system-wide `apm` on `PATH`, so contributors validating the binary under test are not silently shadowed by a global install. (#1167)
- Integration Tests merge-queue job is now sharded 4-way via pytest-split with `-n 2` xdist per shard, cutting wall-clock from ~30 min to ~6 min while keeping HOME-mutating tests race-safe. (#1263)

### Fixed

- `apm install` no longer silently overwrites pre-existing governance files; `check_collision()` now treats `managed_files=None` (first install, no lockfile) as an empty set so hand-rolled files in `.github/instructions/` are detected and protected. (#1256)
- Policy inheritance now fails closed: child policies that omit `unmanaged_files` inherit the parent's action instead of silently defaulting to `ignore`. (#1253)
- MCP server token injection now requires both an allowlisted server name and a verified HTTPS GitHub hostname, preventing PAT exfiltration via poisoned registry entries. (#1239)
- `apm install --target cursor` now emits Cursor-native MCP schema (`type: stdio` / `type: http`) instead of Copilot-only fields that Cursor silently discards; `.cursor/mcp.json` is gitignored to prevent accidental token commits. (#1240)
- `apm install` accepts full ADO HTTPS URLs with sub-path virtual packages (e.g. `https://dev.azure.com/org/proj/_git/repo/sub/path`) instead of rejecting them. (#1254)
- `apm install` no longer crashes with exit 128 when a mono-repo package depends on a sibling pinned to a non-HEAD commit; multiple SHA-pinned refs to the same repository now share a single cached clone. (#1258, #1259)
- `apm install --update` falls back from a stale `ADO_APM_PAT` to an `az login` AAD bearer in the preflight auth probe, matching the behavior of `apm install`; per-host stale-PAT warnings are lock-guarded so parallel installs emit one warning instead of one-per-thread. (#1212, #1214)
- `apm install` rejects unsupported flat-format `dependencies` (e.g. `dependencies: [owner/repo]`) with a clear error and structured-format hint instead of silently ignoring them. (#1189)
- `apm install` accepts the YAML list form under `target:` (e.g. `target: [copilot, claude]`); previously crashed with a garbled `Unknown target` error. (#1197)
- `apm install --target all` no longer enumerates the experimental `copilot-cowork` target, which was crashing project-scope installs and making `gh aw` workflows that pin `target: all` unusable. (#1191)
- `apm install --global <abs-local-path>` no longer rejects absolute local paths at user scope (regression from #1149); restores the post-#937 contract that only relative local paths are ambiguous at user scope. (#1247)
- `apm install` against a `--global` scope now writes MCP entries to the scope-resolved lockfile path instead of the project lockfile. (#1236)
- `apm install <git+https://...>` direct refs now apply the same manifest-driven credential validation as `apm.yml`-declared dependencies, closing a silent auth-fallback gap. (#1242)
- Dependency references no longer treat `:443`/`:80`/`:22` as distinct from default-scheme ports, so two manifest entries that differ only by an explicit default port resolve to the same package. (#1237)
- The experimental `cowork` config key is hidden from `apm config` output, and the verbose target-resolution log no longer leaks internal cowork plumbing. (#1241)
- Multi-account Git Credential Manager users: APM selects the right GitHub account automatically per repository (no account-picker prompt) when `credential.useHttpPath = true` is set. (#1226)
- `apm install` target-agnostic local bundles: `apm pack` no longer hardcodes `pack.target` into bundles; `apm install <bundle>` resolves the consumer target from project context and wires `.mcp.json` servers per target. (#1207, #1217)
- `Unknown target` error suggestions no longer advertise the `agent-skills` meta-target (which `apm targets` intentionally omits); the canonical set still accepts `agent-skills` via `--target` and `apm.yml`. (#1208, #1215)
- `apm outdated --help` now renders the missing one-line description. (#1216)
- `shared/apm.md` no longer wraps the `target` input in a `|| 'all'` fallback that broke gh-aw's expression-substitution regex and silently dropped consumer-supplied `target:` values. (#1185, #1186)
- GitLab monorepo marketplaces: `apm install plugin@marketplace` resolves plugins whose sources live in a subdirectory of the marketplace repository on GitLab-class hosts. (#1149)
- Protocol-fallback port warnings are deduplicated across parallel download workers via a threading lock, so each (host, repo, port) triple warns exactly once. (#1238)
- `apm marketplace add` accepts GitLab-class hosts; unsupported generic hosts now show separate recovery hints for GHES (`GITHUB_HOST`) and self-managed GitLab instead of only `GITHUB_HOST`. (#1149)
- Realigned the integration suite with current product contracts: copilot-target detection requires `.github/copilot-instructions.md` (post-#1154), `apm marketplace build` is removed in favor of `apm pack`, ADO virtual collections use the SUBDIRECTORY layout (post-#1094), and the `repo:` apm.yml key is replaced by `git:`. (#1257, #1261, #1264)
- `triage-panel` scheduled sweep now paginates oldest-first via GitHub MCP `search_issues` with `-label:status/triaged sort:created-asc`, so daily runs drain the untriaged backlog instead of processing one issue per cron tick. (#1193, #1194)
- **Policy `unmanaged_files`:** Child policies that omit the block (or use an empty mapping) under `extends:` inherit the parent org settings transparently, fixing silent downgrades such as losing `action: deny`; values that are not YAML mappings (lists or scalars) are rejected with a recovery hint. (#1198, #1248)

## [0.12.4] - 2026-05-07

### Fixed

- `apm install` now removes deployed files when a package is removed from `apm.yml`. Three sequential early-returns previously short-circuited the cleanup phase when the manifest was emptied; the orphan-cleanup logic itself was correct. (#1173)
- `apm audit --ci` no longer reports false drift on self-package primitives that link to repo-root files (`[..](../../FILE.md)`). The replay's in-package asset rewriter now re-anchors `target_location` onto `package_root` when the candidate sits outside the scratch tree, mirroring real-install output. (#1182)

## [0.12.3] - 2026-05-06

### Security

- `apm install --target copilot` no longer bakes secret values into `~/.copilot/mcp-config.json`: env-var placeholders (`${env:VAR}`, `${VAR}`, legacy `<VAR>`) are translated to Copilot's native `${VAR}` runtime form so secrets never touch disk. Rotate any previously-baked secrets and re-run install. (#1169, closes #1152)

### Changed

- Explicit, auditable target resolution: `apm install` / `apm compile` follow a strict `--target` > `apm.yml target:` > auto-detect chain, print a `[i] Targets: ... (source: ...)` provenance line, and exit 2 on empty repos instead of silently defaulting to `copilot`. Adds `apm targets` discovery command and `apm compile --all` (deprecates `--target all`). (#1165, closes #1154, #1122, #1130, #518, #888, #891, #650, #1056)
- `apm init` opens an interactive numbered-toggle target checklist pre-seeded from filesystem signals so users land in Tier 2 (`apm.yml target:`) by default; adds `--target` for scripted use. (#1165)
- `apm install` honours `policy.fetch_failure_default: block` for `no_git_remote` / `absent` / `empty`, matching the audit behaviour. (#1164)

### Fixed

- `apm audit --ci` no longer silently passes when no org policy is resolved: auto-discovery warns on stderr and honours `policy.fetch_failure_default: block` to fail closed (exit 1); JSON/SARIF on stdout stays clean. (#1164, closes #1159)
- SCP-shorthand SSH URLs from non-`git` users -- `<user>@github.com:owner/repo` (EMU) and `<user>@ssh.dev.azure.com:v3/<org>/<project>/<repo>` (ADO) -- now parse correctly in dependency parsing and policy auto-discovery. (#1164)
- `apm install` against a branch ref re-downloads when upstream advances past the lockfile-recorded SHA, and self-heals lockfiles produced by APM <= 0.12.2 on next install. (#1158)
- In-package relative markdown links are rewritten to their `apm_modules/` location at install time so sibling references survive the `.agents/.github` deploy split. (#1160, closes #1147)
- `.apm-pin` cache marker no longer leaks into skill deploy targets on subsequent installs. (#1153)

## [0.12.2] - 2026-05-05

### Added

- **`apm audit` now catches forgotten installs and hand-edits by default.** No more shipping stale `.github/instructions/` because someone forgot to re-run `apm install`, no more silent hand-edits to regenerated content. Opt out with `--no-drift`. See the [Drift Detection guide](https://danielmeppiel.github.io/awd-cli/guides/drift-detection/). (#1137, closes #1071, supersedes scope of #898)

### Fixed

- **Parallel subdir install race.** `apm install` no longer intermittently fails with `RuntimeError: Subdirectory '<path>' not found in repository` when multiple dependencies (including ADO sub-path deps) resolve to different subdirectories of the same `repo@ref`. The shared clone cache now stores subdir-agnostic bare clones and each consumer materializes its own working tree (mirrors the WS3 `GitCache` pattern). (#1135, fixes #1126, fixes #1140)
- **Re-installing the same package no longer rmtree's it.** `compute_package_hash` now excludes the `.apm-pin` cache marker (introduced by #1137) so the supply-chain content-hash check sees a stable hash across installs instead of falsely tripping and deleting `apm_modules/<owner>/<pkg>/`. (#1142, regression from #1137)

### Changed

- **Docs: `first-package` guide accuracy.** Clarifies how `includes: auto` actually behaves and corrects the skill deployment paths so a newcomer's first package matches what `apm install` writes to disk. (#1129)
- **Docs: APM's role for skills, plugins-as-packages, ADO sub-paths.** Six user-surfaced doc gaps closed in one pass -- unifies the "plugin == package" framing, adds ADO sub-path install examples, and states the current stability posture so users stop guessing from release notes. (#1127)

## [0.12.1] - 2026-05-03

### Added

- **Cursor slash command support (Cursor 1.6+).** `apm install` deploys package `.prompt.md` files to `.cursor/commands/*.md` when a `.cursor/` directory is present, completing cross-tool slash-command parity with Claude Code, OpenCode, and Gemini CLI. (#1046)
- **`apm install` performance + UX overhaul:** WS3 persistent two-tier cache for git + HTTP (with rev-parse HEAD verification on cache hits), parallel level-batched BFS dependency resolution, parallel MCP registry batch lookups with ETag-revalidated HTTP cache, in-install repo clone dedup for subdirectory deps, reflink-aware file copies with write-dedup for cache checkouts, live progress UI for parallel resolution and download, per-phase timing in `--verbose`, elapsed time on every exit path, and ASCII-only progress bar. (#1116)

### Fixed

- **gh-aw lock workflows: bump `microsoft/apm-action` v1.5.0 -> v1.6.0** so packed bundles use the legacy `--format apm` layout that `apm unpack` accepts after the v0.12.0 default flip to plugin format. (#1121)
- **Windows CI: explicit UTF-8 encoding** in the `_make_package` test helper to unblock Windows runners. (#1124)

## [0.12.0] - 2026-05-03

### Added

- **`--target agent-skills` deploys skills to `.agents/skills/` (cross-client shared directory).** The new target writes `SKILL.md` files to the [agentskills.io](https://agentskills.io) standard location without tying them to a single client. Excluded from `--target all` (explicit opt-in only); combine with `--target all,agent-skills` for both. Deduplicates with Codex when both targets resolve to the same path. User-scope (`-g`) deploys to `~/.agents/skills/`. (closes #737)
- **Claude Code as MCP install target.** `apm install --runtime claude` (and auto-detection when `.claude/` exists or the `claude` binary is on PATH) writes MCP server entries to project-scope `.mcp.json` and user-scope `~/.claude.json` per the [Claude Code MCP schema](https://code.claude.com/docs/en/mcp). Project writes are opt-in (gated on the presence of `.claude/`, mirroring Cursor/OpenCode) and user writes are atomic with `0o600` permissions on first creation so concurrent Claude Code sessions cannot truncate the shared config or leak embedded OAuth state. Stdio entries are emitted with explicit `type: "stdio"` so `claude mcp list` renders them identically to entries installed via `claude mcp add --transport stdio`. Schema fidelity is regression-locked by golden fixtures captured live from the upstream `claude` CLI (see `tests/integration/test_claude_mcp_schema_fidelity.py`). Stale-cleanup defaults conservatively when the install scope is unspecified -- only the project file is touched without an explicit `-g/--global` opt-in. Note: Claude Code's third LOCAL scope (per-project private under `~/.claude.json -> projects.<path>.mcpServers`) is intentionally not implemented, since APM packages target reproducible team installs (PROJECT/USER), not per-user-per-project private state. (#1104, closes #643) -- by @dmartinol
- **`apm install <local-bundle-path>` deploys a previously packed bundle (directory or `.tar.gz`) air-gapped, with sha256 integrity verification against the bundle's embedded `apm.lock.yaml`.** Honours `--target`, `--global`, `--force`, `--dry-run`, plus a new `--as ALIAS` log/display label flag. Local installs record written paths in the project lockfile (`local_deployed_files` / `local_deployed_file_hashes`) and never mutate `apm.yml`. `apm unpack` is now `[Deprecated]` and points at this entrypoint. (#1098)
- **`apm pack` now embeds `apm.lock.yaml` inside the bundle** with two new `pack:` fields (`target`, `bundle_files`: a `path -> sha256` manifest) so installs can verify integrity and detect target mismatches before writing any file. (#1098)
- **`apm compile -t copilot` now emits `.github/copilot-instructions.md` with zero user configuration** -- APM's first Copilot-native compile target. Global instructions in `.apm/instructions/` are assembled into the file VS Code and GitHub Copilot read automatically; switching targets cleans it up. APM dogfoods this target. (#1048)
- **`apm marketplace add` accepts full HTTPS URLs and nested HOST/group/sub/.../REPO shorthands.** You can now paste a repository URL straight from the browser (e.g., `apm marketplace add https://github.com/acme/plugin-marketplace`) and register marketplaces hosted under nested sub-paths on GitHub Enterprise (`ghes.corp.example.com/org/team/repo`). Path-traversal sequences in the parsed segments are rejected via `validate_path_segments`. Non-GitHub hosts (GitLab, Bitbucket, etc.) are explicitly rejected at registration time with an actionable error -- this avoids forwarding GitHub credentials to unintended hosts and the silent fetch-time 404 that previously resulted; native non-GitHub support is tracked separately. (#1034, closes #1027)
- Regression tests for `apm compile` placement of narrow `applyTo` patterns: instructions whose matches all live deep inside one subtree are now pinned to the deepest covering directory instead of being hoisted to the project root, across both selective and single-point placement strategies. Also covers the file-walk cache that skips repeated filesystem scans for the same glob. (#871)
- **`apm marketplace audit <name>`** -- detect supply-chain risk in a marketplace with one command. It fetches each plugin's own `apm.yml` at its pinned ref and warns when transitive `dependencies.apm` entries bypass marketplace pinning. Default run is informational and exits 0; `--strict` exits non-zero on bypass warnings or unverifiable plugins, for use in CI. Complements the existing `apm marketplace doctor` environment diagnostics. (#881)
- **`apm pack` marketplace builder hardening.** Local source paths are now emitted relative to `metadata.pluginRoot` (fixes double-prefix bug). New pass-through fields: `author`, `license`, `repository`, `keywords` (alias for `tags`). Curator-wins override semantics for `description`/`version` on remote entries. Security guards reject path traversal and absolute paths post-subtraction. (#1061)
- **Plugin manifest schema-conformance tests.** `tests/unit/test_plugin_exporter_schema.py` validates every shape of `plugin.json` produced by `apm pack` (synthesized, authored, and authored-with-stale-keys) against the vendored official schema. Companion marketplace conformance lives in `tests/unit/marketplace/test_schema_conformance.py`. (#1061)
- **APM now compiles and integrates to Windsurf/Cascade.** New first-class `--target windsurf` support: instructions deploy as `.windsurf/rules/` with trigger frontmatter, agents deploy as `.windsurf/skills/<name>/SKILL.md`, commands as `.windsurf/workflows/`, hooks merge into `.windsurf/hooks.json`, and MCP servers configure via `~/.codeium/windsurf/mcp_config.json`. Auto-detection, user-scope deployment, and `apm pack` all support the new target. (#1066)
- Slash commands installed from APM packages now surface argument hints in Claude Code -- `apm install` automatically maps prompt `input:` to Claude's `arguments:` front-matter, rewrites `${input:name}` references to `$name`, and auto-generates `argument-hint`. Argument names are validated against an allowlist to prevent YAML injection from third-party packages, and the mapping is reported at install time. (#1039)

### Changed

- **Skills for Copilot, Cursor, OpenCode, and Codex now deploy to `.agents/skills/` by default (skill routing convergence).** The four clients whose documentation lists `.agents/` as a skill discovery path now share a single deployment directory, eliminating up to 4 redundant copies per skill when `--target all` is used. Claude retains its native per-client routing (`.claude/skills/`); Gemini joins the convergence in the entry below. Pass `--legacy-skill-paths` (or set `APM_LEGACY_SKILL_PATHS=1`) to restore the previous per-client layout. (closes #1103)
- **Gemini CLI joins the `.agents/skills/` convergence by default.** Gemini CLI docs list `.agents/skills/` as the preferred alias over `.gemini/skills/`, so Gemini now shares the converged deployment directory with Copilot, Cursor, OpenCode, and Codex (5 clients total). Claude remains on its native `.claude/skills/` routing. (#737)
- **Auto-migration**: `apm install` now migrates legacy per-client skill deployments (`.github/skills/`, `.cursor/skills/`, `.opencode/skills/`, `.gemini/skills/`) recorded in `apm.lock.yaml` to `.agents/skills/`. Foreign / hand-authored skills outside the lockfile are left untouched. Use `--legacy-skill-paths` to opt out. (#737)
- **Renamed `NOTICE.md` -> `NOTICE`** to follow the Apache / CNCF convention used by upstream third-party-attribution files (e.g. `kubernetes-sigs/kro`, `kubernetes-sigs/headlamp`). The generator (`scripts/generate-notice.py`), `make notice` target, and `NOTICE Drift Check` workflow now operate on the extension-less path. (#1073)
- **NOTICE: added "Submitted on behalf of a third-party" section** crediting five contributors whose pull requests landed before the `microsoft-github-policy-service` CLA bot recorded a signature on file -- in keeping with the section-7 wording adopted by CNCF NOTICE files. Driven by a new `_third_party_submissions` block in `scripts/notice-metadata.yaml`. (#1073)
- **BREAKING: `apm pack` now produces a Claude Code plugin directory by default — zero extra flags, schema-validated `plugin.json`, convention dirs auto-discovered.** The legacy APM bundle layout is preserved under `--format apm`. Migration: CI workflows and scripts that consume the legacy bundle must add `--format apm` (the [`microsoft/apm-action`](https://github.com/microsoft/apm-action) wrapper has been updated accordingly). (#1061)
- **Plugin manifest schema conformance.** The synthesized/written `plugin.json` no longer emits `agents`/`skills`/`commands`/`instructions` keys pointing at the convention directories — these are auto-discovered by Claude Code, and per the [official schema](https://json.schemastore.org/claude-code-plugin.json) those array entries must be `./*.md` paths to *additional* files. The convention dirs themselves are still copied to disk. When stripping such keys from an authored `plugin.json`, `apm pack` now emits a warning so authors can clean up their source. (#1061)

### Deprecated

- **`--target agents` is deprecated** -- it maps to `copilot` (`.github/`), not `.agents/`. Use `--target copilot` or `--target agent-skills`. Removal in v1.0. (closes #627, #640, #664)

### Removed

- **BREAKING: dropped support for `.collection.yml` / `.collection.yaml` virtual packages.** Dependencies whose paths end in `.collection.yml` or `.collection.yaml` now raise a `ValueError` at parse time with a migration message. Convert any such entry to a regular `apm.yml` with a `dependencies:` section under the same subdirectory, then reference the directory itself as a subdirectory virtual package (no extension). The internal `VirtualPackageType.COLLECTION` enum value, the `download_collection_package` codepath, the `is_virtual_collection()` reference helper, and the `META_PACKAGE` package-type label have been removed -- none were persisted to the lockfile, so existing locks are unaffected. (#1097, closes #1094) Thanks @edenfunf for the original PR.

### Fixed

- **`apm install` now anchors transitive `local_path` deps on the declaring package's directory (npm/pip/cargo parity).** Sibling/monorepo layouts (e.g. `../base` declared inside `packages/specialized/apm.yml`) now resolve relative to the declaring package, not the consumer's project root. **Security tightening:** remote-cloned packages can no longer declare `local_path` deps -- both relative and absolute paths are rejected at `ERROR` severity at resolve time. (#1111, closes #857) Thanks @JahanzaibTayyab.
- `apm compile` no longer silently drops instructions without an `applyTo` pattern from generated `AGENTS.md` and `CLAUDE.md`; globals now render under a `## Global Instructions` section, matching the optimizer's existing `(global)` placement (#1088, closes #1072)
- `apm install` no longer masks local-bundle install failures with `UnboundLocalError`. (#1108)
- **`apm install <pkg>@<marketplace>` no longer fails for all marketplace packages.** The install resolver now accepts both legacy and current marketplace key names: `repository`/`repo` for github sources, `url`/`repo` for git-subdir sources, and `type`/`source` as the source-type discriminator. A scheme guard rejects full URLs passed through the `url` fallback. (#1106, closes #1105)
- **`apm install --update` no longer fails for GHES/generic hosts** that rely on git credential helpers (e.g., `git-credential-manager`) for authentication. The preflight auth probe was blocking credential helpers by setting `GIT_CONFIG_GLOBAL=/dev/null`; it now uses the same relaxed environment as the clone fallback path for non-GitHub/non-ADO hosts. (#1082)
- `apm compile --dry-run -t copilot` now faithfully simulates the hand-authored file guard: a `.github/copilot-instructions.md` lacking the APM marker is reported as `skipped=1` (matching the real run) instead of as `generated=1`. Previously dry-run would claim a write that a real run would refuse, giving CI preview gates a false signal. (#1048)
- `apm compile -t claude,copilot` (and any multi-target list including `copilot`) now correctly generates `.github/copilot-instructions.md`; previously it was silently skipped on the multi-target code path. (#1048)
- `apm compile` no longer overwrites a hand-authored `.github/copilot-instructions.md`; if the file lacks the APM-generated marker, regeneration is skipped with a warning that names the literal marker line (`<!-- Generated by APM CLI from .apm/ primitives -->`) so users can self-serve recovery. **Migration:** to adopt APM management of an existing file, either delete or rename it and re-run `apm compile`, or prepend the marker line to the top of the file and re-run `apm compile`. (#1048)
- Generated footer in `.github/copilot-instructions.md` now reads `apm compile` (was `specify apm compile`). (#1048)
- `apm compile --targets claude` no longer lists `@apm_modules/{owner}/{package}/CLAUDE.md` dependencies for packages that don't have a `CLAUDE.md` file on disk (#1047)
- **`apm prune` no longer flags directories it put there itself** -- skills installed from a subdirectory path (e.g., `owner/repo/.apm/skills/skill-name`) no longer cause the parent `owner/repo/` clone to appear as an orphan. Fixes spurious removal prompts in multi-skill and monorepo-style setups. The same fix applies to `apm deps list` and `apm compile`. A genuinely orphaned `owner/repo` package is still flagged even when a sibling subdirectory dep shares the same `owner/repo` root. No changes to `apm.yml` or the lockfile are required to benefit from this fix. (#1050)

## [0.11.0] - 2026-04-29

### Added

- **`apm pack` is now the single command for marketplace builds** -- with an `apm.yml` `marketplace:` block it emits `.claude-plugin/marketplace.json` directly. New flags: `--offline`, `--include-prerelease`, `--marketplace-output PATH`. (#722)
- **Author marketplaces from `apm.yml`.** New top-level `marketplace:` block, `apm marketplace migrate` to consolidate legacy `marketplace.yml`, `apm init --marketplace` to scaffold, and first-class `source: ./local/path` package sources. (#1038)
- **Codex CLI installs are now project-scoped.** MCP config lands in `.codex/config.toml` for project installs (no more polluting the user-global file); user-scope primitive deployment is also supported. (#803)
- **Cross-org private packages in `shared/apm.md`** via a new `apps:` array (one GitHub App per credential group, matrix fan-out). The single-app shorthand (`app-id` / `private-key` / `owner` / `repositories`) is preserved. (#982)

### Changed

- **`apm marketplace add` preserves the upstream alias** -- now defaults to the `name` declared in the fetched `marketplace.json` instead of the repo name, so install instructions in third-party READMEs work verbatim. (#1032)
- **`--policy` / `--policy-source` help is unified** across CLI and docs, with lockstep tests pinning all surfaces against drift. (#1000, closes #998 #994)
- **BREAKING: invalid `target:` values now fail loud.** CSV strings (`target: a,b,c`), unknown tokens, empty values, and `all` mixed with other targets used to silently no-op `apm install` / `apm compile`; they now raise a parse error. Omitting `target:` still auto-detects. (#820)
- Rename `DownloadStrategyManager` -> `DownloadDelegate` and fix double-checked-locking bug in marketplace registry `_load()`. (#918)

### Removed

- **BREAKING: `apm marketplace build` removed** -- `apm pack` is the replacement; the old verb exits 2 with a migration hint. The `marketplace_authoring` experimental flag is also gone (authoring is GA). (#722)

### Deprecated

- Standalone `marketplace.yml` -- still loaded with a deprecation warning, removal slated for v0.13. (#1038)

### Fixed

- **`apm install` works with your existing credential chain (SSO, EMU, GHES tokens).** Validation now uses the same credentials as the actual clone (PAT header-injected, then git credential helper, then SSH for explicit `#ref` pins) -- enterprise users whose env-var PAT has narrower SSO/EMU access than their `gh auth setup-git` / OS keychain are no longer false-rejected by the installer's API probe. Validation logic is now a separate module (`github_downloader_validation.py`), laying groundwork for future credential-provider extensibility. (#941)
- **`shared/apm.md` single-credential-group runs no longer fail validation** with a spurious `missing APM bundles: apm-default` -- a normalisation step recreates the per-group subdir layout that `actions/download-artifact@v5+` flattens away. (#1051)
- **`apm pack` works against GitHub Enterprise and other Git hosts** -- honors `GITHUB_HOST` for GHES auth and accepts GitHub / GHES / GitLab / Bitbucket / ADO / SSH URL forms. (#1008)
- **ADO Entra ID auth no longer silently fails.** Bearer tokens from `az account get-access-token` are plumbed through, errors are typed + actionable (4-case diagnostic), and `apm install --update` pre-flights auth before touching files. (#1015)
- `apm marketplace add` now uses the `name` field from the fetched `marketplace.json` as the default local alias, falling back to the repo name only when the manifest omits it or declares an invalid value. This restores parity with Claude Code install instructions (e.g. `addyosmani/agent-skills` registers as `addy-agent-skills` as that repo's README documents). Existing marketplace entries are unaffected; use `--name` to override explicitly. (#1032)
- `GEMINI.md` is now only created when explicitly targeted. (#1019)
- Windows-friendly: auto-discovery CLI output uses POSIX paths so `apm install` / `apm compile` output is readable on Windows. (#1018)
- Generated-file footer no longer prints stray `specify` before `apm compile`. (#996)
- CodeQL `clear-text-storage` false-positive resolved (variable rename). (#1002)

## [0.10.0] - 2026-04-27

### Added

- **Microsoft 365 Copilot Cowork** target works end-to-end: `apm install --target cowork --global` deploys skills to OneDrive (behind `apm experimental enable cowork`). (#926)
- **[Experimental] `apm marketplace` authoring CLI**: maintainers can scaffold, build, validate, and publish Anthropic-compliant marketplaces from the CLI (`init` -> `package add` -> `build` -> `publish`). (#790)
- README "Coming from `npx skills add`?" 30-second migration table for users arriving from the agentskills.io ecosystem. (#980)
- `NullCommandLogger` class (`src/apm_cli/core/null_logger.py`) -- null-object pattern for logger injection, eliminating 32 conditional logger forks in `MCPIntegrator`. (#918)
- Thread-safety infrastructure: `_get_console()` double-checked locking singleton, marketplace registry cache `threading.Lock`. (#918)
- 40 characterisation tests for `MCPIntegrator` methods (`install()`, `remove_stale()`, `collect_transitive()`). (#918)
- `_build_children_index()` helper in uninstall engine for O(n) reverse-dependency lookups. (#918)
- Performance benchmarks and scaling guards for complexity audit refactors (`tests/benchmarks/test_audit_benchmarks.py`, `test_scaling_guards.py`): 16 benchmark tests covering dependency parsing, children index, primitive discovery, registry cache, console singleton, and NullCommandLogger; 3 scaling-ratio guards run in the default test suite to catch O(n^2) regressions. (#918)
- Expanded performance benchmark suite with P0 and P1 hot-path coverage: `compute_package_hash`, `get_all_dependencies`, `is_semantically_equivalent`, `flatten_dependencies`, `to_yaml`, `compute_deployed_hashes`, `optimize_instruction_placement`, `_rewrite_markdown_links`, `partition_managed_files`, LockFile round-trip, and `register_contexts` -- 52 new benchmark tests plus 2 additional scaling guards. (#918)
- Iteration 2 benchmark coverage: `_match_double_star` recursive glob matcher, `ContentScanner.scan_text` and `strip_dangerous` security scanning, `build_dependency_tree` BFS resolver, `_parse_ls_remote_output` and `_sort_remote_refs` git ref parsing, `analyze_directory_structure` compiler analysis, and `collect_transitive` MCP integration -- 77 new benchmark tests plus 1 additional scaling guard. (#918)

### Changed

- [Experimental] `apm marketplace plugin` renamed to `apm marketplace package` (npm/pip/cargo familiarity); `--help` grouped into Consumer / Authoring sections. (#722)
- `MCPIntegrator` logger handling: methods default to `NullCommandLogger` instead of `None`, removing 32 `if logger:` / `elif logger:` conditional forks (net -91 production lines). (#918)
- Install pipeline lockfile reads reduced from 2x to 1x by caching early lockfile on `InstallContext`. (#918)
- `APMPackage.from_apm_yml()`: deduplicated dependency parsing via `_parse_dependency_dict()` classmethod. (#918)
- Uninstall engine BFS orphan detection: O(n^2) full-scan replaced with O(n) reverse-dep index. (#918)
- Primitive discovery scanning: 9+ `glob.glob()` calls replaced with single `os.walk` + `fnmatch` pass. (#918)
- MCP registry config reads: O(servers x runtimes) reduced to O(runtimes) via function-scoped cache. (#918)
- `_get_console()`: returns thread-safe singleton instead of creating new `Console()` per call. (#918)
- Marketplace registry cache: `_load()`, `_save()`, `_invalidate_cache()` protected with `threading.Lock`. (#918)
- Complexity audit -- decomposed god functions in `reference.py`, `audit.py`, `deps/cli.py`, and `script_runner.py` into focused single-responsibility helpers (largest: `audit()` 290 lines split into thin dispatcher + `_audit_ci_gate` + `_audit_content_scan` with shared `_AuditConfig` dataclass). (#918)
- Decomposed `github_downloader.py` into three modules: `git_remote_ops.py` (ref parsing), `download_strategies.py` (backend downloads), and a slimmed orchestrator. (#918)
- Decomposed `install()` god function (555 lines) into focused helpers with `InstallContext` parameter bundle. (#918)

### Fixed

- Docs site auto-deploys again after bot-cut releases (now triggered on tag push). (#981)
- Bare `except:` clauses in `formatters.py` (5) and `script_formatters.py` (2) now catch `Exception` instead of `BaseException`, allowing `KeyboardInterrupt` and `SystemExit` to propagate correctly. (#918)
- Silent auth fallback in `discovery.py:_get_token_for_host()` now logs `logger.debug()` when the token manager fails, making credential resolution failures visible with `--verbose`. (#918)
- Silent `except Exception: pass` handlers in `agents_compiler.py` (3) now emit `_logger.debug()` traces for config loading and constitution injection failures. (#918)
- Double `iterdir()` walk in `script_runner.py:_resolve_prompt_file()` collapsed to a single pass. (#918)

### Documentation

- Clarify `NullCommandLogger` partial interface and visible-output semantics in docstring. (#918)

### Maintainer tooling

- `pr-description-skill` ships an evals suite so PR-description quality regressions are caught in CI without an LLM API key. (#985)
- `pr-description-skill` mermaid guidance hardened with `assets/mermaid-conventions.md` (diagram-type-by-intent + GitHub-renderer gotchas `mmdc` misses). (#984)
- Cowork tests mock `sys.platform` so the macOS auto-detection paths don't false-fail on Windows CI. (#989)

## [0.9.4] - 2026-04-27

### Added

- **Day-0 install parity with `npx skills add`**: every public repo that installs cleanly with `npx skills add owner/repo` now installs with `apm install owner/repo`. APM recognises bare `skills/<name>/SKILL.md` (vercel-labs/agent-skills, xixu-me/skills, larksuite/cli, the agentskills.io ecosystem) as a first-class shape (`SKILL_BUNDLE`); `apm.yml` is optional. `--skill <NAME>` (repeatable) selects a subset and **persists** it to `apm.yml` + `apm.lock.yaml`, so bare `apm install` is reproducible across machines. `--skill '*'` resets; `apm audit --ci` flags drift. (#974)
- `curl | sh` install works in air-gapped, GHE, and internal-mirror setups: `install.sh` now reads `APM_INSTALL_DIR`, `GITHUB_URL`, `APM_REPO`, and `VERSION` (or `@vX.Y.Z` arg) -- pinning a version skips the GitHub API entirely, so corporate runners without api.github.com egress can bootstrap APM. (#660)

### Changed

- `apm marketplace` authoring commands (init, build, check, outdated, doctor, publish, package) ring-fenced behind `apm experimental enable marketplace-authoring` feature flag (default: disabled) (#790)
### Fixed

- `apm install` no longer fails behind corporate TLS-intercepting proxies: validation now honours `REQUESTS_CA_BUNDLE` instead of misreporting CA failures as auth errors. (#911)
- `apm experimental <subcommand> --help` now shows the subcommand's own help; CLI help text and short flags aligned from the 2026-04-24 audit. (#910, #903)

### Maintainer tooling

- Untriaged issues are auto-triaged by the `apm-triage-panel` skill on a daily oldest-first sweep (max 10/run) plus `status/needs-triage` for on-demand. Decisions are agentic proposals; any maintainer label edit wins. (#954)
- Docs site auto-deploys again after bot-cut releases (workaround for GitHub's `GITHUB_TOKEN`-suppressed `release: published` event). Silently broken since v0.9.3. (#953)
- Triage-panel themed issues now reach the PGS project board (dispatches `project-sync` directly; same `GITHUB_TOKEN` event-suppression class as #953). (#971)
- Issue templates use canonical APM labels; `python-architect` agent documents the mermaid `classDiagram :::cssClass` GitHub-render trap. (#958, #970)

## [0.9.3] - 2026-04-26

### Added

- **Gemini CLI** as a supported APM target (`--target gemini`): auto-detects `.gemini/`, writes MCP config to `.gemini/settings.json`, and adds `apm runtime setup|remove gemini`. (#917)
- Experimental `cowork` target for Microsoft 365 Copilot Cowork custom-skill deployment via OneDrive (`apm experimental enable cowork`; `apm install --target cowork --global`; persisted via `apm config set cowork-skills-dir`). (#913)
- `apm experimental` command group (`list` / `enable` / `disable` / `reset`) lets you opt into new behaviour before it graduates to default. Ships with the `verbose-version` flag. (#849)
- `apm audit --ci` now verifies hash integrity of locally deployed `.apm/` files so hand-edits and config drift fail CI instead of slipping through. (#887)
- `includes:` manifest field (`auto` or list) gives you explicit control over which local `.apm/` files are deployed; pair with `policy.manifest.require_explicit_includes` to block silent expansion. Audit raises an `includes-consent` advisory while you migrate. (#887)
- `apm-triage-panel` skill: three-persona issue triage panel (DevX UX, Supply Chain Security, APM CEO) emitting a single labelled-decision comment, mirroring `apm-review-panel`. (#915)
- `apm-primitives-architect` persona for designing and critiquing `.apm/` skill bundles, plus a `pr-description-skill` that enforces self-sufficient PR bodies (TL;DR/Problem/Approach/Implementation/Diagrams/Trade-offs/Benefits/Validation/How-to-test) with anchored citations and validated mermaid. (#882, #884)
- New docs guide [`dev-only-primitives`](https://danielmeppiel.github.io/awd-cli/guides/dev-only-primitives/): canonical pattern for maintainer-only primitives that must not ride into your published bundle. (#949)
- Maintainer tooling: PGS project-board sync workflow keeps issues in lockstep with labels/milestones; `APM Self-Check` CI job dogfoods `apm audit --ci` and regeneration-drift gates. (#919, #885)

### Changed

- HYBRID-skill review pipeline: `apm-review-panel` now produces a single CEO-synthesized verdict per run (no per-persona spam), with Hybrid E auth-expert routing and `python-architect`'s mandatory three-artifact contract. PRs get one high-signal comment. (#882, #905, #907, #908)
- Faster primitive discovery on large repos: `compilation.exclude` patterns now prune traversal at the directory level instead of post-filtering. (#870)
- `apm-action` bumped to `v1.4.2` (used by `shared/apm.md` workflows): fixes restore-mode workspace pollution that was overwriting your tracked `apm.lock.yaml` / `apm.yml` / `apm_modules`. (#904)
- CI release-binary smoke (Linux x64/arm64, Windows) only runs on tag/schedule/dispatch instead of every push, cutting ~15 redundant codex downloads/day; release-time gating unchanged. (#878)
- Branch-protection docs: clarify the required check-run name is `gate` (not the workflow display string `Merge Gate / gate`). (#874)

### Fixed

- HYBRID packages (apm.yml + SKILL.md, no `.apm/`) and CLAUDE_SKILL packages with sibling `agents/`/`assets/`/`scripts/` dirs now install correctly via the skill-bundle path; previously `apm install` rejected them silently and looked like a hang. Direct-dependency integration failures now print `[x]` and exit 1 instead of failing silently. (#946)
- `apm update` no longer breaks on Debian trixie arm64, Fedora 43, and similar distros where the bundled PyInstaller `LD_LIBRARY_PATH` was leaking into system `curl`/`tar` and triggering `libssl.so.3: version 'OPENSSL_3.2.0' not found`. Closes #894 (#899)
- `apm install` at user scope no longer recursive-globs your entire home directory: scan is scoped to `~/.apm/`. Fixes #830 (#850)
- `apm audit --ci` now also catches drift / missing / tampered files for locally-authored `.apm/` content (not just installed packages); `apm pack` strips local-content fields so they can't leak into bundled lockfiles. (#887)
- `apm install` for ADO orgs that disable PAT creation: error messages on generic git hosts now surface the custom port too. Custom transport types in MCP-server config are validated up front (defaulting to `http` when missing) instead of writing garbage. Closes #791 (#812)
- Windows: `apm install` no longer false-positives `PathTraversalError` on policy cache dirs that don't yet exist (8.3 short-name resolution mismatch). (#895)
- macOS: long inline policy YAML strings (>1023 bytes) no longer crash with `OSError [Errno 63] File name too long`; they fall back to string-mode parsing. Closes #848 (#860)
- Merge queue: `gate` check now reports inside the queue (added `merge_group` trigger), unblocking PRs that were stuck on "Expected -- Waiting for status to be reported". (#921)
- `apm-review-panel` workflow only runs on PRs labelled `panel-review`, eliminating spurious panel runs on every PR. (#948)

### Removed

- Deleted dead `ci-integration-pr-stub.yml` workflow stubs left over from the pre-merge-gate model. No user impact; reduces CI noise. (#875)

## [0.9.2] - 2026-04-23

### Added

- `apm install` supports Azure DevOps AAD bearer-token auth via `az account get-access-token`, with PAT-first fallback for orgs that disable PAT creation. Closes #852 (#856)
- New `enterprise/governance-guide.md`: flagship governance reference for CISO / VPE / Platform Tech Lead audiences; trims duplication across `governance.md`, `apm-policy.md`, `integrations/github-rulesets.md`; adds `templates/apm-policy-starter.yml`. (#851)
- Enterprise docs IA refactor: hub page + merged team guides, deduped governance content. (#858)
- Landing page rewritten around the three-pillar spine. (#855)
- First-package tutorial rewritten end-to-end; fixes `.apm/` anatomy hallucinations. (#866)
- `apm install --ssh` / `--https` flags and `APM_GIT_PROTOCOL=ssh|https` env to pick the initial transport for shorthand dependencies (#778)
- `apm install --allow-protocol-fallback` flag and `APM_ALLOW_PROTOCOL_FALLBACK=1` env as the migration escape hatch for cross-protocol fallback (#778)
- Add APM Review Panel skill (`.github/skills/apm-review-panel/`) and four new specialist personas (`devx-ux-expert`, `supply-chain-security-expert`, `apm-ceo`, `oss-growth-hacker`) with auto-activating per-persona skills. Routes specialist findings through an APM CEO arbiter for strategic / breaking-change calls, with the OSS growth hacker side-channeling adoption insights via `WIP/growth-strategy.md`. Instrumentation per Handbook Ch. 9 (`The Instrumented Codebase`); PROSE-compliant (thin SKILL.md routers, persona detail lazy-loaded via markdown links, explicit boundaries per persona).
- `apm view plugin@marketplace` displays marketplace plugin metadata (name, version, source, description) (#514)
- `apm outdated` checks marketplace plugin refs and shows a "Source" column distinguishing marketplace vs git updates (#514)
- `apm marketplace validate` command with schema validation and duplicate name detection (#514)
- Ref immutability advisory: caches plugin-to-ref pins and warns when a previously pinned plugin's ref changes (#514)
- Multi-marketplace shadow detection: warns when the same plugin name appears in multiple registered marketplaces (#514)

### Changed

- gh-aw workflows now use `imports:` for shared APM context instead of the deprecated `dependencies:` field. (#864)
- CI: `merge-gate.yml` orchestrator turns dropped `pull_request` webhook deliveries into clear red checks instead of stuck `Expected -- Waiting for status to be reported`. (#865)
- CI: `Merge Gate / gate` aggregates all PR-time required checks (`Build & Test (Linux)` + 4 stubs) into a single verdict; branch protection requires only this one check, decoupling the ruleset from CI workflow topology (Tide / bors pattern). (#867, #868)
- CI: `merge-gate.yml` simplified to a single `pull_request` trigger with `workflow_dispatch` for manual recovery; the dual-trigger redundancy attempt was poisoning the branch-protection rollup with `CANCELLED` check-runs. (#868)

### Fixed

- `apm install` surfaces the custom port in clone / `ls-remote` error messages for generic git hosts. (#804)

## [0.9.1] - 2026-04-22

### Added

- `apm install` enforces org `apm-policy.yml` at install time (deps deny/allow/require, MCP deny/transport/trust-transitive, `compilation.target.allow`, `extends:` chains, `policy.fetch_failure` knob, `policy.hash` pin); `--no-policy` / `APM_POLICY_DISABLE=1` escape hatch; `--dry-run` previews verdicts; failed package installs roll back `apm.yml`. New `apm policy status` diagnostic (table / `--json`, exit-0 by default, `--check` for CI). `apm audit --ci` auto-discovers org policy. **Migration**: orgs publishing `enforcement: block` may see installs that previously succeeded now fail -- preview with `apm install --dry-run`. Closes #827, #829, #831, #834 (#832)
- `pr-review-panel` gh-aw workflow: runs the `apm-review-panel` skill on PRs labelled `panel-review` and posts a synthesized verdict (#824)

### Changed

- Docs site publishes only on stable APM releases, not on every push to `main`. Closes #641 (#822)
- Dogfood APM: authored skills, agents, and instructions live in `.apm/`; `.github/{skills,agents,instructions}/` are regenerated by `apm install --target copilot` and committed (#823)

### Fixed

- `pr-review-panel` workflow now runs on PRs from forks: switched to `pull_request_target` with label-only triggering and a workflow-dispatch path (#826, #836, #837)
- Lowercase the host axis of the `_fallback_port_warned` dedup key so deps that differ only in hostname casing collapse to one cross-protocol fallback warning, matching the `AuthResolver._cache` convention (RFC 4343). Closes #800 (#815)

## [0.9.0] - 2026-04-21

### Changed (BREAKING)

- Strict-by-default git transport selection: explicit `ssh://`/`https://` URLs no longer silently cross-fall back; shorthand defaults to HTTPS (consults `url.<base>.insteadOf`). Opt back into the legacy chain with `--allow-protocol-fallback` or `APM_ALLOW_PROTOCOL_FALLBACK=1`. Adds `--ssh` / `--https` / `APM_GIT_PROTOCOL` for explicit shorthand selection. Closes #328 (#778)
- MCP entry validation hardened: names must match `^[a-zA-Z0-9@_][a-zA-Z0-9._@/:=-]{0,127}$`, URLs limited to `http`/`https`, headers reject CR/LF, stdio commands reject `..`. Error messages now include a valid positive example. (#807)
- Stdio MCP entries with whitespace in `command` and no `args` are rejected at parse time with a fix-it error pointing at the canonical `command: <binary>, args: [...]` shape. Closes #806 (#809)

### Added

- `apm install --mcp NAME` (and `apm mcp install` alias) for declaratively adding MCP servers to `apm.yml`, with `--transport` / `--url` / `--env` / `--header` / `--mcp-version` / `--registry` flags and stdio passthrough. TTY prompts on replace, `--force` required in CI. Includes `--registry URL` and `MCP_REGISTRY_URL` env for custom (enterprise) MCP registries. Closes #807 (#810)
- HTTP dependency support via `--allow-insecure` + `allow_insecure: true` dual opt-in; `--allow-insecure-host` for transitive HTTP from new hosts; credential-helper suppression on HTTP attempts to prevent token leakage; new `apm deps list --insecure` view with `Origin` column. Threat model in `enterprise/security.md`. Thanks @arika0093! (#700)
- Multi-target support: `apm.yml` `target` accepts a list (`[claude, copilot]`) and CLI `--target` accepts comma-separated values; only specified targets are compiled/installed/packed. Single-string form remains backward compatible. (#628)
- Marketplace UX overhaul: `apm view plugin@marketplace`, `apm outdated` Source column, `apm marketplace validate`, ref-immutability advisory, multi-marketplace shadow detection. (#514)
- New **MCP Servers** guide (`docs/guides/mcp-servers.md`) consolidating stdio / registry / remote shapes, flag reference, validation rules, and the conflict matrix in one page; assorted MCP doc drift fixes (#808)
- Build-time `update_policy` module so package-manager distributions (conda-forge, brew, pixi) can disable `apm update` and show custom guidance. Thanks @joostsijm! (#675)
- APM Review Panel skill (`.github/skills/apm-review-panel/`) plus four specialist personas (devx-ux, supply-chain-security, apm-ceo, oss-growth-hacker) routing through an APM CEO arbiter (#777)

### Fixed

- Preserve custom git ports across protocols: non-default ports on `ssh://` / `https://` dependency URLs (e.g. Bitbucket Datacenter SSH 7999, self-hosted GitLab HTTPS 8443) are captured as `DependencyReference.port` and reused on HTTPS fallback. Closes #661, #731 (#665)
- Token resolution now discriminates by port, fixing credential collisions across multiple self-hosted Git instances on the same host. Thanks @edenfunf! Closes #785 (#788)
- Detect port-like first path segment in SCP shorthand (`git@host:7999/path`) and raise an actionable error suggesting the `ssh://` form. Closes #784 (#787)
- `--allow-protocol-fallback` emits a one-shot `[!]` warning when a dependency's custom port is about to be tried across both SSH and HTTPS, recommending pinning the scheme. Closes #786 (#789)
- `apm install --global` now installs MCP servers to global-capable runtimes (Copilot CLI, Codex CLI) instead of skipping all MCP at user scope; `--trust-transitive-mcp` no longer ignored under `--global`. Lockfile-path behavior at `--global` tracked in #794 (#638)
- `apm install` no longer silently drops skills/agents/commands when a Claude Code plugin also ships `hooks/*.json`: detection cascade now classifies plugin-shaped packages as `MARKETPLACE_PLUGIN` first; emits a `[!]` warning when a hook-only classification disagrees with package contents (#780)
- `apm mcp search` / `list` / `show` now honour `MCP_REGISTRY_URL` (previously hardcoded to the public registry), print a `Registry: <url>` diagnostic when set, and surface the configured URL in network-error messages (#813)
- VS Code adapter defaults to `http` transport when `transport_type` is missing from remote registry data, matching Copilot adapter behavior (#654)
- `apm init` no longer prompts to overwrite three times on Windows CP950 terminals. Closes #602 (#647)
- `apm init` Next Steps panel surfaces install/marketplace/plugin workflows instead of the dead-end `apm run start` reference. Closes #603 (#649)

### Security

- `MCP_REGISTRY_URL` validated at startup (schemeless / unsupported schemes rejected; `http://` rejected by default, opt in via `MCP_REGISTRY_ALLOW_HTTP=1`); APM fails closed when a custom registry is unreachable during install pre-flight, instead of silently approving every MCP dep. Default registry keeps assume-valid for transient errors. (#814)
- `apm install --mcp` defense-in-depth: rejects embedded `..` in dep names with a valid positive example, redacts URL credentials in diagnostic output (`https://user:token@host/` -> `https://host/`), warns on `--registry` / `MCP_REGISTRY_URL` pointing at loopback / link-local / RFC1918 / cloud-metadata hosts (including decimal-encoded loopback). (#810)
- `SimpleRegistryClient` applies a `(connect=10s, read=30s)` timeout on every registry HTTP call, removing the unbounded-hang failure mode. Tunable via `MCP_REGISTRY_CONNECT_TIMEOUT` / `MCP_REGISTRY_READ_TIMEOUT`. (#810)

## [0.8.12] - 2026-04-19

### Added

- `apm install` now automatically discovers and deploys local `.apm/` primitives (skills, instructions, agents, prompts, hooks, commands) to target directories, with local content taking priority over dependencies on collision (#626, #644)
- Deploy primitives from the project root's own `.apm/` directory alongside declared dependencies, so single-package projects no longer need a sub-package stub to install their own content (#715)
- Add `temp-dir` configuration key (`apm config set temp-dir PATH`) to override the system temporary directory, resolving `[WinError 5] Access is denied` in corporate Windows environments (#629)

### Changed

- Refactor `apm install` into a modular engine package (`apm_cli/install/`) with discrete phases and apply Strategy / Template Method / Application Service patterns; public CLI behaviour and the `#762` cleanup chokepoint unchanged (#764)
- `apm marketplace browse/search/add/update` now route through the registry proxy when `PROXY_REGISTRY_URL` is set; `PROXY_REGISTRY_ONLY=1` blocks direct GitHub API calls (#506, #617)
- CI: adopt GitHub Merge Queue with tiered CI (Tier 1 unit + binary on `pull_request` + `merge_group`; Tier 2 integration + release-validation on `merge_group` only) plus an inert `pull_request_target` stub workflow for required-check satisfaction. CODEOWNERS now requires Lead Maintainer review for any change to `.github/workflows/**` (#770, #771)
- Bump `pytest` from 8.4.2 to 9.0.3 (#698)
- Bump `dompurify` from 3.3.2 to 3.4.0 in `/docs` (#730)
- Bump `lodash-es` and `langium` in `/docs` (#761)
- Add `.editorconfig` to standardize charset, line endings, indentation, and trailing whitespace across contributions (#671)
- Add `@sergio-sisternes-epam` as maintainer (#623)
- Close install/uninstall/update CLI integration coverage gaps surfaced by the `#764` review (#767)
- Add 55 unit tests for `commands/deps/_utils.py` and `commands/view.py` to address Test Improver backlog items #4 and #5 (#682)

### Fixed

- Harden `apm install` stale-file cleanup to prevent unsafe lockfile deletions, preserve user-edited files via per-file SHA-256 provenance, and improve cleanup reporting during install and `--dry-run` (#666, #750, #762)
- Local `.apm/` stale-cleanup now uses pre-install content hashes for provenance verification. Previously the lockfile was re-read after regeneration, which always yielded empty hashes, causing the user-edit safety gate to be silently skipped for project-local files (#764)
- Fix `apm install --target claude` not creating `.claude/` when the directory does not already exist (`auto_create=False` targets now get their root directory created when explicitly requested) (#763)
- Fix content hash mismatch on re-install when `.git/` is absent from installed packages by falling back to content-hash verification before re-downloading (#763)
- Make `apm install` idempotent for hook entries: upsert by `_apm_source` ownership marker instead of unconditionally appending, so re-running install no longer duplicates per-event hook commands (#709)
- Rewrite Windows backslash paths in hook commands' `windows` key during integration; previously only Unix-style `./` references were rewritten, leaving `windows` script paths unresolved at runtime (#609)
- Add explicit `encoding="utf-8"` to `.prompt.md` `open()` calls in `script_runner` to prevent `UnicodeDecodeError` on Windows non-UTF-8 locales (CP950/CP936/CP932) (#607)
- Validate the `project_name` argument to `apm init` and reject `/` and `\` to prevent confusing `[WinError 3]` and silent path-traversal behaviour (#724)
- Use `yaml.safe_dump` when generating `apm.yml` for virtual-file and collection packages, so `description` values containing `:` no longer break `apm install` with a YAML parse error (#707)
- `_count_package_files` in `apm deps list` now reads the canonical `.apm/context/` (singular) directory; previously it scanned `.apm/contexts/` and always reported `0 context files` per package (#748)
- `apm pack --format plugin` no longer emits duplicated `skills/skills/` nesting for bare-skill dependencies referenced through virtual paths like `skills/<name>` (#738)
- Provide an ADO-specific authentication error message for `dev.azure.com` remotes so users get actionable guidance instead of a generic GitHub-flavored hint (#742)
- Fix `apm compile --target codex` (and `opencode`, `minimal`) being a silent no-op; `AgentsCompiler.compile()` now routes these through the AGENTS.md compiler instead of returning an empty success result that left stale `AGENTS.md` files (#766)
- Support `codeload.github.com`-style archive URLs in Artifactory archive URL generation, unblocking JFrog Artifactory proxies configured against `codeload.github.com` (#712)
- `_parse_artifactory_base_url()` now reads `PROXY_REGISTRY_URL` first (with `ARTIFACTORY_BASE_URL` fallback + `DeprecationWarning`), and the virtual-subdirectory download path checks `dep_ref.is_artifactory()` before falling back to env-var detection, fixing lockfile reinstall failures when proxy config is only on the lockfile entry (#616)
- Fall back to SSH URLs when validating git remotes for generic / self-hosted hosts so `apm install` no longer fails the pre-install validation step against private SSH-only servers (#584)
- Suppress internal config keys (e.g. `default_client`) from `apm config get` output, removing the get/set asymmetry that confused users and was flagged as a Medium security issue (#571)
- Include dependency instructions stored in `.github/instructions/` (not only `.apm/instructions/`) when running `apm compile --target claude` without `--local-only` (#631, #642)
- Fix `apm marketplace add` silently failing for private repos by using credentials when probing `marketplace.json` (#701)
- Harden marketplace plugin normalization to enforce that manifest-declared `agents`/`skills`/`commands`/`hooks` paths resolve inside the plugin root (#760)
- Pin codex setup to `rust-v0.118.0` for security and reproducibility; update config to `wire_api = "responses"` (#663)
- Propagate headers and environment variables through OpenCode MCP adapter with defensive copies to prevent mutation (#622)
- Fix `apm install` hanging indefinitely when corporate firewalls silently drop SSH packets by setting `GIT_SSH_COMMAND` with `ConnectTimeout=30` (#652, #653)
- Stop `test_auto_detect_through_proxy` from making real `api.github.com` calls by passing a mock `auth_resolver`, fixing flaky macOS CI rate-limit failures (#759)
- Fix the Daily Test Improver workflow creating duplicate monthly activity issues; Task 7 now finds and updates the existing month's issue instead of opening a new one each run (#681)

## [0.8.11] - 2026-04-06

### Added

- Artifactory archive entry download for virtual file packages (#525)
- `apm view <package> [field]` command for viewing package metadata and remote refs (#613)
- `apm view <package> versions` field selector lists remote tags and branches via `git ls-remote` (#613)
- `apm outdated` command compares locked dependencies against remote refs (#613)
- `--parallel-checks` (`-j`) option on `apm outdated` for concurrent remote checks (default: 4) (#613)
- Rich progress feedback during `apm outdated` dependency checking (#613)
- `--global` flag on `apm view` for inspecting user-scope packages (#613)

### Changed

- Rename `apm info` to `apm view` for npm convention alignment; `apm info` kept as hidden alias (#613)
- Scope resolution now happens once via `TargetProfile.for_scope()` and `resolve_targets()` -- integrators no longer need scope-aware parameters (#562)
- Unified integration dispatch table in `dispatch.py` -- both install and uninstall import from one source of truth (#562)
- Hook merge logic deduplicated: three copy-pasted JSON-merge methods replaced with `_integrate_merged_hooks()` + config dict (#562)
- `apm outdated` uses SHA comparison for branch-pinned deps instead of reporting them as `unknown` (#613)

### Fixed

- Reject symlinked primitive files in all discovery and resolution paths to prevent symlink-based traversal attacks (#596)
- `apm install -g` now deploys hooks to the scope-resolved target directory instead of hardcoding `.github/hooks/` (#565, #566)
- Hook sync/cleanup derives prefixes dynamically from `KNOWN_TARGETS` instead of hardcoded paths (#565)
- `auto_create=False` targets no longer get directories unconditionally created during install (#576)
- `apm deps update -g` now correctly passes scope, preventing user-scope updates from silently using project-scope paths (#562)
- Subprocess encoding failures on Windows non-UTF-8 consoles (CP950/CP936) -- all subprocess calls now use explicit UTF-8 encoding (#591)
- PowerShell 5.1 compatibility: replace multi-argument `Join-Path` calls with nested two-argument calls (#593)
- `apm marketplace add` now respects `GITHUB_HOST` environment variable for GitHub Enterprise users (#589)
- `compilation.exclude` patterns now filter primitive discovery, preventing excluded files from leaking into compiled output (#477)
- Runtime detection in script runner now uses anchored patterns to prevent false positives when runtime keywords appear in flag values (#563)
- `apm compile` now warns when instructions are missing `applyTo` across all compilation modes (#449)
- Detect remote default branch instead of hardcoding `main` (#574)
- Warn when two packages deploy a native skill with the same name (#545)

## [0.8.10] - 2026-04-03

### Fixed

- Hook integrator now processes the `windows` property in hook JSON files, copying referenced scripts and rewriting paths during install/compile (#311)
- Standardized `--target` choices, replaced Unicode with ASCII for cp1252 compatibility, and documented missing CLI flags (#519)
- `apm install -g` now correctly deploys to user-scope directories, skips unsupported primitives, and cleans up on uninstall -- including multi-level paths like `~/.config/opencode/` (#542)
- `apm deps update` now correctly re-resolves transitive dependencies instead of reusing stale locked SHAs (#548)

### Added

- `apm install` now deploys `.instructions.md` files to `.claude/rules/*.md` for Claude Code, converting `applyTo:` frontmatter to Claude's `paths:` format (#516)

### Changed

- Artifactory virtual file downloads now use the Archive Entry Download API to fetch individual files without downloading the full archive; falls back to full-archive extraction when the entry API is unavailable (#525)

## [0.8.9] - 2026-03-31

### Fixed

- `apm install NAME@MARKETPLACE` now respects `metadata.pluginRoot` from marketplace manifests, fixing resolution of bare-name plugins in marketplaces like `awesome-copilot` (#512)
- Windows unit test assertion tolerates Rich console line-wrapping on long temp paths (#510)
- Release validation scripts match updated `apm deps list` scope output (#510)

## [0.8.8] - 2026-03-31

### Added

- `apm install -g/--global` for user-scope package installation with per-target support matrix and `apm uninstall -g` lifecycle (#452)
- Marketplace integration: `apm install NAME@MARKETPLACE` syntax, `apm marketplace add/list/browse/update/remove`, `apm search` across registered marketplaces (#503)
- Codex as integration target: skills to `.agents/skills/`, agents to `.codex/agents/*.toml`, hooks to `.codex/hooks.json`, `--target codex` on install/compile/pack (#504)
- Lockfile-driven reproducible installs for registry proxies with `content_hash` verification and `RegistryConfig` -- by @chkp-roniz (#401)

### Changed

- `apm deps update` skips download when resolved SHA matches lockfile SHA, making the common "nothing changed" case near-instant (#500)

### Fixed

- `apm install -g ./local-pkg` rejects local path dependencies at user scope with a clear error (#452)
- Orphan documentation pages (`ci-policy-setup`, `policy-reference`) added to sidebar navigation; stale GitHub Rulesets content updated (#505, #507)

## [0.8.7] - 2026-03-30

### Fixed

- `--target opencode` no longer writes prompts/agents to `.github/`; dispatch loop now only fires primitives declared by the selected target (#488, #494)
- `--target cursor` now correctly deploys skills to `.cursor/skills/` instead of `.github/skills/` -- `SkillIntegrator` respects the explicit target list end-to-end (#482, #494)
- Misleading "transitive dep" error message for direct dependency download failures (#478)
- Sparse checkout using global token instead of per-org token from `GITHUB_APM_PAT_<ORG>` (#478)
- Duplicate error count when a dependency fails during both resolution and install phases (#478)
- Windows Defender false-positive (`Trojan:Win32/Bearfoos.B!ml`) mitigation: embed PE version info in Windows binary and disable UPX compression on Windows builds -- by @sergio-sisternes-epam (#490)
- `apm deps update` was a no-op -- rewrote to delegate to the install engine so lockfile, deployed files, and integration state are all refreshed correctly -- by @webmaxru (#493)

### Changed

- Integration dispatch is now data-driven: `KNOWN_TARGETS` defines each target's primitives and directory layout; adding a target requires zero code changes (#494)
- `partition_managed_files()` uses O(1) component-based path routing instead of linear prefix scan (#494)
- Uninstall sync uses pre-partitioned buckets via `partition_bucket_key()` instead of re-scanning the full managed-files set (#494)

### Security

- Bump `pygments` from 2.19.2 to 2.20.0 (#495)

## [0.8.6] - 2026-03-27

### Added

- `apm install --target` flag to force deployment to a specific target (copilot, claude, cursor, opencode, all) (#456)
- Global `apm install --global` / `-g` and `apm uninstall --global` flags for user-scope package installation, backed by `InstallScope`-based scope resolution in `core/scope.py`; deploys primitives to `~/.copilot/`, `~/.claude/`, `~/.cursor/`, `~/.config/opencode/` and tracks metadata under `~/.apm/` (#452)

### Fixed

- Windows antivirus file-lock errors (`WinError 32`) during `apm install` with `file_ops` retry utility (#440)
- Installer fallback to pip in devcontainers, target registry, and lockfile idempotency fixes (#456)
- Reject path traversal sequences in SSH-style Git URLs — by @thakoreh (#458)
- Exclude bundled OpenSSL libs from Linux binary to prevent ABI conflicts (#466)
- Allow spaces in ADO repository names when parsing URLs (#437)
- Gate `.claude/commands/` deployment behind `integrate_claude` flag (#443)
- Sort instruction discovery order for deterministic Build IDs across platforms (#468)
- Share `AuthResolver` across install to prevent duplicate auth popups (#424)

### Changed

- Consolidated path-segment traversal checks into `validate_path_segments()` in `path_security.py` (#458)

## [0.8.5] - 2026-03-24

### Added

- `apm audit --ci` org-level policy engine -- experimental Phase 1 for enterprise governance over agents in the SDLC; GitHub / GitHub Enterprise only (#365)
- `-v` shorthand for `--verbose`, `show_default` on boolean options, `deps clean --dry-run`/`--yes` flags (#303)
- `--verbose` on `apm install` now shows auth source diagnostics for virtual package validation failures (#414)
- Nightly runtime inference tests decoupled from release pipeline via `ci-runtime.yml` (#407)

### Changed

- CI pipeline optimization: merged test+build jobs, macOS as root nodes, native `setup-uv` caching, removed unnecessary `setup-node` steps (#407)
- Encoding instructions enforce ASCII-only source and CLI output with bracket status symbols (#282)

### Fixed

- Windows path hardening: `portable_relpath()` utility, ~23 `relative_to()` call-site migrations, CI lint guard (#411, #422)
- Centralized YAML I/O with UTF-8 encoding via `yaml_io` helpers, preventing Windows cp1252 mojibake, based on prior work by @alopezsanchez (#433, #388)
- SSL certificate verification in PyInstaller binary via `certifi` runtime hook (#429)
- `apm pack --target claude` cross-target path mapping for skills/agents installed under `.github/` (#426)
- `ARTIFACTORY_ONLY` enforcement for virtual package types (files, collections, subdirectories) (#418)
- Local path install: descriptive failure messages and Windows drive-letter path recognition (#431, #435)
- Windows test fixes in config command and agents compiler (#410)
- Removed stale WIP folder from tracking, strengthened `.gitignore` (#420)

## [0.8.4] - 2026-03-22

### Added

- Centralized `AuthResolver` with per-(host, org) token resolution, cached and thread-safe — replaces 4 scattered auth implementations (#394)
- `CommandLogger` and `InstallLogger` base classes for structured CLI output with validation, resolution, and download phases (#394)
- `--verbose` flag on `uninstall`, `pack`, and `unpack` commands (#394)
- Verbose output: dependency tree resolution, auth source/type per download, lockfile SHA, package type, inline per-package diagnostics (#394)
- Parent chain breadcrumb in transitive dependency error messages — "root-pkg > mid-pkg > failing-dep" (#394)
- `DiagnosticCollector.count_for_package()` for inline per-package verbose hints (#394)
- Auth flow diagram and package source behavior matrix in authentication docs (#394)
- Documented `${input:...}` variable support in `headers` and `env` MCP server fields (#349)

### Changed

- All CLI output now uses ASCII symbols (`[+]`, `[x]`, `[!]`) instead of Unicode characters (#394)
- Migrated `_rich_*` calls to `CommandLogger` across install, compile, uninstall, audit, pack, and bundle modules (#394)
- Verbose ref display uses clean `#tag @sha` format instead of nested parentheses (#394)
- Integration tree lines (`└─`) no longer have `[i]` prefix — clean visual hierarchy (#394)
- Global env vars (`GITHUB_APM_PAT`, `GITHUB_TOKEN`, `GH_TOKEN`) apply to all hosts — HTTPS is the security boundary, not host-gating (#394)
- Credential-fill timeout increased from 5s to 60s (configurable via `APM_GIT_CREDENTIAL_TIMEOUT`, max 180s) — fixes Windows credential picker timeouts (#394)

### Fixed

- Bundle lockfile includes non-target `deployed_files` causing `apm unpack` verification failure when packing with `--target` (#394)
- Verbose lockfile iteration crashed with `'str' object has no attribute 'resolved_commit'` (#394)
- CodeQL incomplete URL substring sanitization in test assertions (#394)

### Security

- Bumped `h3` from 1.15.6 to 1.15.9 in docs (#400)

### Removed

- Unused image files: `copilot-banner.png`, `copilot-cli-screenshot.png` (#391)

## [0.8.3] - 2026-03-20

### Added

- Plugin authoring — `apm pack --format plugin` exports APM packages as standalone plugin directories (`plugin.json`, agents, skills, commands) consumable by Copilot CLI, Claude Code, and Cursor without APM installed (#379)
- `apm init --plugin` scaffolds a hybrid project with both `apm.yml` and `plugin.json`, including a `devDependencies` section (#379)
- `devDependencies` in `apm.yml` — dev deps install normally but are excluded from `apm pack` output; `apm install --dev` writes to the dev section (#379)
- VS Code runtime detection now falls back to `.vscode/` directory presence when the `code` binary is not on PATH — by @sergio-sisternes-epam (#359)

### Security

- Content integrity hashing — SHA-256 `content_hash` per dependency in `apm.lock.yaml`, verified on subsequent installs to detect tampering or force-pushed commits (#315, #379)
- `apm audit --strip` now preserves a leading BOM while stripping suspicious mid-file BOMs, preventing false negatives — by @dadavidtseng (#372)

### Changed

- Install URLs now use short `aka.ms/apm-unix` and `aka.ms/apm-windows` redirects across README, docs, and CLI output (#384)
- README highlights link to relevant docs pages; plugin authoring featured as a key value proposition (#385)

### Fixed

- `DependencyReference` preserved through the download pipeline so lockfile records the original ref, not an empty object — by @sergio-sisternes-epam (#383)
- Refactor command and model modules for readability and maintainability — by @sergio-sisternes-epam (#232)
- CLI docs align `compile --target opencode`, `audit --dry-run`, and planned `audit --drift` with current behavior (#373)

## [0.8.2] - 2026-03-19

### Added

- JFrog Artifactory VCS repository support — explicit FQDN, transparent proxy via `ARTIFACTORY_BASE_URL`, and air-gapped `ARTIFACTORY_ONLY` mode (#354)
- GH-AW compatibility gate in release pipeline — `gh-aw-compat` job tests tokenless install + pack before publishing (#356)
- Release validation now includes `test_ghaw_compat` scenario (#356)

### Fixed

- Credential fill returning garbage token in tokenless CI environments — broke `apm install` for public repos in GitHub Actions (#356)

### Security

- Harden dependency path validation — reject invalid path segments at parse time, enforce install-path containment, safe deletion wrappers across `uninstall`, `prune`, and `install` (#364)

## [0.8.1] - 2026-03-17

### Added

- Audit hardening — `apm unpack` content scanning, SARIF/JSON/Markdown `--format`/`--output` for CI capture, `SecurityGate` policy engine, non-zero exits on critical findings (#330)
- Install output now shows resolved git ref alongside package name (e.g. `✓ owner/repo#main (a1b2c3d4)`) (#340)
- `${input:...}` variable resolution for self-defined MCP server headers and env values — by @sergio-sisternes-epam (#344)

### Changed

- Pinning hint moved from inline tip to `── Diagnostics ──` section with aggregated count (#347)
- Install ref display uses `#` separator instead of `@` for consistency with dependency syntax (#340)
- Shorthand `@alias` syntax removed from dependency strings — use the dict format `alias:` field instead (#340)

### Fixed

- File-level downloads from private repos now use OS credential helpers (macOS Keychain, `gh auth login`, Windows Credential Manager) (#332)
- Lockfile now preserves the host for GitHub Enterprise custom domains so subsequent `apm install` clones from the correct server (#338)
- MCP registry validation no longer fails on transient network errors (#337)

## [0.8.0] - 2026-03-16

### Added

- Native Cursor IDE integration — `apm install` deploys instructions→rules (`.mdc`), agents, skills, hooks (`hooks.json`), and MCP (`mcp.json`) to `.cursor/` (#301)
- Native OpenCode integration — `apm install` deploys agents, commands, skills, and MCP (`opencode.json`) to `.opencode/` — inspired by @timvw (#306)
- Content security scanning with `apm audit` command — `--file`, `--strip`, `--dry-run`; install-time pre-deployment gate blocks critical hidden Unicode characters (#313)
- Detect variation selectors (Glassworm attack vector), invisible math operators, bidi marks, annotation markers, and deprecated formatting in content scanning — by @raye-deng (#321, #320)
- Context-aware ZWJ detection — emoji joiners preserved by `--strip`; `--strip --dry-run` preview mode (#321)
- `TargetProfile` data layer for scalable multi-target architecture (#301)
- `CursorClientAdapter` for MCP server management in `.cursor/mcp.json` (#301)
- `OpenCodeClientAdapter` for MCP server management in `opencode.json` (#306)
- Private packages guide and enhanced authentication documentation (#314)

### Changed

- Updated docs landing page to include Cursor and OpenCode (#310)
- Updated all doc pages to reflect full Cursor native support (#304)
- Added OpenCode to README headline and compile description (#308)

### Fixed

- GitHub API rate-limit 403 responses no longer misdiagnosed as authentication failures — unauthenticated users now see actionable "rate limit exceeded" guidance instead of misleading "private repository" errors

## [0.7.9] - 2026-03-13

### Added

- Local filesystem path dependencies — install packages from relative/absolute paths with `apm install ./my-package` (#270)
- Windows native support (Phase 1 & 2) — cross-platform runtime management, PowerShell helpers, and CI parity — by @sergio-sisternes-epam (#227)
- CLI logging UX agent skill for consistent CLI output conventions (#289)

### Fixed

- Resolve `UnboundLocalError` in `apm prune` crashing all prune operations (#283)
- Restore CWD before `TemporaryDirectory` cleanup on Windows — by @sergio-sisternes-epam (#281)
- Fix Codex runtime download 404 on Windows — asset naming uses `.exe.tar.gz` — by @sergio-sisternes-epam (#287)
- Fix `UnicodeEncodeError` on Windows cp1252 consoles via UTF-8 codepage configuration — by @sergio-sisternes-epam (#287)
- Fix `WinError 2` when resolving `.cmd`/`.ps1` shell wrappers via `shutil.which()` — by @sergio-sisternes-epam (#287)
- Fix `GIT_CONFIG_GLOBAL=NUL` failure on some Windows git versions — by @sergio-sisternes-epam (#287)
- Improve sub-skill overwrite UX with content skip and collision protection (#289)

### Changed

- Lockfile renamed from `apm.lock` to `apm.lock.yaml` for IDE syntax highlighting; existing `apm.lock` files are automatically migrated on the next `apm install` (#280)
- Add Windows as first-class install option across documentation site (#278)
- Clarify that `.github/` deployed files should be committed (#290)

## [0.7.8] - 2026-03-13

### Added

- Diff-aware `apm install` — manifest as source of truth: removed packages, ref/version changes, and MCP config drift in `apm.yml` all self-correct on the next `apm install` without `--update` or `--force`; introduces `drift.py` with pure helper functions (#260)
- `DiagnosticCollector` for structured install diagnostics (#267)
- Detailed file-level logging to `apm unpack` command (#252)
- Astro Starlight documentation site with narrative redesign (#243)

### Fixed

- Resolve WinError 32 during sparse-checkout fallback on Windows — by @JanDeDobbeleer (#235)
- CLI consistency: docs alignment, emoji removal, `show_default` flags (#266)

### Changed

- Minimum Python version bumped to 3.10; Black upgraded to 26.3.1 (#269)
- Refactor `cli.py` and `apm_package.py` into focused modules — by @sergio-sisternes-epam (#224)
- Revamp README as storefront for documentation site (#251, #256, #258)
- Remove duplicated content from CLI reference page (#261)
- Bump devalue 5.6.3 → 5.6.4 in docs (#263)
- Primitives models coverage 78% → 100%; add discovery and parser coverage tests (#240, #254)

## [0.7.7] - 2026-03-10

### Added

- `copilot` as the primary user-facing target name for GitHub Copilot / Cursor / Codex / Gemini output format; `vscode` and `agents` remain as aliases (#228)

### Changed

- Consolidate pack/unpack documentation into cli-reference, rename Key Commands section

## [0.7.6] - 2026-03-10

### Added

- `apm pack` and `apm unpack` commands for portable bundle creation and extraction with target filtering, archive support, and verification (#218)
- Plugin MCP Server installation — extract, convert, and deploy MCP servers defined in plugin packages (#217)

### Fixed

- Plugin agents not deployed due to directory nesting in custom agent paths (#214)
- Skip already-configured self-defined MCP servers on re-install (#191)
- CLI consistency: remove emojis from help strings, fix `apm config` bare invocation, update descriptions (#212)

### Changed

- Extract `MCPIntegrator` from `cli.py` — move MCP lifecycle orchestration (~760 lines) into standalone module with hardened error handling (#215)

## [0.7.5] - 2026-03-09

### Added

- Plugin management system with CLI commands for installing and managing plugins from marketplaces (#83)
- Generic git URL support for GitLab, Bitbucket, and any self-hosted git provider (#150)
- InstructionIntegrator for `apm install` — deploy `.instructions.md` files alongside existing integrators (#162)
- Transitive MCP dependency propagation (#123)
- MCP dependency config overlays, transitive trust flag, and related bug fixes (#166)
- Display build commit SHA in CLI version output (#176)
- Documentation: apm.yml manifest schema reference for integrators (#186)

### Fixed

- Handle multiple brace groups in `applyTo` glob patterns (#155)
- Replace substring matching with path-component matching in directory exclusions (#159)
- Handle commit SHA refs in subdirectory package clones (#178)
- Infer `registry_name` when MCP registry API returns empty values (#181)
- Resolve `set()` shadowing and sparse checkout ref issues (#184)
- CLI consistency — align help text with docs (#188)
- `--update` flag now bypasses lockfile SHA to fetch latest content (#192)
- Clean stale MCP servers on install/update/uninstall and prevent `.claude` folder creation (#201)
- Harden plugin security, validation, tests, and docs (#208)
- Use `CREATE_PR_PAT` for agentic workflows in Microsoft org (#144)

### Changed

- Unified `deployed_files` manifest for safe integration lifecycle (#163)
- Exclude `apm_modules` from compilation scanning and cache `Set[Path]` for performance (#157)
- Performance optimization for deep dependency trees (#173)
- Upgrade GitHub Agentic Workflows to v0.52.1 (#141)
- Fix CLI reference drift from consistency reports (#160, #161)
- Replace CHANGELOG link with roadmap discussion in docs index (#196)
- Update documentation for features from 2026-03-07 (#195)

## [0.7.4] - 2025-03-03

### Added

- Support hooks as an agent primitive with install-time integration and dependency display (hooks execute at agent runtime, not during `apm install`) (#97)
- Deploy agents to `.claude/agents/` during `apm install` (#95)
- Promote sub-skills inside packages to top-level `.github/skills/` entries (#102)

### Fixed

- Fix skill integration bugs, transitive dep cleanup, and simplification (#107)
- Fix transitive dependency handling in compile and orphan detection (#111)
- Fix virtual subdirectory deps marked as orphaned, skipping instruction processing (#100)
- Improve multi-host error guidance when `GITHUB_HOST` is set (#113, #130)
- Support spaces in Azure DevOps project names (#92)
- Fix GitHub Actions workflow permissions, integration test skip-propagation, and test corrections (#87, #106, #109)

### Changed

- Migrated to Microsoft OSS organization (#85, #105)
- Added CODEOWNERS, simplified PR/issue templates, triage labels, and updated CONTRIBUTING.md (#115, #118)
- Added missing `version` field in the apm.yml README example (#108)
- Slim PR pipelines to Linux-only, auto-approve integration tests, added agentic workflows for maintenance (#98, #103, #104, #119)


## [0.7.3] - 2025-02-15

### Added

- **SUPPORT.md**: Added Microsoft repo-template support file directing users to GitHub Issues and Discussions for community support

### Changed

- **README Rewording**: Clarified APM as "an open-source, community-driven dependency manager" to set correct expectations under Microsoft GitHub org
- **Microsoft Open Source Compliance**: Updated LICENSE, SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and added Trademark Notice to README
- **Source Integrity**: Fixed source integrity for all integrators and restructured README

### Fixed

- **Install Script**: Use `grep -o` for single-line JSON extraction in install.sh
- **CI**: Fixed integration test script to handle existing venv from CI workflow

### Security

- Bumped `azure-core` 1.35.1 → 1.38.0, `aiohttp` 3.12.15 → 3.13.3, `pip` 25.2 → 26.0, `urllib3` 2.5.0 → 2.6.3

## [0.7.2] - 2025-01-23

### Added

- **Transitive Dependencies**: Full dependency resolution with `apm.lock` lockfile generation

### Fixed

- **Install Script and `apm update`**: Repaired corrupted header in install.sh. Use awk instead of sed for shell subprocess compatibility. Directed shell output to terminal for password input during update process.

## [0.7.1] - 2025-01-22

### Fixed

- **Collection Extension Handling**: Prevent double `.collection.yml` extension when user specifies full path
- **SKILL.md Parsing**: Parse SKILL.md directly without requiring apm.yml generation
- **Git Host Errors**: Actionable error messages for unsupported Git hosts

## [0.7.0] - 2024-12-19

### Changed

- **Native Skills Support**: Skills now install to `.github/skills/` as the primary target (per [agentskills.io](https://agentskills.io/) standard)
- **Skills ≠ Agents**: Removed skill → agent transformation; skills and agents are now separate primitives
- **Explicit Package Types**: Added `type` field to apm.yml (`instructions`, `skill`, `hybrid`, `prompts`) for routing control
- **Skill Name Validation**: Validates and normalizes skill names per agentskills.io spec (lowercase, hyphens, 1-64 chars)
- **Claude Compatibility**: Skills also copy to `.claude/skills/` when `.claude/` folder exists

### Added

- Auto-creates `.github/` directory on install if neither `.github/` nor `.claude/` exists

## [0.6.3] - 2025-12-09

### Fixed

- **Selective Package Install**: `apm install <package>` now only installs the specified package instead of all packages from apm.yml. Previously, installing a single package would also install unrelated packages. `apm install` (no args) continues to install all packages from the manifest.

## [0.6.2] - 2025-12-09

### Fixed

- **Claude Skills Integration**: Virtual subdirectory packages (like `ComposioHQ/awesome-claude-skills/mcp-builder`) now correctly trigger skill generation. Previously all virtual packages were skipped, but only virtual files and collections should be skipped—subdirectory packages are complete skill packages.

## [0.6.1] - 2025-12-08

### Added

- **SKILL.md as first-class primitive**: meta-description of what an APM Package does for agents to read
- **Claude Skills Installation**: Install Claude Skills directly as APM Packages
- **Bidirectional Format Support**:
  - APM packages → SKILL.md (for Claude target)
  - Claude Skills → .agent.md (for VSCode target)
- **Skills Documentation**: New `docs/skills.md` guide

## [0.6.0] - 2025-12-08

### Added

- **Claude Integration**: First-class support for Claude Code and Claude Desktop
  - `CLAUDE.md` generation alongside `AGENTS.md`
  - `.claude/commands/` auto-integration from installed packages
  - `SKILL.md` generation for Claude Skills format
  - Commands get `-apm` suffix (same pattern as VSCode prompts)

- **Target Auto-Detection**: Smart compilation based on project structure
  - `.github/` only → generates `AGENTS.md` + VSCode integration
  - `.claude/` only → generates `CLAUDE.md` + Claude integration
  - Both folders → generates all formats
  - Neither folder → generates `AGENTS.md` only (universal format)

- **`target` field in apm.yml**: Persistent target configuration
  ```yaml
  target: vscode  # or claude, or all
  ```
  Applies to both `apm compile` and `apm install`

- **`--target` flag**: Override auto-detection
  ```bash
  apm compile --target claude
  apm compile --target vscode
  apm compile --target all
  ```

### Fixed

- Virtual package uninstall sync: `apm uninstall` now correctly removes only the specific virtual package's integrated files (uses `get_unique_key()` for proper path matching)

### Changed

- `apm compile` default: Changed from `--target all` to auto-detect
- README refactored with npm-style zero-friction onboarding
- Documentation reorganized with Claude integration guide

## [0.5.9] - 2025-12-04

### Fixed

- **ADO Package Commands**: `compile`, `prune`, and `deps list` now work correctly with Azure DevOps packages

## [0.5.8] - 2025-12-02

### Fixed

- **ADO Path Structure**: Azure DevOps packages now use correct 3-level paths (`org/project/repo`) throughout install, discovery, update, prune, and uninstall commands
- **Virtual Packages**: ADO collections and individual files install to correct 3-level paths
- **Prune Command**: Fixed undefined variable bug in directory cleanup

## [0.5.7] - 2025-12-01

### Added

- **Azure DevOps Support**: Install packages from Azure DevOps Services and Server
  - New `ADO_APM_PAT` environment variable for ADO authentication (separate from GitHub tokens)
  - Supports `dev.azure.com/org/project/_git/repo` URL format
  - Works alongside GitHub and GitHub Enterprise in mixed-source projects
- **Debug Mode**: Set `APM_DEBUG=1` to see detailed authentication and URL resolution output

### Fixed

- **GitHub Enterprise Private Repos**: Fixed authentication for `git ls-remote` validation on non-github.com hosts
- **Token Selection**: Correct token now used per-platform (GitHub vs ADO) in mixed-source installations

## [0.5.6] - 2025-12-01

### Fixed

- Enterprise GitHub host support: fallback clone now respects `GITHUB_HOST` env var instead of hardcoding github.com
- Version validation crash when YAML parses version as numeric type (e.g., `1.0` vs `"1.0"`)

### Changed

- CI/CD: Updated runner from macos-13 and macos-14 to macos-15 for both x86_64 and ARM64 builds

## [0.5.5] - 2025-11-17

### Added
- **Context Link Resolution**: Automatic markdown link resolution for `.context.md` files across installation and compilation
  - Links in prompts/agents automatically resolve to actual source locations (`apm_modules/` or `.apm/context/`)
  - Works everywhere: IDE, GitHub, all coding agents supporting AGENTS.md
  - No file copying needed—links point directly to source files

## [0.5.4] - 2025-11-17

### Added
- **Agent Integration**: Automatic sync of `.agent.md` files to `.github/agents/` with `-apm` suffix (same pattern as prompt integration)

### Fixed
- `sync_integration` URL normalization bug that caused ALL integrated files to be removed during uninstall instead of only the uninstalled package's files
  - Root cause: Metadata stored full URLs (`https://github.com/owner/repo`) while dependency list used short form (`owner/repo`)
  - Impact: Uninstalling one package would incorrectly remove prompts/agents from ALL other packages
  - Fix: Normalize both URL formats to `owner/repo` before comparison
  - Added comprehensive test coverage for multi-package scenarios
- Uninstall command now correctly removes only `apm_modules/owner/repo/` directory (not `apm_modules/owner/`)

## [0.5.3] - 2025-11-16

### Changed
- **Prompt Naming Pattern**: Migrated from `@` prefix to `-apm` suffix for integrated prompts
- **GitIgnore Pattern**: Updated from `.github/prompts/@*.prompt.md` to `.github/prompts/*-apm.prompt.md`

### Migration Notes
- **Existing Users**: Old `@`-prefixed files will not be automatically removed
- **Action Required**: Manually delete old `@*.prompt.md` files from `.github/prompts/` after upgrading

## [0.5.2] - 2025-11-14

### Added
- **Prompt Integration with GitHub** - Automatically sync downloaded prompts to `.github/prompts/` for GitHub Copilot

### Changed
- Improved installer UX and console output

## [0.5.1] - 2025-11-09

### Added
- Package FQDN support - install from any Git host using fully qualified domain names (thanks @richgo for PR #25)

### Fixed
- **Security**: CWE-20 URL validation vulnerability - proper hostname validation using `urllib.parse` prevents malicious URL bypass attacks
- Package validation HTTPS URL construction for git ls-remote checks
- Virtual package orphan detection in `apm deps list` command

### Changed
- GitHub Enterprise support via `GITHUB_HOST` environment variable (thanks @richgo for PR #25)
- Build pipeline updates for macOS compatibility

## [0.5.0] - 2025-10-30

### Added - Virtual Packages
- **Virtual Package Support**: Install individual files directly from any repository without requiring full APM package structure
  - Individual file packages: `apm install owner/repo/path/to/file.prompt.md`
- **Collection Support**: Install curated collections of primitives from [Awesome Copilot](https://github.com/github/awesome-copilot): `apm install github/awesome-copilot/collections/collection-name`
  - Collection manifest parser for `.collection.yml` format
  - Batch download of collection items into organized `.apm/` structure
  - Integration with github/awesome-copilot collections

### Added - Runnable Prompts
- **Auto-Discovery of Prompts**: Run installed prompts without manual script configuration
  - `apm run <prompt-name>` automatically discovers and executes prompts without having to wire a script in `apm.yml`
  - Search priority: local root → .apm/prompts → .github/prompts → dependencies
  - Qualified path support: `apm run owner/repo/prompt-name` for disambiguation
  - Collision detection with helpful error messages when multiple prompts found
  - Explicit scripts in apm.yml always take precedence over auto-discovery
- **Automatic Runtime Detection**: Detects installed runtime (copilot > codex) and generates proper commands
- **Zero-Configuration Execution**: Install and run prompts immediately without apm.yml scripts section

### Changed
- Enhanced dependency resolution to support virtual package unique keys
- Improved GitHub downloader with virtual file and collection package support
- Extended `DependencyReference.parse()` to detect and validate virtual packages (3+ path segments)
- Script runner now falls back to prompt discovery when script not found in apm.yml

### Developer Experience
- Streamlined workflow: `apm install <file>` → `apm run <name>` works immediately
- No manual script configuration needed for simple use cases
- Power users retain full control via explicit scripts in apm.yml
- Better error messages for ambiguous prompt names with disambiguation guidance

## [0.4.3] - 2025-10-29

### Added
- Auto-bootstrap `apm.yml` when running `apm install <package>` without existing config
- GitHub Enterprise Server and Data Residency Cloud support via `GITHUB_HOST` environment variable
- ARM64 Linux support

### Changed
- Refactored `apm init` to initialize projects minimally without templated prompts and instructions
- Improved next steps formatting in project initialization output

### Fixed
- GitHub token fallback handling for Codex runtime setup
- Environment variable passing to subprocess in smoke tests and runtime setup

## [0.4.2] - 2025-09-25

- Copilot CLI Support

## [0.4.1] - 2025-09-18

### Fixed
- Fix prompt file resolution for dependencies in org/repo directory structure
- APM dependency prompt files now correctly resolve from `apm_modules/org/repo/` paths
- `apm run` commands can now find and execute prompt files from installed dependencies
- Updated unit tests to match org/repo directory structure for dependency resolution

## [0.4.0] - 2025-09-18

- Context Packaging
- Context Dependencies
- Context Compilation
- GitHub MCP Registry integration
- Codex CLI Support