diff --git a/.agents/codebase-insights.txt b/.agents/codebase-insights.txt
index ab2c7cf95..bddb734e5 100644
--- a/.agents/codebase-insights.txt
+++ b/.agents/codebase-insights.txt
@@ -31,3 +31,11 @@
 - Third-party frontend assets that were previously symlinks into `node_modules` (`@exuanbo`, `golden-layout/dist`, `monaco-editor/min`, `mousetrap`, `vex-js`, `xterm`) are now materialized from `node-modules-derivation` inside `appimagePayload`, preventing broken symlinks when the payload is copied out of the Nix store.
 - Ruby 3.3 comes from `appimageDeps` (via `pkgs.ruby_3_3`) and is patched inside the derivation, so the AppDir no longer copies Ruby from the devshell during the AppImage build.
 - `nix/packages/default.nix` now hides helper bindings like `mkNimBinary` via `builtins.removeAttrs` so `perSystem.packages` exposes only real derivations; flake checks will reject non-package values there.
+- The generated `appimagePayload` launcher (`bin/ct`) now executes `ct_unwrapped` from the same directory instead of `bin/ct_unwrapped`, fixing AppImage runs where `HERE` already points at `bin/`.
+- `ci/build/dev.sh` temporarily moves `src/links` out of the tree before `tup generate` because the generated script writes artifacts directly into `src/`, forcing a full `git clean -xfd src/` afterward.
+- The staged Tup layout now lives under `src/build/`; live `tup` runs and `just build` execute from there, and variant artifacts are produced in `src/build-debug/build/`.
+- Running a script produced by `tup generate` populates `src/build/`; clean the staging trees with `cd src/build && git clean -fx .` and `cd ../build-debug && git clean -fx .` before resuming live `tup`.
+- `!tup_preserve` only mirrors files relative to the directory containing the Tupfile; after moving Tupfiles into `src/build` we copy assets with the new `!cp_preserve` helper so files can originate from the original `src/` tree without confusing tup.
+- `!cp_preserve` replaces symlink sources with fresh links pointing at the original target (using `readlink -f`) so mirrored assets stay valid when their relative paths shift.
+- `ct_wrapper` resolves `ct_paths.json` by honouring `CODETRACER_CT_PATHS` and otherwise searching upward from both the binary location and the current working directory, so it no longer assumes the wrapper lives at a specific depth in the checkout.
+- The posix `wrapElectron` path (used when `CODETRACER_WRAP_ELECTRON=1`) now forwards `CODETRACER_ELECTRON_ARGS`, so CI overrides like `--no-sandbox` reach Electron even when we re-exec the wrapper. The Playwright launcher preserves any existing value and only appends `--no-sandbox` if it is missing, so CI scripts can layer additional flags (e.g. `--disable-gpu`).
diff --git a/.github/workflows/codetracer.yml b/.github/workflows/codetracer.yml
index 9adcba458..e98437f09 100644
--- a/.github/workflows/codetracer.yml
+++ b/.github/workflows/codetracer.yml
@@ -118,12 +118,6 @@ jobs:
           nix develop .#devShells.x86_64-linux.default --command aws --endpoint-url=${{ secrets.R2_CODETRACER_BUCKET_S3_ENDPOINT }} s3 cp CodeTracer.pub.asc s3://${{ vars.R2_CODETRACER_BUCKET_NAME }}/CodeTracer.pub.asc
   dev-build:
     runs-on: [self-hosted, nixos]
-    needs:
-      - lint-bash
-      - lint-nim
-      - lint-nix
-      - lint-rust
-      - lint-ui-tests
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -142,12 +136,6 @@ jobs:
 
   nix-build:
     runs-on: [self-hosted, nixos]
-    needs:
-      - lint-bash
-      - lint-nim
-      - lint-nix
-      - lint-rust
-      - lint-ui-tests
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -172,6 +160,11 @@ jobs:
       - lint-nix
       - lint-rust
       - lint-ui-tests
+      - test-rust
+      - test-python-recorder
+      - test-ui-tests
+      - dev-build
+      - nix-build
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -216,6 +209,11 @@ jobs:
       - lint-nix
       - lint-rust
       - lint-ui-tests
+      - test-rust
+      - test-python-recorder
+      - test-ui-tests
+      - dev-build
+      - nix-build
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -310,11 +308,6 @@ jobs:
 
   test-rust:
     runs-on: [self-hosted, nixos]
-    needs:
-      - dev-build
-      - nix-build
-      - appimage-build
-      - dmg-build
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -333,11 +326,6 @@ jobs:
 
   test-python-recorder:
     runs-on: [self-hosted, nixos]
-    needs:
-      - dev-build
-      - nix-build
-      - appimage-build
-      - dmg-build
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -356,11 +344,6 @@ jobs:
 
   test-ui-tests:
     runs-on: [self-hosted, nixos]
-    needs:
-      - dev-build
-      - nix-build
-      - appimage-build
-      - dmg-build
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -380,9 +363,6 @@ jobs:
   push-to-cachix:
     runs-on: [self-hosted, nixos]
     needs:
-      - test-rust
-      - test-python-recorder
-      - test-ui-tests
       - appimage-lib-check
       - dmg-lib-check
     if: "github.ref == 'refs/heads/main' && ${{ !github.event.codetracer-ci }}"
