docs(release): state that macOS artifacts ship unsigned by default

[xiaoou-waou]

What this fixes

README.md and README.zh-CN.md currently tell macOS users:

The tagged-release workflow signs, notarizes, and staples macOS artifacts with Developer ID credentials before publication.

The published artifacts are not signed, and the READMEs no longer tell users how to open one.

Evidence

1. The workflow takes the unsigned lane on every tag push.

.github/workflows/release.yml gates signing on inputs.sign_macos == true, and sign_macos is a workflow_dispatch input with default: false. A tag push supplies no inputs, so inputs.sign_macos != true holds and the unsigned lane runs with CSC_IDENTITY_AUTO_DISCOVERY: 'false'. The Staple macOS installer ticket and Verify signed and notarized macOS installer steps carry the same sign_macos == true condition, so neither ran.

2. The repository's own release runbook already says so.

docs/spec/06-delivery/06-release-runbook.md:

Default macOS release policy: the GitHub Release workflow packages macOS DMG/ZIP artifacts unsigned by default. Tag pushes and manual runs with sign_macos omitted or set to false disable identity discovery, do not receive signing or notarization secrets, and skip macOS stapling and signature verification.

3. The v0.14.4 changelog records the change.

packages/shared/src/changelog.ts:

Make macOS signing and notarization explicit opt-in, with opening guidance for trusted unsigned builds.

docs/spec/01-product/01-product-scope.md likewise lists both macOS targets as "signing/notarization remains credential-gated".

4. Measured against the published v0.14.5 artifact.

Downloaded PI-Desktop-0.14.5-arm64.dmg from the release; its sha512 matched latest-mac.yml. Mounted and inspected:

$ codesign -dv --verbose=4 PI-Desktop.app
Identifier=Electron
Format=app bundle with Mach-O thin (arm64)
CodeDirectory v=20400 size=392 flags=0x20002(adhoc,linker-signed)
Signature=adhoc
TeamIdentifier=not set
Info.plist=not bound

$ codesign --verify --deep --strict PI-Desktop.app
PI-Desktop.app: code has no resources but signature indicates they must be present

No Authority=Developer ID Application, no notarization ticket. Resources/bin/pi-desktop-host-core is ad-hoc signed as well.

5. The shipping DMG contradicts the README.

apps/desktop/PI-Desktop-macOS-opening-help.txt is bundled into the DMG, opens with "for this unsigned build", and gives the xattr -cr steps. The artifact tells users the build is unsigned while the README tells them it is signed and stapled.

How this happened

4f4f285 (docs(release): align macOS signing guidance) replaced the previous README text — which correctly said "macOS builds are not yet code-signed or notarized" and documented the xattr -cr workaround — with the signed-and-stapled claim. That commit did align the spec mirrors and the runbook, and those are accurate; the two READMEs are the only surfaces left asserting the old behavior.

AGENTS.md treats READMEs as release surfaces:

When a release changes user-visible behavior, refresh the affected Highlights, Download, Getting started, Status, or Development claims in both locales.

0.14.4 changed exactly this behavior, so this completes that refresh.

What changes

Both READMEs' ### macOS sections only (+25/-3):

• state the unsigned-by-default policy and name the sign_macos: true opt-in
• restore the xattr -cr /Applications/PI-Desktop.app opening guidance
• point at the DMG's bundled help file and the release runbook

No code, workflow, or spec changes. docs/spec/ already describes both lanes correctly, so there is nothing to sync there. English is edited as the source of truth and README.zh-CN.md mirrors it, linking the docs/zh-CN/ runbook.

Validation

• Both runbook link targets exist in their respective locales.
• docs/scripts/check-locales.mjs reports the same three pre-existing notices as on main (03-runtime/08-error-codes.md, 04-ux/08-component-spec.md, 08-meta/decisions-log.md). READMEs are outside its scope.
• The app installs and boots from the unsigned artifact once quarantine is cleared — the exact flow the restored text documents. Verified end to end on macOS arm64: host-core handshake, agent sidecar ready, plugins restored, window-shown, no error or warn log lines.

If the intent is instead to publish signed artifacts from tag builds, the fix belongs in release.yml (running the signed lane on tags) rather than in the READMEs — happy to close this in favour of that.

[vercel]

@xiaoou-waou is attempting to deploy a commit to the vastsa's projects Team on Vercel.

A member of the Team first needs to authorize it.

[muzimu217]

核对了三处事实，与当前 main 一致，文档描述准确：workflow_dispatch 的 sign_macos 默认 false；未签名 lane 通过 CSC_IDENTITY_AUTO_DISCOVERY=false 生效；PI-Desktop-macOS-opening-help.txt 确实挂在 dmg 的 extraResources 并有 packaging-footprint.test.mjs 断言。

补一个我们实测踩到的相邻坑，建议一并写进 README 和 DMG 里的说明文本：应用（或开发目录）位于 iCloud / 文稿同步区时，同步会改写扩展属性并产生 dataless 文件，导致签名校验失败。这种情况下只跑 xattr -cr 是救不回来的，必须先把应用移出同步目录（/Applications 或 ~/Applications）再执行。我们的插件开发目录放在 ~/Documents（iCloud 同步区）时就是这样，迁到 ~/dev 后 codesign 立刻恢复正常。

建议加一句：若执行 xattr -cr 后仍提示“已损坏”，先确认应用不在 iCloud / 文稿同步目录中。

[vastsa]

Thanks for catching the README mismatch with the unsigned-by-default macOS release lane, and for the evidence-backed write-up.

We're currently in a rapid-iteration phase, so documentation PRs will be batched and handled together a bit later rather than merged one by one against a moving tree. We'll come back to this PR in that pass.

Appreciate the effort.