# Plugin Specification For AI Implementers

This document is the compact contract for generating YMhut Box plugins with another AI agent.

## Build A Minimal Local Package

Create exactly the files needed for a runnable local package:

- `ymhut.plugin.json`
- `README.md`
- `index.html`
- `style.css`
- `main.js`

Keep UI code and core logic local. Do not load remote scripts as runtime dependencies. Remote HTTP APIs are allowed only through declared permissions and graceful failure states.

## Manifest Rules

- Use a stable `id` with letters, numbers, `.`, `-`, or `_`.
- Do not prefix the id with `plugin:`.
- Include at least one `ToolboxTool` or `NavPage` surface.
- Include every local file in `resources`, including `README.md`.
- Request only permissions the plugin actually uses.
- Explain every requested permission in `README.md`.

## Runtime Bridge

Use `window.ymhut` for host abilities:

- `output.*` for reports and summaries.
- `storage.*` for plugin-private state.
- `http.fetch` for http/https requests.
- `network.*` for host network diagnostics.
- `clipboard.*` and `file.*` only when clearly user initiated.
- `openExternal(url)` for links, which opens the YMhut safe browser by default.
- `openExternal(url, { target: "system" })` only for an explicit system-browser action.

## UI And Window Boundaries

The plugin page owns only its WebView content area. Do not mimic system title bars, cover host controls, or create invisible click layers. Avoid full-screen fixed overlays; if a modal is necessary, provide a visible close control and restore focus.

Design for both embedded and independent-window use. Use responsive grids, readable card density, clear loading states, empty states, and error states. The host output area should not be used as the primary UI.

## Security Constraints

Do not modify or override:

- `server/`
- built-in app assets
- developer/about identity
- built-in tool IDs
- paths outside the plugin directory

All plugin resources must resolve inside the plugin folder. File access must go through host file pickers; never assume arbitrary filesystem access.

## Acceptance Checklist

- Plugin scans without validation errors.
- README explains features, permissions, boundaries, and known failures.
- Main UI runs without network and shows a useful degraded state.
- Output writes do not hide the main UI.
- Links open in the safe browser by default.
- No remote scripts, no unbounded z-index overlays, no hidden click blockers.