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:

Check	Windows	macOS	Linux
Git	https://git-scm.com	Xcode CLT / brew	distro package
CMake ≥ 3.22	https://cmake.org	brew install cmake	distro package
Node ≥ 18	https://nodejs.org	brew install node	distro / nvm
Python ≥ 3.8	python.org (not Store stub)	system / brew	distro
VS C++	VS 2022 Build Tools	—	—
Xcode CLT	—	xcode-select --install	—
g++/clang	—	—	build-essential
WebView2	Evergreen Runtime	WKWebView (system)	WebKitGTK + libegl-dev
JUCE ≥ 9	submodule	submodule	submodule

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:

Profile	plan	design	impl	ship
Quality	strongest	strong	strong	economy
Balanced (default)	strongest	strong	strong	economy
Budget	mid	mid	mid	economy

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.