npm - @lacneu/wix-openclaw - Versions diffs - 0.2.1 → 0.3.1 - Mend

@lacneu/wix-openclaw 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CHANGELOG.md +497 -2
package/README.md +94 -8
package/dist/config.d.ts +1 -0
package/dist/config.js +16 -1
package/dist/config.js.map +1 -1
package/dist/hooks/approval.d.ts +10 -0
package/dist/hooks/approval.js +301 -18
package/dist/hooks/approval.js.map +1 -1
package/dist/index.d.ts +1348 -8
package/dist/index.js +47 -18
package/dist/index.js.map +1 -1
package/dist/tools/_factory.d.ts +26 -2
package/dist/tools/_factory.js.map +1 -1
package/dist/tools/blog.d.ts +11 -11
package/dist/tools/bookings.d.ts +5 -5
package/dist/tools/contacts.d.ts +5 -5
package/dist/tools/data.d.ts +5 -5
package/dist/tools/design.d.ts +1 -1
package/dist/tools/events.d.ts +3 -3
package/dist/tools/faq.d.ts +5 -5
package/dist/tools/forms.d.ts +2 -2
package/dist/tools/media.d.ts +2 -2
package/dist/tools/multilingual.d.ts +2 -2
package/dist/tools/reviews.d.ts +3 -3
package/dist/tools/seo.d.ts +199 -0
package/dist/tools/seo.js +836 -0
package/dist/tools/seo.js.map +1 -0
package/dist/tools/site.d.ts +2 -2
package/dist/types.d.ts +11 -0
package/dist/wix-client.js +30 -4
package/dist/wix-client.js.map +1 -1
package/openclaw.plugin.json +106 -5
package/package.json +5 -5

package/CHANGELOG.md CHANGED Viewed

