[FEATURE] Feature request: sync/check/status/doctor workflow for installed context

[yogurtearl]

Feature request: sync/check/status/doctor workflow for installed context

At a glance

• Problem: after install, the operational questions are scattered across multiple commands and manual inspection.
• Why it matters: CI and day-to-day maintenance need a simple, repeatable workflow.
• Example syntax:

apm sync
apm sync --update
apm check
apm status
apm doctor

Is your feature request related to a problem? Please describe.

Yes. After APM installs context, teams still need to answer a few basic questions quickly:

• what is installed here?
• does the working tree still match the lockfile?
• why did refresh fail on this machine or in CI?

Today those answers are spread across apm install, apm compile, lockfile inspection, and generic git diff.

Describe the solution you'd like

Add a first-class lifecycle for installed context.

Example syntax:

apm sync            # materialize from the lockfile
apm sync --update   # refresh refs and rewrite the lockfile
apm check           # fail on drift between generated output and lock state
apm status          # show packages, refs, and output locations
apm doctor          # surface auth, cache, config, and environment problems

Even if these start as thin wrappers around existing behavior, the value is having one obvious workflow for both humans and CI.

Describe alternatives you've considered

• apm install + apm compile
• inspect apm.lock.yaml directly
• use git diff to detect drift
• piece together troubleshooting from multiple commands

That works, but it is harder to teach, harder to automate, and slower to debug.

Additional context

This would make APM easier to operate at scale. Repos that rely on generated agent context usually need deterministic installs, a CI-safe drift check, a quick status view, and a fast way to diagnose environment issues.

[danielmeppiel]

Thanks for the well-structured ask, @yogurtearl — it forced a real look at what APM's post-install workflow actually surfaces today vs what users mentally reach for. Convened a small panel internally (devx-ux pro/con, growth, CEO) and here's where we landed.

Three-tier disposition

Ask	Decision	Rationale
apm sync	Decline	Already apm install --frozen — same idiom as pnpm install --frozen-lockfile. Adding a synonym forks every CI script / blog post / SO answer between two names forever (the npm install/i/add graveyard).
apm sync --update	Decline	Already apm update (or apm update --yes for CI). Identical semantics.
apm check	Decline	Already apm audit --ci (with --no-fail-fast, --format sarif, --output, --no-drift). Also: check is taken by apm marketplace check.
apm status	Defer	Tempting, but apm deps tree + apm deps list + apm outdated + apm targets already render the inventory — across two namespaces. We'll only ship status if we can articulate a single line of output that none of those already provide (e.g. real cross-cutting drift detection). For now we'll surface apm deps tree as the canonical "what do I have?" answer.
apm doctor	Ship	This is the real gap. apm marketplace doctor already exists but is scope-debt — most of its checks (git, auth, network reachability) are universal, not publish-specific. Promoting to top-level apm doctor resolves the scope mis-design AND gives the "I'm stuck, what's wrong?" persona a real entry point.

What's shipping in the PR for this issue

1. apm doctor (top-level). Initially preserves the existing marketplace doctor check set so we ship something trustworthy and bounded (avoiding the flutter doctor / brew doctor "always complains" anti-pattern). apm marketplace doctor becomes a hidden deprecated alias for one release. The implementation lands as a small domain-registry so future PRs can add lockfile / cache / runtime / config domains incrementally, each with their own scope justification.
2. apm --help "Common workflows" footer. Lifecycle hint (init → install → outdated → update → doctor) and a CI one-liner (apm install --frozen && apm audit --ci).
3. Contextual error hints. Frozen-install drift failures point at apm outdated / apm update; auth failures point at apm doctor.
4. Rosetta Stone docs page: "Operating installed context" — maps every "I want to..." question to the existing command (including apm deps why, apm deps tree, apm outdated, apm install --frozen, apm audit --ci, apm doctor). The discoverability gap behind your original report is mostly here.

Why not just ship all five

Two reasons that came out strongest in the panel:

• Vocabulary correction vs vocabulary fork. npm ci worked because npm install was non-deterministic by default and ci named a missing concept. apm install --frozen already names the concept — --frozen is a recognized package-manager idiom. Adding apm sync would be a synonym, not a missing primitive.
• Surface area is one-way. APM already has more top-level commands than cargo/uv/npm/pip. Adding 4 more for what's mostly a discoverability problem treats the symptom. Fixing --help, error hints, and docs treats the cause.

doctor is the exception because it's not a synonym — it's a scope-corrected promotion of a command that already exists but was filed under the wrong namespace.

