Add zero-native app builder skill

docs/src/app/cli/page.mdx

@@ -68,13 +68,50 @@ The `zero-native` CLI provides project scaffolding, validation, packaging, and d
       <td><code>zero-native automate &lt;command&gt;</code></td>
       <td>Interact with the automation server</td>
     </tr>
+    <tr>
+      <td><code>zero-native skills list</code></td>
+      <td>List built-in AI agent skills</td>
+    </tr>
+    <tr>
+      <td><code>zero-native skills get &lt;name&gt; [--full]</code></td>
+      <td>Output built-in AI agent skill content</td>
+    </tr>
     <tr>
       <td><code>zero-native version</code></td>
       <td>Print the zero-native version</td>
     </tr>
   </tbody>
 </table>
 
+## `zero-native skills` subcommands
+
+<table>
+  <thead>
+    <tr>
+      <th>Subcommand</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>skills list</code></td>
+      <td>List built-in skills served by the installed CLI</td>
+    </tr>
+    <tr>
+      <td><code>skills get core</code></td>
+      <td>Output the zero-native app-building guide for AI agents</td>
+    </tr>
+    <tr>
+      <td><code>skills get automation</code></td>
+      <td>Output the running-app automation guide for AI agents</td>
+    </tr>
+    <tr>
+      <td><code>skills get --all [--full]</code></td>
+      <td>Output every non-hidden skill; <code>--full</code> also includes reference and template files when present</td>
+    </tr>
+  </tbody>
+</table>
+
 ## `zero-native cef` flags
 
 <table>

packages/zero-native/README.md

@@ -29,6 +29,8 @@ The first run installs the generated frontend dependencies automatically.
 | `zero-native package` | Package the app for distribution |
 | `zero-native bundle-assets` | Copy frontend assets into the build output |
 | `zero-native automate` | Interact with a running app's automation server |
+| `zero-native skills list` | List built-in AI agent skills |
+| `zero-native skills get <name>` | Output AI agent skill content |
 | `zero-native version` | Print the zero-native version |
 
 ## More

packages/zero-native/package.json

