Backfill CHANGELOG [1.2.0] and add copilot-instructions for agent hygiene

.github/copilot-instructions.md

@@ -0,0 +1,44 @@
+# Copilot Agent Instructions
+
+These instructions apply to every Copilot agent session working on this repository.
+
+## Versioning and Changelog (mandatory for every PR)
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and maintains a `CHANGELOG.md` in [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+
+**You must evaluate and, if warranted, perform a version bump and changelog update as part of every PR that changes code or public API.**
+
+### When to bump the version
+
+| Change type | Version segment | Example |
+|---|---|---|
+| New feature or option added (backward-compatible) | **minor** | `1.2.0` → `1.3.0` |
+| Bug fix or internal improvement (backward-compatible) | **patch** | `1.2.0` → `1.2.1` |
+| Breaking change (removes or changes existing behaviour) | **major** | `1.2.0` → `2.0.0` |
+| Docs, tests, CI only (no code change visible to consumers) | none | no bump needed |
+
+### Steps required when a bump is needed
+
+1. Update the `"version"` field in `package.json`.
+2. Add a new `## [x.y.z] - YYYY-MM-DD` section at the top of `CHANGELOG.md` (below the header) with `### Added`, `### Changed`, `### Fixed`, or `### Removed` sub-sections as appropriate.
+3. Describe every user-visible change in plain language — one bullet per change.
+
+### Important reminders
+
+- Do **not** leave a new version number in `package.json` without a matching `CHANGELOG.md` entry.
+- Do **not** leave user-visible changes undocumented in `CHANGELOG.md`.
+- If you are unsure whether a bump is needed, default to making one and explain why in the PR description.
+
+## Code Quality (mandatory for every PR)
+
+- Run `npm run lint` before finalising. Fix all errors; warnings are acceptable.
+- Run `npm test` before finalising. All tests must pass.
+- If you add a new feature or fix a bug, add or update tests in `test/filejson.test.js`.
+
+## TypeScript Definitions
+
+- If you add, remove, or change any public method, option, or return type in `app.js`, update `index.d.ts` to match.
+
+## README
+
+- If you add a user-facing feature or option, add a usage example to `README.md`.

CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-04-30
+
+### Added
+
+- **`createIfMissing` option**: New configuration option that, when set to `true`, automatically creates the JSON file if it does not exist on `load()` instead of returning an error
+  - Defaults to `false` to preserve existing behaviour
+  - Useful for first-run scenarios where the data file may not yet exist
+- **Named exports**: `module.exports.Filejson` and `module.exports.default` now exposed alongside the default export, enabling ESM-style and destructured imports (`const { Filejson } = require('filejson')`)
+
+## [1.2.0] - 2025-10-01
+
+### Added
+
+- **TypeScript definitions**: New `index.d.ts` type-definition file providing full TypeScript support
+  - Typed constructor options (`FileJsonOptions`), `load()`, `save()`, `saveSync()`, `set()`, `get()`, `pause()`, `resume()` and all events
+  - Enables `import FileJson from 'filejson'` in TypeScript projects with correct type inference
+- **`llms.txt`**: Machine-readable documentation file for AI/LLM tooling that describes the full API, configuration options, and usage patterns in a compact format
+- **Improved JSDoc**: `save()` callback parameter and `handler` argument are now fully documented in the source; fixed a misleading inline comment in the auto-save handler
+- **GitHub Actions CI**: New `.github/workflows/ci.yml` runs the test suite against Node.js 18, 20, and 22 on every push and pull request
+  - Matrix strategy with `fail-fast: false` so all Node versions are always tested independently
+  - Codecov integration uploads `lcov.info` coverage data (Node 20 only) to track coverage trends over time
+  - Live CI and coverage badges added to README
+- **`CONTRIBUTING.md`**: Step-by-step guide covering forking, installing, branching, running tests, linting, and opening a pull request
+- **`SECURITY.md`**: Security policy with supported-versions table and instructions for responsibly disclosing vulnerabilities
+
+### Changed
+
+- **Default `saveDelay` changed from `0ms` to `100ms`**: Auto-saves are now debounced by 100 ms by default, which significantly reduces disk I/O for applications that mutate data in rapid succession
+  - To restore the previous immediate-save behaviour, set `saveDelay: 0` in the constructor options
+  - Manual calls to `save()` and `saveSync()` are never affected by `saveDelay`
+
+### Fixed
+
+- Increased timing margins in the Mocha test suite to prevent intermittent failures on slower or heavily loaded CI runners
+
 ## [1.1.0] - 2025-10-01
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "filejson",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Zero-config automatic JSON file persistence with atomic writes, debouncing, and crash safety. Just modify objects, changes save automatically.",
   "main": "app.js",
   "types": "index.d.ts",