feat(cli): promote 'marketplace doctor' to top-level 'apm doctor' (+ workflow discoverability) (#1539)

* feat(cli): promote 'marketplace doctor' to top-level 'apm doctor' (#1537)

Closes one of the four asks in #1537 by promoting the diagnostics
verb to a top-level command and adding small discoverability hooks
around the existing lifecycle commands.

Tier 1 (this PR):
* Promote 'apm marketplace doctor' to 'apm doctor'. The legacy
  invocation keeps working as a hidden deprecated alias that prints
  a one-line migration hint before delegating.
* Add a 'Common workflows' epilog to 'apm --help' so init -> install
  -> outdated -> update -> doctor and the 'install --frozen && audit
  --ci' CI idiom are discoverable from the root help.
* Add contextual error tips: AuthenticationError now points to
  'apm doctor'; FrozenInstallError points to 'apm outdated' +
  'apm update'. Five touch sites, one-line nudges each.
* New Rosetta Stone guide 'Operating installed context' mapping
  npm/pnpm/uv/cargo/brew vocabulary to existing apm verbs (deps why,
  deps tree, outdated, install --frozen, audit --ci, doctor).

Tier 2 deferred: 'apm status' summary view -- waits for a concrete
shape that isn't already covered by deps tree + outdated + targets.

Tier 3 declined: 'apm sync', 'apm sync --update', and 'apm check'
are exact duplicates of 'install --frozen', 'update', and 'audit
--ci' respectively (the 'check' name also collides with 'apm
marketplace check'). Documented in the issue reply.

The arch-invariant budget for commands/install.py is raised
2010 -> 2012 with justification matching the lockfile-UX precedent.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(cli): address copilot-pull-request-reviewer feedback on #1539

Folds 7 inline review comments:

* tests/unit/install/test_architecture_invariants.py: correct skill
  path .github -> .apm/skills/python-architecture/SKILL.md (the
  pre-existing message pointed to a non-existent location).
* tests/unit/commands/test_doctor.py: the deprecation-hint assertion
  now checks both stdout and stderr so it does not depend on Click
  8.2's stream-separation default.
* src/apm_cli/cli.py: reformat _CLI_EPILOG so the per-line layout
  survives Click's epilog rewrapping. Keeps the documented Click
  '\b' formatting marker (already used in src/apm_cli/commands/view.py
  lines 422 and 425) which is a CLI rendering directive, not
  user-facing output.
* src/apm_cli/commands/install.py, src/apm_cli/commands/update.py:
  pass symbol='info' on the new _rich_info() tip lines so they render
  with the standard [i] prefix and match neighbouring usage.
* docs/src/content/docs/guides/operating-installed-context.md:
  document 'apm targets' as the default invocation; mention
  '--json --all' for the agent-skills meta-target.

Arch budget for install.py raised 2012 -> 2014 to absorb ruff's
multi-line reformat of the now-keyword-arg _rich_info() call.
Justification kept inline.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

docs/src/content/docs/guides/operating-installed-context.md

@@ -0,0 +1,91 @@
+---
+title: "Operating installed context"
+description: "Day-to-day workflow for APM-managed projects: reproduce the lockfile in CI, see what is installed, diagnose environment problems. Maps every common operational question to the existing command."
+sidebar:
+  order: 7
+---
+
+After `apm install` succeeds, the day-to-day operating questions are: what
+is installed, has anything drifted from the lockfile, and why is the
+environment broken when something fails. APM ships a command for each
+question -- this page maps the question to the command so you do not have
+to remember the flag matrix.
+
+## At a glance
+
+| You want to... | Run | Notes |
+|---|---|---|
+| Reproduce the lockfile exactly (CI gate) | `apm install --frozen` | Refuses to install when `apm.lock.yaml` is missing or out of sync with `apm.yml`. Equivalent in spirit to `npm ci` / `pnpm install --frozen-lockfile`. |
+| Refresh refs and rewrite the lockfile | `apm update` (or `apm update --yes` for CI) | Restructures the dependency graph against latest matching refs. |
+| Validate lockfile integrity for CI | `apm audit --ci` | Lockfile-consistency check + on-disk integrity. Pair with `--format sarif --output audit.sarif` for GitHub Code Scanning. |
+| See what is installed | `apm deps list` | Project scope. Add `--global` for `~/.apm/`. |
+| Inspect the dependency tree | `apm deps tree` | Hierarchical view of direct + transitive deps. |
+| Find out why a package is installed | `apm deps why <package>` | Reverse lookup -- "who pulled this in?". Add `--json` for scripts. |
+| See what is outdated | `apm outdated` | Locked refs vs latest matching upstream. |
+| Diagnose a broken environment | `apm doctor` | Aggregated pass/fail table: git, network, auth, gh CLI, and (if present) marketplace config. |
+| Inspect the cache | `apm cache info` | Disk usage and location. `apm cache clean` removes everything; `apm cache prune --days N` is incremental. |
+| Inspect resolved runtimes | `apm runtime status` | Active runtime and preference order. |
+| Inspect resolved targets | `apm targets` | Which harnesses APM will deploy to. Add `--json --all` to include meta-targets (e.g. `agent-skills`). |
+| Show package metadata | `apm view <package>` | Versions, refs, owner, declared scripts. |
+
+## Recommended CI block
+
+```yaml
+- run: apm install --frozen
+- run: apm audit --ci --format sarif --output apm-audit.sarif
+```
+
+The `--frozen` flag is the CI-safety primitive: if the lockfile is missing
+or has drifted from `apm.yml`, the install fails before producing any
+artifacts. `apm audit --ci` is then the integrity gate -- it validates that
+the locked content matches what was actually fetched.
+
+## Local refresh loop
+
+```bash
+apm update            # refresh refs + rewrite the lockfile
+apm install           # materialize the new lockfile
+apm audit             # confirm integrity
+```
+
+Use this when you intentionally want to take newer upstream refs. The
+lockfile change is the auditable record of the upgrade.
+
+## When something is broken
+
+The first stop for "I installed but it does not work" or "CI passes
+locally but fails on the runner" is `apm doctor`. It runs a bounded set of
+environment checks (git on PATH, github.com reachable, auth token
+detected, gh CLI present, optionally marketplace config) and renders a
+pass/fail table with a single non-zero exit code if a critical check
+fails.
+
+```bash
+apm doctor               # quick pass/fail table
+apm doctor --verbose     # plus detail per check
+```
+
+For more targeted introspection:
+
+- `apm cache info` -- is the cache writable, how large is it
+- `apm runtime status` -- is the expected runtime installed
+- `apm config` -- is the configuration parseable, what is active
+- `APM_DEBUG=1 apm install --dry-run -v` -- full resolution trace
+
+## Vocabulary mapping for users coming from other ecosystems
+
+If you reach for a verb from another package manager and APM does not
+have it, the equivalent is almost always already in the table above.
+Common translations:
+
+| Other ecosystem | APM equivalent |
+|---|---|
+| `npm ci` | `apm install --frozen` |
+| `npm audit` | `apm audit` |
+| `npm why <pkg>` / `yarn why <pkg>` | `apm deps why <pkg>` |
+| `pnpm install --frozen-lockfile` | `apm install --frozen` |
+| `uv sync` | `apm install` (or `apm install --frozen` for the CI form) |
+| `uv lock --check` | `apm audit --ci` |
+| `cargo tree -i <pkg>` | `apm deps why <pkg>` |
+| `brew doctor` / `flutter doctor` | `apm doctor` |
+| `pip check` | `apm audit` |

src/apm_cli/cli.py

@@ -22,6 +22,7 @@
 from apm_cli.commands.compile import compile as compile_cmd
 from apm_cli.commands.config import config
 from apm_cli.commands.deps import deps
+from apm_cli.commands.doctor import doctor
 from apm_cli.commands.experimental import experimental
 from apm_cli.commands.init import init
 from apm_cli.commands.install import install
@@ -43,8 +44,24 @@
 from apm_cli.commands.update import update
 from apm_cli.commands.view import view as view_cmd
 
+_CLI_EPILOG = (
+    "\b\n"
+    "Common workflows:\n"
+    "  apm init                       Scaffold a new project\n"
+    "  apm install                    Install dependencies from apm.yml\n"
+    "  apm install --frozen           Reproduce lockfile exactly (CI-safe)\n"
+    "  apm outdated                   See what's drifted from upstream\n"
+    "  apm update                     Refresh refs and rewrite the lockfile\n"
+    "  apm audit --ci                 Validate lockfile integrity for CI gates\n"
+    "  apm doctor                     Diagnose environment problems\n"
+    "  apm run <script>               Execute a script from apm.yml"
+)
+
 
-@click.group(help="Agent Package Manager (APM): The package manager for AI-Native Development")
+@click.group(
+    help="Agent Package Manager (APM): The package manager for AI-Native Development",
+    epilog=_CLI_EPILOG,
+)
 @click.option(
     "--version",
     is_flag=True,
@@ -107,6 +124,7 @@ def cli(ctx):
 cli.add_command(mcp)
 cli.add_command(policy)
 cli.add_command(outdated_cmd, name="outdated")
+cli.add_command(doctor)
 cli.add_command(marketplace)
 cli.add_command(marketplace_search, name="search")
 

src/apm_cli/commands/doctor.py

@@ -0,0 +1,32 @@
+"""``apm doctor`` top-level command.
+
+Thin Click wrapper around :func:`apm_cli.commands.marketplace.doctor.run_doctor`.
+The diagnostics are owned by the marketplace doctor module today because that
+is where the existing implementation lives; promoting the entry point to the
+top level is a discoverability fix without scope expansion. Future PRs may
+add additional domains (lockfile, cache, runtime, config) by extending
+``run_doctor`` -- each behind its own scope justification.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .marketplace.doctor import run_doctor
+
+
+@click.command(
+    help=(
+        "Run environment diagnostics (git, network, auth, gh CLI, "
+        "marketplace config). Reports a pass/fail table and exits non-zero "
+        "if a critical check fails."
+    )
+)
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
+def doctor(verbose):
+    """Top-level diagnostic entry point."""
+    exit_code = run_doctor(verbose, logger_name="doctor")
+    if exit_code != 0:
+        sys.exit(exit_code)

src/apm_cli/commands/install.py

@@ -1544,6 +1544,7 @@ def install(  # noqa: PLR0913
         _rich_error(str(e))
         if e.diagnostic_context:
             _rich_echo(e.diagnostic_context)
+        _rich_info("Tip: run 'apm doctor' to diagnose auth and connectivity.", symbol="info")
         sys.exit(1)
     except DirectDependencyError as e:
         _maybe_rollback_manifest(_snapshot_manifest_path, _manifest_snapshot, logger)
@@ -1750,12 +1751,17 @@ def _install_apm_packages(ctx, outcome):
             _rich_error(str(e))
             if e.diagnostic_context:
                 _rich_echo(e.diagnostic_context)
+            _rich_info("Tip: run 'apm doctor' to diagnose auth and connectivity.", symbol="info")
             sys.exit(1)
         except FrozenInstallError as e:
             _maybe_rollback_manifest(ctx.snapshot_manifest_path, ctx.manifest_snapshot, logger)
             _rich_error(str(e))
             for reason in e.reasons:
                 _rich_echo(reason)
+            _rich_info(
+                "Tip: run 'apm outdated' to see what changed, then 'apm update'.",
+                symbol="info",
+            )
             sys.exit(1)
         except Exception as e:
             _maybe_rollback_manifest(ctx.snapshot_manifest_path, ctx.manifest_snapshot, logger)

src/apm_cli/commands/marketplace/__init__.py

@@ -84,7 +84,6 @@ class MarketplaceGroup(click.Group):
         "init",
         "check",
         "outdated",
-        "doctor",
         "publish",
         "package",
         "migrate",

src/apm_cli/commands/marketplace/doctor.py

@@ -1,4 +1,4 @@
-"""``apm marketplace doctor`` command."""
+"""``apm doctor`` (and legacy ``apm marketplace doctor``) command implementation."""
 
 from __future__ import annotations
 
@@ -25,11 +25,14 @@
 )
 
 
-@marketplace.command(help="Run environment diagnostics for marketplace publishing")
-@click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
-def doctor(verbose):
-    """Check git, network, auth, and marketplace config readiness."""
-    logger = CommandLogger("marketplace-doctor", verbose=verbose)
+def run_doctor(verbose: bool, *, logger_name: str = "doctor") -> int:
+    """Execute the doctor diagnostics and return an exit code.
+
+    Shared between the top-level ``apm doctor`` command and the legacy
+    ``apm marketplace doctor`` alias so both surfaces produce identical
+    output. Returns ``0`` if all critical checks pass, ``1`` otherwise.
+    """
+    logger = CommandLogger(logger_name, verbose=verbose)
     checks = []
 
     # Check 1: git on PATH
@@ -275,4 +278,28 @@ def doctor(verbose):
     # Exit: 0 if checks 1-2 pass; config checks are informational
     critical_checks = [c for c in checks if not c.informational]
     if any(not c.passed for c in critical_checks):
-        sys.exit(1)
+        return 1
+    return 0
+
+
+@marketplace.command(
+    name="doctor",
+    help="DEPRECATED: use 'apm doctor' instead. Run environment diagnostics.",
+    hidden=True,
+)
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
+def doctor(verbose):
+    """Deprecated alias for ``apm doctor``.
+
+    Prints a one-line deprecation hint and forwards to :func:`run_doctor`.
+    The command stays functional for one release to give CI pipelines and
+    scripts time to migrate; it is hidden from ``apm marketplace --help``
+    so new users discover the top-level form.
+    """
+    click.echo(
+        "[!] 'apm marketplace doctor' is deprecated; use 'apm doctor' instead.",
+        err=True,
+    )
+    exit_code = run_doctor(verbose, logger_name="marketplace-doctor")
+    if exit_code != 0:
+        sys.exit(exit_code)

src/apm_cli/commands/update.py

@@ -321,11 +321,16 @@ def _plan_callback(plan: UpdatePlan) -> bool:
         _rich_error(str(e))
         for reason in e.reasons:
             _rich_echo(reason)
+        _rich_info(
+            "Tip: run 'apm outdated' to see what changed, then 'apm update'.",
+            symbol="info",
+        )
         sys.exit(1)
     except AuthenticationError as e:
         _rich_error(str(e))
         if e.diagnostic_context:
             _rich_echo(e.diagnostic_context)
+        _rich_info("Tip: run 'apm doctor' to diagnose auth and connectivity.", symbol="info")
         sys.exit(1)
     except (DirectDependencyError, PolicyViolationError) as e:
         _rich_error(str(e))

tests/unit/commands/test_doctor.py

@@ -0,0 +1,89 @@
+"""Tests for the top-level ``apm doctor`` command and its deprecated alias."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from apm_cli.cli import cli
+from apm_cli.commands.marketplace import marketplace
+
+# Token env vars that AuthResolver inspects.  Cleared so the doctor's auth
+# check is deterministic regardless of the host environment.
+_TOKEN_ENV_VARS = ("GITHUB_APM_PAT", "GITHUB_TOKEN", "GH_TOKEN")
+
+
+@pytest.fixture(autouse=True)
+def _clear_token_env(monkeypatch):
+    for var in _TOKEN_ENV_VARS:
+        monkeypatch.delenv(var, raising=False)
+
+
+@pytest.fixture
+def mock_subprocess_success():
+    """Stub git/gh subprocess calls to deterministic success."""
+    with patch("apm_cli.commands.marketplace.doctor.subprocess.run") as run:
+        run.return_value.returncode = 0
+        run.return_value.stdout = "git version 2.42.0"
+        run.return_value.stderr = ""
+        yield run
+
+
+def test_apm_doctor_registered_at_top_level():
+    """`apm doctor --help` must succeed -- it is the discoverability fix."""
+    runner = CliRunner()
+    result = runner.invoke(cli, ["doctor", "--help"])
+    assert result.exit_code == 0
+    assert "environment diagnostics" in result.output.lower()
+
+
+def test_apm_doctor_appears_in_root_help():
+    """`apm --help` must list `doctor` so users can discover it."""
+    runner = CliRunner()
+    result = runner.invoke(cli, ["--help"])
+    assert result.exit_code == 0
+    assert "doctor" in result.output
+
+
+def test_common_workflows_footer_present():
+    """`apm --help` epilog must surface the common-workflows hint."""
+    runner = CliRunner()
+    result = runner.invoke(cli, ["--help"])
+    assert result.exit_code == 0
+    assert "Common workflows" in result.output
+    assert "apm install --frozen" in result.output
+    assert "apm doctor" in result.output
+
+
+def test_marketplace_doctor_hidden_from_help():
+    """Legacy `apm marketplace doctor` must not appear in marketplace --help."""
+    runner = CliRunner()
+    result = runner.invoke(cli, ["marketplace", "--help"])
+    assert result.exit_code == 0
+    # 'doctor' as a subcommand listing should be gone from the Authoring
+    # commands block now that it has been promoted to top-level.
+    assert "doctor  " not in result.output  # column-aligned listing
+
+
+def test_marketplace_doctor_still_works_with_deprecation_hint(mock_subprocess_success):
+    """Legacy invocation must keep working and print the migration hint."""
+    runner = CliRunner()
+    result = runner.invoke(marketplace, ["doctor"])
+    # The deprecation hint is emitted with err=True. Click 8.2 separates
+    # stdout/stderr by default, so check both to stay version-agnostic.
+    combined = (result.output or "") + (getattr(result, "stderr", "") or "")
+    assert "deprecated" in combined.lower()
+    assert "apm doctor" in combined
+    # And the diagnostics still run.
+    assert result.exit_code in (0, 1)  # 1 if network unreachable in sandbox
+
+
+def test_apm_doctor_runs_diagnostics(mock_subprocess_success):
+    """Top-level invocation should produce the diagnostics table."""
+    runner = CliRunner()
+    result = runner.invoke(cli, ["doctor"])
+    # Network check may legitimately fail in sandboxed test env -> non-zero ok.
+    assert result.exit_code in (0, 1)
+    assert "git" in result.output.lower()

tests/unit/install/test_architecture_invariants.py

@@ -185,13 +185,20 @@ def test_install_py_under_legacy_budget():
     by the new ``apm update`` command and CI-safe install flow. All
     additions are entry-point glue at the Click handler boundary; the
     actual logic lives in ``apm_cli/install/`` (plan, errors, service).
+
+    Issue #1537 (sync/check/status/doctor workflow) raised 2010 -> 2014
+    to add two contextual error-hint blocks: an ``apm doctor`` tip on
+    ``AuthenticationError`` and an ``apm outdated`` -> ``apm update``
+    tip on ``FrozenInstallError``. Both are entry-point glue (one
+    ``_rich_info(..., symbol="info")`` call per handler, expanded to
+    multiple lines by ruff's formatter) -- no new logic.
     """
     install_py = Path(__file__).resolve().parents[3] / "src" / "apm_cli" / "commands" / "install.py"
     assert install_py.is_file()
     n = _line_count(install_py)
-    assert n <= 2010, (
-        f"commands/install.py grew to {n} LOC (budget 2010). "
+    assert n <= 2014, (
+        f"commands/install.py grew to {n} LOC (budget 2014). "
         "Do NOT trim cosmetically -- engage the python-architecture skill "
-        "(.github/skills/python-architecture/SKILL.md) and propose an "
+        "(.apm/skills/python-architecture/SKILL.md) and propose an "
         "extraction into apm_cli/install/."
     )