abbu 0.1.2 → 0.4.0

data/docs/ABBU.md

@@ -9,9 +9,34 @@
 They are **not** a single file format — they are a macOS "package" (a directory bundle that Finder
 presents as a single file). This means you can inspect the contents with `ls` or `open -a Finder`.
 
+## Evidence Standard
+
+Apple does not publish a stable specification for every internal Contacts
+archive schema represented by `.abbu` bundles. This document therefore
+distinguishes observed repository-fixture behavior from documented Apple APIs
+and from hypotheses that still require verification.
+
+Never infer Apple Contacts storage semantics merely from Core Data table or
+column names. Require observed fixture evidence, Apple documentation where
+available, or reproducible verification, and record consequential discoveries
+in this document.
+
+For each new schema, relationship, source layout, image convention, or version
+variation:
+
+1. record the macOS or Contacts version when known;
+2. identify the synthetic fixture, SQLite query, plist key path, file evidence,
+   or Apple documentation supporting the conclusion;
+3. add a deterministic regression fixture and spec; and
+4. label unresolved interpretations as hypotheses rather than format guarantees.
+
+Real address-book exports contain sensitive personal data. Use them only for
+local verification, sanitize the observed behavior into deterministic synthetic
+fixtures, and never commit the original contacts, photos, or account identifiers.
+
 ## Structure
 