@@ -9,6 +9,8 @@
   "types": "./zero-native.d.ts",
   "files": [
     "bin",
+    "skill-data",
+    "skills",
     "scripts",
     "src",
     "zero-native.d.ts",

packages/zero-native/scripts/copy-framework.js

@@ -15,3 +15,11 @@ rmSync(targetDir, { recursive: true, force: true });
 cpSync(sourceDir, targetDir, { recursive: true });
 
 console.log(`✓ Copied framework sources to ${targetDir}`);
+
+for (const dir of ['skills', 'skill-data']) {
+  const source = join(repoRoot, dir);
+  const target = join(projectRoot, dir);
+  rmSync(target, { recursive: true, force: true });
+  cpSync(source, target, { recursive: true });
+  console.log(`✓ Copied ${dir} to ${target}`);
+}

skill-data/automation/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: automation
+description: Automation and verification guide for running zero-native WebView shell apps. Use when the user asks to test an app, inspect runtime state, list windows, wait for readiness, reload a WebView, send bridge commands, debug why automation is not connected, create smoke tests, or verify a zero-native example in a GUI-capable session.
+---
+
+# Automate zero-native apps
+
+zero-native has a built-in automation system for inspecting running WebView shell apps. It works through file-based IPC in `.zig-cache/zero-native-automation/` and is intended for smoke tests, CI checks with a GUI session, and quick runtime inspection.
+
+Automation is not browser DOM automation. It reports runtime/window/source state and can ask the runtime to reload or dispatch bridge requests. For frontend DOM testing, use the frontend framework's tests or a browser automation tool against the dev server.
+
+## What automation can verify
+
+- An automation-enabled app started and published `ready=true`.
+- The runtime loaded the expected app name, source kind, and window metadata.
+- The main window exists and is focused/open.
+- The JavaScript-to-Zig bridge can round-trip a request through `zero-native automate bridge`.
+- Builtin window/WebView commands work when exercised by a smoke test.
+- Reload requests are accepted by the runtime.
+
+## What automation cannot verify
+
+- Real screenshots. Current `screenshot` support is a placeholder/unsupported depending on backend.
+- Arbitrary DOM queries and clicks.
+- Visual layout correctness.
+- Browser network assertions.
+
+## Prerequisites
+
+Build/run an app with automation enabled. Generated examples usually expose `-Dautomation=true`:
+
+```bash
+zig build run -Dplatform=macos -Dautomation=true
+```
+
+Repository examples may have specialized steps:
+
+```bash
+zig build run-webview -Dplatform=macos -Dautomation=true
+zig build test-webview-smoke -Dplatform=macos
+```
+
+The runner must pass an automation server into `RuntimeOptions`:
+
+```zig
+const server = zero_native.automation.Server.init(io, ".zig-cache/zero-native-automation", "My App");
+var runtime = zero_native.Runtime.init(.{
+    .platform = my_platform,
+    .automation = server,
+});
+```
+
+Apps built without `-Dautomation=true` usually ignore automation files.
+
+## Commands
+
+```bash
+zero-native automate wait
+zero-native automate list
+zero-native automate snapshot
+zero-native automate reload
+zero-native automate bridge '{"id":"smoke","command":"native.ping","payload":{"source":"automation"}}'
+```
+
+If using the repository-built CLI:
+
+```bash
+zig-out/bin/zero-native automate wait
+zig-out/bin/zero-native automate snapshot
+```
+
+## Standard workflow
+
+1. Start the app with automation enabled.
+2. Run `zero-native automate wait` to block until `snapshot.txt` contains `ready=true`.
+3. Run `zero-native automate snapshot` to confirm app/window/source metadata.
+4. Run `zero-native automate list` to inspect window summaries.
+5. Run `zero-native automate bridge '...'` for bridge round-trip checks.
+6. Use `zero-native automate reload` to request a WebView reload.
+
+## Bridge smoke test pattern
+
+The request must be JSON with an ID, command, and payload:
+
+```bash
+zero-native automate bridge '{"id":"smoke","command":"native.ping","payload":{"source":"automation"}}'
+```
+
+Automation sends the request with origin `zero://inline`. The app's bridge policy must allow that origin or the call will reject with `permission_denied`. For packaged asset origins, app code often allows `zero://app`; for automation smoke tests, add `zero://inline` only when the test needs it.
+
+Expected response shape depends on the handler. A typical `native.ping` handler returns:
+
+```json
+{"id":"smoke","ok":true,"result":{"message":"pong","count":1}}
+```
+
+If the command fails, inspect the bridge error code:
+
+- `unknown_command`: no handler registered or wrong command name.
+- `permission_denied`: origin or permission policy blocked it.
+- `handler_failed`: Zig handler returned an error or invalid JSON.
+- `payload_too_large`: request exceeded bridge limits.
+
+## File protocol
+
+The default directory is `.zig-cache/zero-native-automation/`.
+
+Files:
+
+- `snapshot.txt`: app name, readiness, source kind, source size, window metadata, accessibility summary.
+- `windows.txt`: window list.
+- `command.txt`: command input written by CLI and consumed by runtime.
+- `bridge-response.txt`: last bridge response.
+- `screenshot.ppm`: placeholder screenshot artifact when supported by the runtime layer.
+
+The runtime polls `command.txt`. After processing a command, it writes `done`.
+
+## Debugging automation failures
+
+If `zero-native automate wait` times out:
+
+1. Confirm the app is still running.
+2. Confirm it was built with `-Dautomation=true`.
+3. Confirm the runner passes `automation` into `Runtime.init`.
+4. Check `.zig-cache/zero-native-automation/snapshot.txt`.
+5. Delete stale files in `.zig-cache/zero-native-automation/` and restart the app.
+6. Run with more tracing, for example `zig build run -Dtrace=all`.
+
+If `snapshot` says no app connected:
+
+- The automation directory may not exist yet.
+- The app may be running from a different working directory.
+- The app may be built without automation.
+- The app may not have reached runtime startup.
+
+If bridge automation fails:
+
+- Check command name spelling.
+- Check app handler registration.
+- Check bridge policy origins for `zero://inline`.
+- Check runtime permissions.
+- Check that the handler returns valid JSON.
+
+## CI and smoke tests
+
+Use automation for minimal integration confidence:
+
+```bash
+zig build test-webview-smoke -Dplatform=macos
+```
+
+A good smoke test:
+
+1. Builds an example with `-Dautomation=true` and `-Djs-bridge=true`.
+2. Starts the app in a GUI-capable session.
+3. Waits for readiness.
+4. Verifies snapshot metadata.
+5. Sends `native.ping`.
+6. Exercises builtin windows/WebViews if the app enables them.
+7. Fails on timeout or unexpected bridge response.
+
+Do not use automation for exhaustive UI testing. It is a runtime and bridge smoke layer.
+
+## Notes
+
+- Automation is compile-time gated: apps built without `-Dautomation=true` ignore automation files.
+- The current screenshot artifact is a placeholder PPM or unavailable depending on backend.
+- WebView DOM interaction is intentionally out of scope for this file-based automation layer.
+- Use `zero-native skills get core --full` for app architecture, bridge policy, packaging, and debugging context.