macOS Platform Guide

Full spec: 00-product-spec.md.

1. Platform Target

YZOS runs on macOS 13+. The sole authorization and runtime subject is /Applications/YZOS.app, bundle id com.yzos.desktop. The System Settings prompt displays the name YZOS.

2. Runtime Layout

flowchart TD
  Agent["LaunchAgent (com.yzos.autostart)"] -->|open -g -a| Desktop
  subgraph App["/Applications/YZOS.app"]
    Desktop["yzos-desktop (com.yzos.desktop)"]
    Runtime[yzos-runtime]
    Desktop --> Runtime
    Runtime --> HTTP["HTTP 127.0.0.1:17432"]
    Runtime --> PG[embedded PostgreSQL]
    Runtime --> Loops["Observe / Crystallize / Maintain"]
  end

com.yzos.autostart only opens the app at login. It does not read any protected resource and requires no TCC authorization.

3. Permissions

Permission	Purpose	TCC subject
Screen Recording	ScreenCaptureKit, window screenshots, OCR gap-filling	com.yzos.desktop
Accessibility	AXUIElement reads for UI tree, focus, selection	com.yzos.desktop
Microphone	Voice observation	com.yzos.desktop
Full Disk Access	Some IM or app local databases	com.yzos.desktop

Check permission status:

curl -s http://127.0.0.1:17432/permissions | python3 -m json.tool

4. Reading UI Structure

Capability	macOS API	Purpose
Current app	NSWorkspace	bundle id, localized name, active app
Window list	CGWindowListCopyWindowInfo	window id, title, bounds, z-order
UI tree	AXUIElement	role, label, value, focus, selection, bounds
Screen capture	ScreenCaptureKit	mp4 segments, keyframes, audit evidence
OCR	Vision.framework	ROI OCR, returns text boxes
Microphone	AVFoundation	permission request, audio capture

Structure source priority:

flowchart LR
  Adapter[app adapter] -->|fallback| AX[AX tree]
  AX -->|fallback| DOM[browser adapter / DOM]
  DOM -->|fallback| OCR[ROI OCR]
  OCR -->|fallback| VLM[VLM]

5. ScreenCaptureKit

Screen capture uses SCStream, writing mp4 by segment.

flowchart LR
  SCStream[SCStream] --> Writer[segment writer]
  Writer --> Seg[activity_screen_segments]
  Seg --> KF[ffmpeg keyframes]
  KF --> Out[ROI OCR / VLM]

OCR frame sampling runs at a lower rate than capture fps, to avoid excessive background power usage.

6. Accessibility

AX read targets:

Field	Description
role / subrole	button, text area, table, window, group
title / label	visible control name
value	text field, text area, or selected value
focused	the currently focused element
selected text	selection content in an editor or input field
bounds	node position, used for layout regions

Regions that AX cannot read fall through to OCR or VLM. Electron apps, custom-drawn canvases, and Figma-style canvases need an additional app adapter or visual gap-filling.

7. Development Install

mise trust && mise install
mise run doctor
mise run dev-install

8. Signature Verification

codesign -dvvv /Applications/YZOS.app 2>&1 | grep -E 'Identifier|TeamIdentifier|Authority'

Expected:

Identifier=com.yzos.desktop
TeamIdentifier=T45WM76P25

9. Local HTTP Endpoints

Endpoint	Purpose
GET /status	runtime state, preflight checks
GET /permissions	macOS TCC permission status
POST /permissions/request	permission request or guidance
POST /api/call	local API
/mcp	MCP HTTP transport