@jskit-ai/connectors-catalog 0.1.1

package/docs/wordpress-com.md

@@ -0,0 +1,358 @@
+# WordPress.com
+
+Import `wordpressComProvider` from
+`@jskit-ai/connectors-catalog/server/wordpress-com`. This fragment uses an own
+OAuth web registration for profile/site reads, post/page publishing and media management. It is distinct from
+self-hosted WordPress Application Password authentication.
+
+## Register and configure
+
+1. Sign into WordPress.com. Open the [Applications Manager](https://developer.wordpress.com/apps/)
+   and choose **Create New Application**.
+2. Enter its name and description and the exact backend **Redirect URL**, then
+   choose **Create**. Retain the Client ID and store the Client Secret privately.
+   [Provider's registration walkthrough](https://github.com/Automattic/rest-api-console#configuring-the-console).
+3. Put the secret in `WORDPRESS_COM_CLIENT_SECRET` and the full callback URL in
+   `WORDPRESS_COM_CALLBACK_URL`. Enter the ID and these references in the editor.
+4. Keep `users` for verification. Select `sites` for site listing and `posts` for
+   post reads and publishing. Save configuration, then start consent through the runtime.
+
+Server-to-server requests do not require each editor VM to be a JavaScript
+origin. Browser API access instead has its own configured-origin requirements;
+this fragment keeps provider tokens on the backend.
+[Browser access](https://developer.wordpress.com/docs/api/rest-api-javascript/).
+
+The OAuth flow uses `public-api.wordpress.com/oauth2/authorize` and
+`/oauth2/token`, with an exact registered redirect URI. It requests granular
+permissions rather than `global`; provider selection limits site access. The
+`posts` permission allows both reads and management; the application must authorize each publishing action.
+[OAuth and scopes](https://developer.wordpress.com/docs/api/oauth2/).
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "wordpress": {
+      "source": "own",
+      "clientId": "YOUR_ASSIGNED_CLIENT_ID",
+      "clientSecretRef": "env:WORDPRESS_COM_CLIENT_SECRET",
+      "callbackUrlRef": "env:WORDPRESS_COM_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "publishing": {
+      "provider": "wordpress-com",
+      "displayName": "Publishing account",
+      "accountMode": "per-user",
+      "scopes": ["users", "sites", "posts"],
+      "authentication": { "method": "oauth2", "registrationRef": "wordpress" }
+    }
+  }
+}
+```
+
+The editor offers shared, per-user and assistant ownership. Choose per-user
+when each application user connects independently. Select media permission to upload and manage attachments. Comments enables discussion and moderation operations. Stats provides the site summary; taxonomy provides category/tag management.
+Batch enables bounded read batches; each underlying resource remains subject to provider permissions.
+All five optional permission families default off. Configuration
+does not itself grant access or implement login.
+
+## Runtime and AI composition
+
+Use the [OAuth file-connection pattern](../patterns/oauth-connection/PATTERN.md).
+The provider adapter and connection lifecycle are imported JSKIT code. CLI and
+editor use the same JSON, with encrypted text runtime files outside source;
+no editor, database or generator is needed.
+
+Verification reads `/rest/v1.1/me` with a limited fields selection, including
+`token_scope`, `token_client_id` and `token_site_id`. These fields describe the
+issued token's permissions and ownership.
+[Profile response](https://developer.wordpress.com/docs/api/1.1/get/me/).
+The adapter rejects a mismatched client and retains only permissions present
+in the request, token response when supplied, and verified profile. Missing
+`users` permission fails verification without replacing an existing grant.
+It does not use a successful public post listing to authenticate the account.
+
+The runtime sends comma-separated scopes following the provider examples.
+It sends state and PKCE parameters; provider-side PKCE enforcement has not been
+established by these local tests. The documented code-token example has no
+expiry or refresh token. This adapter does not invent either: an explicit
+expiry without refresh or a later 401 requires consent again. An absent expiry
+does not promise permanent access. Local disconnect does not revoke the
+provider grant; manage provider access separately.
+
+`sites.list` accepts `site_visibility` (all/visible/hidden) and `site_activity`
+(all/active/inactive), both defaulting to all. It returns the accessible `sites`
+array in its provider envelope; no all-sites `global` grant is requested.
+[Sites](https://developer.wordpress.com/docs/api/1.1/get/me/sites/).
+
+```js
+const sites = await connections.invoke({ context, integrationId: "publishing", operation: "sites.list" });
+const page = await connections.invoke({
+  context, integrationId: "publishing", operation: "posts.list",
+  input: { siteId: 81, number: 20, status: "publish", context: "display" }
+});
+// If page.meta.next_page is present, pass it as page_handle on an explicit next call.
+```
+
+`posts.list` accepts a numeric site ID, `number` (1–100, default 20), an opaque
+`page_handle`, `search`, `status` and display/edit `context`. The result retains
+`found`, `posts` and `meta.next_page`; no next page is fetched automatically.
+[Post listing](https://developer.wordpress.com/docs/api/1.1/get/sites/$site/posts/).
+The fragment bounds cursor length to 4096 and search to 500 characters. Site
+domains/URLs are deliberately excluded from operation input. All authenticated
+requests stay on `public-api.wordpress.com`, redirects fail, and returned site
+URLs remain data. Applications own authorization and safe rendering of HTML.
+
+## Application ownership, callbacks and capacity
+
+An AI can prepare configuration, callback wiring and library composition.
+The reviewed registration instructions establish a dashboard flow, not a
+supported public API for provisioning OAuth clients. Initial registration and
+provider consent remain owner steps; do not invent a client-creation endpoint.
+
+The application owner creates the provider registration and stores its secret
+in the application's private Env. Public Vibe64, Vibe64 Online and CLI users use
+this same ownership model. The configuration file holds the client ID and Env
+references; the editor does not own the application's grants.
+
+Register the exact callback implemented by the application. For a hosted project,
+start with its assigned application URL and append the implemented callback path.
+Save that same URL through the application's callback Env reference. On a domain
+or host change, update both the provider registration and callback Env if the URL
+changes. Preserve the application's identity and persistent grant store when
+moving it; neither a new editor URL nor a new hosting address creates a new owner.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md) and
+[application setup command](../../connectors-core/docs/setup-command.md).
+
+Separate client IDs distinguish registration ownership and revocation. They do
+not prove independent quota pools: provider limits can include shared user/site
+or infrastructure boundaries. Automattic's guidelines prohibit excessive API
+traffic and allow access limits.
+[API usage guidance](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/).
+
+## Focused evidence
+
+Six provider tests use simulated HTTP and real encrypted JSON files. They cover
+client verification, reduced scopes, cancellation, replay, persistence, owner
+isolation, post paging, malformed replies and reconnect/error behavior. The
+shared OAuth test additionally proves that refresh cannot restore permissions
+removed during verification. Editor proof covers registration references,
+permission selections and reload. No live signup, consent, provider calls or
+sample-app generation are included. Login is not supplied. Publishing, media, comments, statistics, taxonomy and bounded batches have additional controlled fixtures; final package/UI acceptance is recorded separately.
+
+## Post and page publishing
+
+`posts.get` retrieves one numeric `siteId`/`postId`, defaulting to `context: edit`.
+`posts.create` takes a title plus optional content, excerpt, slug, status, type,
+parent, featured_image and publicize. Creation explicitly defaults to `draft`,
+`type: post` and `publicize: false`; `type: page` creates a page. `posts.list` can
+filter either type. The same update/delete/restore operations apply to both.
+
+`posts.update` requires a post ID and at least one changed field. It sends only
+the supplied changes, preserving empty content/excerpts and an empty
+`featured_image` to clear the attachment. Supply the attachment ID as a string
+to set it. Scheduling/custom types and combined upload-and-publish are not yet
+supplied. Publishing is explicit; the application owns who may publish and
+whether publicizing through external services is allowed.
+
+```js
+const draft = await connections.invoke({
+  context, integrationId: "publishing", operation: "posts.create",
+  input: { siteId: 81, type: "page", title: "Opening hours", content: "<p>9–5</p>" }
+});
+// After the application obtains the author's approval:
+await connections.invoke({
+  context, integrationId: "publishing", operation: "posts.update",
+  input: { siteId: 81, postId: draft.ID, status: "publish", publicize: false }
+});
+```
+
+A native framework makes authenticated form-encoded POSTs to
+`/rest/v1.1/sites/{siteId}/posts/new` and `/posts/{postId}` using the app-owned
+token. It must explicitly choose draft status at creation: the provider's own
+default is publish. Preserve text/HTML exactly in transport and apply suitable
+HTML handling in the application UI.
+[Create](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/posts/new/),
+[edit](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/posts/$post_ID/).
+
+`posts.delete` requires `confirmDeletion: true`. This is deliberately called
+delete, not trash: with trash enabled it normally trashes a post, but a second
+call can permanently delete it; sites without trash can delete immediately.
+Inspect the returned status and never blindly repeat an uncertain request.
+`posts.restore` returns a trashed post to its previous status, which may be
+published. The runtime performs no automatic write retries or rollback.
+[Delete](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/posts/$post_ID/delete/),
+[restore](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/posts/$post_ID/restore/).
+
+## Media workflow
+
+Select `media` before consent (reconnect if the current grant lacks it).
+`media.list` supports bounded `number`, opaque `page_handle`, `search`, `post_ID`
+and `mime_type`. It retains the provider envelope and `meta.next_page`; pass that
+value as a cursor, never fetch it as a URL. `post_ID: 0` finds unattached items.
+`media.get` takes a numeric mediaId. Returned media URLs are data, not automatically
+downloaded. The app owns access checks and safe image/HTML presentation.
+[Media listing](https://developer.wordpress.com/docs/api/1.1/get/sites/$site/media/).
+
+`media.upload` accepts one filename, MIME type and canonical `contentBase64`
+(up to 5 MiB decoded), plus title, caption, description, alt and parent_id. It
+encodes `media[0]` and `attrs[0][field]` multipart fields. It does not fetch file
+paths or supplied URLs. The provider enforces allowed types, account storage and
+upload permissions; this limit is the helper's memory bound, not a provider limit.
+A native framework can use its multipart HTTP client with these same field names
+and its app-owned Bearer token.
+
+```js
+const result = await connections.invoke({
+  context, integrationId: "publishing", operation: "media.upload",
+  input: { siteId: 81, filename: "hours.png", mimeType: "image/png",
+    contentBase64: imageBytes.toString("base64"), alt: "Opening hours" }
+});
+// Persist returned media IDs before any later operation, and present errors.
+if (Object.keys(result.media_errors ?? {}).length || result.media.length !== 1) {
+  // Let the author review partial results; do not automatically upload again.
+  return result;
+}
+await connections.invoke({
+  context, integrationId: "publishing", operation: "posts.update",
+  input: { siteId: 81, postId: draft.ID, featured_image: String(result.media[0].ID) }
+});
+```
+
+The result keeps `media` and `media_errors`, including a failed upload represented
+by an empty media array. A valid HTTP response alone does not mean every file
+was uploaded. If attachment succeeds and updating the draft fails, the app can
+retry only the post update or explicitly remove the orphan attachment; no
+automatic rollback is performed.
+[Upload](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/media/new/).
+
+`media.update` edits metadata sparsely; an empty alt/caption clears it and
+parent_id changes the attached post. `media.delete` requires
+`confirmDeletion: true` and permanently removes the item. It is not a trash
+action. No automatic retry, binary download, URL sideloading, multiple-file
+request or video-specific settings are supplied. The app may compose repeated
+explicit uploads and inspect each outcome.
+[Edit](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/media/$media_ID/),
+[delete](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/media/$media_ID/delete/).
+
+## Comments and moderation
+
+Select `comments` and reconnect if an existing grant lacks it. The provider
+still enforces the site's commenting and moderation permissions. The app owns
+its discussion screen, spam policy and which people can act as the connected
+account. A shared account does not identify every app user as a WordPress author.
+
+`comments.list` supports number (1–100), page, order and approved/unapproved/spam/
+trash/all status, returning the provider's count and comment records.
+`comments.get` reads one commentId. `comments.create` takes postId/content;
+`comments.reply` takes commentId/content. Both send the exact content using
+form encoding, and return the resulting moderation status. Creation may become
+public immediately under the site's rules; there is no local draft queue.
+[Listing](https://developer.wordpress.com/docs/api/1.1/get/sites/$site/comments/),
+[post reply](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/posts/$post_ID/replies/new/),
+[comment reply](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/comments/$comment_ID/replies/new/).
+
+`comments.update` requires an explicit status even when editing content, because
+the provider defaults to approval. Use unapproved to keep a comment under review,
+approved to publish, spam/unspam or trash/untrash for moderation. Unspam/untrash
+can restore visibility. `comments.delete` requires confirmDeletion: true; inspect
+the returned status because deletion may be permanent. Neither operation retries
+automatically. Author identity edits, hierarchical listing and likes are not
+supplied. The native-framework equivalent uses the same comments routes and
+form fields with the application's token.
+[Edit/moderate](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/comments/$comment_ID/),
+[delete](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/comments/$comment_ID/delete/).
+
+```js
+const queue = await connections.invoke({
+  context, integrationId: "publishing", operation: "comments.list",
+  input: { siteId: 81, status: "unapproved", number: 20, page: 1 }
+});
+// After an authorized moderator selects a comment:
+await connections.invoke({
+  context, integrationId: "publishing", operation: "comments.update",
+  input: { siteId: 81, commentId: selectedCommentId, status: "approved" }
+});
+```
+
+## Statistics and taxonomy
+
+Select `stats` and reconnect to read `stats.read({siteId})`. It preserves the
+provider's date, statistics and visits structures, including zero counts. The
+app should label the returned reporting date and render the returned metric
+keys; this is not live tracking, a scheduled collector or an analytics dashboard.
+Site/account entitlements still apply. Native frameworks use an authenticated
+GET to `/rest/v1.1/sites/{siteId}/stats`.
+[Site statistics](https://developer.wordpress.com/docs/api/1.1/get/sites/$site/stats/).
+
+Select `taxonomy` for `categories` and `tags` operations. Each supports list, get,
+create, update and delete. Lists accept number (1–1000), page and search. Get,
+update and delete use the returned termSlug, encoded as one path segment.
+Creation requires name, with optional description and a numeric parent for
+categories. Updates are sparse; deletion requires confirmDeletion: true. The
+provider owns default-category constraints and the effect on existing posts.
+Renaming may change the returned slug; use that new value for later requests.
+No automatic deletion recovery or term synchronization is supplied.
+
+```js
+const category = await connections.invoke({
+  context, integrationId: "publishing", operation: "categories.create",
+  input: { siteId: 81, name: "Opening hours", description: "Business news" }
+});
+await connections.invoke({
+  context, integrationId: "publishing", operation: "posts.update",
+  input: { siteId: 81, postId: draft.ID, categories: [category.ID] }
+});
+```
+
+Post create/update accepts existing numeric category/tag IDs, at most 100 each.
+These replace the supplied taxonomy selection; omitted fields stay untouched.
+Empty lists request clearing, subject to the site's default-category behavior.
+The app owns selecting IDs and retaining desired existing assignments. This
+post operation needs posts permission; managing the terms themselves needs
+taxonomy permission. Custom taxonomies are not supplied.
+
+Native frameworks use the same category/tag routes, form-encoded writes and
+`slug:{encodedSlug}` targets. Retain successful term creation if a later post
+assignment fails; retry the assignment explicitly instead of creating duplicates.
+[Category list](https://developer.wordpress.com/docs/api/1.1/get/sites/$site/categories/),
+[create](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/categories/new/),
+[edit](https://developer.wordpress.com/docs/api/1.1/post/sites/$site/categories/slug:$category/),
+[tag and taxonomy reference](https://developer.wordpress.com/docs/api/rest-api-reference/).
+
+## Read batches
+
+`batch.read` accepts siteId and one to six distinct resources selected from posts,
+media, comments, categories, tags and stats. It builds GET-only endpoint paths for
+one numeric site and requests 20 records per collection. It never accepts a URL,
+write action, arbitrary endpoint or cross-site batch. Use individual list calls
+for pagination/filtering and explicit writes for publishing. No transactional
+write batch exists in this helper.
+
+Select `batch` and the permissions for the resources you intend to read, then
+reconnect. Local invocation checks batch permission; WordPress.com checks access
+to each nested resource. The app must also authorize its resource selection and
+siteId; do not expose an unrestricted batch route to app users. The returned
+object keeps each endpoint's result or error. An outer success does not mean all
+reads succeeded, and this operation does not normalize or retry individual errors.
+
+```js
+const results = await connections.invoke({
+  context, integrationId: "publishing", operation: "batch.read",
+  input: { siteId: 81, resources: ["posts", "media"] }
+});
+for (const [endpoint, result] of Object.entries(results)) {
+  // Route provider errors to the app's feedback UI and render successful data.
+  if (result.error) showResourceError(endpoint, result.error);
+  else showResourceData(endpoint, result);
+}
+```
+
+Native frameworks send authenticated GET `/rest/v1.3/batch/` with repeated
+`urls[]` query values such as `/sites/81/posts?context=edit&number=20`. Paths are
+relative endpoints, not external URLs. The provider client returns results keyed
+by endpoint.
+[Batch API](https://developer.wordpress.com/docs/api/1.1/get/batch/),
+[current client](https://github.com/Automattic/wp-calypso/blob/trunk/packages/wpcom.js/src/lib/batch.js),
+[official archived composition test](https://github.com/Automattic/wpcom.js/blob/master/test/test.wpcom.batch.js).

package/docs/wordpress-self-hosted.md

@@ -0,0 +1,252 @@
+# WordPress (self-hosted)
+
+Import `wordpressSelfHostedProvider` from
+`@jskit-ai/connectors-catalog/server/wordpress-self-hosted`. It verifies an
+authenticated WordPress user and manages posts, pages, media and users under that
+account. It does not implement
+WordPress.com OAuth or application-user login.
+
+## Manual setup
+
+1. Sign into the HTTPS site's dashboard. Open **Users**, then edit the intended
+   user's profile. Record that user's login name.
+2. Find **Application Passwords**, enter a name such as `my-app-reader`, and
+   choose **Add New Application Password**. Copy the displayed password.
+3. Store it as `WORDPRESS_APPLICATION_PASSWORD` in the backend environment.
+   In the editor enter **Site URL**, **Username** and **Application password
+   reference** (`env:WORDPRESS_APPLICATION_PASSWORD`). Save configuration.
+
+Application Passwords authenticate through HTTPS Basic authentication and are
+available in WordPress core from 5.6. Use an Application Password rather than
+the user's interactive login password.
+[Authentication](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/).
+
+The profile shows each password's name and revocation control. Hosting or
+plugins can disable this facility; the administrator must enable the intended
+access if it is unavailable. The owning user's role remains relevant to which
+resources are accessible.
+[Application Passwords integration guide](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/).
+
+## Portable configuration and runtime
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "publishing": {
+      "provider": "wordpress-self-hosted",
+      "displayName": "Company posts",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:WORDPRESS_APPLICATION_PASSWORD"
+      },
+      "settings": {
+        "siteUrl": "https://publisher.example/blog/",
+        "username": "editor"
+      }
+    }
+  }
+}
+```
+
+`api-key` is the common credential-reference configuration method; the provider
+runtime turns this username/password pair into the correct Basic header. It
+never inserts the password into a URL or source file. The site URL includes
+the installation path but excludes `/wp-json`. Usernames reject colons and
+control characters and are limited to 60 characters by this fragment.
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with
+`providers: [wordpressSelfHostedProvider]`, environment resolution and the file
+connection store. CLI and editor share the same schema and JSON. Runtime state
+uses encrypted text files outside source. No database or editor is required
+by the consuming application.
+
+```js
+await connections.connectApiKey({ context, integrationId: "publishing" });
+const posts = await connections.invoke({
+  context, integrationId: "publishing", operation: "posts.list",
+  input: { page: 1, per_page: 20, status: "publish", context: "view" }
+});
+```
+
+Verification uses `GET /wp-json/wp/v2/users/me`, requiring a user object with
+an ID, name and slug. An unauthenticated public-post response cannot verify
+the account. `users.me` is also callable without input after connection.
+[User endpoints](https://developer.wordpress.org/rest-api/reference/users/).
+
+`posts.list` reads `/wp-json/wp/v2/posts`. Its default is ten published posts,
+page 1 and view context. Optional `search` filters results; draft/private reads
+require the owning user's access. Select `context: "edit"` explicitly when
+needed. The response includes provider fields such as rendered titles/content.
+[Posts](https://developer.wordpress.org/rest-api/reference/posts/).
+
+This fragment bounds `per_page` to 1–100, `page` to 1–100000 and search to 500
+characters. It accepts statuses publish/future/draft/pending/private and
+contexts view/edit/embed. It returns one array; pagination headers and automatic
+traversal are not exposed. An empty array is valid; malformed records and error
+objects fail validation. Returned HTML and links are data. The application owns
+safe HTML rendering and does not automatically fetch embedded links.
+
+The configured destination may be an operator-owned private HTTPS host or use
+a nondefault port. Embedded URL credentials, query strings, fragments and
+parent-path segments are rejected. This validation is not DNS/SSRF filtering:
+the application controls who can edit destinations and its outbound-network
+policy. Operations cannot supply another host; redirects fail instead of
+forwarding credentials. Changing site, path or username requires verification
+again. Updating the environment binding rotates the password. Disconnect
+removes local state; revoke the provider password separately.
+
+## Posts and pages publishing
+
+Both `posts` and `pages` expose `.get`, `.create`, `.update` and `.trash`.
+`pages.list` accepts the same page/per_page/search/context inputs as posts,
+with publish/draft/pending/private status filters. All requests use the configured
+site and installation path, authenticate with its Application Password and rely
+on WordPress to enforce that user's capabilities. A successful `users.me` check
+does not establish permission to edit or publish.
+
+- `.get`: positive integer `id` and optional view/edit/embed `context`.
+- `.create`: nonempty `title`, optional `content`, `excerpt`, `slug`, `status`,
+  `featured_media`, `comment_status`; omitted status creates a draft.
+- `.update`: `id` and at least one of those fields. Omitted fields remain
+  untouched. Empty content/excerpt clears it; `featured_media: 0` removes the
+  featured image. Page operations also accept `parent` (0 for none) and
+  `menu_order` (signed integer).
+- `.trash`: `id`; sends DELETE with `force=false`. Permanent deletion cannot be
+  requested through this operation. A site with trash disabled can reject it.
+
+Supported write statuses are draft/pending/private/publish. Scheduling, custom
+post types/fields, taxonomy editing and permanent deletion are not provided by
+these operations. Raw content and excerpt whitespace is preserved, including
+block markup. The framework must handle authoring/rendering HTML appropriately;
+these methods are not a visual editor or HTML sanitizer.
+[Posts](https://developer.wordpress.org/rest-api/reference/posts/),
+[pages](https://developer.wordpress.org/rest-api/reference/pages/).
+
+For a simple publishing workflow, create a draft, show the returned content and
+link to an authorized reviewer, then make an explicit publish request:
+
+```js
+const draft = await connections.invoke({ context, integrationId: "publishing",
+  operation: "posts.create", input: { title, content } });
+// The application obtains the reviewer's decision and checks their authority.
+await connections.invoke({ context, integrationId: "publishing",
+  operation: "posts.update", input: { id: draft.id, status: "publish" } });
+```
+
+The app must authorize each resource and action before invoking it. Shared
+credentials act as the connected WordPress user for every permitted app caller.
+WordPress may reject creation, editing another author's content, publishing or
+trashing under that user's role. Return that failure; do not reconnect as an
+administrator or silently change roles. Updating published content can take
+effect immediately and may trigger site plugins/notifications. There is no
+transaction spanning multiple calls and no blind retry of an uncertain write;
+inspect the site's content before deciding whether to repeat it.
+
+A non-Node framework uses its own HTTPS client, the same site URL/Env username
+and password binding, and these native `/wp-json/wp/v2/posts` or `/pages` routes.
+Use GET for reads, JSON POST for create/update, and DELETE with force=false for
+trash. There is no Vibe64 runtime or JSKIT service requirement for that framework.
+
+## Media and user operations
+
+`media.list` accepts page/per_page/search/context and an optional `media_type`
+(image/video/text/application/audio). `media.get` takes `id` and optional context.
+Both return metadata, including the media URL; they do not fetch the linked file
+or forward credentials to a CDN. `media.update` accepts `id` and one or more of
+`title`, `caption`, `description`, `alt_text`, `post` (0 detaches the attachment).
+
+`media.upload` accepts `filename`, `mimeType`, canonical `contentBase64` and those
+optional metadata fields. The runtime decodes at most **5 MiB** into an ordinary
+multipart `file` upload; WordPress enforces allowed types, upload_files capability
+and any smaller site limit. No filesystem path or source URL is fetched by the
+connector. The framework validates its incoming upload and size before encoding
+it. A Node backend can use `Buffer.from(fileBytes).toString("base64")`; another
+framework can send its native multipart upload to the same media endpoint.
+
+```js
+const attachment = await connections.invoke({ context, integrationId: "publishing",
+  operation: "media.upload", input: { filename: "cover.png", mimeType: "image/png",
+    contentBase64: Buffer.from(fileBytes).toString("base64"), alt_text: "Cover image" } });
+await connections.invoke({ context, integrationId: "publishing",
+  operation: "posts.update", input: { id: draft.id, featured_media: attachment.id } });
+```
+
+These are separate writes. If attaching the image fails, the uploaded attachment
+can still exist. Show that outcome and allow explicit recovery; do not silently
+repeat uploads or delete the attachment. `media.delete` requires `id` and
+`force: true`, returns WordPress's deletion response, and **permanently removes**
+the attachment/file. It is deliberately different from post/page trash. The app
+must obtain the intended user's confirmation and authorize that exact resource.
+[Media endpoint reference](https://developer.wordpress.org/rest-api/reference/media/).
+
+`users.list` takes page/per_page/search/context; `users.get` takes id/context.
+Public view may expose only authors; edit context and full lists require the
+connected account's capabilities. `users.create` requires username, email,
+password and explicit roles; it never uses an implicit site's default role.
+Supported optional profile fields are name, first_name, last_name, nickname and
+description. `users.update` takes id and at least one profile/email/password/roles
+field; omitted fields remain unchanged. Role IDs may be custom site roles;
+WordPress checks whether the actor is allowed to assign them. There is no local
+role elevation or change to the application's own login system.
+
+Passwords here are transient **server-side operation input**, not fields in
+integrations.json or the connection store. The framework must keep them out of
+chat, URL parameters, logs and client responses. Prefer the site's own onboarding
+and password-reset flow when an administrator should not handle new passwords.
+Returned user records cannot include a password. Changing the credential owner's
+profile or deleting that owner may interrupt subsequent connector use.
+
+`users.delete` requires id, force:true and an explicit positive `reassign` user ID
+for the removed user's content. It is permanent, not a trash action. The app
+must authorize this administrative action; multisite and site plugins may impose
+additional restrictions or trigger notifications. Failures are returned without
+automatic retries. No batch transaction, role provisioning or multisite network
+administration is implemented.
+[Users endpoint reference](https://developer.wordpress.org/rest-api/reference/users/).
+
+For read-only public content a framework can make its own unauthenticated REST
+reads. This connector always authenticates; it never falls back to anonymous
+access after denial. Shared-account operations must remain behind application
+permissions even when some records happen to be public.
+
+## Automation and application ownership
+
+An AI can prepare the files and library composition. An authorized operator
+with shell access can provision a password using
+`wp user application-password create <user> <app-name> --porcelain`.
+The command prints the new credential; an automation must capture it directly
+into the secret store and keep it out of logs.
+[WP-CLI password creation](https://developer.wordpress.org/cli/commands/user/application-password/create/).
+
+The REST API also supports creating and deleting passwords at
+`/wp-json/wp/v2/users/{userId}/application-passwords`. It requires an already
+authorized identity, so it does not bootstrap an unknown site's credentials.
+The fragment does not expose these administrative operations.
+[Application Passwords API](https://developer.wordpress.org/rest-api/reference/application-passwords/).
+
+These are passwords owned by a user on a particular site, not global OAuth
+registrations. Use a recognizable application name for revocation and
+attribution. Separate passwords do not provide independent site capacity. The
+application selects its private Env binding and enforces its own access policy;
+the connected site remains owned by that customer.
+
+Manual authentication has no callback, so editor VM and deployed-app domains
+do not need registration. Use the site's final HTTPS address. Moving that site
+or changing its installation path requires configuration and verification again.
+The adapter does not configure per-password scopes, generate passwords, install
+plugins, change WordPress roles or enable disabled REST routes.
+
+## Focused proof and limits
+
+The WordPress-family suite uses simulated provider replies and actual encrypted
+JSON persistence. It covers authenticated verification, posts/drafts, Basic
+headers, site paths, field/input validation, rotation, restart, ownership,
+disconnect, changed destinations and failure responses. Editor checks cover
+fields, error feedback, references, setup links and reload. Live administration,
+provider use and sample-app generation are excluded. Post/page writes, exact multipart upload bytes, media management and user
+administration have controlled fixtures. Custom post types, scheduling, taxonomy
+editing, binary downloads and alternative authentication plugins are not supplied.