plugin.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "jokerly",
  "version": "1.0.1",
  "description": "An American mahjong helper in ChatGPT. Share your rack, as a photo or typed, and Jokerly counts how many tiles away you are from each hand on your own card, suggests which tiles to pass in the Charleston, and checks whether a joker swap is legal. A rules engine does the counting. Jokerly includes no league's card: you save the hands from your own card, privately, or try its practice hands.",
  "author": {
    "name": "The Open Apps, Inc.",
    "email": "support@theopenapps.com",
    "url": "https://jokerly.ambientapp.ai"
  },
  "homepage": "https://jokerly.ambientapp.ai",
  "keywords": [
    "american mahjong",
    "mah jongg",
    "mahjongg",
    "mahjong",
    "mahj",
    "mahjong card",
    "card hands",
    "charleston",
    "charleston pass",
    "blind pass",
    "joker swap",
    "joker exchange",
    "tiles away",
    "mahjong rack",
    "mahjong helper",
    "mahjong practice",
    "jokerly"
  ],
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Jokerly American Mahjong",
        "shortDescription": "Mah jongg hands & Charleston",
        "longDescription": "Jokerly is a helper for American mahjong, for the moments at the table when the counting gets hard.\n\nShare your rack, as a photo or typed, and Jokerly counts how many tiles away you are from every hand on your card. Each hand shows the tiles it still needs and where a joker can stand in, so you can see at a glance which hands are alive.\n\nIn the Charleston, Jokerly tries every set of three tiles in your rack and suggests the pass that keeps you closest to your nearest hands. It never passes a joker, and on the last pass of a Charleston it tells you when a blind pass would save a tile you need. In the card you can mark the pass as done, add the tiles you got back and see the next pass.\n\nWondering whether you can take that joker? Jokerly checks the swap against the standard rules: the joker must be in an exposure, it must be your turn, and your tile must be the one the joker stands for. With your rack, it also says whether the swap brings you closer to a hand.\n\nBring your own card. Jokerly includes no league's card. Type or photograph the hands on the card your table plays, and Jokerly saves them for you alone; they are never shared or combined with anyone else's. Until you do, Jokerly uses its own practice hands so you can try it.\n\nThe answers come from a rules engine: jokers count only in groups of three or more, every suit and number a hand allows is tried, exposures must match a hand, and concealed hands drop out once you have exposed.\n\nLimits:\n- American mahjong only, with 14-tile hands written in Jokerly's simple notation (each card line once).\n- ChatGPT reads your photos; Jokerly lists every tile it received, and you can tap a tile in the card to fix a misread one.\n- Standard rules; your table may play house rules.\n- Jokerly keeps no score and handles no money.\n- Not affiliated with any mahjong league or card publisher.\n- Say \"Delete my Jokerly card\" to delete your saved hands at any time.",
        "developerName": "The Open Apps, Inc.",
        "category": "Entertainment",
        "capabilities": [
          "Interactive",
          "Write"
        ],
        "websiteURL": "https://jokerly.ambientapp.ai",
        "supportURL": "https://jokerly.ambientapp.ai/support",
        "privacyPolicyURL": "https://jokerly.ambientapp.ai/privacy",
        "termsOfServiceURL": "https://jokerly.ambientapp.ai/terms",
        "defaultPrompt": [
          "Use Jokerly to check my mahjong rack",
          "What should I pass in the Charleston?",
          "Can I swap my tile for that joker?"
        ],
        "brandColor": "#0B6B4D",
        "brandColorDark": "#5FD3A5",
        "composerIcon": "./assets/composerIcon.png",
        "logo": "./assets/logo.png",
        "onboardingSkill": "./skills/mahjong-helper/SKILL.md"
      },
      "review": {
        "test_cases": {
          "positive": [
            {
              "description": "Check a typed rack against Jokerly's practice hands. Run this first, in a new chat. Nothing to sign in to and no card needed: Jokerly ships its own practice hands (listed at jokerly.ambientapp.ai/notation#practice) and uses them until the user saves hands from their own card. The tiles are codes: 2B is 2 Bam, F flower, J joker, N North, 9D 9 Dot, 3C 3 Crak.",
              "prompt": "Use Jokerly to check this American mahjong rack against its practice hands: 2B 2B 4B 4B 6B 6B 8B F F J N 9D 3C",
              "tools_triggered": "check_rack",
              "expected_behavior": "The Jokerly card shows the 13 tiles as tile faces and the practice hands ranked by tiles away: #1 Even Steps is first, 4 tiles away. Tapping it shows the best arrangement, with the joker standing in and the missing tiles dashed: 4 Bam, 6 Bam and two 8 Bams. The reply says it used the practice hands, lists the tiles it read and names Even Steps as closest. It adds no other hands, odds or strategy."
            },
            {
              "description": "A rack from a photo. Attach the image at the file attachment URL (a rack of 13 tiles on a wooden rack). ChatGPT reads the tiles and passes them to Jokerly as codes; Jokerly never receives the photo. If ChatGPT misreads a tile, the card shows the tile it got: tap that tile in the card, pick the right one, and the counts update at once.",
              "prompt": "Here's my mahjong rack. How close am I to the Jokerly practice hands?",
              "tools_triggered": "check_rack",
              "expected_behavior": "The reply lists the tiles ChatGPT read: 2 Bam \u00d72, 4 Bam \u00d72, 6 Bam \u00d72, 8 Bam, 3 Crak, 9 Dot, North, two Flowers and a Joker. With those tiles the card ranks #1 Even Steps first, 4 tiles away, the same as case 1. If a tile was misread, the result differs only by that tile, and fixing it in the card restores the ranking.",
              "file_attachment_urls": [
                "https://jokerly.ambientapp.ai/samples/rack-photo-1.png"
              ]
            },
            {
              "description": "A Charleston pass. Can follow case 1 or start a new chat. The first pass of the Charleston is three tiles to the right; jokers are never passed.",
              "prompt": "Jokerly, I'm about to make the first pass right in the Charleston. My rack is 2B 2B 4B 4B 6B 6B 8B F F J N 9D 3C. What should I pass?",
              "tools_triggered": "suggest_charleston_pass",
              "expected_behavior": "The card raises three tiles in the rack: 3 Crak, 9 Dot and North, and lists why each goes (none of the closest hands use 3 Crak or 9 Dot; only Pairs Parade uses North). The joker is kept. The reply gives the same three tiles. In the card, 'I passed these' removes them and asks for the three tiles that came back; after adding any three, the card shows the next pass (pass across)."
            },
            {
              "description": "A joker swap. The question describes the table; nothing to set up. ChatGPT may ask which tile is offered or when; the case passes either way once Jokerly answers.",
              "prompt": "Jokerly question: it's my turn and I just drew. The player across has an exposed pung of 5 Dot, 5 Dot and a joker. Can I swap my 5 Dot for that joker?",
              "tools_triggered": "check_joker_swap",
              "expected_behavior": "The card says 'Swap allowed' and shows the exposure next to the 5 Dot. The reply says yes: the joker stands for 5 Dot, and on your turn you may give your 5 Dot for it. Asking next 'And could I take a joker that was discarded?' gets 'Not allowed': a discarded joker is dead."
            },
            {
              "description": "Save hands from the user's own card. These two lines are made up for testing (no league's card); each is written in Jokerly notation, where a, b and c are suit colors. ChatGPT may show 'Allow ChatGPT to use Jokerly?' because saving writes data; choose Allow once. Afterwards, 'Delete my Jokerly card' (it may ask to confirm) deletes everything Jokerly keeps for the user.",
              "prompt": "Save these two hands from my own mahjong card to Jokerly: Line 1 is NN 111a 999a DDDDb SS, and Line 2 is 2468a 22b 44b 666c 888c.",
              "tools_triggered": "save_card_hands",
              "expected_behavior": "The card lists the two hands as #1 Line 1 and #2 Line 2 and says 'Saved 2 hands.' (if ChatGPT sent the same save twice and shows the second card, it says 'These 2 hands are saved on your card, each once.'). The reply confirms the two hands are saved. Saying it again adds nothing: the card still has 2 hands, each once. Checking a rack now uses these two hands instead of the practice hands. 'Delete my Jokerly card' then deletes them: the reply says the saved card is deleted, or that there is no saved card, and the card says Jokerly keeps nothing."
            }
          ],
          "negative": [
            {
              "description": "A different kind of mahjong. Jokerly is for American mahjong racks, passes and joker swaps; general rules questions are ChatGPT's own job.",
              "prompt": "How does scoring work in Japanese Riichi mahjong?",
              "expected_behavior": "No Jokerly tool is called. ChatGPT answers the question itself."
            },
            {
              "description": "Shopping. Jokerly sells nothing and recommends no products.",
              "prompt": "Recommend a good mahjong set for a beginner.",
              "expected_behavior": "No Jokerly tool is called. ChatGPT answers with its own suggestions."
            },
            {
              "description": "A solo tile-matching game. Mahjong solitaire is a different game with no rack, card or Charleston.",
              "prompt": "Let's play a round of mahjong solitaire.",
              "expected_behavior": "No Jokerly tool is called. ChatGPT responds itself."
            }
          ]
        },
        "commerce": false,
        "demo_recording_url": "https://jokerly.ambientapp.ai/demo.mp4"
      },
      "publication": {
        "countries": [],
        "release_notes": "Listing keywords for mah jongg, mahj, Charleston and blind passes, joker swaps and tiles away; tool descriptions name the lines on the user's card. Adds the mahjong-helper skill. No change to the engine or the card."
      },
      "apps": "./.app.json"
    }
  }
}