Cletus plugin kit: rules for coding agents, specification, host API, style guide, worker SDK and cletus-plugin tool

docs/patterns.md

@@ -0,0 +1,73 @@
+# Patterns
+
+How to build common kinds of plugin on this contract. Each pattern says what
+works today and what waits for a later release.
+
+## Chat tools over your own files and formats
+
+Works today. The smallest useful plugin and the fastest to review.
+
+- Tools that read a format Cletus doesn't understand (an instrument export, a
+  machine log, a proprietary report) and return a short, typed summary.
+- `files` permission; every path through `host.files.resolve`.
+- Large results are written to a file next to the input (after
+  `host.files.can_write`) and the tool returns its path and a summary.
+
+## Long computations and batch jobs
+
+Works today.
+
+- A tool or service that starts a job returns a job id at once. Separate
+  tools report `status`, return `results` and `cancel`.
+- Job state lives in the data folder, so a restarted worker can report it.
+- `plugin.busy` answers `true` while a job runs, so Cletus doesn't stop the
+  worker for an update.
+- Results are written in the folder the user chose, never elsewhere.
+
+## Shared reference data
+
+Works today.
+
+- Reference data a team shares (standards, tables, templates) lives in a
+  shared folder the user picks (`workspace.read`), never inside the plugin.
+- The worker fetches it with `host.workspace.fetch`, which caches unchanged
+  files.
+- Writing results back for the team needs `workspace.write`.
+
+## Reading documents in the background
+
+Works today.
+
+- `agents`: `host.agent.start` runs Cletus over the files the user chose,
+  with a playbook or a prompt. The run can call your plugin's own tools.
+- Poll `host.agent.status`, or wait for `<id>:agent-done`.
+
+## Connecting machines, databases and services
+
+Works today, with direct network access.
+
+- `net.configured` for addresses the user enters (controllers, databases,
+  instruments), or `net:<domain>` for a fixed service.
+- Pure-Go drivers only.
+- Read-only by default. Every write is a separate tool marked `mutating` and
+  `requires_approval`, and `docs/plan.md` says what it changes.
+- Until the secret store ships, ask for passwords when needed and keep them
+  in memory only.
+
+## Libraries written in C or C++
+
+Works today.
+
+- Compile them to WebAssembly from source in your repository and run them
+  with [wazero](https://wazero.io) inside the worker.
+- The build stays pure Go, and review sees the library source.
+
+## With a later release
+
+- **Screens:** 2D and 3D screens in a sandboxed frame. The worker computes
+  and publishes data (`host.data.publish`); the screen draws it.
+- **The organization's AI, vision and speech:** summaries, image reading,
+  transcription.
+- **Camera and microphone** through the host.
+- **Saved connections and a secret store.**
+- **Services of Eidonix plugins**, such as opening a file in CAD Viewer.