flare-plugin-sdk 0.0.0-stage → 0.1.0-beta.2

package/skill/flare-plugin/references/authentication.md

@@ -0,0 +1,239 @@
+# Detection and authentication recipes
+
+These recipes describe the five supported interaction kinds. Website paths and
+helpers in sketches are adaptation points, not universal endpoints. Use the
+[GitHub template](../assets/github-template/plugin.js) for a complete token-login
+implementation and [Pixelfed](../examples/pixelfed/plugin.js) for complete OAuth.
+Never accept a submitted token/password as proof of identity without verifying
+it against the website.
+
+## Detection
+
+Declare `platform.detector: { "priority": 0 }` only when implementing
+`detector.detect(request, context)`. Inspect a documented endpoint on the
+candidate origin. Return `match: "none"` when evidence does not match;
+`"exact"` for the intended software and `"compatible"` only for known compatible
+behavior. Return the canonical HTTPS origin and optional software/instance data:
+
+```js
+// Result after verifying the website's software identity.
+const detected = {
+  match: "exact",
+  canonicalOrigin: context.origin,
+  software: "ExampleSoftware",
+  instance: { domain: context.origin.slice("https://".length), title: "Example" },
+};
+```
+
+Do not claim every reachable host. Detection has no credential access and may
+request only the candidate origin. Omit the declaration and method if explicit
+platform selection is sufficient, as in the template.
+
+## State transitions
+
+The method key is the manifest method **ID**, not necessarily its interaction
+name. `id: "token"` registers `login.token.begin`, for example.
+
+| Interaction | Calls | Allowed outcome |
+| --- | --- | --- |
+| OAuth | begin → browser callback → resume | begin: externalBrowser or success; resume: success |
+| Password | begin(values) | success |
+| CredentialImport | begin(values) | success |
+| Form | begin(values) | success |
+| WebCookie | begin → repeated check(snapshot) | begin: webCookie; check: pending or success |
+
+`pending` is not a general multi-step form mechanism. A form is submitted once;
+include all fields required to complete that submission. Expected login errors
+use `flare.error`; do not return an invented `error` transition.
+
+All successful methods return:
+
+```js
+// profile and credential come from a verified remote login.
+const success = {
+  type: "success",
+  value: {
+    accountId: profile.key.id,
+    origin: context.origin,
+    credential,
+    profile,
+    capabilities: { "flare.datasource.timeline/v1": ["page"] },
+  },
+};
+```
+
+`accountId` equals `profile.key.id`; the profile host equals the selected origin's
+host, including a non-default port. The Host checks origin, account ownership,
+and relogin identity. At least one displayable, declared capability must be
+negotiated with its required operation set. Login can return `composeConfig`
+using the [documented merge rules](manifest.md#compose-defaults). Preserve only credentials needed for later requests;
+avoid retaining a password if the server issues a reusable token instead.
+
+## Credential import
+
+Use `interaction: "CredentialImport"` and a `Secret` field. The template has the
+full manifest, `/api/me` verification, typed errors, and successful identity.
+Adapt its token acquisition instructions and payload to the actual website.
+Login contexts have no credential store access: return the verified payload;
+Flare persists it. Do not call `flare.credential.replace` during login.
+
+## Password
+
+Manifest method fragment:
+
+```json
+{
+  "id": "password",
+  "interaction": "Password",
+  "title": "Sign in",
+  "fields": [
+    { "id": "username", "type": "Username", "label": "Username" },
+    { "id": "password", "type": "Password", "label": "Password" }
+  ]
+}
+```
+
+Service sketch (the three helpers are website-specific implementations):
+
+```js
+const passwordService = {
+  async begin(request, context) {
+    const token = await exchangePassword(context.origin, request.values.username, request.values.password);
+    const profile = await verifiedProfile(context.origin, token);
+    return loginSuccess(context, profile, { accessToken: token });
+  },
+};
+```
+
+`exchangePassword` sends structured form/JSON/basic authentication as specified
+by the website and checks the HTTP response. `verifiedProfile` maps the actual
+authenticated identity. `loginSuccess` constructs the success shape above.
+Register this as `login.password`. Report credential rejection with a typed
+AuthenticationRequired or Validation error appropriate to that API.
+
+## Form
+
+Use a form for a different fixed collection of fields, such as username + OTP:
+
+```json
+{
+  "id": "otp",
+  "interaction": "Form",
+  "title": "Sign in with a code",
+  "fields": [
+    { "id": "username", "type": "Username", "label": "Username" },
+    { "id": "code", "type": "Otp", "label": "One-time code" }
+  ]
+}
+```
+
+```js
+const otpService = {
+  async begin(request, context) {
+    const credential = await verifyOneTimeCode(context.origin, request.values);
+    const profile = await verifiedProfile(context.origin, credential.accessToken);
+    return loginSuccess(context, profile, credential);
+  },
+};
+```
+
+Implement those website-specific helpers and register as `login.otp`. If the
+website requires a preceding “send code” step, explain how the user obtains the
+code outside this form or choose a supported browser flow. Do not invent dynamic
+field updates, an extra resume call, or a pending-form transition.
+
+## OAuth
+
+Declare `{ "id": "oauth", "interaction": "OAuth", "title": "Authorize" }`
+without fields or Cookie config. Implement `login.oauth.begin` and `.resume`.
+Add exact `authOrigins` for a separate authorization/token origin when needed;
+this does not expand later account HTTP access.
+
+1. `begin` receives Host-owned `flowId`, `state`, `redirectUri`, and selected
+   origin. Use the supplied state and redirect URI. Register a client only if
+   the provider supports it, otherwise use the provider-approved configuration.
+2. Return an approved HTTPS browser URL and JSON `pendingPayload` containing
+   only the bounded data needed to resume (for example client ID and PKCE
+   verifier). The begin runtime closes; globals do not carry the flow forward.
+3. `resume` receives Host-validated callback parameters and persisted pending
+   payload. Handle the provider's denial/error response. Exchange the code,
+   verify the resulting account, and return success.
+
+```js
+// begin result fragment; build authorizationUrl from the provider's contract.
+const browserTransition = {
+  type: "externalBrowser",
+  url: authorizationUrl,
+  pendingPayload: { clientId, verifier },
+};
+```
+
+The Host owns callback validation, expiry, persistence, replay protection, and
+relogin identity. It rejects a flow if the running package changed. The plugin
+still implements the provider's token exchange and PKCE requirements; SHA-256
+returns hex, so see [crypto encoding](runtime-http.md#credentials-crypto-and-locale).
+Never hardcode a callback URI from a sample. See Pixelfed for dynamic client
+registration, state propagation, code exchange, and profile verification.
+
+## WebCookie
+
+Manifest method fragment:
+
+```json
+{
+  "id": "browser",
+  "interaction": "WebCookie",
+  "title": "Sign in in the browser",
+  "cookie": {
+    "startUrl": "$accountOrigin/login",
+    "probes": [{
+      "url": "$accountOrigin/api/me",
+      "cookies": [{ "name": "session", "required": true }]
+    }]
+  }
+}
+```
+
+Service sketch; `fetchVerifiedCookieProfile`, `mapProfile`, and `loginSuccess`
+must be implemented for the selected site's profile API and result shape:
+
+```js
+const browserService = {
+  async begin(request, context) {
+    return { type: "webCookie", startUrl: context.origin + "/login" };
+  },
+  async check(request, context) {
+    const probeUrl = context.origin + "/api/me";
+    const cookies = request.cookies.cookies
+      .filter(cookie => cookie.sourceUrl === probeUrl)
+      .map(({ name, value }) => ({ name, value }));
+    const profile = await fetchVerifiedCookieProfile(probeUrl, cookies);
+    if (!profile) return { type: "pending" };
+    return loginSuccess(context, mapProfile(profile, context), { cookies });
+  },
+};
+```
+
+Register as `login.browser`. The returned start URL must exactly match the
+resolved manifest start URL. The Host collects Cookies only for declared probes
+and filters domain/path/HTTPS scope. `sourceUrl` identifies the probe: do not
+combine Cookies from distinct origins merely because their names match. Use
+structured `cookies` in the verification request, and retain only the values
+appropriate for later account-origin requests. Required missing Cookies delay
+checking; a present Cookie still needs server-side identity verification.
+
+Return pending only for a verified “not authenticated yet” state. Map rate limits,
+network failures, and malformed responses to their actual typed errors instead
+of silently polling forever. The Host prevents overlapping checks and owns the
+session's disposal; the plugin supplies no lifecycle hook.
+
+## Refresh and relogin
+
+Refresh access tokens within an account method using the website's documented
+flow and the account's allowed origin. After successful verification, atomically
+replace the full credential payload, retaining required fields. Retry the
+original operation only when safe (especially for writes); avoid unbounded loops.
+An invalid/expired credential that cannot be refreshed should raise
+AuthenticationRequired, which the account adapter routes to relogin. The Host
+requires the same account identity on relogin; schema changes are described in
+[publishing](publishing.md#updates-and-compatibility).

package/skill/flare-plugin/references/capabilities.md

@@ -0,0 +1,88 @@
+# Capability and UI contract
+
+Each ID below has prefix `flare.datasource.` and suffix `/v1`; use the full ID
+in the manifest and negotiated login result. JavaScript methods live under
+`definePlugin({ capabilities: { <service>: ... } })`.
+
+| ID middle | Service | Required operations | Additional operations | Host surface / dependency |
+| --- | --- | --- | --- | --- |
+| `timeline` | `timeline` | `page` | None | Static timelines, including at least one default |
+| `search` | `search` | `posts`, `profiles`, `discoverPosts`, `discoverProfiles`, `discoverHashtags` | None | Search/discovery sections |
+| `profile` | `profile` | `byId`, `byHandle` | `timeline`, `following`, `followers` | Profile lookup; tabs additionally require `timeline` and profileTabs |
+| `post` | `post` | `detail` | `context`, `delete`, `mutate` | Internal post detail, thread context, and supported actions |
+| `relation` | `relation` | `state`, `mutate` | None | Follow/block/mute controls; nonempty static relationActions |
+| `compose` | `compose` | `publish` | None | Composer; requires composeDefaults and an account |
+| `notification` | `notification` | At least one of `page`, `badge` | Both may be declared | `page` supplies the list and requires notificationFilters; badge alone is not a displayable login capability |
+| `list` | `list` | `page`, `detail`, `create`, `update`, `delete`, `timeline`, `members`, `memberships`, `addMember`, `removeMember` | None | List browsing and management |
+| `direct-message` | `directMessage` | `rooms`, `room`, `messages`, `send`, `delete`, `leave`, `create`, `badge`, `canSend` | None | DM rooms, conversation, and related account controls |
+| `article` | `article` | `detail`, `comments` | None | Article detail when a post selects article navigation |
+| `gallery` | `gallery` | `detail`, `comments`, `recommendations` | None | Gallery detail when a post selects gallery navigation |
+| `tab-catalog` | `tabCatalog` | `page` | None | Dynamic timeline catalog; also needs timeline.page and a static/default timeline |
+
+These sets come from the Host's `PluginAbiV1` contract, not from TypeScript
+`Partial<Service>` declarations. Known capability operations must be implemented
+and declared together. A website without a required operation may need a smaller
+feature set; do not advertise a successful mutation that does nothing. A genuine
+empty comments collection may return an empty ended page; an unsupported remote
+operation should be explained and omitted where the Host allows omission.
+
+## Declaration, registration, negotiation
+
+For the same timeline, these three shapes are intentionally different:
+
+```json
+{ "flare.datasource.timeline/v1": { "operations": { "page": { "directions": ["refresh", "older"] } } } }
+```
+
+```js
+// Registration fragment: include inside the single definePlugin call.
+const timelineService = {
+  async page(request, context) {
+    return loadTimeline(request.timelineId, request.page, context);
+  },
+};
+```
+
+```json
+{ "flare.datasource.timeline/v1": ["page"] }
+```
+
+The first is `platform.capabilities`, the second is `capabilities.timeline`
+(with a website-specific `loadTimeline` implementation), and the third is the
+login success's `capabilities`. On login, negotiate only declared, complete sets
+that this account/instance supports. At least one displayable capability is
+required: compose/relation alone and a notification badge alone do not qualify.
+Guest access uses the enabled guest declaration and manifest capabilities instead
+of account login negotiation. See [upgrade negotiation](publishing.md#updates-and-compatibility)
+for how an existing account adopts newly declared operations after an update.
+
+## Entry points and actions
+
+The Host builds UI from capabilities and static configuration. Implementing an
+undeclared function does not add a UI entry. A static timeline ID is passed as
+`request.timelineId`; profile tabs pass `request.tabId`. Names and parameters are
+not network URLs unless your implementation explicitly interprets them that way.
+
+Post actions additionally depend on their `ActionDescriptorV1`, enabled state,
+account, and mutation capability. Set accurate `active`/`count` values even when
+an action is disabled. The Host supplies layout and controls; plugins cannot
+install arbitrary UI or arbitrary action kinds.
+
+| `PostV1.detailType` | Click behavior | Required target |
+| --- | --- | --- |
+| Omitted or `post` | Internal post detail | post.detail |
+| `article` | Internal article detail | article.detail + comments |
+| `gallery` | Internal gallery detail | gallery.detail + comments + recommendations |
+| `link` | Browser according to user settings | Absolute HTTPS `url`, no internal-detail capability needed |
+
+Missing internal target capability makes that click unavailable; it does not
+fall back to another detail type. `link` bypasses internal Deep Link matching.
+Grid covers use the same article/gallery/link navigation; author/actions and
+reposted targets retain their own behavior.
+
+The login profile remains the current account's saved identity if profile lookup
+is absent. It does not enable arbitrary profile pages, profile timelines, or
+lookup methods. Use this for a minimal read-only feed such as the template.
+
+See [recipes](recipes.md) for every service's inputs, result shape, and adaptation
+points, and [the type declarations](../flare-plugin.d.ts) for full signatures.

package/skill/flare-plugin/references/manifest.md

@@ -0,0 +1,192 @@
+# Manifest reference
+
+`manifest.json` is UTF-8, strict JSON. Unknown fields, comments, and trailing
+commas are rejected. Property names and enum spellings are case-sensitive.
+Defaults below apply when a field is omitted; use omission for optional fields
+rather than sending null for non-nullable values. Start from the complete
+[template manifest](../assets/github-template/manifest.json).
+
+## Root object
+
+| Field | Required / default | Contract |
+| --- | --- | --- |
+| `schemaVersion` | `1` | Manifest schema, currently exactly 1 |
+| `apiVersion` | Required | Runtime ABI, currently exactly 1 |
+| `id` | Required | Stable reverse-domain plugin ID; `[a-z][a-z0-9]*(?:\.[a-z][a-z0-9-]*)+` |
+| `version` | Required | SemVer; use stable `major.minor.patch` for GitHub distribution |
+| `defaultLocale` | `"en"` | BCP-47 locale tag |
+| `name` | Required | Manifest text |
+| `description` | Omitted | Manifest text |
+| `permissions` | `{}` | Permission object below |
+| `platform` | Required | Exactly one platform object |
+
+Manifest text is either a nonblank string or `{ "key": "plugin.name", "fallback":
+"Example" }`. Every localized key used by the manifest must exist in the default
+locale catalog. Plain strings need no locale file. This encoding differs from
+runtime `WireTextV1`; see [localization](recipes.md#localization).
+
+## Permissions
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `authOrigins` | `[]` | Up to 16 additional exact HTTPS origins for login, e.g. `https://login.example.org` |
+| `mediaNetwork` | `false` | Allows automatic remote media loading, including avatars, HTML images, audio/video, and covers |
+
+Auth origins have no paths, trailing slash, query, fragment, wildcard, or URL
+credentials. Use normalized host casing and omit the default `:443` port.
+They do not grant account/guest HTTP access to extra origins. Media permission
+allows destinations across websites, including CDNs/federated servers; it does
+not expand the HTTP API. See [origin rules](runtime-http.md#origins-and-permissions).
+
+## Platform object
+
+| Field | Required / default | Contract |
+| --- | --- | --- |
+| `id` | Required | Stable platform ID, `[A-Za-z][A-Za-z0-9_.-]{0,63}`; avoid built-in and other plugin platform IDs |
+| `name`, `description` | Name required | Manifest text |
+| `detector` | Omitted | `{ "priority": 0 }`; priority -10000..10000, requires `detector.detect` |
+| `loginMethods` | `[]` | Login declarations below; method IDs unique and at most one method per interaction kind |
+| `capabilities` | `{}` | Capability ID → declaration; up to 32 entries |
+| `timelines` | `[]` | Static timeline declarations; timeline capability requires at least one |
+| `profileTabs` | `[]` | Profile tab declarations; requires `profile.timeline` |
+| `deepLinks` | `[]` | Up to 64 structured rules; see [Deep Links](recipes.md#deep-links) |
+| `composeDefaults` | Omitted | Required conservative defaults when declaring `compose.publish` |
+| `guest` | Omitted | `{ "enabled": true }` enables guest datasource access; object defaults enabled to true |
+| `credentialSchemaVersion` | `1` | Integer 1..1000000; changing it requires existing accounts to log in again |
+| `timelineSchemaVersion` | `1` | Integer 1..1000000; changes timeline identity; see [upgrades](publishing.md#updates-and-compatibility) |
+
+Other identifiers (method, field, timeline, tab, parameter, capture) generally use
+`[A-Za-z][A-Za-z0-9_.-]{0,127}`. Parameter objects have at most 32 string values,
+each at most 4096 characters. Plugin/platform IDs have their separate rules above.
+
+### Capabilities
+
+```json
+{
+  "flare.datasource.timeline/v1": {
+    "operations": { "page": { "directions": ["refresh", "older"] } }
+  }
+}
+```
+
+An operation configuration is an object, not a function name or boolean.
+`directions` defaults to `[]`, which the current loader treats as unrestricted;
+declare the actually supported directions explicitly. Non-paging operations use
+`{}`. The [capability matrix](capabilities.md) defines exact names and required
+sets. Known capability declarations with missing methods/operations fail
+installation; unknown capability IDs produce warnings and are ignored.
+
+`notificationFilters` belongs on the notification capability declaration and
+must be nonempty when `page` is declared. Values: `all`, `mention`, `comment`,
+`like`. `relationActions` belongs on the relation declaration and must be
+nonempty. Values: `follow`, `block`, `mute`. Both default to empty and are static
+arrays; placing them on another capability is invalid.
+
+### Timelines and profile tabs
+
+| Field | Timeline default | Profile-tab default |
+| --- | --- | --- |
+| `id`, `title` | Required ID and manifest text | Required ID and manifest text |
+| `icon` | `"Home"` | `"Profile"` |
+| `display` | `"List"` | `"List"` |
+| `parameters` | `{}` | `{}` |
+| `defaultForNewAccount` | `false` | Not a profile-tab field |
+
+IDs must be unique within each list. At least one declared timeline must have
+`defaultForNewAccount: true`. `display` is `List` or `Grid`, not lowercase.
+`tabCatalog.page` still requires a static timeline and `timeline.page`.
+
+Icons use these Host semantic names:
+`Home`, `Notification`, `Search`, `Profile`, `Local`, `World`, `Featured`,
+`Bookmark`, `Heart`, `List`, `Messages`, `Channel`, `Like`, `Repost`, `Reply`,
+`Delete`, `Follow`, `Block`, `Mute`, `Info`. The platform icon itself is the
+package's `assets/icon.<extension>` (PNG, JPEG, WebP, GIF or ICO), not one of these names.
+
+#### Default and manually added tabs
+
+When a new account with timeline access is added, Flare adds every timeline with
+`defaultForNewAccount: true` in manifest order. The first default is also the
+account's main timeline. Multiple defaults are supported; other static timelines
+and dynamic `tabCatalog.page` entries remain available for manual addition.
+
+Default tabs follow the same presentation convention as built-in platforms on
+Android, iOS, native macOS and Compose Desktop:
+
+| Where the tab appears | Title | Icon |
+| --- | --- | --- |
+| First automatically added default | Localized `platform.name` | Packaged platform icon |
+| Other automatically added defaults | Declared timeline `title` | Packaged platform icon |
+| Default timeline in the manual-add list | Declared timeline `title` | Packaged platform icon |
+| Other timelines in the manual-add list | Declared timeline `title` | Declared timeline `icon` |
+
+Keep functional titles such as Home, Discover or Bookmarks in the timeline
+declarations; Flare supplies the platform name for the first automatic tab.
+The declared semantic `icon` is not used for default timelines in these lists.
+Timeline IDs, parameters and `List`/`Grid` presentation are unchanged by these rules.
+Profile tabs continue to use their own declared titles and icons.
+
+Automatic addition happens only when creating an account. Signing in again or
+updating/reloading a plugin does not recreate existing tabs or overwrite saved
+names, icons, ordering or user customizations. Updated declarations apply to
+newly added tabs.
+
+### Login methods
+
+Each method has required `id`, `interaction`, `title`; optional `description`;
+`fields` defaults to `[]`; `cookie` is omitted except for WebCookie.
+
+| Interaction | Required registration | Configuration |
+| --- | --- | --- |
+| `OAuth` | `login.<id>.begin`, `.resume` | No fields or Cookie configuration |
+| `Password` | `login.<id>.begin` | At least one field |
+| `CredentialImport` | `login.<id>.begin` | At least one field |
+| `Form` | `login.<id>.begin` | At least one field |
+| `WebCookie` | `login.<id>.begin`, `.check` | Cookie configuration; no fields |
+
+Fields require `id`, `type`, `label`; `placeholder` is optional and `required`
+defaults to true. Label/placeholder use manifest text. Field types are `Text`,
+`Username`, `Password`, `Otp`, `Secret`. These select Host controls; the plugin
+still validates credentials against the website. The form Host accepts at most
+32 submitted fields, each up to 16384 characters, with only declared field IDs.
+
+Cookie configuration contains `startUrl` and `probes`. Each probe has `url` and
+`cookies: [{ "name": "session", "required": true }]`. There must be 1..16
+probes and 1..32 requirements per probe, without duplicate Cookie names within a
+probe. Cookie start/probe URLs use an approved HTTPS origin, or the special
+`$accountOrigin` prefix. That prefix is resolved in Cookie and Deep Link manifest
+configuration; it is not a general string interpolation facility for plugin code.
+See the [complete login recipes](authentication.md).
+
+### Compose defaults
+
+| Field | Shape and defaults |
+| --- | --- |
+| `text` | Optional `{ "maxLength": 500 }`; limit 1..1000000 |
+| `media` | Optional object; required `maxCount` (0..100), `maxBytes` (1..1073741824) |
+| `media.minCountForNew` | Default 0, between 0 and maxCount |
+| `media.supportedMimeTypes` | Default `[]`; up to 128 MIME patterns, including `image/*` |
+| `media.altTextMaxLength` | Default 1500, range 0..100000 |
+| `media.canSensitive` | Default true |
+| `visibility` | Optional `{ "allowed": ["public"], "default": "public" }`; default must be allowed |
+| `contentWarning` | Default false |
+| `poll` | Optional `{ "maxOptions": 4 }`, range 2..100 |
+| `language` | Optional `{ "maxCount": 1 }`, range 1..32 |
+
+Visibility values are `public`, `unlisted`, `followers`, `direct`. Describe what
+the website actually supports. Login may return an instance config. When both sides define a section, the Host
+uses the stricter limits, intersects visibility/MIME constraints, and rejects
+empty intersections. When only one side defines an optional section, that section
+is retained; omission is not a prohibition. Content-warning support requires
+both sides when both configs exist. Implement every resulting enabled field in
+`compose.publish`; see [compose](recipes.md#compose).
+
+## Frequent invalid combinations
+
+- Timeline capability without a static/default timeline.
+- A profile tab without the profile timeline operation.
+- Compose capability without compose defaults, or defaults without the capability.
+- Only `search.posts` declared when the search Host interface requires all five operations.
+- A login method ID that differs from the corresponding `login` object key.
+- Localized manifest keys absent from the default catalog.
+- Extra root properties such as `author`, `homepage`, `entry`, or a trust badge:
+  API v1 defines no such manifest fields; put human-facing information in README.

package/skill/flare-plugin/references/publishing.md

@@ -0,0 +1,111 @@
+# GitHub publication and upgrades
+
+GitHub is the recommended distribution path. Flare installs from a public
+`https://github.com/OWNER/REPOSITORY` URL (optional `.git` suffix), with one plugin
+at the repository root:
+
+```text
+manifest.json
+plugin.js
+assets/icon.png
+locales/en.json       # optional; other BCP-47 catalogs as needed
+README.md            # author/user instructions, ignored by the importer
+```
+
+The package must contain exactly one `assets/icon.<extension>`: `png`, `jpg`,
+`jpeg`, `webp`, `gif`, or `ico`. Its extension must match its encoded contents.
+The icon is kept unchanged, limited to 2 MiB and 1024×1024 pixels. SVG is not
+supported. PNG remains the default in the templates.
+
+Development files may coexist in the repository. Flare selects the plugin files;
+it does not run a package manager, build script, or client-side bundler. Commit
+the already-built classic script, including all runtime dependencies. A Flare
+monorepo URL pointing to an example subdirectory is not a valid installation URL:
+copy that example's contents into a repository you own first.
+
+## Prepare and publish
+
+1. Adapt the website endpoints and verify the advertised features. Replace the
+   template IDs, name, description, and placeholder icon before publication.
+   Keep real tokens, Cookies, passwords, and private fixtures out of Git history.
+2. Put the required files at root and check that a clean checkout contains them.
+   Include README instructions for supported website/instances, token acquisition
+   if relevant, features, permissions, and tests actually performed.
+3. Set a stable SemVer manifest version, for example `0.1.0`. Publish a tag
+   `0.1.0` or `v0.1.0` on the commit with those files. Removing the optional
+   **lowercase** `v` must exactly match manifest.version. Follow the same rule for
+   any permitted build metadata; plain major.minor.patch is the simplest choice.
+4. Share the repository URL. A GitHub Release page and uploaded `.fpp` asset are
+   not required. Creating/pushing the repository or tag follows the user's
+   authorization; a generated project alone is not permission to publish it.
+5. The user enters the repository URL in Flare plugin management and clicks
+   **Install**. Flare selects and downloads the latest stable version, then shows
+   source and permission review in the same dialog. Only confirmation installs
+   the plugin; cancellation discards the download. Errors stay in the dialog for
+   retry. Successful installs take effect immediately; verify the installed
+   tag/version and running behavior without restarting Flare.
+
+Private repositories, arbitrary branch tracking, prerelease tags, automatic
+installation, and build-on-device are unsupported. A public repo without a stable
+version tag has no installable version, even if its default branch has valid files.
+
+Flare resolves the latest stable tag to a commit SHA and downloads that source ZIP.
+Archive checks also inspect ignored development files for unsafe paths/symlinks,
+duplicates, multiple roots, and size limits. Do not commit node_modules, build
+caches, or unrelated large assets. See [limits](troubleshooting.md#limits).
+
+## Updates and compatibility
+
+Increment manifest.version and publish a new stable tag. Preserve plugin ID,
+platform ID, and the GitHub repository identity for an in-place update. Flare
+records repository ID, owner/name, tag, and SHA. A moved tag/source change or new
+permission is surfaced in review; prefer a new tag over rewriting a published
+one. Failure/cancellation leaves the installed package intact.
+
+Opening management checks for updates using a five-minute metadata cache;
+manual checking bypasses it. Discovery only offers an update; download/review/
+confirmation are separate steps. GitHub metadata uses global proxy routing and
+rate-limit handling, not plugin account credentials. Excessive tag lists produce
+an error rather than an incomplete “latest version” answer.
+
+Install, update, and uninstall take effect immediately. Installed plugins are always enabled. There are no plugin lifecycle/migration callbacks. Media
+grants follow the running package; cached media retains plugin ownership and
+rechecks that package's permission. Missing plugins cannot restore their media.
+Uninstall records removal before account cleanup. Once that record is saved,
+account-cleanup or final-index-write failures keep the plugin stopped across
+restart; retry deletion from management to finish. Updating or reinstalling
+cannot bypass incomplete removal. Unused package-file cleanup can be retried
+separately from management after deletion completes.
+Publishing controls follow the current account capabilities after replacement or
+relogin, without requiring the account list to change.
+
+| Change | Author consequence |
+| --- | --- |
+| Credential payload format becomes incompatible | Increment credentialSchemaVersion; existing accounts require relogin, with no plugin migration hook |
+| Timeline IDs/parameters change incompatibly | Consider timelineSchemaVersion; it changes timeline identities and retires old specs. Explain that existing selections may need reconfiguration |
+| Capabilities removed | Running capabilities are filtered by the new manifest |
+| Operations newly declared compared with the account's saved manifest | Current Host admits those new operations without re-negotiating login; do not assume a new login will gate them |
+| Previously declared operation was not negotiated for the account | It remains unavailable unless account negotiation changes |
+| Package hash changes | Account adapter invalidates cached content when refreshing its persisted package snapshot |
+
+Treat website/credential compatibility deliberately. A version bump alone does
+not convert stored credentials. Document new permissions and user-visible changes.
+The Host's own cache-database migration is separate from a plugin's versioning;
+plugin authors do not control it.
+
+## Optional local installation
+
+For offline development or local transfer, the skill includes Node's standard-
+library-only packer. From this skill directory:
+
+```sh
+node pack.mjs assets/github-template /tmp/example-feed-0.1.0.fpp
+```
+
+For an adapted plugin repository, create a staging directory containing only
+manifest.json, plugin.js, one supported assets/icon.<extension>, and optional locales/*.json, then pass
+that directory to pack.mjs. The packer ignores only a root README.md; unlike
+GitHub import it rejects other development files, including .git, tests, and type
+declarations. Keep the output outside the input directory. Packaging success is
+not full manifest/registration/behavior validation. Local packages are unverified
+and still require review; installation takes effect immediately and no GitHub source/update tracking is recorded.