# Cardstock > Greeting cards an agent makes from a description, opened by link as a 3D paper card. # Overview Source: https://cardstock.timmo.dev/ Cardstock makes greeting cards. You describe the card you want to an agent, such as "a Christmas card for Mum with snow and a photo of the dog", and it writes the words, picks or makes the pictures, and saves the card. You get a link, and whoever opens it sees an envelope that opens into a paper card, with the effect and music you chose. You can change any card afterwards in the web app on your phone or computer, and save it as a still, an MP4 or a GIF to send in a chat. Cardstock is being built in the open on [timmo001/cardstock#1](https://github.com/timmo001/cardstock/issues/1). Each page here says what works today and what is still to come. ## What it does - **Cards from a description:** an agent turns what you ask for into a card, using your own pictures, ones it finds on Openverse or Unsplash, or ones it draws. See [Making a card](/making-a-card). - **Private links:** a card opens only for whoever holds its link. The card is encrypted before it leaves your device, and the server never sees the key. See [Links and privacy](/links-and-privacy). - **A 3D paper card:** the envelope, the fold and the paper are drawn with three.js on WebGPU, falling back to WebGL. With reduced motion on, the card shows still and open. - **The web app:** your cards, their links and your devices, installed on a phone or computer. See [The web app](/web-app). - **For agents:** the `cardstock` CLI with Code Mode and MCP, and a skill that tells an agent how to use them. See [CLI](/cli) and [Agents](/agents). ## Parts | Part | What it is | | ----------------- | ------------------------------------------------------------------ | | `packages/card` | The card format, encryption, renderer, designs, effects and export | | `packages/app` | The web app, with the viewer and editor | | `packages/server` | The Cloudflare Worker that stores encrypted cards | | `packages/cli` | The `cardstock` CLI, with Code Mode and MCP for agents | | `docs` | This site | ## Machine-readable docs | URL | Use | | ----------------------------------------- | ---------------------------------------- | | https://cardstock.timmo.dev/llms.txt | Compact page index | | https://cardstock.timmo.dev/llms-full.txt | Full docs bundle | | https://cardstock.timmo.dev/mcp | Hosted MCP (search, page and navigation) | | `/{route}.md` | One page as Markdown | --- # Agents Source: https://cardstock.timmo.dev/agents An agent makes cards through the [`cardstock` CLI](/cli), in this order of preference: 1. **Code Mode:** `cardstock agent tools --json` prints every tool with its input as JSON Schema and whether it reads or writes. 2. **MCP:** `cardstock mcp` serves the same operations on stdio. 3. **The CLI** itself, with `--json`. ## The skill `skills/cardstock/SKILL.md` tells an agent to: - turn a request into a card spec, using whatever pictures it's given, makes, draws or finds, and credit them - save presets by itself, so later cards start from what you liked - add a new design or effect only as code, in a pull request for you to review The server has no AI of its own: the agent writes the words and picks the pictures, and the server only stores the encrypted card. ## Status The Code Mode manifest, MCP server and skill are still being built. --- # CLI Source: https://cardstock.timmo.dev/cli The `cardstock` CLI in `packages/cli` does everything the web app does, and is what agents use. Every command that returns data takes `--json`. | Command | What it does | | ----------------------------------------------- | ----------------------------------------------- | | `cardstock setup` | Makes your owner key and vault key | | `cardstock pair` | A one-time code to pair another device | | `cardstock devices list`, `devices remove` | The paired devices, and removing one | | `cardstock card create` | Makes a card from a card spec as JSON | | `cardstock card edit`, `show`, `list`, `delete` | Changes, shows, lists or deletes cards | | `cardstock media add ` | Adds your own picture or sound | | `cardstock media add --openverse ` | Finds a picture on Openverse | | `cardstock media add --unsplash ` | Finds a photo on Unsplash | | `cardstock link add --name ` | A link for one person, with `--expires ` | | `cardstock link list`, `link remove` | A card's links, and removing one | | `cardstock preset save`, `preset list` | Saved starting points for new cards | | `cardstock export ` | Saves a card with `--still`, `--mp4` or `--gif` | | `cardstock status` | Whether the server answers, and what's stored | | `cardstock agent tools --json` | The Code Mode manifest; see [Agents](/agents) | | `cardstock mcp` | Serves the same operations over MCP on stdio | Its config lives in `~/.config/cardstock/config.json`, readable only by you. Unsplash needs an access key in `UNSPLASH_ACCESS_KEY`; Openverse needs none. Run it from the repository with `bun packages/cli/src/cli.ts`. ## Status The CLI is still being built; today it only prints its version. --- # Designs Source: https://cardstock.timmo.dev/designs A design sets a card's paper, colours, fonts and shape. An effect plays around it once it opens. A card can only name a design and effect that exist, since both are listed in one registry the card format is built from. ## Designs | Design | For | | ------------- | ----------------------------------- | | `christmas` | Christmas, the first to be finished | | `birthday` | Birthdays | | `anniversary` | Anniversaries | | `any` | Any other occasion | ## Effects | Effect | What it does | | ---------- | -------------------------- | | `confetti` | Confetti falls as it opens | | `snow` | Snow drifts down | | `hearts` | Hearts float up | | `sparkle` | Sparkles catch the light | With reduced motion on, effects don't play. ## Adding one Designs live in `packages/card/src/designs/.ts` and effects in `packages/card/src/effects/.ts`. An agent can add one, but only as code in a pull request for you to review. ## Status The designs and effects are still being built. --- # Links and privacy Source: https://cardstock.timmo.dev/links-and-privacy A card's link looks like this: ```text https://cards.timmo.dev/c/#. ``` Everything after the `#` stays in the browser, since browsers never send it to the server. - **The link key** says you may fetch the card. The viewer sends it in a header, never in an address, and the server keeps only its hash. - **The content key** decrypts the card. It's never sent anywhere. ## Encryption Each card has its own random key. The card and each picture or sound are encrypted separately with AES-GCM, on your device, before they're uploaded. The server stores only encrypted files. To edit your cards on every device without the server learning their keys, your devices share a vault key. Each card's key is stored on the server encrypted with the vault key, and a new device gets the vault key when you pair it. ## When a link stops working You can give each person their own link, with an optional expiry, and remove any link at any time. A wrong, removed or expired link all show the same "This card isn't available", so nobody can tell which it was. Ten wrong tries from one address lock it out for an hour. Cards are kept until you delete them. Deleting a card removes its files and all its links. Opening a card sends you no notification. --- # Making a card Source: https://cardstock.timmo.dev/making-a-card You ask an agent for a card in your own words. The agent works out the rest and saves it with the `cardstock` CLI: 1. It picks the occasion, a [design](/designs) and an effect. 2. It writes the words for the front and the inside. 3. It finds the pictures: yours, ones from Openverse or Unsplash, or ones it draws. 4. It saves the card, which encrypts it on your machine before uploading it. 5. It adds a link for each person you're sending it to. Then you can change anything in the [web app](/web-app). ## What a card holds A card is data, never code. It holds: - the occasion, design and effect - the front: a title and an optional picture - the inside: the message, who it's from and, optionally, who it's to - optional music - the pictures and sounds it uses, each with where it came from Credits for the back of the card are worked out from where each picture came from, so they can't be left off. Photos from Unsplash load from Unsplash, as its rules ask, and only their address is kept in the card. ## Status The card format, the CLI and the agent skill are still being built. --- # The web app Source: https://cardstock.timmo.dev/web-app The web app at [cards.timmo.dev](https://cards.timmo.dev) opens cards, and lets you change your own once your device is paired. Install it from the browser to keep it on your phone or computer. ## Opening a card A card's link opens the viewer. Tap the envelope to take the card out, tap again to open it, then drag to turn it. Sound starts on the first tap, and the mute button remembers your choice on that device. The page around the card follows light or dark mode, while the card keeps its own design. ## Your cards Once paired, the app has: - **Cards:** your list of cards. - **Card:** a live preview with the words, picture, design, effect and music. Pictures can be uploaded, found on Openverse or Unsplash, or come from an agent. - **Links:** one for each person, with a name, an optional expiry, Copy and Remove. - **Devices:** the devices paired with your cards, each with Remove. - **Settings:** Auto, Light or Dark. Every save encrypts the card in the browser before uploading it. ## Saving for chats Each card can be saved as a still of its front (PNG), an MP4 or a GIF, to send where a link won't do. ## Status The viewer and editor are still being built.