JB AI Publisher Skill

Use this skill to control jb-ai-publisher through its HTTP API while keeping the browser editor as the human interface.

Assumptions

• Backend base URL defaults to http://127.0.0.1:8000 for local development.
• Public deployment base URL is https://jbai-publisher.tgview.pp.ua.
• Frontend base URL defaults to http://localhost:3000 for local development.
• The backend owns persistence under storage/.
• Do not modify storage/documents/*.json directly unless the API is unavailable and the user explicitly approves file-level recovery.

Import and Human Handoff

1. Check backend health with GET /api/health.
2. Discover capabilities with GET /agent/manifest.
3. Import the source with scripts/import_and_open.py.
4. Return editorUrl and ask the user to complete visual editing in the browser.
5. Continue through Document APIs only when the user requests Agent-side changes.
6. Render a paged preview before exporting PDF.

python scripts/import_and_open.py ./source.docx --open-browser

Set JB_AI_PUBLISHER_BASE_URL for the target service. When the host has no MCP connector, connect the Skill to Publisher with the local OAuth helper:

python scripts/publisher_auth.py login --base-url https://jbai-publisher.tgview.pp.ua
python scripts/publisher_auth.py status --base-url https://jbai-publisher.tgview.pp.ua
python scripts/publisher_auth.py disconnect --base-url https://jbai-publisher.tgview.pp.ua

The helper uses Authorization Code + S256 PKCE with a loopback callback, stores OAuth credentials in the operating system credential store, refreshes access tokens before expiry, and retries one REST request after a 401/403 when a saved refresh token is available. JB_AI_PUBLISHER_ACCESS_TOKEN remains the explicit/env override for a Publisher API Token or externally supplied OAuth access token; JB_AI_PUBLISHER_API_TOKEN is the final legacy API-token fallback. Token resolution is explicit argument, JB_AI_PUBLISHER_ACCESS_TOKEN, saved OAuth connection, then JB_AI_PUBLISHER_API_TOKEN.

Publisher API Tokens are created by an administrator, scoped, expiring, revocable, and stored server-side only as hashes. They are compatibility credentials, not OAuth access tokens. Remote MCP clients should connect to /mcp and use the discovered OAuth flow when the host supports it. Direct REST API calls may use the same OAuth bearer token when MCP is unavailable. Never put Publisher API Tokens, OAuth access tokens, or refresh tokens in Document JSON, source files, logs, connector JSON, or command output.

Remote MCP

For MCP-capable WorkBuddy or desktop clients, connect to:

https://jbai-publisher.tgview.pp.ua/mcp

Let the client follow the RFC 9728 discovery challenge and Keycloak Authorization Code + S256 PKCE flow. Request publisher:read for document discovery and publisher:write before create, update, render, or export calls. Prefer MCP over the compatibility API Token when the host supports OAuth. Do not manually collect a person's password or copy browser cookies into the Agent runtime.

Available MCP tools are list_documents, get_publisher_document, create_publisher_document, update_publisher_document, render_publisher_document, and export_publisher_document_pdf. OAuth scopes and organization roles are enforced together; inaccessible objects return a hidden/not-found result and viewer roles cannot use write tools.

PDF and image sources use 2 MB chunk uploads and run Smart Import before the editor URL is returned. Word (.docx), Markdown, and text sources create the editable Document immediately. Reject unsupported formats such as legacy .doc before upload. Reimporting/opening the same Library item reuses its existing Document and active Agent session.

Continue Editing

For a known document id, create a session:

POST /agent/sessions
{
  "document_id": "DOCUMENT_ID",
  "instruction": "Continue editing the consulting report."
}

Then use:

POST /agent/sessions/{session_id}/continue
{
  "instruction": "Adjust the report into flow mode and export PDF."
}

Use layout.mode = "flow" for Paged.js long-form pagination, manual for Craft.js page composition, and hybrid for manual pages plus flow body.

Treat the web editor as the human approval boundary. Do not export a final publication after material Agent edits unless the user asked for export or approved the preview.

Upgrade Check

Use POST /agent/upgrade/check.

The backend checks the Admin UI Skill upgrade settings first, then falls back to the JB_AI_PUBLISHER_SKILL_MANIFEST_URL environment variable. It only checks remote metadata. It does not download or execute upgrade code. If an update is available, report it and ask the user before applying any trusted installer or git update.

On the public deployment, the Settings UI at /settings can configure a Tencent COS-hosted upgrade manifest and package URL.

Helper Script

Use scripts/continue_edit.py for an existing document:

python scripts/continue_edit.py --document-id DOCUMENT_ID --export-pdf

Read references/api.md when endpoint details, Publisher API Token scopes, or the planned OAuth contract are needed.