# DDNYC Contact Card Kit — complete agent guide

Canonical human page: https://anthemhayek.com/open-source/contact-card
Machine-readable manifest: https://anthemhayek.com/open-source/contact-card-kit.json
Configuration schema: https://anthemhayek.com/open-source/contact-card-kit/config.schema.json
Source archive: https://anthemhayek.com/downloads/ddnyc-contact-card-kit.zip
Raw source base: https://anthemhayek.com/open-source/contact-card-kit/
License: MIT
Version: 1.0.0
Price: $0 USD
Author: Anthem Hayek Blanchard

## Purpose

The DDNYC Contact Card Kit generates two deployable artifacts from one JSON configuration:

1. `dist/contact.vcf` — a standards-folded vCard 3.0 contact.
2. `dist/share-card.png` — a 1290 by 2796 portrait QR card matching the iPhone 14 aspect ratio.

The QR contains the exact HTTPS value of `publicVcfUrl`. The recipient scans the image, taps the camera banner, reviews the vCard and confirms the save. A QR code cannot silently write to an address book.

## Fast path

```sh
npm install
cp config.example.json config.json
# Edit config.json. Optionally add a square profile image.
npm run generate
npm test
```

Upload `dist/contact.vcf` to the exact `publicVcfUrl`. Save `dist/share-card.png` to a phone. Test the live QR on at least one iPhone and one Android device before printing or distributing it.

## Input contract

Authoritative JSON Schema: https://anthemhayek.com/open-source/contact-card-kit/config.schema.json
Example configuration: https://anthemhayek.com/open-source/contact-card-kit/config.example.json

Required properties:
- `firstName`: non-empty string
- `lastName`: non-empty string
- `fullName`: non-empty string
- `phone`: phone-number string
- `email`: email address
- `website`: HTTPS URL
- `publicVcfUrl`: HTTPS URL ending in `.vcf`

Optional properties:
- `organization`, `title`, `note`, `eventLabel`, `tagline`
- `photoPath`: local image path relative to the configuration file
- `photoUrl`: public HTTPS fallback for the contact photo
- `socials`: object keyed by service; values are a URL string or `{ "url": "...", "username": "..." }`
- `cardTitleLines`: one or two short strings
- `colors`: six-digit hex values for `paper`, `accent`, `signal` and `ink`

For the most reliable social serialization, supply both `url` and `username`. Replace all example identity data and artwork before distribution.

## Output and validation contract

The vCard must use version 3.0 and CRLF delimiters. Every physical line must be no longer than 75 UTF-8 bytes, and continuation lines begin with one space. Core portable fields are name, organization, title, mobile phone, email and website. Contact-photo and social-profile import is best effort because behavior varies by contact app and OS release.

The QR destination must be HTTPS and must equal `publicVcfUrl`. Preserve a quiet zone and high error correction. The automated test generates both files, checks the portable vCard fields and line lengths, decodes the finished PNG, and asserts the exact destination URL.

## Privacy and security

Generation is local. The kit has no account, analytics, form submission or database. Everything placed in a public vCard is public information. Share only data intended for strangers to retain, host the vCard on a domain you control, use HTTPS, and do not later redirect a distributed QR to unrelated content.

## Commercial use

Commercial use is allowed under the MIT License, including paid client work, internal tools, products, hosted services, consulting, courses, modification, white-label distribution and resale. Preserve the included copyright and permission notice in copies or substantial portions of the software.

The code license does not grant third-party name, image, logo, event, trademark or endorsement rights. Do not imply that Anthem Hayek Blanchard, Doginal Dogs or DDNYC sponsors or approves a derivative product. You remain responsible for privacy disclosures, consent, accessibility, security, hosting, testing and applicable law.

Commercial guidance: https://anthemhayek.com/open-source/contact-card-kit/COMMERCIAL-USE.md

## Raw files

- README: https://anthemhayek.com/open-source/contact-card-kit/README.md
- Agent instructions: https://anthemhayek.com/open-source/contact-card-kit/AGENTS.md
- Commercial guide: https://anthemhayek.com/open-source/contact-card-kit/COMMERCIAL-USE.md
- MIT License: https://anthemhayek.com/open-source/contact-card-kit/LICENSE
- Package metadata: https://anthemhayek.com/open-source/contact-card-kit/package.json
- JSON Schema: https://anthemhayek.com/open-source/contact-card-kit/config.schema.json
- Example configuration: https://anthemhayek.com/open-source/contact-card-kit/config.example.json
- Generator: https://anthemhayek.com/open-source/contact-card-kit/generate.mjs
- Automated test: https://anthemhayek.com/open-source/contact-card-kit/test.mjs

## Safe agent modification policy

Agents may change copy, colors, layout, configuration fields and output names. If changing the QR payload, vCard serialization or image dimensions, update the automated test and preserve every invariant in the JSON manifest. Never claim guaranteed contact-photo or social-profile import on every OS. Never claim silent address-book insertion.