release-train: staging -> main

.github/workflows/add-to-kanban.yml

@@ -9,8 +9,84 @@ on:
 jobs:
   add-to-project:
     runs-on: ubuntu-latest
+    # NO GITHUB_TOKEN AT ALL (saadqbal, #2181). Every call in this job authenticates
+    # as the App, so the workflow token needs nothing -- and an empty grant is the
+    # only version of that claim a reader can check. Free, and it means the least-
+    # privilege story covers both credentials in the job rather than just the loud one.
+    permissions: {}
     steps:
+      # Board writes authenticate as the tracebloc-release-train App (backend#2036),
+      # not a human's PAT. `owner:` yields an ORG-scoped installation token; a
+      # repo-scoped one cannot write the org project. No fallback to the PAT: a
+      # fallback would let a broken App path keep working silently.
+      #
+      # This workflow also fires on DEPENDABOT PRs, which GitHub gates on a separate
+      # secret scope -- both app secrets are set there too, or Dependabot PRs would
+      # stop reaching the board with `Input required and not supplied`.
+      - name: Mint an installation token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.RELEASE_TRAIN_APP_ID }}
+          private-key: ${{ secrets.RELEASE_TRAIN_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          # SCOPED TO THIS REPO, or the two reads below land org-wide (saadqbal,
+          # #2181). `owner:` alone does not narrow anything -- run 32239403796 says
+          # so in as many words: "Input 'repositories' is not set. Creating token for
+          # all repositories owned by tracebloc." A token calling itself
+          # least-privilege while carrying issue+PR read across all 19 installed
+          # repos is the claim this PR exists to stop making.
+          #
+          # `organization_projects` is an ORG-level permission and is not affected by
+          # repo scoping, so the board write should be unchanged -- but that is an
+          # assumption, and it is the same class of assumption that broke the first
+          # attempt, so the verification run is what settles it rather than this
+          # comment. If it is wrong the failure is LOUD (see below), which is what
+          # makes trying it cheap.
+          repositories: ${{ github.event.repository.name }}
+          # Least privilege (backend#2166): without any `permission-*` the token
+          # carries the App's FULL installation grant. actions/add-to-project needs
+          # THREE scopes, not one: it must RESOLVE the triggering issue/PR node
+          # before it can add it to the board, so it needs read on both content
+          # types (this workflow fires on `issues` and `pull_request`) in addition
+          # to the project write. Projects-write alone leaves the node unresolvable
+          # -- the add fails with "Could not resolve to a node with the global id".
+          #
+          # WHAT IS ACTUALLY DEMONSTRATED, and what is not. Stated narrowly because
+          # two earlier versions of this paragraph each overclaimed in a different
+          # direction, and this text is copied verbatim into 17 repos -- a wrong
+          # argument here is a wrong argument 17 times, in a byte-compared file
+          # nobody re-derives.
+          #
+          # DEMONSTRATED: a MISSING READ scope fails loudly. Run 32239403796 on this
+          # branch, at commit 218f0b13 (projects-write only), errored with
+          # `Could not resolve to a node with the global id` and the job went RED --
+          # `add-to-project` routes GraphQL errors through `setFailed`.
+          #
+          # NOT DEMONSTRATED: the case the FIRST version of this comment described --
+          # the token resolving the node fine and then 403ing the BOARD WRITE. No run
+          # has ever produced it. So "fails loudly" is proven for the read scopes and
+          # is an expectation, not a measurement, for the write.
+          #
+          # AND ONE RUN THAT LOOKED LIKE EVIDENCE IS NOT (aptracebloc). The previous
+          # wording cited run 32237283072 as a second scope failure. It is not one:
+          # it ran on `develop`, whose file at that sha passes NO `permission-*` at
+          # all (the App's full grant), and it failed on
+          # `Could not resolve to a node with the global id of I_kwDONNfQt88...` --
+          # a node a fully-privileged token also cannot see, i.e. an issue that no
+          # longer exists (this workflow fires on `issues: transferred`). Run
+          # 32237067262, the SAME develop sha, succeeded 2m34s earlier. A dead node,
+          # not a permission.
+          #
+          # The proof this is right is therefore still a LANDED CARD, not a passing
+          # mint: a mint can succeed with a scope the board write then needs and
+          # lacks, and that is the one path nothing here has exercised.
+          permission-issues: read
+          permission-pull-requests: read
+          permission-organization-projects: write
+
       - uses: actions/add-to-project@5afcf98fcd03f1c2f92c3c83f58ae24323cc57fd # v2.0.0
         with:
           project-url: https://github.com/orgs/tracebloc/projects/2
-          github-token: ${{ secrets.PROJECTS_KANBAN_TOKEN }}
+          github-token: ${{ steps.app-token.outputs.token }}
+

environment-setup/configuration.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Configuration"
 description: "Customize your tracebloc workspace — environment variables, cluster management, GPU support, and manual Helm deployment."
 ---
 
 The installer uses sensible defaults; this page covers what you can change.
@@ -43,7 +43,7 @@
 
 ### View logs
 
 The jobs manager is the main tracebloc process. Check its logs when debugging connectivity or job execution issues:
 
 ```bash
 kubectl logs -n <workspace> -l app=manager
@@ -71,7 +71,7 @@
 
 Fully automatic. The installer:
 
 1. Detects NVIDIA GPUs via `nvidia-smi` or `lspci`
 2. Installs drivers if missing (Ubuntu, RHEL/CentOS, Arch)
 3. Installs the NVIDIA Container Toolkit and configures Docker
 4. Deploys the NVIDIA k8s device plugin into the cluster
@@ -81,11 +81,11 @@
 
 ### AMD (Linux)
 
 Auto-detected. ROCm is installed automatically on Ubuntu and RHEL/CentOS. A logout/login may be needed for full GPU access.
 
 ### macOS
 
-CPU only. Docker Desktop on macOS does not support GPU passthrough. For GPU workloads, deploy on a Linux machine with NVIDIA GPUs or use [AWS (EKS)](/environment-setup/eks-client-deployment-guide).
+CPU only, on both Intel and Apple silicon. Training runs inside Linux containers, which on macOS run in a virtual machine with no access to the Apple GPU — so macOS machines train on CPU by design, regardless of device settings. For GPU training, use a machine with an NVIDIA GPU (Linux, or Windows via WSL2), or deploy on [AWS (EKS)](/environment-setup/eks-client-deployment-guide).
 
 ### Windows
 
@@ -158,7 +158,7 @@
 ```
 
 <Note>
   **The database must stay on local disk.** MySQL/InnoDB is unsafe on NFS/CIFS, so the database and logs always use the local `/tracebloc` tree. To place large **datasets** on a network mount, set the installer's `HOST_DATASET_DIR` — it relocates only the dataset volume (the chart's `hostPath.datasetPath` → `/tracebloc-data`) and runs ingestion as the mount's owner uid, so writes succeed under NFS `root_squash`.
 </Note>
 
 Platform snippets (drop into your values file):
@@ -247,7 +247,7 @@
 
 #### Docker Registry
 
 The chart pulls the client image from a container registry — credentials are required in production. Use a token, not a plaintext password.
 
 ```yaml
 dockerRegistry:
@@ -284,11 +284,11 @@
   timeout: "10m"
 ```
 
 The CronJob's ServiceAccount is bound to the built-in `cluster-admin` ClusterRole because the chart templates cluster-scoped resources (PriorityClass, StorageClass, ClusterRoleBinding, optionally Namespace). Disable if you need a manual approval gate on upgrades.
 
 #### NetworkPolicy hardening for training pods
 
 Training pods run untrusted ML code. The chart can apply a NetworkPolicy that denies all ingress and restricts egress — arbitrary pod-to-pod traffic and the Kubernetes API are blocked, while the in-cluster MySQL that serves the training data and the proxy that reports results stay reachable. Direct outbound HTTPS is allowed by default; a stricter lockdown that instead routes it through an in-cluster egress gateway can be enabled per cluster.
 
 ```yaml
 networkPolicy:
@@ -314,12 +314,12 @@
 Leave `enabled: false` on clusters without an enforcing CNI — silently having no protection is worse than explicitly disabling it.
 
 <Warning>
 The chart's training-pod egress lockdown only blocks traffic if your CNI enforces NetworkPolicy. Verify your CNI before relying on it.
 </Warning>
 
 #### Resource Monitor and node-agents namespace
 
 The `tracebloc-resource-monitor` DaemonSet collects node-level CPU/memory metrics. It mounts `hostPath` volumes (`/proc`, `/sys`) which Pod Security Admission's `restricted` profile bans — so the chart isolates it in a dedicated **privileged** namespace (default `tracebloc-node-agents`).
 
 ```yaml
 resourceMonitor: true          # set false on clusters where metrics-server cannot be installed
@@ -329,7 +329,7 @@
     name: tracebloc-node-agents
 ```
 
 When `create: false`, create the namespace yourself with the required PSA labels:
 
 ```bash
 kubectl create namespace tracebloc-node-agents
@@ -343,7 +343,7 @@
 
 #### Pod Security Admission labels
 
 Training Jobs run untrusted user-supplied ML code. The chart can create the release namespace with Pod Security Admission `warn`/`audit`/`enforce` labels at the `restricted` profile for defense-in-depth:
 
 ```yaml
 namespace:
@@ -354,7 +354,7 @@
     enforce: restricted        # set "" for bare-metal hostPath installs
 ```
 
 When `create: false` (default) and you want PSA labels on an existing namespace:
 
 ```bash
 kubectl label namespace <workspace> \
@@ -379,7 +379,7 @@
 
 #### PriorityClass and PodDisruptionBudgets
 
 The chart pins the MySQL pod with a `tracebloc-data-plane` PriorityClass (value `1000000`) so it survives node-level OOM and scheduling pressure, and applies PDBs to MySQL and the jobs manager. Override only if you run a multi-replica MySQL externally:
 
 ```yaml
 priorityClass:
@@ -394,7 +394,7 @@
 
 ### Deploy
 
 Install the chart into a new namespace:
 
 ```bash
 helm upgrade --install <workspace> tracebloc/client \
@@ -425,7 +425,7 @@
 helm uninstall <workspace> -n <workspace>
 ```
 
 PVCs and the PriorityClass are annotated `helm.sh/resource-policy: keep` so your data and shared cluster resources survive uninstall. To remove them too:
 
 ```bash
 kubectl delete pvc --all -n <workspace>
@@ -445,11 +445,11 @@
 
 ## Security
 
 Tracebloc is designed so your data never has to leave your network. Here's how:
 
 - **Data stays local.** Training data never leaves your infrastructure. Only metadata and metrics are shared with the platform.
 - **Encrypted.** All communication between client and platform is TLS-encrypted.
 - **Isolated.** Training runs in containers with restricted system access. Kubernetes namespaces separate workloads from each other.
 - **Scanned.** Submitted models are analyzed for vulnerabilities before execution on your infrastructure.
 - **Minimal footprint.** The installer only modifies `~/.tracebloc/` and Docker. No system-wide changes.
 

environment-setup/deployment-environments.mdx

@@ -1,17 +1,17 @@
 ---
 title: "Deployment environments"
 description: "Run tracebloc anywhere — local, bare-metal, EKS, AKS, or OpenShift. Same chart, same steps, your choice of infrastructure."
 ---
 
 tracebloc runs the same way everywhere: one chart (`tracebloc/client`), one set of steps, your choice of infrastructure. **Local is a first-class production option** — a workspace on an on-prem server is every bit as real as one on a managed cloud cluster.
 
 ## Pick your environment
 
 | Environment | Runs on | GPU | Best when |
 |---|---|---|---|
-| [Local / k3d](/environment-setup/deploy-local) | One machine you own | NVIDIA / AMD, auto-detected | A laptop or a single on-prem server — the fastest start |
+| [Local / k3d](/environment-setup/deploy-local) | One machine you own | NVIDIA / AMD, auto-detected (macOS: CPU only) | A laptop or a single on-prem server — the fastest start |
 | [Bare-metal](/environment-setup/deploy-bare-metal) | Your own Kubernetes cluster | Your nodes | You already run on-prem Kubernetes |
 | [Amazon EKS](/environment-setup/eks-client-deployment-guide) | AWS (managed) | GPU nodegroups | You're on AWS and want managed, autoscaling compute |
 | [Azure AKS](/environment-setup/deploy-aks) | Azure (managed) | GPU node pools | You're on Azure |
 | [OpenShift](/environment-setup/deploy-openshift) | OpenShift / OKD | Your nodes | You run Red Hat OpenShift |