@@ -5,7 +5,501 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-## [Unreleased]
+## [0.3.0] - 2026-08-28
+Nine `wix_seo_*` tools, **off by default**, close the gap that made this plugin
+able to manage a site's *content* but not to look at its SEO. Turn them on with
+`enableSeoTools: true`.
+**One fix here affects every existing install, whether or not you want the SEO
+tools:** approval prompts were too long for the gateway to accept, so every
+approval-gated tool was blocked without the operator ever being asked. See
+*approval prompts were too long for the gateway to show at all* below.
+The three SEO read paths were verified against a live Wix site; the four writing
+paths were deliberately left unexercised. Everything else recorded under this
+version is work on code that had not shipped before — it is written down because
+the reasoning is the point, not because anyone was affected by it.
+### Added — SEO: auditing a site, and managing its URL redirects
+> **These tools are OFF by default and must be opted into with
+> `enableSeoTools: true`.** Every Wix endpoint behind them is in Developer
+> Preview: Wix may change them at any time and states they shouldn't be used on
+> live sites. Four of them also write irreversibly the moment they succeed.
+**Permission.** All nine sit behind a single Wix scope,
+`SCOPE.PROMOTE.MANAGE-SEO` — shown untranslated in the Wix UI, under *All site
+permissions*, between *Social Posts* and *Import orders*. Wix publishes no
+read-only SEO scope, so a key that can audit a site can also delete its
+redirects: the read/write boundary is `enableSeoTools` plus the approvals, not
+the key. The three read paths were verified live against a real site; the four
+writing paths were deliberately left unexercised.
+Nine tools under `wix_seo_*`, closing the gap that made the plugin able to
+manage a site's *content* but not to look at its SEO.
+**Audit.** `wix_seo_list_item_tags` is the entry point: pass `STATIC_PAGE` and
+it enumerates the site's pages, each with the tags it sets itself, whether it
+sets any (`hasOverride`), and the tags it is expected to render with — every one
+marked with where it came from (the item, its host page, a customised pattern,
+Wix's own pattern, or the site). Other item types are `BLOG_POST`,
+`STORES_PRODUCT` and `WIX_DATA_PAGE_ITEM-{pageId}`. `wix_seo_get_item_tags` and
+`wix_seo_get_site_tags` read one item and the site-wide tags.
+**Redirects.** List, get, create, delete, and both bulk forms.
+### Two limits stated in the tool descriptions, not just the docs
+*A static page reads as its SAVED revision, never the published one*, and
+`publishStatus` is always `PUBLISH_STATUS_UNSPECIFIED` for one — Wix exposes no
+path to read the published revision back. The description says so, because an
+agent that doesn't know it will report on a draft as though it were the live
+page. `resolvedTags` likewise omits whatever site code and apps add at render
+time, so it is not the page's rendered `<head>`.
+### Changed — `wix_seo_create_redirect` is approval-gated, like the deletes
+Creating a redirect is destructive by construction. Redirects do not chain: when
+an existing redirect **starts at** the path a new one points to, that existing
+redirect is deleted so the create can proceed — no flag asked for, and no way
+back. `options.forceReplace` deletes a second one. Gating by verb would have
+left the most damaging call in the set ungated.
+### Fixed — approval prompts were too long for the gateway to show at all
+The gateway declares an approval's `title` as 1–80 characters and its
+`description` as 1–256 (`PluginApprovalRequestParamsSchema`). The prompt this
+plugin built embedded a 600-character parameter preview under a paragraph of
+boilerplate, so it could not fit — and an over-long request is not truncated,
+it fails validation. **Every approval-gated tool was affected, not only the new
+ones**: the operator was never asked, and the call was blocked.
+The description is now BUILT to that budget rather than written and hoped for,
+ordered by what decides a refusal: the irreversible effect first, then the site
+the call actually lands on (the old preview stripped `siteId`, so on a
+multi-site key the operator never saw which tenant), then the parameters that
+matter, then everything else until the budget runs out.
+A redirect is shown with its SCOPE — exact or group, and its language or `all`
+— because the paths alone made an exact French-only rule and a global group rule
+over a whole branch read identically, while the second can make far more pages
+unreachable. That applies to a bulk create's members too, which had been going
+through the generic JSON path: up to 500 group rules over whole branches read
+the same as 500 exact ones. A batch also reports a count PER SCOPE over every
+member, and its sample leads with the widest rules. Its size and fingerprint are
+their own part of the prompt, so a long scope breakdown can be dropped without
+taking the batch's identity with it — sampling in request order
+put three exact rules on screen while the global group ones sat inside an
+opaque fingerprint. A list reports its size, a few of its members and a stable
+fingerprint of the whole set — reporting only a count made two bulk deletes of completely
+different GUIDs read identically. Long values are shortened in the middle, so
+two paths sharing a prefix stay distinguishable, and a value that still cannot
+fit is skipped rather than ending the rendering, which is how `from` and `to`
+could disappear from a prompt entirely. A test asserts both limits for every
+gated tool, at the largest values Wix itself accepts.
+### Changed — a redirect create REFUSES rather than silently destroying
+Creating a redirect deletes an existing one that starts at the path the new one
+points to — redirects do not chain — and `forceReplace` deletes the one holding
+the same `from` path. Neither is reported by the API, and telling the agent to
+check first only made it advice: a direct call, or a model that skipped the
+instruction, still lost a redirect nobody had named.
+`wix_seo_create_redirect` and `wix_seo_bulk_create_redirects` now list the
+site's redirects themselves and refuse, naming each redirect they would delete
+and why, until the caller repeats those GUIDs back in `acknowledgeDeletions`.
+Trailing-slash and case differences count as the same path, as Wix treats them.
+A create that destroys nothing goes straight through.
+### Changed — the destructive preflight compares what Wix STORES, and fails closed
+Three ways the check could be walked around, all closed:
+- **Language prefixes.** Wix stores a language-scoped redirect without its
+  prefix — a `fr` redirect from `/fr/about` comes back as `/about`. Comparing
+  the caller's path against the stored one found nothing, so a language-scoped
+  deletion went through unannounced. Paths are now normalised the way Wix
+  stores them, against the language of BOTH sides: a global create pointing at
+  `/fr/blog` is aiming at the public path of a `fr` redirect stored as `/blog`,
+  and normalising only by the candidate's own language (none, there) left the
+  two looking unrelated. Scopes that cannot collide are skipped rather than
+  flagged.
+- **An unreadable list.** Anything that wasn't a `redirects` array — a 2xx the
+  client couldn't parse, a schema change, a proxy's own page — read as "this
+  site has no redirects", and the destructive write went out on the strength of
+  it. The call now refuses. The one answer a safety check must never invent is
+  the reassuring one.
+- **Concurrency.** The check and the write are two requests, so two concurrent
+  creates could each read a state without the other's redirect and the second to
+  land would delete the first's. Destructive writes are now serialised per
+  EFFECTIVE site — keying on the raw argument put an omitted `siteId` and the
+  same site named explicitly into two different queues, so the calls the lock
+  exists to order ran side by side. A change made in the Wix dashboard between
+  the read and the write is still possible — Wix offers no precondition to close
+  that — and the tool descriptions say so rather than promising otherwise.
+- **An entry the plugin cannot read.** Validating only that `redirects` was an
+  array closed the check at the top and left it open underneath: a preview
+  rename to `source` passes an array test, every `from` reads as undefined, no
+  conflict is found, and the write goes out on a list nobody understood. Each
+  entry is now checked before anything is computed from it.
+### Changed — an acknowledgement is tied to the redirect's CURRENT state
+`acknowledgeDeletions` took bare GUIDs, which were guessable: a caller could
+name one on the first call and never be shown what it destroys. Worse, an id
+outlives the redirect behind it — Wix lets a create supply its own GUID, so
+between a refusal and the retry the same id can point somewhere else, and the
+acknowledgement would authorise deleting something the user never saw.
+The refusal now hands back a `token` derived from the redirect's id, paths,
+language and group flag, **and the effective site**, HMAC'd with a secret minted
+once per process. It cannot be produced without having listed, it stops matching
+the moment the redirect changes — in which case the call refuses again with the
+new one — and a token earned on one site does not unlock its twin on another.
+Two allowed sites can hold an identical redirect, since Wix accepts
+caller-supplied GUIDs, and a cross-site replay would have authorised a deletion
+on a tenant whose state nobody was shown.
+### Changed — the two kinds of bulk loop are told apart, and only one is guarded
+An intermediate version of this work refused any batch whose members looped on
+each other, on the assumption that one would delete the other. The reference says
+otherwise: an item closing a loop with an EARLIER item of the same request fails
+on its own with `REDIRECT_LOOP` and the rest of the batch goes ahead — nothing
+is deleted. That guard blocked migrations Wix would have applied in part, and
+told the operator redirects would be lost when none would. It is gone.
+What remains guarded is the deletion the reference does document: an item that
+closes a loop with a redirect ALREADY ON THE SITE is created and that redirect is
+deleted. The tool description now states both cases separately.
+The declared bound also drops from 500 to **100** for bulk create, which is what
+the method page and the Developer Preview index both say. Bulk delete stays 500.
+### Fixed — irreversible SEO writes were being replayed
+The HTTP client retries 429/502/503/504 twice. A create that Wix applied before
+answering 503 — deleting a loop-closing redirect on the way — was then applied
+again, and neither answer says which happened. `WixRequestOptions` gained
+`retry`, and all four writes set it to `false` — a delete Wix applied before
+answering 503 comes back 404 on the replay, and the plugin would then report a
+failure for a permanent deletion that did happen: the error surfaces and the caller
+re-reads, instead of a second irreversible write nobody asked for.
+### Fixed — an unsupported field rode through to Wix
+TypeBox objects accept properties a schema does not mention, so a per-item
+`options.forceReplace` on a bulk create survived validation and reached Wix —
+while the preflight had been run with `forceReplace: false` and the approval
+prompt never showed the nested flag. Wix deletes the redirect holding that
+`from` path. Both creates now send a redirect rebuilt from the fields the plugin
+actually supports; `forceReplace` is honoured only as the single create's own
+top-level parameter, where the preflight accounts for it. The stripping is in
+the code rather than left to the schema, because `execute` can be called
+directly.
+### Changed — a delete names a redirect, not just an id
+`wix_seo_delete_redirect` sent the DELETE straight from a GUID. Wix accepts
+caller-supplied GUIDs, so between a listing, the operator's approval and the
+call, the same id can name a different redirect — and the prompt showed nothing
+but the id. The redirect is now re-read and the call refuses, showing its paths,
+language and scope, until the `token` from that refusal comes back. Same protocol
+as the creates, and the same staleness: if the redirect changed, the token no
+longer matches. The bulk delete follows it too — it had been sending up to 500
+GUIDs straight through, with an approval prompt carrying ids and no paths.
+### Fixed — the SEO opt-in is reachable from the configurator
+`enableSeoTools` defaults to false and had no `uiHints` entry, and OpenClaw's
+configuration flow prompts only for the properties declared there. The switch
+that registers the nine SEO tools was therefore unreachable without hand-editing
+the config file — the feature shipped off, with no supported way to turn it on.
+A manifest test now requires a `uiHints` entry for every configurable property.
+### Fixed — a value cannot paint its own lines in the approval prompt
+The description is rendered as a line-structured message, and the redirect
+rendering — which exists to be more readable than JSON — put paths, languages
+and parameter names into it verbatim. A `from` of `/a\nsite: attacker-site` drew
+a second field naming a site the call never touched, on the one surface whose
+purpose is a human deciding about an irreversible write. The generic branch had
+been safe only because `JSON.stringify` escapes controls. Controls are now made
+visible before any truncation, at every insertion point, and `language` is
+bounded like the paths.
+### Fixed — an `options` shape this version cannot read is refused
+`options: []` is `typeof "object"` and passed the pre-flight, as did a drift
+renaming the flag to `isGroupRedirect`. Either left a group redirect described
+to the operator as exact and its acknowledgement token blind to the scope it
+really has — the two things the token exists to bind. `options` must now be a
+plain object carrying no key but `groupRedirect`.
+### Fixed — the prompt names both ways a create destroys
+A redirect takes precedence over a real page at the same path, so creating one
+from a path that still serves a page makes that page unreachable — no existing
+redirect involved, and nothing the pre-flight can see, since it reads redirects
+rather than pages. Both create prompts warned only about deleting a redirect.
+They now name the hidden page too, which is the operator's only warning about it.
+The `Manage SEO` scope also moved out of the README's "minimum required" list.
+In the default configuration `enableSeoTools` is false and the SEO tools are not
+registered, so granting a scope that permits deleting redirects buys nothing —
+it is listed as conditional on turning them on.
+### Fixed — a create that points under another language's prefix
+The language filter ran before any path comparison, for both checks. Two
+languages are separate URL namespaces, so that is right for a create pointing
+inside its own — refusing there would block a create that destroys nothing. But
+a caller can write the other language's prefix explicitly: an `en` redirect
+pointing at `/fr/blog` names the public entry of the `fr` redirect Wix stores as
+`/blog`, and the filter dropped that pair before the comparison that would have
+recognised it, so the deletion went unannounced. That case is now detected; none
+is taken away. Two related questions upstream does not answer — whether a group
+redirect resolves a loop for destinations merely UNDER its `from`, and how the
+two languages compare in general — are recorded in the code as known bounds
+rather than guessed at, because settling them needs a create and a delete
+against a live site.
+A global redirect — one with no `language` — applies to every language, so it is
+also entered at `/de/blog` and not only at `/blog`. Against such a rule the scope
+comparison always "overlaps", which is precisely what kept the foreign-prefix
+check from running, and a create pointing at `/de/blog` closed a loop with it
+unannounced. The site's configured languages cannot be read here (that endpoint
+needs a different scope and can answer 403), so a leading segment SHAPED like a
+language tag is now recognised. It errs towards announcing: a `/fr/...` that is
+really a content folder costs one acknowledgement, and the operator sees exactly
+which redirect is named.
+### Fixed — the create describes the protocol it implements
+Two sentences of `wix_seo_create_redirect`'s description sent a model down paths
+the code refuses: it named Wix's own `options.forceReplace` — the nested flag
+this plugin strips, so the create would have failed as if the flag were never
+set — and it asked for the doomed redirects' GUIDs, where the acknowledgement
+protocol takes the `token` from the refusal and rejects a bare id. The behaviour
+was right throughout; only the contract a model reads before acting was wrong,
+which no behavioural test could catch. Both are corrected, the bulk create says
+`token` explicitly too, and a test now holds the descriptions to it.
+### Fixed — the pre-flight trusts a listing only when it understands all of it
+The destructive pre-flight refused a redirect listing whose entries had no
+string `from`, but the acknowledgement token also binds `id`, `to`, `language`
+and `groupRedirect`, substituting a default for whatever is absent. A drift that
+renamed or dropped `to` — a stated possibility on a Developer Preview API —
+therefore degraded the token into one that no longer changed when the redirect's
+destination did, and a stale acknowledgement would have authorised a permanent
+deletion. Every field the token binds is now checked, scope fields for shape.
+### Fixed — the write lock forgets, and the audit pages as the endpoint defines
+`serializedBySite` kept one settled promise per site id it had ever been given.
+The key is caller-supplied and queued BEFORE the whitelist rejects it, so a
+long-lived gateway retained an entry for every string ever passed — the comment
+already claimed the chain was dropped "once it is the last one"; now the code
+does it, and only while it is still the tail.
+`wix_seo_list_item_tags` advertised the shared GET paging envelope, `offset`
+included, on an endpoint that pages by cursor alone. The schema is now
+cursor-only AND the query is built from those two keys: narrowing a TypeBox
+object does not strip what it omits, and `execute` can be called directly, so
+an `offset` arriving at runtime would still have been forwarded.
+The smoke test no longer probes the SEO endpoints unless `WIX_SMOKE_SEO=1`.
+They would otherwise have demanded `SCOPE.PROMOTE.MANAGE-SEO` — a scope that
+also permits deleting redirects — of every key, including the default
+configuration where the SEO tools are not even registered.
+### Fixed — a refusal names the whole loss, and the protocol converges
+Every refusal listed only the redirects still lacking an acknowledgement, while
+`howToProceed` asked for "every token above". The phrase therefore named a
+different set on each round: a caller that REPLACED its token list rather than
+extending it alternated between halves and never got through, so a legitimate
+multi-redirect deletion was impossible. The shrinking list also understated the
+loss — the second prompt showed fewer deletions than the first. All three
+multi-target refusals (single create, bulk create, bulk delete) now list the
+complete set, each entry carrying `acknowledged: true | false`.
+### Fixed — an omitted parameter is always marked as omitted
+The approval description reserved room for the ` · …` marker only until the
+first part was dropped, and stopped reserving exactly when the marker had become
+certain. Parts after that drop filled the 256-character budget to the brim and
+the final truncation cut the marker off, so a prompt that had silently dropped a
+parameter read as complete — on the destructive calls where it matters. Room is
+now reserved from the first drop onwards, and trailing parts are surrendered if
+that is what it takes for the marker to survive.
+The approval fingerprint moved from a 32-bit FNV to SHA-256 truncated to 128
+bits, over a key-sorted serialisation. The old one was small enough to collide
+deliberately — two batches whose sampled members matched then produced identical
+prompts for two different permanent deletions — and insertion-order
+serialisation gave the same batch different identities depending on how its
+fields happened to be written.
+### Fixed — SEO writes ignored cancellation
+The tool factory hands each run an `AbortSignal` and the HTTP client honours it,
+but the SEO tools never took it. A destructive write can sit behind another
+site-write for as long as that one takes, so an irreversible POST could go out
+after the runtime had already reported the operation cancelled. The signal is
+now checked after the queue and again immediately before the write, and passed
+to every request — the five READ tools had never declared it either, so a
+cancelled audit went on waiting, retrying and spending quota. The retry backoff
+is interruptible too: a plain timer meant an abandoned call still sat out the
+whole wait, which `Retry-After` can make long, before noticing.
+### Fixed — the manifest tests were checking a list they maintained themselves
+`test/manifest.test.ts` re-listed the tool domains instead of reading what the
+plugin registers, so adding a whole domain left its guards passing over the new
+tools without seeing them. Registration now goes through a single exported
+`buildAllTools()` that the tests read, and two guards were added: `contracts.tools`
+must name exactly the registered tools, and the manifest's `approvalRequired`
+default must match the code's.
+### Fixed — the build no longer depends on a package nobody declared
+`src/tools/_factory.ts` imported the `AgentToolResult` type from
+`@mariozechner/pi-agent-core`, which was never a dependency of this plugin: it
+arrived only because `openclaw` happened to pull it in. Upstream dropped it
+(absent from 2026.6.x onwards), so the import resolved on a machine holding an
+older tree and nowhere else — a fresh install compiled no more.
+The shape is now declared in the plugin itself. `openclaw/plugin-sdk/agent-core`
+re-exports the same type, but that subpath only exists from 2026.5.28 while this
+plugin supports `>=2026.5.0`: importing it would have quietly dropped the bottom
+of the declared range. The local declaration holds across the whole of it, and
+the structural check still happens where it matters — at `registerTool`, against
+whichever SDK is installed. Verified compiling at both ends of the range, 2026.5.2
+and 2026.6.34.
+Two related repairs came with it. The default export is now annotated
+(`ReturnType<typeof definePluginEntry>`): its inferred type reached into an
+openclaw build-internal chunk that TypeScript cannot name from a declaration
+file (`TS2742`). And `package-lock.json`, stale at `0.1.1` since that release,
+is regenerated — `npm ci` had been failing on every run since, silently falling
+back to `npm install`, which is why a dependency that had quietly vanished
+upstream went unnoticed until now.
+### Migration
+For instance owners on `@lacneu/wix-openclaw@0.2.2`:
+1. `openclaw plugins update @lacneu/wix-openclaw` — **`update`, not
+   `install`**: `install` rewrites `plugins.entries.wix-openclaw` with the
+   manifest's defaults, discarding the API key, the site whitelist and any
+   `approvalRequired` you have tuned. `update` preserves them.
+2. Restart the gateway container. This release adds no environment variable, so
+   a `restart` is enough — no `--force-recreate` needed.
+3. Verify in the boot log:
+   `wix-openclaw: ready — 50 tool(s) registered`.
+Fifty, not fifty-nine: the SEO tools are not registered until you opt in. Nothing
+else changes, and the approval fix applies as soon as the plugin loads — a gated
+tool that used to fail without asking will now put its prompt to the operator.
+To add the SEO tools:
+1. Tick **Manage SEO** (`SCOPE.PROMOTE.MANAGE-SEO`) on the Wix API key used by
+   that instance. Its label
+   is untranslated in the Wix UI — it sits under *All site permissions*, between
+   *Social Posts* and *Import orders*. There is no read-only variant: the same
+   permission that allows the audit also allows deleting redirects.
+2. Set `enableSeoTools: true` — via the configurator, which prompts for it as
+   *Enable SEO tools (audit + URL redirects)*, or with
+   `openclaw config set plugins.entries.wix-openclaw.config.enableSeoTools true`.
+   `update` carries your existing config forward and the new field simply
+   defaults to `false`, so nothing turns on by surprise.
+3. Restart, and expect `59 tool(s) registered`.
+4. Read the Developer Preview warning at the top of this section before pointing
+   any of the four writing tools at a live site.
+## [0.2.2] - 2026-05-03
+### Fixed — OpenClaw 2026.5.x compatibility
+OpenClaw 2026.5.2 introduced a manifest contract for plugin tool
+ownership: tools registered via `api.registerTool(...)` are
+**rejected at runtime** with the error
+`plugin must declare contracts.tools before registering agent tools`
+when the plugin manifest does not declare them.
+Without this release, `@lacneu/wix-openclaw` loads on 2026.5.x but
+all 50 of its `wix_*` tools are silently rejected at registration —
+the plugin runs hooks but exposes 0 tools to the agent.
+### Added — `contracts.tools` (50 entries)
+`openclaw.plugin.json` now declares every tool the plugin owns
+under `contracts.tools` as a flat array of strings. Mirrors the 50
+tools registered by `registerWixPlugin(api)`:
+- 11 blog tools (drafts CRUD, publish/unpublish, posts, categories, tags)
+- 6 bookings (services list, query, create, get, cancel, reschedule)
+- 1 business info
+- 6 contacts CRUD + label + query
+- 6 wix data CRUD (collections, items)
+- 1 design brief
+- 3 events (list, get, list_guests)
+- 5 FAQ (list categories/questions, create/update/delete question)
+- 2 forms (list submissions, get submission)
+- 2 media (list, upload)
+- 2 multilingual (list languages, list schemas)
+- 3 reviews (list, get, moderate)
+- 2 sites (list, url get)
+### Added — `activation.onStartup: true`
+Per the OpenClaw 2026.5.x manifest spec, external plugins should
+declare an explicit activation policy. `onStartup: true` ensures
+the plugin is loaded at gateway startup so its tools are
+discoverable when the agent resolves its tool inventory.
+### Added — `toolMetadata._default.configSignals`
+Tells OpenClaw's tool descriptor planner that every tool in this
+plugin requires both `apiKey` and `accountId` to be configured at
+`plugins.entries.wix-openclaw.config`. The platform skips loading
+the plugin runtime when these are missing — cheap availability
+check at reply startup.
+### Changed — compat aligned to 2026.5.0
+- `package.json#openclaw.compat`:
+  `pluginApi: ">=2026.4.0"` → `">=2026.5.0"`,
+  `minGatewayVersion: "2026.4.0"` → `"2026.5.0"`.
+- `peerDependencies.openclaw` and `devDependencies.openclaw`:
+  `">=2026.4.0"` → `">=2026.5.0"`.
+### Migration
+For instance owners on `@lacneu/wix-openclaw@0.2.1` running
+OpenClaw 2026.5.x:
+1. `openclaw plugins install @lacneu/wix-openclaw@0.2.2 --force`
+2. Restart the gateway container.
+3. Verify in the boot log:
+   `wix-openclaw: ready — 50 tool(s) registered`.
+4. Verify with `openclaw plugins inspect wix-openclaw --runtime --json`:
+   `"toolNames"` should list the 50 `wix_*` tools.
+### Note on agent tool inventory bug
+OpenClaw 2026.5.2 has a separate regression (issue #76598) that
+prevents plugin tools from appearing in the per-agent tool
+inventory even when the plugin is correctly installed and registered.
+Fixed in commit `a3b94f39109d` on 2026-05-03 — pending in 2026.5.3.
+Symptom: `tools.alsoAllow` listing the wix tools logs as
+`unknown entries` despite the plugin being loaded. No client-side
+workaround; await the upstream release.
 ## [0.2.1] - 2026-04-29
@@ -157,5 +651,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Release workflow using **npm Trusted Publishing (OIDC)** — no `NPM_TOKEN`
   secret required, provenance attached automatically.
-[Unreleased]: https://github.com/OlivierNeu/wix-openclaw-plugin/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/OlivierNeu/wix-openclaw-plugin/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/OlivierNeu/wix-openclaw-plugin/compare/v0.2.2...v0.3.0
 [0.1.0]: https://github.com/OlivierNeu/wix-openclaw-plugin/releases/tag/v0.1.0

package/README.md CHANGED Viewed

@@ -15,10 +15,10 @@
 ## Overview
 `wix-openclaw` is an OpenClaw plugin that lets your agent operate a Wix site
-through the official Wix REST API. It registers ~50 tools split across a dozen
+through the official Wix REST API. It registers ~60 tools split across a dozen
 Wix products (Blog, CMS Data, Forms, Bookings, Contacts, Events, Reviews, FAQ,
-Multilingual, Sites, Site Media), plus a `wix_design_brief` helper that turns
-loose textual briefs into structured markdown artefacts.
+Multilingual, Sites, Site Media, SEO), plus a `wix_design_brief` helper that
+turns loose textual briefs into structured markdown artefacts.
 Every tool funnels through a single authenticated HTTP client that:
