[2026-10-15] eagle: personal/projects/balda/execution-broker.md personal/projects/balda/setup.md work/projects/vscode-migration/tech-design-xcode-build-server.md work/projects/vscode-migration/xcode-build-server.md

work/projects/vscode-migration/tech-design-xcode-build-server.md

@@ -31,11 +31,10 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 
 **What a developer gets**
 - Completion, jump-to-definition, references and live errors for app, test and package code, on macOS or iOS. One platform is chosen per worktree and can be switched.
-- Tasks to build any scheme and run unit tests; errors and failed tests show in the Problems panel.
+- Tasks to build any scheme and run unit tests; errors and failed tests show in the Problems panel. launch.json/tasks.json aren‘t committed.
 - Debugging with breakpoints:
   - the macOS app, launched from the editor;
-  - the iOS app on a simulator, by running the app and then attaching.
-- **Shared with Xcode.** Builds and the index live in the worktree's usual Xcode DerivedData folder. Whatever Xcode built or indexed is ready in VS Code, and the other way round.
+  - the iOS app on a simulator: one launch builds, installs and starts the app, and attaches the debugger.
 - Optional background indexing of worktrees while no editor is open.
 
 **How it works**
@@ -43,13 +42,13 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 - Builds and tests go through `xcodebuild` with the same settings Xcode uses.
 - The build server is installed locally by a script that builds it from source at a pinned commit of our fork (see below).
 
-**The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so we'll offer them upstream. We don't depend on upstream accepting them: we fork the build server into a DuckDuckGo repository, keep our changes there and pull upstream changes manually after reviewing them.
+**The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so we'll open a PR for the upstream. We don't depend on upstream accepting them: we fork the build server into a DuckDuckGo repository, keep our changes there and pull upstream changes manually after reviewing them.
 
 **Steps**
 1. Fork sourcekit-xcode-bsp into a DuckDuckGo repository with our changes.
 2. Land the setup in the repository, plus a short README.
 3. Offer the changes upstream as PRs.
-4. A few early adopters on macOS and iOS try it for a couple of weeks; then we decide whether to announce it more widely.
+4. Document the setup in the [Apple Documentation](https://app.asana.com/1/137249556945/project/1202500774821704/list/1203980668089483) project and in the onboarding docs.
 
 ### Pros
 
@@ -57,14 +56,13 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 - **Same build as Xcode.** swift-build reads the projects, so per-configuration settings and dependencies, resources, macros and plugins behave like in Xcode.
 - **Nothing to maintain in the app code.** No lint rules or checks to keep the setup working.
 - **Both platforms**, so it doesn't add a gap between macOS and iOS.
-- **No cost for Xcode users**, and those who use both tools share one build and one index.
+- **No cost for Xcode users.** Builds and the index live in the worktree's usual Xcode DerivedData folder, so those who use both tools share one build and one index: whatever Xcode built or indexed is ready in VS Code, and the other way round.
 
 ### Cons
 
 - **A young third-party tool** (version 0.1.0, "early-stage" by its authors) that we fork and maintain ourselves.
 - **Some rough edges:**
   - one platform per worktree at a time;
-  - iOS debugging is two steps (run, then attach);
   - the first index of a new worktree takes ~5 minutes.
 - **Someone has to own it.** I will; the setup is small (a workspace file and ~6 scripts), and it's documented.
 - **Maintenance as Xcode, swift-build and the build server move.** Xcode updates or upstream changes can need updates to the fork or the setup. Mitigation: the people who use the setup do the updates, mostly with AI agents (the setup is small and has a README and tests). Xcode-only users and CI never depend on it.