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

package/skill/flare-plugin/README.md

@@ -0,0 +1,204 @@
+# Flare Plugin SDK and skill
+
+Use this directory as the `flare-plugin` skill to build a website adapter with an
+AI coding agent, or read the same references directly. All material describes
+Social Plugin API v1 in the accompanying Flare source. Use a Flare build that
+includes this subsystem; this directory does not promise a minimum public app
+release. The module targets Android, JVM Desktop, iOS, and native macOS, not Web.
+
+## Install the skill
+
+This skill installs into your AI coding agent. The website adapter it helps you
+create is installed separately into Flare; see [Start a plugin repository](#start-a-plugin-repository).
+The source package is `feature/plugin/sdk/skill/flare-plugin/`. Copy that **entire
+directory**, including references, types, assets, and examples. Copying only
+`SKILL.md` loses the SDK. The parent `skill/` directory is just a container.
+
+The package follows the [Agent Skills format](https://agentskills.io/specification):
+the directory and frontmatter name are both `flare-plugin`, the entrypoint is
+`SKILL.md`, and supporting files use relative links. It has no agent-specific
+runtime dependency. Optional UI metadata such as `agents/openai.yaml` is not
+needed to use it. Your agent still needs file access and the tools required by
+your plugin project; Node is needed for the documented syntax and package checks.
+
+### Install from GitHub with Codex
+
+The [development source](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin)
+is on the `feature/plugin` branch of `DimensionDev/Flare`. It is a development
+branch, not a released SDK version. For reproducible installation, select the
+full commit SHA containing the skill in GitHub and use it in place of the branch.
+
+Ask Codex's built-in installer:
+
+```text
+$skill-installer Install the flare-plugin skill from repository DimensionDev/Flare,
+ref feature/plugin, path feature/plugin/sdk/skill/flare-plugin.
+Copy the complete skill directory, including its supporting files.
+```
+
+Give the repository, ref, and path separately: this ref contains a slash. If you
+use the installer's Python CLI directly, the equivalent arguments are
+`--repo DimensionDev/Flare --ref feature/plugin --path feature/plugin/sdk/skill/flare-plugin`.
+Record the resolved commit SHA when you need to reproduce an installation. If a
+skill already exists, follow [Update or remove](#update-or-remove) first.
+
+### Install from a local checkout
+
+Check out a revision that contains this directory. For example, clone the
+development branch into a new directory, then enter its repository root:
+
+```sh
+git clone --branch feature/plugin --single-branch https://github.com/DimensionDev/Flare.git
+cd Flare
+```
+
+For an existing checkout, use your normal Git workflow to select the intended
+revision before copying. No Flare build is needed to install the skill.
+
+From the Flare repository root, choose **one** of the following first-install
+commands. The existence check prevents copying into an already-installed skill.
+
+Codex, for all local projects:
+
+```sh
+mkdir -p "$HOME/.agents/skills"
+if [ ! -e "$HOME/.agents/skills/flare-plugin" ] && [ ! -L "$HOME/.agents/skills/flare-plugin" ]; then
+  cp -R feature/plugin/sdk/skill/flare-plugin "$HOME/.agents/skills/flare-plugin"
+else
+  echo "flare-plugin already exists; follow Update or remove before replacing it."
+fi
+```
+
+Claude Code, for all local projects:
+
+```sh
+mkdir -p "$HOME/.claude/skills"
+if [ ! -e "$HOME/.claude/skills/flare-plugin" ] && [ ! -L "$HOME/.claude/skills/flare-plugin" ]; then
+  cp -R feature/plugin/sdk/skill/flare-plugin "$HOME/.claude/skills/flare-plugin"
+else
+  echo "flare-plugin already exists; follow Update or remove before replacing it."
+fi
+```
+
+For a project-only installation, copy the same `flare-plugin/` folder into the
+**plugin project's** `.agents/skills/` (Codex) or `.claude/skills/` (Claude Code).
+Use the plugin project's path, even when your source checkout is elsewhere.
+Choose one scope per agent to avoid loading duplicate copies. The expected
+layout is `<skills-directory>/flare-plugin/SKILL.md`, with resources beside it.
+
+### Verify discovery and invoke
+
+1. Check the installed folder contains `SKILL.md`, `flare-plugin.d.ts`,
+   `references/manifest.md`, `assets/github-template/plugin.js`, and
+   `examples/pixelfed/plugin.js`.
+2. In Codex CLI or its IDE extension, use `/skills` or type `$` and select
+   `flare-plugin`. If it is missing, restart Codex and check the installation
+   location. In Claude Code, type `/flare-plugin`; if a newly created skills
+   directory is not discovered, run `/reload-skills` or start a new session.
+3. Run a read-only check before creating a plugin:
+
+   ```text
+   Use the flare-plugin skill. Read its bundled references and template.
+   Explain the required files for a GitHub plugin and the available login methods,
+   and identify the template's illustrative endpoints. Do not create or publish files.
+   ```
+
+   Confirm the agent reads resources from the installed directory and identifies
+   `/api/me` and `/api/posts` as illustrative. This checks discovery and access,
+   not the correctness of a future website integration.
+
+For actual work, prefix your request with `$flare-plugin` in Codex CLI/IDE or
+`/flare-plugin` in Claude Code. Natural-language requests can also trigger the
+skill when they match its description. See the current official
+[Codex instructions](https://learn.chatgpt.com/docs/build-skills) and
+[Claude Code instructions](https://code.claude.com/docs/en/skills) for discovery
+locations, invocation, and client-specific behavior. These local installations
+do not automatically install the skill in a remote or cloud agent environment.
+
+### Update or remove
+
+To update, select the desired source revision and review its changes. Back up the
+existing installed `flare-plugin` folder **outside all skill discovery directories**,
+preserving any local edits, then replace it with the complete new folder. With
+Codex's installer, move the old folder out before reinstalling; it does not
+overwrite an existing installation. Avoid merging copies: removed reference
+files would otherwise remain. Repeat the discovery check after replacement.
+
+To remove, delete or move out only the installed `flare-plugin` folder from the
+location you chose. Restart the agent if its menu still shows it. Updating or
+removing this skill does not change generated plugin repositories or plugins
+already installed in Flare.
+
+### Use without installing
+
+An agent with access to this checkout can follow an explicit request to read
+`feature/plugin/sdk/skill/flare-plugin/SKILL.md` and its referenced files. This
+works for a single task; it does not register a discoverable skill. Keep the
+entire folder accessible rather than pasting only the entrypoint into chat.
+
+## Use with an AI coding agent
+
+Start with a request such as:
+
+> Use the flare-plugin skill to create a plugin for [website / HTTPS API origin].
+> Implement [features] using [login method]. Here are the API documentation and
+> redacted example responses: [sources]. First map these features to Flare
+> capabilities and list any missing API information. Then create a GitHub-ready
+> repository, validate the available paths, and explain installation and any
+> remaining integration work.
+
+For an existing plugin:
+
+> Use the flare-plugin skill to add [feature] to this repository. Preserve its
+> plugin and platform IDs and existing features. Inspect the current manifest,
+> implementation, and website API before editing. Update the capability mapping,
+> documentation, and relevant checks, and explain the version/schema implications.
+
+Provide API docs, authenticated-profile and content responses, paging examples,
+and authentication details relevant to the requested feature. Remove real tokens,
+passwords, Cookies, and private user content. Tell the agent which errors or edge
+cases matter. It should identify gaps rather than invent website endpoints.
+
+## Start a plugin repository
+
+1. Copy the contents of [assets/github-template](assets/github-template/README.md)
+   to a new repository root. Its example website contract needs adaptation; no
+   demonstration server is required or provided.
+2. Choose stable plugin/platform IDs, replace the placeholder icon, and adapt
+   authentication and data mapping to your website. See [manifest](references/manifest.md)
+   and [authentication](references/authentication.md).
+3. Implement the required capability methods and map the responses into
+   [Wire data](references/wire-data.md). The starter uses token import and a
+   read-only timeline whose posts open their website URLs.
+4. Use [Desktop plugin development](references/testing.md#develop-locally-in-desktop)
+   to validate and reload a local directory. Follow the other testing checks, then
+   commit the ready-to-run `plugin.js` and publish a public GitHub repository with a stable version tag.
+5. In Flare's plugin management, enter `https://github.com/OWNER/REPO` and click
+   **Install**. Flare downloads the latest stable version and shows its source and
+   permissions in the same dialog. Confirm installation to use the plugin immediately.
+   Follow the plugin's README to select the platform, origin, and login method.
+
+See [publishing](references/publishing.md) for exact tag rules and updates. Flare
+reads the tagged repository root; a subdirectory in the Flare repository itself
+is not a plugin installation URL. A GitHub Release or `.fpp` upload is unnecessary.
+
+## Reference and example index
+
+| Need | Reference |
+| --- | --- |
+| Agent workflow | [SKILL.md](SKILL.md) |
+| Boundary contract and registration | [ABI.md](ABI.md) |
+| Exact JavaScript signatures and field comments | [flare-plugin.d.ts](flare-plugin.d.ts) |
+| Manifest fields, defaults, enums, and validation | [Manifest](references/manifest.md) |
+| All twelve capabilities, minimum methods, and UI requirements | [Capabilities](references/capabilities.md) |
+| Platform engines, async completion, HTTP, permissions, credentials, and state | [Runtime and HTTP](references/runtime-http.md) |
+| Detection and all five login methods | [Authentication](references/authentication.md) |
+| DTO mapping, pagination, media, and opaque tokens | [Wire data](references/wire-data.md) |
+| Capability implementations, guest, localization, and Deep Links | [Recipes](references/recipes.md) |
+| Errors, resource limits, and recovery | [Troubleshooting](references/troubleshooting.md) |
+| Author checks, Host tests, and acceptance evidence | [Testing](references/testing.md) |
+| GitHub publication, upgrades, and optional local installation | [Publishing](references/publishing.md) |
+| Complete website adapter | [Pixelfed](examples/pixelfed/README.md) |
+
+Rules have one canonical reference; the skill links to it when needed. Recipe
+fragments explain adaptation points and are not separate installable plugins.

package/skill/flare-plugin/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: flare-plugin
+description: Create, extend, debug, and prepare GitHub distribution for Flare Social Plugin API v1 plugins. Use when implementing a website adapter, editing a Flare plugin manifest or classic JavaScript entrypoint, adding login or datasource capabilities, or diagnosing Flare plugin installation and runtime errors.
+---
+
+# Flare Plugin
+
+Produce a website adapter that matches Flare's API v1 contract and can be installed
+from a public GitHub repository. Use the user's chosen website and requested
+features. This skill includes the SDK; resolve links relative to this file, not
+to the user's plugin repository.
+
+## Establish the contract
+
+1. Inspect an existing plugin before changing it. For a new plugin, collect the
+   target HTTPS origin, requested features, login method, API documentation, and
+   representative redacted responses. Public API documentation may supply missing
+   information. Identify unresolved endpoint, authentication, identity, or paging
+   assumptions before implementing the affected feature.
+2. Read [manifest](references/manifest.md), [capabilities](references/capabilities.md),
+   and [runtime/HTTP](references/runtime-http.md). Map requested features to
+   capability IDs, their required operations, service method paths, and UI entry
+   points. Declare only supported behavior, including any required companion
+   operations. A function's TypeScript optionality does not relax manifest rules.
+3. Use [flare-plugin.d.ts](flare-plugin.d.ts) for exact signatures and [ABI.md](ABI.md)
+   for the boundary contract. Preserve API v1 behavior. If the target Flare build
+   has a different contract, establish its version before generating code; there
+   is no implied released-app minimum version in this skill.
+
+## Implement the requested adapter
+
+Start a new repository from [the GitHub template](assets/github-template/README.md).
+Copy the **contents** of `assets/github-template/` to the new repository root.
+Its `/api/me` and `/api/posts` contract is illustrative, not a live service. Adapt
+it from verified website evidence before presenting it as an integration.
+Use [Pixelfed](examples/pixelfed/README.md) as a complete real-service example,
+not as a universal API specification.
+
+Read the references needed for the task:
+
+| Task | Read |
+| --- | --- |
+| Detection, OAuth, password, token import, form, Cookie, credential refresh | [Authentication](references/authentication.md) |
+| Map remote entities, HTML, media, identity, cursor pagination, opaque tokens | [Wire data](references/wire-data.md) |
+| Implement any of the twelve capabilities, guest access, actions, Deep Links, localization | [Recipes](references/recipes.md) and the relevant [capability row](references/capabilities.md) |
+| Diagnose a rejected package, missing UI, failed request, or retired runtime | [Troubleshooting and limits](references/troubleshooting.md) |
+| Check the generated files and exercise behavior | [Testing](references/testing.md) |
+| Prepare a GitHub repository, version tag, update, or schema change | [Publishing](references/publishing.md) |
+
+Keep `plugin.js` a self-contained classic script and call `definePlugin` once.
+Use `flare.http.request` with structured authorization/Cookies; retain credentials
+through the Host account credential API. Map remote data explicitly into Wire
+DTOs. Do not add fields to the ABI or assume browser/Node globals exist. Perform
+Host calls inside registered methods, not during script initialization.
+
+The manifest, registered methods, and login's negotiated capabilities must agree.
+Keep account IDs stable, use the selected origin for authenticated identity, and
+treat globals as disposable cache. Use typed `flare.error` results for expected
+remote failures. Request media permission only when the adapter returns remote
+media. Keep actual secrets out of source, examples, logs, and repository history.
+
+## Validate and deliver
+
+Follow [testing](references/testing.md): check syntax, manifest/method agreement,
+representative mapping and paging behavior, and available real Host validation.
+For an existing plugin, recheck the behavior changed by the edit. State what ran
+and what still needs the target website or Flare UI; syntax checks and mocked
+responses do not prove live integration.
+
+Prefer GitHub distribution: one plugin at repository root, an already-built
+`plugin.js`, and a stable version tag matching `manifest.version`. Prepare files
+and release instructions; create/push repositories, commits, or tags only within
+the user's current authorization. See [publishing](references/publishing.md) for
+immediate activation, uninstall cleanup, and the optional local `.fpp` path.
+
+Deliver the complete repository files, feature-to-capability mapping, setup and
+installation instructions, checks performed, and remaining assumptions. A new
+adapter is ready for use only when its documented website contract and required
+runtime paths have been exercised; otherwise identify the unfinished integration
+steps precisely.

package/skill/flare-plugin/assets/github-template/README.md

@@ -0,0 +1,71 @@
+# Example Feed plugin template
+
+This is a GitHub repository template for a token-based Flare API v1 adapter.
+The website API below is an **illustrative contract**, not an available service.
+Adapt the paths, authentication, and mapping to your website before publishing.
+No demonstration server is included. Tests in Flare exercise this template with
+fixture HTTP responses through the real QuickJS runtime.
+
+## Adapt the template
+
+1. Copy this directory's contents to your own repository root.
+2. Change `manifest.id`, `platform.id`, names, and description. Keep IDs stable
+   after publication. Replace the one-pixel placeholder PNG with your own icon.
+3. Adapt `plugin.js` using the Flare Plugin skill and your website's API evidence.
+   It currently verifies an imported bearer token with `/api/me`, then reads
+   `/api/posts`. It registers no detector, so choose the platform explicitly.
+4. Update this README with the actual website, token acquisition steps, supported
+   features, verification results, and remaining limitations.
+
+The template requests no media permission and emits text-only posts. Every post
+uses `detailType: "link"`, opening its HTTPS website URL. There is no arbitrary
+profile lookup, internal post detail, write capability, or guest access. The
+authenticated profile returned at login supplies the saved account identity.
+
+## Illustrative website API to replace
+
+The selected origin is an absolute HTTPS origin such as `https://api.example.org`
+with no path. Both requests use a structured bearer token. The imported token
+is accepted only after the profile request succeeds.
+
+`GET /api/me`:
+
+```json
+{ "id": "alice", "username": "alice", "name": "Alice" }
+```
+
+`GET /api/posts?limit=20` and subsequent `&cursor=<encoded opaque cursor>`:
+
+```json
+{
+  "items": [{
+    "id": "post-1",
+    "author": { "id": "alice", "username": "alice", "name": "Alice" },
+    "created_at": "2026-01-01T00:00:00Z",
+    "text": "A post from the website",
+    "url": "https://example.org/posts/post-1"
+  }],
+  "next_cursor": "page-2"
+}
+```
+
+`next_cursor` is omitted or null at the end. Empty pages may still contain a next
+cursor. IDs are strings and stable across requests; request cursors never become
+entity IDs. A refresh starts without the old cursor. Adapt these assumptions to
+the actual API, including token expiry and rate-limit responses. The helper maps
+401/404/429 to typed errors, treats other HTTP failures as `Remote`, and parses
+the response's string `body` explicitly.
+
+## Publish and install after adaptation
+
+- Commit `manifest.json`, the self-contained `plugin.js`, one `assets/icon.png` (or JPEG/WebP/GIF/ICO), and
+  any `locales/*.json` at the root of a public GitHub repository.
+- Publish a stable tag matching the manifest version, initially `v0.1.0`.
+- In Flare plugin management, install `https://github.com/OWNER/REPO`, confirm the
+  review. The plugin becomes available immediately. A GitHub Release or `.fpp` asset is not required.
+- Select your platform and HTTPS API origin, then import a real access token.
+  Verify that the saved account, Home timeline, pagination, and link clicks work.
+
+Publish later changes under a new version tag. Keep tokens and Cookies out of
+the repository. Describe separately which checks passed with fixtures and which
+passed against the actual website and Flare UI.

package/skill/flare-plugin/assets/github-template/manifest.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "dev.example.flare.feed",
+  "version": "0.1.0",
+  "name": "Example Feed",
+  "description": "Adapt this token-based feed template to your website API",
+  "platform": {
+    "id": "ExampleFeed",
+    "name": "Example Feed",
+    "loginMethods": [{
+      "id": "token",
+      "interaction": "CredentialImport",
+      "title": "Import an access token",
+      "fields": [{ "id": "token", "type": "Secret", "label": "Access token" }]
+    }],
+    "capabilities": {
+      "flare.datasource.timeline/v1": {
+        "operations": { "page": { "directions": ["refresh", "older"] } }
+      }
+    },
+    "timelines": [{
+      "id": "home",
+      "title": "Home",
+      "icon": "Home",
+      "defaultForNewAccount": true
+    }]
+  }
+}

package/skill/flare-plugin/assets/github-template/plugin.js

@@ -0,0 +1,108 @@
+// Adapt the illustrative website contract in README.md before publication.
+definePlugin({
+  login: {
+    token: {
+      async begin(request, context) {
+        const token = request.values.token && request.values.token.trim();
+        if (!token) fail("Validation", "Enter an access token");
+        const profile = mapProfile(await requestJson(context.origin + "/api/me", token), context);
+        return {
+          type: "success",
+          value: {
+            accountId: profile.key.id,
+            origin: context.origin,
+            credential: { accessToken: token },
+            profile,
+            capabilities: { "flare.datasource.timeline/v1": ["page"] },
+          },
+        };
+      },
+    },
+  },
+  capabilities: {
+    timeline: {
+      async page(request, context) {
+        if (request.timelineId !== "home") fail("Unsupported", "Unknown timeline");
+        const credential = await flare.credential.read();
+        if (!credential || typeof credential !== "object" || Array.isArray(credential) ||
+            typeof credential.accessToken !== "string" || !credential.accessToken) {
+          fail("AuthenticationRequired", "Import your access token again");
+        }
+        let url = context.origin + "/api/posts?limit=" + request.page.limit;
+        if (request.page.direction !== "refresh" && request.page.cursor) {
+          url += "&cursor=" + encodeURIComponent(request.page.cursor);
+        }
+        const data = await requestJson(url, credential.accessToken);
+        if (!Array.isArray(data.items)) fail("InvalidResponse", "Expected a post array");
+        if (data.next_cursor != null && (typeof data.next_cursor !== "string" || !data.next_cursor)) {
+          fail("InvalidResponse", "Expected a non-empty cursor or null");
+        }
+        return {
+          items: data.items.map(post => ({
+            key: { id: requiredString(post && post.id), host: accountHost(context) },
+            author: mapProfile(post.author, context),
+            createdAt: requiredString(post.created_at),
+            content: { format: "plain", value: requiredString(post.text) },
+            detailType: "link",
+            url: requiredString(post.url),
+          })),
+          olderCursor: data.next_cursor,
+          endReached: data.next_cursor == null,
+        };
+      },
+    },
+  },
+});
+
+function accountHost(context) {
+  return context.origin.slice("https://".length);
+}
+
+function mapProfile(value, context) {
+  return {
+    key: { id: requiredString(value && value.id), host: accountHost(context) },
+    handle: requiredString(value.username),
+    displayName: requiredString(value.name),
+  };
+}
+
+function requiredString(value) {
+  if (typeof value !== "string" || !value.trim()) fail("InvalidResponse", "Missing required text field");
+  return value;
+}
+
+async function requestJson(url, token) {
+  let response;
+  try {
+    response = await flare.http.request({ url, authorization: { type: "bearer", token } });
+  } catch (error) {
+    if (error && error.code === "host.unavailable") fail("Network", "The request could not be completed");
+    throw error;
+  }
+  if (response.status === 401) fail("AuthenticationRequired", "The access token was rejected");
+  if (response.status === 404) fail("NotFound", "The requested resource was not found");
+  if (response.status === 429) {
+    const entry = Object.entries(response.headers).find(([name]) => name.toLowerCase() === "retry-after");
+    const value = entry && entry[1][0];
+    const seconds = value && /^\d+$/.test(value) ? Number(value) : undefined;
+    throw flare.error({
+      code: "RateLimited",
+      message: { value: "Try again later" },
+      retryAfterSeconds: typeof seconds === "number" && Number.isInteger(seconds) && seconds <= 604800 ? seconds : undefined,
+    });
+  }
+  if (response.status < 200 || response.status >= 300) fail("Remote", "The website returned an error");
+  let data;
+  try {
+    data = JSON.parse(response.body);
+  } catch (_) {
+    fail("InvalidResponse", "The website did not return JSON");
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) fail("InvalidResponse", "Expected a JSON object");
+  return data;
+}
+
+/** @param {PluginErrorCodeV1} code @param {string} message @returns {never} */
+function fail(code, message) {
+  throw flare.error({ code, message: { value: message } });
+}

package/skill/flare-plugin/examples/pixelfed/README.md

@@ -0,0 +1,78 @@
+# Pixelfed sample plugin
+
+This sample implements Pixelfed through Flare's Social Plugin API v1. It is a
+self-contained classic script and has no npm or runtime dependencies.
+
+Implemented features:
+
+- exact Pixelfed detection;
+- dynamic OAuth client registration and login;
+- Home, Discover, Local, Federated, Bookmarks, and Favourites timelines;
+- profile lookup, Posts/Gallery tabs, following/followers, and search;
+- post detail, context, delete, favourite, repost, and bookmark actions;
+- media upload and status publishing.
+
+Guest mode, lists, direct messages, notifications, and plugin Deep Links are
+intentionally omitted. The manifest exposes only the implemented capabilities
+and configuration. Custom plugin UI is unavailable in API v1.
+
+The manifest explicitly requests `mediaNetwork` so avatars and federated/CDN
+images can load. Installation review discloses that media destinations may
+receive this plugin's account data.
+
+## Develop locally in Desktop
+
+In Settings > Plugins > Plugin development, select this directory and start
+development. File edits are validated automatically; use **Reload plugin** to
+apply them. See [local development](../../references/testing.md#develop-locally-in-desktop)
+for account access, reload boundaries, and restoring the installed version.
+
+## Publish on GitHub and install
+
+Copy the contents of this directory to the root of your own public GitHub
+repository. Publish a stable tag `v0.1.0` matching `manifest.version`, then install
+the repository URL from Flare's plugin management. It becomes available immediately. The script
+is already built; a GitHub Release or uploaded `.fpp` asset is unnecessary.
+
+For a separately maintained fork, choose your own plugin ID and a distinct
+platform ID before release. The sample's `Pixelfed` platform ID cannot coexist
+with another registered platform of the same name. Keep IDs stable after users
+install the fork. See [GitHub publication and updates](../../references/publishing.md).
+
+This example cannot be installed by passing the Flare monorepo URL or a GitHub
+subdirectory URL: each installation repository must contain one root plugin.
+Actual server behavior may differ by Pixelfed version; report the instance and
+checks performed when claiming live compatibility.
+
+## Optional local package
+
+From the skill directory (the installed `flare-plugin` directory, or
+`feature/plugin/sdk/skill/flare-plugin` in a Flare checkout):
+
+```sh
+node pack.mjs examples/pixelfed /tmp/pixelfed-0.1.0.fpp
+```
+
+The output is deterministic: identical input bytes produce an identical `.fpp`.
+Install it from Flare's Settings > Plugins page, then continue with
+logging in. Local packages are unverified and should be reviewed before use.
+
+The bundled icon comes from Pixelfed's official
+[`brand-assets`](https://github.com/pixelfed/brand-assets) repository.
+
+## Read the implementation
+
+- `manifest.json`: static capabilities, timeline/profile tabs, compose defaults,
+  localized labels, and explicit media permission.
+- `plugin.js`: detection, OAuth registration/resume, structured HTTP, entity
+  mapping, cursor pagination, actions, and multipart publication.
+- `locales/`: English and Simplified Chinese catalogs. The SDK guides are English;
+  these catalogs demonstrate plugin localization.
+
+Use the [capability recipes](../../references/recipes.md) for features this sample
+does not implement and [testing](../../references/testing.md) for evidence levels.
+
+## Optional real-instance smoke test
+
+Set `PIXELFED_TEST_HOST` and `PIXELFED_TEST_TOKEN` when running the JVM tests.
+The test remains read-only unless `PIXELFED_TEST_ALLOW_WRITE=1` is also set.

package/skill/flare-plugin/examples/pixelfed/locales/en.json

@@ -0,0 +1,24 @@
+{
+  "error.authentication": "Sign in to Pixelfed again",
+  "error.invalidResponse": "Pixelfed returned an invalid response",
+  "error.network": "Unable to reach the Pixelfed instance",
+  "error.notFound": "The requested Pixelfed content was not found",
+  "error.rateLimited": "Pixelfed is rate limiting requests",
+  "error.remote": "Pixelfed rejected the request",
+  "error.unsupported": "This Pixelfed operation is not supported",
+  "error.validation": "Pixelfed rejected the request",
+  "login.oauth": "Continue with Pixelfed",
+  "login.oauth.description": "Authorize Flare in your browser",
+  "platform.description": "A federated image sharing platform",
+  "platform.name": "Pixelfed",
+  "plugin.description": "Pixelfed support implemented as a Flare social plugin",
+  "plugin.name": "Pixelfed Sample",
+  "profile.gallery": "Gallery",
+  "profile.posts": "Posts",
+  "timeline.bookmarks": "Bookmarks",
+  "timeline.discover": "Discover",
+  "timeline.favourites": "Favourites",
+  "timeline.federated": "Federated",
+  "timeline.home": "Home",
+  "timeline.local": "Local"
+}

package/skill/flare-plugin/examples/pixelfed/locales/zh-Hans.json

@@ -0,0 +1,24 @@
+{
+  "error.authentication": "请重新登录 Pixelfed",
+  "error.invalidResponse": "Pixelfed 返回了无效响应",
+  "error.network": "无法连接到 Pixelfed 实例",
+  "error.notFound": "找不到请求的 Pixelfed 内容",
+  "error.rateLimited": "Pixelfed 暂时限制了请求频率",
+  "error.remote": "Pixelfed 拒绝了请求",
+  "error.unsupported": "此 Pixelfed 操作不受支持",
+  "error.validation": "Pixelfed 拒绝了请求",
+  "login.oauth": "使用 Pixelfed 继续",
+  "login.oauth.description": "在浏览器中授权 Flare",
+  "platform.description": "联邦式图片分享平台",
+  "platform.name": "Pixelfed",
+  "plugin.description": "通过 Flare Social 插件实现的 Pixelfed 支持",
+  "plugin.name": "Pixelfed 示例插件",
+  "profile.gallery": "相册",
+  "profile.posts": "帖子",
+  "timeline.bookmarks": "书签",
+  "timeline.discover": "发现",
+  "timeline.favourites": "喜欢",
+  "timeline.federated": "联邦",
+  "timeline.home": "首页",
+  "timeline.local": "本地"
+}