Write a setup card

This page is for whoever sets Maisnie up on someone else’s behalf. You shape their setup in a setup card: a small file they import in Setup. It carries every choice and your reason for it. It never carries a password, a key, a private calendar link or a token: in each of those places it carries one sentence saying where the owner will find it, and the owner types it in themselves, on their own computer. You never need their passwords, and you never need access to their computer or their network.

For what the owner sees when they import your card, see import a setup card.

Start from a real setup

The quickest way to a good card is to write one from a computer that’s already set up the way you want:

maisnie card write ~/dana-setup.json

It writes every choice that computer has (vault, sources and their settings, the AI model, time zone, remote address, People’s threshold) and puts a “where it comes from” sentence in place of every password and key. It never reads a password or key, so the file has none in it. It won’t replace a file that’s already there unless you add --force, and if any plain setting itself looks like a password or key (a feed address with a key in it, say), it leaves that setting out and tells you how many it left.

Then edit the file for the person you’re setting up: their folder, their mail server and username, their time zone, and a one-line reason for each choice.

Check it before you send it

maisnie card check ~/dana-setup.json

check reads the card exactly as importing it would and either says it’s ready, with what it sets and how many passwords and keys it will ask for, or lists every problem, one plain sentence each, and exits with status 1. It changes nothing and needs no running Maisnie. Run it on your own computer before you send a card; a folder or an app’s location only has to be a full path on some computer there, since the card is meant for another one.

The format

A card is one JSON object. The first key marks it as a setup card; every section after it is optional, and anything a section leaves out is left as it is on the owner’s computer.

The plain settings each source takes are the ones its Accounts step asks for:

• Mail (imap): host, port (optional; 993 if left out), username. Secret: password.
• News feeds (feeds): feeds, a list of feed addresses.
• Morning briefing (briefing): daily_at, the time it’s written, HH:MM on a 24-hour clock.
• Calendar (ical): no plain settings. Secret: ics_url, the private calendar link.

Every section, and every source, may also have a reason: one sentence, shown beside that choice on the owner’s plan.

Placeholders: where it comes from, never what it is

In every place a password or key belongs, put a placeholder:

{ "ask_owner": "an app password from your mail provider (account → security → app passwords); not your normal password" }

The sentence is what the owner reads on the page where they type it in, so make it the instruction you’d give them in person: which account, which page, what it’s called there, and what it is not. A short link to the right settings page is fine; a link with anything after a ? or # isn’t, because that’s where links carry keys.

What gets a card refused

A card is used whole or not at all. Maisnie refuses it, with one sentence per problem, if it:

• has anything other than a placeholder where a password or key belongs, however short;
• has anything that looks like a password or key anywhere else: a long run of letters and digits, a password-like word, password=…, a link with a key in it. This applies to the notes, the reasons, the placeholders’ own sentences and every plain setting;
• tries to set the passphrase, turn remote access on or off, or start a support session;
• names a source, a setting, a section or a way of reaching an AI this version doesn’t have. An unknown key is refused rather than ignored, so a typo never quietly drops a choice;
• has a value Setup itself would refuse: a port above 65535, a feed address that isn’t http:// or https://, a time zone this computer doesn’t know, a hostname without a dot.

The refusal never repeats the value back. It names the place, such as “Mail’s app password”.

What a card can’t change on a computer already set up

A card never moves a vault that’s already set up, never changes the address of remote access that’s already on, and never asks again for a password or key that’s already saved. On a computer that’s already set up, those show on the plan as Left for you or Already set up. Importing the same card twice changes nothing more.

A complete example

Every value here is invented.

{
  "maisnie_setup_card": 1,
  "written_by": "Priya Raman",
  "written_on": "2026-10-01",
  "notes": "Dana, this is what we agreed on the call. Mail and calendar first; we can add more feeds later.",
  "vault": {
    "mode": "create",
    "path": "~/Maisnie",
    "git": true,
    "git_name": "Dana Whitfield",
    "git_email": "[email protected]",
    "reason": "A new vault in your home folder, with a change history so you can see what Maisnie added."
  },
  "sources": {
    "ical": {
      "enabled": true,
      "secrets": {
        "ics_url": { "ask_owner": "the secret address in iCal format, from your calendar's settings for that one calendar (it ends in .ics)" }
      },
      "reason": "Your work calendar, so meetings show up on Home."
    },
    "imap": {
      "enabled": true,
      "settings": { "host": "imap.example.com", "port": 993, "username": "[email protected]" },
      "secrets": {
        "password": { "ask_owner": "an app password from your mail provider (account → security → app passwords); not your normal password" }
      },
      "reason": "Your personal mail. Maisnie only reads it."
    },
    "feeds": {
      "enabled": true,
      "settings": { "feeds": ["https://news.example.org/feed.xml", "https://blog.example.net/atom.xml"] },
      "reason": "The two sites you said you read every morning."
    },
    "briefing": {
      "enabled": true,
      "settings": { "daily_at": "06:45" },
      "reason": "Ready before you leave at seven."
    }
  },
  "model": {
    "kind": "api",
    "provider": "Anthropic",
    "base_url": "https://api.anthropic.com",
    "models": { "fast": "claude-haiku-4-5", "balanced": "claude-sonnet-5" },
    "budget_usd": 20,
    "api_key": { "ask_owner": "an API key from your Anthropic console, under API keys; create a new one named Maisnie" },
    "reason": "Pay as you go, capped at $20 a month."
  },
  "owner": { "timezone": "America/Chicago", "reason": "Where you live." },
  "remote": {
    "hostname": "home.example.com",
    "api_token": { "ask_owner": "a token from your Cloudflare profile with exactly Zone:DNS:Edit and Account:Cloudflare Tunnel:Edit" },
    "reason": "For reading your notes on your phone, once you turn it on."
  },
  "people": { "min_notes": 3, "reason": "You meet a lot of people once; three notes means they matter." }
}

Imported on a fresh computer, this card creates the vault, turns on all four sources with their settings, saves the AI connection with its spending limit, sets the time zone, fills in the remote address (still off), and sets People’s threshold. Then it asks Dana for three things, one page each: the calendar’s secret address, the mail app password, and the API key. The Cloudflare token waits for the Remote access step, where she turns remote access on herself.

Sending it

A setup card holds no secrets, so send it however is easiest: email, a shared folder, a printout. The owner reads the whole plan before anything changes, and nothing changes until they press Use this card.