[BUG] compile help and invalid-target error must advertise the accepted intellij target

[danielmeppiel]

fix(compile): advertise the accepted IntelliJ target

TL;DR

apm compile --target intellij already succeeds, but compile help and unknown-target guidance omitted it. This change derives compile and install help from the accepted target catalog and uses that catalog for invalid-target guidance.

Fixes #2138

Problem (WHY)

• apm compile --help contained zero intellij mentions.
• apm compile --target definitely-bogus exited 2 but omitted intellij from Valid targets.
• [!] The accepted catalog and advertised lists were maintained independently, allowing target drift.

Approach (WHAT)

1. Add one stable user-facing projection of VALID_TARGET_VALUES.
2. Reuse that projection in compile and install option help.
3. Pass the accepted catalog to unknown-target rendering instead of the narrower manifest catalog.
4. Lock the three user-visible IntelliJ scenarios with regression tests.

Implementation (HOW)

File	Change
src/apm_cli/core/target_detection.py	Defines TARGET_VALUES_HELP from VALID_TARGET_VALUES and supplies the accepted set to unknown-target guidance.
src/apm_cli/commands/compile/cli.py	Builds --target help from the shared projection and explains IntelliJ's Copilot file profile.
src/apm_cli/commands/install.py	Uses the same target projection so command help cannot drift independently.
tests/unit/compilation/test_compile_target_flag.py	Covers help, invalid-target guidance, and successful IntelliJ compilation to AGENTS.md.
Compile docs and apm-usage/commands.md	Document IntelliJ's accepted compile behavior and MCP-only distinction.

Diagram

The catalog is now the common input for validation, help, and invalid-target guidance.

flowchart LR
    C[VALID_TARGET_VALUES] --> V[TargetParamType validation]
    C --> H[TARGET_VALUES_HELP]
    H --> CH[compile help]
    H --> IH[install help]
    C --> E[unknown-target guidance]

Loading

Trade-offs

• Chose a small catalog projection over a new target-capability class; the current bug needs shared presentation, not a broader architecture migration.
• Preserved the existing agent-skills filtering policy in the generic error renderer; this change only corrects the catalog supplied by TargetParamType.

Benefits

1. Compile help now mentions intellij three times instead of zero.
2. Invalid-target guidance now includes intellij while retaining exit code 2.
3. apm compile --target intellij remains accepted and generates AGENTS.md.
4. Future accepted targets automatically appear in compile and install help.

Validation

Base regression proof

Before the implementation, the new tests produced:

2 failed, 1 passed, 80 deselected in 1.27s

Fixed regression tests

3 passed, 80 deselected in 1.25s

Targeted suites

182 passed in 0.48s
122 passed in 1.49s

Manual CLI scenarios

compile-help=3
install-help=4
invalid-exit=2 invalid-intellij=1
intellij-exit=0 agents-md=yes

Lint

The CI-mirror ruff, formatting, YAML I/O, file-length, portable-path, pylint R0801, auth-boundary, and ASCII checks passed.

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	Compile help tells me IntelliJ is accepted	DevX, Multi-harness support	tests/unit/compilation/test_compile_target_flag.py::TestCompileCommandCLI::test_help_advertises_intellij_target (regression-trap for #2138)	unit
2	An invalid target error lists IntelliJ among valid choices	DevX, Multi-harness support	tests/unit/compilation/test_compile_target_flag.py::TestCompileCommandCLI::test_invalid_target_error_advertises_intellij (regression-trap for #2138)	unit
3	Compiling for IntelliJ succeeds and generates AGENTS.md	Portability by manifest, Multi-harness support	tests/unit/compilation/test_compile_target_flag.py::TestCompileCommandCLI::test_target_flag_accepts_intellij	unit

How to test

• Run apm compile --help; confirm intellij appears.
• Run apm compile --target definitely-bogus; confirm exit 2 and intellij in Valid targets.
• In a project with a local instruction, run apm compile --target intellij; confirm exit 0 and AGENTS.md exists.
• Run the targeted pytest suites listed above; confirm all pass.

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

[Copilot]

Pull request overview

This PR fixes a DevX drift where apm compile --target intellij is accepted, but apm compile --help and the unknown-target error message did not advertise intellij. It centralizes target help text around a shared target catalog and adds regression tests + doc updates to keep the advertised/accepted sets aligned.

Changes:

• Introduces a shared, stable TARGET_VALUES_HELP string derived from the --target validator’s accepted value set.
• Uses the shared projection in compile and install --target help text, and updates unknown-target rendering to include the accepted catalog.
• Adds unit tests and documentation updates covering intellij help visibility, invalid-target guidance, and a successful IntelliJ compilation scenario.

Show a summary per file

File	Description
src/apm_cli/core/target_detection.py	Adds TARGET_VALUES_HELP and switches unknown-target guidance to use the accepted target catalog.
src/apm_cli/commands/compile/cli.py	Derives --target help from the shared projection and documents IntelliJ behavior in CLI help text.
src/apm_cli/commands/install.py	Uses the same shared target projection in install --help to prevent drift.
tests/unit/compilation/test_compile_target_flag.py	Adds regression tests for help text, invalid-target guidance, and --target intellij success.
docs/src/content/docs/reference/cli/compile.md	Updates CLI reference docs to reflect that help derives from the validation catalog and documents IntelliJ behavior.
docs/src/content/docs/producer/compile.md	Updates producer docs to include intellij as an accepted compile target and clarifies behavior.
packages/apm-guide/.apm/skills/apm-usage/commands.md	Updates the command reference to mention intellij acceptance and Copilot-profile behavior for file primitives.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 2
• Review effort level: Low

[danielmeppiel]

Superseded by #2155. The reliability campaign consolidated all 13 point fixes into a single architectural cure PR that re-homes each fix under its canonical owner module and adds owner-invariant guards. The fix for #2138 is folded into #2155 and re-verified there (full CI green). Closing this point PR in favor of the consolidated cure; the branch is preserved and this can be reopened if #2155 is not merged.