-Typical contents of a `.abbu` bundle:
+The supported synthetic fixtures and observed exports use layouts such as:
 
 ```text
 Contacts.abbu/
@@ -36,12 +61,16 @@ Contacts.abbu/
 
 ### 1. SQLite (modern macOS)
 
-Newer macOS versions store the address book in a single SQLite database:
+Supported modern fixtures contain one or more SQLite databases named:
 
 ```
 AddressBook-v22.abcddb
 ```
 
+The following tables and mappings are exercised by the repository's generated
+SQLite fixture and parser specs. Their names alone are not evidence that the
+same semantics apply to every macOS version.
+
 Key tables:
 
 | Table                    | Purpose                                |
@@ -77,12 +106,194 @@ Notable columns in `ZABCDRECORD`:
 | `ZPRONOUNS`              | Pronouns                 |
 | `ZRINGTONE`              | Ringtone                 |
 | `ZTEXTTONE`              | Text tone                |
+| `ZCREATIONDATE`          | Optional record creation timestamp |
+| `ZMODIFICATIONDATE`      | Optional record modification timestamp |
+
+### Timestamp and source provenance
+
+Observed Contacts databases may include `ZCREATIONDATE` and `ZMODIFICATIONDATE` on
+`ZABCDRECORD`. ABBU interprets numeric values in those columns as Apple absolute time:
+seconds since 2001-01-01 00:00:00 UTC. The columns are optional because exported schemas
+vary across macOS releases and account providers; when either column is absent or invalid,
+the corresponding `Contact` value is `nil`.
+
+These values describe timestamps stored on the record. They must not be interpreted as
+proof of a user-initiated creation or edit, because syncing and migration can also affect
+them.
+
+Every parsed contact includes source provenance with the absolute source path, its path
+relative to the `.abbu` root, and whether it came from the root bundle or a database under
+`Sources/<identifier>/`. Legacy plist contacts receive the same file-level provenance.
+
+### Opt-in live Contacts stores
+
+The CLI uses `--live` only for auto-discovery and `--live-path PATH` for an explicit
+store. These forms are mutually exclusive and accept no positional archive/path arguments.
+Option ordering does not change input selection. Synthetic WAL-mode and concurrent-writer
+validation remains a follow-up; read-only handles do not establish snapshot consistency
+across an actively changing Contacts store.
+
+`Abbu.open_live` and the CLI's live modes can read an AddressBook directory
+without first exporting an `.abbu` archive. This mode is deliberately separate from
+`Abbu.open`: archive validation and plist fallback do not apply to a live store.
+
+When no path is supplied on macOS, ABBU checks the observed per-user location at
+`~/Library/Application Support/AddressBook`. Callers may instead provide a directory,
+which keeps automation and tests independent of the host platform and user account.
+ABBU discovers databases directly under that directory and one level below
+`Sources/<identifier>/`, preserving the same root/source provenance used for archives.
+Only files matching the observed `AddressBook-v*.abcddb` shape are candidates; this
+filename pattern is discovery evidence, not a guarantee of stable Apple semantics.
+
+Every live-store database is opened using SQLite's read-only mode. ABBU has no live-store
+write API and never creates, updates, or deletes Contacts data. macOS privacy controls may
+deny access even when the path exists. In that case ABBU raises
+`Abbu::LiveStore::PermissionError` with instructions to grant the calling terminal or
+application Full Disk Access in **System Settings → Privacy & Security → Full Disk
+Access**. Missing directories and databases raise `Abbu::LiveStore::NotFoundError`, and
+automatic discovery without a caller-supplied path raises
+`Abbu::LiveStore::UnsupportedPlatformError` outside macOS.
+
+The repository verifies live-store behavior only with deterministic synthetic SQLite
+fixtures. It does not inspect or commit a developer's real Contacts store.
+### Provenance-aware identity evidence
+
+ABBU treats deduplication as a suggestion boundary rather than proof that two records are
+the same person. `Utils::Deduplicator#matches` compares normalized email, phone, name, and
+organization signals while returning both original contacts, both source records, raw
+evidence, normalized comparison values, confidence, and ambiguity status.
+
+Email comparison trims surrounding whitespace and applies Unicode-aware case folding.
+Names and organizations use Unicode NFKC normalization, case folding, and whitespace or
+punctuation normalization without transliterating distinct characters. Explicit `+` and
+`00` phone forms are compared as international numbers. The trimmed raw value must start
+with a literal ASCII `+` or contiguous `00`; punctuation removal never establishes an
+international prefix. For example, `(001) 512-555-0100` remains national-format evidence.
+National-format numbers remain
+source-local evidence because ABBU has no country or numbering-plan evidence with which
+to infer a global identity.
+
+SQLite primary keys, source identifiers, private Apple link identifiers, and image stems
+are not treated as global contact identifiers. The repository fixtures do not establish
+such semantics. Competing candidates and weak name/organization or source-local phone
+matches remain ambiguous, and no contact is merged unless the caller supplies an explicit
+merge policy.
+
+### Image resolution and extraction
+
+The synthetic SQLite fixture demonstrates a `ZIMAGEURI` value whose stem matches a file
+under an `Images/` directory. Resolution covers the root bundle and nested
+`Sources/<identifier>/Images/` directories. When duplicate stems exist, ABBU uses the
+contact's database provenance to select only an image beside that database; it does not
+guess when the available evidence remains ambiguous.
+
+`Archive#extract_images(output_dir)` and the CLI `--extract-images DIR` copy resolved
+images without changing `Contact#image_uri`, `Contact#image_path`, or `Contact#source`.
+Exported filenames combine a sanitized contact name, the original image identifier, and
+a stable provenance digest. Path separators, control characters, and reserved filename
+characters cannot create subdirectories or traverse outside the selected output directory.
+
+The selected output directory (including symlinked parents) is resolved to its canonical
+directory before copying; callers must control that directory and prevent concurrent
+directory replacement. Each image is created exclusively with owner-only permissions.
+Existing destinations are never overwritten, including regular files, hard links, and
+symlinks (even dangling ones). These collisions produce a `destination_exists` extraction
+diagnostic and no successful file record; other images continue. Repeating extraction
+into the same directory therefore reports collisions instead of replacing earlier output.
+Directory creation/resolution failures raise filesystem errors before extraction begins.
+
+Extraction diagnostics are a separate API from `archive.diagnostics`: they may contain
+contact names, raw image identifiers, source paths, and filesystem error details. Treat
+them and the CLI's image warnings as sensitive contact data, not safe-to-publish logs.
+
+ABBU recognizes JPEG, PNG, GIF, and common HEIF/HEIC-compatible brands from file
+signatures and chooses the exported extension from those bytes rather than the source
+extension. Unknown content is reported as a diagnostic instead of being relabeled. HEIC
+data is copied unchanged; ABBU does not transcode it.
+
+No repository fixture currently demonstrates a reliable Apple thumbnail-versus-full-size
+naming or selection rule. ABBU therefore exports the image resolved by the observed
+`ZIMAGEURI` relationship and does not infer size semantics from filenames or directories.
+
+### Recovery and diagnostics
+
+By default, ABBU recovers from malformed individual plist records, missing
+optional SQLite relationship tables, and unresolved image references. Each
+recovery appends an `Abbu::Diagnostic` to `archive.diagnostics` with a category,
+parser, source path, non-PII context, and a stable message. Required contact
+schema failures still raise because no evidence-backed contact record can be
+recovered safely.
+
+An absent optional SQLite table produces one diagnostic per database and table,
+regardless of contact count. ABBU does not place record identifiers or raw image
+references in these schema- and image-level diagnostic contexts.
+
+Pass `strict: true` to `Abbu.open` or `--strict` to the CLI to raise
+`Abbu::ParseError` on the first recoverable condition. The CLI prints a
+diagnostic summary to standard error so exported data on standard output remains
+pipeable.
+
+### Schema diagnostics
+
+`Archive#schema_report` and `abbu Contacts.abbu --schema` inspect every discovered
+SQLite database and return deterministic schema metadata. Reports identify recognized
+and unrecognized tables and columns, recognized items that are absent, declared SQLite
+types, primary-key and nullability metadata, source provenance, and exact owner/contact-
+style column names that may represent contact links.
+
+These reports are research evidence, not parser mappings. In particular, a
+`contact_link_candidate` flag records only an exact column-name shape such as `ZOWNER`,
+`ZCONTACT`, or `Z_CONTACT`; it does not claim a foreign-key target or assign Apple
+Contacts semantics. Unknown tables and columns must be reproduced in a sanitized fixture
+or supported by documentation before ABBU uses them to populate contacts.
+
+Missing recognized tables and columns remain visible as diagnostic observations. The
+parser tolerates absent established email, phone, and postal-address tables by returning
+empty collections, while the schema report preserves the absence for compatibility
+research. If one of those tables exists but lacks an expected column, parsing raises the
+SQLite schema error instead of silently treating the contact as having no corresponding
+data. The core `ZABCDRECORD` table remains required for contact parsing.
+
+### Labeled values
+
+The synthetic SQLite and plist fixtures include both custom labels and Apple's
+observed standard-label wrapper, such as `_$!<Work>!$_`. ABBU exposes the
+human-facing value as `label` (`Work`) and preserves the exact stored value as
+`raw_label`. Custom, blank, malformed, Unicode, and already-normalized labels
+are not otherwise rewritten. Direct plist keys such as `Birthday` have no
+stored label, so their normalized label is derived from the key and
+`raw_label` is `nil`.
+
+Normalization applies to email addresses, phone numbers, postal addresses,
+URLs, related names, date components, and instant-message handles. JSON keeps
+both values. Human-facing CSV uses normalized labels, while vCard anniversary
+labels prefer `raw_label` so Apple label wrappers and custom source values
+survive parse → model → interchange export.
 
 ### 2. Plist / `.abcdp` (legacy macOS)
 
