feat: report managed install changes

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.1
+### Features
+
+- **Verbose install update summaries** — `agentdeps install` now reports which managed skills and agents were added, updated, or removed when a dependency repository changes, making registry updates much easier to verify.
+
+### Notes
+
+- No new flags were added; unchanged installs still stay concise and report targets as up to date.
+- Link installs detect updated managed items from cached repository changes, while copy installs report updates when synced content changes on disk.
+
+
 ## 0.5.0
 
 ### Features

README.md

@@ -54,6 +54,17 @@ agentdeps install
 
 This clones/updates all dependency repos, discovers skills and agents, and installs them into each configured coding agent's directories.
 
+When install changes managed items, the output now includes itemized change groups so you can see exactly what changed:
+
+```text
+✓ Project (Pi): 1 skill added, 1 skill updated, 1 skill removed
+      skills added: new-skill
+      skills updated: my-skill
+      skills removed: another-skill
+```
+
+If nothing changed, install stays concise and reports the target as `up to date`.
+
 ### 4. List dependencies
 
 ```bash

openspec/changes/show-install-update-changes/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-27

openspec/changes/show-install-update-changes/design.md

@@ -0,0 +1,63 @@
+## Context
+
+`agentdeps install` currently reports aggregate counts per scope by reading `SyncSummary.added` and `SyncSummary.removed` from `syncManagedDir()`. That keeps the output short, but it loses the concrete item names users care about after a repository update. It also does not model `updated` as a first-class outcome: link-mode replacements are counted as additions, and copy-mode syncs classify existing targets as unchanged even when files were overwritten or removed.
+
+The install flow already has a natural place to surface better feedback. `src/install/managed.ts` decides whether each managed item was created, replaced, synchronized, pruned, or left alone, and `src/commands/install.ts` formats the user-facing summary. Improving those two layers keeps the change localized and avoids altering dependency resolution or registry semantics.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Distinguish top-level managed items that were added, updated, removed, or unchanged during install
+- Show itemized install output when changes occur so users can see which skills changed after a repository update
+- Preserve concise `up to date` output when install makes no changes
+- Cover both link and copy install methods with consistent change categories
+
+**Non-Goals:**
+- Showing file-level diffs within a skill or agent
+- Adding a new `--verbose` flag or other CLI surface area in this change
+- Changing dependency resolution, repository caching behavior, or install destinations
+- Reworking the overall install flow beyond the reporting data it already produces
+
+## Decisions
+
+### 1. Track `updated` as a first-class managed-item outcome
+
+`SyncSummary` will grow from `{ added, removed, unchanged }` to `{ added, updated, removed, unchanged }`.
+
+- In link mode, `ensureSymlink()` returning `created` maps to `added`, `replaced` maps to `updated`, and `unchanged` stays `unchanged`.
+- In copy mode, an existing target that required filesystem mutations during sync maps to `updated`; an existing target with no mutations remains `unchanged`.
+
+**Rationale:** The managed install layer already knows whether each top-level item was created, replaced, changed in place, or left alone. Making that explicit gives the CLI an accurate source of truth for user-facing reporting.
+
+**Alternative considered:** Infer updates later from aggregate counts or cache metadata. Rejected because counts lose item identity and cache changes do not always translate directly into installed-item changes.
+
+### 2. Make smart copy sync report whether it mutated the target
+
+`smartSync()` will return a change indicator that tells callers whether any files or directories were added, overwritten, or removed while synchronizing an existing target.
+
+**Rationale:** `syncManagedDir()` cannot accurately distinguish `updated` from `unchanged` in copy mode unless the copy layer reports whether it actually mutated the destination.
+
+**Alternative considered:** Snapshot and diff destination trees before and after sync. Rejected as more complex and less efficient than returning change information from the code that already performs the mutations.
+
+### 3. Report final installed item names at the managed-directory level
+
+Install output will be driven by the final managed sync results per scope/agent target, not by per-repository git diffs.
+
+**Rationale:** The install command merges resolved items across dependencies and deduplicates shared target directories before syncing. Reporting the final managed-item names is what users need to confirm what actually changed in their installed environment, and it avoids threading repository provenance through the full pipeline.
+
+**Alternative considered:** Compute per-repository diffs from cached git state and print those. Rejected because it adds cache-layer coupling and can diverge from what was ultimately installed after filtering and deduplication.
+
+### 4. Keep no-op installs concise and expand only changed categories
+
+`src/commands/install.ts` will continue to emit a compact `up to date` summary when nothing changed. When a scope/agent target has changes, the output will include the change counts plus indented item lists for non-empty `added`, `updated`, and `removed` groups.
+
+**Rationale:** This matches the user's request for more verbosity when installs change while preserving the current low-noise experience for repeat installs.
+
+**Alternative considered:** Always print full added/updated/removed sections or add a dedicated verbosity flag. Rejected because the current request is about making changed installs more informative, not making every install noisier or expanding the CLI API.
+
+## Risks / Trade-offs
+
+- **[Risk] Large updates could produce long output** → Mitigation: only print non-empty change groups and keep unchanged items summarized as `up to date`.
+- **[Risk] Copy-mode update classification could drift from real filesystem mutations** → Mitigation: derive `updated` directly from `smartSync()`'s actual write/remove operations instead of a second-pass guess.
+- **[Trade-off] Output is grouped by final managed target, not by source repository** → Acceptable because users asked to know which installed skills changed, and the managed target is the authoritative final state.
+- **[Trade-off] This adds more reporting data to tests** → Acceptable because the richer summaries should be locked down with unit and integration coverage.

openspec/changes/show-install-update-changes/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+`agentdeps install` currently reports only aggregate added/removed counts per scope. When an existing cached repository is updated, users cannot see which managed skills changed, which makes it hard to verify a registry update or understand why a project's installed capabilities now differ.
+
+## What Changes
+
+- Expand `agentdeps install` reporting so updated dependency repositories produce itemized change output instead of only aggregate counts.
+- Distinguish managed items that were added, updated, and removed during install, with clear skill-level reporting for repositories that changed.
+- Keep the install output concise when nothing changed, while surfacing detailed change lists only when they add value.
+
+## Capabilities
+
+### New Capabilities
+
+_(none — this extends existing capabilities)_
+
+### Modified Capabilities
+
+- `cli-commands`: The `install` command reports which managed items changed when a dependency repository update results in added, updated, or removed installs.
+- `install-management`: Managed directory sync exposes added, updated, removed, and unchanged item categories so install reporting can describe concrete changes instead of only counts.
+
+## Impact
+
+- **Code**: `src/commands/install.ts`, `src/install/managed.ts`, and supporting tests in `src/install/managed.test.ts` and `src/integration.test.ts`.
+- **Docs**: `README.md` should describe the richer install output.
+- **APIs**: No external API changes; CLI output becomes more descriptive.
+- **Dependencies**: None expected.

openspec/changes/show-install-update-changes/specs/cli-commands/spec.md

@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: CLI provides install command
+The CLI SHALL provide an `install` command that reads dependency configurations, clones/pulls repositories to the cache, discovers skills and subagents, installs them for all configured agents, and reports managed items that were added, updated, or removed when install changes occur.
+
+#### Scenario: Install with project agents.yaml
+- **WHEN** user runs `agentdeps install` in a directory containing `agents.yaml`
+- **THEN** the tool processes all dependencies, caches repos, and installs skills into `skills/_agentdeps_managed/` and subagents into `agents/_agentdeps_managed/` for each configured agent
+
+#### Scenario: Install without agents.yaml
+- **WHEN** user runs `agentdeps install` in a directory without `agents.yaml`
+- **THEN** the tool processes only the global `agents.yaml` (if it exists) and prints a message that no project dependencies were found
+
+#### Scenario: Install without global config
+- **WHEN** user runs `agentdeps install` and no `~/.config/agentdeps/config.yaml` exists
+- **THEN** the tool triggers the interactive setup before proceeding with installation
+
+#### Scenario: Install via npx
+- **WHEN** user runs `npx agentdeps install`
+- **THEN** the tool works identically to a globally installed version, with no additional setup required beyond the first-run config
+
+#### Scenario: Install reports managed item changes after dependency updates
+- **WHEN** user runs `agentdeps install` and the resolved install state changes for a managed target after dependency updates or dependency selection changes
+- **THEN** the output includes non-empty added, updated, and removed groups naming the affected managed skills and agents for that target
+
+#### Scenario: Install stays concise when nothing changed
+- **WHEN** user runs `agentdeps install` and all managed items already match the resolved dependencies
+- **THEN** the output indicates the relevant scope or target is up to date without printing empty change groups

openspec/changes/show-install-update-changes/specs/install-management/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Managed sync classifies item outcomes
+The tool SHALL classify each top-level managed skill or agent as added, updated, removed, or unchanged during sync so install reporting can describe concrete item changes.
+
+#### Scenario: First install is classified as added
+- **WHEN** a desired managed skill or agent does not yet exist in `_agentdeps_managed/`
+- **THEN** the sync result classifies that item as added
+
+#### Scenario: Replaced symlink is classified as updated
+- **WHEN** link-mode install finds an existing managed symlink that points to a different target than the desired cached item
+- **THEN** the sync result classifies that item as updated
+
+#### Scenario: Copy sync mutations are classified as updated
+- **WHEN** copy-mode install finds an existing managed item and smart sync overwrites, creates, or removes nested files or directories while reconciling it with the source
+- **THEN** the sync result classifies that item as updated
+
+#### Scenario: Pruned item is classified as removed
+- **WHEN** an item exists in `_agentdeps_managed/` but is no longer part of the desired managed set
+- **THEN** the sync result classifies that item as removed
+
+#### Scenario: Matching item is classified as unchanged
+- **WHEN** an existing managed item already matches the desired source without any filesystem mutations
+- **THEN** the sync result classifies that item as unchanged

openspec/changes/show-install-update-changes/tasks.md

@@ -0,0 +1,21 @@
+## 1. Add failing managed-sync tests
+
+- [x] 1.1 Update `src/install/managed.test.ts` to cover added, updated, removed, and unchanged outcomes in link mode
+- [x] 1.2 Update `src/install/copy.test.ts` and/or `src/install/managed.test.ts` to cover copy-mode targets that truly change versus targets that remain unchanged
+
+## 2. Implement managed item change classification
+
+- [x] 2.1 Change `src/install/copy.ts` so `smartSync()` reports whether it mutated the destination for file and directory syncs
+- [x] 2.2 Extend `src/install/managed.ts` `SyncSummary` and sync logic to populate `updated` separately from `added`, `removed`, and `unchanged`
+- [x] 2.3 Update any dependent types or helpers so link-mode replacements and copy-mode mutations are classified consistently
+
+## 3. Add failing install output tests
+
+- [x] 3.1 Add `src/commands/install.test.ts` coverage for install summaries that list non-empty added, updated, and removed groups while keeping no-op output concise
+- [x] 3.2 Extend `src/integration.test.ts` to verify `agentdeps install` prints changed managed skill names after an update
+
+## 4. Implement CLI reporting and docs
+
+- [x] 4.1 Update `src/commands/install.ts` to carry detailed change lists through install results and print itemized output for changed targets
+- [x] 4.2 Update `README.md` to document the richer install output
+- [x] 4.3 Run `bunx tsc --noEmit`, `bun test`, and `bun run build`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentdeps",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Declarative dependency manager for AI coding agent skills and subagents",
   "module": "src/index.ts",
   "type": "module",