flare-plugin-sdk 0.1.0-beta.2 → 0.1.0-beta.5

package/README.md

@@ -1,60 +1,151 @@
 # Flare Plugin SDK
 
-`flare-plugin-sdk` contains editor types, a local package command,
+`flare-plugin-sdk` contains a project initializer, editor types, a local package command,
 templates, examples, and a portable AI authoring skill for Social Plugin API v1.
 Flare provides the plugin runtime. Supported targets are Android, JVM Desktop,
 iOS, and native macOS, not Web. Use a Flare build that includes Plugins in Settings;
 this SDK does not promise a minimum public app release.
 
-## Install for development
+## Create a plugin
 
-Install the npm preview:
+With Node 22 or newer, run:
 
 ```sh
-npm install --save-dev flare-plugin-sdk@next
+npx flare-plugin-sdk@next init my-plugin
+cd my-plugin
 ```
 
-To validate a Flare checkout without publication, build a local tarball instead:
+This copies the GitHub template bundled with that SDK version into `my-plugin`:
 
-```sh
-cd feature/plugin/sdk
-npm ci
-npm test
-npm pack --pack-destination /tmp
+```text
+my-plugin/
+  manifest.json
+  plugin.js
+  assets/icon.png
+  README.md
 ```
 
-Install the resulting `.tgz` in your plugin project with
-`npm install --save-dev /path/to/flare-plugin-sdk-VERSION.tgz`.
-These local checks and packaging commands do not publish anything.
-
-## Create and develop a plugin
-
-1. Copy the contents of `node_modules/flare-plugin-sdk/skill/flare-plugin/assets/github-template/`
-   into your plugin repository. Replace its IDs, icon, and illustrative website
-   endpoints using evidence from the real API.
-2. Read the [complete developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin).
-   The same guide is bundled at `skill/flare-plugin/README.md` inside the npm package,
-   with all authentication, capability, runtime, data, testing, and publication references.
-3. Keep your ready-to-run `manifest.json`, classic-script `plugin.js`, one supported
-   `assets/icon.<extension>`, and optional `locales/*.json` in a plugin output directory.
-   For a TypeScript project, configure your bundler to produce that classic script.
-4. In Desktop or native macOS, select the output directory in Settings → Plugins →
-   Plugin development. Start development, then reload after edits or rebuilds.
-5. For local file installation, package that directory from your plugin project:
+The directory name becomes the plugin and platform display name. The initializer
+generates unique plugin/platform IDs; keep them stable after publication. New and
+empty directories are accepted, including `init .` in an empty current directory.
+Non-empty directories, files, and symbolic links are rejected without overwriting
+them. The command uses bundled files only and does not install dependencies,
+initialize Git, contact your website, or publish anything. Run
+`npx flare-plugin-sdk@next --help` for usage.
+
+Edit `plugin.js` to use your website's real authentication, endpoints, response
+mapping, and pagination. The starter's `/api/me` and `/api/posts` are illustrative;
+no demonstration server is included. Update the description, login methods and
+capabilities in `manifest.json`, and replace the placeholder icon. The plain
+JavaScript starter needs no dependency installation or build step.
+
+For manual template copies, replace the example IDs and names before use. For
+`npx` projects, keep the generated IDs. Read the
+[complete developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin)
+for authentication, Host APIs, capabilities, and Wire data mapping.
+
+## Develop and debug in Flare
+
+1. From `my-plugin`, check the source syntax:
+
+   ```sh
+   node --check plugin.js
+   node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
+   ```
+
+   Actual execution and manifest/registration validation happen in Flare, which
+   provides `definePlugin` and `flare`.
+2. In Compose Desktop or native macOS, open **Settings → Plugins → More → Plugin
+   development**. Choose the `my-plugin` directory, click **Start development**,
+   and confirm the access review.
+3. Add an account in Flare. Select your plugin platform explicitly, enter the
+   website's HTTPS API origin, and import a real access token using the starter's
+   login form. Adapt this step if you change the login method. Test login,
+   timeline refresh, older pages, end-of-list behavior, and website link clicks.
+4. Edit and save the files. Flare automatically validates changes; click **Reload
+   plugin** to apply the validated version. Invalid edits keep the last working
+   version running. The development panel shows validation errors and recent-call
+   diagnostics; recent calls contain method names and outcomes, without HTTP
+   request/response payloads.
+5. Click **Stop development** before installing or updating the same plugin.
+   Development temporarily overrides the running version; stopping restores the
+   previous version. App restarts do not automatically mount the directory.
+   Development uses real accounts and data, and remote writes are not rolled back.
+
+Finish active writes before reloading; credential-schema changes may require
+logging in again. For TypeScript, run your own compiler/watch command and
+select its output directory; Flare loads one self-contained classic `plugin.js`.
+See [development and testing details](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/testing.md#develop-locally-in-desktop).
+
+## Publish and install through GitHub (recommended)
+
+1. Create a public GitHub repository. Its tagged root must contain `manifest.json`,
+   the ready-to-run `plugin.js`, exactly one supported `assets/icon.<extension>`,
+   and optional `locales/*.json`. Update the project README with the actual website,
+   login instructions, supported features, and verification results. Flare reads
+   these files directly; commit any compiled output at the root before tagging.
+2. Commit and push the plugin files. For a new project and an empty GitHub
+   repository, replace `OWNER/REPO` and run from `my-plugin`:
+
+   ```sh
+   git init
+   git add manifest.json plugin.js assets README.md
+   # If used, also stage translations with: git add locales
+   git commit -m "Add Flare plugin"
+   git branch -M main
+   git remote add origin https://github.com/OWNER/REPO.git
+   git push -u origin main
+   ```
+
+   Use your existing Git setup if the project is already a repository. Keep real
+   credentials, private fixtures, `node_modules`, and build caches out of Git.
+3. Set a stable `manifest.version` and push a matching tag. The generated version
+   is `0.1.0`, so the first release can use:
 
    ```sh
-   npx flare-plugin-pack ./dist ./plugin.fpp
+   git tag v0.1.0
+   git push origin refs/tags/v0.1.0
    ```
 
-The packer accepts plugin files only, so keep source, `.git`, `package.json`,
-`node_modules`, and the generated `.fpp` outside `dist`. It checks archive structure;
-Flare still validates the manifest, registration, permissions, and runtime behavior.
-For GitHub installation, commit the ready-to-run plugin files at the repository
-root and publish a stable tag matching `manifest.version`. npm SDK versions and
-individual plugin versions are independent; GitHub plugin installation ignores
-prerelease tags even though the npm SDK can use them.
+   Commit and push any version edit before tagging. npm SDK versions are separate
+   from your plugin's version. Flare ignores prerelease plugin tags; pushing only
+   a branch does not create an installable version. A GitHub Release and `.fpp`
+   upload are unnecessary.
+4. Stop development, then open **Settings → Plugins → Add → Install from GitHub**
+   on any supported Flare platform. Enter `https://github.com/OWNER/REPO`, load the
+   latest stable version, and review its source and permissions before confirming.
+   Installation takes effect immediately. Add/log in to the plugin account and
+   verify its behavior on that device.
+5. For updates, increment `manifest.version`, commit and push, then publish a new
+   matching stable tag. Keep plugin/platform IDs unchanged. In Flare, check for
+   updates and review/confirm the offered version; app restart is unnecessary.
+
+See [GitHub publication and update rules](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/publishing.md).
+
+## Optional: package and install a local file
+
+Use `.fpp` for offline transfer or local testing when GitHub distribution is not
+needed. From your project, create a new, empty `dist` directory and copy only
+`manifest.json`, `plugin.js`, one `assets/icon.<extension>`, and any `locales/*.json`
+into it, preserving those paths. Keep source, `.git`, `package.json`, `node_modules`,
+and previous archives outside `dist`. Then run from the project root:
+
+```sh
+npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+```
+
+Stop development for this plugin. In **Settings → Plugins → Add**, choose file
+installation, select the `.fpp`, review, and confirm. Installation is immediate.
+Packaging checks archive structure; Flare still validates the manifest,
+registration, permissions, and behavior. File installs have no GitHub update tracking.
+
+## Optional: editor types and TypeScript
 
-## Editor types
+Install editor types in your authoring project:
+
+```sh
+npm install --save-dev flare-plugin-sdk@next
+```
 
 Add the package to your TypeScript project's compiler options:
 
@@ -85,11 +176,18 @@ All documentation is in English. The complete Pixelfed adapter is bundled at
 
 From `feature/plugin/sdk`, run `npm ci` and `npm test` with Node 22 or newer.
 The tests build an npm tarball, check its complete resource set and license,
-install it offline in an empty project, type-check an actual consumer, and run
-the installed package command against the bundled template. They do not contact
-a website or publish to npm. Flare's Host and platform acceptance checks are
+install it offline in an empty project, invoke the actual npx initializer,
+type-check a consumer, and package both the generated project and bundled template.
+Initializer tests cover valid unique IDs, empty/nested/Unicode paths, invalid
+arguments, and preserving existing directories, files, and symlinks. They do not
+contact a website or publish to npm. Flare's Host and platform acceptance checks are
 documented in `skill/flare-plugin/references/testing.md`.
 
+To try the SDK from a checkout before npm publication, run
+`npm pack --pack-destination /tmp` after those checks, then install the resulting `.tgz` in
+a separate authoring project with
+`npm install --save-dev /path/to/flare-plugin-sdk-VERSION.tgz`.
+
 ## Publish this SDK (maintainers)
 
 For the first publication, use the npm account that will own this unscoped package.
@@ -121,8 +219,8 @@ Public OIDC publications from this public repository receive provenance automati
 For subsequent releases:
 
 1. Update the SDK version and lockfile together, for example with
-   `npm version 0.1.0-beta.2 --no-git-tag-version`, and commit the tested changes.
-2. Tag that commit `plugin-sdk-v0.1.0-beta.2` and push only that tag when ready to publish.
+   `npm version prerelease --preid beta --no-git-tag-version`, and commit the tested changes.
+2. Tag that commit `plugin-sdk-v<version>` using the new version and push only that tag when ready to publish.
    The workflow rejects a tag that does not exactly match `package.json`.
 3. The workflow validates the tarball first, then publishes prereleases to `next`
    and stable versions to `latest`. Existing app workflows exclude SDK tags.

package/bin/cli.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const usage = "Usage: flare-plugin-sdk init <directory>";
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(usage);
+    return;
+  }
+  if (args.length !== 2 || args[0] !== "init" || !args[1] || args[1].startsWith("-")) {
+    throw new Error(usage);
+  }
+
+  const target = resolve(args[1]);
+  const name = basename(target);
+  if (!name.trim() || /[\u0000-\u001f\u007f]/.test(args[1])) {
+    throw new Error("Choose a directory name without control characters or blank text");
+  }
+  const metadata = await lstat(target).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (metadata && (!metadata.isDirectory() || metadata.isSymbolicLink() || (await readdir(target)).length)) {
+    throw new Error("Destination must be a new or empty directory, not a file or symbolic link");
+  }
+
+  const template = fileURLToPath(new URL("../skill/flare-plugin/assets/github-template/", import.meta.url));
+  const manifestPath = join(template, "manifest.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const identity = randomUUID().replaceAll("-", "");
+  manifest.id = `local.plugin.p${identity}`;
+  manifest.name = name;
+  manifest.platform.id = `Plugin${identity}`;
+  manifest.platform.name = name;
+
+  await mkdir(target, { recursive: true });
+  for (const entry of await readdir(template)) {
+    if (entry === "manifest.json") continue;
+    await cp(join(template, entry), join(target, entry), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    });
+  }
+  await writeFile(join(target, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+
+  console.log(`Created ${target}\nPlugin ID: ${manifest.id}\nPlatform ID: ${manifest.platform.id}`);
+  console.log("Adapt the example API in plugin.js and README.md, then load this directory in Flare's Plugin development.");
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flare-plugin-sdk",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.5",
   "description": "Types, tooling, templates and authoring references for Flare plugins",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/DimensionDev/Flare#plugins-beta",
@@ -13,10 +13,12 @@
     "url": "https://github.com/DimensionDev/Flare/issues"
   },
   "bin": {
+    "flare-plugin-sdk": "bin/cli.mjs",
     "flare-plugin-pack": "skill/flare-plugin/pack.mjs"
   },
   "types": "skill/flare-plugin/flare-plugin.d.ts",
   "files": [
+    "bin/",
     "skill/flare-plugin/"
   ],
   "engines": {

package/skill/flare-plugin/README.md

@@ -161,25 +161,39 @@ 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
+1. With Node 22 or newer, create the starter:
+
+   ```sh
+   npx flare-plugin-sdk@next init my-plugin
+   cd my-plugin
+   ```
+
+   It generates unique plugin/platform IDs and needs no dependency installation
+   or build step for plain JavaScript. For manual copies of
+   [assets/github-template](assets/github-template/README.md), replace its example
+   IDs and names first. The example API needs adaptation; no demonstration server
+   is provided.
+2. Keep the generated IDs stable, 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
+   to start the local directory, test an account, and apply saved edits with
+   **Reload plugin** after automatic validation. Follow the syntax, behavior and
+   platform checks. Stop development before installing/updating the same plugin.
+5. Prefer GitHub distribution: commit the ready-to-run files at a public repository
+   root, then push a stable tag matching `manifest.version`. In Flare's plugin
+   management, enter `https://github.com/OWNER/REPO` and click **Install**. Review
+   source and permissions, then confirm to use the plugin immediately. Follow the
+   plugin's README to select the platform, origin, and login method.
+
+The generated [project README](assets/github-template/README.md) contains the full
+adaptation, local debugging, Git setup/tagging, GitHub installation and update path.
+See [publishing](references/publishing.md) for exact tag rules, updates, and
+[optional local `.fpp` installation](references/publishing.md#optional-local-installation).
+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

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

@@ -6,15 +6,21 @@ 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. Adapt the plugin
 
-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.
+If you created this project with `npx flare-plugin-sdk@next init my-plugin`, work
+inside `my-plugin` and keep its generated plugin/platform IDs. If you copied the
+template manually, first copy its contents to your repository root and replace
+the example `manifest.id`, `platform.id`, and names. Keep IDs stable for updates.
+
+1. Update the description, login methods, and declared capabilities in
+   `manifest.json`. Replace the one-pixel placeholder PNG with your own icon.
+2. Adapt `plugin.js` using the
+   [developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin)
+   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
+3. 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
@@ -22,6 +28,112 @@ 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.
 
+## 2. Develop and debug locally
+
+The plain JavaScript starter needs Node 22 or newer for tooling, with no dependency
+installation or build step. From this project directory, check syntax:
+
+```sh
+node --check plugin.js
+node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
+```
+
+Flare supplies the `definePlugin` and `flare` globals and performs the actual
+manifest, registration, and runtime checks. Use a Flare build with Plugins in Settings.
+
+1. In Compose Desktop or native macOS, open **Settings → Plugins → More → Plugin
+   development**. Choose this directory, click **Start development**, and confirm
+   the access review.
+2. Add an account, explicitly select this plugin platform, and enter your website's
+   HTTPS API origin. Import a real access token. After adapting the endpoints,
+   verify the account identity, Home refresh, older/empty/end pages, and link clicks.
+3. Edit and save `plugin.js`, `manifest.json`, the icon, or translations. Flare
+   automatically validates them; click **Reload plugin** to apply the validated
+   version. Invalid edits leave the previous working version running.
+4. Check validation errors and recent-call diagnostics in the development panel.
+   Recent calls show method names and outcomes, without HTTP request/response
+   payloads. Reproduce authentication, HTTP, response-mapping, and paging failures
+   against your website's documented API.
+5. Click **Stop development** before installing or updating this plugin. Stopping
+   restores the version that was running before development; app restarts do not
+   automatically mount this directory. Development uses real accounts and data,
+   and remote writes are not rolled back.
+
+For TypeScript, run your own compiler/watch process and select its output directory.
+Emit one self-contained classic `plugin.js`; Flare provides its Host APIs rather
+than Node/browser APIs. Commit that built script at the repository root for release.
+See [development and testing details](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/testing.md#develop-locally-in-desktop)
+for reload restrictions, credential changes, and platform acceptance checks.
+
+## 3. Publish and install through GitHub (recommended)
+
+Create a public GitHub repository with these ready-to-run files at its root:
+
+```text
+manifest.json
+plugin.js
+assets/icon.png
+README.md
+locales/en.json       # optional; other locale catalogs as needed
+```
+
+The icon can also be JPEG, WebP, GIF, or ICO; keep exactly one supported icon.
+Development files may coexist in the repository, but keep credentials,
+`node_modules`, build caches, and private fixtures out of Git. Flare reads the
+committed plugin files directly, so build TypeScript before committing/tagging.
+
+For a new project and an empty GitHub repository, replace `OWNER/REPO` and run:
+
+```sh
+git init
+git add manifest.json plugin.js assets README.md
+# If used, also stage translations with: git add locales
+git commit -m "Add Flare plugin"
+git branch -M main
+git remote add origin https://github.com/OWNER/REPO.git
+git push -u origin main
+```
+
+Use the existing Git setup if the project is already a repository. The generated
+`manifest.version` is `0.1.0`. After pushing the matching commit, publish its stable tag:
+
+```sh
+git tag v0.1.0
+git push origin refs/tags/v0.1.0
+```
+
+If you changed the manifest version, commit/push it and use that exact version
+after the optional lowercase `v`. npm SDK versions and plugin versions are
+independent. Flare ignores prerelease plugin tags; a branch alone is insufficient.
+A GitHub Release and uploaded `.fpp` asset are unnecessary.
+
+Stop development, then in **Settings → Plugins → Add → Install from GitHub** enter
+`https://github.com/OWNER/REPO`. Load the latest stable version, review its source
+and permissions, and confirm. Installation takes effect immediately. Select the
+plugin platform, HTTPS API origin, and real access token to verify it on each target
+device. For later updates, increment `manifest.version`, commit/push, and publish
+a new matching stable tag while preserving IDs. Check for updates in Flare and
+review/confirm the new version. See the
+[publication and update rules](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/publishing.md).
+
+## Alternative: package a local file
+
+Use `.fpp` for offline transfer or local testing. Create a new, empty `dist`
+directory and copy only `manifest.json`, `plugin.js`, one supported
+`assets/icon.<extension>`, and any `locales/*.json` into it, keeping those paths.
+Keep `.git`, `package.json`, `node_modules`, tests, and old archives outside `dist`.
+From this project directory, run:
+
+```sh
+npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+```
+
+Stop development for this plugin, then choose file installation in **Settings →
+Plugins → Add**, select the `.fpp`, review, and confirm. It becomes available
+immediately. The packer checks archive structure; Flare still validates the
+manifest, registration, permissions, and behavior. Local file installs have no
+GitHub source/update tracking.
+
 ## Illustrative website API to replace
 
 The selected origin is an absolute HTTPS origin such as `https://api.example.org`
@@ -56,16 +168,5 @@ 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.
+Describe separately which checks passed with fixtures and which passed against
+the actual website and Flare UI. Keep tokens and Cookies out of the repository.

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

@@ -26,7 +26,9 @@ 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.
+   name, description, and placeholder icon before publication. For manual template
+   copies, replace the example plugin/platform IDs; keep the unique IDs generated
+   by `npx flare-plugin-sdk@next init my-plugin` stable.
    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
@@ -45,6 +47,10 @@ copy that example's contents into a repository you own first.
    retry. Successful installs take effect immediately; verify the installed
    tag/version and running behavior without restarting Flare.
 
+For a first release from a generated project, follow the complete Git setup,
+commit/push and tag commands in the [project walkthrough](../assets/github-template/README.md#3-publish-and-install-through-github-recommended).
+Stop development for the same plugin before installation or updating it.
+
 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.
@@ -95,17 +101,30 @@ 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:
+Use `.fpp` as an alternative for offline transfer or local testing. In your plugin
+project, create a new, empty `dist` directory. Copy only `manifest.json`, `plugin.js`,
+one supported `assets/icon.<extension>`, and optional `locales/*.json` into it,
+preserving those paths. From the project root:
+
+```sh
+npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+```
+
+The complete skill also includes the standard-library-only packer for use without
+npm. For example, 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
+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.
+not full manifest/registration/behavior validation.
+
+Stop development for this plugin, then in **Settings → Plugins → Add** choose file
+installation, select the `.fpp`, review its source/permissions, and confirm. Local
+packages are unverified and still require review. Installation takes effect
+immediately; test the account and declared features on the target device. No
+GitHub source/update tracking is recorded, so later file updates require manually
+importing another package.