PR incoming on this branch. Thanks again for the thoughtful issue — it's the kind that improves the CLI well past its own surface area.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/cli
area/docs-site
type/feature
status/needs-design

(Note: type/feature label already present and preserved.)

Milestone

null

Suggested next action

Draft a design note mapping each proposed command (sync, check, status, doctor) to existing APM commands, justifying which warrant a new top-level verb vs a new flag on an existing command, and defining the exact behavior and exit codes for each.

Suggested issue comment

Thanks for the well-framed request -- the pain is real. After install, the operational questions (what is installed? does the tree match the lockfile? why is CI failing?) are currently scattered across `apm install`, `apm compile`, `apm deps list`, and lockfile inspection.

The direction (a first-class operational lifecycle) is accepted in principle. Before we commit to four new top-level verbs, a design note is needed that maps each to existing behavior:

- `apm sync`: is this `apm install --from-lockfile`? A new flag on `apm install`, or a new verb?
- `apm check`: this seems genuinely new (drift detection between generated output and lock state). Confirm.
- `apm status`: how does this differ from `apm deps list`? What new information does it surface?
- `apm doctor`: what exact checks does it run? (auth, cache, config, env vars, harness detection?) What is the output format and exit code on failure?

The "thin wrappers around existing behavior" framing is pragmatic and appreciated. Starting with `apm check` (the clearest gap) and `apm doctor` (no existing equivalent) as the first PR, while `sync` and `status` land as flags on existing commands, might be the right sequencing.

Would you like to draft the design note?

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The brew doctor mental model is the strongest part of this request -- apm doctor for auth/cache/config/env diagnostics has no current equivalent and would be high-value for CI debugging. apm check (drift detection) also appears to be a genuine gap. apm sync and apm status have more overlap with existing commands and need clearer differentiation. The key UX question is: does APM's surface benefit from four new verbs, or should some be flags on existing commands?

Supply Chain Security Expert -- Risk-Surface Reviewer

apm doctor surfacing auth tokens, cache paths, and env var values must confirm presence/absence of secrets, not print their values. No new network surface. area/cli applies. No supply-chain risk in the proposal itself.

OSS Growth Hacker -- Contributor-Tone Reviewer

yogurtearl is NONE association, same author as #1535. Two well-written feature requests from the same contributor -- clearly invested in APM adoption. The reply should warmly acknowledge both issues, give a concrete design question to answer for this one, and avoid making them feel like their requests are being deflected.

Python Architect -- Architecture Reviewer

Four new top-level CLI verbs is a significant surface commitment. The design must answer for each proposed verb: (1) does equivalent functionality already exist? (2) is a new verb justified or would a flag suffice? (3) what are the exact exit codes? apm check and apm doctor appear to be genuine gaps; apm sync and apm status need stronger differentiation from apm install and apm deps list. Status: needs-design.

Doc Writer -- Documentation Reviewer

New commands need new reference pages and a guide for the CI-safe drift check workflow. area/docs-site is included in the label set as a primary secondary area for this issue.

APM CEO -- Triage Arbiter

The pain is real but four new top-level verbs is a large surface commitment. apm doctor and apm check are the clearest gaps; apm sync and apm status need design work to differentiate from existing commands. Verdict: needs-design. theme/portability because these commands improve cross-platform, cross-target operational consistency.

{
  "decision": "needs-design",
  "decision_detail": "Design must map each proposed command (sync, check, status, doctor) to existing APM commands, justify new top-level verbs vs new flags on existing commands, and define exact behavior and exit codes for each.",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design note mapping each proposed command to existing APM commands, justifying which warrant a new verb vs a new flag, and defining behavior and exit codes.",
  "comment_markdown": "Direction accepted in principle. Before committing to four new top-level verbs, a design note is needed mapping each (sync, check, status, doctor) to existing behavior and justifying new verbs over new flags. apm check and apm doctor appear to be genuine gaps. Would you like to draft the design note?"
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 7.4M · ◷

[danielmeppiel]

Thanks for pushing on post-install discoverability. The core of this has shipped: apm doctor is now a top-level command for environment and health checks.

On the remaining proposed verbs, we are intentionally keeping the CLI surface small. sync overlaps apm install --frozen, check is covered by apm audit --ci, and status decomposes into the existing apm deps tree / apm outdated. Adding synonyms tends to fragment muscle memory rather than help, so we would rather invest in docs discoverability than new verbs.

Closing as completed (doctor landed). If there is a specific workflow doctor does not cover, a focused follow-up issue is very welcome.