From c1583ddcbbcd628dc9d9d6e36c2b3f2d887aaa9c Mon Sep 17 00:00:00 2001
From: Dax <mail@thdxr.com>
Date: Wed, 19 Aug 2026 11:29:06 -0400
Subject: [PATCH] docs: move CPU profiling to dev skill (#43448)

---
 .opencode/skills/opencode-dev/SKILL.md     | 27 ++++++++++++++++++++++
 packages/core/src/plugin/skill/opencode.md | 18 ---------------
 2 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/.opencode/skills/opencode-dev/SKILL.md b/.opencode/skills/opencode-dev/SKILL.md
index 386b33633fe..12f71dc1124 100644
--- a/.opencode/skills/opencode-dev/SKILL.md
+++ b/.opencode/skills/opencode-dev/SKILL.md
@@ -185,6 +185,33 @@ pmap -x <pid> | sort -k3 -nr | head -25
 
 Heap serialization itself can temporarily increase RSS and allocator high-water marks, so record `ps`/`smaps_rollup` both before and after capture. Large anonymous mappings with a comparatively small live heap require native-allocation or allocator investigation; they cannot be explained from JavaScript retainer paths alone.
 
+## CPU profiles
+
+The CLI installs a `SIGPROF` listener on non-Windows processes in `packages/cli/src/cpu-profile.ts`. One signal starts a ten-second CPU profile and stops it automatically; additional signals are ignored while a profile is active. There is no CPU profile CLI flag or environment variable.
+
+1. Get the PID from the health endpoint. For shared-service performance, target the server PID returned here rather than the short wrapper or TUI process:
+
+```bash
+opencode2 api get /api/health
+```
+
+Use `bun dev api get /api/health` instead when targeting the local/dev channel.
+
+2. Start the capture:
+
+```bash
+kill -PROF <server-pid>
+```
+
+3. Wait for `CPU profile written` in the channel's log before opening the file. Profiles are written to the same log directory as `cpu-<pid>-<timestamp>.cpuprofile`; the log's `path=` field is authoritative:
+
+```bash
+grep 'CPU profile' ~/.local/share/opencode/log/opencode.log | tail
+find ~/.local/share/opencode/log -maxdepth 1 -name 'cpu-<server-pid>-*.cpuprofile' -printf '%T@ %s %p\n' | sort -nr | head
+```
+
+Use `opencode-local.log` for a local/dev process. Load the completed `.cpuprofile` in Chrome DevTools or another V8 CPU profile viewer and inspect the hottest functions, call stacks, and self time during the controlled workload.
+
 ## Debugger
 
 - To debug the V2 CLI or TUI with Bun's inspector, launch the CLI entrypoint through Terminal Control with an inspector URL, then attach a debugger to that URL:
diff --git a/packages/core/src/plugin/skill/opencode.md b/packages/core/src/plugin/skill/opencode.md
index c30035ad1a8..c363b51816e 100644
--- a/packages/core/src/plugin/skill/opencode.md
+++ b/packages/core/src/plugin/skill/opencode.md
@@ -236,24 +236,6 @@ problem belongs to the client, the shared server, or one project.
 - Redact API keys, authorization headers, prompts, file contents, and other
   sensitive data before sharing diagnostics.
 
-### CPU profiles
-
-On Linux and macOS, send `SIGPROF` to a running OpenCode process to capture its
-CPU activity. Get the background server PID from the health endpoint, then send
-the signal:
-
-```sh
-opencode2 api get /api/health
-kill -SIGPROF <pid>
-```
-
-One signal starts a ten-second profile and stops it automatically. OpenCode
-writes the result to its log directory as
-`cpu-<pid>-<timestamp>.cpuprofile` and logs the complete path. Additional
-`SIGPROF` signals are ignored while a profile is active. Signal-triggered CPU
-profiles are unavailable on Windows. There is no CPU profile CLI flag or
-environment variable.
-
 See the [full troubleshooting guide](https://opencode.ai/v2/docs/troubleshooting)
 for service lifecycle commands, API inspection, log locations, explicit server
 connections, issue-reporting details, and local development paths.