feat: Support Codex CLI as integration target

[Copilot]

Description

Codex CLI uses a multi-directory config model that breaks APM's single-root_dir assumption: skills deploy to .agents/skills/ (cross-tool agent skills standard), while agents (TOML) and hooks live under .codex/.

Core abstraction: deploy_root: Optional[str] = None on PrimitiveMapping. When set, overrides target.root_dir for path computation. Default None = zero behavior change for existing targets.

"codex": TargetProfile(
    name="codex",
    root_dir=".codex",
    primitives={
        "agents": PrimitiveMapping("agents", ".toml", "codex_agent"),
        "skills": PrimitiveMapping("skills", "/SKILL.md", "skill_standard",
                                   deploy_root=".agents"),  # cross-tool dir
        "hooks": PrimitiveMapping("", "hooks.json", "codex_hooks"),
    },
    auto_create=False,
    detect_by_dir=True,
)

• Foundation (targets.py, base_integrator.py): deploy_root field, Codex in KNOWN_TARGETS, get_integration_prefixes() emits .agents/, partition_managed_files() routes cross-root paths
• Agent transform (agent_integrator.py): _write_codex_agent() — MD→TOML via format_id == "codex_agent", parsing YAML frontmatter for name/description, body as developer_instructions
• Hook merge (hook_integrator.py): integrate_package_hooks_codex() — Cursor-pattern merge into .codex/hooks.json with _apm_source markers, scripts to .codex/hooks/{pkg}/
• Skill routing (skill_integrator.py): All skill deploy paths use mapping.deploy_root or target.root_dir — Codex skills land in .agents/skills/, others unchanged
• All integrators: sync_for_target() and path computation updated for deploy_root (agent, command, instruction, prompt, skill, hook)
• Uninstall (engine.py): Deploy-root-aware sync, .agents/skills/ cleanup
• CLI: --target codex on install, compile, pack
• Docs: Integration guide, CLI reference, compilation guide, manifest schema, skills guide, CHANGELOG

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

16 new tests across 5 files (3197 total passing): target auto-detection (.codex/ yes, .agents/ alone no), dispatch gating, partition routing, MD→TOML transform, hook merge with _apm_source markers, skill deploy_root routing, security prefix validation.

[Copilot]

Pull request overview

Adds Codex CLI as a first-class APM integration target by introducing per-primitive deploy_root overrides (to support Codex's split .codex/ + .agents/ layout) and extending integrators, CLI flags, tests, and docs accordingly.

Changes:

• Introduce PrimitiveMapping.deploy_root and propagate “effective root” pathing through integrators, uninstall sync, and prefix validation/partitioning.
• Add Codex target profile and Codex-specific integrations (MD->TOML agent transform, hooks merge into .codex/hooks.json, skills routed to .agents/skills/).
• Add Codex-related tests and update CLI/docs/changelog to surface the new target.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/apm_cli/integration/targets.py	Adds deploy_root and registers the codex target; expands integration prefix allowlist.
src/apm_cli/integration/base_integrator.py	Makes managed-file partitioning deploy-root-aware (but currently misroutes some Codex paths).
src/apm_cli/integration/agent_integrator.py	Uses deploy-root-aware target roots; adds Codex MD->TOML agent writer.
src/apm_cli/integration/skill_integrator.py	Routes skills via deploy_root and extends sync cleanup to .agents/skills/.
src/apm_cli/integration/hook_integrator.py	Adds Codex hook merge + script copy support and sync cleanup for .codex/hooks.json.
src/apm_cli/integration/prompt_integrator.py	Updates sync prefix/path computation for deploy_root-aware layouts.
src/apm_cli/integration/command_integrator.py	Updates install + sync to use deploy_root-aware paths.
src/apm_cli/integration/instruction_integrator.py	Updates install + sync to use deploy_root-aware paths.
src/apm_cli/commands/uninstall/engine.py	Makes uninstall sync deploy-root-aware and checks for skill dirs under deploy_root.
src/apm_cli/commands/install.py	Adds --target codex and updates integration logging paths.
src/apm_cli/commands/compile/cli.py	Adds --target codex option (but underlying target detection/compiler logic is not yet updated).
src/apm_cli/commands/pack.py	Adds --target codex option (but pack-time target filtering/detection is not yet updated).
tests/unit/integration/test_targets.py	Adds Codex auto-detection tests.
tests/unit/integration/test_agent_integrator.py	Adds Codex agent MD->TOML transformation tests and filename expectations.
tests/unit/integration/test_hook_integrator.py	Adds Codex hook merge tests for .codex/hooks.json.
tests/unit/integration/test_skill_integrator.py	Adds tests asserting Codex skills deploy to .agents/skills/.
tests/unit/integration/test_data_driven_dispatch.py	Adds Codex dispatch gating + partition routing + prefix security tests.
docs/src/content/docs/reference/manifest-schema.md	Documents codex as a target and mentions .codex/ auto-detection.
docs/src/content/docs/reference/cli-commands.md	Updates CLI reference to include codex in command options.
docs/src/content/docs/integrations/ide-tool-integration.md	Documents Codex destinations and behavior across primitives.
docs/src/content/docs/guides/skills.md	Updates skills guide for Codex routing to .agents/skills/.
docs/src/content/docs/guides/compilation.md	Updates compilation guide to include Codex behavior.
CHANGELOG.md	Adds Unreleased entries for Codex support and deploy_root.

Comments suppressed due to low confidence (1)

src/apm_cli/integration/base_integrator.py:192

• partition_managed_files() adds hook prefixes using effective_root + '/' when mapping.subdir is empty. With Codex hooks mapped as subdir="", this makes the hook prefix ".codex/", which causes all ".codex/..." paths (including ".codex/agents/") to be bucketed under "hooks". That breaks uninstall/sync for Codex agents because AgentIntegrator.sync_for_target will get an empty managed_files subset while HookIntegrator won't delete ".codex/agents/" paths. Narrow the Codex hooks routing to only ".codex/hooks/" and ".codex/hooks.json" (or change the Codex hooks mapping to avoid an empty subdir) so ".codex/agents/*" routes to the agents_codex bucket.

                effective_root = mapping.deploy_root or target.root_dir
                prefix = f"{effective_root}/{mapping.subdir}/" if mapping.subdir else f"{effective_root}/"
                if prim_name == "skills":
                    skill_prefixes.append(prefix)
                elif prim_name == "hooks":
                    hook_prefixes.append(prefix)