diff --git a/0006-tup-build-staging-area.md b/0006-tup-build-staging-area.md
new file mode 100644
index 000000000..e6b91889c
--- /dev/null
+++ b/0006-tup-build-staging-area.md
@@ -0,0 +1,57 @@
+# ADR 0006: Stage Tup Builds Under `src/build`
+
+- **Status:** Proposed
+- **Date:** 2025-10-21
+- **Deciders:** Codetracer Build & Tooling Maintainers
+- **Consulted:** Desktop Packaging, CI & Release Engineering, Developer Experience
+- **Informed:** Runtime Leads, Support, Product Management
+
+## Context
+
+The `tup` build root currently lives directly under `src/`, with `Tupfile`, `Tuprules.tup`, and a constellation of subordinate `Tupfile`s spread across the source tree. This layout works when `tup` runs in FUSE mode, but `tup generate` emits shell scripts whose commands write artifacts (executables in `bin/`, JS bundles, copied resources, etc.) straight into the source tree. CI (`ci/build/dev.sh`) therefore jumps through hoops—temporarily moving `src/links`, running `git clean -xfd src/`, and manually restoring symlinks—to keep the repository tidy. Developers face the same issue when they need the generated script for environments where FUSE is unavailable.
+
+We tried `tup generate --builddir …` to sandbox the outputs, but the option is too buggy for our workload (incorrect relative paths and missing variant awareness). As a result, the source directory accumulates transient build files, complicating `git status`, forcing frequent cleans, and making it risky to script `tup.sh` execution inside packaging or CI jobs.
+
+## Decision
+
+We will move the entire Tup configuration into a dedicated staging area at `src/build/`, so that both `tup` FUSE runs and generated scripts create or modify files only inside that subtree while still producing the expected variant outputs (`build-debug/`, etc.).
+
+1. **Establish `src/build/` as the staging tree:** Relocate the root `Tupfile` and every subordinate `Tupfile` under a mirrored directory structure rooted at `src/build/`, while keeping `Tupfile.ini` anchored in `src/` so the Tup root remains the project root. The staged layout becomes the canonical entry point—invocations now run from `src/build/` without requiring a compatibility shim in `src/Tupfile`. Each rule references sources in `../` (or higher) as needed, but outputs and intermediate files stay under `src/build/` by default.
+2. **Stable path conventions via `SRC_DIR`:** Each staged `Tupfile` declares its own source root with a local `SRC_DIR` variable. This per-file approach is sufficient for the refactor and avoids introducing additional global macros.
+3. **Git hygiene:** Add a scoped `.gitignore` inside `src/build/` that admits `tup.sh`, generated metadata (`*.tup` state, temporary outputs), and any new staging directories while keeping declarative build files tracked.
+4. **Tooling alignment:** Update `ci/build/dev.sh`, `justfile`, and shell/Nix helpers to invoke `tup` from `src/build/`. The CI clean step focuses on `src/build/` and `src/build-debug/build/`, and hacks that relocate `src/links` become unnecessary.
+5. **Documentation & onboarding:** Refresh contributor docs to explain the new layout, clarifying that FUSE-based workflows (`tup monitor`) operate inside `src/build/`, while `tup build-debug` and generated scripts populate `src/build-debug/build/`. Highlight that `tup generate` writes into the staging tree and document the clean-up sequence required before running the live `tup` monitor again (`cd src/build && git clean -fx .`, followed by `cd ../build-debug && git clean -fx .`).
+
+## Alternatives Considered
+
+- **Continue using `tup generate` in `src/`:** Rejected; it keeps polluting the source tree and forces manual hygiene steps that are easy to forget.
+- **Rely on `tup generate --builddir`:** Rejected because upstream bugs break our rules (incorrect include paths and missing variant-specific outputs).
+- **Wrap `tup.sh` in custom sandboxing scripts:** Adds maintenance overhead without addressing the root problem that the Tup metadata lives inside the source tree.
+
+## Consequences
+
+- **Positive:** Generated scripts run cleanly without polluting tracked files; CI simplifications; consistent developer experience across environments lacking FUSE; easier to inspect or purge build artifacts via `git clean src/build` and `git clean src/build-debug/build`.
+- **Neutral/Enabling:** Establishes clearer separation between declarative build metadata and source assets, paving the way for additional variants or build caching under `src/build/`.
+- **Negative:** Requires refactoring every `Tupfile` path to account for the new root; risk of path mistakes during migration; temporary churn for developers with pending Tup changes. Running a generated script will populate `src/build/`; developers must clean both `src/build/` and `src/build-debug/` before resuming normal `tup` usage.
+- **Risks & Mitigations:** Misconfigured outputs could still escape the sandbox—mitigate by adding integration tests that run `tup generate` + `tup.sh` and assert the set of touched paths. Variant parity must be verified by running `tup build-debug` before and after the move within CI. Document the clean-up sequence after generated runs to avoid confusing residual artifacts.
+
+## Key Locations
+
+- `src/Tupfile`, `src/Tuprules.tup`, and all `src/**/Tupfile` instances that define the current build graph.
+- `ci/build/dev.sh`, `justfile`, and `nix/shells/*.nix` scripts that `cd src` before invoking `tup`.
+- `src/build-debug/tup.config` and any logic that depends on variant output directories.
+- Documentation under `docs/` and contributor guides describing the build workflow.
+
+## Implementation Notes
+
+1. Mirror the existing Tup hierarchy under `src/build/`, keeping directory-by-directory `Tupfile`s collocated with their rules while adjusting relative paths for inputs and outputs; retain `src/Tupfile.ini` at the root and run `tup` directly from `src/build/`.
+2. Keep per-directory `SRC_DIR` variables to reference the original sources without introducing additional macros.
+3. Create a `.gitignore` within `src/build/` that ignores generated scripts, logs, and `tup` state directories but keeps the committed `Tupfile`s tracked.
+4. Update tooling (`ci`, `just`, Nix shells) to execute `tup` from `src/build/`, ensuring variant commands still find `build-debug/tup.config` and write outputs to `src/build-debug/build/`.
+5. Add CI coverage that runs both `tup generate` + generated script and `tup build-debug` to confirm artifacts remain confined to `src/build/` and `src/build-debug/build/`, and document the clean-up requirement after generated runs.
+
+## Status & Next Steps
+
+- Draft ADR for review (this document).
+- Prototype the directory move on a feature branch to validate the staged layout, confirm both `tup` and `tup generate` succeed, and measure the clean-up workflow required after generated runs.
+- Once validated, mark this ADR **Accepted**, land the staging refactor, update the documentation (including the post-`tup.sh` cleaning steps), and complete the implementation plan alongside automated regression coverage.
diff --git a/ci/build/dev.sh b/ci/build/dev.sh
index 052290a21..8a2d30e48 100755
--- a/ci/build/dev.sh
+++ b/ci/build/dev.sh
@@ -15,11 +15,8 @@ echo '##########################################################################
 # stop processes: make sure none of those processes left from last build
 stop_processes
 
-git clean -xfd src/build-debug
-
-mv src/links links
-git clean -xfd src/
-mv links src/links
+git clean -fdx src/build
+git clean -fdx src/build-debug/build
 
 echo '###############################################################################'
 echo "Build:"
@@ -34,10 +31,3 @@ TUP_OUTPUT_SCRIPT=tup-generated-build-once.sh
 tup generate --config build-debug/tup.config "$TUP_OUTPUT_SCRIPT"
 ./"$TUP_OUTPUT_SCRIPT"
 rm "$TUP_OUTPUT_SCRIPT"
-
-# TODO: this is not really working, problems with variants: generated script produce
-#   files directly in src/, instead of in src/build-debug, and so it can't run well
-#   we need to see if we can generate it in a better way, or to wrap/restructure the resulting folders
-#   to make possible to test the dev build in CI
-
-popd
diff --git a/ci/test/python-recorder-smoke.sh b/ci/test/python-recorder-smoke.sh
index 76b1c9145..3576a21a0 100755
--- a/ci/test/python-recorder-smoke.sh
+++ b/ci/test/python-recorder-smoke.sh
@@ -11,7 +11,7 @@ echo '##########################################################################
 
 nix develop .#devShells.x86_64-linux.default --command ./ci/build/dev.sh
 
-CT_BIN="${ROOT_DIR}/src/bin/ct"
+CT_BIN="${ROOT_DIR}/src/build/bin/ct"
 if [[ ! -x "${CT_BIN}" ]]; then
   echo "error: ${CT_BIN} not found after build"
   exit 1
diff --git a/ci/test/ui-tests.sh b/ci/test/ui-tests.sh
index 2bca6ccb2..d2e14bd12 100755
--- a/ci/test/ui-tests.sh
+++ b/ci/test/ui-tests.sh
@@ -6,9 +6,7 @@ echo '##########################################################################
 echo 'Running ui e2e playwright tests'
 echo '###############################################################################'
 
-# TODO: maybe pass the result from the build stage as artifact to this job?
-# TODO: tup generate seems problematic with variants: we need to fix/change the resulting dirs to work correctly
-# ./ci/build/dev.sh
+./ci/build/dev.sh
 
 # trying to make it work with the nix build, instead of the tup build:
 
@@ -25,10 +23,22 @@ echo '##########################################################################
 
 # ./ci/build/nix.sh
 
-# CODETRACER_E2E_CT_PATH="$(pwd)/result/bin/ct"
-# export CODETRACER_E2E_CT_PATH
+CODETRACER_E2E_CT_PATH="$(pwd)/src/build/bin/ct"
+LINKS_PATH_DIR="$(pwd)/src/build"
+NIX_CODETRACER_EXE_DIR="$(pwd)/src/build"
+CODETRACER_LINKS_PATH="$(pwd)/src/build"
+CODETRACER_ELECTRON_ARGS="--no-sandbox --disable-gpu"
 
-# pushd ui-tests
-# nix develop --command ./ci.sh
+export CODETRACER_E2E_CT_PATH
+export LINKS_PATH_DIR
+export NIX_CODETRACER_EXE_DIR
+export CODETRACER_LINKS_PATH
+export CODETRACER_ELECTRON_ARGS
 
-# popd
+pushd ui-tests
+nix develop --command ./ci.sh
+
+popd
+
+git clean -fx ./src/build
+git clean -fx ./src/build-debug
diff --git a/docs/a.md b/docs/a.md
index 26e7e3ff9..7db374d82 100644
--- a/docs/a.md
+++ b/docs/a.md
@@ -8,7 +8,7 @@
 ### Local
 
 I sometimes do 
-`set -gx PATH /home/al/codetracer/src/build-debug $PATH`
+`set -gx PATH /home/al/codetracer/src/build-debug/build $PATH`
 to get many codetracer-related binaries in my path: `codetracer`, `tester` and maybe others
 
 # Fix preloading
@@ -83,4 +83,3 @@ to get many codetracer-related binaries in my path: `codetracer`, `tester` and m
 
 
 
