APC Setup (/apc-setup)

Trigger: /apc-setup · /setup (deprecated alias) · "set up Audio Plugin Coder"

Model preference: economy / cheap (routing only). Read apc.config.json → models.phases.setup if present.

Goal

Walk the user through a complete, cross-platform first-run configuration and write apc.config.json. Do not start a plugin phase.

Preconditions

1. Workspace is an APC checkout (CMakeLists.txt, scripts/, apc.config.example.json).
2. Detect OS: Windows → PowerShell; macOS/Linux → Bash.

Idempotency

If apc.config.json exists and setup.completed is true, ask the user to choose:

1. Re-check only — run system-check, report results
2. Change paths — update paths.* only
3. Change models — update models.* only (including optional Codex orchestration toggle)
4. Full wizard — redo all steps (confirm before overwriting paths)

Never silently overwrite custom paths.

Wizard steps

1. Welcome

Explain APC briefly and that this configures the framework (not a plugin).

2. Prerequisites

Run system-check:

• Windows: .\scripts\system-check.ps1 -Human
• macOS/Linux: bash scripts/system-check.sh --human

For each failing check, give install guidance:

Re-run checks until critical tools pass (or user explicitly continues with warnings).

3. Submodules / tools

git submodule update --init --recursive

git submodule update --init --recursive

Confirm _tools/JUCE major ≥ 9 via system-check. Ask whether Visage UI support is desired (defaults.enable_visage).

4. Path layout

Ask (defaults recommended for first-time users):

1. Keep plugins/, build/, release/ inside the repo? Yes (recommended) / customize
2. If custom plugins path: absolute or relative to the repo root (e.g. ../apc_plugins); create directory if missing. Scripts and APC workflows resolve via Get-ApcPluginPath / apc_plugin_path — a junction/symlink at ./plugins is optional (legacy convenience only).
3. Custom build path (e.g. ../apc_builds): warn against OneDrive/Dropbox/iCloud
4. Custom release path for installers/zips (e.g. ../apc_releases; default release/)

Relative paths are resolved from the APC repo root. Absolute paths are also supported.

5. UI framework default

Ask preferred default for new plugins: webview (recommended) or visage. Store in defaults.ui_framework_preference.

6. AI model routing (global)

Offer presets, then allow per-phase overrides:

Ask the user for concrete model IDs they can use in their agent (do not invent vendor-specific IDs they did not confirm). Store under models.phases.*.

Remind: many hosts cannot auto-switch models; APC will announce the preferred model at phase start.

6b. Codex cost-aware CLI routing (optional)

Ask whether the user wants Codex CLI cost-aware orchestration (Luna → Terra → Sol → Astra). This is off by default and only relevant if they use Codex CLI / ChatGPT-authenticated codex exec. Cursor, Claude Code, and Kilo users can skip.

If Yes:

1. Confirm Codex CLI is installed (codex on PATH). If missing, point to OpenAI Codex install docs and continue with a warning.
2. Prefer ChatGPT sign-in (codex login), not an API key, when staying on Plus/plan allowance.
3. When writing config, pass --enable-codex / -EnableCodexOrchestration so models.codex.enabled = true.
   • The models.codex block is already in apc.config.example.json and is merged automatically — users do not hand-copy JSON.
4. Ask optionally: enable build/test escalation (--enable-codex-escalation / -EnableCodexEscalation)?
5. Install named profiles into the user Codex home (automatic when orchestration is enabled, or via scripts/codex/install-profiles.ps1 / .sh).
6. Point to docs/codex-orchestration.md for the runner (scripts/codex/apc-codex-run).

If No: leave models.codex.enabled = false (block still present from the example for later opt-in).

7. Verify

1. Write apc.config.json (from answers; start from / merge with apc.config.example.json)
2. Re-run system-check
3. Optional smoke: configure CMake only into the configured build dir with -DAPC_PLUGINS_DIR=...
4. Set setup.completed = true, setup.completed_at, setup.platform

Helper scripts (prefer these over hand-writing JSON when possible):

• Windows: .\scripts\apc-write-config.ps1 (supports -EnableCodexOrchestration, -EnableCodexEscalation, -InstallCodexProfiles)
• macOS/Linux: bash scripts/apc-write-config.sh (supports --enable-codex, --enable-codex-escalation, --install-codex-profiles)
• Or edit JSON carefully with the path helpers in scripts/lib/Get-ApcPaths.ps1

8. Summary

Print:

• Resolved plugins / build / release paths
• JUCE major
• Model profile
• Codex orchestration on/off (and whether profiles were installed)
• Next command: /apc-dream <PluginName>

Stop. Do not run dream.

Soft gate for other phases

If another APC phase runs while setup.completed is false, warn once and offer /apc-setup, but do not hard-block power users who already have a working toolchain.