AI Publishing Skill

# It Just Vibes — AI Publishing Skill
name: itjustvibes
description: Publish, find, share, and manage widgets on itjustvibes.com from any shell or AI tool.
version: 1.0.0

## What this skill teaches

Use the `vibes` CLI (or the hosted MCP connector) to:
- Publish HTML/React widgets from files or chat sessions
- Find and explore the widget catalogue
- Fetch widget source code by slug
- Export widget source to a local file
- Share or update widget visibility
- Sign in with an API key
- Connect the It Just Vibes MCP server to AI tools that support native MCP

---

## SECTION 1 — CLI (Primary Path)

Install the CLI:

  npm install -g @itjustvibes/cli

Or without global install:

  npx @itjustvibes/cli <command>

### Sign in

  vibes login --key <YOUR_API_KEY>

API keys are available from your account settings at itjustvibes.com.
The key is saved to ~/.config/itjustvibes/config.json with 0o600 permissions.
You can also pass it inline with --key or set the IJV_API_KEY environment variable.

Credential precedence: --key flag > IJV_API_KEY env > saved config file.

### Publish a widget (authenticated)

  vibes publish <file.html>
  vibes publish <file.html> --title "My Widget" --category games

Success output:
  Published.
    URL:  https://itjustvibes.com/w/<slug>
    Slug: <slug>

With --json: {"ok":true,"url":"...","slug":"...","claim_url":null}

### Publish a widget (anonymous / guest)

Omit the API key to publish as a guest. A claim URL is returned so you can
claim the widget later by signing in.

  vibes publish <file.html>

Guest output:
  Published.
    URL:   https://itjustvibes.com/w/<slug>
    Claim: https://itjustvibes.com/claim/<token>
    Note:  This widget expires in 24 hours unless claimed.

With --json: {"ok":true,"url":"...","slug":"...","claim_url":"https://..."}

### Find widgets

  vibes find "<query>"
  vibes find "<query>" --category games --author @handle --limit 10

Output: aligned table of SLUG / TITLE / AUTHOR / VOTES
With --json: raw JSON array of widgets.

### Get widget details + source

  vibes get <slug>
  vibes get <slug> --json

Human output: Title / Author / Visibility / URL / Created + source code block.
JSON: {slug, title, author, visibility, url, source_code, created_at}

### Export widget source to file

  vibes export <slug> --output <file.html>
  vibes export <slug>                        # prints to stdout

Note: URL-like --output paths are rejected for security.

### Share / update visibility

  vibes share <slug> --visibility public
  vibes share <slug> --visibility private_sole

Valid values: public | private_sole
Note: private_group is not yet supported (group targeting deferred). Passing private_group exits 2 (USAGE).
Requires authentication. 401/403/404 exits with code 4.

### Global flags (all commands)

  --key <key>     API key (overrides IJV_API_KEY env and saved config)
  --json          Machine-readable JSON output (no color, no table)
  --no-color      Disable ANSI color (auto-off when stdout is not a TTY)
  --help, -h      Show help for the command
  --version, -v   Print CLI version and exit 0

### Exit codes

  0  SUCCESS   — command completed successfully
  1  ERROR     — network failure, server error, parse error
  2  USAGE     — bad arguments, unknown flag, missing required argument (e.g. URL-like --output on export, private_group on share)
  4  PERMISSION — authentication failed (401/403/404) or no key configured

---

## SECTION 2 — MCP Connector (Secondary Path)

For AI tools that support the Model Context Protocol natively, you can connect
the hosted It Just Vibes MCP server instead of (or alongside) the CLI.

### Option A: mcp install (writes .mcp.json config)

  vibes mcp install

This merges the hosted connector config into .mcp.json in the current directory.
It is safe to run in an existing project — it preserves sibling mcpServers entries.
Existing connectors are never clobbered; only the itjustvibes key is overwritten.

Output:
  MCP connector written to .mcp.json
    URL: https://www.itjustvibes.com/api/mcp

After running mcp install, restart your AI tool to pick up the new connector.

### Option B: mcp serve (stdio proxy)

  vibes mcp serve

Starts a stdio MCP proxy that forwards JSON-RPC requests (ListTools + CallTool)
to the hosted /api/mcp endpoint with your Bearer token. Use this for tools that
require a local stdio-mode MCP server rather than a remote HTTP connector.

Requires vibes login (or --key / IJV_API_KEY). Exits 4 if no key is configured.
All output goes to stderr — stdout is the MCP JSON-RPC transport channel.

### Option C: manual connector config

Point your AI tool directly at the hosted MCP URL:

  URL:  https://www.itjustvibes.com/api/mcp
  Auth: Bearer <YOUR_API_KEY>

---

## SECTION 3 — Agent State via MCP

After connecting the MCP server (see SECTION 2), four state tools let you read and write
the agent-accessible state a widget exposes through its `vibes.ai.*` SDK methods.

**Owner-grant prerequisite:** The widget owner must enable agent access in the widget's
Manage page → Agent tab before these tools return data. Calling a tool on a widget that
has not granted access returns error code BRIDGE_GRANT_MISSING. Advise the user to open
the widget's Manage page and enable agent access there.

### vibes_state_list

List all agent-accessible state keys for a widget.

  vibes_state_list(widget_slug: string)

Returns: { keys: string[], widget_slug: string, context: { summary: string } }
Keys are returned WITHOUT the internal "ai/" prefix.
Requires: read scope (any valid API key or MCP connector token).

### vibes_state_get

Read the value of a single agent-accessible state key.

  vibes_state_get(widget_slug: string, key: string)

Returns: { key: string, value: unknown }
If the key does not exist, value is null (not an error).
Requires: read scope.

### vibes_state_set

Write an agent-accessible state value for a widget.

  vibes_state_set(widget_slug: string, key: string, value: unknown)

The value must be JSON-serializable.
Returns an error if the token has read-only scope (error code READ_ONLY) — advise the user
to generate a read-write API key or enable write access on the connector.
Requires: write scope.

### vibes_state_delete

Remove an agent-accessible state key for a widget.

  vibes_state_delete(widget_slug: string, key: string)

Returns: { success: true }
Requires: write scope.

### Agent State Error Codes

| Code | Meaning | Suggested action |
|------|---------|-----------------|
| BRIDGE_GRANT_MISSING | Widget owner has not enabled agent access | Ask owner to open Manage → Agent tab and enable access |
| READ_ONLY | Token has read scope but a write op was attempted | Use a read-write API key or update the connector grant |
| KEY_NOT_ALLOWED | Key prefix is not in the widget's allowed namespace list | Contact the widget owner |
| QUOTA_EXCEEDED | Widget has hit its agent-state storage quota | Delete unused keys with vibes_state_delete |

---

## Notes

- Widget source files must be valid HTML or JSX/TSX (50 KB limit by default).
- The vibes CLI is open source: https://github.com/itjustvibes/itjustvibes
- API keys are available at itjustvibes.com → Account Settings → API Keys.
- Run `vibes <command> --help` for per-command flag reference.