| name | apc-setup |
| description | Guided first-run APC setup — toolchain, paths, models, JUCE verification. Trigger with /apc-setup or natural language "set up APC". |
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
- Workspace is an APC checkout (
CMakeLists.txt, scripts/, apc.config.example.json).
- Detect OS: Windows → PowerShell; macOS/Linux → Bash.
Idempotency
If apc.config.json exists and setup.completed is true, ask the user to choose:
- Re-check only — run system-check, report results
- Change paths — update
paths.* only
- Change models — update
models.* only
- 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):
- Keep
plugins/, build/, release/ inside the repo? Yes (recommended) / customize
- 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).
- Custom build path (e.g.
../apc_builds): warn against OneDrive/Dropbox/iCloud
- 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.
7. Verify
- Write
apc.config.json (from answers; start from apc.config.example.json)
- Re-run system-check
- Optional smoke: configure CMake only into the configured build dir with
-DAPC_PLUGINS_DIR=...
- 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 (see script help)
- 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
- 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.