-Older macOS versions stored each contact as a separate binary plist file under `Records/`.
-Each file is a serialised `ABPerson` dictionary. The `abbu` gem currently stubs this parser
-and returns an empty array with a warning.
+Older macOS versions stored contacts as separate plist files under `Records/`.
+The repository fixtures demonstrate dictionaries that the plist parser
+normalizes into the same contact model used by the SQLite parser. Additional
+plist keys or layouts require fixture evidence before they are treated as
+supported semantics.
+
+## Repository Evidence
+
+- `spec/fixtures/TestContacts.abbu/` exercises the supported synthetic SQLite,
+  nested source, and image-resolution behavior.
+- `spec/fixtures/PlistContacts.abbu/` exercises the supported synthetic legacy
+  plist behavior.
+- `spec/fixtures/identity_cases.yml` contains deterministic synthetic cross-source and
+  Unicode near-collision identity evidence.
+- `spec/support/fixture_generator.rb` is the reproducible source for generated
+  SQLite fixture structure and data.
+- `spec/abbu/schema_inspector_spec.rb` builds deterministic temporary SQLite
+  schemas for missing tables, unknown contact-link candidates, and column drift.
+
+These fixtures prove only the variations they contain. Table names, column
+names, entity numbers, UUIDs, and directory names alone are not sufficient
+evidence for new behavior.
 
 ## Export Steps
 
@@ -96,9 +307,17 @@ The "Contacts Archive" option produces a `.abbu` bundle.
 
 ## References
 