@@ -175,6 +175,19 @@ should stay unticked.
 Tick these only if the corresponding Wix product is actually in use on
 the target site:
+- [ ] **Manage SEO** (`SCOPE.PROMOTE.MANAGE-SEO`) — **only if you set
+  `enableSeoTools: true`.** In the default configuration the SEO tools are not
+  registered at all, so granting this scope would hand the key the power to
+  delete redirects for tools that cannot run. Wix exposes a **single** SEO
+  scope, not a read/write pair: ticking it grants redirect creation and deletion
+  along with the read-only audit, so there is no such thing as an audit-only SEO
+  key. In the Wix UI the checkbox sits under **All site permissions**, between
+  *Social Posts* and *Import orders*; its label is currently untranslated and
+  renders literally as `site.scope.SCOPE.PROMOTE.MANAGE-SEO.name`. Since Wix
+  cannot narrow it, the read/write boundary is enforced by this plugin instead —
+  the four writing tools require an approval naming every redirect they would
+  destroy.
 - [ ] **Pricing Plans** — if you sell subscription packages
 - [ ] **Wix Stores** + **Wix eCommerce** — if you sell physical/digital
   products. Without these, the `wix_*` tools that touch e-commerce
@@ -225,6 +238,7 @@ columns and remove the matching tools from your agent's allow-list.
 | `wix_reviews_*` | Wix Reviews | Reviews moderation |
 | `wix_faq_*` | Manage FAQ | FAQ tooling |
 | `wix_multilingual_*` | Multilingual Translation Schema Read | Translation reads |
