apple build stops before the archive in an SSH / non-GUI session (errSecInternalComponent) with how to run it in the logged-in session, --allow-ssh to skip; relative credential paths resolve from the project and xcodebuild gets an absolute ASC key path; tests, pitfall 101

skills/store-pitfalls/SKILL.md

@@ -1220,3 +1220,16 @@ that fails without the fix (see CONTRIBUTING.md).
   --from-text <file>`.
 - **Guard:** `textToFile` in `cli/mcp.ts` sends multi-line text as `--from-text <temp file>`; `clip` keeps the start of
   long JSON output (the end of plain text) and names a file with the whole output (`tests/mcp-text-file.test.ts`).
+
+## 101. `apple build` over SSH: errSecInternalComponent; a relative ASC_P8 path: "must be an absolute path"
+- **Symptom:** `storebound apple build` run over SSH on a Mac failed late in the archive (Embed Pods Frameworks,
+  codesign errSecInternalComponent). With `ASC_P8` set to a project-relative path, xcodebuild stopped with
+  "-authenticationKeyPath must be an absolute path".
+- **Cause:** codesign in an SSH session cannot use the login keychain. The key path was handed to xcodebuild as written
+  (and read relative to the working directory, not the project).
+- **Do:** run the build in the Mac's logged-in session: a CI agent started there, or from SSH a `.command` file opened
+  with `open -a Terminal <file>` (unset SSH_CONNECTION SSH_CLIENT SSH_TTY inside). `--allow-ssh` after
+  `security unlock-keychain` skips the check.
+- **Guard:** `remoteBuildSession` in `cli/lib/xcode.ts` stops `apple build` before the archive; `credPath` in
+  `cli/lib/credentials.ts` resolves relative credential paths from the project and `ascKeyFile` hands xcodebuild an
+  absolute path (`tests/build-sign.test.ts`).