-- [Apple Contacts Framework (private)](https://developer.apple.com/documentation/contacts)
+- [Apple Contacts framework](https://developer.apple.com/documentation/contacts)
+- [iQueryContacts forensic schema notes](https://github.com/MetadataForensics/iQueryContacts)
+- [Observed Contacts timestamp epoch](https://apple.stackexchange.com/questions/115551/how-to-sort-contacts-by-creation-date-or-modification-date-in-ios-contacts-or-os/229313)
+- [LifeOS Apple Contacts timestamp conversion](https://github.com/nbramia/LifeOS/blob/main/scripts/apple_data_export.py)
 - [SQLite3 gem](https://github.com/sparklemotion/sqlite3-ruby)
-- macOS `AddressBook.framework` private headers (reverse-engineered)
+- [macos-ts live Contacts reader](https://github.com/evantahler/macos-ts)
+- Repository fixtures and regression specs listed above
+
+Apple's public Contacts framework documents application-facing concepts, not a
+stable `.abbu` storage contract. Private framework names and Core Data names are
+not normative references.
 
 ---
 Stan Carver II

data/docs/CHANGELOG.md

@@ -0,0 +1,193 @@
+<!-- CHANGELOG.md -->
+
+# Changelog
+
+All notable changes to `abbu` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-30
+
+### Fixed
+
+- Live CLI input uses distinct `--live` auto-discovery and `--live-path PATH` forms;
+  mixed modes and unexpected live positional arguments are rejected.
+
+- Deduplication recognizes international phone prefixes from trimmed raw input, not
+  punctuation-stripped digits, keeping national-looking `(001)` values source-local.
+
+- Image extraction exclusively creates destination files and reports `destination_exists`
+  rather than overwriting existing files, symlinks, or hard links. Output directory aliases
+  are resolved before extraction; extraction diagnostic privacy is documented.
+
+### Added
+
+- Explicit, read-only live Contacts access through `Abbu.open_live` and
+  `abbu --live` / `abbu --live-path PATH`, with root and `Sources/*` database discovery
+- Actionable live-store errors for missing databases, unsupported automatic
+  discovery, and macOS Full Disk Access restrictions
+- Platform-independent synthetic coverage for live-store discovery, source
+  provenance, SQLite read-only enforcement, and CLI behavior
+- Provenance-aware `Utils::Deduplicator#matches` suggestions with normalized email,
+  international/source-local phone, Unicode name, and organization evidence
+- Match confidence, ambiguity status, original source records, and raw evidence, plus an
+  explicit callable merge-policy boundary that never silently collapses contacts
+
+- `Archive#extract_images` and `Abbu::ImageExtractor` for copying contact photos to a
+  caller-selected directory with structured missing, unreadable, and unsupported-image
+  diagnostics
+- `--extract-images DIR` CLI support with content-aware JPEG, PNG, GIF, and HEIC extension
+  selection and safe, Unicode-preserving, collision-resistant filenames
+- Source-local resolution for duplicate image stems in nested account directories without
+  guessing when provenance cannot disambiguate candidates
+
+- Structured tolerant-parsing diagnostics with strict API/CLI mode for corrupt
+  plist records, missing optional SQLite data, and unresolved image references
+- Missing optional SQLite tables emit one non-PII diagnostic per database and
+  table instead of repeating schema-level warnings for every contact
+- Evidence-safe SQLite schema diagnostics through `Archive#schema_report` and
+  `abbu <archive> --schema`, including unknown tables/columns, absent recognized
+  schema elements, and owner/contact-style relationship candidates
+- Deterministic schema-variation coverage for missing optional tables, unknown
+  contact-linked tables, and column drift
+- Normalized Apple standard labels with the original source value preserved as
+  `raw_label` on labeled contact values
+- Chainable `Abbu::Query` and `Archive#where` APIs for contact filtering
+- Exact normalized email and phone lookup that returns all matches across sources
+- Case-insensitive partial name and email search through Ruby and tab-separated CLI output
+- Stable `--json` search output using the regular contact JSON schema
+- Contact creation and modification timestamps from optional SQLite `ZCREATIONDATE` and `ZMODIFICATIONDATE` columns
+- Provenance metadata identifying each contact's source database or plist and its location within the ABBU bundle
+- Creation, modification, and source metadata in JSON exports
+- Repository constitution and focused local skills for ABBU format evidence,
+  Ruby gem development, testing, and Sheriff-gated releases
+- Canonical `bin/spec` and `bin/package` workflows, with CI reusing project-local
+  `bin/spec` and `bin/lint` instead of duplicating their commands
+
+### Changed
+
+- CI now runs the Ruby matrix once for pull requests and on pushes to canonical `main`, avoiding duplicate feature-branch push and pull-request runs
+- SQLite parsing now tolerates absent established email, phone, and postal-address
+  tables and returns empty collections while retaining the variation in schema diagnostics;
+  unexpected column drift and other SQL errors on present tables continue to surface
+- vCard anniversary export now prefers the original `raw_label` so Apple and
+  custom source representations survive parse-and-export round trips
+- Minimum supported Ruby and RuboCop target are now 3.3; CI covers Ruby 3.3,
+  3.4, and 4.0, with Ruby 3.3 as the designated lint/tooling job
+- Agent guidance is consolidated in `AGENTS.md`; the redundant `CLAUDE.md` has
+  been removed
+- Gem packaging now includes only the public `bin/abbu` executable instead of
+  repository-only developer commands
+
+## [0.3.0] - 2026-09-29
+
+### Added
+
+- `Contact#image_uri` and `Contact#image_path` accessors
+- `Parsers::SqliteParser` extracts `ZIMAGEURI` from `ZABCDRECORD`
+- `Utils::ImageResolver` builds an index of every image file under the bundle's `**/Images/` directories (jpg, jpeg, png, heic — case-insensitive) and resolves a contact's `image_uri` to a `Pathname` within the bundle
+- `Archive#contacts` automatically resolves `image_path` for any contact that has a non-nil `image_uri`
+- CSV export: new `ImagePath` column (last column)
+- JSON export: `image_uri` and `image_path` fields (omitted via `.compact` when blank)
+- vCard export: `PHOTO;VALUE=URI:file://<absolute path>` line, emitted when `image_path` is present
+- `spec/fixtures/TestContacts.abbu/Images/stan-photo.jpg` stub image, regenerated by `spec/support/fixture_generator.rb`
+
+### Notes
+
+- PlistParser does not extract images — legacy `.abcdp` contacts typically embed image data inline, which is a separate extraction path
+- vCard `PHOTO` references the absolute bundle path; base64 embedding and the `--extract-images` CLI flag are tracked for follow-up
+
+### Fixed
+
+- vCard `PHOTO` file URIs now percent-encode spaces, reserved characters, and non-ASCII bytes in image paths
+- `abbu:export` Rake task wrote hash literals (e.g. `{:address=>"…", :label=>"…"}`) into the `Email` and `Phone` CSV columns. Now correctly extracts the first address and number from each contact's multi-value field.
+
+## [0.2.0] - 2026-05-03
+
+### Added
+
+- `Parsers::PlistParser` — full implementation of legacy `.abcdp` plist contact parsing, replacing the previous stub
+- `PlistParser::FIELD_MAP` constant for flat-field mapping
+- Multi-value field extraction for emails, phones, addresses, URLs, notes, related names, and social profiles
+- `Archive` recursively scans `**/*.abcdp` across the entire bundle tree
+- `plist` gem (~> 3.7) runtime dependency
+- Plist fixture files (`spec/fixtures/PlistContacts.abbu/`) for integration testing
+- `middle_name` attribute on `Contact`; `ZMIDDLENAME` / `Middle` plist key
+- `dates` attribute on `Contact` (array of `{ year:, month:, day:, label: }` hashes)
+- `birthday`, `anniversary`, and `lunar_birthday` accessor methods derived from the dates list
+- `instant_messages` attribute (AIM, Jabber, Skype, etc.); `ZABCDMESSAGINGADDRESS` / `InstantMessage` key
+- `verification_code` attribute on `Contact`; `ZVERIFICATIONCODE` column / `VerificationCode` plist key
+- `phonetic_middle_name` attribute; `ZPHONETICMIDDLENAME` column / `PhoneticMiddle` plist key
+- `ZABCDDATECOMPONENTS` parsing (year/month/day split columns)
+- `BDAY`, `X-LUNAR-BDAY`, `X-ABDATE`, `X-ABLABEL` vCard fields
+- `IMPP` vCard field for instant messaging
+- Birthday, anniversary, lunar birthday, instant messages, and verification code in CSV and JSON exports
+- Plist fixture for testing all the above (`spec/fixtures/PlistContacts.abbu/`)
+
+### Changed
+
+- `Contact#full_name` now includes middle name (`Honorable Stan The Man "Stretch" Carver II`)
+- vCard `N` field includes middle name component
+- `SqliteParser::RECORD_FIELD_MAP` extended with the new column → attr mappings
+- `JsonExporter#contact_hash` includes all new fields; blank fields are dropped via `.compact`
+- `CsvExporter` extended-field section now exports lunar birthday and verification code
+
+## [0.1.2] - 2026-04-26
+
+### Added
+
+- Full Apple Contacts schema support: job title, department, maiden name, phonetic names, pronouns, ringtone, texttone
+- Relational table parsing: URLs, notes, related names (family/business), social profiles (Twitter, etc.)
+- Nickname, prefix, and suffix fields with smart `full_name` formatting
+- Hash-based email/phone data preserving custom labels (e.g. "Direct Line", "Work")
+- Address, group, URL, notes, related names, and social profiles in CSV export
+- Comprehensive JSON export with all contact fields
+- vCard 3.0 export with ADR, URL, NICKNAME, TITLE, NOTE, X-SOCIALPROFILE
+- `rubocop-rspec` plugin integration
+- 100% line coverage across all 44 specs
+
+### Changed
+
+- Refactored `SqliteParser` to use `RECORD_FIELD_MAP` constant for maintainability
+- Refactored `CsvExporter` into `core_fields`/`extended_fields` for cleaner ABC metrics
+- All specs comply with rubocop-rspec conventions
+
+## [0.1.1] - 2026-04-23
+
+### Fixed
+
+- `require 'pathname'` missing in `archive.rb` causing `NameError` in isolation
+- Added regression guard spec for file require isolation
+
+
+## [0.1.0] - 2026-04-12
+
+### Added
+
+- `Abbu.open(path)` entry point returning an `Archive`
+- `Archive#contacts` — reads contacts from SQLite or falls back to plist stub
+- `Archive#sqlite?` — detects modern `.abcddb` bundles
+- `Contact` object with `first_name`, `last_name`, `emails`, `phones`, `company`, `full_name`
+- `Parsers::SqliteParser` — queries `ZABCDRECORD`, `ZABCDEMAILADDRESS`, `ZABCDPHONENUMBER`
+- `Parsers::PlistParser` — stub with warning (legacy `.abcdp` support in v0.2)
+- `Exporters::CsvExporter` — `to_file` and `to_stdout`
+- `Exporters::JsonExporter` — `to_file` and `to_stdout`
+- `Exporters::VcardExporter` — `to_file` and `to_stdout` (vCard 3.0)
+- `Utils::Deduplicator` — groups contacts by first email, returns duplicates hash
+- `bin/abbu` CLI with `--format`, `--output`, `--stats`, `--dedupe`, `--version`
+- Rake tasks: `abbu:export`, `abbu:dedupe`, `abbu:stats`
+- Example scripts: CSV, JSON, vCard, API, CRM sync, stats, dedupe
+- `docs/ABBU.md` — file format reference
+- RSpec test suite with 100% coverage target
+- Guard + RuboCop DX loop
+- GitHub Actions CI (Ruby 3.2 + 3.3)
+
+---
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+<!-- CONTRIBUTING.md -->
+
+# Contributing to abbu
+
+Thank you for your interest in contributing!
+
+## Setup
+
+```bash
+git clone https://github.com/scarver2/abbu
+cd abbu
+mise exec -- bundle install
+```
+
+## DX Loop
+
+```bash
+mise exec -- bundle exec guard
+```
+
+This runs RSpec and RuboCop automatically on file changes.
+
+## Running Tests
+
+```bash
+bin/spec
+```
+
+## Linting
+
+```bash
+bin/lint
+mise exec -- bundle exec rubocop -a   # autocorrect
+```
+
+## Packaging
+
+```bash
+bin/package
+```
+
+This builds the current gem, verifies its metadata, installs it into an isolated
+gem home, and loads that installed copy. A successful package check is evidence
+only; it does not authorize a release tag or RubyGems publication.
+
+## Pull Request Guidelines
+
+- Base branch: `main`
+- Commit style: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `chore:`)
+- All specs must pass and coverage must remain at 100%
+- RuboCop must pass with no offenses
+- Add an entry to `docs/CHANGELOG.md` under `[Unreleased]`
+
+## Reporting Issues
+
+Open an issue on GitHub with a minimal reproduction case.
+
+---
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com