+| `wix_seo_*` (all nine) | Manage SEO (`SCOPE.PROMOTE.MANAGE-SEO`) | SEO audit **and** redirect changes — Wix has no read-only SEO scope, so this one permission covers both |
 | `wix_design_brief` | _(none — no API call)_ | Always |
 ### Wix app installation requirements
@@ -237,7 +251,7 @@ working as soon as the app is installed (no plugin upgrade needed).
 | Tool group | Wix app required | Error returned when missing |
 |---|---|---|
 | `wix_blog_*` | Wix Blog | `404` |
-| `wix_data_*` | Velo / Wix Code (enable in Editor) | `400 WDE0110: Wix Code not enabled` |
+| `wix_data_*` | Wix CMS (Velo / Wix Code — enable in Editor) | `400 WDE0110: Wix CMS app is not installed for site` |
 | `wix_forms_*` | Wix Forms | `404` |
 | `wix_bookings_*` | Wix Bookings | `404` |
 | `wix_events_*` | Wix Events | `428 WIX_EVENTS_APP_NOT_INSTALLED` |
@@ -338,7 +352,9 @@ site; `app-not-installed` and `velo-not-enabled` mean the tool's
 endpoint exists but its backing Wix product is not active on the
 smoke-test site (the request still reaches Wix and the path/headers
 are correct); `docs` means write/destructive endpoints that we do not
