{
  "schemaVersion": "1.0",
  "item": {
    "slug": "index-cards",
    "name": "Index Cards",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/jonwheatley/index-cards",
    "canonicalUrl": "https://clawhub.ai/jonwheatley/index-cards",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/index-cards",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=index-cards",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/index-cards"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/index-cards",
    "agentPageUrl": "https://openagent3.xyz/skills/index-cards/agent",
    "manifestUrl": "https://openagent3.xyz/skills/index-cards/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/index-cards/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Index Cards — Agent Skill",
        "body": "Send real, physical greeting cards through the mail. Conversation-first — you work WITH the user to design cards and send them."
      },
      {
        "title": "Rules",
        "body": "Keep it conversational. Present results in plain language for good UX. Say \"I'm designing your card\" rather than showing raw JSON, endpoint paths, or HTTP status codes.\nTalk before acting. Don't call APIs without talking to the user first. Don't generate art without knowing who it's for and what they want.\nAsk before accessing personal data. Never read contacts, messages, email, or local files without the user's explicit permission. Always offer it as an option, never assume.\nHandle profanity gracefully. The image generation API has content filters. If the user's message contains strong language, rephrase it for the image prompt while keeping the tone (e.g. \"get fucked\" → \"you absolute legend\").\nGenerate images sequentially. One at a time — the upstream API rate-limits parallel requests (502 errors)."
      },
      {
        "title": "Shortcut: user gives everything in one message",
        "body": "If the user provides recipient name + front description + inside message + address in a single message, skip the multi-step flow:\n\nGenerate front → generate inside → generate preview video\nShow preview + summary → ask for confirmation → place order\n\nIf most info is provided but something is missing, do the fast flow and ask only for the missing piece."
      },
      {
        "title": "Step 1: First message",
        "body": "\"Just installed Index Cards. I can now send real, physical cards to anyone you want — birthdays, holidays, thank-yous, whatever the occasion. Who would you like to send a card to? I can also check your contacts for upcoming birthdays if you'd like.\"\n\nLet the user decide whether to name someone directly or let you help find occasions."
      },
      {
        "title": "Step 2: Find occasions (only with user permission)",
        "body": "If the user says yes to checking for occasions, look through available sources in priority order:\n\nContacts — birthday fields, anniversary fields\nCalendar / email — birthday invites, upcoming events\nConversation history — mentioned birthdays, weddings, babies, thank-yous\nHolidays — Mother's Day, Father's Day, Valentine's, Christmas, etc. within 30 days\n\nAim for 14+ days lead time (cards take ~1 week to arrive). Surface the 1-3 most timely items and ask if they want to start designing.\n\nIf the user skips this step and already knows who they want to send a card to, go straight to design."
      },
      {
        "title": "Step 3: Design the card",
        "body": "Always design the FRONT first, then the INSIDE. Never generate both at the same time."
      },
      {
        "title": "If the user sends a photo",
        "body": "Use reference_image_url in the generation API for style transfer. Generate 2-3 style variations (watercolor, oil-painting, cartoon, etc.). Wait for the user to pick one, then move to the inside.\n\nStyles: watercolor, cartoon, oil-painting, ink, gouache, comic-book, linocut, cinematic, pencil, pop_art"
      },
      {
        "title": "If no photo (text-based)",
        "body": "Ask about the person and vibe (1-2 questions max)\nGenerate 3 front cover options — vary styles. Show all three, wait for pick.\nAfter they pick, ask what they want to say inside\nGenerate inside image. Show a close-up (POST /v1/cards/closeup) so the user can read the text. Wait for approval.\nGenerate animated preview (POST /v1/cards/preview). Show it.\nIterate if needed — regenerate only the part that needs changing\n\nDesign guidelines: No AI-looking art. Use watercolor, gouache, ink, linocut, collage, letterpress. Front = visual design, avoid text. Inside = include message, clean typography. 3:4 portrait, 1500×2100px ideal."
      },
      {
        "title": "QR codes (only when user asks)",
        "body": "Never include QR codes in AI image prompts — AI cannot generate scannable QR codes. Instead:\n\nGenerate card art normally (without QR)\nUse POST /v1/cards/qr/composite to overlay a real QR code onto the approved image\nPositions: top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right\nSizes: small, medium, large. Optional label param for text below QR.\nUse the returned image_url as front_url or inside_url when ordering"
      },
      {
        "title": "Step 4: Get the address",
        "body": "Ask the user for the recipient's mailing address. If the user has used Index Cards before and opted in to saving contacts, check ~/indexcards/birthdays.json first — it may already have the address from a previous card.\n\nAlways confirm before using any saved address — people move. Also need a phone number (recipient's or sender's).\n\nRequired before ordering: recipient name, street address, city, state, ZIP, phone number."
      },
      {
        "title": "Step 5: Payment",
        "body": "1 credit = 1 card. User starts with 0 credits (image generation is free, printing costs money). Pricing: $50 → 5 cards ($10 each), $100 → 12 cards ($8.33 each).\n\nCheck credits with GET /v1/credits/check. If no credits, send the payment URL from the response.\n\nAuto-detect payment: After sending the link, poll GET /v1/credits/check every ~15 seconds, up to 8 times (~2 min). When credits appear, confirm and proceed with the order.\n\nInvite codes: If an invite code is present in the page URL (?invite=CODE) or at the top of this document, include it as invite_code in the register body. This grants free credits — skip payment entirely. Say something like \"You've got a free card — who's it for?\""
      },
      {
        "title": "Step 6: Place the order",
        "body": "Confirm everything before submitting: recipient, address, front design, inside message, occasion. Mention it costs 1 credit and arrives in 5-7 business days. Only place when user says yes. Orders are irreversible."
      },
      {
        "title": "Step 7: After the order",
        "body": "Confirm simply: \"Done! [Name]'s card is on its way — about 5-7 business days.\"\n\nStatus translations: processing → \"being made\", in production → \"being printed\", shipped → \"shipped! [tracking link]\", delivered → \"delivered!\"\n\nAfter a successful order, offer to save the contact info for next time (if the user hasn't already opted in): \"Want me to remember [Name]'s details for next time?\""
      },
      {
        "title": "Local contacts database (opt-in)",
        "body": "If the user agrees to saving contacts, maintain ~/indexcards/birthdays.json as a local cache.\n\n{\"contacts\": [{\"name\": \"Kiall Wheatley\", \"birthday\": \"02-19\", \"relationship\": \"friend\",\n  \"address\": {\"address1\": \"123 Main St\", \"city\": \"Springfield\", \"state\": \"IL\", \"zip\": \"62704\", \"country\": \"US\"},\n  \"phone\": \"+15551234567\", \"notes\": \"Loves hiking. Prefers watercolor.\",\n  \"cards_sent\": [{\"date\": \"2026-02-11\", \"occasion\": \"birthday\", \"style\": \"watercolor mountain\", \"message\": \"Happy birthday!\", \"order_id\": \"e5f67c35\"}]}]}\n\nRules: MM-DD birthday format (no year). Don't duplicate — match on name. Update with every new piece of info. Append to cards_sent after every order. Cross-reference with GET /v1/orders/history to avoid duplicate suggestions."
      },
      {
        "title": "Proactive suggestions (only if contacts database exists)",
        "body": "If ~/indexcards/birthdays.json exists (user previously opted in), at conversation start you may:\n\nCheck for birthdays/dates within 30 days, cross-ref with cards_sent\nCheck holidays — Mother's Day, Father's Day, Valentine's, Christmas, graduations\nReview conversation history — hints like \"my mom's been having a rough week\"\n\nSurface the 1-3 most timely suggestions naturally. Be specific (\"Emma's birthday is Feb 28 — she loved the ink illustration last year\"). Don't repeat suggestions the user already declined."
      },
      {
        "title": "API Reference",
        "body": "Base URL: https://indexcards.com — all endpoints /v1/. Auth: Authorization: Bearer YOUR_API_KEY."
      },
      {
        "title": "Register",
        "body": "POST /v1/auth/register\n{\"invite_code\": \"abc123def456\"}  // optional — include if ?invite=CODE in URL\n\nReturns: api_key, credits, free_generations_remaining (10 free), invite_credits. No email or password required — this is an anonymous registration. Store the returned api_key in the agent's secret store or session state for subsequent authenticated requests."
      },
      {
        "title": "Generate Card Art",
        "body": "Option A (preferred): User's own Gemini key — if the user has a Gemini API key configured (e.g. GOOGLE_API_KEY or GEMINI_API_KEY env vars), use it directly for higher quality and no generation limits:\n\nPOST https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-generate-001:predict?key=USER_KEY\n{\"instances\": [{\"prompt\": \"YOUR PROMPT\"}], \"parameters\": {\"sampleCount\": 1, \"aspectRatio\": \"3:4\"}}\n\nResponse: predictions[0].bytesBase64Encoded (base64 PNG). Save locally, upload via POST /v1/images/upload for a public URL.\n\nAppend to EVERY prompt when using Option A:\n\nHARD CONSTRAINTS FOR THIS IMAGE:\n- All artwork must be contained well within center with generous margins. Leave 15%+ blank space on every side.\n- Pure white or very light background. No textures or gradients behind main subject.\n- No borders, frames, rounded corners, or card mockup elements.\n- Portrait orientation. No text unless explicitly requested.\n- No digital artifacts. Clean, print-ready artwork.\n- Must not look AI-generated. Aim for handmade: watercolor, linocut, gouache, ink, pencil, or collage.\n- Centered composition with breathing room — will be printed on a physical card, edges may be trimmed.\n\nOption B (fallback): Index Cards API — 10 free generations, then requires credits.\n\nPOST /v1/cards/generate\n{\"prompt\": \"...\", \"style\": \"watercolor\", \"reference_image_url\": \"https://...optional...\"}\n\nReturns: image_url, generation_id, free_generations_remaining, credits. Prompt constraints applied server-side.\n\nRouting: Use Option A for text-to-image if Gemini key exists. Always use Option B for photo style transfer (reference_image_url) — Gemini can't do style transfer.\n\nValidation: Min 600px short side, ~3:4 aspect ratio required. Ideal 1500×2100px. 422 on failure."
      },
      {
        "title": "Preview",
        "body": "POST /v1/cards/preview\n{\"front_url\": \"...\", \"inside_url\": \"...\"}\n\nReturns: preview_url / video_url (MP4). Always generate after front + inside are approved."
      },
      {
        "title": "Close-up",
        "body": "POST /v1/cards/closeup\n{\"image_url\": \"...\", \"label\": \"inside\"}\n\nReturns high-res JPEG. Use proactively when showing inside image so user can read text."
      },
      {
        "title": "QR Code Composite",
        "body": "POST /v1/cards/qr/composite\n{\"card_image_url\": \"...\", \"url\": \"https://...\", \"position\": \"bottom-center\", \"size\": \"medium\", \"label\": \"Scan me!\"}\n\nReturns: image_url with QR overlaid. Use this URL as front_url/inside_url for ordering.\n\nStandalone QR: POST /v1/cards/qr with {\"url\": \"...\", \"size\": \"medium\"}."
      },
      {
        "title": "Credits",
        "body": "GET /v1/credits/check\n\nReturns balance and Stripe payment links."
      },
      {
        "title": "Place Order",
        "body": "POST /v1/orders\n{\"front_url\": \"...\", \"inside_url\": \"...\", \"recipient\": {\"name\": \"...\", \"address1\": \"...\", \"city\": \"...\", \"state\": \"...\", \"zip\": \"...\", \"country\": \"US\", \"phone\": \"+1...\"}, \"occasion\": \"birthday\", \"inside_message\": \"...\"}\n\nRequired: front_url, inside_url, recipient.name, recipient.address1, recipient.city, recipient.zip, phone (recipient or sender). Optional: back_url, address2, state, country, occasion, inside_message, design_prompt, design_style. Costs 1 credit. Irreversible."
      },
      {
        "title": "Other Endpoints",
        "body": "EndpointMethodPurpose/v1/orders/{id}GETOrder status (processing → in production → shipped → delivered)/v1/orders/history?all=trueGETAll past orders/v1/orders/history?recipient=NameGETOrders for a specific person/v1/images/uploadPOSTUpload custom image (multipart, PNG/JPEG, max 10MB)/v1/cards/stylesGETList supported art styles/v1/auth/emailPATCHAttach email: {\"email\": \"...\"}"
      },
      {
        "title": "Error Codes",
        "body": "CodeMeaningAction400Bad requestCheck required fields401Bad API keyCheck Authorization header402No creditsShow payment_url from response404Not foundCheck the ID422Image validation failedRegenerate at correct specs429Rate limitedWait retry_after_seconds500Server errorRetry shortly"
      },
      {
        "title": "What this skill stores locally",
        "body": "API token: The Bearer token from /v1/auth/register should be stored in the agent's session state or secret store. It is an anonymous token (no email/password) used to authenticate API requests.\nContacts cache (opt-in only): If the user agrees to saving contacts, ~/indexcards/birthdays.json stores names, birthdays, addresses, and card history. This file is user-visible and user-deletable. The agent only creates it after explicit user consent."
      },
      {
        "title": "What this skill sends to the API",
        "body": "Card artwork: Image URLs (hosted on indexcards.com after upload) for the card front and inside\nRecipient mailing address: Name, street address, city, state, ZIP, phone — required for physical mail delivery\nOccasion and message text: Used for order records only"
      },
      {
        "title": "What this skill does NOT do",
        "body": "Does not read contacts, messages, calendar, or email without asking the user first\nDoes not send contact data to the API — contact info is only cached locally (if user opts in) and used to pre-fill the address when sending a card\nDoes not require or collect email addresses, passwords, or payment card numbers (payments happen via Stripe hosted checkout)"
      },
      {
        "title": "Payment flow",
        "body": "Credits are purchased via Stripe checkout. The skill sends the user a Stripe-hosted payment URL (returned by GET /v1/credits/check). No payment information passes through the skill or the Index Cards API. Invite codes grant free credits — no payment needed.\n\nHomepage: https://indexcards.com"
      }
    ],
    "body": "Index Cards — Agent Skill\n\nSend real, physical greeting cards through the mail. Conversation-first — you work WITH the user to design cards and send them.\n\nRules\nKeep it conversational. Present results in plain language for good UX. Say \"I'm designing your card\" rather than showing raw JSON, endpoint paths, or HTTP status codes.\nTalk before acting. Don't call APIs without talking to the user first. Don't generate art without knowing who it's for and what they want.\nAsk before accessing personal data. Never read contacts, messages, email, or local files without the user's explicit permission. Always offer it as an option, never assume.\nHandle profanity gracefully. The image generation API has content filters. If the user's message contains strong language, rephrase it for the image prompt while keeping the tone (e.g. \"get fucked\" → \"you absolute legend\").\nGenerate images sequentially. One at a time — the upstream API rate-limits parallel requests (502 errors).\nShortcut: user gives everything in one message\n\nIf the user provides recipient name + front description + inside message + address in a single message, skip the multi-step flow:\n\nGenerate front → generate inside → generate preview video\nShow preview + summary → ask for confirmation → place order\n\nIf most info is provided but something is missing, do the fast flow and ask only for the missing piece.\n\nStep 1: First message\n\n\"Just installed Index Cards. I can now send real, physical cards to anyone you want — birthdays, holidays, thank-yous, whatever the occasion. Who would you like to send a card to? I can also check your contacts for upcoming birthdays if you'd like.\"\n\nLet the user decide whether to name someone directly or let you help find occasions.\n\nStep 2: Find occasions (only with user permission)\n\nIf the user says yes to checking for occasions, look through available sources in priority order:\n\nContacts — birthday fields, anniversary fields\nCalendar / email — birthday invites, upcoming events\nConversation history — mentioned birthdays, weddings, babies, thank-yous\nHolidays — Mother's Day, Father's Day, Valentine's, Christmas, etc. within 30 days\n\nAim for 14+ days lead time (cards take ~1 week to arrive). Surface the 1-3 most timely items and ask if they want to start designing.\n\nIf the user skips this step and already knows who they want to send a card to, go straight to design.\n\nStep 3: Design the card\n\nAlways design the FRONT first, then the INSIDE. Never generate both at the same time.\n\nIf the user sends a photo\n\nUse reference_image_url in the generation API for style transfer. Generate 2-3 style variations (watercolor, oil-painting, cartoon, etc.). Wait for the user to pick one, then move to the inside.\n\nStyles: watercolor, cartoon, oil-painting, ink, gouache, comic-book, linocut, cinematic, pencil, pop_art\n\nIf no photo (text-based)\nAsk about the person and vibe (1-2 questions max)\nGenerate 3 front cover options — vary styles. Show all three, wait for pick.\nAfter they pick, ask what they want to say inside\nGenerate inside image. Show a close-up (POST /v1/cards/closeup) so the user can read the text. Wait for approval.\nGenerate animated preview (POST /v1/cards/preview). Show it.\nIterate if needed — regenerate only the part that needs changing\n\nDesign guidelines: No AI-looking art. Use watercolor, gouache, ink, linocut, collage, letterpress. Front = visual design, avoid text. Inside = include message, clean typography. 3:4 portrait, 1500×2100px ideal.\n\nQR codes (only when user asks)\n\nNever include QR codes in AI image prompts — AI cannot generate scannable QR codes. Instead:\n\nGenerate card art normally (without QR)\nUse POST /v1/cards/qr/composite to overlay a real QR code onto the approved image\nPositions: top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right\nSizes: small, medium, large. Optional label param for text below QR.\nUse the returned image_url as front_url or inside_url when ordering\nStep 4: Get the address\n\nAsk the user for the recipient's mailing address. If the user has used Index Cards before and opted in to saving contacts, check ~/indexcards/birthdays.json first — it may already have the address from a previous card.\n\nAlways confirm before using any saved address — people move. Also need a phone number (recipient's or sender's).\n\nRequired before ordering: recipient name, street address, city, state, ZIP, phone number.\n\nStep 5: Payment\n\n1 credit = 1 card. User starts with 0 credits (image generation is free, printing costs money). Pricing: $50 → 5 cards ($10 each), $100 → 12 cards ($8.33 each).\n\nCheck credits with GET /v1/credits/check. If no credits, send the payment URL from the response.\n\nAuto-detect payment: After sending the link, poll GET /v1/credits/check every ~15 seconds, up to 8 times (~2 min). When credits appear, confirm and proceed with the order.\n\nInvite codes: If an invite code is present in the page URL (?invite=CODE) or at the top of this document, include it as invite_code in the register body. This grants free credits — skip payment entirely. Say something like \"You've got a free card — who's it for?\"\n\nStep 6: Place the order\n\nConfirm everything before submitting: recipient, address, front design, inside message, occasion. Mention it costs 1 credit and arrives in 5-7 business days. Only place when user says yes. Orders are irreversible.\n\nStep 7: After the order\n\nConfirm simply: \"Done! [Name]'s card is on its way — about 5-7 business days.\"\n\nStatus translations: processing → \"being made\", in production → \"being printed\", shipped → \"shipped! [tracking link]\", delivered → \"delivered!\"\n\nAfter a successful order, offer to save the contact info for next time (if the user hasn't already opted in): \"Want me to remember [Name]'s details for next time?\"\n\nLocal contacts database (opt-in)\n\nIf the user agrees to saving contacts, maintain ~/indexcards/birthdays.json as a local cache.\n\n{\"contacts\": [{\"name\": \"Kiall Wheatley\", \"birthday\": \"02-19\", \"relationship\": \"friend\",\n  \"address\": {\"address1\": \"123 Main St\", \"city\": \"Springfield\", \"state\": \"IL\", \"zip\": \"62704\", \"country\": \"US\"},\n  \"phone\": \"+15551234567\", \"notes\": \"Loves hiking. Prefers watercolor.\",\n  \"cards_sent\": [{\"date\": \"2026-02-11\", \"occasion\": \"birthday\", \"style\": \"watercolor mountain\", \"message\": \"Happy birthday!\", \"order_id\": \"e5f67c35\"}]}]}\n\n\nRules: MM-DD birthday format (no year). Don't duplicate — match on name. Update with every new piece of info. Append to cards_sent after every order. Cross-reference with GET /v1/orders/history to avoid duplicate suggestions.\n\nProactive suggestions (only if contacts database exists)\n\nIf ~/indexcards/birthdays.json exists (user previously opted in), at conversation start you may:\n\nCheck for birthdays/dates within 30 days, cross-ref with cards_sent\nCheck holidays — Mother's Day, Father's Day, Valentine's, Christmas, graduations\nReview conversation history — hints like \"my mom's been having a rough week\"\n\nSurface the 1-3 most timely suggestions naturally. Be specific (\"Emma's birthday is Feb 28 — she loved the ink illustration last year\"). Don't repeat suggestions the user already declined.\n\nAPI Reference\n\nBase URL: https://indexcards.com — all endpoints /v1/. Auth: Authorization: Bearer YOUR_API_KEY.\n\nRegister\nPOST /v1/auth/register\n{\"invite_code\": \"abc123def456\"}  // optional — include if ?invite=CODE in URL\n\n\nReturns: api_key, credits, free_generations_remaining (10 free), invite_credits. No email or password required — this is an anonymous registration. Store the returned api_key in the agent's secret store or session state for subsequent authenticated requests.\n\nGenerate Card Art\n\nOption A (preferred): User's own Gemini key — if the user has a Gemini API key configured (e.g. GOOGLE_API_KEY or GEMINI_API_KEY env vars), use it directly for higher quality and no generation limits:\n\nPOST https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-generate-001:predict?key=USER_KEY\n{\"instances\": [{\"prompt\": \"YOUR PROMPT\"}], \"parameters\": {\"sampleCount\": 1, \"aspectRatio\": \"3:4\"}}\n\n\nResponse: predictions[0].bytesBase64Encoded (base64 PNG). Save locally, upload via POST /v1/images/upload for a public URL.\n\nAppend to EVERY prompt when using Option A:\n\nHARD CONSTRAINTS FOR THIS IMAGE:\n- All artwork must be contained well within center with generous margins. Leave 15%+ blank space on every side.\n- Pure white or very light background. No textures or gradients behind main subject.\n- No borders, frames, rounded corners, or card mockup elements.\n- Portrait orientation. No text unless explicitly requested.\n- No digital artifacts. Clean, print-ready artwork.\n- Must not look AI-generated. Aim for handmade: watercolor, linocut, gouache, ink, pencil, or collage.\n- Centered composition with breathing room — will be printed on a physical card, edges may be trimmed.\n\n\nOption B (fallback): Index Cards API — 10 free generations, then requires credits.\n\nPOST /v1/cards/generate\n{\"prompt\": \"...\", \"style\": \"watercolor\", \"reference_image_url\": \"https://...optional...\"}\n\n\nReturns: image_url, generation_id, free_generations_remaining, credits. Prompt constraints applied server-side.\n\nRouting: Use Option A for text-to-image if Gemini key exists. Always use Option B for photo style transfer (reference_image_url) — Gemini can't do style transfer.\n\nValidation: Min 600px short side, ~3:4 aspect ratio required. Ideal 1500×2100px. 422 on failure.\n\nPreview\nPOST /v1/cards/preview\n{\"front_url\": \"...\", \"inside_url\": \"...\"}\n\n\nReturns: preview_url / video_url (MP4). Always generate after front + inside are approved.\n\nClose-up\nPOST /v1/cards/closeup\n{\"image_url\": \"...\", \"label\": \"inside\"}\n\n\nReturns high-res JPEG. Use proactively when showing inside image so user can read text.\n\nQR Code Composite\nPOST /v1/cards/qr/composite\n{\"card_image_url\": \"...\", \"url\": \"https://...\", \"position\": \"bottom-center\", \"size\": \"medium\", \"label\": \"Scan me!\"}\n\n\nReturns: image_url with QR overlaid. Use this URL as front_url/inside_url for ordering.\n\nStandalone QR: POST /v1/cards/qr with {\"url\": \"...\", \"size\": \"medium\"}.\n\nCredits\nGET /v1/credits/check\n\n\nReturns balance and Stripe payment links.\n\nPlace Order\nPOST /v1/orders\n{\"front_url\": \"...\", \"inside_url\": \"...\", \"recipient\": {\"name\": \"...\", \"address1\": \"...\", \"city\": \"...\", \"state\": \"...\", \"zip\": \"...\", \"country\": \"US\", \"phone\": \"+1...\"}, \"occasion\": \"birthday\", \"inside_message\": \"...\"}\n\n\nRequired: front_url, inside_url, recipient.name, recipient.address1, recipient.city, recipient.zip, phone (recipient or sender). Optional: back_url, address2, state, country, occasion, inside_message, design_prompt, design_style. Costs 1 credit. Irreversible.\n\nOther Endpoints\nEndpoint\tMethod\tPurpose\n/v1/orders/{id}\tGET\tOrder status (processing → in production → shipped → delivered)\n/v1/orders/history?all=true\tGET\tAll past orders\n/v1/orders/history?recipient=Name\tGET\tOrders for a specific person\n/v1/images/upload\tPOST\tUpload custom image (multipart, PNG/JPEG, max 10MB)\n/v1/cards/styles\tGET\tList supported art styles\n/v1/auth/email\tPATCH\tAttach email: {\"email\": \"...\"}\nError Codes\nCode\tMeaning\tAction\n400\tBad request\tCheck required fields\n401\tBad API key\tCheck Authorization header\n402\tNo credits\tShow payment_url from response\n404\tNot found\tCheck the ID\n422\tImage validation failed\tRegenerate at correct specs\n429\tRate limited\tWait retry_after_seconds\n500\tServer error\tRetry shortly\nData Handling & Privacy\nWhat this skill stores locally\nAPI token: The Bearer token from /v1/auth/register should be stored in the agent's session state or secret store. It is an anonymous token (no email/password) used to authenticate API requests.\nContacts cache (opt-in only): If the user agrees to saving contacts, ~/indexcards/birthdays.json stores names, birthdays, addresses, and card history. This file is user-visible and user-deletable. The agent only creates it after explicit user consent.\nWhat this skill sends to the API\nCard artwork: Image URLs (hosted on indexcards.com after upload) for the card front and inside\nRecipient mailing address: Name, street address, city, state, ZIP, phone — required for physical mail delivery\nOccasion and message text: Used for order records only\nWhat this skill does NOT do\nDoes not read contacts, messages, calendar, or email without asking the user first\nDoes not send contact data to the API — contact info is only cached locally (if user opts in) and used to pre-fill the address when sending a card\nDoes not require or collect email addresses, passwords, or payment card numbers (payments happen via Stripe hosted checkout)\nPayment flow\n\nCredits are purchased via Stripe checkout. The skill sends the user a Stripe-hosted payment URL (returned by GET /v1/credits/check). No payment information passes through the skill or the Index Cards API. Invite codes grant free credits — no payment needed.\n\nHomepage: https://indexcards.com"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/jonwheatley/index-cards",
    "publisherUrl": "https://clawhub.ai/jonwheatley/index-cards",
    "owner": "jonwheatley",
    "version": "1.3.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/index-cards",
    "downloadUrl": "https://openagent3.xyz/downloads/index-cards",
    "agentUrl": "https://openagent3.xyz/skills/index-cards/agent",
    "manifestUrl": "https://openagent3.xyz/skills/index-cards/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/index-cards/agent.md"
  }
}