# The `.deeta` generation kit — for AI agents and scripts This kit lets an AI agent or a script write a `.deeta` merge file for **Import & Merge**. Give the agent four things: 1. the prompt below; 2. `deeta-import-v1.schema.json`, the file's JSON Schema; 3. `deeta-import-v1.report.schema.json`, the error report's JSON Schema; 4. the examples `examples/minimal.deeta` and `examples/enrich.deeta`. Then give it what you want changed: usually your own Deeta export (Settings → Privacy → Export My Data) and what to add or correct. The full rules are in `deeta-import-v1.md`; the prompt carries the ones a generator most often gets wrong. ## Before you use it - **Generated content is unverified.** An agent can be wrong about a real person. Everything a file adds is marked **imported** in Deeta, and the preview shows every change before anything is saved. Read the preview. - **`overwrite` lets the generator remove deets it did not know about.** That is why the prompt makes `additive` the default. Use `overwrite` only when you mean to start one person's deets over. - **Use it on your own records.** The kit is for bringing your own data in: migrating from another tool, or adding what you already know about the people in your life. It is not for building profiles of strangers. ## The prompt Copy everything inside the block. ```text You write a .deeta merge file for Deeta's Import & Merge. The file is JSON and must validate against the JSON Schema you were given (deeta-import-v1.schema.json). The two example files show the shape. ENVELOPE - "format" is exactly "deeta-data-export-v2". "formatVersion" is "1.4". - "generator" names your tool (up to 200 characters). "generatedAt" (an ISO-8601 time) is optional. "contacts" is required, and may be empty when the file changes only the user's own data. - Never include "relationships". A file with relationships is refused. IDENTITY - Every person row's "id" is either the exact id copied from the user's export, or the literal "new". Never invent an id. Write "new:" instead of "new" when another row in the file needs to refer to this person; is 1-64 characters of A-Z a-z 0-9 _ -. - A row with an existing id must carry "importType". A "new" row must not. - One person appears at most once in a file, with one mode. If one person needs both a correction ("update") and an addition ("additive"), write two files. The first holds everything else and that person's "update" row; the second holds only their "additive" row. The user imports the first file, then the second. Importing the addition first can leave two deets with the same key, and the correction is then refused. - Deet, tag and group row ids are labels inside the file, used only so other rows can name them. Use "new:" for every row you write. - Every reference names a row in this same file: a deet's "contactId" and "parentDeetId", every key and value in "contact_tag_ids" and "group_members", and "memberSelfDeetIds". Never point a reference at an id that is only in the export. - To add a deet under one the person already has, also write a row for that existing deet (same key, same parent) and use it as the parent. Deeta finds existing deets by their place and key, never by id, so under "additive" the existing deet is matched, not duplicated. Copy its value from the export; children are added under it either way. - To put someone in a tag or group the user already has, write a "tags" or "groups" row with that name. Deeta matches an existing tag by name, ignoring case, and an existing group by name under the same parent, so the user's tag is reused, not duplicated. MODES (importType) - "additive" only adds. It adds deets. It adds a phone, email, URL or address entry under a label the person does not have yet, and a birthday if the person has none. An existing entry is skipped and never changed. It fills organization and notes only when empty. - "update" only changes values of things that already exist: deets by key, phone, email, URL and address entries by label, and the birthday. It is the ONLY way to change an existing phone, email, URL, address or birthday. It creates nothing. - "overwrite" makes the person's deets exactly the deet rows you write for them. Every deet you leave out is removed. It does not touch phone, email, URL, address, birthday, organization or notes. - When in doubt, use "additive". Use "update" for corrections. Use "overwrite" only when the user asks to start a person's deets over. - No mode changes a name, deletes a person, removes a phone, email, URL or address entry, or detaches a tag or group. - A person whose row says "update" must not appear in "contact_tag_ids" or "group_members". To add tags or groups for that person, use a separate file with "additive". - A value another person shares with the user live cannot be changed. An "update" to it is added beside it, and an "overwrite" keeps it. Do not retry such a change. FIELDS - Phone, email and URL entries are { "label", "value" }. Addresses are { "label", "street", "city", "state", "postalCode", "country", "isoCountryCode" }. Birthday is { "month", "day", "year" } with "year" optional. Every entry needs a "label" (1-50 characters); one person has at most one entry per field and label. - To keep a value as it is, leave the field out. To clear a text value under "update", write "". Never write null in a text field: the file is refused. - Deets: "contactId" is the person's id from "contacts", "key" is 1-50 characters, "value" is up to 280, "parentDeetId" is another deet row's id for the same person or null. Deets nest at most 7 levels. - Stay within the limits in the schema. Do not invent fields the schema does not list. THE USER'S OWN DATA (only when the user asks) - "self_profile" carries "importType" (same three modes) and may set "bio" and "organization". The user's name is never changed. - "self_deets" rows are like deet rows without "contactId", plus optional "visibility" ("always", "ask" or "never"). They need a "self_profile" row. - "deet_sets" rows follow the person identity rule. "memberSelfDeetIds" lists "self_deets" row ids. A file cannot delete a set. - Changing the user's own deets reaches the people they share with live, as an edit in the app does. ERROR REPORTS - If the user gives you a Deeta error report, correct exactly the rows it lists, matched by "collection" + "rowIndex" + "rowId", and change nothing else. Then return the whole corrected file. AFTER A SUCCESSFUL IMPORT - Never send a file's "new" rows again. Every imported "new" row creates a person, so sending it twice makes a duplicate. To change someone you created, ask the user for a fresh export and use that person's id. OUTPUT - Return only the JSON file, nothing else. When the request needs two files, return both, labelled "1" and "2" in the order to import them. ``` ## When the import fails Deeta shows the first problem and offers **Save error report**. Give the report file (`deeta-import-report.json`) back to the agent with the same prompt and the file it wrote. The prompt tells it to correct exactly the rows the report lists. ## What the agent does not get The kit contains no Deeta data. The agent sees only what you give it, and the error report holds locations, never values (`deeta-import-v1.md`, section 9).