-exercise live.
+exercise live. The SEO reads are skipped by the smoke test unless
+`WIX_SMOKE_SEO=1` is set, so a key without `SCOPE.PROMOTE.MANAGE-SEO` is not
+failed for lacking a scope the default configuration never uses.
 ### Blog
@@ -455,15 +471,85 @@ Requires the Wix FAQ app (returns `400 App is not installed` otherwise).
 ### Multilingual (read-only in V1)
-Returns `403` on the Ataraxis smoke-test site — likely missing the
-`Multilingual Translation Schema Read` permission on the API key
-rather than an app-not-installed condition.
+Returns `403` on the Ataraxis smoke-test site, with an EMPTY body. The earlier
+guess — a missing `Multilingual Translation Schema Read` permission — has since
+been ruled out: that permission is granted on the key and the `403` persists.
+What remains undetermined is whether the Wix Multilingual app is simply not
+installed, or whether these two endpoints also require the separate
+`SCOPE.MULTILINGUAL.MANAGE_TRANSLATIONS` scope. The empty body does not say, and
+neither answer has been tested.
 | Tool | What it does | Approval | Validated |
 |---|---|---|---|
 | `wix_multilingual_list_languages` | List configured languages; standard query envelope | — | 403-permission |
 | `wix_multilingual_list_schemas` | List translation schemas | — | 403-permission |