-
diff --git a/docs/book/src/installation.md b/docs/book/src/installation.md
index 6b00b69a9..9f32de75d 100644
--- a/docs/book/src/installation.md
+++ b/docs/book/src/installation.md
@@ -62,9 +62,12 @@ Direnv should be set up in your shell, as shown [here](https://direnv.net/docs/h
    ```
 4. Run `nix develop`
 5. Run `direnv allow`
-6. To build codetracer simply run `just build`. The location of the resulting binary will be `./src/build-debug/bin/ct`
+6. To build codetracer simply run `just build`. The location of the resulting binary will be `./src/build-debug/build/bin/ct`
 7. Now every time you enter the `codetracer` directory your environment should be updated
 
+> [!NOTE]
+> When you need to use `tup generate`, remember that the generated script writes into the staging tree. After it finishes, run `cd src/build && git clean -fx .` followed by `cd ../build-debug && git clean -fx .` before invoking `tup` again.
+
 > [!TIP]
 > Users of Visual Studio Code might encounter issues when using `code .`. To fix them do the following:
 > 1. Run `direnv deny`
diff --git a/docs/tests.md b/docs/tests.md
index 443c0b161..e043e8818 100644
--- a/docs/tests.md
+++ b/docs/tests.md
@@ -21,6 +21,6 @@ we can save the steps in a file by passing `--file`, instead of running those au
 Running:
 
 ```bash
-src/build-debug/tests/run/a_test <traceID>
-src/build-debug/tests/run/a_test examples/sum.nim
+src/build-debug/build/tests/run/a_test <traceID>
+src/build-debug/build/tests/run/a_test examples/sum.nim
 ```
diff --git a/justfile b/justfile
index e1dfb62fb..cf636aa38 100644
--- a/justfile
+++ b/justfile
@@ -17,7 +17,7 @@ build:
   cd src
   tup build-debug
   tup monitor -a
-  cd ../
+  cd ..
 
   # start webpack
   node_modules/.bin/webpack --watch --progress & # building frontend_bundle.js
@@ -32,7 +32,7 @@ build-once:
   # We have to make the dist directory here, because it's missing on a fresh check out
   # It will be created by the webpack command below, but we have an a chicken and egg
   # problem because the Tupfiles refer to it.
-  mkdir public/dist
+  mkdir -p src/public/dist
 
   cd src
   tup build-debug
@@ -45,6 +45,7 @@ build-once:
   # that tup will discover
   cd src
   tup build-debug
+  cd ..
 
 build-docs:
   #!/usr/bin/env bash
@@ -103,7 +104,7 @@ build-macos-app:
 build-app-image:
   ./appimage-scripts/build_appimage.sh
 
-tester := "src/build-debug/bin/tester"
+tester := "src/build-debug/build/bin/tester"
 
 test-ui headless="0":
   #!/usr/bin/env bash
@@ -197,7 +198,7 @@ tail pid_or_current_or_last kind process="default" instance_index="0":
   tail -f ${log_file_path}
 
 build-nix:
-  nix build --print-build-logs '.?submodules=1#codetracer' --show-trace --keep-failed
+  nix build --print-build-logs '.#codetracer' --show-trace --keep-failed
 
 cachix-push-nix-package:
   cachix push metacraft-labs-codetracer $(nix build --print-out-paths ".?submodules=1#codetracer")
@@ -215,7 +216,7 @@ pid pid_or_current_or_last:
   #!/usr/bin/env bash
   # argument can be either `current`, `last` or a pid number
   if [[ "{{pid_or_current_or_last}}" == "current" ]]; then \
-    echo $(ps aux | grep src/build-debug/codetracer | head -n 1 | awk '{print $2}') ; \
+    echo $(ps aux | grep src/build-debug/build | head -n 1 | awk '{print $2}') ; \
   elif [[ "{{pid_or_current_or_last}}" == "last" ]]; then \
     TTMP=$(just findtmp) ; \
     echo $(cat $TTMP/last-start-pid) ; \
diff --git a/nix/shells/armShell.nix b/nix/shells/armShell.nix
index 4fb400b24..eb752cb8a 100644
--- a/nix/shells/armShell.nix
+++ b/nix/shells/armShell.nix
@@ -197,7 +197,7 @@ mkShell {
 
     # ====
 
-    export CODETRACER_LINKS_PATH=$PWD/src/build-debug/
+    export CODETRACER_LINKS_PATH=$PWD/src/build-debug/build
 
     echo "{\"PYTHONPATH\": \"$CT_PYTHONPATH\",\"LD_LIBRARY_PATH\":\"$CT_LD_LIBRARY_PATH\"}" > ct_paths.json
 
@@ -244,10 +244,10 @@ mkShell {
     rm -rf $ROOT_PATH/node_modules
     ln -s $NIX_NODE_PATH $ROOT_PATH/node_modules
 
-    export NIX_CODETRACER_EXE_DIR=$ROOT_PATH/src/build-debug/
-    export LINKS_PATH_DIR=$ROOT_PATH/src/build-debug/
+    export NIX_CODETRACER_EXE_DIR=$ROOT_PATH/src/build-debug/build
+    export LINKS_PATH_DIR=$ROOT_PATH/src/build-debug/build
     export CODETRACER_REPO_ROOT_PATH=$ROOT_PATH
-    export PATH=$PATH:$PWD/src/build-debug/bin
+    export PATH=$PWD/src/build/bin:$PWD/src/build-debug/build/bin:$PATH
     export PATH=$PATH:$ROOT_PATH/node_modules/.bin/
     export CODETRACER_DEV_TOOLS=1
     export CODETRACER_LOG_LEVEL=INFO
diff --git a/nix/shells/main.nix b/nix/shells/main.nix
index 9918d1329..c2c01ab34 100644
--- a/nix/shells/main.nix
+++ b/nix/shells/main.nix
@@ -220,7 +220,7 @@ mkShell {
 
     # ====
 
-    export CODETRACER_LINKS_PATH=$PWD/src/build-debug/
+    export CODETRACER_LINKS_PATH=$PWD/src/build-debug/build
 
     echo "{\"PYTHONPATH\": \"$CT_PYTHONPATH\",\"LD_LIBRARY_PATH\":\"$CT_LD_LIBRARY_PATH\"}" > ct_paths.json
 
@@ -276,10 +276,10 @@ mkShell {
     rm -rf $ROOT_PATH/node_modules
     ln -s $NIX_NODE_PATH $ROOT_PATH/node_modules
 
-    export NIX_CODETRACER_EXE_DIR=$ROOT_PATH/src/build-debug/
-    export LINKS_PATH_DIR=$ROOT_PATH/src/build-debug/
+    export NIX_CODETRACER_EXE_DIR=$ROOT_PATH/src/build-debug/build
+    export LINKS_PATH_DIR=$ROOT_PATH/src/build-debug/build
     export CODETRACER_REPO_ROOT_PATH=$ROOT_PATH
-    export PATH=$PWD/src/build-debug/bin:$PATH
+    export PATH=$PWD/src/build-debug/build/bin:$PATH
     export PATH=$ROOT_PATH/node_modules/.bin/:$PATH
     export CODETRACER_DEV_TOOLS=0
     export CODETRACER_LOG_LEVEL=INFO
diff --git a/non-nix-build/env.sh b/non-nix-build/env.sh
index 6e4d4de22..ac2d5bbd0 100755
--- a/non-nix-build/env.sh
+++ b/non-nix-build/env.sh
@@ -49,7 +49,7 @@ if [ ! -f "$ROOT_DIR"/ct_paths.json ]; then
   echo "{\"PYTHONPATH\": \"\",\"LD_LIBRARY_PATH\":\"\"}" > "$ROOT_DIR"/ct_paths.json
 fi
 
-export PATH=$DEPS_DIR/nim/bin:$ROOT_DIR/node_modules/.bin:$BIN_DIR:$CARGO_HOME/bin:$ROOT_DIR/src/build-debug/bin:$PATH
+export PATH=$DEPS_DIR/nim/bin:$ROOT_DIR/node_modules/.bin:$BIN_DIR:$CARGO_HOME/bin:$ROOT_DIR/src/build/bin:$ROOT_DIR/src/build-debug/build/bin:$PATH
 
 if [ "$os" == "mac" ]; then
   brew install sqlite3 ruby node universal-ctags go capnp
diff --git a/src/Tupfile b/src/Tupfile
deleted file mode 100644
index 4bb1f5f16..000000000
--- a/src/Tupfile
+++ /dev/null
@@ -1,40 +0,0 @@
-include_rules
-
-# JS build
-: frontend/index.nim |> !nim_node_index |> index.js | index.js.map
-: frontend/subwindow.nim |> !nim_node_subwindow |> subwindow.js | subwindow.js.map
-: frontend/index.nim |> !nim_node_index_server |> server_index.js | server_index.js.map
-: frontend/ui_js.nim |> !nim_js |> ui.js
-# : frontend/browsersync_serv.nim |> !nim_node |> browsersync_serv.js
-# : frontend/codetracer_shell.nim |> !codetracer_shell |> bin/codetracer_shell.js
-
-# TODO : helpers.ts |> !ts |> helpers.js
-: helpers.js |> !tup_preserve |> helpers.js
-
-: index.js |> cp %f %o |> src/index.js
-: subwindow.js |> cp %f %o |> src/subwindow.js
-: ui.js |> cp %f %o |> public/ui.js
-: helpers.js |> cp %f %o |> src/helpers.js
-
-# preserve
-# : links/trace.rb |> !tup_preserve |> src/trace.rb
-
-: links/codetracer-pure-ruby-recorder |> !tup_preserve |> bin/codetracer-pure-ruby-recorder
-
-: links/recorder.rb |> !tup_preserve |> src/recorder.rb
-: links/trace.py |> !tup_preserve |> src/trace.py
-: links/bash |> !tup_preserve |> bin/bash
-: links/node |> !tup_preserve |> bin/node
-: links/ruby |> !tup_preserve |> bin/ruby
-: links/nargo |> !tup_preserve |> bin/nargo
-: links/wazero |> !tup_preserve |> bin/wazero
-: links/ctags |> !tup_preserve |> bin/ctags
-: links/electron |> !tup_preserve |> bin/electron
-# : links/unzip |> !tup_preserve |> bin/unzip
-# : links/zip |> !tup_preserve |> bin/zip
-: links/curl |> !tup_preserve |> bin/curl
-: foreach *.json *.yaml   |> !tup_preserve |>
-: frontend/index.html |> !tup_preserve |> index.html
-: frontend/subwindow.html |> !tup_preserve |> subwindow.html
-: config/default_layout.json |> !tup_preserve |> config/default_layout.json
-: config/default_config.yaml |> !tup_preserve |> config/default_config.yaml
diff --git a/src/backend-manager/Tupfile b/src/backend-manager/Tupfile
deleted file mode 100644
index 46f0ad292..000000000
--- a/src/backend-manager/Tupfile
+++ /dev/null
@@ -1,3 +0,0 @@
-include_rules
-
-: |> !rust_cargo_backend_manager |> ../bin/backend-manager
diff --git a/src/build/.gitignore b/src/build/.gitignore
new file mode 100644
index 000000000..c9926ceb3
--- /dev/null
+++ b/src/build/.gitignore
@@ -0,0 +1,14 @@
+#
+# Ignore everything in this directory and its subdirectories except for
+# files that are part of the Tup build configuration. The double-asterisk
+# patterns allow Tup metadata to be tracked no matter where the files live.
+#
+*
+!*/
+!.gitignore
+!**/Tupfile
+!**/Tupfile.lua
+!**/Tupconfig
+!**/Tuprules.tup
+!**/tup.config
+.tup/
diff --git a/src/build/Tupfile b/src/build/Tupfile
new file mode 100644
index 000000000..2ef462aba
--- /dev/null
+++ b/src/build/Tupfile
@@ -0,0 +1,42 @@
+include_rules
+
+SRC_DIR = ..
+
+# JS build
+: $(SRC_DIR)/frontend/index.nim |> !nim_node_index |> index.js | index.js.map
+: $(SRC_DIR)/frontend/subwindow.nim |> !nim_node_subwindow |> subwindow.js | subwindow.js.map
+: $(SRC_DIR)/frontend/index.nim |> !nim_node_index_server |> server_index.js | server_index.js.map
+: $(SRC_DIR)/frontend/ui_js.nim |> !nim_js |> ui.js
+# : frontend/browsersync_serv.nim |> !nim_node |> browsersync_serv.js
+# : frontend/codetracer_shell.nim |> !codetracer_shell |> bin/codetracer_shell.js
+
+# TODO : helpers.ts |> !ts |> helpers.js
+: $(SRC_DIR)/helpers.js |> !cp_preserve |> helpers.js
+
+: index.js |> cp %f %o |> src/index.js
+: subwindow.js |> cp %f %o |> src/subwindow.js
+: ui.js |> cp %f %o |> public/ui.js
+: helpers.js |> cp %f %o |> src/helpers.js
+
+# preserve
+# : links/trace.rb |> !tup_preserve |> src/trace.rb
+
+: $(SRC_DIR)/links/codetracer-pure-ruby-recorder |> !cp_preserve |> bin/codetracer-pure-ruby-recorder
+
+: $(SRC_DIR)/links/recorder.rb |> !cp_preserve |> src/recorder.rb
+: $(SRC_DIR)/links/trace.py |> !cp_preserve |> src/trace.py
+: $(SRC_DIR)/links/bash |> !cp_preserve |> bin/bash
+: $(SRC_DIR)/links/node |> !cp_preserve |> bin/node
+: $(SRC_DIR)/links/ruby |> !cp_preserve |> bin/ruby
+: $(SRC_DIR)/links/nargo |> !cp_preserve |> bin/nargo
+: $(SRC_DIR)/links/wazero |> !cp_preserve |> bin/wazero
+: $(SRC_DIR)/links/ctags |> !cp_preserve |> bin/ctags
+: $(SRC_DIR)/links/electron |> !cp_preserve |> bin/electron
+# : links/unzip |> !tup_preserve |> bin/unzip
+# : links/zip |> !tup_preserve |> bin/zip
+: $(SRC_DIR)/links/curl |> !cp_preserve |> bin/curl
+: foreach $(SRC_DIR)/*.json $(SRC_DIR)/*.yaml   |> !cp_preserve |> %b
+: $(SRC_DIR)/frontend/index.html |> !cp_preserve |> index.html
+: $(SRC_DIR)/frontend/subwindow.html |> !cp_preserve |> subwindow.html
+: $(SRC_DIR)/config/default_layout.json |> !cp_preserve |> config/default_layout.json
+: $(SRC_DIR)/config/default_config.yaml |> !cp_preserve |> config/default_config.yaml
diff --git a/src/Tuprules.tup b/src/build/Tuprules.tup
similarity index 88%
rename from src/Tuprules.tup
rename to src/build/Tuprules.tup
index 64e9b9523..293cc52cc 100644
--- a/src/Tuprules.tup
+++ b/src/build/Tuprules.tup
@@ -46,6 +46,15 @@ STYLUS = stylus
 
 # misc rules
 !cp = |> ^ %f^ cp %f %o |>
+!cp_preserve = |> DIR=`dirname %o`; \
+  mkdir -p "$DIR" && \
+  rm -rf %o && \
+  if [ -L %f ]; then \
+    TARGET=`readlink -f %f 2>/dev/null || readlink %f`; \
+    ln -s "$TARGET" %o; \
+  else \
+    cp -a %f %o; \
+  fi |>
 !stylus = |> ^ %f^ $(STYLUS) %f -o %o |>
 # workaround for errors, file seems to be still generated
 !ts = |> ^ %f^ $(TSC) %f |> %o
@@ -153,21 +162,21 @@ export RUSTUP_HOME
 
 !rust_cargo_backend_manager = |> \
   CARGO_TARGET_DIR=/tmp/codetracer/backend_manager_target \
-    cargo build --release && \
+    cargo build --release --manifest-path %f && \
     cp /tmp/codetracer/backend_manager_target/release/backend-manager %o |> %o
 !debug_rust_cargo_db_backend = |> \
   CARGO_TARGET_DIR=/tmp/codetracer/db_backend_target \
-    cargo build && \
+    cargo build --manifest-path %f && \
     cp /tmp/codetracer/db_backend_target/debug/db-backend %o |> %o
 !rust_cargo_db_backend = |> \
   CARGO_TARGET_DIR=/tmp/codetracer/db_backend_target \
-    cargo build --release && \
+    cargo build --release --manifest-path %f && \
     cp /tmp/codetracer/db_backend_target/release/db-backend %o |> %o
 !rust_cargo_virtualization_layers = |> \
   CARGO_TARGET_DIR=/tmp/codetracer/virtualization_layers_target \
-    cargo build --release && \
+    cargo build --release --manifest-path %f && \
     cp /tmp/codetracer/virtualization_layers_target/release/virtualization-layers %o |> %o
 !rust_cargo_small_lang = |> \
   CARGO_TARGET_DIR=/tmp/codetracer/small_lang_target \
-    cargo build --release && \
+    cargo build --release --manifest-path %f && \
     cp /tmp/codetracer/small_lang_target/release/small-lang %o |> %o
diff --git a/src/build/backend-manager/Tupfile b/src/build/backend-manager/Tupfile
new file mode 100644
index 000000000..f6d5d1565
--- /dev/null
+++ b/src/build/backend-manager/Tupfile
@@ -0,0 +1,5 @@
+SRC_DIR = ../../backend-manager
+
+include_rules
+
+: $(SRC_DIR)/Cargo.toml |> !rust_cargo_backend_manager |> ../bin/backend-manager
diff --git a/src/build/ct/Tupfile b/src/build/ct/Tupfile
new file mode 100644
index 000000000..33dc4dfed
--- /dev/null
+++ b/src/build/ct/Tupfile
@@ -0,0 +1,9 @@
+SRC_DIR = ../../ct
+
+include_rules
+
+: $(SRC_DIR)/codetracer.nim |> !codetracer |> ../bin/codetracer_depending_on_env_vars_in_tup
+: $(SRC_DIR)/ct_wrapper.nim |> !nim_c |> ../bin/ct
+# TODO think if we want explicitly both
+# : $(SRC_DIR)/ct_wrapper.nim |> !nim_c |> ../bin/codetracer
+: $(SRC_DIR)/db_backend_record.nim |> !codetracer |> ../bin/db-backend-record
diff --git a/src/db-backend/Tupfile b/src/build/db-backend/Tupfile
similarity index 66%
rename from src/db-backend/Tupfile
rename to src/build/db-backend/Tupfile
index 6c70f945e..472849f89 100644
--- a/src/db-backend/Tupfile
+++ b/src/build/db-backend/Tupfile
@@ -1,6 +1,8 @@
+SRC_DIR = ../../db-backend
+
 include_rules
 
-: src/main.rs |> !debug_rust_cargo_db_backend |> ../bin/db-backend
+: $(SRC_DIR)/Cargo.toml |> !debug_rust_cargo_db_backend |> ../bin/db-backend
 # required for now only for system lang backend
 # for now not needed for db-backend
 # : src/bin/virtualization-layers.rs |> !rust_cargo_virtualization_layers |> ../bin/virtualization-layers
diff --git a/src/db-backend/tree-sitter-trace/Tupfile b/src/build/db-backend/tree-sitter-trace/Tupfile
similarity index 81%
rename from src/db-backend/tree-sitter-trace/Tupfile
rename to src/build/db-backend/tree-sitter-trace/Tupfile
index 10373c458..36635a140 100644
--- a/src/db-backend/tree-sitter-trace/Tupfile
+++ b/src/build/db-backend/tree-sitter-trace/Tupfile
@@ -1,3 +1,5 @@
+SRC_DIR = ../../../db-backend/tree-sitter-trace
+
 include_rules
 
 # TODO: make tup build work
diff --git a/src/build/frontend/styles/Tupfile b/src/build/frontend/styles/Tupfile
new file mode 100644
index 000000000..76e1642f0
--- /dev/null
+++ b/src/build/frontend/styles/Tupfile
@@ -0,0 +1,15 @@
+SRC_DIR = ../../../frontend/styles
+
+include_rules
+
+# workaround if css does not build:
+# css
+# comment uncomment the line below and comment out everything else
+# save the file, let tup work its magic and after that return the file to previous state
+#: foreach *.styl |> !stylus |>
+
+: $(SRC_DIR)/default_white_theme.styl |> !stylus |> default_white_theme.css
+: $(SRC_DIR)/default_dark_theme_electron.styl |> !stylus |> default_dark_theme_electron.css
+: $(SRC_DIR)/default_dark_theme_extension.styl |> !stylus |> default_dark_theme_extension.css
+: $(SRC_DIR)/loader.styl |> !stylus |> loader.css
+: $(SRC_DIR)/subwindow.styl |> !stylus |> subwindow.css
diff --git a/src/build/public/Tupfile b/src/build/public/Tupfile
new file mode 100644
index 000000000..7095c1a9d
--- /dev/null
+++ b/src/build/public/Tupfile
@@ -0,0 +1,16 @@
+include_rules
+SRC_DIR = ../../public
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
+: foreach $(SRC_DIR)/third_party/wnumb-1.2.0/*.js |> !cp_preserve |> third_party/wnumb-1.2.0/%b
+: foreach $(SRC_DIR)/resources/window/*.svg |> !cp_preserve |> resources/window/%b
+: foreach $(SRC_DIR)/resources/notifications/*.svg |> !cp_preserve |> resources/notifications/%b
+: foreach $(SRC_DIR)/third_party/bootstrap-4.3.1-dist/css/*.css |> !cp_preserve |> third_party/bootstrap-4.3.1-dist/css/%b
+: $(SRC_DIR)/third_party/tippy.js/tippy.css |> !cp_preserve |> third_party/tippy.js/tippy.css
+: $(SRC_DIR)/third_party/monaco-editor/min |> !cp_preserve |> third_party/monaco-editor/min
+: $(SRC_DIR)/third_party/@exuanbo |> !cp_preserve |> third_party/@exuanbo
+: $(SRC_DIR)/third_party/golden-layout/dist |> !cp_preserve |> third_party/golden-layout/dist
+: $(SRC_DIR)/third_party/mousetrap |> !cp_preserve |> third_party/mousetrap
+: $(SRC_DIR)/third_party/vex-js |> !cp_preserve |> third_party/vex-js
+: $(SRC_DIR)/third_party/xterm |> !cp_preserve |> third_party/xterm
+: foreach $(SRC_DIR)/dist/* |> !cp_preserve |> dist/%b
diff --git a/src/build/public/resources/Tupfile b/src/build/public/resources/Tupfile
new file mode 100644
index 000000000..cda47eb85
--- /dev/null
+++ b/src/build/public/resources/Tupfile
@@ -0,0 +1,8 @@
+include_rules
+
+SRC_DIR = ../../../public/resources
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
+: foreach $(SRC_DIR)/welcome/*.svg |> !cp_preserve |> welcome/%b
+: foreach $(SRC_DIR)/jstree/*.png |> !cp_preserve |> jstree/%b
+: foreach $(SRC_DIR)/jstree/*.gif |> !cp_preserve |> jstree/%b
diff --git a/src/build/public/resources/calltrace/Tupfile b/src/build/public/resources/calltrace/Tupfile
new file mode 100644
index 000000000..b59378338
--- /dev/null
+++ b/src/build/public/resources/calltrace/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/calltrace
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/debug/Tupfile b/src/build/public/resources/debug/Tupfile
new file mode 100644
index 000000000..aab4892f3
--- /dev/null
+++ b/src/build/public/resources/debug/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/debug
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/fonts/Tupfile b/src/build/public/resources/fonts/Tupfile
new file mode 100644
index 000000000..a7dff4322
--- /dev/null
+++ b/src/build/public/resources/fonts/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/fonts
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/fonts/fira_code/Tupfile b/src/build/public/resources/fonts/fira_code/Tupfile
new file mode 100644
index 000000000..8b803a220
--- /dev/null
+++ b/src/build/public/resources/fonts/fira_code/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../../public/resources/fonts/fira_code
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/fonts/space_grotesk/Tupfile b/src/build/public/resources/fonts/space_grotesk/Tupfile
new file mode 100644
index 000000000..c4ea5d0c8
--- /dev/null
+++ b/src/build/public/resources/fonts/space_grotesk/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../../public/resources/fonts/space_grotesk
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/menu/Tupfile b/src/build/public/resources/menu/Tupfile
new file mode 100644
index 000000000..4162d58f0
--- /dev/null
+++ b/src/build/public/resources/menu/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/menu
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/shared/Tupfile b/src/build/public/resources/shared/Tupfile
new file mode 100644
index 000000000..a3a9e4a2f
--- /dev/null
+++ b/src/build/public/resources/shared/Tupfile
@@ -0,0 +1,6 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/shared
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
+: foreach $(SRC_DIR)/filesystem/*.svg |> !cp_preserve |> filesystem/%b
diff --git a/src/build/public/resources/shell/Tupfile b/src/build/public/resources/shell/Tupfile
new file mode 100644
index 000000000..2bbc849f0
--- /dev/null
+++ b/src/build/public/resources/shell/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/shell
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/resources/tracepoints/Tupfile b/src/build/public/resources/tracepoints/Tupfile
new file mode 100644
index 000000000..d16470b83
--- /dev/null
+++ b/src/build/public/resources/tracepoints/Tupfile
@@ -0,0 +1,5 @@
+include_rules
+
+SRC_DIR = ../../../../public/resources/tracepoints
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/public/third_party/Tupfile b/src/build/public/third_party/Tupfile
new file mode 100644
index 000000000..1ff4e4096
--- /dev/null
+++ b/src/build/public/third_party/Tupfile
@@ -0,0 +1,4 @@
+include_rules
+SRC_DIR = ../../../public/third_party
+
+: foreach $(SRC_DIR)/*.* |> !cp_preserve |> %b
diff --git a/src/build/small-lang/Tupfile b/src/build/small-lang/Tupfile
new file mode 100644
index 000000000..903fe3c1c
--- /dev/null
+++ b/src/build/small-lang/Tupfile
@@ -0,0 +1,5 @@
+SRC_DIR = ../../small-lang
+
+include_rules
+
+: $(SRC_DIR)/Cargo.toml |> !rust_cargo_small_lang |> ../bin/small-lang
diff --git a/src/build/tester/Tupfile b/src/build/tester/Tupfile
new file mode 100644
index 000000000..090b1e140
--- /dev/null
+++ b/src/build/tester/Tupfile
@@ -0,0 +1,5 @@
+SRC_DIR = ../../tester
+
+include_rules
+
+: $(SRC_DIR)/tester.nim |> !nim_tester |> ../bin/tester
diff --git a/src/build/tui/Tupfile b/src/build/tui/Tupfile
new file mode 100644
index 000000000..655736e4a
--- /dev/null
+++ b/src/build/tui/Tupfile
@@ -0,0 +1,5 @@
+SRC_DIR = &(src_root)/tui
+
+include_rules
+
+#: $(SRC_DIR)/src/main.rs |> !rust_cargo_tui |> ../bin/tui
diff --git a/src/ct/Tupfile b/src/ct/Tupfile
deleted file mode 100644
index 01fc81991..000000000
--- a/src/ct/Tupfile
+++ /dev/null
@@ -1,7 +0,0 @@
-include_rules
-
-: codetracer.nim |> !codetracer |> ../bin/codetracer_depending_on_env_vars_in_tup
-: ct_wrapper.nim |> !nim_c |> ../bin/ct
-# TODO think if we want explicitly both
-# : ct_wrapper.nim |> !nim_c |> ../bin/codetracer
-: db_backend_record.nim |> !codetracer |> ../bin/db-backend-record
diff --git a/src/ct/ct_wrapper.nim b/src/ct/ct_wrapper.nim
index 4bb7e26dd..5ceec7267 100644
--- a/src/ct/ct_wrapper.nim
+++ b/src/ct/ct_wrapper.nim
@@ -1,5 +1,5 @@
 import
-  std / [os, osproc, strformat, strtabs, posix, posix_utils],
+  std / [os, osproc, strformat, strtabs, posix],
   json_serialization, json_serialization / std / tables
 
 type
@@ -9,18 +9,81 @@ type
     # LD_LIBRARY_PATH: string
     # PYTHONPATH: string
 
+const
+  pathsConfigFile = "ct_paths.json"
+  missingConfigHint = "Try setting CODETRACER_CT_PATHS explicitly or run `direnv allow` inside the codetracer source folder."
+
+proc searchForConfig(startDirs: seq[string]): tuple[path: string, attempts: seq[string]] =
+  ## Walk each directory in `startDirs` upwards until the filesystem root
+  ## looking for `ct_paths.json`. Returns the first hit as well as the list
+  ## of paths that were examined.
+  var attempts: seq[string] = @[]
+
+  for dir in startDirs:
+    if dir.len == 0:
+      continue
+
+    var cursor: string
+    try:
+      cursor = dir.absolutePath()
+    except OSError:
+      continue
+
+    while true:
+      let candidate = cursor / pathsConfigFile
+      if candidate notin attempts:
+        attempts.add(candidate)
+        if fileExists(candidate):
+          return (candidate, attempts)
+
+      let parent = cursor.parentDir
+      if parent.len == 0 or parent == cursor:
+        break
+      cursor = parent
+
+  return ("", attempts)
+
+proc locatePathsConfig(): string =
+  ## Resolve the location of `ct_paths.json`. Honour an explicit
+  ## CODETRACER_CT_PATHS override first; otherwise search upwards from
+  ## both the executable's directory and the current working directory.
+  let envCandidate = getEnv("CODETRACER_CT_PATHS")
+  if envCandidate.len > 0:
+    if fileExists(envCandidate):
+      return envCandidate
+    raise newException(IOError,
+      fmt"CODETRACER_CT_PATHS points at '{envCandidate}', but the file does not exist.")
+
+  var searchRoots: seq[string] = @[]
+  let appDir = getAppDir()
+  if appDir.len > 0:
+    searchRoots.add(appDir)
+
+  try:
+    let currentDir = getCurrentDir()
+    if currentDir.len > 0 and currentDir notin searchRoots:
+      searchRoots.add(currentDir)
+  except OSError:
+    discard
+
+  let (discovered, attempts) = searchForConfig(searchRoots)
+  if discovered.len > 0:
+    return discovered
+
+  var message = "expected a paths config generated by shell.nix, but could not find ct_paths.json.\n"
+  if attempts.len > 0:
+    message.add("Looked in:\n")
+    for candidate in attempts:
+      message.add("  " & candidate & "\n")
+  message.add(missingConfigHint)
+  raise newException(IOError, message)
+
 var ctProcess: Process = nil
 
 proc start(args: seq[string]) =
-  let configPath = getEnv(
-    "CODETRACER_CT_PATHS",
-    getAppDir().parentDir.parentDir.parentDir / "ct_paths.json")
-  if not existsFile(configPath):
-    echo fmt"error: expected a paths config generated by shell.nix in {configPath}:"
-    echo "  please try to go in the codetracer source folder and run `direnv allow` there"
-    quit(1)
-
+  var configPath = ""
   try:
+    configPath = locatePathsConfig()
     var config = Json.decode(readFile(configPath), PathsConfig)
     var env = newStringTable(modeStyleInsensitive)
     for name, value in envPairs():
@@ -51,7 +114,8 @@ proc start(args: seq[string]) =
     quit(waitForExit(ctProcess))
   except:
     echo "ct helper error: ", getCurrentExceptionMsg()
-    echo "  ct paths config path: ", configPath
+    if configPath.len > 0:
+      echo "  ct paths config path: ", configPath
     quit(1)
 
 onSignal(SIGTERM):
@@ -65,4 +129,3 @@ onSignal(SIGINT):
     quit(128 + SIGINT)
 
 start(commandLineParams())
-
diff --git a/src/ct/launch/electron.nim b/src/ct/launch/electron.nim
index 89c6e82bd..970363cf3 100644
--- a/src/ct/launch/electron.nim
+++ b/src/ct/launch/electron.nim
@@ -89,24 +89,33 @@ when defined(posix):
 
   proc wrapElectron*(args: seq[string]) =
     let startIndex = getEnv("CODETRACER_START_INDEX", "") == "1"
+    # Preserve custom Electron CLI overrides (e.g. --no-sandbox for CI environments).
+    let optionalElectronArgs = getEnv("CODETRACER_ELECTRON_ARGS", "").splitWhitespace()
 
     # internal ct runs should be normal, not wrapping electron again
     putEnv("CODETRACER_WRAP_ELECTRON", "")
     putEnv("CODETRACER_START_INDEX", "")
 
-    let execvArgsCount = if startIndex: args.len + 2 else: args.len + 1
+    let totalArgs = args.len + optionalElectronArgs.len
+    let execvArgsCount = if startIndex: totalArgs + 2 else: totalArgs + 1
 
     # copied and adapted from nim forum: nucky9 and Araq:
     #   https://forum.nim-lang.org/t/7415#47044
     var execvArgs = cast[cstringArray](alloc0((execvArgsCount + 1) * sizeof(cstring)))
     execvArgs[0] = electronExe.cstring
-    for i, arg in args:
-      execvArgs[i + 1] = arg.cstring
+    var argIndex = 1
+    for arg in args:
+      execvArgs[argIndex] = arg.cstring
+      inc argIndex
+    for arg in optionalElectronArgs:
+      execvArgs[argIndex] = arg.cstring
+      inc argIndex
 
     if startIndex:
-      execvArgs[execvArgsCount - 1] = electronIndexPath.cstring
+      execvArgs[argIndex] = electronIndexPath.cstring
+      inc argIndex
 
-    execvArgs[execvArgsCount] = nil
+    execvArgs[argIndex] = nil
 
     discard execv(
       electronExe.cstring,
diff --git a/src/db-backend/editor-config/emacs/init.el b/src/db-backend/editor-config/emacs/init.el
index 4b48020ff..db553ef30 100644
--- a/src/db-backend/editor-config/emacs/init.el
+++ b/src/db-backend/editor-config/emacs/init.el
@@ -30,7 +30,7 @@
 (dap-register-debug-provider
  "rust"
  (lambda (conf)
-   (plist-put conf :dap-server-path "/home/alexander92/codetracer/src/build-debug/bin/db-backend")
+   (plist-put conf :dap-server-path "/home/alexander92/codetracer/src/build-debug/build/bin/db-backend")
    conf))
 
 (dap-register-debug-template "CodeTracer db-backend rust"
@@ -40,4 +40,4 @@
                                    :traceFolder "/home/alexander92/.local/share/codetracer/trace-414/"
                                    :name "CodeTracer db-backend rust"))
 
-(toggle-debug-on-error)
\ No newline at end of file
+(toggle-debug-on-error)
diff --git a/src/frontend/styles/Tupfile b/src/frontend/styles/Tupfile
deleted file mode 100644
index 56ff28603..000000000
--- a/src/frontend/styles/Tupfile
+++ /dev/null
@@ -1,13 +0,0 @@
-include_rules
-
-# workaround if css does not build:
-# css
-# comment uncomment the line below and comment out everything else
-# save the file, let tup work its magic and after that return the file to previous state
-#: foreach *.styl |> !stylus |>
-
-: default_white_theme.styl |> !stylus |> default_white_theme.css
-: default_dark_theme_electron.styl |> !stylus |> default_dark_theme_electron.css
-: default_dark_theme_extension.styl |> !stylus |> default_dark_theme_extension.css
-: loader.styl |> !stylus |> loader.css
-: subwindow.styl |> !stylus |> subwindow.css
diff --git a/src/public/Tupfile b/src/public/Tupfile
deleted file mode 100644
index aed061b61..000000000
--- a/src/public/Tupfile
+++ /dev/null
@@ -1,14 +0,0 @@
-: foreach *.* |> !tup_preserve |>
-: foreach third_party/wnumb-1.2.0/*.js |> !tup_preserve |> %f
-: foreach resources/window/*.svg |> !tup_preserve |> %f
-: foreach resources/notifications/*.svg |> !tup_preserve |> %f
-: foreach third_party/bootstrap-4.3.1-dist/css/*.css |> !tup_preserve |> %f
-: third_party/tippy.js/tippy.css |> !tup_preserve |> %f
-: third_party/monaco-editor/min |> !tup_preserve |> %f
-: third_party/@exuanbo |> !tup_preserve |> %f
-: third_party/golden-layout/dist |> !tup_preserve |> %f
-: third_party/mousetrap |> !tup_preserve |> %f
-: third_party/vex-js |> !tup_preserve |> %f
-: third_party/xterm |> !tup_preserve |> %f
-: foreach dist/* |> !tup_preserve |> %f
-
diff --git a/src/public/resources/Tupfile b/src/public/resources/Tupfile
deleted file mode 100644
index 4b7bb77eb..000000000
--- a/src/public/resources/Tupfile
+++ /dev/null
@@ -1,5 +0,0 @@
-: foreach *.* |> !tup_preserve |>
-: foreach welcome/*.svg |> !tup_preserve |> %f
-: foreach jstree/*.png |> !tup_preserve |> %f
-: foreach jstree/*.gif |> !tup_preserve |> %f
-
diff --git a/src/public/resources/calltrace/Tupfile b/src/public/resources/calltrace/Tupfile
deleted file mode 100644
index 4cd39ee24..000000000
--- a/src/public/resources/calltrace/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
\ No newline at end of file
diff --git a/src/public/resources/debug/Tupfile b/src/public/resources/debug/Tupfile
deleted file mode 100644
index 56d2f95e5..000000000
--- a/src/public/resources/debug/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
diff --git a/src/public/resources/fonts/Tupfile b/src/public/resources/fonts/Tupfile
deleted file mode 100644
index 4cd39ee24..000000000
--- a/src/public/resources/fonts/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
\ No newline at end of file
diff --git a/src/public/resources/fonts/fira_code/Tupfile b/src/public/resources/fonts/fira_code/Tupfile
deleted file mode 100644
index 4cd39ee24..000000000
--- a/src/public/resources/fonts/fira_code/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
\ No newline at end of file
diff --git a/src/public/resources/fonts/space_grotesk/Tupfile b/src/public/resources/fonts/space_grotesk/Tupfile
deleted file mode 100644
index 4cd39ee24..000000000
--- a/src/public/resources/fonts/space_grotesk/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
\ No newline at end of file
diff --git a/src/public/resources/menu/Tupfile b/src/public/resources/menu/Tupfile
deleted file mode 100644
index 56d2f95e5..000000000
--- a/src/public/resources/menu/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
diff --git a/src/public/resources/shared/Tupfile b/src/public/resources/shared/Tupfile
deleted file mode 100644
index 3ea128581..000000000
--- a/src/public/resources/shared/Tupfile
+++ /dev/null
@@ -1,2 +0,0 @@
-: foreach *.* |> !tup_preserve |>
-: foreach filesystem/*.svg |> !tup_preserve |> %f
diff --git a/src/public/resources/shell/Tupfile b/src/public/resources/shell/Tupfile
deleted file mode 100644
index 56d2f95e5..000000000
--- a/src/public/resources/shell/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
diff --git a/src/public/resources/tracepoints/Tupfile b/src/public/resources/tracepoints/Tupfile
deleted file mode 100644
index 56d2f95e5..000000000
--- a/src/public/resources/tracepoints/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
diff --git a/src/public/third_party/Tupfile b/src/public/third_party/Tupfile
deleted file mode 100644
index 56d2f95e5..000000000
--- a/src/public/third_party/Tupfile
+++ /dev/null
@@ -1 +0,0 @@
-: foreach *.* |> !tup_preserve |>
diff --git a/src/small-lang/Tupfile b/src/small-lang/Tupfile
deleted file mode 100644
index b7be9a6ac..000000000
--- a/src/small-lang/Tupfile
+++ /dev/null
@@ -1,3 +0,0 @@
-include_rules
-
-: src/main.rs |> !rust_cargo_small_lang |> ../bin/small-lang
diff --git a/src/tester/Tupfile b/src/tester/Tupfile
deleted file mode 100644
index e5c7516d9..000000000
--- a/src/tester/Tupfile
+++ /dev/null
@@ -1,3 +0,0 @@
-include_rules
-
-: tester.nim |> !nim_tester |> ../bin/tester
diff --git a/src/tui/Tupfile b/src/tui/Tupfile
deleted file mode 100644
index 6deaa3fd3..000000000
--- a/src/tui/Tupfile
+++ /dev/null
@@ -1,3 +0,0 @@
-include_rules
-
-#: src/main.rs |> !rust_cargo_tui |> ../bin/tui
diff --git a/tup-build-staging-implementation-plan.md b/tup-build-staging-implementation-plan.md
new file mode 100644
index 000000000..3d9e37339
--- /dev/null
+++ b/tup-build-staging-implementation-plan.md
@@ -0,0 +1,70 @@
+# Tup Build Staging Refactor – Implementation Plan
+
+This plan tracks the work required to implement ADR 0006 (“Stage Tup Builds Under `src/build`”).
+
+---
+
+## Part 1 – Establish the `src/build/` Tup Root
+
+1. **Create the staging layout**
+   - Add `src/build/` with placeholders for every directory that currently hosts a `Tupfile`.
+   - Move the root `Tupfile` and each subordinate `Tupfile` into the mirrored locations (e.g., `src/build/frontend/Tupfile`), leaving `Tupfile.ini` anchored at the project root and keeping `Tuprules.tup` wherever is most practical.
+   - Ensure the Git history retains only the relocated files (remove the old copies rather than duplicating them). `tup` now runs directly from `src/build/`, so no compatibility shim in `src/Tupfile` is required.
+
+2. **Shared path configuration**
+   - Retain per-file `SRC_DIR` variables for referencing source directories; no additional global macros (`SRC_ROOT`, `BUILD_ROOT`, `VARIANT_ROOT`) are necessary.
+   - Review staged Tupfiles to confirm outputs route into the staging tree using the existing `SRC_DIR` pattern.
+
+3. **Output confinement**
+   - Ensure commands emit intermediate and final outputs into `src/build/` (for live runs) or `src/build-debug/build/` (for variant builds) instead of the source tree.
+   - Confirm resource-copy rules (`!cp_preserve`, etc.) still put assets in the expected staging paths and that downstream consumers read from the new locations.
+
+## Part 2 – Preserve Variant Behaviour
+
+1. **Variant path wiring**
+   - Audit references to `build-debug` (and other variant directories) to ensure they resolve relative to the new staging root.
+   - Update scripts or rules that assume the old `src/build-debug/bin` layout so they target `src/build-debug/build/**` instead.
+
+2. **Regression tests**
+   - Run `tup build-debug` in the new layout and compare the directory structure of `src/build-debug/` against a baseline (focus on executables in `bin/`, JS bundles, and resource copies).
+   - Capture discrepancies and update rules until parity is achieved; ensure the `build-debug/build` subtree contains the expected artifacts.
+
+3. **Generated script validation**
+   - Run `tup generate tup.sh` inside `src/build/`, execute the script, and confirm the outputs stay within the staging area (`src/build/`) and `src/build-debug/build/`.
+   - Document the required clean-up before returning to the live monitor: `cd src/build && git clean -fx .` followed by `cd ../build-debug && git clean -fx .`.
+   - Add automated checks (e.g., a CI script diffing `git status`) to prevent regressions.
+
+## Part 3 – Tooling & Automation Updates
+
+1. **CI adjustments**
+   - Simplify `ci/build/dev.sh` to operate entirely within `src/build/`, removing the temporary `src/links` relocation and limiting cleanups to `src/build/` and `src/build-debug/build/`.
+   - Update any other CI jobs that run `tup` or expect artifacts in `src/`, including the post-`tup.sh` cleaning sequence.
+
+2. **Developer workflows**
+   - Modify `justfile` recipes, Nix shell hooks (`nix/shells/main.nix`, `armShell.nix`), and helper scripts so they `cd src/build` before invoking `tup` and expect outputs in `src/build-debug/build/`.
+   - Double-check that commands such as `tup monitor -a` behave identically in the new location after cleaning.
+
+3. **Git hygiene**
+   - Add `src/build/.gitignore` to ignore generated scripts, `.tup` state directories, and transient outputs while keeping committed `Tupfile`s tracked.
+   - Remove any obsolete ignore rules from the repository root (e.g., `tup-generate.vardict`) if the new layout changes artefact names or locations.
+
+## Part 4 – Documentation & Follow-Up
+
+1. **Contributor docs**
+   - Update build instructions (`README.md`, `docs/book`, onboarding guides) to reference `src/build/` as the entry point for `tup` workflows.
+   - Highlight the difference between the staging area (`src/build/`) and variant outputs (`src/build-debug/build/`) to avoid confusion.
+   - Document the clean-up sequence required after running a generated script so developers can return to live `tup` runs without residual artifacts.
+
+2. **Knowledge base**
+   - Refresh `.agents/codebase-insights.txt` (and any other internal notes) to capture the new layout.
+
+3. **Post-migration cleanup**
+   - Remove temporary workarounds that are no longer necessary (e.g., scripts assuming outputs land in `src/` or `src/build-debug/bin`).
+   - Monitor developer feedback during the first few sprints and adjust documentation or supporting scripts as needed.
+
+---
+
+**Milestones**
+1. Land the directory move and macro updates (Part 1) with passing `tup build-debug`.
+2. Validate generated scripts and CI pipelines (Part 2 & Part 3).
+3. Finish documentation and cleanup tasks (Part 4), then mark ADR 0006 as **Accepted**.
diff --git a/tup-build-staging-status.md b/tup-build-staging-status.md
new file mode 100644
index 000000000..82cf0424b
--- /dev/null
+++ b/tup-build-staging-status.md
@@ -0,0 +1,12 @@
+# Tup Build Staging Refactor – Status
+
+## Completed
+- Relocated the entire Tup graph to `src/build/`, with `Tupfile.ini` still rooted in `src/`; `tup` now runs directly from the staging tree and no `src/Tupfile` shim is needed.
+- Standardized on per-file `SRC_DIR` handling for relocated Tupfiles, added `!cp_preserve` plus `src/build/.gitignore`, and refreshed `.agents/codebase-insights.txt`; no further Tupfile edits are planned.
+- Validated the build: both `tup` and `tup generate` succeed, `just build` / `just build-once` work end-to-end, and their outputs land under `src/build/` or `src/build-debug/build/` as intended.
+- Aligned developer tooling (Just recipes, CI helpers, Nix shells, non-Nix env scripts) and documentation—including contributor guides, mdBook outputs, and WebDriver specs—with the `src/build/` staging root and the new `build-debug/build` artifact paths, and documented the required clean-up after running generated scripts.
+- Confirmed the updated workflows by exercising the key entry points (`tup build`, `tup build-debug`, `tup generate` + generated script, `just build`, `just build-once`) after the clean-up procedure; no regressions observed.
+
+## Next
+- Mark ADR 0006 as **Accepted**, close out this implementation plan, and communicate the finalized workflow (including the `tup generate` clean-up) to the wider team.
+- Monitor for feedback over the next sprint and decide whether additional automation is needed to enforce the post-`tup.sh` cleaning steps.
diff --git a/ui-tests/Helpers/PlayrwightLauncher.cs b/ui-tests/Helpers/PlayrwightLauncher.cs
index ca24a9e66..6e4872b56 100644
--- a/ui-tests/Helpers/PlayrwightLauncher.cs
+++ b/ui-tests/Helpers/PlayrwightLauncher.cs
@@ -1,3 +1,4 @@
+using System;
 using System.Diagnostics;
 using Microsoft.Playwright;
 using UiTests.Helpers;
@@ -55,6 +56,14 @@ public static async Task<IBrowser> LaunchAsync(string programRelativePath)
         info.EnvironmentVariables.Add("CODETRACER_TEST", "1");
         info.EnvironmentVariables.Add("CODETRACER_WRAP_ELECTRON", "1");
         info.EnvironmentVariables.Add("CODETRACER_START_INDEX", "1");
+        const string electronArgsKey = "CODETRACER_ELECTRON_ARGS";
+        var existingElectronArgs = info.EnvironmentVariables[electronArgsKey];
+        var sanitizedElectronArgs = string.IsNullOrWhiteSpace(existingElectronArgs)
+            ? "--no-sandbox"
+            : existingElectronArgs.Contains("--no-sandbox", StringComparison.Ordinal)
+                ? existingElectronArgs
+                : $"{existingElectronArgs} --no-sandbox";
+        info.EnvironmentVariables[electronArgsKey] = sanitizedElectronArgs;
         // info.EnvironmentVariables.Add("CODETRACER_DEV_TOOLS", "");
 
         var process = Process.Start(info)!;
@@ -103,4 +112,4 @@ public static async Task<IPage> GetAppPageAsync(IBrowser browser, string? titleC
             throw new TimeoutException("Could not find app page (non-DevTools) after connecting playwright.");
         }
     }
-}
\ No newline at end of file
+}
diff --git a/wdio.conf.js b/wdio.conf.js
index b1de32082..1a2308390 100644
--- a/wdio.conf.js
+++ b/wdio.conf.js
@@ -14,10 +14,10 @@ const config = {
     [
       'electron',
       {
-        // appPath: 'node_modules/.bin/', // join(__dirname, 'src/build-debug/dist'),
+        // appPath: 'node_modules/.bin/', // join(__dirname, 'src/build-debug/build/dist'),
         // appName: 'electron',
         binaryPath: join(__dirname, 'node_modules', '.bin', 'electron'),
-        appArgs: ['app=src/build-debug'],
+        appArgs: ['app=src/build-debug/build'],
         chromedriver: {
           port: 9519,
           logFileName: 'wdio-chromedriver.log',
@@ -36,7 +36,7 @@ const config = {
   logLevel: 'debug',
   runner: 'local',
   outputDir: 'wdio-logs',
-  specs: ['./src/build-debug/tests/dom_test.js'],
+  specs: ['./src/build-debug/build/tests/dom_test.js'],
 
   // framework: 'mocha',
   // mochaOpts: {