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

docs/submission.md

@@ -0,0 +1,101 @@
+# Submitting a plugin
+
+**Submissions open with a later release.** This is how they will work, so
+you can prepare now.
+
+Plugins reach users only through the Eidonix plugin store. Cletus refuses
+any plugin Eidonix has not signed. There is no other way to install one.
+
+## 1. Become a publisher
+
+Ask Eidonix for a publisher account. Eidonix checks:
+
+- your company (registration documents);
+- your web domain: you add a DNS TXT record
+  `_cletus-publisher.<your domain>` with the value Eidonix gives you;
+- a signed publisher agreement (confidentiality, review, withdrawal).
+
+You receive:
+
+- your **publisher id** (the first half of every plugin id: `acme.…`);
+- an account on `git.eidonix.com`, with a private repository for each plugin
+  (`plugin-submissions/acme-gauge-check`). Only you and Eidonix's review
+  team can see it;
+- a place to register the SSH or GPG key you sign tags with.
+
+Users see your verified company name and domain on every listing and
+install screen.
+
+## 2. Build and check
+
+Develop wherever you like. Before submitting:
+
+```sh
+cletus-plugin check         # the store's automated checks, locally
+```
+
+## 3. Submit
+
+1. Push your code to your plugin's repository on `git.eidonix.com`.
+2. Push a **signed tag** `v<version>` that matches `version` in
+   `plugin.json`. The tag is the submission.
+
+Unsigned tags, tags signed by an unregistered key, and versions that were
+used before are ignored.
+
+Also include `listing/listing.json`:
+
+```json
+{
+  "summary": "Check measured gauges against the drawing's tolerances.",
+  "category": "Quality",
+  "visibility": "store",
+  "organizations": [],
+  "support": "support@acme.com",
+  "price": "free"
+}
+```
+
+- `visibility` is `"store"` (every organization can find it) or
+  `"organizations"`: only the organizations listed, by name. Use that for a
+  plugin made for one customer.
+- `price`: `"free"`, or `"paid"`. Paid plugins are arranged with Eidonix
+  directly for now; the store does not take payments yet.
+
+## 4. What happens next
+
+Progress shows as a status on your tag, and in an issue opened for each
+submission in your repository. Review comments go in that issue.
+
+| Status | Meaning |
+| --- | --- |
+| Building | Eidonix is building from your tag. |
+| Checks failed | The build or an automated check failed. The issue says which; fix and submit a higher version. |
+| In review | A reviewer is reading the code and running the plugin. |
+| Changes requested | Fix what the issue lists and submit a higher version. |
+| Approved | Waiting for Eidonix to sign and publish. |
+| Published | Available in the store (or to the organizations listed). |
+| Rejected | Not publishable. The issue says why. |
+
+The first review of a plugin reads all of it. Updates are reviewed as the
+difference from the last published version, so small, focused releases go
+through faster. An update that adds a permission is reviewed in full, and
+organizations must approve it again before their users get it.
+
+## 5. After publishing
+
+- Users choose when to update and may go back to earlier versions. Every
+  published version stays available unless withdrawn.
+- You can withdraw a version or the plugin (ask in your repository's
+  issues). Withdrawn versions stop being offered; installed copies keep
+  working unless Eidonix revokes them.
+- Eidonix revokes a version, plugin or publisher that is harmful or breaks
+  the agreement. A revoked plugin stops on every machine. Users keep the
+  files it saved.
+- Problems users report reach you through your repository's issues.
+
+## Your source code
+
+- Only the built plugin is distributed. Your source is not published.
+- How Eidonix may use, store and retain your source is set out in the
+  publisher agreement, which you sign before your first submission.