+### SEO
+> **Developer Preview, and OFF by default.** Every Wix endpoint behind these
+> nine tools is listed in Wix's
+> [Developer Preview](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-developer-preview)
+> — Item SEO Tags, Site SEO Tags and all six Redirects methods. Wix may change
+> them at any time, and states plainly that you **shouldn't use them on live
+> sites**: they are for testing and feedback. An API stays in preview for at
+> most six months.
+>
+> Nothing here registers unless you set `enableSeoTools: true` in the plugin
+> config. Four of the tools write irreversibly to the live site the moment they
+> succeed, so opting in is the operator saying they accept both risks.
+> _Preview status verified against the Wix reference on 2026-08-28._
+Auditing a site's SEO, and managing its URL redirects.
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_seo_list_item_tags` | List the items of one type with their SEO tags. `STATIC_PAGE` enumerates the site's pages. Reports `hasOverride`, the item's own `tags`, and `resolvedTags` marked with each tag's source. Cursor paging. | — | live |
+| `wix_seo_get_item_tags` | One item's tags, own and resolved | — | schema |
+| `wix_seo_get_site_tags` | Site-wide tags, plus dashboard verification embeds (read-only) | — | live |
+| `wix_seo_list_redirects` | Every redirect on the site. No filter, sort or paging — the endpoint takes none | — | live |
+| `wix_seo_get_redirect` | One redirect by GUID | — | schema |
+| `wix_seo_create_redirect` | Create a 301 redirect | **required** | schema |
+| `wix_seo_delete_redirect` | Delete one redirect (re-reads it and refuses until its token is acknowledged) | **required** | schema |
+| `wix_seo_bulk_create_redirects` | Create 1–100 redirects | **required** | schema |
+| `wix_seo_bulk_delete_redirects` | Delete 1–500 redirects | **required** | schema |
+**Three things to know before using these.**
+*A read of a static page is the SAVED revision, not the live one.* For
+`STATIC_PAGE`, `tags`, `focusKeywords` and `resolvedTags` always reflect the
+saved revision, and `publishStatus` is always `PUBLISH_STATUS_UNSPECIFIED` — the
+API has no path to read the published revision back. An audit report should say
+it is about the saved page. `resolvedTags` also omits anything site code or apps
+add while the page renders, so it is not a copy of the rendered `<head>`.
+*Creating a redirect can delete another one.* Redirects do not chain: if an
+existing redirect **starts at** the path a new one points to, that existing
+redirect is deleted and the create proceeds — no flag involved, no way back.
+The tool's own top-level `forceReplace` parameter additionally deletes a
+redirect holding the same `from` path. Wix documents that flag nested as
+`options.forceReplace`; do **not** send it there — the tool rebuilds the
+redirect from the fields it supports, so a nested flag is dropped and the create
+fails with `FROM_URL_EXISTS` as if it had never been set. This is why
+`wix_seo_create_redirect` is approval-gated by default
+alongside the deletes. A redirect also takes precedence over a real page at the
+same path, which makes that page unreachable.
+*The create refuses before it destroys.* `wix_seo_create_redirect` and
+`wix_seo_bulk_create_redirects` list the site's redirects themselves and refuse,
+naming each redirect they would delete — with its paths, language and whether it
+is a group rule — until the caller repeats the `token` from that refusal back in
+`acknowledgeDeletions`. The token is derived from the redirect's current state,
+so it cannot be guessed without listing and goes stale if the redirect changes.
+The check is in the execution path, not in the tool description, so a direct call
+gets it too, and it refuses outright rather than assuming an empty list when the
+redirects cannot be read. Destructive writes are serialised per site; a change
+made in the Wix dashboard between the read and the write remains possible.
+*There is no update method and no query method.* To change a redirect: get it,
+delete it, then create it carrying **every** field over — an omitted field is
+filled with its default, not its previous value. To find one, list them all and
+filter client-side.
 ### Design
 | Tool | What it does | Approval | Validated |

package/dist/config.d.ts CHANGED Viewed

@@ -6,6 +6,7 @@ import type { ResolvedWixConfig, WixPluginConfig } from "./types.js";
  * become empty strings to avoid leaking `undefined` into downstream code.
  */
 export declare function resolveEnv<T>(value: T): T;
+export declare const DEFAULT_APPROVAL_REQUIRED: string[];
 /**
  * Apply defaults and env substitution to the raw plugin config.
  *